CEXT-6160: store commerce instance on association and expose retrieval helpers by vinayrao2000 · Pull Request #511 · adobe/aio-commerce-sdk

vinayrao2000 · 2026-06-09T16:48:39Z

Description

Adds a new feature that stores the Commerce instance details (Base URL + deployment type) when an app is associated with a Commerce instance, and exposes typed async helpers so any runtime action can call Commerce APIs without custom storage setup.

Two new helpers in @adobe/aio-commerce-lib-app:

Helper	Returns	Use when
`getCommerceInstance(params)`	`{ baseUrl, env }`	You need the raw stored values (URL/env)
`getCommerceClient(params)`	`AdobeCommerceHttpClient` (ready to call APIs)	You want to call Commerce APIs directly

Both throw AppNotAssociatedError if the app isn't currently associated.

Storage (via new ./system submodule in @adobe/aio-commerce-lib-config):

Two-layer pattern: state (cache) → files (persistent source of truth)
Generic getSystemConfigByKey / setSystemConfigByKey API — reusable for other "system-level" config beyond association
Key namespace: system.association for this feature

New runtime action auto-scaffolded into apps:

POST /association — store { commerceBaseUrl, commerceEnv } (called by App Management UI on associate)
DELETE /association — clear stored data (called on unassociate)

Related Issue

CEXT-6160

Motivation and Context

Before this change, every action that wanted to call Commerce APIs had to:

Read auth params from params
Read the base URL from env vars or a custom-managed config
Manually construct AdobeCommerceHttpClient
Handle missing config in every action

This pushed boilerplate and inconsistent storage patterns into every app. Customers had no standard way to know which Commerce instance their app was associated with at runtime.

After this change, one line in any action gets a configured client:

const client = await getCommerceClient(params)

The SDK owns where association data is stored (state + files), how it's read, and how it propagates from the association event to runtime actions.

How Has This Been Tested?

Unit tests (~1,865 tests passing across the monorepo):

lib-config: system-repository.test.ts covers set/get/clear, state-as-cache + files-as-source-of-truth, null clears, type safety
lib-app:
- app-not-associated-error.test.ts — class, message, options
- association-repository.test.ts — round-trip via system config
- actions/association.test.ts — router (POST/DELETE), validation, logger middleware
- index.test.ts — getCommerceInstance and getCommerceClient happy + error paths

Typecheck: clean across all 13 packages (pnpm typecheck)

Lint: clean (pnpm check:ci)

E2E (in commerce-app-purchase-approval demo app):

Associate via App Management UI → POST .../association → 200 OK
Invoke commerce-config-demo action → { associated: true, instance: { baseUrl, env }, clientType: "AdobeCommerceHttpClient" }
Unassociate via App Management UI → DELETE .../association → 204 No Content
Invoke demo action again → { associated: false, ... }
Re-associate after unassociate → flow works cleanly

Both helpers verified working end-to-end through deployed actions.

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have read the DEVELOPMENT document.
I have added tests to cover my changes.
All new and existing tests passed.

Changesets

aio-commerce-lib-app — minor (new helpers + new action; additive only)
aio-commerce-lib-config — minor (new ./system subpath export; additive only)

Affected packages

Package	Change type
`@adobe/aio-commerce-lib-app`	new public API: `getCommerceInstance`, `getCommerceClient`, `AppNotAssociatedError`, association runtime action + scaffolding template
`@adobe/aio-commerce-lib-config`	new public API: `./system` subpath export with `getSystemConfigByKey` / `setSystemConfigByKey`

…tion lifecycle

Drop the Associated prefix from the public helpers per Daniel's review feedback - cleaner, more discoverable API.

… CEXT-6160-commerce-system-config-on-association

Per Ivan's review feedback - 'not associated' is exceptional state, throwing keeps happy-path code clean without forcing null checks at every call site.

Per Daniel's review feedback - puts SDK-managed config under a system.* namespace, cleanly separated from user-defined configuration.* keys.

lib-config now exposes generic system config primitives (setSystemConfigByKey/getSystemConfigByKey), and lib-app has the typed association wrappers on top. Drops the delete operation - clearing is done by setting null.

Typed association helpers (setAssociationData, getAssociationData, clearAssociationData) live in lib-app per the layered design, not lib-config. lib-config only exposes the generic system config primitives.

lib-config provides persistence via lib-files with lib-state as a performance cache. Cache expiry triggers automatic re-fetch from files, so no TTL refresh logic is needed in our code.

Adds setSystemConfigByKey / getSystemConfigByKey primitives under modules/configuration/system/. Uses lib-files for persistent storage with lib-state as a performance cache. Passing null to set clears the entry. Exposed via the new @adobe/aio-commerce-lib-config/system subpath export. Domain-agnostic - operates purely on opaque keys and values. Will be used by lib-app's association module via the public subpath export.

- AppNotAssociatedError class (extends CommerceSdkErrorBase) - Internal association module: setAssociationData / getAssociationData / clearAssociationData (calls into lib-config system submodule) - Public root entrypoint: getCommerceInstance and getCommerceClient helpers, both throw AppNotAssociatedError when no data is stored - Add root export to package.json and tsdown.config.ts

- New association runtime action with POST / and DELETE / handlers, protected with require-adobe-auth: true - POST / accepts { commerceBaseUrl, commerceEnv } and stores it via the internal association module - DELETE / clears the stored data - Add association.js.template for app scaffolding - Update buildAppManagementExtConfig to deploy the association action alongside app-config (always deployed, no feature gating) - Update OpenAPI spec with the new POST /association and DELETE /association routes, bump info.version to 1.1.0 - Update test fixtures and config test expectations

- Unit tests for AppNotAssociatedError, association repository, public helpers (getCommerceInstance / getCommerceClient), and the association runtime action handlers (POST / and DELETE /) - changesets for minor bumps in lib-app and lib-config - Document the new helpers in lib-app usage.md

changeset-bot · 2026-06-09T16:48:43Z

🦋 Changeset detected

Latest commit: 305860a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@adobe/aio-commerce-lib-app	Minor
@adobe/aio-commerce-lib-config	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

oshmyheliuk · 2026-06-11T21:04:28Z

+  const logger = getLogger("@adobe/aio-commerce-lib-config:system-repository");
+  try {
+    const state = await getSharedState();
+    await state.put(key, payload);


Shouldn't we add a TTL here? As I know a default value is 24 hours

asalloum5 · 2026-06-12T09:05:02Z

+                      "enum": ["saas", "paas"]
+                    }
+                  },
+                  "required": ["baseUrl", "env"]


Is there a reason why the response body is different from the request body? I expected to see commerceBaseUrl or baseUrl in both.

obarcelonap · 2026-06-12T12:02:53Z

    "title": "App Management API",
    "description": "REST API for managing Adobe Commerce App Builder apps: resolving app configuration, managing configuration values, running the installation and uninstallation lifecycle, exposing the Admin UI SDK registration, and managing the scope tree.",
-    "version": "1.1.0",
+    "version": "1.1.1",


should be minor instead of patch

obarcelonap · 2026-06-12T12:05:46Z

+export async function main(params) {
+  try {
+    const client = await getCommerceClient(params);
+    return {


use preset ok() from the sdk

obarcelonap · 2026-06-12T12:06:05Z

+    };
+  } catch (error) {
+    if (error instanceof AppNotAssociatedError) {
+      return {


use preset badRequest from the sdk

obarcelonap · 2026-06-12T12:07:44Z

+      "The 'commerceBaseUrl' field must be a valid absolute URL (e.g., 'https://my-store.example.com')",
+    ),
+  ),
+  commerceEnv: v.picklist(["saas", "paas"]),


didn't we used flavour in other parts of the sdk? we should align this

obarcelonap · 2026-06-12T12:11:49Z

can you check if createCombinedStore can be used instead of implementing your own cache

vinayrao2000 added 20 commits May 19, 2026 18:10

CEXT-6160: store and expose Commerce system config during app associa…

9a7f23e

…tion lifecycle

CEXT-6160: add association-data spec

92644b9

address review feedback

9f2d51e

address review feedback

204f842

CEXT-6160: rename to getCommerceInstance/getCommerceClient

07a1aae

Drop the Associated prefix from the public helpers per Daniel's review feedback - cleaner, more discoverable API.

Merge branch 'main' of https://github.com/adobe/aio-commerce-sdk into…

9e3fef5

… CEXT-6160-commerce-system-config-on-association

CEXT-6160: throw AppNotAssociatedError instead of returning null

bd84bf8

Per Ivan's review feedback - 'not associated' is exceptional state, throwing keeps happy-path code clean without forcing null checks at every call site.

CEXT-6160: use system.association as storage key

ccd61de

Per Daniel's review feedback - puts SDK-managed config under a system.* namespace, cleanly separated from user-defined configuration.* keys.

CEXT-6160: split storage into generic + typed layers

0457e1e

lib-config now exposes generic system config primitives (setSystemConfigByKey/getSystemConfigByKey), and lib-app has the typed association wrappers on top. Drops the delete operation - clearing is done by setting null.

CEXT-6160: update spec to reference correct modules

42dfccc

Typed association helpers (setAssociationData, getAssociationData, clearAssociationData) live in lib-app per the layered design, not lib-config. lib-config only exposes the generic system config primitives.

CEXT-6160: clarify generic lib-config module and helper layering in spec

4eed582

CEXT-6160: document that system config bypasses scope tree

434ebe2

CEXT-6160: drop TTL refresh, document two-layer storage

2ffbd15

lib-config provides persistence via lib-files with lib-state as a performance cache. Cache expiry triggers automatic re-fetch from files, so no TTL refresh logic is needed in our code.

CEXT-6160: nest system module under configuration/

2b1c005

Merge branch 'main' into CEXT-6160-commerce-system-config-on-association

f80b47e

resloved conflicts in usage.md

034f895

github-actions Bot added with-changeset The PR contains a Changeset file. pkg: aio-commerce-lib-config Includes changes in `packages/aio-commerce-lib-config` pkg: aio-commerce-lib-app Includes changes in `packages/aio-commerce-lib-app` labels Jun 9, 2026

CEXT-6160: clarify association adoption docs for new vs existing apps

46ed932

oshmyheliuk reviewed Jun 10, 2026

View reviewed changes

Comment thread packages/aio-commerce-lib-app/docs/usage.md Outdated

CEXT-6160: resolve merge conflict in lib-app usage.md

f54668c

oshmyheliuk reviewed Jun 10, 2026

View reviewed changes

vinayrao2000 added 2 commits June 11, 2026 10:07

CEXT-6160: validate commerceBaseUrl as a URL in association schema

6ab289f

CEXT-6160: document system-repository helpers and read files directly

305860a

oshmyheliuk reviewed Jun 11, 2026

View reviewed changes

asalloum5 approved these changes Jun 12, 2026

View reviewed changes

obarcelonap reviewed Jun 12, 2026

View reviewed changes

obarcelonap mentioned this pull request Jun 12, 2026

CEXT-6269: Support Environment-Scoped Creation for Webhooks and Events Aligned with Business Configurations UX #510

Open

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CEXT-6160: store commerce instance on association and expose retrieval helpers#511

CEXT-6160: store commerce instance on association and expose retrieval helpers#511
vinayrao2000 wants to merge 24 commits into
mainfrom
CEXT-6160-commerce-system-config-on-association

vinayrao2000 commented Jun 9, 2026

Uh oh!

changeset-bot Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oshmyheliuk Jun 11, 2026

Uh oh!

asalloum5 Jun 12, 2026

Uh oh!

obarcelonap Jun 12, 2026

Uh oh!

obarcelonap Jun 12, 2026

Uh oh!

obarcelonap Jun 12, 2026

Uh oh!

obarcelonap Jun 12, 2026

Uh oh!

obarcelonap Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

vinayrao2000 commented Jun 9, 2026

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Types of changes

Checklist:

Changesets

Affected packages

Uh oh!

changeset-bot Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oshmyheliuk Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

asalloum5 Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

obarcelonap Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

obarcelonap Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

obarcelonap Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

obarcelonap Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

obarcelonap Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

changeset-bot Bot commented Jun 9, 2026 •

edited

Loading