@W-18575180@ Generate node SDK from OAS by vcua-mobify · Pull Request #418 · SalesforceCommerceCloud/commerce-sdk

vcua-mobify · 2025-05-23T22:50:02Z

THIS PR CONTAINS BREAKING CHANGES

This PR updates commerce-sdk so that it downloads OAS files from anypoint exchange rather than raml files

This requires the changes from SalesforceCommerceCloud/raml-toolkit#228 to work

Testing the changes:

Check out both this PR and the @W-17701650@ Add support for OAS raml-toolkit#228
Build raml-toolkit: npm install && npm run build
In commerce-sdk's package.json, ensure the dependency to raml-toolkit is pointed to your local raml-toolkit.
Run yarn ci to install dependencies and include the local raml-toolkit
Set some env vars for the anypoint exchange credentials
export ANYPOINT_USERNAME="<insert_username_here>"
export ANYPOINT_PASSWORD="<insert_password_here>"
Download the OAS files from anypoint exchange and run diff check. You currently need to run this twice; the 1st run will compare the current contents of the apis dir (which contain raml files) with the newly downloaded oas files. The 2nd run onwards will compare only oas files (the files you downloaded from the 1st run with the files you downloaded from the 2nd run). You may also need to delete the updateApisTemp directory.
yarn updateApis
yarn renderTemplates will call raml-toolkit to run openapi-generator. The files it generates will be outputted under renderedTemplates

Currently the generated files have a naming conflict for ShopperContexts, CorsPreferences, Catalog, and ShopperBasketsV2. Current workaround is to manually address the name conflicts or to edit the oas files in question that were downloaded from exchange and define a x-sdk-classname

For example:

x-sdk-classname: CatalogsAPI

For the other affected APIs, set the x-sdk-classname to one of: CORSPreferences or ShopperContexts or ShopperBasketsV2

Bundle the generated files with yarn compile
Run tests with yarn test
Generate docs with yarn doc

Note:
The changes from SalesforceCommerceCloud/commerce-sdk-isomorphic#197 have been applied to the mustache templates here.

TODO - will be done in a follow up PR:
OASDiff fails with duplicate endpoint for order/shopper-order and product/shopper-product - this will be a separate ticket
~~Investigate why doc generation has many duplicate types~~ this will be a separate ticket

vcua-mobify · 2025-06-06T19:23:56Z

I was doing some file clean up on the fork and it somehow closed the PR =/

…-sdk into oas-support

src/generate-oas.ts

package.json

unandyala · 2025-06-10T21:42:57Z

src/generate-oas.ts

+    ) {
+      return {
+        filepath: path.join(directory, exchangeConfig.main),
+        filename: exchangeConfig.main,


Does changing the filename to include V2 change the class name for the generated class? If so I think we should do that

This refers to the file name of the file that's defined in exchange.json. For shopper baskets v2, this is shopper-baskets-oas-v2-bundled.yaml

If we change the name of the .yaml file then we will need to come up with a different way to get that file name rather than relying on exchange.json.

src/generate-oas.ts

joeluong-sfcc

Will you create a PR for updating APIs?

I also noticed that I can't seem to get my local RAML toolkit directory linked up to the node SDK without using yarn, once we release the RAML toolkit with the new changes, this should be fine. If we aren't able to, however, we'll have a problem

package.json

yarn.lock

src/generate-oas.ts

templatesOas/index.mustache

vcua-mobify · 2025-06-13T22:59:25Z

package.json

-    "snyk": "^1.836.0",
+    "snyk": "^1.996.0",
    "sort-package-json": "^1.53.1",
+    "source-map-support": "^0.5.21",


This is required to be able to run tests with npm. Not sure why this wasn't required when I was running the tests through yarn.

vcua-mobify · 2025-06-13T23:00:20Z

package.json

-    "eslint-plugin-tsdoc": "^0.2.17",
    "fs-extra": "^9.1.0",
-    "handlebars-helpers": "^0.10.0",
+    "handlebars": "4.7.7",


depcheck wants this dependency to be handlebars rather than handlebars-helpers.

I've set the version of handlebars to the same version used by the isomorphic sdk

vcua-mobify · 2025-06-16T22:25:09Z

testIntegration/package.json

    "test:prod": "npm run bundle:install && npm run test",
-    "test:staging": "COMMERCE_SDK_INPUT_DIR=testIntegration/stagingApis npm run test:prod",
-    "test:ci": "npm run test:prod && npm run test:staging",
+    "test:ci": "npm run test:prod",


The tests already run against the apis downloaded to the apis directory so I don't see why we need to duplicate the download to the staging directory + test run.

Note: This may change in the near future if we start making a distinction between 'external' and 'internal' apis.

vcua-mobify · 2025-06-16T22:26:53Z

testIntegration/tests/userAgent.test.ts

-    expect(nock.isDone()).to.be.true;
-  });
+  // TODO: Investigate why this test fails if a user-agent header is passed in the method call
+  // it("merges with alternative case header in method", async () => {


I'm not sure why this test in particular is failing. The API includes a call to mergeHeaders like before:

const headers = mergeHeaders(getHeaders(options), { [USER_AGENT_HEADER]: USER_AGENT_VALUE });

so I'm not sure if something has changed with the implementation in commerce-apps-core

+1 to Ujwala's point for documenting this work, we should create a small ticket or update one of our other tickets to revisit this so we don't lose track of it

unandyala

Overall LGTM. If there are known issues, please create follow up tickets to fix

unandyala · 2025-06-17T13:51:12Z

src/lib/config.ts

+  "catalogs-oas",
+  "cdn-api-process-apis-oas",
+  "coupons-oas",
+  // "cors-preferences-oas", // This is included in preferences-oas. Error: diff failed: duplicate endpoint (PUT /organizations/{organizationId}/cors) found in apis/cors-preferences-oas/cors-preferences-oas/cors-preferences-oas-v1-bundled.yaml and apis/preferences-oas/cors-preferences-oas/cors-preferences-oas-v1-bundled.yaml. You may add the x-since-date extension to specify order


so we don't need this API family? If so can we delete from here?

unandyala · 2025-06-17T13:52:26Z

src/lib/config.ts

+  "customers-oas",
+  "gift-certificates-oas",
+  "orders-oas", // Error: failed to load base specs from glob "updateApisTmp/oldApis/**/*.yaml": failed to load "updateApisTmp/oldApis/orders-oas/orders-oas/orders-oas-v1-bundled.yaml": failed to unmarshal data: json error: invalid character 'o' looking for beginning of value, yaml error: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal array into field Schema.items of type openapi3.Schema
+  "products-oas", // Error: diff failed: duplicate endpoint (GET /organizations/{organizationId}/products/{id}) found in apis/products-oas/products-oas/products-oas-v1-bundled.yaml and apis/products-oas/products-oas-test/products-oas-test-v1-bundled.yaml. You may add the x-since-date extension to specify order


Are we downloading both products-oas-v1-bundled.yaml and products-oas-test-v1-bundled.yaml? Is this something we need to fix in the download?

This issue was fixed once I started downloading the latest stable version rather than a snapshot.

I'll remove the comments

unandyala · 2025-06-17T13:53:06Z

src/lib/config.ts

+  // "cors-preferences-oas", // This is included in preferences-oas. Error: diff failed: duplicate endpoint (PUT /organizations/{organizationId}/cors) found in apis/cors-preferences-oas/cors-preferences-oas/cors-preferences-oas-v1-bundled.yaml and apis/preferences-oas/cors-preferences-oas/cors-preferences-oas-v1-bundled.yaml. You may add the x-since-date extension to specify order
+  "customers-oas",
+  "gift-certificates-oas",
+  "orders-oas", // Error: failed to load base specs from glob "updateApisTmp/oldApis/**/*.yaml": failed to load "updateApisTmp/oldApis/orders-oas/orders-oas/orders-oas-v1-bundled.yaml": failed to unmarshal data: json error: invalid character 'o' looking for beginning of value, yaml error: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal array into field Schema.items of type openapi3.Schema


Do we still have this issue? Do we need a story to fix this?

This issue was fixed once I started downloading the latest stable version rather than a snapshot.

I'll remove the comments

joeluong-sfcc

Just minor comments, but otherwise LGTM

joeluong-sfcc · 2025-06-17T15:23:59Z

testIntegration/tests/userAgent.test.ts

    });
    await client.authorizeCustomer({
-      body: {},
+      parameters: params,


Just to clarify this change, we're now using authorizeCustomer from ShopperLogin instead of from ShopperCustomers and it expects a parameters object instead of a request body?

That's correct

joeluong-sfcc · 2025-06-17T15:27:34Z

testIntegration/tests/slasHelper.test.ts

-    const tokenResponse = await slasHelpers.loginGuestUser(slasClient, {
-      redirectURI: "redirect_uri",
-    });
+    // TODO: Using 'as any' to avoid type errors betwen the enum 'code' and the string 'code'. This should be fixed in the future.


I think we can add this as an AC to the refactor node SDK ticket (@W-18136408@) or we can create a new ticket for fixing all the tests

joeluong-sfcc · 2025-06-17T15:33:05Z

src/lib/utils.ts

-      `category:"CC API Family" = "${apiFamily}"`,
-      deployment
+      `"${apiFamily}" category:Visibility = "External" category:"SDK Type" = "Commerce"`,
+      undefined,


[NIT] can we add a small comment on why we passed undefined as it's not immediately clear unless you understand the search method

vcua-mobify · 2025-06-17T18:49:15Z

Thanks for the inputs @unandyala and @joeluong-sfcc . I'll merge this PR and will open a follow up PR shortly to address the remaining comments and get the contents of the apis directory updated from raml to oas

vcua-mobify added 2 commits May 22, 2025 18:01

prep scripts

121441f

Add support for downloading OAS files via raml-toolkit

95744ba

vcua-mobify changed the title ~~@W-18575180@ WIP - DO NOT MERGE - Generate node SDK from OAS~~ @W-18575180@ WIP - DO NOT MERGE - Download OAS spec for node sdk May 23, 2025

vcua-mobify changed the base branch from main to feature/oas May 27, 2025 16:38

vcua-mobify added 14 commits May 28, 2025 16:50

Update api families

1a6be2a

Download cdn-api

1bae476

Generate SDK from OAS

35c2828

Include types and index

a7a44cb

Fix tests and lint

c3b4c85

Update anypoint exchange search parameters

91b1886

Download all OAS specs

2da8879

Bump typescript and ts-node version

52ed46c

Move types.ts

e100d66

Fix oneOf issue in generated files missing imports

3e0dc5f

Set name for SlasAdmin api

9cc409a

allow delete to be used as function name by openapi generator

fbc131e

Update commands and typedoc dependencies

3ad83a5

Remove raml generator files

65ec2fc

vcua-mobify closed this Jun 6, 2025

vcua-mobify force-pushed the oas-support branch from f513912 to 1c729a9 Compare June 6, 2025 19:19

Merge branch 'oas-support' of https://github.com/vcua-mobify/commerce…

6815191

…-sdk into oas-support

vcua-mobify reopened this Jun 6, 2025

vcua-mobify added 7 commits June 6, 2025 12:36

Cleanup fork

94d281d

More cleanup

3c7141f

More cleanup

23aa529

Update .nycrc.json

c84aba2

bump typescript version

4a69e2f

Add missing shopper apis

91f40e2

Camel case and handle baskets v2

9f2fe25

Delete openapitools.json

0252bda

unandyala reviewed Jun 10, 2025

View reviewed changes

vcua-mobify added 8 commits June 10, 2025 15:24

Remove unused handlebars templates

e9e9d62

Update comments for api family

a0b2735

Remove unused asset object map

3541481

Remove skipLibCheck

fd3aa05

Add more api name workarounds

1821845

Pin nested dependency version to resolve ts lib check errors

48f70bf

Return only directories with exchange.json

cc4a92d

Dynamic version for user agent

ddc3789

joeluong-sfcc requested changes Jun 12, 2025

View reviewed changes

package.json Outdated Show resolved Hide resolved

yarn.lock Outdated Show resolved Hide resolved

src/generate-oas.ts Show resolved Hide resolved

src/generate-oas.ts Show resolved Hide resolved

src/generate-oas.ts Outdated Show resolved Hide resolved

joeluong-sfcc reviewed Jun 12, 2025

View reviewed changes

templatesOas/index.mustache Outdated Show resolved Hide resolved

vcua-mobify added 4 commits June 12, 2025 17:41

Fix tests and helpers

ba7f016

Use npm instead of yarn

18a9bf1

Re-add depcheck and change catalog name

5ea68fe

Add new dependency required to run tests in npm

e482d92

vcua-mobify commented Jun 13, 2025

View reviewed changes

vcua-mobify requested review from joeluong-sfcc and unandyala June 13, 2025 23:11

vcua-mobify added 2 commits June 16, 2025 12:08

Fix depcheck and renderTemplates

5e14dc0

More test adjustments

33a8049

vcua-mobify commented Jun 16, 2025

View reviewed changes

Remove staging api from config

935d536

unandyala approved these changes Jun 17, 2025

View reviewed changes

joeluong-sfcc approved these changes Jun 17, 2025

View reviewed changes

vcua-mobify merged commit 9dee573 into SalesforceCommerceCloud:feature/oas Jun 17, 2025
5 checks passed

vcua-mobify mentioned this pull request Jun 17, 2025

@W-17701719@ Replace raml files with oas #420

Merged

Conversation

vcua-mobify commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vcua-mobify commented Jun 6, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

joeluong-sfcc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unandyala left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joeluong-sfcc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vcua-mobify commented Jun 17, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vcua-mobify commented May 23, 2025 •

edited

Loading