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()`	`{ baseUrl, env }`	You need the raw stored values (URL/env)
`getCommerceClient(auth)`	`AdobeCommerceHttpClient` (ready to call APIs)	You want to call Commerce APIs directly

getCommerceInstance() takes no arguments — it reads directly from storage. getCommerceClient(auth) is composable: it accepts auth already resolved by the caller (via resolveAuthParams from @adobe/aio-commerce-lib-auth) and combines it with the stored base URL and deployment type. Both throw AppNotAssociatedError if the app isn't currently associated.

Storage (generic system-config primitives 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
Exported from the package root (no dedicated subpath). Rather than reimplementing the two-layer cache, they reuse configuration-repository's loadConfig / persistConfig / deleteConfig, parameterized by a separate system.* storage namespace
Key namespace: system.association for this feature, stored under system/{key}.json, kept distinct from Business Configuration's configuration.* / scope/ namespace

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, an action resolves auth once and gets a configured client:

const client = await getCommerceClient(resolveAuthParams(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-config.test.ts covers set/get/clear, state-as-cache + files-as-source-of-truth, null/undefined clears, corrupt-JSON fallback, type safety
lib-app:
- errors/app-not-associated-error.test.ts — class, message, options
- modules/association/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 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 root exports getSystemConfigByKey / setSystemConfigByKey; 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: root exports `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: dd4c61c

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

This PR includes changesets to release 11 packages

Name	Type
@adobe/aio-commerce-lib-app	Minor
@adobe/aio-commerce-lib-core	Minor
@adobe/aio-commerce-lib-config	Minor
@adobe/aio-commerce-lib-admin-ui	Patch
@adobe/aio-commerce-lib-api	Patch
@adobe/aio-commerce-lib-auth	Patch
@adobe/aio-commerce-lib-events	Patch
@adobe/aio-commerce-lib-webhooks	Patch
@adobe/aio-commerce-sdk	Patch
@aio-commerce-sdk/common-utils	Patch
@aio-commerce-sdk/scripting-utils	Patch

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

…stemConfigByKey

…ns doc

…ent to IMS, return 204 from POST /association

…urn 204 from POST /association

iivvaannxx · 2026-06-17T14:37:16Z

 Two helpers are exposed from the root entrypoint:

- `getCommerceClient(auth)` — returns a ready-to-use [`AdobeCommerceHttpClient`](../../aio-commerce-lib-api/docs/usage.md). Use this when you need to call the Commerce API. The base URL and flavor come from the stored association data; you supply the resolved auth credentials (resolve them with `resolveAuthParams` from [`@adobe/aio-commerce-lib-auth`](../../aio-commerce-lib-auth/docs/usage.md)).
+- `getCommerceClient(auth, fetchOptions?)` — returns a ready-to-use [`AdobeCommerceHttpClient`](../../aio-commerce-lib-api/docs/usage.md). Use this when you need to call the Commerce API. The base URL and flavor come from the stored association data; you supply the resolved IMS auth. App Management requires IMS, so this accepts only IMS auth: resolve params with `resolveImsAuthParams`, or pass an `ImsAuthProvider` built with `getImsAuthProvider` / `forwardImsAuthProvider` from [`@adobe/aio-commerce-lib-auth`](../../aio-commerce-lib-auth/docs/usage.md). The optional `fetchOptions` are forwarded to the underlying client (e.g. `headers`, `timeout`, `retry`).


A link to what fetchOptions is could be added. Not a blocker.

iivvaannxx · 2026-06-17T14:41:12Z

 import { AppNotAssociatedError } from "../errors/app-not-associated-error";
-import { getAssociationData } from "../modules/association/association-repository";
+import { getAssociationData } from "../management/association/association-repository";

 import type { CommerceHttpClientParams } from "@adobe/aio-commerce-lib-api";
-import type { AssociatedCommerceInstance } from "../modules/association/types";
+import type {
+  ImsAuthParams,
+  ImsAuthProvider,
+} from "@adobe/aio-commerce-lib-auth";
+import type { AssociatedCommerceInstance } from "../management/association/types";


Suggested change

import { AppNotAssociatedError } from "../errors/app-not-associated-error";

import { getAssociationData } from "../modules/association/association-repository";

import { getAssociationData } from "../management/association/association-repository";

import type { CommerceHttpClientParams } from "@adobe/aio-commerce-lib-api";

import type { AssociatedCommerceInstance } from "../modules/association/types";

import type {

ImsAuthParams,

ImsAuthProvider,

} from "@adobe/aio-commerce-lib-auth";

import type { AssociatedCommerceInstance } from "../management/association/types";

import { AppNotAssociatedError } from "#errors/app-not-associated-error";

import { getAssociationData } from "#management/association/association-repository";

import type { CommerceHttpClientParams } from "@adobe/aio-commerce-lib-api";

import type {

ImsAuthParams,

ImsAuthProvider,

} from "@adobe/aio-commerce-lib-auth";

import type { AssociatedCommerceInstance } from "#management/association/types";

iivvaannxx · 2026-06-17T14:42:41Z

+ * IMS auth: resolve params with `resolveImsAuthParams`, or pass an
+ * `ImsAuthProvider` built with `getImsAuthProvider` / `forwardImsAuthProvider`
+ * from `@adobe/aio-commerce-lib-auth`.


Maybe a bit too verbose, a JSDoc doesn't need to be a calc of docs.

iivvaannxx · 2026-06-17T14:53:30Z

+    expect(MockAdobeCommerceHttpClient).toHaveBeenCalledWith({
+      auth,
+      config: { baseUrl: data.baseUrl, flavor: "paas" },
+      fetchOptions,
+    });


For this test you don't need to assert it's called with auth and config, only fetchOptions. Keeps the test less likely to fail :)

iivvaannxx · 2026-06-17T14:55:01Z

+      mockGetSystemConfigByKey: vi.fn(async (key: string) =>
+        store.has(key) ? store.get(key) : null,
+      ),
+      mockSetSystemConfigByKey: vi.fn(async (key: string, value: unknown) => {
+        if (value === null || value === undefined) {
+          store.delete(key);
+        } else {
+          store.set(key, value);
+        }


Mocking this provides little to no-value, as these helpers are directly invoked from within the tested API. Again, the underlying storage layer would be a more correct mocking target.

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

vinayrao2000 added 5 commits June 12, 2026 11:46

CEXT-6160: test 500 path when association storage fails

80a7526

CEXT-6160: reuse CommerceSdkErrorBaseOptions in AppNotAssociatedError

8b61c1e

CEXT-6160: document 401/403 on association routes

4847086

CEXT-6160: use response presets and unwrap prose in usage.md

90f2491

CEXT-6160: invalidate system-config cache on write failure

0a4de5c

github-actions Bot added the pkg: aio-commerce-lib-core Includes changes in `packages/aio-commerce-lib-core` label Jun 12, 2026

vinayrao2000 added 4 commits June 16, 2026 00:54

CEXT-6160: move runtime helpers to access module

b2409d9

CEXT-6160: make getCommerceClient composable, drop unused param

bf31144

CEXT-6160: keep AppNotAssociatedError options as a named seam

04b6559

CEXT-6160: reuse configuration-repository for system config storage

de6e29f

github-actions Bot added the spec Includes changes in `specs/features` label Jun 16, 2026

iivvaannxx reviewed Jun 16, 2026

View reviewed changes

vinayrao2000 added 16 commits June 16, 2026 09:41

CEXT-6160: restore caching-failure comment in configuration-repository

b290319

CEXT-6160: read config file directly instead of list-then-read

5e948fe

CEXT-6160: bubble up persisted config delete errors

3f09333

CEXT-6160: reuse shared storage mocks in system-config tests

f1130a7

CEXT-6160: move SYSTEM_NAMESPACE into system-config and default getSy…

9b42d0e

…stemConfigByKey

CEXT-6160: add changeset for CommerceSdkErrorBaseOptions export

b83a64f

CEXT-6160: removed implementation detail from changeset

36fa0c9

CEXT-6160: split internal rationale out of AppNotAssociatedErrorOptio…

6d4c3c3

…ns doc

CEXT-6160: move association under management, restrict getCommerceCli…

871f7fb

…ent to IMS, return 204 from POST /association

CEXT-6160: harden getCommerceClient (IMS-only, fetch options) and ret…

cb74abd

…urn 204 from POST /association

CEXT-6160: address PR review feedback

8898984

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

8ff826d

CEXT-6160: use CommerceEnv from lib-core for association env

120de50

CEXT-6160: test association repository via round-trip storage

835cb89

CEXT-6160: rename stale index test to access/commerce-instance

0cc7dde

CEXT-6160: align spec with final association design

dd4c61c

iivvaannxx approved these changes Jun 17, 2026

View reviewed changes

iivvaannxx mentioned this pull request Jun 17, 2026

CEXT-6151: Add ACL admin UI schema and helper to check permissions #522

Merged

11 tasks

Conversation

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

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iivvaannxx Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

iivvaannxx Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

iivvaannxx Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

iivvaannxx Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

iivvaannxx Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vinayrao2000 commented Jun 9, 2026 •

edited

Loading

changeset-bot Bot commented Jun 9, 2026 •

edited

Loading