feat(specs): add composition API (#4056)

Co-authored-by: shortcuts <[email protected]>
Co-authored-by: Pierre Millot <[email protected]>

Author: 3 people

clients/algoliasearch-client-javascript/bundlesize.config.json

@@ -16,6 +16,10 @@
       "path": "packages/client-analytics/dist/builds/browser.umd.js",
       "maxSize": "4.85KB"
     },
+    {
+      "path": "packages/client-composition/dist/builds/browser.umd.js",
+      "maxSize": "4.05KB"
+    },
     {
       "path": "packages/client-insights/dist/builds/browser.umd.js",
       "maxSize": "3.90KB"

clients/algoliasearch-client-javascript/package.json

@@ -6,7 +6,7 @@
     "packages/*"
   ],
   "scripts": {
-    "build": "lerna run build --scope '@algolia/requester-testing' --scope '@algolia/logger-console' --scope 'algoliasearch' --include-dependencies",
+    "build": "lerna run build --scope '@algolia/requester-testing' --scope '@algolia/logger-console' --scope 'algoliasearch' --scope '@algolia/client-composition' --include-dependencies",
     "clean": "lerna run clean",
     "release:bump": "lerna version ${0:-patch} --no-changelog --no-git-tag-version --no-push --exact --force-publish --yes",
     "release:publish": "tsc --project scripts/tsconfig.json && node scripts/dist/scripts/publish.js",

clients/algoliasearch-client-javascript/packages/client-composition/package.json

@@ -0,0 +1,67 @@
+{
+  "version": "0.0.1-alpha.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/algolia/algoliasearch-client-javascript.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "author": "Algolia",
+  "scripts": {
+    "build": "yarn clean && yarn tsup && yarn rollup -c rollup.config.js",
+    "clean": "rm -rf ./dist || true",
+    "test:bundle": "publint . && attw --pack ."
+  },
+  "name": "@algolia/client-composition",
+  "description": "JavaScript client for client-composition",
+  "exports": {
+    ".": {
+      "node": {
+        "types": {
+          "import": "./dist/node.d.ts",
+          "module": "./dist/node.d.ts",
+          "require": "./dist/node.d.cts"
+        },
+        "import": "./dist/builds/node.js",
+        "module": "./dist/builds/node.js",
+        "require": "./dist/builds/node.cjs"
+      },
+      "worker": {
+        "types": "./dist/fetch.d.ts",
+        "default": "./dist/builds/fetch.js"
+      },
+      "default": {
+        "types": "./dist/browser.d.ts",
+        "module": "./dist/builds/browser.js",
+        "import": "./dist/builds/browser.js",
+        "default": "./dist/builds/browser.umd.js"
+      }
+    },
+    "./src/*": "./src/*.ts"
+  },
+  "jsdelivr": "./dist/builds/browser.umd.js",
+  "unpkg": "./dist/builds/browser.umd.js",
+  "react-native": "./dist/builds/browser.js",
+  "files": [
+    "dist",
+    "index.js",
+    "index.d.ts"
+  ],
+  "dependencies": {
+    "@algolia/client-common": "5.12.0",
+    "@algolia/requester-browser-xhr": "5.12.0",
+    "@algolia/requester-node-http": "5.12.0",
+    "@algolia/requester-fetch": "5.12.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.16.4",
+    "@types/node": "22.8.1",
+    "publint": "0.2.12",
+    "rollup": "4.24.2",
+    "tsup": "8.3.5",
+    "typescript": "5.6.3"
+  },
+  "engines": {
+    "node": ">= 14.0.0"
+  }
+}

clients/algoliasearch-client-javascript/yarn.lock

@@ -54,6 +54,23 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@algolia/client-composition@workspace:packages/client-composition":
+  version: 0.0.0-use.local
+  resolution: "@algolia/client-composition@workspace:packages/client-composition"
+  dependencies:
+    "@algolia/client-common": "npm:5.12.0"
+    "@algolia/requester-browser-xhr": "npm:5.12.0"
+    "@algolia/requester-fetch": "npm:5.12.0"
+    "@algolia/requester-node-http": "npm:5.12.0"
+    "@arethetypeswrong/cli": "npm:0.16.4"
+    "@types/node": "npm:22.8.1"
+    publint: "npm:0.2.12"
+    rollup: "npm:4.24.2"
+    tsup: "npm:8.3.5"
+    typescript: "npm:5.6.3"
+  languageName: unknown
+  linkType: soft
+
 "@algolia/client-insights@npm:5.12.0, @algolia/client-insights@workspace:packages/client-insights":
   version: 0.0.0-use.local
   resolution: "@algolia/client-insights@workspace:packages/client-insights"

config/clients.config.json

@@ -113,12 +113,7 @@
       "extension": ".java",
       "outputFolder": "src/test/java/com/algolia"
     },
-    "supportedVersions": [
-      "8",
-      "11",
-      "21",
-      "17"
-    ]
+    "supportedVersions": ["8", "11", "21", "17"]
   },
   "javascript": {
     "clients": [
@@ -161,6 +156,10 @@
       {
         "name": "search",
         "output": "clients/algoliasearch-client-javascript/packages/client-search"
+      },
+      {
+        "name": "composition",
+        "output": "clients/algoliasearch-client-javascript/packages/client-composition"
       }
     ],
     "folder": "clients/algoliasearch-client-javascript",
@@ -257,13 +256,7 @@
       "extension": ".py",
       "outputFolder": ""
     },
-    "supportedVersions": [
-      "3.8",
-      "3.9",
-      "3.10",
-      "3.11",
-      "3.12"
-    ]
+    "supportedVersions": ["3.8", "3.9", "3.10", "3.11", "3.12"]
   },
   "ruby": {
     "clients": [

generators/src/main/java/com/algolia/codegen/AlgoliaJavascriptGenerator.java

@@ -18,6 +18,7 @@ public class AlgoliaJavascriptGenerator extends TypeScriptNodeClientCodegen {
 
   private String CLIENT;
   private boolean isAlgoliasearchClient;
+  private boolean isAlgoliaCompositionClient;
 
   @Override
   public String getName() {
@@ -30,6 +31,7 @@ public void processOpts() {
 
     CLIENT = Helpers.camelize((String) additionalProperties.get("client"));
     isAlgoliasearchClient = CLIENT.equals("algoliasearch");
+    isAlgoliaCompositionClient = CLIENT.equals("composition");
 
     // generator specific options
     setSupportsES6(true);
@@ -155,6 +157,7 @@ private void setDefaultGeneratorOptions() {
     additionalProperties.put("isSearchClient", CLIENT.equals("search") || isAlgoliasearchClient);
     additionalProperties.put("isIngestionClient", CLIENT.equals("ingestion"));
     additionalProperties.put("isAlgoliasearchClient", isAlgoliasearchClient);
+    additionalProperties.put("isAlgoliaCompositionClient", isAlgoliaCompositionClient);
     additionalProperties.put("packageVersion", Helpers.getPackageJsonVersion(packageName));
     additionalProperties.put("packageName", packageName);
     additionalProperties.put("npmPackageName", isAlgoliasearchClient ? packageName : "@algolia/" + packageName);
@@ -169,10 +172,16 @@ private void setDefaultGeneratorOptions() {
           continue;
         }
 
+        String version = Helpers.getPackageJsonVersion(name);
+
+        if (version.contains("alpha") || version.contains("beta")) {
+          continue;
+        }
+
         var dependency = new HashMap<String, Object>();
         dependency.put("dependencyName", Helpers.createClientName((String) pkg.get("name"), "javascript"));
         dependency.put("dependencyPackage", "@algolia/" + name);
-        dependency.put("dependencyVersion", Helpers.getPackageJsonVersion(name));
+        dependency.put("dependencyVersion", version);
         dependency.put("withInitMethod", !name.contains("search"));
         dependency.put(
           "dependencyHasRegionalHosts",

generators/src/main/java/com/algolia/codegen/cts/AlgoliaCTSGenerator.java

@@ -148,6 +148,7 @@ public Map<String, Object> postProcessSupportingFileData(Map<String, Object> obj
       // We can put whatever we want in the bundle, and it will be accessible in the template
       bundle.put("mode", mode);
       bundle.put("is" + Helpers.capitalize(client) + "Client", true);
+      bundle.put("isStandaloneClient", client.contains("search") || client.equals("composition"));
       bundle.put("isSearchClient", client.contains("search")); // just so algoliasearch is treated as a search client too
       bundle.put("client", Helpers.createClientName(importClientName, language) + "Client");
       bundle.put("clientPrefix", Helpers.createClientName(importClientName, language));

generators/src/main/java/com/algolia/codegen/cts/manager/JavascriptCTSManager.java

@@ -46,7 +46,13 @@ public void addDataToBundle(Map<String, Object> bundle) throws GeneratorExceptio
     bundle.put("utilsPackageVersion", Helpers.getPackageJsonVersion("client-common"));
     bundle.put("algoliasearchVersion", Helpers.getPackageJsonVersion("algoliasearch"));
     bundle.put("initMethod", "init" + Helpers.capitalize(Helpers.camelize(client)));
-    bundle.put("clientName", client.equals("algoliasearch") ? "liteClient" : "algoliasearch");
-    bundle.put("importPackage", client.equals("algoliasearch") ? "algoliasearch/lite" : "algoliasearch");
+    bundle.put(
+      "clientName",
+      client.equals("algoliasearch") ? "liteClient" : client.equals("composition") ? "compositionClient" : "algoliasearch"
+    );
+    bundle.put(
+      "importPackage",
+      client.equals("algoliasearch") ? "algoliasearch/lite" : client.equals("composition") ? "@algolia/client-composition" : "algoliasearch"
+    );
   }
 }

playground/javascript/node/composition.ts

@@ -0,0 +1,24 @@
+import { ApiError } from '@algolia/client-common';
+import { compositionClient } from '@algolia/client-composition';
+
+const appId = process.env.ALGOLIA_APPLICATION_ID || '**** APP_ID *****';
+const apiKey = process.env.ALGOLIA_ADMIN_KEY || '**** ADMIN_KEY *****';
+
+// Init client with appId and apiKey
+const client = compositionClient(appId, apiKey);
+
+async function testComposition() {
+  try {
+    const res = await client.listCompositions();
+
+    console.log(`[OK]`, res);
+  } catch (e) {
+    if (e instanceof ApiError) {
+      return console.log(`[${e.status}] ${e.message}`, e.stackTrace, e);
+    }
+
+    console.log('[ERROR]', e);
+  }
+}
+
+testComposition();

playground/javascript/node/package.json

@@ -10,6 +10,7 @@
     "@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",

scripts/common.ts

@@ -276,6 +276,10 @@ export async function callGenerator(gen: Generator): Promise<void> {
   );
 }
 
+export function isWSL(): boolean {
+  return process.env.WSL_DISTRO_NAME !== undefined;
+}
+
 export async function setupAndGen(
   generators: Generator[],
   mode: GeneratorMode,

scripts/cts/testServer/timeout.ts

@@ -17,6 +17,7 @@ export function assertValidTimeouts(expectedCount: number): void {
   for (const [lang, state] of Object.entries(timeoutState)) {
     let numberOfTestSuites = 1;
 
+    // python has sync and async tests
     if (lang === 'python') {
       numberOfTestSuites = 2;
     }
@@ -26,23 +27,23 @@ export function assertValidTimeouts(expectedCount: number): void {
     expect(state.duration.length).to.equal(3 * numberOfTestSuites);
 
     for (let i = 0; i < numberOfTestSuites; i++) {
-      expect(state.timestamp[3 * i + 1] - state.timestamp[3 * i]).to.be.closeTo(state.duration[3 * i], 100);
-      expect(state.timestamp[3 * i + 2] - state.timestamp[3 * i + 1]).to.be.closeTo(state.duration[3 * i + 1], 100);
+      expect(state.timestamp[3 * i + 1] - state.timestamp[3 * i]).to.be.closeTo(state.duration[3 * i], 400);
+      expect(state.timestamp[3 * i + 2] - state.timestamp[3 * i + 1]).to.be.closeTo(state.duration[3 * i + 1], 400);
 
       // languages are not consistent yet for the delay between requests
       switch (lang) {
         case 'javascript':
           expect(state.duration[3 * i] * 4).to.be.closeTo(state.duration[3 * i + 1], 300);
           break;
         case 'php':
-          expect(state.duration[3 * i] * 2).to.be.closeTo(state.duration[3 * i + 1], 200);
+          expect(state.duration[3 * i] * 2).to.be.closeTo(state.duration[3 * i + 1], 300);
           break;
         case 'swift':
           expect(state.duration[3 * i]).to.be.closeTo(state.duration[3 * i + 1], 800);
           break;
         default:
           // the delay should be the same, because the `retryCount` is per host instead of global
-          expect(state.duration[3 * i]).to.be.closeTo(state.duration[3 * i + 1], 150);
+          expect(state.duration[3 * i]).to.be.closeTo(state.duration[3 * i + 1], 300);
           break;
       }
     }

scripts/generate.ts

@@ -1,4 +1,4 @@
-import { callGenerator, setupAndGen } from './common.js';
+import { callGenerator, isWSL, run, setupAndGen } from './common.js';
 import { getLanguageFolder } from './config.js';
 import { formatter } from './formatter.js';
 import { removeExistingCodegen } from './pre-gen/index.js';
@@ -15,6 +15,9 @@ export async function generate(generators: Generator[]): Promise<void> {
   });
 
   for (const lang of [...new Set(generators.map((gen) => gen.language))]) {
+    if (isWSL()) {
+      await run(`sudo chmod 777 -R ${getLanguageFolder(lang)}`);
+    }
     await formatter(lang, getLanguageFolder(lang));
   }
 }

specs/common/responses/CompositionNotFound.yml

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

specs/composition/common/parameters.yml

@@ -0,0 +1,11 @@
+compositionID:
+  in: path
+  name: compositionID
+  description: Unique Composition ObjectID.
+  required: true
+  schema:
+    $ref: '#/compositionObjectID'
+
+compositionObjectID:
+  type: string
+  description: Unique Composition ObjectID.

specs/composition/common/schemas/Batch.yml

@@ -0,0 +1,6 @@
+action:
+  type: string
+  enum:
+    - upsert
+    - delete
+  description: Type of Composition Batch operation.

specs/composition/common/schemas/GetTaskResponse.yml

@@ -0,0 +1,8 @@
+title: getTaskResponse
+type: object
+additionalProperties: false
+properties:
+  status:
+    $ref: '../../../common/responses/common.yml#/taskStatus'
+required:
+  - status

specs/composition/common/schemas/Hit.yml

@@ -0,0 +1,43 @@
+hit:
+  type: object
+  description: |
+    Search result.
+
+    A hit is a record from your index, augmented with special attributes for highlighting, snippeting, and ranking.
+  x-is-generic: true
+  additionalProperties: true
+  required:
+    - objectID
+  properties:
+    objectID:
+      $ref: '../../../common/parameters.yml#/objectID'
+    _highlightResult:
+      $ref: '../../../common/schemas/HighlightResult.yml#/highlightResultMap'
+    _snippetResult:
+      $ref: '../../../common/schemas/SnippetResult.yml#/snippetResultMap'
+    _rankingInfo:
+      $ref: '#/rankingInfo'
+    _distinctSeqID:
+      $ref: '../../../common/schemas/Hit.yml#/distinctSeqID'
+
+rankingInfo:
+  allOf:
+    - $ref: '../../../common/schemas/Hit.yml#/rankingInfo'
+    - $ref: '#/compositionRankingInfo'
+
+compositionRankingInfo:
+  type: object
+  additionalProperties: false
+  properties:
+    composed:
+      title: composedRankingInfo
+      type: object
+      additionalProperties: false
+      properties:
+        index:
+          type: string
+        inset:
+          type: string
+      required:
+        - index
+        - inset