@W-18349405@ Download and generate multiple versions of ShopperBaskets by vcua-mobify · Pull Request #198 · SalesforceCommerceCloud/commerce-sdk-isomorphic

vcua-mobify · 2025-06-05T21:44:02Z

This PR contains the following changes to support handling both ShopperBaskets v1 and v2:

An update to allow the generatre-oas script to look into subdirectories for exchange.json files.

With this change, we can now look for the exchange.json files in the following directory structure:

shopper-baskets
- shopper-baskets-v1
  - exchange.json
- shopper-baskets-v2
  - exchange.json

Updates to how information is extracted from exchange.json + handling the API name for both ShopperBasketsV1 and ShopperBasketsV2

A fix to handle -internal vs -public OAS files. The generator will only consider -internal files.
A template adjustment to handle differences in ShopperProductQueryParameters between getProduct and getProducts (Thanks @joeluong-sfcc for this!)
A test update following the change to allow unknown query parameters.
Update to api versions + a manual fix to x-sdk-classname format.

Testing these changes:
Generate the SDk with npm run renderTemplates

Run npm run test

Verify that all tests pass and that the generated SDK has no errors (areas to look at would be ShopperBaskets V1 / V2, ShopperProducts, ShopperContexts, and the top level index.ts)

alexvuong · 2025-06-16T17:52:49Z

scripts/generate-oas.ts

+
+    // Special handling for shopper-baskets-v2
+    if (
+      exchangeConfig.assetId === 'shopper-baskets-oas' &&


Can we be a bit generic for all apis ? If other apis happen to have version 2, we have to come back and manually fix this?

That's fair. We can update this so that if apiVersion is v2, then append v2 to the various names

alexvuong · 2025-06-16T17:56:48Z

src/static/helpers/slasHelper.test.ts

-      refreshToken: 'refresh_token',
-      response_type: 'code',
-      usid: 'usid',
+    const unexpectedQueryParams = {


Dumb question, why do we need to change this test?

This test fix addresses a change that was made to for allowing any query parameters through: #196

Rather than check for expected options, I think it's better we assert that the code challenge wasn't included. That way, if new non-breaking options appear in the future, this test will continue to work.

alexvuong · 2025-06-16T17:57:18Z

scripts/utils.ts

+  const matchedApis = await download.search(
+    `"${name}" category:Visibility = "External" category:"SDK Type" = "Commerce"  category:"SDK Type" = "Isomorphic"`,
+    undefined,
+    true


I assumed the search has error handling?

This is applying a subset of the changes from #200.

It may be better for us to merge the changes from @unandyala first then add this one after

The changes from #200 are in

vcua-mobify · 2025-06-16T23:20:23Z

scripts/generate-oas.ts

        outputDir: `${outputDir}`,
        templateDir: `${TEMPLATE_DIRECTORY}`,
-        skipValidateSpec: true,
+        flags: `--reserved-words-mappings delete=delete`,


This is needed to address some naming collisions around the delete methods that are generated for the SDK

What does skipValidateSpec do? Do we not want to include it alongside the new flags?

Also what naming collisions do we have with the delete keyword? Or is it just to bring it in alignment with the node SDK

skipValidateSpec was an argument I was passing in the early days of this work to force the generator to run even when there were errors in the oas spec (back when I was pulling down snapshots rather than stable versions of the specs).

We don't need to set it now that we're downloading stable versions of the spec but the setup allows us to add it again in the future.

can you add a comment explaining the delete flag

joeluong-sfcc

Correct me if I'm wrong, but it seems like the main change is we use a new helper function that recursively goes through the api directory and collects all the sub directories with an exchange.json file into an array

LGTM

joeluong-sfcc · 2025-06-17T16:29:25Z

scripts/generate-oas.ts

        outputDir: `${outputDir}`,
        templateDir: `${TEMPLATE_DIRECTORY}`,
-        skipValidateSpec: true,
+        flags: `--reserved-words-mappings delete=delete`,


What does skipValidateSpec do? Do we not want to include it alongside the new flags?

Also what naming collisions do we have with the delete keyword? Or is it just to bring it in alignment with the node SDK

vcua-mobify · 2025-06-18T17:01:43Z

@joeluong-sfcc , re: --reserved-words-mappings delete=delete, yes I was aligning the isomorphic and node sdks so that they used the same flags. We can adjust the flags though if we need to

unandyala · 2025-06-19T13:27:45Z

scripts/generate-oas.ts

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


Feels like this should be part of the search query parameter to the raml-toolkit downloader. I think it is fine for now. Can we create a followup ticket to make this change in raml-toolkit and remove this code from here?

New ticket W-18833027 created for this suggestion

unandyala · 2025-06-19T13:45:44Z

scripts/generate-oas.ts

+}
+
+export function resolveApiName(name: string, version: string): string {
+  if (name === 'Shopper Baskets OAS') {


Can we make this generic instead of hard-coding? That way any V2 api will be generated

I've modified the function to be more generic when appending V2. But I left the special case for appending V1 to ShopperBaskets specifically for now. We'll need to remove it if ShopperBasketsV1 is reverted to just ShopperBaskets by the IPA team.

unandyala · 2025-06-19T13:47:05Z

scripts/generate-oas.ts

        outputDir: `${outputDir}`,
        templateDir: `${TEMPLATE_DIRECTORY}`,
-        skipValidateSpec: true,
+        flags: `--reserved-words-mappings delete=delete`,


can you add a comment explaining the delete flag

unandyala · 2025-06-19T13:52:20Z

scripts/generate-oas.ts

  fs.writeFileSync(`${TARGET_DIRECTORY}/version.ts`, generatedVersion);
 }

+export function getAllDirectoriesWithExchangeFiles(


nit: rename to getAllApiDirectories as it is easy to understand? And add a doc for the function

unandyala · 2025-06-19T13:53:20Z

scripts/generate-oas.ts

+        : item;
+
+      if (fs.lstatSync(itemPath).isDirectory()) {
+        if (fs.existsSync(path.join(itemPath, 'exchange.json'))) {


nit: Add a comment "Only directories with exchange.json are considered as valid APIs"

joeluong-sfcc · 2025-06-19T14:49:15Z

apis/shopper-baskets-oas-1.8.23/shopper-baskets-oas-v1-internal.yaml

+            price: 20.99
+          - description: Order received the next business day
+            id: '003'
+            name: Overn


Wait, was this a manual change or did the IPA team add this?

If it's the IPA team, we'll have to ask them to revert this as we probably just want the classname to be ShopperBaskets as its the default right?

IPA team made this change to set the x-sdk-classname to ShopperBaskets v1.

unandyala · 2025-06-19T20:18:43Z

scripts/generate-oas.ts

  }
-  return name.replace(/\s+/g, '').replace('OAS', '');
+
+  return version !== 'v1' ? apiName + version.toUpperCase() : apiName;


This seem to be opposite of what you are doing for Shopper Baskets? Why do we need this?

This was my adjustment to allow for a more generic v2 as per your comment above.

Here, if apiVersion in exchange.json is v1, we don't append V1. This results in just the api name being returned. Ie. ShopperProducts

If the apiVersion in exchange.json is v2, this returns ShopperProductsV2.

ShopperBaskets is a special case where the API team have set x-sdk-classname to ShopperBasketsV1 in the -internal OAS spec. So the API name returned here has to match that (ie. ShopperBasketsV1) since the imports in the top level index.ts are generated using these API names by Handlebars rather than produced by the OAS generator.

We don't want to append V1 to other APIs (ie. we don't want ShopperProductsV1).

vcua-mobify added 2 commits June 5, 2025 12:50

Fix tests after change to allow unknown query parameters to api

653c401

add ability to check subdirectories for exchange.json files

ba489c4

vcua-mobify requested review from joeluong-sfcc and unandyala June 5, 2025 21:44

vcua-mobify changed the base branch from main to feature/oas June 5, 2025 21:44

vcua-mobify mentioned this pull request Jun 6, 2025

Fix: Isomorphic OAS SDK gaps (@W-18669767@) #197

Merged

vcua-mobify marked this pull request as ready for review June 10, 2025 19:45

vcua-mobify requested a review from a team as a code owner June 10, 2025 19:45

vcua-mobify and others added 3 commits June 11, 2025 14:38

Merge branch 'feature/oas' into include-nested-api-directories

302c543

Download both ShopperBaskets v1 and v2

4c8c86c

Push directory changes for APIs

ac5ac05

vcua-mobify changed the title ~~Include nested api directories~~ @W-18349405@ Download and generate multiple versions of ShopperBaskets Jun 13, 2025

alexvuong mentioned this pull request Jun 14, 2025

W 18764378/oasdiff on multi vers of api SalesforceCommerceCloud/raml-toolkit#233

Merged

alexvuong reviewed Jun 16, 2025

View reviewed changes

vcua-mobify commented Jun 16, 2025

View reviewed changes

joeluong-sfcc approved these changes Jun 17, 2025

View reviewed changes

vcua-mobify added 6 commits June 17, 2025 17:17

Merge branch 'feature/oas' into include-nested-api-directories

90dc775

Apply more generic handling of api version

f9a9dc0

Remove comment

e8c8506

Update apis

c7d14bb

Manual fixes to x-sdk-classname

f643e61

Adjust test

5d72525

vcua-mobify requested review from alexvuong and joeluong-sfcc June 18, 2025 01:21

add fix for enum collision

ad3ffc4

unandyala reviewed Jun 19, 2025

View reviewed changes

joeluong-sfcc reviewed Jun 19, 2025

View reviewed changes

vcua-mobify and others added 3 commits June 19, 2025 12:37

Apply PR feedback

b81ab10

Bump API versions

fc2d2be

Merge branch 'feature/oas' into include-nested-api-directories

c2d4b29

joeluong-sfcc mentioned this pull request Jun 19, 2025

Feat: Support x-scapi-internal (@W-18760264@) #202

Merged

unandyala reviewed Jun 19, 2025

View reviewed changes

unandyala approved these changes Jun 19, 2025

View reviewed changes

vcua-mobify merged commit 88d2c83 into feature/oas Jun 19, 2025
4 of 6 checks passed

Conversation

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

Uh oh!

Uh oh!

alexvuong Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

vcua-mobify commented Jun 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

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!

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 Jun 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vcua-mobify commented Jun 5, 2025 •

edited

Loading

alexvuong Jun 16, 2025 •

edited

Loading

vcua-mobify Jun 19, 2025 •

edited

Loading

vcua-mobify Jun 19, 2025 •

edited

Loading