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

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'

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

@@ -0,0 +1,41 @@
+configurationObject:
+  type: object
+  properties:
+    indices:
+      type: array
+      items:
+        title: configurationObject
+        type: object
+        properties:
+          index:
+            type: string
+          affinities:
+            type: array
+            items:
+              type: string
+          source:
+            title: source
+            type: object
+            properties:
+              type:
+                $ref: '../enums.yml#/sourceType'
+              events:
+                $ref: './Configuration.yml#/events'
+          errors:
+            type: array
+            items:
+              $ref: './Configuration.yml#/issue'
+          warnings:
+            type: array
+            items:
+              $ref: './Configuration.yml#/issue'
+          lastUpdatedAt:
+            type: string
+        required: [index, affinities, source, errors, warnings, lastUpdatedAt]
+    personalizationReRanking:
+      $ref: './Configuration.yml#/personalizationReRanking'
+    profileType:
+      $ref: './Configuration.yml#/profileType'
+    status:
+      $ref: './Configuration.yml#/status'
+  required: [indices, personalzationReRanking, profileType, status]

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

@@ -0,0 +1,30 @@
+user:
+  type: object
+  properties:
+    userID:
+      type: string
+    affinities:
+      type: array
+      items:
+        title: affinity
+        type: object
+        properties:
+          name:
+            type: string
+          indices:
+            type: array
+            items:
+              type: string
+              minimum: 1
+          value:
+            type: string
+          score:
+            type: number
+            minimum: 1
+            maximum: 20
+          lastUpdatedAt:
+            type: string
+        required: [name, indices, value, score, lastUpdatedAt]
+    lastUpdatedAt:
+      type: string
+  required: [userID, affinities, lastUpdatedAt]

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

@@ -0,0 +1,104 @@
+# query
+startDate:
+  name: startDate
+  description: |
+    Filter users by start date (in RFC3339 format).
+    Only users that were updated after the passed date will be returned.
+  in: query
+  schema:
+    type: string
+    example: 2024-06-27T08:27:26Z
+
+endDate:
+  name: endDate
+  description: |
+    Filter users by end date (in RFC3339 format).
+    Only users that were updated before the passed date will be returned.
+  in: query
+  schema:
+    type: string
+    example: 2024-06-28T08:27:26Z
+
+indices:
+  name: indices
+  description: |
+    Filter users by matching indices.
+    If multiple indices are passed, returned users will match all indices.
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+  examples:
+    singleIndex:
+      value: [products_EN]
+      summary: Filter by single index
+    multipleIndices:
+      value: [products_EN, products_FR]
+      summary: Filter by multiple indices
+  style: form
+  explode: false
+
+affinity:
+  name: affinity
+  description: |
+    Filter users by affinity name and value.
+    If multiple values are passed, returned users will match all values.
+  in: query
+  schema:
+    type: array
+    items:
+      type: string
+  examples:
+    affinityName:
+      value: brand
+      summary: Filter by single affinity name
+    affinityValuePair:
+      value: brand:Nike
+      summary: Filter by single affinity name and value
+    multipleAffinityNames:
+      value: brand,color
+      summary: Filter by multiple affinity names
+    multipleAffinityValuePairs:
+      value: brand:Nike,color:white
+      summary: Filter by multiple affinity name and value pairs
+
+limit:
+  name: limit
+  description: |
+    Limit the number of users in the response.
+    The value of this parameter ranges from 1 to 1000.
+  in: query
+  schema:
+    type: integer
+    default: 10
+    minimum: 1
+    maximum: 1000
+
+nextPageToken:
+  name: nextPageToken
+  description: |
+    Reference for the next page, when navigating forward using pagination.
+    Can't be used in the same request as `previousPageToken`.
+  in: query
+  schema:
+    type: string
+
+previousPageToken:
+  name: previousPageToken
+  description: |
+    Reference for the previous page, when navigating backward using pagination.
+    Can't be used in the same request as `nextPageToken`.
+  in: query
+  schema:
+    type: string
+
+# path
+
+userID:
+  name: userID
+  description: ID of the user.
+  in: path
+  required: true
+  schema:
+    type: string