feat(javascript): add waitForApiKey helper method

Author: shortcuts

templates/javascript/api-single.mustache

@@ -18,7 +18,7 @@ export function create{{capitalizedApiName}}({
     hosts: getDefaultHosts({{^hasRegionalHost}}appIdOption{{/hasRegionalHost}}{{#hasRegionalHost}}regionOption{{/hasRegionalHost}}),
     ...options,
     algoliaAgent: getAlgoliaAgent({
-      algoliaAgents: algoliaAgents,
+      algoliaAgents,
       client: '{{{algoliaAgent}}}',
       version: apiClientVersion,
     }),
@@ -39,32 +39,7 @@ export function create{{capitalizedApiName}}({
 
   return {
     addAlgoliaAgent,
-    {{#isSearchClient}}
-    /**
-     * Wait for a task to complete with `indexName` and `taskID`.
-     *
-     * @summary Wait for a task to complete.
-     * @param waitForTaskProps - The waitForTaskProps object.
-     * @param waitForTaskProps.indexName - The index in which to perform the request.
-     * @param waitForTaskProps.taskID - The unique identifier of the task to wait for.
-     */
-    waitForTask({
-      indexName,
-      taskID,
-      ...createRetryablePromiseOptions,
-    }: {
-      indexName: string;
-      taskID: number;
-    } & Omit<CreateRetryablePromiseOptions<GetTaskResponse>, 'func' | 'validate'>): Promise<void> {
-      return new Promise<void>((resolve, reject) => {
-        createRetryablePromise<GetTaskResponse>({
-          ...createRetryablePromiseOptions,
-          func: () => this.getTask({ indexName, taskID }),
-          validate: (response) => response.status === 'published',
-        }).then(() => resolve()).catch(reject);
-      });
-    },
-    {{/isSearchClient}}
+    {{#isSearchClient}}{{> api/helpers}}{{/isSearchClient}}
     {{#operation}}
     {{> api/operation/jsdoc}}
     {{nickname}}( {{> api/operation/parameters}} ) : Promise<{{{returnType}}}> {

templates/javascript/api/helpers.mustache

@@ -0,0 +1,66 @@
+/**
+ * Helper: Wait for a task to complete with `indexName` and `taskID`.
+ *
+ * @summary Wait for a task to complete.
+ * @param waitForTaskOptions - The waitForTaskOptions object.
+ * @param waitForTaskOptions.indexName - The `indexName` where the operation was performed.
+ * @param waitForTaskOptions.taskID - The `taskID` returned in the method response.
+ */
+waitForTask({
+  indexName,
+  taskID,
+  ...createRetryablePromiseOptions
+}: WaitForTaskOptions): Promise<GetTaskResponse> {
+  return createRetryablePromise({
+    ...createRetryablePromiseOptions,
+    func: () => this.getTask({ indexName, taskID }),
+    validate: (response) => response.status === 'published',
+  });
+},
+/**
+ * Helper: Wait for an API key to be valid, updated or deleted based on a given `operation`.
+ *
+ * @summary Wait for an API key task to be processed.
+ * @param waitForApiKeyOptions - The waitForApiKeyOptions object.
+ * @param waitForApiKeyOptions.operation - The `operation` that was done on a `key`.
+ * @param waitForApiKeyOptions.key - The `key` that has been added, deleted or updated.
+ * @param waitForApiKeyOptions.apiKey - Necessary to know if an `update` operation has been processed, compare fields of the response with it.
+ */
+waitForApiKey({
+  operation,
+  key,
+  apiKey,
+  ...createRetryablePromiseOptions
+}: WaitForApiKeyOptions): Promise<ApiError | Key> {
+  if (operation === 'update') {
+    const validate = (response: ApiKey): boolean => {
+      for (const [entry, values] of Object.entries(apiKey)) {
+        if (Array.isArray(values)) {
+          if (
+            values.length === response[entry].length &&
+            values.every((val, index) => val === response[entry][index])
+          ) {
+            return true;
+          }
+        } else if (values === response[entry]) {
+          return true;
+        }
+      }
+
+      return false;
+    };
+
+    return createRetryablePromise({
+      ...createRetryablePromiseOptions,
+      func: () => this.getApiKey({ key }),
+      validate,
+    });
+  }
+
+  return createRetryablePromise({
+    ...createRetryablePromiseOptions,
+    func: () => this.getApiKey({ key }).catch((error) => error),
+    validate: (error: ApiError) =>
+      operation === 'add' ? error.status !== 404 : error.status === 404,
+  });
+},

templates/javascript/api/imports.mustache

@@ -15,7 +15,7 @@ import type {
   RequestOptions,
   QueryParameters,
   {{#isSearchClient}}
-  CreateRetryablePromiseOptions,
+  ApiError,
   {{/isSearchClient}}
 } from '{{{npmNamespace}}}/client-common';
 
@@ -25,6 +25,10 @@ import { {{classname}} } from '{{filename}}';
 
 {{#operations}}
 import type {
+  {{#isSearchClient}}
+    WaitForTaskOptions,
+    WaitForApiKeyOptions,
+  {{/isSearchClient}}
   {{#operation}}
     {{#vendorExtensions}}
       {{#x-create-wrapping-object}}

templates/javascript/clientMethodProps.mustache

@@ -7,6 +7,9 @@ import { {{classname}} } from '{{filename}}';
 {{! Imports for the legacy search method signature }}
 {{#operations}}{{#operation}}{{#vendorExtensions.x-legacy-signature}}{{> api/operation/legacySearchCompatible/imports}}{{/vendorExtensions.x-legacy-signature}}{{/operation}}{{/operations}}
 
+{{! Imports for the helpers method of the search client }}
+{{#isSearchClient}}import type { CreateRetryablePromiseOptions } from '@experimental-api-clients-automation/client-common';{{/isSearchClient}}
+
 {{#operations}}
 {{#operation}}
 
@@ -33,4 +36,48 @@ export type {{#lambda.titlecase}}{{nickname}}{{/lambda.titlecase}}Props = {
 
 {{/operation}}
 {{/operations}}
+
+{{#isSearchClient}}
+type WaitForOptions<T> = Omit<
+  CreateRetryablePromiseOptions<T>,
+  'func' | 'validate'
+>;
+
+export type WaitForTaskOptions = WaitForOptions<GetTaskResponse> & {
+  /**
+   * The `indexName` where the operation was performed.
+   */
+  indexName: string;
+  /**
+   * The `taskID` returned by the method response.
+   */
+  taskID: number;
+};
+
+export type WaitForApiKeyOptions = WaitForOptions<Key> & {
+  /**
+   * The API Key.
+   */
+  key: string;
+} & (
+    | {
+        /**
+         * The operation that has been performed, used to compute the stop condition.
+         */
+        operation: 'add' | 'delete';
+        apiKey?: never;
+      }
+    | {
+        /**
+         * The operation that has been performed, used to compute the stop condition.
+         */
+        operation: 'update';
+        /**
+         * The updated fields, used to compute the stop condition.
+         */
+        apiKey: Partial<ApiKey>;
+      }
+  );
+{{/isSearchClient}}
+
 {{/apiInfo.apis.0}}

website/docs/clients/guides/copy-index-to-another-application.md

@@ -1,5 +1,5 @@
 ---
-title: Copy or move an index
+title: Copy an index to another application
 ---
 
 :::caution

website/docs/clients/guides/wait-for-api-key-to-be-valid.mdx

@@ -0,0 +1,43 @@
+---
+title: Wait for an API key to be valid
+---
+
+import { TabsLanguage } from '../../../src/components/TabsLanguage';
+import TabItem from '@theme/TabItem';
+
+> The `waitForApiKey` method is only available in the `search` client context.
+
+Adding, updating or deleting API keys is not always instantaneous, which is why you might want to ensure the job has been processed before jumping to an other task.
+
+We provide a `waitForApiKey` helper method for you to easily wait for a specific `operation` made on a `key`.
+
+> An `operation` can either be `add` | `update` | `delete`
+
+<TabsLanguage>
+<TabItem value="javascript">
+
+```js
+import { algoliasearch } from '@experimental-api-clients-automation/algoliasearch';
+
+const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
+
+const { key } = await client.addApiKey({
+  acl: ['analytics', 'browse', 'editSettings'],
+});
+
+// Poll the task status with defaults values
+await client.waitForApiKey({ operation: 'add', key });
+
+// Poll the task status with your options
+await client.waitForTask({
+  operation: 'add',
+  key,
+  // Number of maximum retries to do
+  maxRetries: 100,
+  // The time to wait between tries
+  timeout: (retryCount: number): number => Math.min(retryCount * 200, 5000),
+});
+```
+
+</TabItem>
+</TabsLanguage>

website/sidebars.js

@@ -79,6 +79,7 @@ const sidebars = {
         'clients/guides/retrieving-facets',
         'clients/guides/customized-client-usage',
         'clients/guides/wait-for-a-task-to-finish',
+        'clients/guides/wait-for-api-key-to-be-valid',
         'clients/guides/copy-or-move-index',
         'clients/guides/copy-index-to-another-application',
       ],