fix(specs): recommend api (#2958)

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

clients/algoliasearch-client-dart/packages/client_recommend/example/example.dart

@@ -9,15 +9,15 @@ void main() async {
 
   // Creating recommendation requests for different products.
   var requests = [
-    RecommendationsQuery(
-      model: RecommendationModels.relatedProducts,
+    RelatedQuery(
+      model: RelatedModel.relatedProducts,
       objectID: '6445156',
       indexName: 'instant_search',
       threshold: 70,
       maxRecommendations: 3,
     ),
-    RecommendationsQuery(
-      model: RecommendationModels.relatedProducts,
+    RelatedQuery(
+      model: RelatedModel.relatedProducts,
       objectID: '6443034',
       indexName: 'instant_search',
       threshold: 70,

specs/common/parameters.yml

@@ -14,8 +14,7 @@ ObjectID:
   description: Unique record identifier.
   required: true
   schema:
-    type: string
-    example: '123'
+    $ref: '#/objectID'
 
 # query
 Index:
@@ -123,6 +122,7 @@ Limit:
 objectID:
   type: string
   description: Unique record identifier.
+  example: test-record-123
 
 ruleID:
   title: objectID

specs/common/schemas/SearchParams.yml

@@ -397,9 +397,9 @@ listOfSearchFilters:
 filters:
   type: string
   description: |
-    Filter the search so that only records with matching values are included in the results.
+    Filter expression to only include items that match the filter criteria in the response.
 
-    These filters are supported:
+    You can use these filter expressions:
 
     - **Numeric filters.** `<facet> <op> <number>`, where `<op>` is one of `<`, `<=`, `=`, `!=`, `>`, `>=`.
     - **Ranges.** `<facet>:<lower> TO <upper>` where `<lower>` and `<upper>` are the lower and upper limits of the range (inclusive).
@@ -421,7 +421,6 @@ filters:
 
     For more information, see [Filters](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/).
   example: '(category:Book OR category:Ebook) AND _tags:published'
-  default: ''
   x-categories:
     - Filtering
 

specs/common/securitySchemes.yml

@@ -1,8 +1,13 @@
 appId:
   type: apiKey
   in: header
-  name: X-Algolia-Application-Id
+  name: x-algolia-application-id
+  description: Your Algolia application ID.
 apiKey:
   type: apiKey
   in: header
-  name: X-Algolia-API-Key
+  name: x-algolia-api-key
+  description: |
+    Your Algolia API key with the necessary permissions to make the request.
+    Permissions are controlled through access control lists (ACL) and access restrictions.
+    The required ACL to make a request is listed in each endpoint's reference.

specs/recommend/common/parameters.yml

@@ -2,11 +2,12 @@ Models:
   in: path
   name: model
   required: true
-  description: >
-    [Recommend models](https://www.algolia.com/doc/guides/algolia-recommend/overview/#recommend-models).
+  description: |
+    [Recommend model](https://www.algolia.com/doc/guides/algolia-recommend/overview/#recommend-models).
   schema:
     $ref: '#/recommendModels'
 
+# This list excludes `looking-similar` as that can't be used with rules.
 recommendModels:
   type: string
   enum: [related-products, bought-together, trending-facets, trending-items]
@@ -15,14 +16,19 @@ ObjectID:
   in: path
   name: objectID
   required: true
-  type: string
-  description: Unique Recommend rule identifier.
+  description: Unique identifier of a Recommend rule object.
   example: 'a-recommend-rule-id'
+  schema:
+    $ref: '../../common/parameters.yml#/ruleID'
 
 facetName:
   type: string
-  description: Facet name for trending models.
+  description: |
+    Facet attribute. To be used in combination with `facetValue`.
+    If specified, only recommendations matching the facet filter will be returned.
 
 facetValue:
   type: string
-  description: Facet value for trending models.
+  description: |
+    Facet value. To be used in combination with `facetName`.
+    If specified, only recommendations matching the facet filter will be returned.

specs/recommend/common/schemas/FrequentlyBoughtTogetherQuery.yml

@@ -0,0 +1,24 @@
+boughtTogetherQuery:
+  title: Frequently bought together
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/frequentlyBoughtTogether'
+
+frequentlyBoughtTogether:
+  type: object
+  properties:
+    model:
+      $ref: '#/fbtModel'
+    objectID:
+      $ref: '../../../common/parameters.yml#/objectID'
+  required:
+    - model
+    - objectID
+
+fbtModel:
+  type: string
+  description: |
+    Frequently bought together model.
+
+    This model recommends items that have been purchased within 1 day with the item with the ID `objectID`.
+  enum: [bought-together]

specs/recommend/common/schemas/LookingSimilarQuery.yml

@@ -0,0 +1,26 @@
+lookingSimilarQuery:
+  title: Looking similar
+  allOf:
+    - $ref: './RecommendationsRequest.yml#/baseRecommendRequest'
+    - $ref: '#/lookingSimilar'
+
+lookingSimilar:
+  type: object
+  properties:
+    model:
+      $ref: '#/lookingSimilarModel'
+    objectID:
+      $ref: '../../../common/parameters.yml#/objectID'
+    fallbackParameters:
+      $ref: './RecommendationsRequest.yml#/fallbackParams'
+  required:
+    - model
+    - objectID
+
+lookingSimilarModel:
+  type: string
+  description: |
+    Looking similar model.
+
+    This model recommends items that look similar to the item with the ID `objectID` based on image attributes in your index.
+  enum: [looking-similar]

specs/recommend/common/schemas/RecommendRule.yml

@@ -0,0 +1,119 @@
+RecommendRule:
+  type: object
+  description: Recommend rule.
+  additionalProperties: false
+  properties:
+    _metadata:
+      type: object
+      description: Rule metadata.
+      properties:
+        lastUpdate:
+          $ref: '../../../common/responses/common.yml#/updatedAt'
+    objectID:
+      $ref: '../../../common/parameters.yml#/ruleID'
+    condition:
+      $ref: '#/Condition'
+    consequence:
+      $ref: '#/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.
+
+Condition:
+  type: object
+  description: |
+    Condition that triggers the rule.
+    If not specified, the rule is triggered for all recommendations.
+  properties:
+    filters:
+      $ref: '../../../common/schemas/SearchParams.yml#/filters'
+    context:
+      $ref: '../../../search/paths/rules/common/schemas.yml#/context'
+
+Consequence:
+  type: object
+  description: Effect of the rule.
+  properties:
+    hide:
+      $ref: '#/HideConsequence'
+    promote:
+      $ref: '#/PromoteConsequence'
+    params:
+      $ref: '#/ParamsConsequence'
+
+HideConsequence:
+  type: array
+  description: Exclude items from recommendations.
+  minItems: 1
+  items:
+    $ref: '#/HideConsequenceObject'
+
+HideConsequenceObject:
+  type: object
+  description: Object ID of the recommendation you want to exclude.
+  properties:
+    objectID:
+      $ref: '../../../common/parameters.yml#/objectID'
+
+PromoteConsequence:
+  type: array
+  description: Place items at specific positions in the list of recommendations.
+  minItems: 1
+  items:
+    $ref: '#/PromoteConsequenceObject'
+
+PromoteConsequenceObject:
+  type: object
+  description: Object ID and position of the recommendation you want to pin.
+  properties:
+    objectID:
+      $ref: '../../../common/parameters.yml#/objectID'
+    position:
+      type: integer
+      description: Index in the list of recommendations where to place this item.
+      minimum: 0
+
+ParamsConsequence:
+  type: object
+  description: Filter or boost recommendations matching a facet filter.
+  properties:
+    automaticFacetFilters:
+      type: array
+      description: Filter recommendations that match or don't match the same `facet:facet_value` combination as the viewed item.
+      items:
+        $ref: '#/AutoFacetFilter'
+    filters:
+      $ref: '../../../common/schemas/SearchParams.yml#/filters'
+    optionalFilters:
+      type: array
+      description: |
+        Filters to promote or demote records in the search results.
+
+        Optional filters work like facet filters, but they don't exclude records from the search results.
+        Records that match the optional filter rank before records that don't match.
+        Matches with higher weights (`<score=N>`) rank before matches with lower weights.
+        If you're using a negative filter `facet:-value`, matching records rank after records that don't match.
+      items:
+        type: string
+      example:
+        - 'category:books<score=1>'
+        - 'category:-movies<score=1>'
+
+AutoFacetFilter:
+  type: object
+  description: Facet attribute. Only recommendations with the same value (or only recommendations with a different value) as the original viewed item are included.
+  properties:
+    facet:
+      type: string
+      description: Facet attribute.
+    negative:
+      type: boolean
+      description: |
+        Whether the filter is negative.
+        If true, recommendations must not have the same value for the `facet` attribute.
+        If false, recommendations must have the same value for the `facet` attribute.

specs/recommend/common/schemas/RecommendationsRequest.yml

@@ -1,8 +1,10 @@
 recommendationsRequest:
   oneOf:
+    - $ref: './FrequentlyBoughtTogetherQuery.yml#/boughtTogetherQuery'
+    - $ref: './RelatedQuery.yml#/relatedQuery'
     - $ref: './TrendingItemsQuery.yml#/trendingItemsQuery'
     - $ref: './TrendingFacetsQuery.yml#/trendingFacetsQuery'
-    - $ref: './RecommendationsQuery.yml#/recommendationsQuery'
+    - $ref: './LookingSimilarQuery.yml#/lookingSimilarQuery'
     - $ref: './RecommendedForYouQuery.yml#/recommendedForYouQuery'
 
 baseRecommendRequest:
@@ -12,16 +14,38 @@ baseRecommendRequest:
     indexName:
       $ref: '../../../common/parameters.yml#/indexName'
     threshold:
-      type: integer
+      type: number
+      format: double
       minimum: 0
       maximum: 100
-      description: >
-        Recommendations with a confidence score lower than `threshold` won't appear in results.
-
-        > **Note**: Each recommendation has a confidence score of 0 to 100. The closer the score is to 100, the more relevant the recommendations are.
+      description: Minimum score a recommendation must have to be included in the response.
     maxRecommendations:
       type: integer
-      default: 0
-      description: Maximum number of recommendations to retrieve. If 0, all recommendations will be returned.
+      minimum: 1
+      maximum: 1000
+      default: 30
+      description: |
+        Maximum number of recommendations to retrieve.
+        By default, all recommendations are returned and no fallback request is made.
+        Depending on the available recommendations and the other request parameters,
+        the actual number of recommendations may be lower than this value.
+    queryParameters:
+      $ref: '#/searchParams'
   required:
     - indexName
+    - threshold
+
+searchParams:
+  title: queryParameters
+  allOf:
+    # TODO: This isn't correct. `page`, `hitsPerPage`, `offset`, and `length` aren't allowed
+    - $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    - type: object
+      description: Search parameters for filtering the recommendations.
+
+fallbackParams:
+  title: fallbackParameters
+  allOf:
+    - $ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
+    - type: object
+      description: Search parameters to use for a fallback request if there aren't enough recommendations.

specs/recommend/common/schemas/RecommendationsResponse.yml

@@ -1,5 +1,6 @@
 recommendationsResults:
   allOf:
+    # TODO: this isn't correct. Not all elements of the Search response are included for Recommend.
     - $ref: '../../../search/common/schemas/SearchResponse.yml#/baseSearchResponse'
     - $ref: '#/recommendationsHits'
 
@@ -11,12 +12,6 @@ recommendationsHits:
       type: array
       items:
         $ref: '#/recommendationsHit'
-    query:
-      $ref: '../../../common/schemas/SearchParams.yml#/query'    
-    params:
-      type: string
-      description: URL-encoded string of all search parameters.
-      example: query=a&hitsPerPage=20     
   required:
     - hits