Feat: Add helper to encode special characters (@W-17577102@) (#189)

* add initial fix

* switch order of CI

* add helper to encode special char

* revert encoding path params

* bump bundle size

Author: joeluong-sfcc

.github/workflows/test.yml

@@ -19,6 +19,7 @@ jobs:
         with:
           node-version: ${{ matrix.node }}
           cache: npm
+      - run: yarn install
       - name: Cache node modules
         id: cache-nodemodules
         uses: actions/cache@v3
@@ -27,7 +28,6 @@ jobs:
         with:
           path: "**/node_modules"
           key: ${{ runner.os }}-node${{ matrix.node }}-build-${{ env.cache-name }}-${{ hashFiles('yarn.lock') }}
-      - run: yarn install
         if: ${{ steps.cache-nodemodules.outputs.cache-hit != 'true' }}
       - run: yarn run renderTemplates
       - run: yarn build:lib

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## v3.3.0
 - Allow custom params for 'loginGuestUser', 'authorizeIDP' and custom body for 'loginRegisteredUserB2C' functions [#186](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/186)
+- Add helper to encode special SCAPI characters [#189](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic/pull/189)
 
 ## v3.2.0
 

README.md

@@ -21,6 +21,12 @@ In practice, we recommend:
 - For customers using the SLAS helpers with a public client, it is recommended to upgrade to at least `v1.8.0` of the `commerce-sdk-isomorphic`.
 - For customers using the SLAS helpers with a private client, it is recommended to upgrade to `v3.0.0` of the `commerce-sdk-isomorphic`.
 
+## :warning: Planned SDK Changes :warning:
+
+### Encoding path parameters
+
+In the next major version release, the SDK will encode special characters (UTF-8 based on SCAPI guidelines) in path parameters by default. Please see the [Encoding special characters](#encoding-special-characters) section for more details.
+
 ## Getting Started
 
 ### Requirements
@@ -114,7 +120,7 @@ try {
 
 * `headers`: Headers to include with API requests.
 
-### Custom Query Parameters
+#### Custom Query Parameters
 
 You can pass custom query parameters through the SDK to be used in [B2C Commerce API Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html). Custom query parameters must begin with `c_`:
 
@@ -129,7 +135,7 @@ 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 are filtered from the request with a warning.
 
-### Custom APIs
+#### Custom APIs
 
 The SDK supports calling [B2C Commerce Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html) with a helper function, `callCustomEndpoint`:
 
@@ -195,6 +201,67 @@ await helpers.callCustomEndpoint({
 
 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).
 
+#### Encoding special characters
+
+The SDK currently single encodes special characters for query parameters in UTF-8 format based on SCAPI guidelines. However, the SDK does NOT encode path parameters, and will require the developer to encode any path parameters with special characters.
+
+Additionally, SCAPI has special characters that should be double encoded, specifically `%` and `,`:
+- `%` should always be double encoded
+- `,` should be double encoded when used as part of an ID/parameter string, and single encoded when used to differentiate items in a list 
+
+There is a helper function called `encodeSCAPISpecialCharacters` that can be utilized to single encode the SCAPI special characters and no other special characters.
+
+Here's an example where the `getCategory/getCategories` endpoints are called with a `categoryID` with special characters:
+```javascript
+import pkg from "commerce-sdk-isomorphic";
+const { helpers, ShopperProducts } = pkg;
+
+const clientConfig = {
+  parameters: {
+    clientId: "<your-client-id>",
+    organizationId: "<your-org-id>",
+    shortCode: "<your-short-code>",
+    siteId: "<your-site-id>",
+  }
+};
+
+const shopperProducts = new ShopperProducts({
+  ...clientConfig,
+  headers: {authorization: `Bearer <insert_access_token>`}
+});
+
+const categoryId = "SpecialCharacter,%$^@&$;()!123Category";
+// "SpecialCharacter%2C%25$^@&$;()!123Category"
+const scapiSpecialEncodedId = helpers.encodeSCAPISpecialCharacters(categoryId);
+
+
+// id is a path parameter for API call:
+// <base-url>/product/shopper-products/v1/organizations/{organizationId}/categories/{id}
+const categoryResult = await shopperProducts.getCategory({
+  parameters: {
+    // Path parameters are NOT encoded by the SDK, so we have to single encode special characters
+    // and the SCAPI special characters will end up double encoded
+    id: encodeURIComponent(scapiSpecialEncodedId),
+  }
+});
+
+console.log("categoryResult: ", categoryResult);
+
+// `ids` are a query parameter and comma delimited to separate category IDs
+const categoriesResult = await shopperProducts.getCategories({
+  parameters: {
+    // No need to use `encodeURIComponent` as query parameters are single encoded by the SDK
+    // So the SCAPI special characters will end up double encoded as well
+    // Commas that separate items in a list will end up single encoded
+    ids: `${scapiSpecialEncodedId},${scapiSpecialEncodedId}`,
+  }
+});
+
+console.log("categoriesResult: ", categoriesResult);
+```
+
+**NOTE: In the next major version release, path parameters will be single encoded by default**
+
 ## License Information
 
 The Commerce SDK Isomorphic is licensed under BSD-3-Clause license. See the [license](./LICENSE.txt) for details.

package.json

@@ -181,7 +181,7 @@
     },
     {
       "path": "commerce-sdk-isomorphic-with-deps.tgz",
-      "maxSize": "561 kB"
+      "maxSize": "562 kB"
     }
   ],
   "proxy": "https://SHORTCODE.api.commercecloud.salesforce.com"

src/static/helpers/fetchHelper.test.ts

@@ -8,7 +8,7 @@ import nock from 'nock';
 import {Response} from 'node-fetch';
 import * as environment from './environment';
 import ClientConfig from '../clientConfig';
-import {doFetch} from './fetchHelper';
+import {doFetch, encodeSCAPISpecialCharacters} from './fetchHelper';
 
 describe('doFetch', () => {
   const basePath = 'https://short_code.api.commercecloud.salesforce.com';
@@ -139,3 +139,18 @@ describe('doFetch', () => {
     );
   });
 });
+
+describe('encodeSCAPISpecialCharacters', () => {
+  test('only encodes special characters `%` and `,` in a string', () => {
+    const input = "women'sCategory,%@#$%^&*()_+,";
+    const expectedOutput = "women'sCategory%2C%25@#$%25^&*()_+%2C";
+    const output = encodeSCAPISpecialCharacters(input);
+    expect(output).toEqual(expectedOutput);
+  });
+
+  test('returns the same string if no SCAPI special characters are included', () => {
+    const input = "women'sCategory!@#$^&*()_+";
+    const output = encodeSCAPISpecialCharacters(input);
+    expect(output).toEqual(input);
+  });
+});

src/static/helpers/fetchHelper.ts

@@ -68,3 +68,12 @@ export const doFetch = async <Params extends BaseUriParameters>(
     return (text ? JSON.parse(text) : {}) as unknown | Response;
   }
 };
+
+/**
+ * Single encodes SCAPI specific special characters (percentage sign `%` and comma `,`) in the given string in UTF-8
+ * Does not encode any other special characters in the string
+ * @param str - The string to encode
+ * @returns The encoded string
+ */
+export const encodeSCAPISpecialCharacters = (str: string): string =>
+  str.replace(/%/g, '%25').replace(/,/g, '%2C');