feat(clients): add real-time personalization to advanced-personalization [PRED-3870] (#4976)

raed667 · bengreenbank · shortcuts · web-flow · commit 0ea1d0ca9851 · 2025-06-16T09:52:27.000+02:00
Co-authored-by: Ben Greenbank &lt;61185468+bengreenbank@users.noreply.github.com&gt;
Co-authored-by: Clément Vannicatte &lt;vannicattec@gmail.com&gt;
diff --git a/clients/algoliasearch-client-javascript/package.json b/clients/algoliasearch-client-javascript/package.json
@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "scripts": {
-    "build": "lerna run build --skip-nx-cache --scope '@algolia/requester-testing' --scope '@algolia/logger-console' --scope 'algoliasearch' --scope '@algolia/client-composition' --scope '@algolia/composition' --include-dependencies",
+    "build": "lerna run build --skip-nx-cache --scope '@algolia/requester-testing' --scope '@algolia/logger-console' --scope 'algoliasearch' --scope '@algolia/client-composition' --scope '@algolia/composition' --scope '@algolia/advanced-personalization' --include-dependencies ",
     "clean": "lerna run clean",
     "release:publish": "tsc --project scripts/tsconfig.json && node scripts/dist/publish.js",
     "test": "lerna run test $*",
diff --git a/clients/algoliasearch-client-javascript/yarn.lock b/clients/algoliasearch-client-javascript/yarn.lock
@@ -5,6 +5,23 @@ __metadata:
   version: 8
   cacheKey: 10
 
+"@algolia/advanced-personalization@workspace:packages/advanced-personalization":
+  version: 0.0.0-use.local
+  resolution: "@algolia/advanced-personalization@workspace:packages/advanced-personalization"
+  dependencies:
+    "@algolia/client-common": "npm:5.27.0"
+    "@algolia/requester-browser-xhr": "npm:5.27.0"
+    "@algolia/requester-fetch": "npm:5.27.0"
+    "@algolia/requester-node-http": "npm:5.27.0"
+    "@arethetypeswrong/cli": "npm:0.18.2"
+    "@types/node": "npm:22.15.30"
+    publint: "npm:0.3.12"
+    rollup: "npm:4.41.0"
+    tsup: "npm:8.5.0"
+    typescript: "npm:5.8.3"
+  languageName: unknown
+  linkType: soft
+
 "@algolia/client-abtesting@npm:5.27.0, @algolia/client-abtesting@workspace:packages/client-abtesting":
   version: 0.0.0-use.local
   resolution: "@algolia/client-abtesting@workspace:packages/client-abtesting"
diff --git a/config/clients.config.json b/config/clients.config.json
@@ -163,6 +163,11 @@
         "name": "personalization",
         "output": "clients/algoliasearch-client-javascript/packages/client-personalization"
       },
+      {
+        "name": "advanced-personalization",
+        "output": "clients/algoliasearch-client-javascript/packages/advanced-personalization",
+        "isStandaloneClient": true
+      },
       {
         "name": "query-suggestions",
         "output": "clients/algoliasearch-client-javascript/packages/client-query-suggestions"
diff --git a/config/clients.schema.json b/config/clients.schema.json
@@ -18,6 +18,7 @@
                 "insights",
                 "monitoring",
                 "personalization",
+                "advanced-personalization",
                 "query-suggestions",
                 "recommend",
                 "search"
@@ -41,6 +42,7 @@
                     "insights",
                     "monitoring",
                     "personalization",
+                    "advanced-personalization",
                     "query-suggestions",
                     "recommend",
                     "search"
diff --git a/generators/src/main/java/com/algolia/codegen/cts/tests/TestsRequest.java b/generators/src/main/java/com/algolia/codegen/cts/tests/TestsRequest.java
@@ -83,11 +83,11 @@ public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation>
 
     bundle.put(
       "e2eAppID",
-      client.startsWith("composition") || client.startsWith("realtime") ? "METIS_APPLICATION_ID" : "ALGOLIA_APPLICATION_ID"
+      client.startsWith("composition") || client.startsWith("advanced-personalization") ? "METIS_APPLICATION_ID" : "ALGOLIA_APPLICATION_ID"
     );
     bundle.put(
       "e2eApiKey",
-      client.startsWith("composition") || client.startsWith("realtime")
+      client.startsWith("composition") || client.startsWith("advanced-personalization")
         ? "METIS_API_KEY"
         : (client.equals("monitoring") ? "MONITORING_API_KEY" : "ALGOLIA_ADMIN_KEY")
     );
diff --git a/playground/javascript/node/advancedPersonalization.ts b/playground/javascript/node/advancedPersonalization.ts
@@ -0,0 +1,24 @@
+import { advancedPersonalizationClient } from '@algolia/advanced-personalization';
+import { ApiError } from '@algolia/client-common';
+
+const appId = process.env.ALGOLIA_APPLICATION_ID || '**** APP_ID *****';
+const apiKey = process.env.ALGOLIA_RECOMMENDATION_KEY || '**** RECOMMENDATION_API_KEY *****';
+
+// Init client with appId and apiKey
+const client = advancedPersonalizationClient(appId, apiKey, 'eu');
+
+async function testPersonalization() {
+  try {
+    const res = await client.computeRealtimeUser({ userToken: 'userToken' });
+
+    console.log(`[OK]`, res);
+  } catch (e) {
+    if (e instanceof ApiError) {
+      return console.log(`[${e.status}] ${e.message}`, e.stackTrace);
+    }
+
+    console.log('[ERROR]', e);
+  }
+}
+
+testPersonalization();
diff --git a/playground/javascript/node/package.json b/playground/javascript/node/package.json
@@ -7,14 +7,14 @@
     "start": "tsc && node --env-file=../../.env dist/$0.js"
   },
   "dependencies": {
+    "@algolia/advanced-personalization": "link:../../../clients/algoliasearch-client-javascript/packages/advanced-personalization",
     "@algolia/client-abtesting": "link:../../../clients/algoliasearch-client-javascript/packages/client-abtesting",
     "@algolia/client-analytics": "link:../../../clients/algoliasearch-client-javascript/packages/client-analytics",
     "@algolia/client-common": "link:../../../clients/algoliasearch-client-javascript/packages/client-common",
     "@algolia/client-composition": "link:../../../clients/algoliasearch-client-javascript/packages/client-composition",
     "@algolia/client-insights": "link:../../../clients/algoliasearch-client-javascript/packages/client-insights",
     "@algolia/client-personalization": "link:../../../clients/algoliasearch-client-javascript/packages/client-personalization",
     "@algolia/client-query-suggestions": "link:../../../clients/algoliasearch-client-javascript/packages/client-query-suggestions",
-    "@algolia/client-realtime-personalization": "link:../../../clients/algoliasearch-client-javascript/packages/client-realtime-personalization",
     "@algolia/client-search": "link:../../../clients/algoliasearch-client-javascript/packages/client-search",
     "@algolia/composition": "link:../../../clients/algoliasearch-client-javascript/packages/composition",
     "@algolia/ingestion": "link:../../../clients/algoliasearch-client-javascript/packages/ingestion",
diff --git a/scripts/common.ts b/scripts/common.ts
@@ -71,13 +71,9 @@ export const GENERATORS = Object.entries(clientsConfig).reduce(
 
 export const LANGUAGES = [...new Set(Object.values(GENERATORS).map((gen) => gen.language))];
 
-// `crawler` and `advanced-personalization` are manually added so we can still bundled and validate the specs
+// `crawler` is 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',
-  'advanced-personalization',
-];
+export const CLIENTS = [...new Set(Object.values(GENERATORS).map((gen) => gen.client)), 'crawler'];
 
 export async function run(command: string, { errorMessage, cwd, language }: RunOptions = {}): Promise<string> {
   const realCwd = path.resolve(ROOT_DIR, cwd ?? '.');
diff --git a/specs/advanced-personalization/common/enums.yml b/specs/advanced-personalization/common/enums.yml
@@ -21,3 +21,11 @@ sourceType:
   title: type
   type: string
   enum: [insights]
+
+strategy:
+  type: string
+  enum:
+    - session
+    - historical
+    - hybrid
+  example: 'session'
diff --git a/specs/advanced-personalization/common/parameters.yml b/specs/advanced-personalization/common/parameters.yml
diff --git a/specs/advanced-personalization/common/schemas/RealtimeUser.yml b/specs/advanced-personalization/common/schemas/RealtimeUser.yml
diff --git a/specs/advanced-personalization/paths/computeRealtimeUser.yml b/specs/advanced-personalization/paths/computeRealtimeUser.yml
@@ -1,7 +1,7 @@
 post:
   tags:
     - users
-  operationId: computeUser
+  operationId: computeRealtimeUser
   x-acl:
     - recommendation
   summary: Compute the user's personalization profile
diff --git a/specs/advanced-personalization/paths/getRealtimeUser.yml b/specs/advanced-personalization/paths/getRealtimeUser.yml
@@ -1,7 +1,7 @@
 get:
   tags:
     - users
-  operationId: getUser
+  operationId: getRealtimeUser
   x-acl:
     - recommendation
   summary: Retrieve the user's personalization profile
@@ -14,7 +14,7 @@ get:
       content:
         application/json:
           schema:
-            $ref: '../common/schemas/user.yml#/user'
+            $ref: '../common/schemas/RealtimeUser.yml#/user'
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':
diff --git a/specs/advanced-personalization/spec.yml b/specs/advanced-personalization/spec.yml
@@ -114,3 +114,19 @@ paths:
 
   /2/users/{userID}:
     $ref: 'paths/user.yml'
+
+  # #################
+  # ### Real-time ###
+  # #################
+
+  /2/realtime/users/{userToken}:
+    $ref: 'paths/getRealtimeUser.yml'
+
+  /2/realtime/users/{userToken}/compute:
+    $ref: 'paths/computeRealtimeUser.yml'
+
+  # ###############
+  # ### Helpers ###
+  # ###############
+  /setClientApiKey:
+    $ref: '../common/helpers/setClientApiKey.yml#/method'
diff --git a/specs/realtime-personalization/common/enums.yml b/specs/realtime-personalization/common/enums.yml
diff --git a/specs/realtime-personalization/spec.yml b/specs/realtime-personalization/spec.yml
diff --git a/tests/CTS/client/advanced-personalization/parameters.json b/tests/CTS/client/advanced-personalization/parameters.json
@@ -0,0 +1,50 @@
+[
+  {
+    "testName": "throws when region is not given",
+    "autoCreateClient": false,
+    "steps": [
+      {
+        "type": "createClient",
+        "parameters": {
+          "appId": "my-app-id",
+          "apiKey": "my-api-key",
+          "region": ""
+        },
+        "expected": {
+          "error": "`region` is required and must be one of the following: eu, us"
+        }
+      }
+    ]
+  },
+  {
+    "testName": "throws when incorrect region is given",
+    "autoCreateClient": false,
+    "steps": [
+      {
+        "type": "createClient",
+        "parameters": {
+          "appId": "my-app-id",
+          "apiKey": "my-api-key",
+          "region": "not_a_region"
+        },
+        "expected": {
+          "error": "`region` is required and must be one of the following: eu, us"
+        }
+      }
+    ]
+  },
+  {
+    "testName": "does not throw when region is given",
+    "autoCreateClient": false,
+    "steps": [
+      {
+        "type": "createClient",
+        "parameters": {
+          "appId": "my-app-id",
+          "apiKey": "my-api-key",
+          "region": "us"
+        }
+      }
+    ]
+  }
+]
diff --git a/tests/CTS/client/realtime-personalization/api.json b/tests/CTS/client/realtime-personalization/api.json
diff --git a/tests/CTS/requests/advanced-personalization/computeRealtimeUser.json b/tests/CTS/requests/advanced-personalization/computeRealtimeUser.json
@@ -0,0 +1,11 @@
+[
+  {
+    "parameters": {
+      "userToken": "foo"
+    },
+    "request": {
+      "path": "/2/realtime/users/foo/compute",
+      "method": "POST"
+    }
+  }
+]
diff --git a/tests/CTS/requests/advanced-personalization/deleteUser.json b/tests/CTS/requests/advanced-personalization/deleteUser.json
@@ -0,0 +1,11 @@
+[
+  {
+    "parameters": {
+      "userID": "user-1"
+    },
+    "request": {
+      "path": "/2/users/user-1",
+      "method": "DELETE"
+    }
+  }
+]
diff --git a/tests/CTS/requests/advanced-personalization/getConfig.json b/tests/CTS/requests/advanced-personalization/getConfig.json
@@ -0,0 +1,8 @@
+[
+  {
+    "request": {
+      "path": "/2/config",
+      "method": "GET"
+    }
+  }
+]
diff --git a/tests/CTS/requests/advanced-personalization/getRealtimeUser.json b/tests/CTS/requests/advanced-personalization/getRealtimeUser.json
diff --git a/tests/CTS/requests/advanced-personalization/getUser.json b/tests/CTS/requests/advanced-personalization/getUser.json
@@ -0,0 +1,11 @@
+[
+  {
+    "parameters": {
+      "userID": "user-1"
+    },
+    "request": {
+      "path": "/2/users/user-1",
+      "method": "GET"
+    }
+  }
+]
diff --git a/tests/CTS/requests/advanced-personalization/getUsers.json b/tests/CTS/requests/advanced-personalization/getUsers.json
@@ -0,0 +1,14 @@
+[
+  {
+    "parameters": {
+      "indices": ["indexName"]
+    },
+    "request": {
+      "path": "/2/users",
+      "method": "GET",
+      "queryParameters": {
+        "indices": "indexName"
+      }
+    }
+  }
+]
diff --git a/tests/CTS/requests/advanced-personalization/putConfig.json b/tests/CTS/requests/advanced-personalization/putConfig.json
diff --git a/tests/output/javascript/yarn.lock b/tests/output/javascript/yarn.lock
