Feat: support custom APIs @W-15111169@

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## v1.14.0-dev
+
+#### Enchancements
+
+- Add support for custom APIs with `callCustomEndpoint` helper function [#149](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/149)
+
 ## v1.13.1
 
 #### Bug fixes

README.md

@@ -141,6 +141,62 @@ const searchResult = await shopperSearch.productSearch({
 
 Invalid query parameters that are not a part of the API and do not follow the `c_` custom query parameter convention will be filtered from the request and a warning will be displayed.
 
+### Custom APIs
+
+The SDK supports calling custom APIs with a helper function, `callCustomEndpoint`.
+
+Example usage:
+
+```javascript
+import pkg from 'commerce-sdk-isomorphic';
+const { helpers } = pkg;
+
+const CLIENT_ID = "<your-client-id>";
+const ORG_ID = "<your-org-id>";
+const SHORT_CODE = "<your-short-code>";
+const SITE_ID = "<your-site-id>";
+
+// client configuration parameters
+const clientConfig = {
+  parameters: {
+    clientId: CLIENT_ID,
+    organizationId: ORG_ID,
+    shortCode: SHORT_CODE,
+    siteId: SITE_ID,
+    // Custom API path parameters
+    endpointPath: 'customers',
+    apiName: 'loyalty-info',
+    apiVersion: 'v1', // defaults to v1 if not provided
+  },
+};
+
+// Flag to retrieve raw response or data from helper function
+const rawResponse = false;
+const accessToken = '<INSERT ACCESS TOKEN HERE>';
+
+let response = await helpers.callCustomEndpoint(
+  {
+    method: 'GET',
+    parameters: {
+      queryParameter: 'queryParameter1',
+      siteId: SITE_ID,
+    },
+    headers: {
+      'Content-Type': 'application/json',
+      authorization: `Bearer ${access_token}`
+    }
+  }, 
+  clientConfig,
+  rawResponse
+)
+
+console.log('RESPONSE: ', response)
+```
+
+For more documentation about this helper function, please refer to the [commerce-sdk-isomorphic docs](https://salesforcecommercecloud.github.io/commerce-sdk-isomorphic/modules/helpers.html).
+
+For more information about custom APIs, please refer to the [Salesforce Developer Docs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html?q=custom+API)
+
 ## License Information
 
 The Commerce SDK Isomorphic is licensed under BSD-3-Clause license. See the [license](./LICENSE.txt) for details.

src/static/helpers/customApi.test.ts

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2024, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import nock from 'nock';
+import {callCustomEndpoint} from './customApi';
+import * as fetchHelper from './fetchHelper';
+import ClientConfig from '../clientConfig';
+import {CustomParams} from '../../lib/helpers';
+
+describe('callCustomEndpoint', () => {
+  beforeEach(() => {
+    jest.restoreAllMocks();
+    nock.cleanAll();
+  });
+
+  const clientConfigParameters: CustomParams = {
+    shortCode: 'short_code',
+    organizationId: 'organization_id',
+    clientId: 'client_id',
+    siteId: 'site_id',
+    apiName: 'api_name',
+    apiVersion: 'v2',
+    endpointPath: 'endpoint_path',
+  };
+
+  const options = {
+    method: 'POST',
+    parameters: {
+      queryParam1: 'query parameter 1',
+      queryParam2: 'query parameter 2',
+    },
+    headers: {
+      authorization: 'Bearer token',
+    },
+    body: {
+      data: 'data',
+    },
+  };
+
+  test('throws an error when required path parameters are not passed', () => {
+    // separate apiName using spread since we can't use 'delete' operator as it isn't marked as optional
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const {apiName, ...copyClientConfigParams} = clientConfigParameters;
+
+    const clientConfig = new ClientConfig({
+      parameters: copyClientConfigParams,
+    });
+
+    expect(async () => {
+      // eslint-disable-next-line
+      // @ts-ignore <-- we know it'll complain since we removed apiName
+      await callCustomEndpoint(options, clientConfig);
+    })
+      .rejects.toThrow(
+        'Missing required property in clientConfig.parameters: apiName'
+      )
+      .finally(() => 'resolve promise');
+  });
+
+  test('sets api version to "v1" if not provided', async () => {
+    const copyClientConfigParams = {...clientConfigParameters};
+    delete copyClientConfigParams.apiVersion;
+
+    const clientConfig = new ClientConfig({
+      parameters: copyClientConfigParams,
+    });
+
+    const {shortCode, apiName, organizationId, endpointPath} =
+      clientConfig.parameters;
+
+    const nockBasePath = `https://${shortCode}.api.commercecloud.salesforce.com`;
+    const nockEndpointPath = `/custom/${apiName}/v1/organizations/${organizationId}/${endpointPath}`;
+    nock(nockBasePath).post(nockEndpointPath).query(true).reply(200);
+
+    const expectedUrl = `${
+      nockBasePath + nockEndpointPath
+    }?queryParam1=query+parameter+1&queryParam2=query+parameter+2`;
+    const doFetchSpy = jest.spyOn(fetchHelper, 'doFetch');
+
+    const response = (await callCustomEndpoint(
+      options,
+      clientConfig,
+      true
+    )) as Response;
+
+    expect(response.status).toBe(200);
+    expect(doFetchSpy).toBeCalledTimes(1);
+    expect(doFetchSpy).toBeCalledWith(
+      expectedUrl,
+      options,
+      expect.anything(),
+      true
+    );
+    expect(expectedUrl).toContain('/v1/');
+  });
+
+  test('doFetch is called with the correct arguments', async () => {
+    const clientConfig = new ClientConfig({
+      parameters: clientConfigParameters,
+    });
+
+    const {shortCode, apiName, organizationId, endpointPath} =
+      clientConfig.parameters;
+
+    const nockBasePath = `https://${shortCode}.api.commercecloud.salesforce.com`;
+    const nockEndpointPath = `/custom/${apiName}/v2/organizations/${organizationId}/${endpointPath}`;
+    nock(nockBasePath).post(nockEndpointPath).query(true).reply(200);
+
+    const expectedUrl = `${
+      nockBasePath + nockEndpointPath
+    }?queryParam1=query+parameter+1&queryParam2=query+parameter+2`;
+    const expectedClientConfig = {
+      ...clientConfig,
+      baseUri:
+        'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}',
+    };
+
+    const doFetchSpy = jest.spyOn(fetchHelper, 'doFetch');
+    await callCustomEndpoint(options, clientConfig, true);
+    expect(doFetchSpy).toBeCalledTimes(1);
+    expect(doFetchSpy).toBeCalledWith(
+      expectedUrl,
+      options,
+      expectedClientConfig,
+      true
+    );
+  });
+});

src/static/helpers/customApi.ts

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import {BodyInit} from 'node-fetch';
+import {PathParameters} from './types';
+import {doFetch} from './fetchHelper';
+import TemplateURL from '../templateUrl';
+import {ClientConfigInit} from '../clientConfig';
+
+export interface CustomParams {
+  apiName: string;
+  apiVersion?: string;
+  endpointPath: string;
+  organizationId: string;
+  shortCode: string;
+  [key: string]: unknown;
+}
+
+/**
+ * A helper function designed to make calls to a custom API endpoint
+ * For more information about custom APIs, please refer to the [API documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html?q=custom+API)
+ * @param options - An object containing any custom settings you want to apply to the request
+ * @param options.method? - The request HTTP operation. 'GET' is the default if no method is provided.
+ * @param options.parameters? - Query parameters that are added to the request
+ * @param options.headers? - Headers that are added to the request. Authorization header should be in this parameter or in the clientConfig.headers
+ * @param options.body? - Body that is used for the request
+ * @param clientConfig - Client Configuration object used by the SDK with properties that can affect the fetch call
+ * @param clientConfig.parameters - Path parameters used for custom API endpoints. The required properties are: apiName, endpointPath, organizationId, and shortCode. An error will be thrown if these are not provided.
+ * @param clientConfig.headers? - Additional headers that are added to the request. Authorization header should be in this argument or in the options?.headers. options?.headers will override any duplicate properties.
+ * @param clientConfig.baseUri? - baseUri used for the request, where the path parameters are wrapped in curly braces. Default value is 'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}'
+ * @param clientConfig.fetchOptions? - fetchOptions that are passed onto the fetch request
+ * @param clientConfig.throwOnBadResponse? - flag that when set true will throw a response error if the fetch request fails
+ * @param clientConfig.proxy? - Routes API calls through a proxy when set
+ * @param rawResponse? - Flag to return the raw response from the fetch call. True for raw response object, false for the data from the response
+ * @returns Raw response or data from response based on rawResponse argument from fetch call
+ */
+export const callCustomEndpoint = async (
+  options: {
+    method?: string;
+    parameters?: {
+      [key: string]: string | number | boolean | string[] | number[];
+    };
+    headers?: {
+      authorization?: string;
+    } & {[key: string]: string};
+    body?: BodyInit | globalThis.BodyInit | unknown;
+  },
+  clientConfig: ClientConfigInit<CustomParams>,
+  rawResponse?: boolean
+): Promise<Response | unknown> => {
+  const requiredArgs = [
+    'apiName',
+    'endpointPath',
+    'organizationId',
+    'shortCode',
+  ];
+  requiredArgs.forEach(arg => {
+    if (!clientConfig.parameters[arg]) {
+      throw new Error(
+        `Missing required property in clientConfig.parameters: ${arg}`
+      );
+    }
+  });
+
+  const defaultBaseUri =
+    'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}';
+  let clientConfigCopy = clientConfig;
+
+  if (!clientConfig.baseUri || !clientConfig.parameters?.apiVersion) {
+    clientConfigCopy = {
+      ...clientConfig,
+      ...(!clientConfig.baseUri && {baseUri: defaultBaseUri}),
+      parameters: {
+        ...clientConfig.parameters,
+        ...(!clientConfig.parameters?.apiVersion && {apiVersion: 'v1'}),
+      },
+    };
+  }
+
+  const url = new TemplateURL(
+    '/organizations/{organizationId}/{endpointPath}',
+    clientConfigCopy.baseUri as string,
+    {
+      pathParams: clientConfigCopy.parameters as PathParameters,
+      queryParams: options.parameters,
+      origin: clientConfigCopy.proxy,
+    }
+  );
+
+  return doFetch(url.toString(), options, clientConfigCopy, rawResponse);
+};

src/static/helpers/environment.ts

@@ -32,6 +32,8 @@ export const fetch: FetchFunction = (() => {
     return require('node-fetch').default;
   }
 
+  // difficult to test in node environment
+  /* istanbul ignore next */
   if (!hasFetchAvailable)
     throw new Error(
       'Bad environment: it is not a node environment but fetch is not defined'