Merge pull request #423 from SalesforceCommerceCloud/feature/oas

Feat: Merge feature OAS branch

Author: joeluong-sfcc

.depcheckrc.yml

@@ -5,3 +5,11 @@ ignores:
   - node-fetch # We only use @types/node-fetch, not node-fetch itself
   - retry # Use OperationOptions from retry in templates but not recognized by depcheck
   - '@types/retry' # Corresponds to retry
+  - '@openapitools/openapi-generator-cli' # Used by openapi-generator-cli in `npm run renderTemplates`
+  - '@types/node-fetch' # Used by multiple files for fetch types
+  - chai # Used by multiple files for testing
+  - sinon # Used by multiple files for testing
+  - nock # Used by multiple files for testing to mock API calls
+  - handlebars # Used by generation script to generate version.ts and top level index.ts files
+  - fs-extra # Used by generation script and updateApis script
+  - tslib # Used by the TypeScript compiler

.eslintrc.json

@@ -7,7 +7,6 @@
   "plugins": [
     "@typescript-eslint",
     "@typescript-eslint/eslint-plugin",
-    "tsdoc",
     "header",
     "jsdoc"
   ],
@@ -32,7 +31,7 @@
         "selector": "interface",
         "format": ["PascalCase"],
         "custom": {
-          "regex": "^I[A-Z]",
+          "regex": "^[A-Z]",
           "match": true
         }
       }
@@ -53,7 +52,7 @@
       ]
     ],
     "jsdoc/require-description": [
-      "error",
+      "warn",
       {
         "checkConstructors": false
       }
@@ -76,8 +75,7 @@
     "jsdoc/require-param-type": "off",
     "jsdoc/require-returns-check": "error",
     "jsdoc/require-returns-description": "error",
-    "jsdoc/require-returns-type": "off",
-    "tsdoc/syntax": "error"
+    "jsdoc/require-returns-type": "off"
   },
   "overrides": [
     {

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
   linux-tests:
     strategy:
       matrix:
-        node: [16, 18, 20, 22]
+        node: [20, 22]
       fail-fast: false
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -66,6 +66,9 @@ dist
 
 .idea
 
+# Openapi-generator generates this when running renderTemplates
+openapitools.json
+
 # Release folders
 renderedTemplates
 .vscode

.nycrc.json

@@ -3,9 +3,13 @@
   "branches": 80,
   "check-coverage": true,
   "exclude": [
-    "src/generate.ts",
     "src/updateApis.ts",
-    "src/lib/config.ts"
+    "src/lib/config.ts",
+    "src/generate-oas.ts",
+    "src/generateVersionTable.ts",
+    "src/removeInternalOas.ts",
+    "src/static/helpers/index.ts",
+    "src/lib/utils.ts"
   ],
   "extends": "@istanbuljs/nyc-config-typescript",
   "extension": [

CHANGELOG.md

@@ -1,4 +1,48 @@
-## CHANGELOG
+# CHANGELOG
+
+## v5.0.0
+
+### API Versions
+
+| API Name | API Version |
+|----------|-------------|
+| assignments | 1.0.35 |
+| campaigns | 1.0.37 |
+| catalogs | 1.0.42 |
+| cdn-api-process-apis | 1.0.39 |
+| cors-preferences | 1.0.5 |
+| coupons | 1.0.39 |
+| customers | 1.0.32 |
+| gift-certificates | 1.0.39 |
+| orders | 1.4.10 |
+| preferences | 1.1.3 |
+| products | 1.0.40 |
+| promotions | 1.0.33 |
+| shopper-baskets | 1.9.0 |
+| shopper-baskets | 2.1.0 |
+| shopper-consents | 1.1.0 |
+| shopper-context | 1.1.1 |
+| shopper-customers | 1.1.1 |
+| shopper-experience | 1.0.7 |
+| shopper-gift-certificates | 1.0.26 |
+| shopper-login | 1.39.41 |
+| shopper-orders | 1.5.0 |
+| shopper-products | 1.0.37 |
+| shopper-promotions | 1.0.36 |
+| shopper-search | 1.3.0 |
+| shopper-seo | 1.0.13 |
+| shopper-stores | 1.0.17 |
+| slas-admin | 1.12.30 |
+| source-code-groups | 1.0.37 |
+
+### Enchancements
+- Enum types have been added for certain operations and types
+- Certain operations have had types updated for query parameters
+- SLAS helpers have been refactored to accept a single `options` object argument, where the properties are the old arguments
+  - `loginGuestUserPrivate` now passes `usid` under `options.parameters`
+- Path parameter special characters are encoded by default
+- API family layer and API namespace has been removed. To import API classes, please refer to the [README](https://github.com/SalesforceCommerceCloud/commerce-sdk?tab=readme-ov-file#sample-code)
+- Docs Site has been upgraded to reflect new directory structure [#426](https://github.com/SalesforceCommerceCloud/commerce-sdk/pull/426)
 
 
 ## v4.2.0

README.md

@@ -4,6 +4,28 @@ The Salesforce Commerce SDK allows easy interaction with the Salesforce B2C Comm
 
 Visit the [Commerce Cloud Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud) to learn more about Salesforce Commerce. The developer center has API documentation, getting started guides, community forums, and more.
 ​
+## Documentation
+
+An auto-generated [documentation site](https://salesforcecommercecloud.github.io/commerce-sdk/) provides comprehensive reference for all available endpoints and types across API classes. Following the v5.0.0 release, the underlying SDK file structure has been reorganized, introducing additional layers of imports/exports that may affect navigation.
+
+### Navigating the Documentation
+
+**For API Classes:**
+
+1. **Accessing API Classes:** Click on the API class name (e.g., `shopperProducts`) on the right hand side
+2. **Viewing Endpoints:** Scroll to the `Classes` section and click the corresponding API class link (e.g., `ShopperProducts`) to see available endpoints and their parameters
+3. **Type Definitions:** Scroll to the `Type aliases` section for available types
+4. **Navigating Back to API Classes**: To return to the main documentation page with all API classes listed on the right sidebar, click on `Globals` in the navigation.
+
+**Utility Classes:** Utility classes and methods such as `clientConfig` and `helpers` maintain the same structure as previous versions.
+
+**NOTES:** 
+
+1. **Type Access**: API class types are accessible through the `<api_class>Types` namespace (e.g., `ShopperProductsTypes`). Individual types can be accessed as `ShopperProductsTypes.Product`.
+2. **Type References**: The `References` section under API classes in the generated documentation may show duplicate entries. This occurs because types are exported both at their original definition and under the API class namespace. Both references point to the same underlying type definition.
+3. **V4 Migration Guide**: Starting in v5, API classes will no longer be exported under API family namespaces. See the [Sample Code](#sample-code) section for migration examples.
+4. **Supporting Files**: The SDK includes additional supporting modules beyond the `helpers` SLAS functions. The `types` module provides common type definitions shared across API classes, while the `version` module automatically implements user agent headers for all requests. The user agent value follows the format `commerce-sdk@<version>` based on the current SDK version.
+
 ## :warning: Planned API Changes :warning:
 
 ### Shopper Context
@@ -64,14 +86,25 @@ To use an SDK client, instantiate an object of that client and configure these p
 
 // Import the SDK in TypeScript
 // tsc requires the --esModuleInterop flag for this
-import { Search, Customer, helpers, slasHelpers } from "commerce-sdk";
+// Starting in v5, API classes will no longer be namespaced under API family
+import { ShopperSearch, ShopperLogin, helpers, slasHelpers } from "commerce-sdk";
+// For v4 and below, you'll have to import the API family first
+// import { Search, Customer, helpers, slasHelpers } from "commerce-sdk";
+// const loginClient = new Customer.ShopperLogin(config);
+// const searchClient = new Search.ShopperSearch(config);
+
 // Older Node.js versions can instead use:
 // const { ClientConfig, helpers, slasHelpers Search } = require("commerce-sdk");
 
+// Types for each individual API can be imported as <api_name>Types starting in v5
+import type { ShopperLoginTypes } from "commerce-sdk"
+
 // demo client credentials, if you have access to your own please replace them below.
 // do not store client secret as plaintext. Store it in a secure location.
+// For guidance on generating a private client with a client secret, please refer to:
+// https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html
+const CLIENT_SECRET = "<INSERT_CLIENT_SECRET>";
 const CLIENT_ID = "da422690-7800-41d1-8ee4-3ce983961078";
-const CLIENT_SECRET = "D*HHUrgO2%qADp2JTIUi";
 const ORG_ID = "f_ecom_zzte_053";
 const SHORT_CODE = "kv7kzm78";
 const SITE_ID = "RefArch";
@@ -92,10 +125,10 @@ const config = {
  *
  * @returns guest user authorization token
  */
-async function getGuestUserAuthToken(): Promise<Customer.ShopperLogin.TokenResponse> {
+async function getGuestUserAuthToken(): Promise<ShopperLoginTypes.TokenResponse> {
   const base64data = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
   const headers = { Authorization: `Basic ${base64data}` };
-  const loginClient = new Customer.ShopperLogin(config);
+  const loginClient = new ShopperLogin(config);
 
   return await loginClient.getAccessToken({
     headers,
@@ -104,10 +137,10 @@ async function getGuestUserAuthToken(): Promise<Customer.ShopperLogin.TokenRespo
 }
 
 // Alternatively you may use the SLAS helper functions to generate JWT/access token
-const guestTokenResponse = await slasHelpers.loginGuestUser(
-    new Customer.ShopperLogin(config), 
-    { redirectURI: 'http://localhost:3000/callback' }
-  )
+const guestTokenResponse = await slasHelpers.loginGuestUser({
+    slasClient: new ShopperLogin(config), 
+    parameters: { redirectURI: 'http://localhost:3000/callback' }
+  })
   .then((guestTokenResponse) => {
     console.log("Guest Token Response: ", guestTokenResponse);
     return guestTokenResponse;
@@ -119,7 +152,7 @@ getGuestUserAuthToken().then(async (token) => {
   // Add the token to the client configuration
   config.headers["authorization"] = `Bearer ${token.access_token}`;
 
-  const searchClient = new Search.ShopperSearch(config);
+  const searchClient = new ShopperSearch(config);
 
   // Search for dresses
   const searchResults = await searchClient.productSearch({

apis/.metadata.json

@@ -1 +1 @@
-{"shopperAuthClient":"Customer.ShopperCustomers","shopperAuthApi":"authorizeCustomer","shopperAuthDataType":"Customer","enforceCcdcId":true}
+{"shopperAuthClient":"Customer.ShopperCustomers","shopperAuthApi":"authorizeCustomer","shopperAuthDataType":"Customer"}

apis/assignments-oas-1.0.35/.metadata.json

@@ -0,0 +1,16 @@
+{
+  "id": "893f605e-10e2-423a-bdb4-f952f56eb6d8/assignments-oas/1.0.35",
+  "name": "Assignments OAS",
+  "description": "",
+  "groupId": "893f605e-10e2-423a-bdb4-f952f56eb6d8",
+  "assetId": "assignments-oas",
+  "version": "1.0.35",
+  "categories": {
+    "SDK Type": [
+      "Commerce"
+    ],
+    "Visibility": [
+      "External"
+    ]
+  }
+}