feat(javascript): add bridge to transformation on algoliasearch (generated)

algolia/api-clients-automation#4852

Co-authored-by: algolia-bot <[email protected]>
Co-authored-by: Clément Vannicatte <[email protected]>

Author: algolia-bot

packages/algoliasearch/__tests__/algoliasearch.common.test.ts

@@ -143,131 +143,110 @@ describe('api', () => {
     });
   });
 
-  describe('init clients', () => {
-    test('provides an init method for the analytics client', () => {
-      expect(client.initAnalytics).not.toBeUndefined();
-    });
-
-    test('provides an init method for the abtesting client', () => {
-      expect(client.initAbtesting).not.toBeUndefined();
+  describe('bridge methods', () => {
+    test('throws when missing transformation.region', () => {
+      //@ts-expect-error
+      expect(() => algoliasearch('APP_ID', 'API_KEY', { transformation: {} })).toThrow(
+        '`region` must be provided when leveraging the transformation pipeline',
+      );
     });
 
-    test('provides an init method for the personalization client', () => {
-      expect(client.initPersonalization).not.toBeUndefined();
-    });
+    test('throws when calling the transformation methods without init parameters', async () => {
+      await expect(
+        client.saveObjectsWithTransformation({
+          indexName: 'foo',
+          objects: [{ objectID: 'bar', baz: 42 }],
+          waitForTasks: true,
+        }),
+      ).rejects.toThrow('`transformation.region` must be provided at client instantiation before calling this method.');
 
-    test('provides an init method for the recommend client', () => {
-      expect(client.initRecommend).not.toBeUndefined();
+      await expect(
+        client.partialUpdateObjectsWithTransformation({
+          indexName: 'foo',
+          objects: [{ objectID: 'bar', baz: 42 }],
+          waitForTasks: true,
+        }),
+      ).rejects.toThrow('`transformation.region` must be provided at client instantiation before calling this method.');
     });
 
-    test('default `init` clients to the root `algoliasearch` credentials', async () => {
-      const abtestingClient = client.initAbtesting({ options: { requester: browserEchoRequester() } });
-      const analyticsClient = client.initAnalytics({ options: { requester: browserEchoRequester() } });
-      const recommendClient = client.initRecommend({ options: { requester: browserEchoRequester() } });
-      const personalizationClient = client.initPersonalization({
-        region: 'eu',
-        options: { requester: browserEchoRequester() },
+    test('exposes the transformation methods at the root of the client', async () => {
+      const ingestionClient = algoliasearch('APP_ID', 'API_KEY', {
+        requester: browserEchoRequester(),
+        transformation: { region: 'us' },
       });
 
-      const res1 = (await abtestingClient.customGet({
-        path: 'abtestingClient',
-      })) as unknown as EchoResponse;
-      const res2 = (await analyticsClient.customGet({
-        path: 'analyticsClient',
-      })) as unknown as EchoResponse;
-      const res3 = (await personalizationClient.customGet({
-        path: 'personalizationClient',
-      })) as unknown as EchoResponse;
-      const res4 = (await recommendClient.customGet({
-        path: 'recommendClient',
+      expect(ingestionClient.saveObjectsWithTransformation).not.toBeUndefined();
+
+      let res = (await ingestionClient.saveObjectsWithTransformation({
+        indexName: 'foo',
+        objects: [{ objectID: 'bar', baz: 42 }],
+        waitForTasks: true,
       })) as unknown as EchoResponse;
 
-      expect(res1.headers).toEqual(
-        expect.objectContaining({
-          'x-algolia-application-id': 'APP_ID',
-          'x-algolia-api-key': 'API_KEY',
-        }),
-      );
-      expect(res2.headers).toEqual(
+      expect(res.headers).toEqual(
         expect.objectContaining({
           'x-algolia-application-id': 'APP_ID',
           'x-algolia-api-key': 'API_KEY',
         }),
       );
-      expect(res3.headers).toEqual(
-        expect.objectContaining({
-          'x-algolia-application-id': 'APP_ID',
-          'x-algolia-api-key': 'API_KEY',
-        }),
-      );
-      expect(res4.headers).toEqual(
+      expect(res.url.startsWith('https://data.us.algolia.com/1/push/foo?watch=true')).toBeTruthy();
+      expect(res.data).toEqual({
+        action: 'addObject',
+        records: [
+          {
+            baz: 42,
+            objectID: 'bar',
+          },
+        ],
+      });
+      expect(ingestionClient.partialUpdateObjectsWithTransformation).not.toBeUndefined();
+
+      res = (await ingestionClient.partialUpdateObjectsWithTransformation({
+        indexName: 'foo',
+        objects: [{ objectID: 'bar', baz: 42 }],
+        waitForTasks: true,
+        createIfNotExists: true,
+      })) as unknown as EchoResponse;
+
+      expect(res.headers).toEqual(
         expect.objectContaining({
           'x-algolia-application-id': 'APP_ID',
           'x-algolia-api-key': 'API_KEY',
         }),
       );
-    });
-
-    test('`init` clients accept different credentials', async () => {
-      const abtestingClient = client.initAbtesting({
-        appId: 'appId1',
-        apiKey: 'apiKey1',
-        options: { requester: browserEchoRequester() },
-      });
-      const analyticsClient = client.initAnalytics({
-        appId: 'appId2',
-        apiKey: 'apiKey2',
-        options: { requester: browserEchoRequester() },
-      });
-      const personalizationClient = client.initPersonalization({
-        appId: 'appId3',
-        apiKey: 'apiKey3',
-        region: 'eu',
-        options: { requester: browserEchoRequester() },
-      });
-      const recommendClient = client.initRecommend({
-        appId: 'appId4',
-        apiKey: 'apiKey4',
-        options: { requester: browserEchoRequester() },
+      expect(res.url.startsWith('https://data.us.algolia.com/1/push/foo?watch=true')).toBeTruthy();
+      expect(res.data).toEqual({
+        action: 'partialUpdateObject',
+        records: [
+          {
+            baz: 42,
+            objectID: 'bar',
+          },
+        ],
       });
 
-      const res1 = (await abtestingClient.customGet({
-        path: 'abtestingClient',
-      })) as unknown as EchoResponse;
-      const res2 = (await analyticsClient.customGet({
-        path: 'analyticsClient',
-      })) as unknown as EchoResponse;
-      const res3 = (await personalizationClient.customGet({
-        path: 'personalizationClient',
-      })) as unknown as EchoResponse;
-      const res4 = (await recommendClient.customGet({
-        path: 'recommendClient',
+      res = (await ingestionClient.partialUpdateObjectsWithTransformation({
+        indexName: 'foo',
+        objects: [{ objectID: 'bar', baz: 42 }],
+        waitForTasks: true,
       })) as unknown as EchoResponse;
 
-      expect(res1.headers).toEqual(
-        expect.objectContaining({
-          'x-algolia-application-id': 'appId1',
-          'x-algolia-api-key': 'apiKey1',
-        }),
-      );
-      expect(res2.headers).toEqual(
-        expect.objectContaining({
-          'x-algolia-application-id': 'appId2',
-          'x-algolia-api-key': 'apiKey2',
-        }),
-      );
-      expect(res3.headers).toEqual(
+      expect(res.headers).toEqual(
         expect.objectContaining({
-          'x-algolia-application-id': 'appId3',
-          'x-algolia-api-key': 'apiKey3',
-        }),
-      );
-      expect(res4.headers).toEqual(
-        expect.objectContaining({
-          'x-algolia-application-id': 'appId4',
-          'x-algolia-api-key': 'apiKey4',
+          'x-algolia-application-id': 'APP_ID',
+          'x-algolia-api-key': 'API_KEY',
         }),
       );
+      expect(res.url.startsWith('https://data.us.algolia.com/1/push/foo?watch=true')).toBeTruthy();
+      expect(res.data).toEqual({
+        action: 'partialUpdateObjectNoCreate',
+        records: [
+          {
+            baz: 42,
+            objectID: 'bar',
+          },
+        ],
+      });
     });
   });
 });

packages/algoliasearch/builds/browser.ts

@@ -1,6 +1,6 @@
 // Code generated by OpenAPI Generator (https://openapi-generator.tech), manual changes will be lost - read more on https://github.com/algolia/api-clients-automation. DO NOT EDIT.
 
-import type { ClientOptions } from '@algolia/client-common';
+import type { ClientOptions, RequestOptions } from '@algolia/client-common';
 
 import type { AbtestingClient } from '@algolia/client-abtesting';
 import { abtestingClient } from '@algolia/client-abtesting';
@@ -21,9 +21,13 @@ import { monitoringClient } from '@algolia/monitoring';
 import type { RecommendClient } from '@algolia/recommend';
 import { recommendClient } from '@algolia/recommend';
 
+import type { PartialUpdateObjectsOptions, SaveObjectsOptions } from '@algolia/client-search';
+import type { PushTaskRecords, WatchResponse } from '@algolia/ingestion';
+
 import type {
   AbtestingRegionOptions,
   AnalyticsRegionOptions,
+  IngestionRegion,
   IngestionRegionOptions,
   InitClientOptions,
   InsightsRegionOptions,
@@ -42,9 +46,56 @@ export type Algoliasearch = SearchClient & {
   initPersonalization: (initOptions: InitClientOptions & PersonalizationRegionOptions) => PersonalizationClient;
   initQuerySuggestions: (initOptions: InitClientOptions & QuerySuggestionsRegionOptions) => QuerySuggestionsClient;
   initRecommend: (initOptions?: InitClientOptions) => RecommendClient;
+
+  // Bridge helpers to expose along with the search endpoints at the root of the API client
+
+  /**
+   * Helper: Similar to the `saveObjects` method but requires a Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/) to be created first, in order to transform records before indexing them to Algolia. The `region` must've been passed to the client instantiation method.
+   *
+   * @summary Save objects to an Algolia index by leveraging the Transformation pipeline setup in the Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/).
+   * @param saveObjects - The `saveObjects` object.
+   * @param saveObjects.indexName - The `indexName` to save `objects` in.
+   * @param saveObjects.objects - The array of `objects` to store in the given Algolia `indexName`.
+   * @param saveObjects.batchSize - The size of the chunk of `objects`. The number of `batch` calls will be equal to `length(objects) / batchSize`. Defaults to 1000.
+   * @param saveObjects.waitForTasks - Whether or not we should wait until every `batch` tasks has been processed, this operation may slow the total execution time of this method but is more reliable.
+   * @param requestOptions - The requestOptions to send along with the query, they will be forwarded to the `batch` method and merged with the transporter requestOptions.
+   */
+  saveObjectsWithTransformation: (
+    options: SaveObjectsOptions,
+    requestOptions?: RequestOptions,
+  ) => Promise<WatchResponse>;
+
+  /**
+   * Helper: Similar to the `partialUpdateObjects` method but requires a Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/) to be created first, in order to transform records before indexing them to Algolia. The `region` must've been passed to the client instantiation method.
+   *
+   * @summary Save objects to an Algolia index by leveraging the Transformation pipeline setup in the Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/).
+   * @param partialUpdateObjects - The `partialUpdateObjects` object.
+   * @param partialUpdateObjects.indexName - The `indexName` to update `objects` in.
+   * @param partialUpdateObjects.objects - The array of `objects` to update in the given Algolia `indexName`.
+   * @param partialUpdateObjects.createIfNotExists - To be provided if non-existing objects are passed, otherwise, the call will fail..
+   * @param partialUpdateObjects.batchSize - The size of the chunk of `objects`. The number of `batch` calls will be equal to `length(objects) / batchSize`. Defaults to 1000.
+   * @param partialUpdateObjects.waitForTasks - Whether or not we should wait until every `batch` tasks has been processed, this operation may slow the total execution time of this method but is more reliable.
+   * @param requestOptions - The requestOptions to send along with the query, they will be forwarded to the `getTask` method and merged with the transporter requestOptions.
+   */
+  partialUpdateObjectsWithTransformation: (
+    options: PartialUpdateObjectsOptions,
+    requestOptions?: RequestOptions,
+  ) => Promise<WatchResponse>;
+};
+
+export type TransformationOptions = {
+  // When provided, a second transporter will be created in order to leverage the `*WithTransformation` methods exposed by the Push connector (https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/).
+  transformation?: {
+    // The region of your Algolia application ID, used to target the correct hosts of the transformation service.
+    region: IngestionRegion;
+  };
 };
 
-export function algoliasearch(appId: string, apiKey: string, options?: ClientOptions): Algoliasearch {
+export function algoliasearch(
+  appId: string,
+  apiKey: string,
+  options?: ClientOptions & TransformationOptions,
+): Algoliasearch {
   if (!appId || typeof appId !== 'string') {
     throw new Error('`appId` is missing.');
   }
@@ -55,9 +106,66 @@ export function algoliasearch(appId: string, apiKey: string, options?: ClientOpt
 
   const client = searchClient(appId, apiKey, options);
 
+  let ingestionTransporter: IngestionClient | undefined;
+
+  if (options?.transformation) {
+    if (!options.transformation.region) {
+      throw new Error('`region` must be provided when leveraging the transformation pipeline');
+    }
+
+    ingestionTransporter = ingestionClient(appId, apiKey, options.transformation.region, options);
+  }
+
   return {
     ...client,
 
+    async saveObjectsWithTransformation({ indexName, objects, waitForTasks }, requestOptions): Promise<WatchResponse> {
+      if (!ingestionTransporter) {
+        throw new Error('`transformation.region` must be provided at client instantiation before calling this method.');
+      }
+
+      if (!options?.transformation?.region) {
+        throw new Error('`region` must be provided when leveraging the transformation pipeline');
+      }
+
+      return ingestionTransporter?.push(
+        {
+          indexName,
+          watch: waitForTasks,
+          pushTaskPayload: {
+            action: 'addObject',
+            records: objects as PushTaskRecords[],
+          },
+        },
+        requestOptions,
+      );
+    },
+
+    async partialUpdateObjectsWithTransformation(
+      { indexName, objects, createIfNotExists, waitForTasks },
+      requestOptions,
+    ): Promise<WatchResponse> {
+      if (!ingestionTransporter) {
+        throw new Error('`transformation.region` must be provided at client instantiation before calling this method.');
+      }
+
+      if (!options?.transformation?.region) {
+        throw new Error('`region` must be provided when leveraging the transformation pipeline');
+      }
+
+      return ingestionTransporter?.push(
+        {
+          indexName,
+          watch: waitForTasks,
+          pushTaskPayload: {
+            action: createIfNotExists ? 'partialUpdateObject' : 'partialUpdateObjectNoCreate',
+            records: objects as PushTaskRecords[],
+          },
+        },
+        requestOptions,
+      );
+    },
+
     /**
      * Get the value of the `algoliaAgent`, used by our libraries internally and telemetry system.
      */