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

* add encoding helper

* update CHANGELOG

Author: joeluong-sfcc

.eslintrc.json

@@ -44,7 +44,7 @@
         "",
         {
           "pattern": "^ \\* Copyright \\(c\\) \\d{4}, salesforce.com, inc\\.$",
-          "template": " * Copyright (c) 2022, salesforce.com, inc."
+          "template": " * Copyright (c) 2025, salesforce.com, inc."
         },
         " * All rights reserved.",
         " * SPDX-License-Identifier: BSD-3-Clause",

CHANGELOG.md

@@ -1,7 +1,11 @@
 ## CHANGELOG
 
+
 ## v4.2.0 - future release
+
+### Enchancements
 - Allow custom params for 'loginGuestUser' and custom body for 'loginRegisteredUserB2C' function [#415](https://github.com/SalesforceCommerceCloud/commerce-sdk/pull/415)
+- Add helper to encode special SCAPI characters [#416](https://github.com/SalesforceCommerceCloud/commerce-sdk/pull/416)
 
 ## v4.1.0
 

README.md

@@ -18,6 +18,12 @@ Please be aware that existing tenants are on a temporary allow list and will see
 
 In practice, we recommend that customers using the SLAS helper functions upgrade to `v4.0.0` of the `commerce-sdk`.
 
+## :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.
+
 ## Prerequisites
 
 Download and install Node.js and npm [here](https://nodejs.org/en/download/).
@@ -319,6 +325,67 @@ console.log('get response: ', getResponse)
 console.log('post response: ', postResponse)
 ```
 
+### 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 * as CommerceSdk from "commerce-sdk";
+const { helpers, Product } = CommerceSdk;
+
+const clientConfig = {
+  parameters: {
+    clientId: "<your-client-id>",
+    organizationId: "<your-org-id>",
+    shortCode: "<your-short-code>",
+    siteId: "<your-site-id>",
+  }
+};
+
+const shopperProducts = new Product.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**
+
 ## Caching
 
 The SDK currently supports two types of caches - In-memory and Redis. Both the implementations respect [standard cache headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). To use another type of cache, write your own implementation of the [CacheManager](https://github.com/SalesforceCommerceCloud/commerce-sdk-core/tree/main/src/base/cacheManager.ts). See the [default cache manager](https://github.com/SalesforceCommerceCloud/commerce-sdk-core/tree/main/src/base/cacheManagerKeyv.ts) to design your implementation.

src/static/helperTemplates/index.ts.hbs

@@ -6,7 +6,9 @@
  */
 
 import { callCustomEndpoint } from "./customApi";
+import { encodeSCAPISpecialCharacters } from "./fetchHelpers";
 export const helpers = {
-    callCustomEndpoint
+    callCustomEndpoint,
+    encodeSCAPISpecialCharacters
 }
 export * as slasHelpers from "./slas";

src/static/helpers/fetchHelper.test.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025, 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 { encodeSCAPISpecialCharacters } from "./fetchHelpers";
+import { expect } from "chai";
+
+describe("encodeSCAPISpecialCharacters", () => {
+  it("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).to.be.equal(expectedOutput);
+  });
+
+  it("returns the same string if no SCAPI special characters are included", () => {
+    const input = "women'sCategory!@#$^&*()_+";
+    const output = encodeSCAPISpecialCharacters(input);
+    expect(output).to.be.equal(input);
+  });
+});

src/static/helpers/fetchHelpers.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2025, 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
+ */
+
+/**
+ * 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");