@adobe/aio-commerce-lib-app 1.6.0 → 1.8.0-alpha-20260717142750

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # @adobe/aio-commerce-lib-app
 
+## 1.8.0-alpha-20260717142750
+### Minor Changes
+
+
+
+- [#528](https://github.com/adobe/aio-commerce-sdk/pull/528) [`0bb7d15`](https://github.com/adobe/aio-commerce-sdk/commit/0bb7d150961f631116b1ac421124960b5b857896) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Add the optional `aclProtected` field to Admin UI grid columns, mass actions, and order view buttons. When `true`, Commerce auto-generates a per-app ACL resource for the component from `metadata.id` for role-based access control, matching the existing menu behaviour.
+
+
+
+- [#522](https://github.com/adobe/aio-commerce-sdk/pull/522) [`4396a64`](https://github.com/adobe/aio-commerce-sdk/commit/4396a647ad22dba063cdf03a16e04aef9387212f) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Add optional `aclProtected` field to Admin UI menu configuration. When `true`, Commerce auto-generates a per-app ACL resource from `metadata.id` for role-based menu access control.
+
+
+
+- [#561](https://github.com/adobe/aio-commerce-sdk/pull/561) [`e85bec4`](https://github.com/adobe/aio-commerce-sdk/commit/e85bec40f1eaa91dd6bb7bc6954b2ecfc3ea4029) Thanks [@jcuerdo](https://github.com/jcuerdo)! - New `publishEvent` export for publishing a configured I/O Event from a runtime action by provider key and event name as declared in `app.commerce.config.ts`. Provider and event resolution happens automatically from metadata stored at installation time.
+
+
+
+- [#511](https://github.com/adobe/aio-commerce-sdk/pull/511) [`caed6d5`](https://github.com/adobe/aio-commerce-sdk/commit/caed6d5cbc526bc980221a06a59542427752a1ab) Thanks [@vinayrao2000](https://github.com/vinayrao2000)! - Add helpers to retrieve the Commerce instance an app is associated with from any runtime action: `getCommerceInstance()` returns the stored instance data, and `getCommerceClient(auth)` returns a ready-to-use Commerce HTTP client built from that instance.
+
+
+
+- [#508](https://github.com/adobe/aio-commerce-sdk/pull/508) [`c36f825`](https://github.com/adobe/aio-commerce-sdk/commit/c36f825aff7329fc2831d8aaca032d17bbee373a) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Add support for Admin UI menus in `commerce/backend-ui/2` via `adminUi.menu`.
+
+
+
+- [#577](https://github.com/adobe/aio-commerce-sdk/pull/577) [`b8368e9`](https://github.com/adobe/aio-commerce-sdk/commit/b8368e93137d84c914d1b3f10591a39038801a4f) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Added `resolveIoEventCode` to compute an event's I/O Events event code from its app ID, name, and provider type, without needing to read it back from stored installation data.
+
+
+
+- [#551](https://github.com/adobe/aio-commerce-sdk/pull/551) [`a66f389`](https://github.com/adobe/aio-commerce-sdk/commit/a66f3892622584d27cd6b5d2fc633e15bf9942a8) Thanks [@asalloum5](https://github.com/asalloum5)! - The app installation flow now enables the Admin UI SDK in Commerce before registering the extension, so Admin UI extensions are served correctly after install.
+
+
+
+- [#510](https://github.com/adobe/aio-commerce-sdk/pull/510) [`ce7768e`](https://github.com/adobe/aio-commerce-sdk/commit/ce7768e0ddc6ca35ad6ccec60f584c8bb5a743f0) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Webhooks and events now accept an optional `env` array (`"paas"` / `"saas"`) to scope them to specific Commerce environments. Items without `env` apply everywhere; scoped items are only installed on matching environments, and an event provider left with no applicable events is skipped entirely. The `app-config` action also accepts an optional `commerceEnv` query param that returns business-config fields, webhooks, and events already filtered to that environment. The installation and `scope-tree` actions now validate `commerceEnv` against the supported values (`"paas"` / `"saas"`) instead of accepting any string; this only rejects values that were never valid in practice.
+
+
+
+- [#486](https://github.com/adobe/aio-commerce-sdk/pull/486) [`413da36`](https://github.com/adobe/aio-commerce-sdk/commit/413da36dcd83e5a41c194f5af50611097659e725) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Add support for Admin UI grid column extensions on `commerce/backend-ui/2`.
+
+
+
+- [#512](https://github.com/adobe/aio-commerce-sdk/pull/512) [`b259e61`](https://github.com/adobe/aio-commerce-sdk/commit/b259e61c05bcb7a025486d1515ce644fb6f4265b) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Remove `commerce/backend-ui/1` support and the `adminUiSdk` config key. Migrate to `adminUi` and `commerce/backend-ui/2`.
+  
+  **Migration:** Replace `adminUiSdk` in your `app.commerce.config.*` with the `adminUi` config key. See the updated `usage.md` for the new shape. The generated `src/commerce-backend-ui-1/` directory and its `pre-app-build` hook can be removed from your project.
+
+
+- [#492](https://github.com/adobe/aio-commerce-sdk/pull/492) [`ce63b2b`](https://github.com/adobe/aio-commerce-sdk/commit/ce63b2b46f7ef1f2f68780b13e52d1c13fd5fe6e) Thanks [@jcuerdo](https://github.com/jcuerdo)! - Support Admin UI SDK v2 mass actions. Declare mass actions under `adminUi` with explicit `type: "view"` (iframe) or `type: "worker"` (runtime action), support for notifications, and a unified `selectionLimit` across Order, Product, and Customer entities.
+
+
+
+- [#534](https://github.com/adobe/aio-commerce-sdk/pull/534) [`b33ad74`](https://github.com/adobe/aio-commerce-sdk/commit/b33ad741c30262279180496ab28a82516569a17f) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Uninstallation now removes exactly the resources that were created at install time, even when the app configuration has since changed. Installs created before this change fall back to the current request config. The installation/uninstallation status responses now include an optional `config` field recording what was applied.
+
+
+
+- [#548](https://github.com/adobe/aio-commerce-sdk/pull/548) [`7670e39`](https://github.com/adobe/aio-commerce-sdk/commit/7670e39ae3cdf1172d9d9f09f0f100c19966d5a0) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Implement initial web source scaffolding for projects with Admin UI view operations
+
+
+
+- [#506](https://github.com/adobe/aio-commerce-sdk/pull/506) [`a18d900`](https://github.com/adobe/aio-commerce-sdk/commit/a18d900771df65a025dde2146da8422f08c5e4ae) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Add `adminUi.order.viewButtons` support on `commerce/backend-ui/2`, with `type: "view"` (iframe) and `type: "worker"` (runtime action) variants.
+
+
+### Patch Changes
+
+
+
+- [#576](https://github.com/adobe/aio-commerce-sdk/pull/576) [`b0c86a5`](https://github.com/adobe/aio-commerce-sdk/commit/b0c86a512965a691b3497ff1c286249508297388) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Commerce and external event names are now validated to be non-empty and unique within each provider in `app.commerce.config.ts`.
+
+
+
+- [#525](https://github.com/adobe/aio-commerce-sdk/pull/525) [`2e40262`](https://github.com/adobe/aio-commerce-sdk/commit/2e402628f1cd21a85dfb7c8dc3660a454f1053c0) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Characters in `metadata.id` that are disallowed by the Commerce Eventing API, such as hyphens, are now normalized to underscores in the generated event code.
+
+
+
+- [#528](https://github.com/adobe/aio-commerce-sdk/pull/528) [`0bb7d15`](https://github.com/adobe/aio-commerce-sdk/commit/0bb7d150961f631116b1ac421124960b5b857896) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Grid column entries in `adminUi` config now reject unknown keys (strict validation), so a mistyped field such as `aclprotected` surfaces a validation error instead of being silently dropped — matching the existing behavior of mass actions and view buttons.
+
+
+
+- [#548](https://github.com/adobe/aio-commerce-sdk/pull/548) [`7670e39`](https://github.com/adobe/aio-commerce-sdk/commit/7670e39ae3cdf1172d9d9f09f0f100c19966d5a0) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - For static business configs, the `#app.commerce.config` alias now resolves to a generated ESM module that re-exports the app manifest, so generated runtime actions can import it directly without needing a JSON import attribute.
+
+- Updated dependencies [[`0bb7d15`](https://github.com/adobe/aio-commerce-sdk/commit/0bb7d150961f631116b1ac421124960b5b857896), [`4396a64`](https://github.com/adobe/aio-commerce-sdk/commit/4396a647ad22dba063cdf03a16e04aef9387212f), [`c15b50f`](https://github.com/adobe/aio-commerce-sdk/commit/c15b50f667e6d1288270dbd4192c150db0ff0914), [`c36f825`](https://github.com/adobe/aio-commerce-sdk/commit/c36f825aff7329fc2831d8aaca032d17bbee373a), [`bdcced9`](https://github.com/adobe/aio-commerce-sdk/commit/bdcced9297ae5e1b87ce86490a2b6fad76b2e341), [`19400fb`](https://github.com/adobe/aio-commerce-sdk/commit/19400fbdfc03c5bbfc30f995a2acdd4272c5e032), [`e85bec4`](https://github.com/adobe/aio-commerce-sdk/commit/e85bec40f1eaa91dd6bb7bc6954b2ecfc3ea4029), [`a66f389`](https://github.com/adobe/aio-commerce-sdk/commit/a66f3892622584d27cd6b5d2fc633e15bf9942a8), [`ce7768e`](https://github.com/adobe/aio-commerce-sdk/commit/ce7768e0ddc6ca35ad6ccec60f584c8bb5a743f0), [`4396a64`](https://github.com/adobe/aio-commerce-sdk/commit/4396a647ad22dba063cdf03a16e04aef9387212f), [`e85bec4`](https://github.com/adobe/aio-commerce-sdk/commit/e85bec40f1eaa91dd6bb7bc6954b2ecfc3ea4029), [`413da36`](https://github.com/adobe/aio-commerce-sdk/commit/413da36dcd83e5a41c194f5af50611097659e725), [`a5b6d61`](https://github.com/adobe/aio-commerce-sdk/commit/a5b6d6138d5f048426ef655c4dc37f470aa74e2b), [`413da36`](https://github.com/adobe/aio-commerce-sdk/commit/413da36dcd83e5a41c194f5af50611097659e725), [`ca2c4fe`](https://github.com/adobe/aio-commerce-sdk/commit/ca2c4febcdfbe52b933775f08e9a53765fc306ab), [`ce63b2b`](https://github.com/adobe/aio-commerce-sdk/commit/ce63b2b46f7ef1f2f68780b13e52d1c13fd5fe6e), [`caed6d5`](https://github.com/adobe/aio-commerce-sdk/commit/caed6d5cbc526bc980221a06a59542427752a1ab), [`19400fb`](https://github.com/adobe/aio-commerce-sdk/commit/19400fbdfc03c5bbfc30f995a2acdd4272c5e032)]:
+  - @adobe/aio-commerce-lib-admin-ui@0.2.0-alpha-20260717142750
+  - @adobe/aio-commerce-lib-core@1.2.0-alpha-20260717142750
+  - @adobe/aio-commerce-lib-events@1.3.0-alpha-20260717142750
+  - @adobe/aio-commerce-lib-api@1.3.0-alpha-20260717142750
+  - @adobe/aio-commerce-lib-auth@1.1.2-alpha-20260717142750
+  - @adobe/aio-commerce-lib-config@1.6.0-alpha-20260717142750
+  - @adobe/aio-commerce-lib-webhooks@1.2.0-alpha-20260717142750
+
+## 1.7.0
+
+### Minor Changes
+
+- [#481](https://github.com/adobe/aio-commerce-sdk/pull/481) [`cffcc6a`](https://github.com/adobe/aio-commerce-sdk/commit/cffcc6af58c734486de4447c1f1eaa7a4784a4e2) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Introduce a new `GET /openapi.json` for `lib-app` in `app-config`.
+
+- [#471](https://github.com/adobe/aio-commerce-sdk/pull/471) [`82adf80`](https://github.com/adobe/aio-commerce-sdk/commit/82adf8002e693166fe0d285f9b901750dbad2f5e) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Default generated actions to `nodejs:24`, the latest App Builder Runtime version with prewarm support.
+
+### Patch Changes
+
+- [#489](https://github.com/adobe/aio-commerce-sdk/pull/489) [`d227e47`](https://github.com/adobe/aio-commerce-sdk/commit/d227e475ec0b513ca06e4e7950497b2a20ee4674) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Refactor Admin UI SDK extension registration and unregistration to use `@adobe/aio-commerce-lib-admin-ui` client instead of raw HTTP calls.
+
+- [#481](https://github.com/adobe/aio-commerce-sdk/pull/481) [`cffcc6a`](https://github.com/adobe/aio-commerce-sdk/commit/cffcc6af58c734486de4447c1f1eaa7a4784a4e2) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Fix `scopes` body validation in the scope tree action to use the proper recursive `CustomScopeInput` schema instead of `v.any()`.
+
+- [#495](https://github.com/adobe/aio-commerce-sdk/pull/495) [`c8d8c3a`](https://github.com/adobe/aio-commerce-sdk/commit/c8d8c3a1f1279493d12bd1403e5fd71f18ee9dc1) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Fix an issue where developers could not define custom installation scripts via `module.exports` when using CJS.
+
+- [#481](https://github.com/adobe/aio-commerce-sdk/pull/481) [`cffcc6a`](https://github.com/adobe/aio-commerce-sdk/commit/cffcc6af58c734486de4447c1f1eaa7a4784a4e2) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Return `400` instead of `500` when a custom scope tree fails validation (reserved or duplicate scope codes, invalid fields).
+
+- Updated dependencies [[`f6aec01`](https://github.com/adobe/aio-commerce-sdk/commit/f6aec01a22ed185fe130170751353fae881c0f2d), [`9b41376`](https://github.com/adobe/aio-commerce-sdk/commit/9b413761fd857a2e75c3f5210efb83ce2b1b4b6e), [`d227e47`](https://github.com/adobe/aio-commerce-sdk/commit/d227e475ec0b513ca06e4e7950497b2a20ee4674)]:
+  - @adobe/aio-commerce-lib-webhooks@1.1.2
+  - @adobe/aio-commerce-lib-config@1.5.1
+  - @adobe/aio-commerce-lib-admin-ui@0.1.0
+
 ## 1.6.0
 
 ### Minor Changes

package/dist/cjs/actions/app-config/index.cjs

@@ -0,0 +1,205 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_rolldown_runtime = require('../../rolldown-runtime-Cozy-1ZF.cjs');
+const require_environment = require('../../environment-B7EnozSg.cjs');
+const require_validate = require('../../validate-C_eCKp21.cjs');
+const require_router = require('../../router-hA_Y9gZ1.cjs');
+let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
+let valibot = require("valibot");
+valibot = require_rolldown_runtime.__toESM(valibot, 1);
+let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
+let crypto = require("crypto");
+
+//#region source/actions/app-config/openapi.ts
+/**
+* Loads the committed OpenAPI spec via dynamic import so it
+* lands in its own chunk and is not parsed on every cold start.
+*/
+const importOpenApi = () => Promise.resolve().then(() => require("../../openapi-CwytYdWl.cjs"));
+/** Matches component schema `$ref` strings, capturing the schema name. */
+const SCHEMA_REF_PATTERN = /"#\/components\/schemas\/(\w+)"/g;
+/**
+* Collects the names of every component schema referenced via `$ref` in a value
+* Scans the serialized JSON, so it catches refs at any depth.
+*
+* @param value - Any part of the spec to scan.
+*/
+function collectSchemaRefs(value) {
+	return [...(JSON.stringify(value) ?? "").matchAll(SCHEMA_REF_PATTERN)].map((match) => match[1]);
+}
+/**
+* Deletes component schemas not reachable from the remaining paths, in place.
+*
+* Follows `$ref`s transitively from `spec.paths`; the visited set handles
+* recursive schemas (e.g. `ScopeNode`).
+*
+* @param spec - The spec to prune, after paths have been stripped.
+*/
+function pruneUnusedSchemas(spec) {
+	const schemas = spec.components.schemas;
+	const reachable = new Set(collectSchemaRefs(spec.paths));
+	const pending = [...reachable];
+	while (pending.length > 0) {
+		const name = pending.pop();
+		if (name === void 0) continue;
+		for (const ref of collectSchemaRefs(schemas[name])) if (!reachable.has(ref)) {
+			reachable.add(ref);
+			pending.push(ref);
+		}
+	}
+	for (const name of Object.keys(schemas)) if (!reachable.has(name)) delete schemas[name];
+}
+/**
+* Removes top-level tags no longer referenced by any remaining path operation, in place.
+* @param spec - The spec to prune, after paths have been stripped.
+*/
+function pruneUnusedTags(spec) {
+	const usedTags = /* @__PURE__ */ new Set();
+	for (const pathItem of Object.values(spec.paths)) for (const operation of Object.values(pathItem)) for (const tag of operation.tags ?? []) usedTags.add(tag);
+	for (let i = spec.tags.length - 1; i >= 0; i -= 1) if (!usedTags.has(spec.tags[i].name)) spec.tags.splice(i, 1);
+}
+/**
+* Computes a short hash identifying the spec served for the given config domains.
+* Changes whenever the served spec would: with the OpenAPI spec version (`info.version`),
+* the package version, or the domains that drive pruning.
+*
+* @param domains - The active config domains.
+*/
+function getOpenApiCacheKey(domains) {
+	const input = `1.8.0-alpha-20260717142750:${[...domains].sort().join(",")}:2.0.0`;
+	return (0, crypto.createHash)("sha256").update(input).digest("hex").slice(0, 8);
+}
+/** Returns the server URL to be set in the OpenAPI spec, based on the current namespace. */
+function getServerUrl() {
+	return `https://${process.env.__OW_NAMESPACE}.adobeioruntime.net/api/v1/web/app-management`;
+}
+/**
+* Builds the OpenAPI spec served by `GET /openapi.json`, tailored to the app's
+* capabilities: unused paths are stripped, along with the schemas they leave
+* unreferenced.
+*
+* Works on a fresh copy so the shared module import is never mutated. The
+* committed `docs/openapi.json` always describes the full surface.
+*
+* @param domains - The active config domains that drive path trimming.
+* @param logger - Logger used to report which paths get stripped.
+*/
+async function buildOpenApiSpec(domains, logger) {
+	const { default: openAPISpec } = await importOpenApi();
+	const spec = structuredClone(openAPISpec);
+	const stripPath = (path) => {
+		if (spec.paths[path]) {
+			logger.debug(`Stripping OpenAPI spec path: ${path}`);
+			delete spec.paths[path];
+		}
+	};
+	if (!domains.has("businessConfig.schema")) {
+		logger.debug("Application doesn't define business configuration, stripping references...");
+		stripPath("/config");
+		stripPath("/scope-tree");
+		stripPath("/scope-tree/commerce");
+	}
+	if (!require_validate.requiresInstallationFromDomains(domains)) {
+		logger.debug("Application doesn't require installation, stripping references...");
+		stripPath("/installation");
+		stripPath("/installation/validation");
+		stripPath("/installation/uninstallation");
+	}
+	pruneUnusedSchemas(spec);
+	pruneUnusedTags(spec);
+	spec.servers[0].url = getServerUrl();
+	return spec;
+}
+
+//#endregion
+//#region source/actions/app-config/router.ts
+/**
+* App Config action router.
+*
+* Routes:
+* - GET /               Retrieve the Commerce App configuration.
+* - GET /openapi.json   Returns the OpenAPI spec for all SDK actions
+*/
+const router = new require_router.HttpActionRouter().use(require_router.logger({ name: () => "app-config" }));
+/** GET / - Get app config */
+router.get("/", {
+	handler: async (req, { logger, rawParams }) => {
+		const rawAppConfig = rawParams.appConfig;
+		if (!rawAppConfig) return (0, _adobe_aio_commerce_lib_core_responses.internalServerError)("The app config is missing. Does the action receive it as a parameter?");
+		let appConfig = rawAppConfig;
+		if (require_validate.hasBusinessConfigSchema(rawAppConfig)) {
+			logger.debug("Resolving business config schema...");
+			const schema = await (0, _adobe_aio_commerce_lib_config.resolveBusinessConfigSchema)(rawAppConfig.businessConfig.schema, rawParams);
+			appConfig = {
+				...rawAppConfig,
+				businessConfig: {
+					...rawAppConfig.businessConfig,
+					schema
+				}
+			};
+		}
+		logger.debug("Validating app config...");
+		const validatedConfig = require_validate.validateCommerceAppConfig(appConfig);
+		logger.debug("Successfully validated the app config");
+		const { commerceEnv } = req.query;
+		const config = commerceEnv ? require_environment.filterAppConfigByEnv(validatedConfig, commerceEnv) : validatedConfig;
+		const domains = require_validate.getConfigDomains(rawParams.appConfig);
+		const openApiSpecUrl = `${getServerUrl()}/app-config/openapi.json?ck=${getOpenApiCacheKey(domains)}`;
+		return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: {
+			...config,
+			openApiSpecUrl
+		} });
+	},
+	query: valibot.object({ commerceEnv: valibot.optional(_adobe_aio_commerce_lib_core_commerce.CommerceEnvSchema) })
+});
+/**
+* GET /openapi.json - Returns the OpenAPI spec for all SDK actions
+* @internal - Do not add to OpenAPI Spec.
+*/
+router.get("/openapi.json", {
+	handler: async (req, { logger, rawParams }) => {
+		const { ck } = req.query;
+		const domains = require_validate.getConfigDomains(rawParams.appConfig);
+		if (ck && getOpenApiCacheKey(domains) === ck) {
+			logger.debug(`Received request for OpenAPI spec with cache key query param: ${ck}`);
+			return (0, _adobe_aio_commerce_lib_core_responses.ok)({
+				body: await buildOpenApiSpec(domains, logger),
+				headers: { "Cache-Control": "public, max-age=31536000, immutable" }
+			});
+		}
+		return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: await buildOpenApiSpec(domains, logger) });
+	},
+	query: valibot.object({ ck: valibot.optional(valibot.string()) })
+});
+
+//#endregion
+//#region source/actions/app-config/index.ts
+/**
+* Factory to create the route handler for the `app-config` action.
+* @param args - The arguments required to create the runtime action.
+*/
+const appConfigRuntimeAction = (args) => async (params) => {
+	const handler = router.handler();
+	const { appConfig } = args;
+	return await handler({
+		...params,
+		appConfig
+	});
+};
+
+//#endregion
+exports.appConfigRuntimeAction = appConfigRuntimeAction;

package/dist/cjs/actions/{app-config.d.cts → app-config/index.d.cts}

@@ -12,17 +12,20 @@
  * governing permissions and limitations under the License.
  */
 
-import { t as CommerceAppConfig } from "../app-CakwxQvs.cjs";
+import { n as CommerceAppConfig } from "../../app-BwehWeu1.cjs";
 import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
 
-//#region source/actions/app-config.d.ts
-/** Arguments for the runtime action factory. */
+//#region source/actions/app-config/router.d.ts
+/** The arguments required to create the runtime action for the app-config action. */
 type RuntimeActionFactoryArgs = {
   appConfig: CommerceAppConfig;
 };
-/** Factory to create the route handler for the `app-config` action. */
-declare const appConfigRuntimeAction: ({
-  appConfig
-}: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion
+//#region source/actions/app-config/index.d.ts
+/**
+ * Factory to create the route handler for the `app-config` action.
+ * @param args - The arguments required to create the runtime action.
+ */
+declare const appConfigRuntimeAction: (args: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
 //#endregion
 export { appConfigRuntimeAction };

package/dist/cjs/actions/association/index.cjs

@@ -0,0 +1,85 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_rolldown_runtime = require('../../rolldown-runtime-Cozy-1ZF.cjs');
+const require_repository = require('../../repository-CbceYZqc.cjs');
+const require_router = require('../../router-hA_Y9gZ1.cjs');
+let valibot = require("valibot");
+valibot = require_rolldown_runtime.__toESM(valibot, 1);
+let _adobe_aio_commerce_lib_core_commerce = require("@adobe/aio-commerce-lib-core/commerce");
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
+
+//#region source/actions/association/schema.ts
+/** Request body for POST / — store association data. */
+const AssociationRequestBodySchema = valibot.object({
+	commerceBaseUrl: valibot.pipe(valibot.string(), valibot.url("The 'commerceBaseUrl' field must be a valid absolute URL (e.g., 'https://my-store.example.com')")),
+	commerceEnv: _adobe_aio_commerce_lib_core_commerce.CommerceEnvSchema
+});
+
+//#endregion
+//#region source/actions/association/router.ts
+/**
+* Association action router.
+*
+* Routes:
+* - POST /   Store Commerce instance details (`baseUrl`, `env`)
+* - DELETE / Clear stored Commerce instance details
+*/
+const router = new require_router.HttpActionRouter().use(require_router.logger({ name: () => "association" }));
+/**
+* POST / - Store association data.
+*
+* Persists the Commerce instance the app is associated with so runtime actions
+* can later retrieve it via `getCommerceInstance` / `getCommerceClient`.
+*/
+router.post("/", {
+	body: AssociationRequestBodySchema,
+	handler: async (req, { logger }) => {
+		const { commerceBaseUrl, commerceEnv } = req.body;
+		logger.debug(`Storing association data (baseUrl: "${commerceBaseUrl}", env: "${commerceEnv}")`);
+		await require_repository.setAssociationData({ commerce: {
+			baseUrl: commerceBaseUrl,
+			env: commerceEnv
+		} });
+		return (0, _adobe_aio_commerce_lib_core_responses.noContent)();
+	}
+});
+/**
+* DELETE / - Clear association data.
+*
+* Called when the app is unassociated.
+*/
+router.delete("/", { handler: async (_req, { logger }) => {
+	logger.debug("Clearing association data");
+	await require_repository.clearAssociationData();
+	return (0, _adobe_aio_commerce_lib_core_responses.noContent)();
+} });
+
+//#endregion
+//#region source/actions/association/index.ts
+/**
+* Factory to create the route handler for the `association` action.
+*
+* The `association` action manages the lifecycle of the Commerce instance the
+* app is associated with — `POST /` stores the data when the app is associated,
+* and `DELETE /` clears it on unassociation. Runtime actions consume the data
+* via `getCommerceInstance` / `getCommerceClient` from the root entrypoint.
+*/
+const associationRuntimeAction = () => async (params) => {
+	return await router.handler()({ ...params });
+};
+
+//#endregion
+exports.associationRuntimeAction = associationRuntimeAction;

package/dist/cjs/actions/association/index.d.cts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
+
+//#region source/actions/association/index.d.ts
+/**
+ * Factory to create the route handler for the `association` action.
+ *
+ * The `association` action manages the lifecycle of the Commerce instance the
+ * app is associated with — `POST /` stores the data when the app is associated,
+ * and `DELETE /` clears it on unassociation. Runtime actions consume the data
+ * via `getCommerceInstance` / `getCommerceClient` from the root entrypoint.
+ */
+declare const associationRuntimeAction: () => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion
+export { associationRuntimeAction };