@adobe/aio-commerce-lib-app 1.6.0 → 1.7.0

package/dist/cjs/{validate-DydOAZha.cjs → validate-oAOpyFyb.cjs}

@@ -15,8 +15,8 @@
 const require_chunk = require('./chunk-Cozy-1ZF.cjs');
 const require_schemas = require('./schemas-FngDuIeo.cjs');
 const require_webhooks = require('./webhooks-tbZy9G3p.cjs');
-let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
 let _adobe_aio_commerce_lib_core_error = require("@adobe/aio-commerce-lib-core/error");
+let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
 let valibot = require("valibot");
 valibot = require_chunk.__toESM(valibot, 1);
 
@@ -61,19 +61,6 @@ function hasMetadata(config) {
 	return config.metadata !== void 0;
 }
 
-//#endregion
-//#region source/config/schema/app.ts
-/** biome-ignore-all lint/performance/noBarrelFile: We want to have all the schema exports in one file. */
-/** The schema used to validate the commerce app config file. */
-const CommerceAppConfigSchema = valibot.looseObject({
-	metadata: MetadataSchema,
-	businessConfig: valibot.optional(_adobe_aio_commerce_lib_config.SchemaBusinessConfig),
-	eventing: valibot.optional(require_webhooks.EventingSchema),
-	adminUiSdk: valibot.optional(require_webhooks.AdminUiSdkSchema),
-	installation: valibot.optional(require_webhooks.InstallationSchema),
-	webhooks: valibot.optional(require_webhooks.WebhooksSchema)
-});
-
 //#endregion
 //#region source/config/schema/domains.ts
 /** The individual validatable domains of the app config. */
@@ -120,6 +107,39 @@ function hasConfigDomain(config, domain) {
 	return getConfigDomains(config).has(domain);
 }
 
+//#endregion
+//#region source/config/schema/app.ts
+/** biome-ignore-all lint/performance/noBarrelFile: We want to have all the schema exports in one file. */
+/** The schema used to validate the commerce app config file. */
+const CommerceAppConfigSchema = valibot.looseObject({
+	metadata: MetadataSchema,
+	businessConfig: valibot.optional(_adobe_aio_commerce_lib_config.SchemaBusinessConfig),
+	eventing: valibot.optional(require_webhooks.EventingSchema),
+	adminUiSdk: valibot.optional(require_webhooks.AdminUiSdkSchema),
+	installation: valibot.optional(require_webhooks.InstallationSchema),
+	webhooks: valibot.optional(require_webhooks.WebhooksSchema)
+});
+/**
+* Returns true if the given config domains require installation, false otherwise.
+* @param domains - The config domains to check.
+*/
+function requiresInstallationFromDomains(domains) {
+	return [
+		"installation.customInstallationSteps",
+		"eventing.commerce",
+		"eventing.external",
+		"webhooks",
+		"adminUiSdk"
+	].some((feature) => domains.has(feature));
+}
+/**
+* Returns true if the given config requires installation, false otherwise.
+* @param config - The commerce app config to check.
+*/
+function requiresInstallation(config) {
+	return requiresInstallationFromDomains(getConfigDomains(config));
+}
+
 //#endregion
 //#region source/config/lib/validate.ts
 const commerceAppConfigDomainsSchema = valibot.picklist(Object.keys(CommerceAppConfigSchemas));
@@ -243,6 +263,18 @@ Object.defineProperty(exports, 'hasMetadata', {
     return hasMetadata;
   }
 });
+Object.defineProperty(exports, 'requiresInstallation', {
+  enumerable: true,
+  get: function () {
+    return requiresInstallation;
+  }
+});
+Object.defineProperty(exports, 'requiresInstallationFromDomains', {
+  enumerable: true,
+  get: function () {
+    return requiresInstallationFromDomains;
+  }
+});
 Object.defineProperty(exports, 'validateCommerceAppConfig', {
   enumerable: true,
   get: function () {

package/dist/es/actions/app-config/index.d.mts

@@ -0,0 +1,31 @@
+/**
+ * @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 { n as CommerceAppConfig } from "../../app-DrYHK-z1.mjs";
+import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
+
+//#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;
+};
+//#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/es/actions/app-config/index.mjs

@@ -0,0 +1,199 @@
+/**
+ * @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 { i as requiresInstallationFromDomains, o as getConfigDomains, t as validateCommerceAppConfig, u as hasBusinessConfigSchema } from "../../validate-Dfajrp99.mjs";
+import { n as logger, t as HttpActionRouter } from "../../router-D58JJHHA.mjs";
+import { resolveBusinessConfigSchema } from "@adobe/aio-commerce-lib-config";
+import * as v from "valibot";
+import { internalServerError, ok } from "@adobe/aio-commerce-lib-core/responses";
+import { createHash } from "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 = () => import("../../openapi-B6uP0SRn.mjs");
+/** 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--) 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.7.0:${[...domains].sort().join(",")}:1.0.0`;
+	return 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 (!domains.has("adminUiSdk")) {
+		logger.debug("Application doesn't define Admin UI SDK registration, stripping references...");
+		stripPath("/registration");
+	}
+	if (!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 HttpActionRouter().use(logger({ name: () => "app-config" }));
+/** GET / - Get app config */
+router.get("/", { handler: async (_req, { logger, rawParams }) => {
+	const rawAppConfig = rawParams.appConfig;
+	if (!rawAppConfig) return internalServerError("The app config is missing. Does the action receive it as a parameter?");
+	let appConfig = rawAppConfig;
+	if (hasBusinessConfigSchema(rawAppConfig)) {
+		logger.debug("Resolving business config schema...");
+		const schema = await resolveBusinessConfigSchema(rawAppConfig.businessConfig.schema, rawParams);
+		appConfig = {
+			...rawAppConfig,
+			businessConfig: {
+				...rawAppConfig.businessConfig,
+				schema
+			}
+		};
+	}
+	logger.debug("Validating app config...");
+	const config = validateCommerceAppConfig(appConfig);
+	logger.debug("Successfully validated the app config");
+	const domains = getConfigDomains(rawParams.appConfig);
+	const openApiSpecUrl = `${getServerUrl()}/app-config/openapi.json?ck=${getOpenApiCacheKey(domains)}`;
+	return ok({ body: {
+		...config,
+		openApiSpecUrl
+	} });
+} });
+/**
+* GET /openapi.json - Returns the OpenAPI spec for all SDK actions
+* @internal - Do not add to OpenAPI Spec.
+*/
+router.get("/openapi.json", {
+	query: v.object({ ck: v.optional(v.string()) }),
+	handler: async (req, { logger, rawParams }) => {
+		const { ck } = req.query;
+		const domains = getConfigDomains(rawParams.appConfig);
+		if (ck && getOpenApiCacheKey(domains) === ck) {
+			logger.debug(`Received request for OpenAPI spec with cache key query param: ${ck}`);
+			return ok({
+				body: await buildOpenApiSpec(domains, logger),
+				headers: { "Cache-Control": "public, max-age=31536000, immutable" }
+			});
+		}
+		return ok({ body: await buildOpenApiSpec(domains, logger) });
+	}
+});
+
+//#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
+export { appConfigRuntimeAction };

package/dist/{cjs/actions/config.d.cts → es/actions/config/index.d.mts}

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

package/dist/es/actions/{config.mjs → config/index.mjs}

@@ -12,20 +12,50 @@
  * governing permissions and limitations under the License.
  */
 
-import { n as logger, t as HttpActionRouter } from "../router-D58JJHHA.mjs";
-import { r as nonEmptyStringValueSchema } from "../schemas-hRovglBF.mjs";
+import { r as nonEmptyStringValueSchema } from "../../schemas-hRovglBF.mjs";
+import { n as logger, t as HttpActionRouter } from "../../router-D58JJHHA.mjs";
 import { byScopeId, getConfiguration, initialize, setConfiguration } from "@adobe/aio-commerce-lib-config";
-import { ok } from "@adobe/aio-commerce-lib-core/responses";
 import * as v from "valibot";
+import { ok } from "@adobe/aio-commerce-lib-core/responses";
 
-//#region source/actions/config.ts
-const MASKED_PASSWORD_VALUE = "*****";
+//#region source/actions/config/schema.ts
+const AcceptedConfigurationValuesSchema = v.union([
+	v.boolean(),
+	v.string(),
+	v.array(v.string())
+]);
 /** The set of valid Commerce environments a configuration field can be scoped to. */
 const COMMERCE_ENVS = ["paas", "saas"];
+/** Query parameters for GET / */
+const GetConfigurationQuerySchema = v.object({
+	scopeId: nonEmptyStringValueSchema("scopeId"),
+	commerceEnv: v.optional(v.picklist(COMMERCE_ENVS))
+});
+/** Request body for PUT / */
+const PutConfigBodySchema = v.object({
+	scopeId: nonEmptyStringValueSchema("scopeId"),
+	config: v.array(v.object({
+		name: nonEmptyStringValueSchema("config[i].name"),
+		value: v.union([v.string(), v.array(v.string())])
+	}))
+});
+/** Request body for PATCH / */
+const PatchConfigBodySchema = v.object({
+	scopeId: nonEmptyStringValueSchema("scopeId"),
+	config: v.array(v.object({
+		name: nonEmptyStringValueSchema("config[i].name"),
+		value: v.nullable(AcceptedConfigurationValuesSchema)
+	}))
+});
+
+//#endregion
+//#region source/actions/config/router.ts
+const MASKED_PASSWORD_VALUE = "*****";
 /**
 * Filters a business configuration schema to the fields applicable to the
 * given Commerce environment. Fields without an `env` property apply to all
 * environments and are always included.
+*
 * @param schema - The business configuration schema to filter.
 * @param env - The Commerce environment to filter by.
 */
@@ -34,9 +64,9 @@ function filterSchemaByEnv(schema, env) {
 }
 /**
 * Filters password fields from the configuration values.
+*
 * @param schema - The schema to use to filter the values.
 * @param values - The values to filter.
-* @returns The filtered values.
 */
 function filterPasswordFields(schema, values) {
 	return values.map((item) => {
@@ -47,13 +77,18 @@ function filterPasswordFields(schema, values) {
 		return item;
 	});
 }
-const router = new HttpActionRouter().use(logger());
+/**
+* Config action router.
+*
+* Routes:
+* - GET /     Get current configuration values for a given scope
+* - POST /    Set configuration (overrides all values for the scope) (deprecated)
+* - PATCH /   Partially update configuration (only updates provided fields, allows unsetting)
+*/
+const router = new HttpActionRouter().use(logger({ name: () => "config" }));
 /** GET / - Retrieve configuration */
 router.get("/", {
-	query: v.object({
-		scopeId: nonEmptyStringValueSchema("scopeId"),
-		commerceEnv: v.optional(v.picklist(COMMERCE_ENVS))
-	}),
+	query: GetConfigurationQuerySchema,
 	handler: async (req, ctx) => {
 		const { logger, rawParams } = ctx;
 		const { configSchema: rawConfigSchema } = rawParams;
@@ -77,17 +112,12 @@ router.get("/", {
 });
 /**
 * PUT / - Set configuration (deprecated)
+*
 * @deprecated Use PATCH instead. This endpoint overwrites all values for the scope
 * and does not support partial updates or unset semantics.
 */
 router.put("/", {
-	body: v.object({
-		scopeId: nonEmptyStringValueSchema("scopeId"),
-		config: v.array(v.object({
-			name: nonEmptyStringValueSchema("config.name"),
-			value: v.union([v.string(), v.array(v.string())])
-		}))
-	}),
+	body: PutConfigBodySchema,
 	handler: async (req, ctx) => {
 		const { logger, rawParams } = ctx;
 		logger.debug(`Setting configuration with scope id: ${req.body.scopeId}`);
@@ -109,17 +139,7 @@ router.put("/", {
 });
 /** PATCH / - Partially update configuration */
 router.patch("/", {
-	body: v.object({
-		scopeId: nonEmptyStringValueSchema("scopeId"),
-		config: v.array(v.object({
-			name: nonEmptyStringValueSchema("config.name"),
-			value: v.nullable(v.union([
-				v.boolean(),
-				v.string(),
-				v.array(v.string())
-			]))
-		}))
-	}),
+	body: PatchConfigBodySchema,
 	handler: async (req, ctx) => {
 		const { logger, rawParams } = ctx;
 		logger.debug(`Patching configuration with scope id: ${req.body.scopeId}`);
@@ -136,9 +156,17 @@ router.patch("/", {
 		});
 	}
 });
-/** Factory to create the route handler for the `config` action. */
-const configRuntimeAction = ({ configSchema }) => async (params) => {
-	return await router.handler()({
+
+//#endregion
+//#region source/actions/config/index.ts
+/**
+* Factory to create the route handler for the `config` action.
+* @param args - The arguments required to create the runtime action.
+*/
+const configRuntimeAction = (args) => async (params) => {
+	const handler = router.handler();
+	const { configSchema } = args;
+	return await handler({
 		...params,
 		configSchema
 	});

package/dist/{cjs/actions/installation.d.cts → es/actions/installation/index.d.mts}

@@ -12,21 +12,23 @@
  * governing permissions and limitations under the License.
  */
 
-import { n as CommerceAppConfigOutputModel, t as CommerceAppConfig } from "../app-CakwxQvs.cjs";
-import { o as InstallationContext } from "../step-CKVE0aJi.cjs";
+import { n as CommerceAppConfig, r as CommerceAppConfigOutputModel } from "../../app-DrYHK-z1.mjs";
+import { Y as InstallationContext } from "../../index-DLMbTtKS.mjs";
 import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
 
-//#region source/actions/installation.d.ts
+//#region source/actions/installation/router.d.ts
 type CustomScriptsLoader = (config: CommerceAppConfigOutputModel, logger: InstallationContext["logger"]) => Record<string, unknown>;
 /** Arguments for the runtime action factory. */
 type RuntimeActionFactoryArgs = {
   appConfig: CommerceAppConfig;
   customScriptsLoader?: CustomScriptsLoader;
 };
-/** Factory to create the route handler for the `installation` action. */
-declare const installationRuntimeAction: ({
-  appConfig,
-  customScriptsLoader
-}: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
+//#endregion
+//#region source/actions/installation/index.d.ts
+/**
+ * Factory to create the route handler for the `installation` action.
+ * @param args - The arguments required to create the runtime action.
+ */
+declare const installationRuntimeAction: (args: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<import("@adobe/aio-commerce-lib-core/responses").ActionResponse>;
 //#endregion
 export { installationRuntimeAction };

package/dist/es/actions/{installation.mjs → installation/index.mjs}

@@ -12,13 +12,12 @@
  * governing permissions and limitations under the License.
  */
 
-import { n as logger, t as HttpActionRouter } from "../router-D58JJHHA.mjs";
-import { r as nonEmptyStringValueSchema } from "../schemas-hRovglBF.mjs";
-import { t as validateCommerceAppConfig } from "../validate-Du3LhCre.mjs";
-import { a as runValidation, c as isFailedState, i as runUninstallation, l as isInProgressState, n as createInitialUninstallationState, r as runInstallation, s as isCompletedState, t as createInitialInstallationState, u as isSucceededState } from "../management-BZ4Y6lVp.mjs";
-import { accepted, badRequest, conflict, internalServerError, noContent, ok } from "@adobe/aio-commerce-lib-core/responses";
+import { r as nonEmptyStringValueSchema } from "../../schemas-hRovglBF.mjs";
+import { a as runValidation, c as isFailedState, i as runUninstallation, l as isInProgressState, n as createInitialUninstallationState, r as runInstallation, s as isCompletedState, t as createInitialInstallationState, u as isSucceededState } from "../../management-BUX-w2Ji.mjs";
+import { t as validateCommerceAppConfig } from "../../validate-Dfajrp99.mjs";
+import { n as logger, t as HttpActionRouter } from "../../router-D58JJHHA.mjs";
 import * as v from "valibot";
-import { object, string } from "valibot";
+import { accepted, badRequest, conflict, internalServerError, noContent, ok } from "@adobe/aio-commerce-lib-core/responses";
 import { init } from "@adobe/aio-lib-files";
 import { init as init$1 } from "@adobe/aio-lib-state";
 import openwhisk from "openwhisk";
@@ -257,16 +256,19 @@ const AppDataSchema = v.object({
 });
 
 //#endregion
-//#region source/actions/installation.ts
-const DEFAULT_ACTION_NAME = "app-management/installation";
-/** Request body schema shared by POST / and POST /validation. */
-const InstallationRequestBodySchema = object({
+//#region source/actions/installation/schema.ts
+/** Request body for POST / and POST /validation (shared shape) */
+const InstallationRequestBodySchema = v.object({
 	appData: AppDataSchema,
-	commerceBaseUrl: string(),
-	commerceEnv: string(),
-	ioEventsUrl: string(),
-	ioEventsEnv: string()
+	commerceBaseUrl: v.string(),
+	commerceEnv: v.string(),
+	ioEventsUrl: v.string(),
+	ioEventsEnv: v.string()
 });
+
+//#endregion
+//#region source/actions/installation/router.ts
+const DEFAULT_ACTION_NAME = "app-management/installation";
 /** Creates a workflow state store with the given prefix. */
 function createWorkflowStore(prefix) {
 	return createCombinedStore({
@@ -349,14 +351,14 @@ function createInstallationHooks(store, logFn) {
 * Installation action router.
 *
 * Routes:
-* - GET /installation             - Get current installation status
-* - POST /installation            - Start installation (creates plan, invokes execution async)
-* - POST /installation/execution  - Execute installation (internal, called async)
-* - POST /installation/validation - Pre-installation validation
-* - POST /installation/uninstallation           - Start uninstallation (async)
-* - GET /installation/uninstallation            - Get current uninstallation status
-* - POST /installation/uninstallation/execution - Execute uninstallation (internal, called async)
-* - DELETE /installation/uninstallation         - Clear uninstallation state only (no offboarding)
+* - GET /                            Get current installation status
+* - POST /                           Start installation (creates plan, invokes execution async)
+* - POST /execution                  Execute installation (internal, called async)
+* - POST /validation                 Pre-installation validation
+* - POST /uninstallation             Start uninstallation (creates plan, invokes execution async)
+* - GET /uninstallation              Get current uninstallation status
+* - POST /uninstallation/execution   Execute uninstallation (internal, called async)
+* - DELETE /uninstallation           Clear uninstallation state only (no offboarding)
 */
 const router = new HttpActionRouter().use(logger({ name: () => "installation" }));
 /**
@@ -398,7 +400,7 @@ router.post("/", {
 			logger.debug("Previous installation failed, allowing retry");
 		}
 		const rawAppConfig = rawParams.appConfig;
-		if (!rawAppConfig) return internalServerError("Could not find or parse the app.commerce.manifest.json file, is it present and valid?");
+		if (!rawAppConfig) return internalServerError("The app config is missing. Does the action receive it as a parameter?");
 		const appConfig = validateCommerceAppConfig(rawAppConfig);
 		const initialState = createInitialInstallationState({ config: appConfig });
 		logger.debug(`Created initial state: ${initialState.id}`);
@@ -426,7 +428,8 @@ router.post("/", {
 	}
 });
 /**
-* POST /installation/execution - Execute installation (internal)
+* POST /installation/execution - Execute installation
+* @internal - Do not add to OpenAPI Spec.
 *
 * This endpoint is called asynchronously by POST /installation.
 * It runs the actual installation workflow and saves state.
@@ -473,7 +476,7 @@ router.post("/validation", {
 	handler: async (req, { logger, rawParams }) => {
 		logger.debug("Running pre-installation validation...");
 		const rawAppConfig = rawParams.appConfig;
-		if (!rawAppConfig) return internalServerError("Could not find or parse the app.commerce.manifest.json file, is it present and valid?");
+		if (!rawAppConfig) return internalServerError("The app config is missing. Does the action receive it as a parameter?");
 		const appConfig = validateCommerceAppConfig(rawAppConfig);
 		const { appData, ...params } = buildWorkflowParams(req.body, rawParams);
 		const result = await runValidation({
@@ -513,7 +516,7 @@ router.post("/uninstallation", {
 		const { appData, commerceBaseUrl } = req.body;
 		logger.debug(`Starting uninstallation for app "${appData.projectName}" (workspace: "${appData.workspaceName}", commerce: "${commerceBaseUrl}")`);
 		const rawAppConfig = rawParams.appConfig;
-		if (!rawAppConfig) return internalServerError("Could not find or parse the app.commerce.manifest.json file, is it present and valid?");
+		if (!rawAppConfig) return internalServerError("The app config is missing. Does the action receive it as a parameter?");
 		const appConfig = validateCommerceAppConfig(rawAppConfig);
 		const store = await createUninstallationStore();
 		const existingState = await store.get(getStorageKey());
@@ -546,7 +549,8 @@ router.post("/uninstallation", {
 	}
 });
 /**
-* POST /uninstallation/execution - Execute uninstallation (internal, called async by POST /uninstallation)
+* POST /uninstallation/execution - Execute uninstallation
+* @internal - Do not add to OpenAPI Spec.
 *
 * Flow:
 * 1. Build InstallationContext from params
@@ -595,9 +599,17 @@ router.delete("/uninstallation", { handler: async (_req, { logger }) => {
 	logger.debug("Uninstallation state cleared");
 	return noContent();
 } });
-/** Factory to create the route handler for the `installation` action. */
-const installationRuntimeAction = ({ appConfig, customScriptsLoader }) => async (params) => {
-	return await router.handler()({
+
+//#endregion
+//#region source/actions/installation/index.ts
+/**
+* Factory to create the route handler for the `installation` action.
+* @param args - The arguments required to create the runtime action.
+*/
+const installationRuntimeAction = (args) => async (params) => {
+	const handler = router.handler();
+	const { appConfig, customScriptsLoader } = args;
+	return await handler({
 		...params,
 		appConfig,
 		customScriptsLoader