docs(ai-perso): add ai-personalization spec file for documentation generation (#4063)

Author: writeens

scripts/common.ts

@@ -69,7 +69,13 @@ export const GENERATORS = Object.entries(clientsConfig).reduce(
 
 export const LANGUAGES = [...new Set(Object.values(GENERATORS).map((gen) => gen.language))];
 
-export const CLIENTS = [...new Set(Object.values(GENERATORS).map((gen) => gen.client)), 'crawler'];
+// `crawler` and `ai-personalization` are manually added so we can still bundled and validate the specs
+// the entry can be removed once at least one client is generated
+export const CLIENTS = [
+  ...new Set(Object.values(GENERATORS).map((gen) => gen.client)),
+  'crawler',
+  'ai-personalization',
+];
 
 export async function run(command: string, { errorMessage, cwd, language }: RunOptions = {}): Promise<string> {
   const realCwd = path.resolve(ROOT_DIR, cwd ?? '.');

specs/ai-personalization/common/enums.yml

@@ -0,0 +1,22 @@
+errorCodes:
+  title: errorCodes
+  type: string
+  enum:
+    - blocked
+    - deleted
+    - no_perso_access
+    - all_attr_value_filtered
+    - missing_index
+    - no_events_last_30_days
+    - pending_pipelines
+    - invalid_config
+
+status:
+  title: status
+  type: string
+  enum: [pending, active, paused]
+
+sourceType:
+  title: type
+  type: string
+  enum: [insights]

specs/ai-personalization/common/responses/BadRequest.yml

@@ -0,0 +1,5 @@
+description: Bad request.
+content:
+  application/json:
+    schema:
+      $ref: './BaseResponse.yml'

specs/ai-personalization/common/responses/BaseResponse.yml

@@ -0,0 +1,8 @@
+type: object
+properties:
+  status:
+    type: integer
+    description: HTTP status code.
+  message:
+    type: string
+    description: Details about the response, such as error messages.

specs/ai-personalization/common/responses/ConfigurationNotFound.yml

@@ -0,0 +1,5 @@
+description: Configuration not found.
+content:
+  application/json:
+    schema:
+      $ref: './BaseResponse.yml'

specs/ai-personalization/common/responses/InternalServerError.yml

@@ -0,0 +1,5 @@
+description: Internal server error.
+content:
+  application/json:
+    schema:
+      $ref: './BaseResponse.yml'

specs/ai-personalization/common/responses/InvalidUserID.yml

@@ -0,0 +1,5 @@
+description: Invalid user ID format.
+content:
+  application/json:
+    schema:
+      $ref: './BaseResponse.yml'

specs/ai-personalization/common/responses/Unauthorized.yml

@@ -0,0 +1,5 @@
+description: Not authorized to access this resource.
+content:
+  application/json:
+    schema:
+      $ref: './BaseResponse.yml'

specs/ai-personalization/common/responses/UserNotFound.yml

@@ -0,0 +1,5 @@
+description: User not found.
+content:
+  application/json:
+    schema:
+      $ref: './BaseResponse.yml'

specs/ai-personalization/common/schemas/Configuration.yml

@@ -0,0 +1,75 @@
+event:
+  type: object
+  properties:
+    type:
+      $ref: '#/eventType'
+    subtype:
+      $ref: '#/subtype'
+    name:
+      type: string
+  required: [type, name]
+
+events:
+  type: object
+  properties:
+    viewDetails:
+      type: array
+      items:
+        $ref: '#/event'
+    viewListing:
+      type: array
+      items:
+        $ref: '#/event'
+    addToCart:
+      type: array
+      items:
+        $ref: '#/event'
+    purchase:
+      type: array
+      items:
+        $ref: '#/event'
+  required: [viewDetails, viewListing, addToCart, purchase]
+
+issue:
+  type: object
+  description: An issue is either an 'error' or a 'warning' that is generated by the validator.
+  properties:
+    code:
+      type: string
+    index:
+      type: string
+    message:
+      type: string
+  required: [code, index, message]
+
+personalizationReRanking:
+  type: string
+  description: The impact that personalization has on the re-ranking of search results.
+  enum: [none, low, medium, high, maximum]
+
+profileType:
+  type: string
+  enum: [basic, predictive]
+  description: |
+    The type of user profiles to generate.
+
+    Basic profiles are based on past behaviors, ensuring search results align with previous interests.
+    Predictive profiles are AI-powered profiles that predict and adapt to users' interests, ensuring search results align with evolving preferences.
+
+eventType:
+  type: string
+  enum: [view, click, conversion]
+
+subtype:
+  type: string
+  enum: [addToCart, purchase]
+
+status:
+  type: object
+  properties:
+    type:
+      $ref: '../enums.yml#/status'
+    errors:
+      type: array
+      items:
+        $ref: '../enums.yml#/errorCodes'