feat(specs): add recommend batch rules endpoint (#3782)

Co-authored-by: Pierre Millot <pierre.millot@algolia.com>
Co-authored-by: Clément Vannicatte <vannicattec@gmail.com>

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

@@ -106,6 +106,7 @@ public class AlgoliaSwiftGenerator extends Swift5ClientCodegen {
     "supportedlanguage",
     "tagfilters",
     "taskstatus",
+    "timerange",
     "typotolerance",
     "typotoleranceenum",
     "value"

playground/javascript/node/recommend.ts

@@ -10,7 +10,7 @@ const searchQuery = process.env.SEARCH_QUERY || 'test_query';
 // Init client with appId and apiKey
 const client = recommendClient(appId, apiKey);
 
-async function testRecommend() {
+async function testGetRecommendations() {
   try {
     const res = await client.getRecommendations({
       requests: [
@@ -23,14 +23,20 @@ async function testRecommend() {
       ],
     });
 
-    console.log(`[OK]`, res);
+    console.log('[OK] GetRecommendations', res);
   } catch (e) {
     if (e instanceof ApiError) {
       return console.log(`[${e.status}] ${e.message}`, e.stackTrace);
     }
 
-    console.log('[ERROR]', e);
+    console.log('[ERROR] GetRecommendations', e);
   }
 }
 
+
+
+async function testRecommend() {
+  await testGetRecommendations();
+}
+
 testRecommend();

specs/common/schemas/Rule.yml

@@ -6,3 +6,17 @@ context:
     For example, if `context: mobile`, the rule is only triggered when the search request has a matching `ruleContexts: mobile`.
     A rule context must only contain alphanumeric characters.
   example: mobile
+
+timeRange:
+  type: object
+  additionalProperties: false
+  properties:
+    from:
+      type: integer
+      description: When the rule should start to be active, in Unix epoch time.
+    until:
+      type: integer
+      description: When the rule should stop to be active, in Unix epoch time.
+  required:
+    - from
+    - until

specs/recommend/common/responses/RecommendUpdatedAt.yml

@@ -0,0 +1,5 @@
+description: OK
+content:
+  application/json:
+    schema:
+      $ref: './common.yml#/recommendUpdatedAtResponse'

specs/recommend/common/responses/common.yml

@@ -0,0 +1,26 @@
+taskID:
+  type: integer
+  format: int64
+  example: 1514562690001
+  description: |
+    Unique identifier of a task.
+
+    A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the [`task` operation](#tag/Indices/operation/getTask) and this `taskID`.
+
+updatedAt:
+  type: string
+  example: 2023-07-04T12:49:15Z
+  description: Date and time when the object was updated, in RFC 3339 format.
+
+recommendUpdatedAtResponse:
+  type: object
+  description: Response, taskID, and update timestamp.
+  additionalProperties: false
+  required:
+    - taskID
+    - updatedAt
+  properties:
+    taskID:
+      $ref: '#/taskID'
+    updatedAt:
+      $ref: '#/updatedAt'

specs/recommend/common/schemas/RecommendRule.yml

@@ -9,7 +9,7 @@ RecommendRule:
       description: Rule metadata.
       properties:
         lastUpdate:
-          $ref: '../../../common/responses/common.yml#/updatedAt'
+          $ref: '../responses/common.yml#/updatedAt'
     objectID:
       $ref: '../../../common/parameters.yml#/ruleID'
     condition:
@@ -19,11 +19,16 @@ RecommendRule:
     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'
+      example: 'Boost on-sale items'
     enabled:
       type: boolean
       default: true
       description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+    validity:
+      type: array
+      description: Time periods when the rule is active.
+      items:
+        $ref: '../../../common/schemas/Rule.yml#/timeRange'
 
 Condition:
   type: object

specs/recommend/paths/batchRecommendRules.yml

@@ -0,0 +1,38 @@
+post:
+  tags:
+    - rules
+  operationId: batchRecommendRules
+  x-acl:
+    - editSettings
+  summary: Create or update a batch of Recommend Rules
+  description: |
+    Create or update a batch of Recommend Rules
+
+    Each Recommend Rule is created or updated, depending on whether a Recommend Rule with the same `objectID` already exists.
+    You may also specify `true` for `clearExistingRules`, in which case the batch will atomically replace all the existing Recommend Rules.
+
+    Recommend Rules are similar to Search Rules, except that the conditions and consequences apply to a [source item](/doc/guides/algolia-recommend/overview/#recommend-models) instead of a query. The main differences are the following:
+    - Conditions `pattern` and `anchoring` are unavailable.
+    - Condition `filters` triggers if the source item matches the specified filters.
+    - Condition `filters` accepts numeric filters.
+    - Consequence `params` only covers filtering parameters.
+    - Consequence `automaticFacetFilters` doesn't require a facet value placeholder (it tries to match the data source item's attributes instead).
+  parameters:
+    - $ref: '../../common/parameters.yml#/IndexName'
+    - $ref: '../common/parameters.yml#/Models'
+  requestBody:
+    content:
+      application/json:
+        schema:
+          title: rules
+          type: array
+          description: Recommend rules.
+          additionalProperties: false
+          items:
+            $ref: '../common/schemas/RecommendRule.yml#/RecommendRule'
+
+  responses:
+    '200':
+      $ref: '../common/responses/RecommendUpdatedAt.yml'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'

specs/recommend/spec.yml

@@ -131,6 +131,9 @@ paths:
 
   /1/indexes/{indexName}/{model}/recommend/rules/search:
     $ref: 'paths/searchRecommendRules.yml'
+
+  /1/indexes/{indexName}/{model}/recommend/rules/batch:
+    $ref: 'paths/batchRecommendRules.yml'
 
   # ###############
   # ### Helpers ###

templates/javascript/clients/algoliasearch/builds/models.mustache

@@ -13,8 +13,8 @@ import type {
   AroundRadiusAll,
   AutomaticFacetFilter,
   AutomaticFacetFilters,
-  BaseSearchParams,
   BaseIndexSettings,
+  BaseSearchParams,
   BaseSearchParamsWithoutQuery,
   BaseSearchResponse,
   BooleanString,
@@ -43,8 +43,8 @@ import type {
   HighlightResultOption,
   IgnorePlurals,
   IndexSettingsAsSearchParams,
-  MatchLevel,
   MatchedGeoLocation,
+  MatchLevel,
   Mode,
   NumericFilters,
   OptionalFilters,
@@ -56,14 +56,14 @@ import type {
   QueryType,
   Range,
   RankingInfo,
-  ReRankingApplyFilter,
   Redirect,
-  RedirectRuleIndexMetadata,
   RedirectRuleIndexData,
+  RedirectRuleIndexMetadata,
   RedirectURL,
   RemoveStopWords,
   RemoveWordsIfNoResults,
   RenderingContent,
+  ReRankingApplyFilter,
   SearchPagination,
   SearchParams,
   SearchParamsObject,
@@ -75,6 +75,7 @@ import type {
   SupportedLanguage,
   TagFilters,
   TaskStatus,
+  TimeRange,
   TypoTolerance,
   TypoToleranceEnum,
   Value,
@@ -91,16 +92,19 @@ export * from '@algolia/client-analytics';
 export * from '@algolia/client-abtesting';
 
 export {
+  AbTestingRegion,
   AdvancedSyntaxFeatures,
   AlternativesAsExact,
+  AnalyticsRegion,
   Anchoring,
+  apiClientVersion,
   AroundPrecision,
   AroundRadius,
   AroundRadiusAll,
   AutomaticFacetFilter,
   AutomaticFacetFilters,
-  BaseSearchParams,
   BaseIndexSettings,
+  BaseSearchParams,
   BaseSearchParamsWithoutQuery,
   BaseSearchResponse,
   BooleanString,
@@ -129,8 +133,8 @@ export {
   HighlightResultOption,
   IgnorePlurals,
   IndexSettingsAsSearchParams,
-  MatchLevel,
   MatchedGeoLocation,
+  MatchLevel,
   Mode,
   NumericFilters,
   OptionalFilters,
@@ -142,32 +146,30 @@ export {
   QueryType,
   Range,
   RankingInfo,
-  ReRankingApplyFilter,
   Redirect,
-  RedirectRuleIndexMetadata,
   RedirectRuleIndexData,
+  RedirectRuleIndexMetadata,
   RedirectURL,
+  Region,
   RemoveStopWords,
   RemoveWordsIfNoResults,
   RenderingContent,
+  ReRankingApplyFilter,
+  SearchPagination,
   SearchParams,
   SearchParamsObject,
   SearchParamsQuery,
   SemanticSearch,
-  SearchPagination,
   SnippetResult,
   SnippetResultOption,
   SortRemainingBy,
   SupportedLanguage,
   TagFilters,
   TaskStatus,
+  TimeRange,
   TypoTolerance,
   TypoToleranceEnum,
   Value,
-  AnalyticsRegion,
-  AbTestingRegion,
-  Region,
-  apiClientVersion,
 };
 
 /**
@@ -190,4 +192,4 @@ export type InitClientRegion<TRegion> = Partial<{
    * Available regions of the initialized client.
    */
   region: TRegion;
-}>;
+}>;

tests/CTS/requests/recommend/batchRecommendRules.json

@@ -0,0 +1,14 @@
+[
+    {
+        "testName": "batch recommend rules",
+        "parameters": {
+            "indexName": "indexName",
+            "model": "related-products"
+        },
+        "request": {
+            "path": "/1/indexes/indexName/related-products/recommend/rules/batch",
+            "method": "POST",
+            "body": {}
+        }
+    }
+]