feat(clients): add collections

Author: dhayab

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' --scope '@algolia/advanced-personalization' --include-dependencies ",
+    "build": "lerna run build --skip-nx-cache --scope '@algolia/requester-testing' --scope '@algolia/logger-console' --scope 'algoliasearch' --scope '@algolia/collections' --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 $*",

clients/algoliasearch-client-javascript/yarn.lock

@@ -173,6 +173,23 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@algolia/collections@workspace:packages/collections":
+  version: 0.0.0-use.local
+  resolution: "@algolia/collections@workspace:packages/collections"
+  dependencies:
+    "@algolia/client-common": "npm:5.35.0"
+    "@algolia/requester-browser-xhr": "npm:5.35.0"
+    "@algolia/requester-fetch": "npm:5.35.0"
+    "@algolia/requester-node-http": "npm:5.35.0"
+    "@arethetypeswrong/cli": "npm:0.18.2"
+    "@types/node": "npm:22.17.0"
+    publint: "npm:0.3.12"
+    rollup: "npm:4.41.0"
+    tsup: "npm:8.5.0"
+    typescript: "npm:5.9.2"
+  languageName: unknown
+  linkType: soft
+
 "@algolia/composition@workspace:packages/composition":
   version: 0.0.0-use.local
   resolution: "@algolia/composition@workspace:packages/composition"

config/clients.config.json

@@ -5,6 +5,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -39,6 +40,10 @@
         "name": "abtesting-v3",
         "output": "clients/algoliasearch-client-dart/packages/client_abtesting_v3"
       },
+      {
+        "name": "collections",
+        "output": "clients/algoliasearch-client-dart/packages/client_collections"
+      },
       {
         "name": "composition",
         "output": "clients/algoliasearch-client-dart/packages/client_composition"
@@ -76,6 +81,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -105,6 +111,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -153,6 +160,12 @@
         "name": "analytics",
         "output": "clients/algoliasearch-client-javascript/packages/client-analytics"
       },
+      {
+        "name": "collections",
+        "output": "clients/algoliasearch-client-javascript/packages/collections",
+        "isStandaloneClient": true,
+        "clientName": "collections"
+      },
       {
         "name": "composition",
         "output": "clients/algoliasearch-client-javascript/packages/composition",
@@ -218,6 +231,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -247,6 +261,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -276,6 +291,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -312,6 +328,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -341,6 +358,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",
@@ -370,6 +388,7 @@
       "abtesting",
       "abtesting-v3",
       "analytics",
+      "collections",
       "composition",
       "ingestion",
       "insights",

config/clients.schema.json

@@ -14,6 +14,7 @@
                 "abtesting",
                 "abtesting-v3",
                 "analytics",
+                "collections",
                 "composition",
                 "ingestion",
                 "insights",
@@ -38,6 +39,7 @@
                     "abtesting",
                     "abtesting-v3",
                     "analytics",
+                    "collections",
                     "composition",
                     "composition-full",
                     "ingestion",

playground/javascript/node/package.json

@@ -17,6 +17,7 @@
     "@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-search": "link:../../../clients/algoliasearch-client-javascript/packages/client-search",
+    "@algolia/collections": "link:../../../clients/algoliasearch-client-javascript/packages/collections",
     "@algolia/composition": "link:../../../clients/algoliasearch-client-javascript/packages/composition",
     "@algolia/ingestion": "link:../../../clients/algoliasearch-client-javascript/packages/ingestion",
     "@algolia/monitoring": "link:../../../clients/algoliasearch-client-javascript/packages/monitoring",

specs/collections/common/parameters.yml

@@ -0,0 +1,40 @@
+indexName:
+  name: indexName
+  in: query
+  required: true
+  description: Name of the index.
+  schema:
+    type: string
+    example: ALGOLIA_INDEX_NAME
+
+paginationLimit:
+  name: limit
+  in: query
+  description: Number of items to fetch.
+  required: false
+  schema:
+    $ref: './schemas/pagination.yml#/limit'
+
+paginationOffset:
+  name: offset
+  in: query
+  description: Number of items to skip.
+  required: false
+  schema:
+    $ref: './schemas/pagination.yml#/offset'
+
+pathCollectionID:
+  name: collectionID
+  in: path
+  required: true
+  description: Unique identifier of a collection.
+  schema:
+    $ref: './schemas/common.yml#/collectionID'
+
+query:
+  name: query
+  in: query
+  required: false
+  description: Query to filter collections.
+  schema:
+    $ref: './schemas/common.yml#/query'

specs/collections/common/responses/CollectionNotFound.yml

@@ -0,0 +1,10 @@
+description: Collection not found.
+content:
+  application/json:
+    schema:
+      title: collectionNotFoundResponse
+      type: object
+      properties:
+        message:
+          type: string
+          example: 'Collection not found'

specs/collections/common/schemas/collection.yml

@@ -0,0 +1,81 @@
+Collection:
+  type: object
+  properties:
+    id:
+      type: string
+      example: '5db3039e-04b5-4ed6-a00e-ba3304032c5a'
+    name:
+      type: string
+      example: 'Summer Deals'
+    indexName:
+      type: string
+      example: 'prod_products_EN'
+    createdAt:
+      type: string
+      format: date-time
+      example: '2024-10-07T00:00:00Z'
+    updatedAt:
+      type: string
+      format: date-time
+      example: '2024-10-07T00:00:00Z'
+    status:
+      $ref: '#/CollectionStatus'
+    conditions:
+      $ref: 'condition.yml#/Conditions'
+    records:
+      type: array
+      items:
+        type: string
+
+CollectionStatus:
+  type: string
+  description: |
+    Collection commit status.
+    Only returned if the request API key has write ACLs.
+  enum:
+    - COMMITTED
+    - COMMITTING
+    - TO_COMMIT
+
+CollectionUpsert:
+  type: object
+  description: API request body for upserting a Collection.
+  properties:
+    id:
+      type: string
+    indexName:
+      type: string
+    name:
+      type: string
+    description:
+      type: string
+    add:
+      type: array
+      description: a list of objectIDs.
+      minItems: 0
+      items:
+        type: string
+    remove:
+      type: array
+      description: a list of objectIDs.
+      minItems: 0
+      items:
+        type: string
+    conditions:
+      $ref: 'condition.yml#/Conditions'
+  required:
+    - indexName
+    - name
+
+CollectionsResponse:
+  type: object
+  allOf:
+    - type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/Collection'
+      required:
+        - items
+    - $ref: 'pagination.yml#/Pagination'

specs/collections/common/schemas/common.yml

@@ -0,0 +1,10 @@
+collectionID:
+  type: string
+  # format: uuid
+  description: Universally unique identifier (UUID) of a collection.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+query:
+  type: string
+  description: Query to filter collections.
+  example: Summer collection

specs/collections/common/schemas/condition.yml

@@ -0,0 +1,8 @@
+Conditions:
+  type: object
+  description: Conditions to filter records.
+  properties:
+    facetFilters:
+      $ref: '../../../common/schemas/SearchParams.yml#/facetFilters'
+    numericFilters:
+      $ref: '../../../common/schemas/SearchParams.yml#/numericFilters'