feat(spec): add trending models (#213)

Author: shortcuts

clients/algoliasearch-client-javascript/packages/recommend/model/baseRecommendRequest.ts

@@ -0,0 +1,18 @@
+import type { SearchParamsObject } from './searchParamsObject';
+
+export type BaseRecommendRequest = {
+  /**
+   * The Algolia index name.
+   */
+  indexName: string;
+  /**
+   * The threshold to use when filtering recommendations by their score.
+   */
+  threshold: number;
+  /**
+   * The max number of recommendations to retrieve. If it\'s set to 0, all the recommendations of the objectID may be returned.
+   */
+  maxRecommendations?: number;
+  queryParameters?: SearchParamsObject;
+  fallbackParameters?: SearchParamsObject;
+};

clients/algoliasearch-client-javascript/packages/recommend/model/baseRecommendationRequest.ts

@@ -0,0 +1,9 @@
+import type { RecommendationModels } from './recommendationModels';
+
+export type BaseRecommendationRequest = {
+  model: RecommendationModels;
+  /**
+   * Unique identifier of the object.
+   */
+  objectID: string;
+};

clients/algoliasearch-client-javascript/packages/recommend/model/baseTrendingRequest.ts

@@ -0,0 +1,13 @@
+import type { TrendingModels } from './trendingModels';
+
+export type BaseTrendingRequest = {
+  model: TrendingModels;
+  /**
+   * The facet name to use for trending models.
+   */
+  facetName?: string;
+  /**
+   * The facet value to use for trending models.
+   */
+  facetValue?: string;
+};

clients/algoliasearch-client-javascript/packages/recommend/model/getRecommendationsParams.ts

@@ -1,4 +1,4 @@
-import type { RecommendationRequest } from './recommendationRequest';
+import type { RecommendationsRequest } from './recommendationsRequest';
 
 /**
  * The `getRecommendations` parameters.
@@ -7,5 +7,5 @@ export type GetRecommendationsParams = {
   /**
    * The `getRecommendations` requests.
    */
-  requests: RecommendationRequest[];
+  requests: RecommendationsRequest[];
 };

clients/algoliasearch-client-javascript/packages/recommend/model/recommendationModels.ts

@@ -0,0 +1,5 @@
+/**
+ * The recommendation model to use.
+ */
+
+export type RecommendationModels = 'bought-together' | 'related-products';

clients/algoliasearch-client-javascript/packages/recommend/model/recommendationRequest.ts

@@ -1,28 +1,5 @@
-import type { SearchParams } from './searchParams';
+import type { BaseRecommendRequest } from './baseRecommendRequest';
+import type { BaseRecommendationRequest } from './baseRecommendationRequest';
 
-export type RecommendationRequest = {
-  /**
-   * The Algolia index name.
-   */
-  indexName: string;
-  /**
-   * Unique identifier of the object.
-   */
-  objectID: string;
-  /**
-   * The recommendation model to use.
-   */
-  model: RecommendationRequestModel;
-  /**
-   * The threshold to use when filtering recommendations by their score.
-   */
-  threshold: number;
-  /**
-   * The max number of recommendations to retrieve. If it\'s set to 0, all the recommendations of the objectID may be returned.
-   */
-  maxRecommendations?: number;
-  queryParameters?: SearchParams;
-  fallbackParameters?: SearchParams;
-};
-
-export type RecommendationRequestModel = 'bought-together' | 'related-products';
+export type RecommendationRequest = BaseRecommendationRequest &
+  BaseRecommendRequest;

clients/algoliasearch-client-javascript/packages/recommend/model/recommendationsRequest.ts

@@ -0,0 +1,4 @@
+import type { RecommendationRequest } from './recommendationRequest';
+import type { TrendingRequest } from './trendingRequest';
+
+export type RecommendationsRequest = RecommendationRequest | TrendingRequest;

clients/algoliasearch-client-javascript/packages/recommend/model/searchParams.ts renamed to clients/algoliasearch-client-javascript/packages/recommend/model/searchParamsObject.ts

@@ -2,6 +2,6 @@ import type { BaseSearchParams } from './baseSearchParams';
 import type { IndexSettingsAsSearchParams } from './indexSettingsAsSearchParams';
 import type { RequiredSearchParams } from './requiredSearchParams';
 
-export type SearchParams = BaseSearchParams &
+export type SearchParamsObject = BaseSearchParams &
   IndexSettingsAsSearchParams &
   RequiredSearchParams;

clients/algoliasearch-client-javascript/packages/recommend/model/trendingModels.ts

@@ -0,0 +1,5 @@
+/**
+ * The trending model to use.
+ */
+
+export type TrendingModels = 'trending-facets' | 'trending-items';

clients/algoliasearch-client-javascript/packages/recommend/model/trendingRequest.ts

@@ -0,0 +1,4 @@
+import type { BaseRecommendRequest } from './baseRecommendRequest';
+import type { BaseTrendingRequest } from './baseTrendingRequest';
+
+export type TrendingRequest = BaseRecommendRequest & BaseTrendingRequest;

specs/bundled/recommend.yml

@@ -42,13 +42,16 @@ components:
         message:
           type: string
           example: Invalid Application-Id or API-Key
+    trendingModels:
+      description: The trending model to use.
+      type: string
+      enum:
+        - trending-facets
+        - trending-items
     indexName:
       type: string
       example: products
       description: The Algolia index name.
-    objectID:
-      type: string
-      description: Unique identifier of the object.
     page:
       type: integer
       description: Specify the page to retrieve.
@@ -556,11 +559,79 @@ components:
             set via the settings for a default value and can be overridden via
             rules.
           default: {}
-    searchParams:
+    searchParamsObject:
       allOf:
         - $ref: '#/components/schemas/baseSearchParams'
         - $ref: '#/components/schemas/requiredSearchParams'
         - $ref: '#/components/schemas/indexSettingsAsSearchParams'
+    baseRecommendRequest:
+      type: object
+      additionalProperties: false
+      properties:
+        indexName:
+          $ref: '#/components/schemas/indexName'
+        threshold:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: The threshold to use when filtering recommendations by their score.
+        maxRecommendations:
+          type: integer
+          default: 0
+          description: >-
+            The max number of recommendations to retrieve. If it's set to 0, all
+            the recommendations of the objectID may be returned.
+        queryParameters:
+          $ref: '#/components/schemas/searchParamsObject'
+        fallbackParameters:
+          $ref: '#/components/schemas/searchParamsObject'
+      required:
+        - indexName
+        - threshold
+    trendingRequest:
+      allOf:
+        - type: object
+          title: baseTrendingRequest
+          additionalProperties: false
+          properties:
+            model:
+              $ref: '#/components/schemas/trendingModels'
+            facetName:
+              type: string
+              description: The facet name to use for trending models.
+            facetValue:
+              type: string
+              description: The facet value to use for trending models.
+          required:
+            - model
+        - $ref: '#/components/schemas/baseRecommendRequest'
+    recommendationModels:
+      description: The recommendation model to use.
+      type: string
+      enum:
+        - related-products
+        - bought-together
+    objectID:
+      type: string
+      description: Unique identifier of the object.
+    recommendationRequest:
+      allOf:
+        - type: object
+          title: baseRecommendationRequest
+          additionalProperties: false
+          properties:
+            model:
+              $ref: '#/components/schemas/recommendationModels'
+            objectID:
+              $ref: '#/components/schemas/objectID'
+          required:
+            - model
+            - objectID
+        - $ref: '#/components/schemas/baseRecommendRequest'
+    recommendationsRequest:
+      oneOf:
+        - $ref: '#/components/schemas/trendingRequest'
+        - $ref: '#/components/schemas/recommendationRequest'
     abTestID:
       type: integer
       description: >-
@@ -1025,43 +1096,7 @@ paths:
                   type: array
                   description: The `getRecommendations` requests.
                   items:
-                    title: recommendationRequest
-                    type: object
-                    additionalProperties: false
-                    properties:
-                      indexName:
-                        $ref: '#/components/schemas/indexName'
-                      objectID:
-                        $ref: '#/components/schemas/objectID'
-                      model:
-                        description: The recommendation model to use.
-                        type: string
-                        enum:
-                          - related-products
-                          - bought-together
-                      threshold:
-                        type: integer
-                        minimum: 0
-                        maximum: 100
-                        description: >-
-                          The threshold to use when filtering recommendations by
-                          their score.
-                      maxRecommendations:
-                        type: integer
-                        default: 0
-                        description: >-
-                          The max number of recommendations to retrieve. If it's
-                          set to 0, all the recommendations of the objectID may
-                          be returned.
-                      queryParameters:
-                        $ref: '#/components/schemas/searchParams'
-                      fallbackParameters:
-                        $ref: '#/components/schemas/searchParams'
-                    required:
-                      - model
-                      - indexName
-                      - objectID
-                      - threshold
+                    $ref: '#/components/schemas/recommendationsRequest'
               required:
                 - requests
       responses:

specs/recommend/common/schemas/RecommendationsRequest.yml

@@ -0,0 +1,70 @@
+recommendationsRequest:
+  oneOf:
+    - $ref: '#/trendingRequest'
+    - $ref: '#/recommendationRequest'
+
+trendingRequest:
+  allOf:
+    - type: object
+      title: baseTrendingRequest
+      additionalProperties: false
+      properties:
+        model:
+          $ref: '#/trendingModels'
+        facetName:
+          type: string
+          description: The facet name to use for trending models.
+        facetValue:
+          type: string
+          description: The facet value to use for trending models.
+      required:
+        - model
+    - $ref: '#/baseRecommendRequest'
+
+recommendationRequest:
+  allOf:
+    - type: object
+      title: baseRecommendationRequest
+      additionalProperties: false
+      properties:
+        model:
+          $ref: '#/recommendationModels'
+        objectID:
+          $ref: '../../../common/parameters.yml#/objectID'
+      required:
+        - model
+        - objectID
+    - $ref: '#/baseRecommendRequest'
+
+baseRecommendRequest:
+  type: object
+  additionalProperties: false
+  properties:
+    indexName:
+      $ref: '../../../common/parameters.yml#/indexName'
+    threshold:
+      type: integer
+      minimum: 0
+      maximum: 100
+      description: The threshold to use when filtering recommendations by their score.
+    maxRecommendations:
+      type: integer
+      default: 0
+      description: The max number of recommendations to retrieve. If it's set to 0, all the recommendations of the objectID may be returned.
+    queryParameters:
+      $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    fallbackParameters:
+      $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+  required:
+    - indexName
+    - threshold
+
+trendingModels:
+  description: The trending model to use.
+  type: string
+  enum: [trending-facets, trending-items]
+
+recommendationModels:
+  description: The recommendation model to use.
+  type: string
+  enum: [related-products, bought-together]

specs/recommend/common/schemas/SearchParams.yml

@@ -16,36 +16,7 @@ post:
               type: array
               description: The `getRecommendations` requests.
               items:
-                title: recommendationRequest
-                type: object
-                additionalProperties: false
-                properties:
-                  indexName:
-                    $ref: '../../common/parameters.yml#/indexName'
-                  objectID:
-                    $ref: '../../common/parameters.yml#/objectID'
-                  model:
-                    description: The recommendation model to use.
-                    type: string
-                    enum: [related-products, bought-together]
-                  threshold:
-                    type: integer
-                    minimum: 0
-                    maximum: 100
-                    description: The threshold to use when filtering recommendations by their score.
-                  maxRecommendations:
-                    type: integer
-                    default: 0
-                    description: The max number of recommendations to retrieve. If it's set to 0, all the recommendations of the objectID may be returned.
-                  queryParameters:
-                    $ref: '../common/schemas/SearchParams.yml#/searchParams'
-                  fallbackParameters:
-                    $ref: '../common/schemas/SearchParams.yml#/searchParams'
-                required:
-                  - model
-                  - indexName
-                  - objectID
-                  - threshold
+                $ref: '../common/schemas/RecommendationsRequest.yml#/recommendationsRequest'
           required:
             - requests
   responses: