fix(specs): port recommend changes (#2476)

Author: shortcuts

specs/common/schemas/SearchParams.yml

@@ -136,11 +136,7 @@ baseSearchParamsWithoutQuery:
       x-categories:
         - Personalization
     userToken:
-      type: string
-      description: Associates a [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) with the current search.
-      example: '123456'
-      x-categories:
-        - Personalization
+      $ref: '#/userToken'
     getRankingInfo:
       type: boolean
       description: Incidates whether the search response includes [detailed ranking information](https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/#ranking-information).
@@ -209,6 +205,13 @@ paramsAsString:
   type: string
   default: ''
 
+userToken:
+  type: string
+  description: Associates a [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) with the current search.
+  example: '123456'
+  x-categories:
+    - Personalization
+
 query:
   type: string
   description: Text to search for in an index.

specs/recommend/common/parameters.yml

@@ -18,3 +18,11 @@ ObjectID:
   type: string
   description: Unique Recommend rule identifier.
   example: 'a-recommend-rule-id'
+
+facetName:
+  type: string
+  description: Facet name for trending models.
+
+facetValue:
+  type: string
+  description: Facet value for trending models.

specs/recommend/common/schemas/RecommendationsQuery.yml

@@ -1,7 +1,7 @@
 recommendationsQuery:
   allOf:
-    - $ref: '#/baseRecommendationsQuery'
     - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseRecommendationsQuery'
 
 baseRecommendationsQuery:
   type: object

specs/recommend/common/schemas/RecommendationsRequest.yml

@@ -1,8 +1,9 @@
 recommendationsRequest:
   oneOf:
-    - $ref: './TrendingQuery.yml#/trendingItemsQuery'
-    - $ref: './TrendingQuery.yml#/trendingFacetsQuery'
+    - $ref: './TrendingItemsQuery.yml#/trendingItemsQuery'
+    - $ref: './TrendingFacetsQuery.yml#/trendingFacetsQuery'
     - $ref: './RecommendationsQuery.yml#/recommendationsQuery'
+    - $ref: './RecommendedForYouQuery.yml#/recommendedForYouQuery'
 
 baseRecommendRequest:
   type: object

specs/recommend/common/schemas/RecommendationsResponse.yml

@@ -1,16 +1,16 @@
-recommendationsResponse:
+recommendationsResults:
   allOf:
     - $ref: '../../../search/common/schemas/SearchResponse.yml#/baseSearchResponse'
-    - $ref: '#/recommendHits'
+    - $ref: '#/recommendationsHits'
 
-recommendHits:
+recommendationsHits:
   type: object
   additionalProperties: false
   properties:
     hits:
       type: array
       items:
-        $ref: '#/recommendHit'
+        $ref: '#/recommendationsHit'
     query:
       $ref: '../../../common/schemas/SearchParams.yml#/query'    
     params:
@@ -20,6 +20,11 @@ recommendHits:
   required:
     - hits
 
+recommendationsHit:
+  oneOf:
+    - $ref: '#/recommendHit'
+    - $ref: '#/trendingFacetHit'
+
 recommendHit:
   type: object
   description: Recommend hit.
@@ -39,41 +44,26 @@ recommendHit:
     _distinctSeqID:
       $ref: '../../../search/common/schemas/Hit.yml#/_distinctSeqID'
     _score:
-      type: number
-      format: double
-      minimum: 0
-      maximum: 100
-      description: Recommendation score.
+      $ref: '#/recommendScore'
 
-ruleResponse:
+trendingFacetHit:
   type: object
-  description: Rule object.
-  additionalProperties: false
-  properties:
-    _metadata:
-      type: object
-      properties:
-        lastUpdate:
-          $ref: '../../../common/responses/common.yml#/updatedAt'
-    objectID:
-      type: string
-      description: Unique identifier for a rule object.
-      example: 'hide-12345'
-    conditions:
-      type: array
-      description: >
-        [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
-      items:
-        $ref: '../../../search/paths/rules/common/schemas.yml#/condition'
-    consequence:
-      $ref: '../../../search/paths/rules/common/schemas.yml#//consequence'
-    description:
-      type: string
-      description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
-      example: 'Display a promotional banner'
-    enabled:
-      type: boolean
-      default: true
-      description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+  description: Trending facet hit.
   required:
-    - objectID
+    - _score
+    - facetName
+    - facetValue
+  properties:
+    _score:
+      $ref: '#/recommendScore'
+    facetName:
+      $ref: '../parameters.yml#/facetName'
+    facetValue:
+      $ref: '../parameters.yml#/facetValue'
+
+recommendScore:
+  type: number
+  format: double
+  minimum: 0
+  maximum: 100
+  description: Recommendation score.

specs/recommend/common/schemas/RecommendedForYouQuery.yml

@@ -0,0 +1,35 @@
+recommendedForYouQuery:
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseRecommendedForYouQuery'
+
+recommendedForYouQueryParameters:
+  allOf:
+    - $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    - $ref: '#/baseRecommendedForYouQueryParameters'
+
+baseRecommendedForYouQueryParameters:
+  type: object
+  properties:
+    userToken:
+      $ref: '../../../common/schemas/SearchParams.yml#/userToken'
+  required:
+    - userToken
+
+baseRecommendedForYouQuery:
+  type: object
+  additionalProperties: false
+  properties:
+    model:
+      $ref: '#/recommendedForYouModel'
+    queryParameters:
+      $ref: '#/recommendedForYouQueryParameters'
+    fallbackParameters:
+      $ref: '#/recommendedForYouQueryParameters'
+  required:
+    - model
+
+recommendedForYouModel:
+  description: Recommended for you model.
+  type: string
+  enum: [recommended-for-you]

specs/recommend/common/schemas/RuleResponse.yml

@@ -0,0 +1,31 @@
+type: object
+description: Rule object.
+additionalProperties: false
+properties:
+  _metadata:
+    type: object
+    properties:
+      lastUpdate:
+        $ref: '../../../common/responses/common.yml#/updatedAt'
+  objectID:
+    type: string
+    description: Unique identifier for a rule object.
+    example: 'hide-12345'
+  conditions:
+    type: array
+    description: >
+      [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
+    items:
+      $ref: '../../../search/paths/rules/common/schemas.yml#/condition'
+  consequence:
+    $ref: '../../../search/paths/rules/common/schemas.yml#//consequence'
+  description:
+    type: string
+    description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
+    example: 'Display a promotional banner'
+  enabled:
+    type: boolean
+    default: true
+    description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+required:
+  - objectID

specs/recommend/common/schemas/TrendingFacetsQuery.yml

@@ -0,0 +1,20 @@
+trendingFacetsQuery:
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseTrendingFacetsQuery'
+
+baseTrendingFacetsQuery:
+  type: object
+  additionalProperties: false
+  properties:
+    facetName:
+      $ref: '../parameters.yml#/facetName'
+    model:
+      $ref: '#/trendingFacetsModel'
+  required:
+    - facetName
+
+trendingFacetsModel:
+  description: Trending facets model.
+  type: string
+  enum: [trending-facets]

specs/recommend/common/schemas/TrendingItemsQuery.yml

@@ -0,0 +1,24 @@
+trendingItemsQuery:
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/baseTrendingItemsQuery'
+
+baseTrendingItemsQuery:
+  type: object
+  additionalProperties: false
+  properties:
+    facetName:
+      $ref: '../parameters.yml#/facetName'
+    facetValue:
+      $ref: '../parameters.yml#/facetValue'
+    model:
+      $ref: '#/trendingItemsModel'
+    queryParameters:
+      $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    fallbackParameters:
+      $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+
+trendingItemsModel:
+  description: Trending items model.
+  type: string
+  enum: [trending-items]