Feat: support custom APIs @W-15111169@ (#149)

* add custom endpoint helper * refactor * implement runFetchHelper * use runFetchHelper in operations handlebar template * fix broken calls * fix linting errors and most type errors * Refactor and add tsdoc comments * refactor and add unit test * add comment for test coverage * add unit test and update changelog * update type for body * address PR comments * add example in README * update types and allow baseUri as argument * lint * add check in test for response status code * combine params into 1 object and pull out custom path params into options * default application/json as content type and add test * add check for clientConfig headers * lint * use siteId from clientConfig * update README * remove comment * pull out default base URI into config file
SalesforceCommerceCloud · Apr 30, 2024 · 93358e3 · 93358e3
1 parent fa49335
commit 93358e3
Show file tree

Hide file tree

Showing 11 changed files with 724 additions and 19 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## v1.14.0-dev
+
+#### Enchancements
+
+- Add helper function `callCustomEndpoint` to call [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html) - [#149](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/149)
+
 ## v1.13.1
 
 #### Bug fixes

diff --git a/README.md b/README.md
@@ -141,6 +141,83 @@ 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html) with a helper function, `callCustomEndpoint`.
+
+Example usage:
+
+```javascript
+import pkg from 'commerce-sdk-isomorphic';
+const { helpers } = pkg;
+
+const clientConfigExample = {
+  parameters: {
+    clientId: "<your-client-id>",
+    organizationId: "<your-org-id>",
+    shortCode: "<your-short-code>",
+    siteId: "<your-site-id>",
+  },
+  // If not provided, it'll use the default production URI:
+  // 'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}'
+  // path parameters should be wrapped in curly braces like the default production URI
+  baseUri: "<your-base-uri>"
+};
+
+// Required params: apiName, endpointPath, shortCode, organizaitonId
+// Required path params can be passed into:
+// options.customApiPathParameters or clientConfig.parameters
+const customApiArgs = { 
+  apiName: 'loyalty-info',
+  apiVersion: 'v1', // defaults to v1 if not provided
+  endpointPath: 'customers'
+}
+
+const accessToken = '<INSERT ACCESS TOKEN HERE>';
+
+let getResponse = await helpers.callCustomEndpoint({
+  options: {
+    method: 'GET',
+    parameters: {
+      queryParameter: 'queryParameter1',
+    },
+    headers: {
+      // Content-Type is defaulted to application/json if not provided
+      'Content-Type': 'application/json',
+      authorization: `Bearer ${access_token}`
+    },
+    customApiPathParameters: customApiArgs
+  }, 
+  clientConfig: clientConfigExample,
+  // Flag to retrieve raw response or data from helper function
+  rawResponse: false, 
+})
+
+let postResponse = await helpers.callCustomEndpoint({
+  options: {
+    method: 'POST',
+    parameters: {
+      queryParameter: 'queryParameter1',
+    },
+    headers: {
+      authorization: `Bearer ${access_token}`
+    },
+    customApiPathParameters: customApiArgs,
+    body: JSON.stringify({ data: 'data' })
+  }, 
+  clientConfig: clientConfigExample,
+  // Flag to retrieve raw response or data from helper function
+  rawResponse: false, 
+})
+
+console.log('get response: ', getResponse)
+console.log('post response: ', postResponse)
+```
+
+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)
+
 ## License Information
 
 The Commerce SDK Isomorphic is licensed under BSD-3-Clause license. See the [license](./LICENSE.txt) for details.
diff --git a/src/static/config.ts b/src/static/config.ts
@@ -0,0 +1,9 @@
+/*
+ * 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
+ */
+// eslint-disable-next-line import/prefer-default-export
+export const CUSTOM_API_DEFAULT_BASE_URI =
+  'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}';
diff --git a/src/static/helpers/customApi.test.ts b/src/static/helpers/customApi.test.ts
@@ -0,0 +1,252 @@
+/*
+ * 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, CustomParams} from './customApi';
+import * as fetchHelper from './fetchHelper';
+import ClientConfig from '../clientConfig';
+
+describe('callCustomEndpoint', () => {
+  beforeEach(() => {
+    jest.restoreAllMocks();
+    nock.cleanAll();
+  });
+
+  const clientConfig = new ClientConfig<CustomParams>({
+    parameters: {
+      shortCode: 'short_code',
+      organizationId: 'organization_id',
+      clientId: 'client_id',
+      siteId: 'site_id',
+    },
+  });
+
+  const options = {
+    method: 'POST',
+    parameters: {
+      queryParam1: 'query parameter 1',
+      queryParam2: 'query parameter 2',
+    },
+    customApiPathParameters: {
+      apiName: 'api_name',
+      apiVersion: 'v2',
+      endpointPath: 'endpoint_path',
+    },
+    headers: {
+      'Content-Type': 'text/plain',
+      authorization: 'Bearer token',
+    },
+    body: 'Hello World',
+  };
+
+  const queryParamString = new URLSearchParams({
+    ...options.parameters,
+    siteId: clientConfig.parameters.siteId as string,
+  }).toString();
+
+  // helper function that creates a copy of the options object
+  // and adds siteId to the parameters object that comes from clientConfig
+  const addSiteIdToOptions = (optionsObj: Record<string, unknown>) => ({
+    ...optionsObj,
+    parameters: {
+      ...(optionsObj.parameters as Record<string, unknown>),
+      siteId: clientConfig.parameters.siteId,
+    },
+  });
+
+  test('throws an error when required path parameters are not passed', () => {
+    const copyOptions = {
+      ...options,
+      // omit endpointPath
+      customApiPathParameters: {
+        apiName: 'api_name',
+      },
+    };
+
+    expect(async () => {
+      // eslint-disable-next-line
+      // @ts-ignore <-- we know it'll complain since we removed endpointPath
+      await callCustomEndpoint({options: copyOptions, clientConfig});
+    })
+      .rejects.toThrow(
+        'Missing required property needed in options.customApiPathParameters or clientConfig.parameters: endpointPath'
+      )
+      .finally(() => 'resolve promise');
+  });
+
+  test('sets api version to "v1" if not provided', async () => {
+    const copyOptions = {
+      ...options,
+      // omit apiVersion
+      customApiPathParameters: {
+        endpointPath: 'endpoint_path',
+        apiName: 'api_name',
+      },
+    };
+
+    const {shortCode, organizationId} = clientConfig.parameters;
+    const {apiName, endpointPath} = copyOptions.customApiPathParameters;
+
+    const nockBasePath = `https://${shortCode}.api.commercecloud.salesforce.com`;
+    const nockEndpointPath = `/custom/${apiName}/v1/organizations/${
+      organizationId as string
+    }/${endpointPath}`;
+    nock(nockBasePath).post(nockEndpointPath).query(true).reply(200);
+
+    const expectedUrl = `${
+      nockBasePath + nockEndpointPath
+    }?${queryParamString}`;
+    const expectedOptions = addSiteIdToOptions(copyOptions);
+
+    const doFetchSpy = jest.spyOn(fetchHelper, 'doFetch');
+
+    const response = (await callCustomEndpoint({
+      options: copyOptions,
+      clientConfig,
+      rawResponse: true,
+    })) as Response;
+
+    expect(response.status).toBe(200);
+    expect(doFetchSpy).toBeCalledTimes(1);
+    expect(doFetchSpy).toBeCalledWith(
+      expectedUrl,
+      expectedOptions,
+      expect.anything(),
+      true
+    );
+    expect(expectedUrl).toContain('/v1/');
+  });
+
+  test('doFetch is called with the correct arguments', async () => {
+    const {shortCode, organizationId} = clientConfig.parameters;
+    const {apiName, endpointPath} = options.customApiPathParameters;
+
+    const nockBasePath = `https://${shortCode}.api.commercecloud.salesforce.com`;
+    const nockEndpointPath = `/custom/${apiName}/v2/organizations/${
+      organizationId as string
+    }/${endpointPath}`;
+    nock(nockBasePath).post(nockEndpointPath).query(true).reply(200);
+
+    const expectedUrl = `${
+      nockBasePath + nockEndpointPath
+    }?${queryParamString}`;
+    const expectedOptions = addSiteIdToOptions(options);
+
+    const expectedClientConfig = {
+      ...clientConfig,
+      baseUri:
+        'https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}',
+    };
+
+    const doFetchSpy = jest.spyOn(fetchHelper, 'doFetch');
+    await callCustomEndpoint({options, clientConfig, rawResponse: true});
+    expect(doFetchSpy).toBeCalledTimes(1);
+    expect(doFetchSpy).toBeCalledWith(
+      expectedUrl,
+      expectedOptions,
+      expectedClientConfig,
+      true
+    );
+  });
+
+  test('uses path params from options and clientConfig, prioritizing options', async () => {
+    const copyClientConfig = {
+      ...clientConfig,
+      // Only shortCode will be used
+      parameters: {
+        endpointPath: 'clientConfig_endpoint_path',
+        apiName: 'clientConfig_api_name',
+        shortCode: 'clientconfig_shortcode',
+        apiVersion: 'v2',
+        organizationId: 'clientConfig_organizationId',
+        siteId: 'site_id',
+      },
+    };
+
+    const copyOptions = {
+      ...options,
+      // these parameters will be prioritzed
+      customApiPathParameters: {
+        endpointPath: 'customApiPathParameters_endpoint_path',
+        apiName: 'customApiPathParameters_api_name',
+        apiVersion: 'v3',
+        organizationId: 'customApiPathParameters_organizationId',
+      },
+    };
+
+    // nock interception should be using custom API path parameters from options
+    const {apiName, endpointPath, organizationId, apiVersion} =
+      copyOptions.customApiPathParameters;
+    // except shortcode since we didn't implement it in copyOptions.customApiPathParameters
+    const {shortCode} = copyClientConfig.parameters;
+
+    const nockBasePath = `https://${shortCode}.api.commercecloud.salesforce.com`;
+    const nockEndpointPath = `/custom/${apiName}/${apiVersion}/organizations/${organizationId}/${endpointPath}`;
+    nock(nockBasePath).post(nockEndpointPath).query(true).reply(200);
+
+    // expected URL is a mix of both params
+    const expectedUrl = `${
+      nockBasePath + nockEndpointPath
+    }?${queryParamString}`;
+
+    const doFetchSpy = jest.spyOn(fetchHelper, 'doFetch');
+    await callCustomEndpoint({
+      options: copyOptions,
+      clientConfig: copyClientConfig,
+    });
+    expect(doFetchSpy).toBeCalledTimes(1);
+    expect(doFetchSpy).toBeCalledWith(
+      expectedUrl,
+      expect.anything(),
+      expect.anything(),
+      undefined
+    );
+  });
+
+  test('uses application/json as default content type if not provided', async () => {
+    const copyOptions = {
+      ...options,
+      // exclude Content-Type
+      headers: {
+        authorization: 'Bearer token',
+      },
+    };
+
+    const {apiName, endpointPath, apiVersion} =
+      copyOptions.customApiPathParameters;
+    const {shortCode, organizationId} = clientConfig.parameters;
+
+    const expectedJsonHeaders = {
+      authorization: 'Bearer token',
+      'Content-Type': 'application/json',
+    };
+
+    const nockBasePath = `https://${shortCode}.api.commercecloud.salesforce.com`;
+    const nockEndpointPath = `/custom/${apiName}/${apiVersion}/organizations/${
+      organizationId as string
+    }/${endpointPath}`;
+    nock(nockBasePath, {
+      reqheaders: expectedJsonHeaders,
+    })
+      .post(nockEndpointPath)
+      .query(true)
+      .reply(200);
+
+    const doFetchSpy = jest.spyOn(fetchHelper, 'doFetch');
+    await callCustomEndpoint({
+      options: copyOptions,
+      clientConfig,
+    });
+    expect(doFetchSpy).toBeCalledTimes(1);
+    expect(doFetchSpy).toBeCalledWith(
+      expect.any(String),
+      expect.objectContaining({headers: expectedJsonHeaders}),
+      expect.anything(),
+      undefined
+    );
+  });
+});