@adobe/aio-commerce-lib-app 0.3.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @adobe/aio-commerce-lib-app
 
+## 1.0.0
+
+### Major Changes
+
+- [#271](https://github.com/adobe/aio-commerce-sdk/pull/271) [`0170e73`](https://github.com/adobe/aio-commerce-sdk/commit/0170e7340d28367a6f001c9b2ff7e1ec0874a49b) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Turn `get-app-config` into a REST-like `app-config` runtime action.
+
+- [#271](https://github.com/adobe/aio-commerce-sdk/pull/271) [`0170e73`](https://github.com/adobe/aio-commerce-sdk/commit/0170e7340d28367a6f001c9b2ff7e1ec0874a49b) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Introduce `config` and `scope-tree` runtime actions with REST-like API for business configuration.
+
+- [#294](https://github.com/adobe/aio-commerce-sdk/pull/294) [`6d5b16a`](https://github.com/adobe/aio-commerce-sdk/commit/6d5b16a7659ab0d83b251921ac478ff7faf0d4e5) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - General Availability (GA) release of the Adobe Commerce SDK and all libraries.
+
+- [#287](https://github.com/adobe/aio-commerce-sdk/pull/287) [`fc16aae`](https://github.com/adobe/aio-commerce-sdk/commit/fc16aaec9b459b58e368379bc3127c3e0d698c6a) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Changed case format from camelCase to snake_case for Commerce eventing API
+
+### Patch Changes
+
+- [#274](https://github.com/adobe/aio-commerce-sdk/pull/274) [`d599ba8`](https://github.com/adobe/aio-commerce-sdk/commit/d599ba8ae30d3139d4ba19d0c63eaf716603f25f) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Fix typo: `prioritary` should be `priority`
+
+- [#267](https://github.com/adobe/aio-commerce-sdk/pull/267) [`8642288`](https://github.com/adobe/aio-commerce-sdk/commit/8642288be4efd44b375d47e7cb75adb038c08334) Thanks [@jnatherley](https://github.com/jnatherley)! - Implements a rolldown plugin to correctly externalize transitive dependencies of private packages during build, but keep the source code of those same packages bundled.
+
+- [#277](https://github.com/adobe/aio-commerce-sdk/pull/277) [`b706ac7`](https://github.com/adobe/aio-commerce-sdk/commit/b706ac73042df4df1f7f77da3d58b7042a65ae9a) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Optimize generated `actions` by exposing runtime actions in individual entrypoints.
+
+- [#264](https://github.com/adobe/aio-commerce-sdk/pull/264) [`ac8203f`](https://github.com/adobe/aio-commerce-sdk/commit/ac8203f6c9d380dc0c337cc173ea730e66a36439) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Support word characters, hyphens, underscores, and dots for external event names
+
+- [#293](https://github.com/adobe/aio-commerce-sdk/pull/293) [`86443ef`](https://github.com/adobe/aio-commerce-sdk/commit/86443ef71570c1cbbb3b7398f712157b73933f31) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Support any casing in the `runtimeActions` property of the `app.commerce.config` for events.
+
+- [#269](https://github.com/adobe/aio-commerce-sdk/pull/269) [`a502120`](https://github.com/adobe/aio-commerce-sdk/commit/a502120d8c16fdc1ed4afc579c5cfd79ec56c8e0) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Use a safe CLI wrapper to ensure binaries can always be linked
+
+- Updated dependencies [[`d599ba8`](https://github.com/adobe/aio-commerce-sdk/commit/d599ba8ae30d3139d4ba19d0c63eaf716603f25f), [`8642288`](https://github.com/adobe/aio-commerce-sdk/commit/8642288be4efd44b375d47e7cb75adb038c08334), [`0170e73`](https://github.com/adobe/aio-commerce-sdk/commit/0170e7340d28367a6f001c9b2ff7e1ec0874a49b), [`6d5b16a`](https://github.com/adobe/aio-commerce-sdk/commit/6d5b16a7659ab0d83b251921ac478ff7faf0d4e5), [`0170e73`](https://github.com/adobe/aio-commerce-sdk/commit/0170e7340d28367a6f001c9b2ff7e1ec0874a49b), [`a502120`](https://github.com/adobe/aio-commerce-sdk/commit/a502120d8c16fdc1ed4afc579c5cfd79ec56c8e0), [`6d5b16a`](https://github.com/adobe/aio-commerce-sdk/commit/6d5b16a7659ab0d83b251921ac478ff7faf0d4e5), [`fc16aae`](https://github.com/adobe/aio-commerce-sdk/commit/fc16aaec9b459b58e368379bc3127c3e0d698c6a), [`0170e73`](https://github.com/adobe/aio-commerce-sdk/commit/0170e7340d28367a6f001c9b2ff7e1ec0874a49b), [`3398078`](https://github.com/adobe/aio-commerce-sdk/commit/33980787b7874a3615b5946b76af1af36153cf76)]:
+  - @adobe/aio-commerce-lib-events@1.0.0
+  - @adobe/aio-commerce-lib-config@1.0.0
+  - @adobe/aio-commerce-lib-auth@1.0.0
+  - @adobe/aio-commerce-lib-core@1.0.0
+  - @adobe/aio-commerce-lib-api@1.0.0
+
+## 0.3.2
+
+### Patch Changes
+
+- [#262](https://github.com/adobe/aio-commerce-sdk/pull/262) [`7cb9252`](https://github.com/adobe/aio-commerce-sdk/commit/7cb9252736acd34f5490e2dc940b74a7ec40f17c) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Dependencies should be installed early in the init process.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,12 @@
 # `@adobe/aio-commerce-lib-app`
 
-> [!WARNING]
-> This package is still under development and is not yet ready for use. You might be able to install it, but you may encounter breaking changes.
-
 App configuration management library for Adobe Commerce applications.
 
 This library provides tools for defining, validating, and managing configurations for Adobe Commerce applications. It defines the configuration schema, provides validation, and supports multiple configuration file formats with built-in TypeScript support.
 
 ## Installation
 
-```bash
+```shell
 npm install @adobe/aio-commerce-lib-app
 ```
 

package/bin/cli.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/*
+ * 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.
+ */
+
+try {
+  await import("../dist/es/commands/index.mjs");
+} catch (e) {
+  if (e.code && e.code === "ERR_MODULE_NOT_FOUND") {
+    console.error("CLI was not built!");
+    process.exit(1);
+  }
+
+  throw e;
+}

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

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_schemas = require('../schemas-CZ6c8Id9.cjs');
+const require_router = require('../router-DCw7oEQ9.cjs');
+const require_validate = require('../validate-BegMfe-i.cjs');
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
+
+//#region source/actions/app-config.ts
+/** Router for the app config actions. */
+const router = new require_router.HttpActionRouter().use(require_router.logger({ name: () => "get-app-config" }));
+/** GET / - Get app config */
+router.get("/", { handler: async (_req, { logger, rawParams }) => {
+	logger.debug("Validating app config...");
+	const { appConfig } = rawParams;
+	const config = require_validate.validateCommerceAppConfig(appConfig);
+	logger.debug("Successfully validated the app config");
+	return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: config });
+} });
+/** Factory to create the route handler for the `app-config` action. */
+const appConfigRuntimeAction = ({ appConfig }) => async (params) => {
+	return await router.handler()({
+		...params,
+		appConfig
+	});
+};
+
+//#endregion
+exports.appConfigRuntimeAction = appConfigRuntimeAction;

package/dist/cjs/actions/app-config.d.cts

@@ -0,0 +1,15 @@
+import { n as CommerceAppConfigOutputModel } from "../app-PTKvEBea.cjs";
+import * as _adobe_aio_commerce_lib_core_responses0 from "@adobe/aio-commerce-lib-core/responses";
+import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
+
+//#region source/actions/app-config.d.ts
+/** Arguments for the runtime action factory. */
+type RuntimeActionFactoryArgs = {
+  appConfig: CommerceAppConfigOutputModel;
+};
+/** Factory to create the route handler for the `app-config` action. */
+declare const appConfigRuntimeAction: ({
+  appConfig
+}: RuntimeActionFactoryArgs) => (params: RuntimeActionParams) => Promise<_adobe_aio_commerce_lib_core_responses0.ActionResponse>;
+//#endregion
+export { appConfigRuntimeAction };

package/dist/cjs/actions/config.cjs

@@ -0,0 +1,79 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_schemas = require('../schemas-CZ6c8Id9.cjs');
+const require_router = require('../router-DCw7oEQ9.cjs');
+const require_validate = require('../validate-BegMfe-i.cjs');
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
+let valibot = require("valibot");
+valibot = require_schemas.__toESM(valibot);
+let _adobe_aio_commerce_lib_config = require("@adobe/aio-commerce-lib-config");
+
+//#region source/actions/config.ts
+const MASKED_PASSWORD_VALUE = "*****";
+/**
+* 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) => {
+		if (schema.find((field) => field.name === item.name)?.type === "password") return {
+			...item,
+			value: MASKED_PASSWORD_VALUE
+		};
+		return item;
+	});
+}
+const router = new require_router.HttpActionRouter().use(require_router.logger());
+/** GET / - Retrieve configuration */
+router.get("/", {
+	query: valibot.object({ scopeId: require_schemas.nonEmptyStringValueSchema("scopeId") }),
+	handler: async (req, ctx) => {
+		const { logger, rawParams } = ctx;
+		const configSchema = rawParams.configSchema;
+		logger.debug("Validating configuration schema...");
+		const validatedSchema = require_validate.validateCommerceAppConfigDomain(configSchema, "businessConfig.schema");
+		(0, _adobe_aio_commerce_lib_config.initialize)({ schema: validatedSchema });
+		const { scopeId } = req.query;
+		logger.debug(`Retrieving configuration with scope id: ${scopeId}`);
+		const appConfiguration = await (0, _adobe_aio_commerce_lib_config.getConfiguration)((0, _adobe_aio_commerce_lib_config.byScopeId)(scopeId), { encryptionKey: rawParams.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY });
+		logger.debug("Masking password values...");
+		appConfiguration.config = filterPasswordFields(configSchema, appConfiguration.config);
+		return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: {
+			schema: validatedSchema,
+			values: appConfiguration
+		} });
+	}
+});
+/** POST / - Set configuration */
+router.put("/", {
+	body: valibot.object({
+		scopeId: require_schemas.nonEmptyStringValueSchema("scopeId"),
+		config: valibot.array(valibot.object({
+			name: require_schemas.nonEmptyStringValueSchema("config.name"),
+			value: valibot.union([valibot.string(), valibot.array(valibot.string())])
+		}))
+	}),
+	handler: async (req, ctx) => {
+		const { logger, rawParams } = ctx;
+		const { configSchema } = rawParams;
+		logger.debug(`Setting configuration with scope id: ${req.body.scopeId}`);
+		const { scopeId, config } = req.body;
+		const result = await (0, _adobe_aio_commerce_lib_config.setConfiguration)({ config: config.filter((item) => item.value !== MASKED_PASSWORD_VALUE) }, (0, _adobe_aio_commerce_lib_config.byScopeId)(scopeId), { encryptionKey: rawParams.AIO_COMMERCE_CONFIG_ENCRYPTION_KEY });
+		result.config = filterPasswordFields(configSchema, result.config);
+		return (0, _adobe_aio_commerce_lib_core_responses.ok)({
+			body: result,
+			headers: { "Cache-Control": "no-store" }
+		});
+	}
+});
+/** Factory to create the route handler for the `config` action. */
+const configRuntimeAction = ({ configSchema }) => async (params) => {
+	return await router.handler()({
+		...params,
+		configSchema
+	});
+};
+
+//#endregion
+exports.configRuntimeAction = configRuntimeAction;

package/dist/cjs/actions/config.d.cts

@@ -0,0 +1,15 @@
+import * as _adobe_aio_commerce_lib_core_responses0 from "@adobe/aio-commerce-lib-core/responses";
+import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
+import { BusinessConfigSchema } from "@adobe/aio-commerce-lib-config";
+
+//#region source/actions/config.d.ts
+/** The arguments for the config action factory. */
+type ConfigActionFactoryArgs = {
+  configSchema: BusinessConfigSchema;
+};
+/** Factory to create the route handler for the `config` action. */
+declare const configRuntimeAction: ({
+  configSchema
+}: ConfigActionFactoryArgs) => (params: RuntimeActionParams) => Promise<_adobe_aio_commerce_lib_core_responses0.ActionResponse>;
+//#endregion
+export { configRuntimeAction };

package/dist/cjs/actions/installation.cjs

@@ -0,0 +1,424 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_schemas = require('../schemas-CZ6c8Id9.cjs');
+const require_router = require('../router-DCw7oEQ9.cjs');
+const require_runner = require('../runner-CUJ8RHzY.cjs');
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
+let valibot = require("valibot");
+valibot = require_schemas.__toESM(valibot);
+let _adobe_aio_lib_files = require("@adobe/aio-lib-files");
+let _adobe_aio_lib_state = require("@adobe/aio-lib-state");
+let openwhisk = require("openwhisk");
+openwhisk = require_schemas.__toESM(openwhisk);
+
+//#region ../../packages-private/common-utils/source/storage/files-store.ts
+/** Default directory prefix. */
+const DEFAULT_DIR_PREFIX = "store";
+/**
+* Creates a generic key-value store backed by @adobe/aio-lib-files.
+* Provides persistent storage that survives beyond TTL.
+*
+* @typeParam T - The type of data to store.
+* @param options - Configuration options for the store.
+* @returns A KeyValueStore implementation.
+*
+* @example
+* ```typescript
+* interface UserProfile {
+*   id: string;
+*   name: string;
+*   email: string;
+* }
+*
+* const store = await createFilesStore<UserProfile>({
+*   dirPrefix: "profiles",
+* });
+*
+* await store.put("user-123", { id: "123", name: "John", email: "john@example.com" });
+* const profile = await store.get("user-123");
+* ```
+*/
+async function createFilesStore(options = {}) {
+	const { dirPrefix = DEFAULT_DIR_PREFIX } = options;
+	return new FilesStore(await (0, _adobe_aio_lib_files.init)(), dirPrefix);
+}
+/**
+* Key-value store implementation using @adobe/aio-lib-files.
+*/
+var FilesStore = class {
+	constructor(files, dirPrefix) {
+		this.files = files;
+		this.dirPrefix = dirPrefix;
+	}
+	async get(key) {
+		const filePath = this.buildFilePath(key);
+		try {
+			const content = await this.files.read(filePath);
+			if (!content) return null;
+			return JSON.parse(content.toString("utf8"));
+		} catch {
+			return null;
+		}
+	}
+	async put(key, data) {
+		const filePath = this.buildFilePath(key);
+		await this.files.write(filePath, JSON.stringify(data));
+	}
+	async delete(key) {
+		const filePath = this.buildFilePath(key);
+		try {
+			const result = await this.files.delete(filePath);
+			return Array.isArray(result) && result.length > 0;
+		} catch {
+			return false;
+		}
+	}
+	buildFilePath(key) {
+		return `${this.dirPrefix}/${key}.json`;
+	}
+};
+
+//#endregion
+//#region ../../packages-private/common-utils/source/storage/state-store.ts
+/** Default TTL for state entries (3 hours in seconds). */
+const DEFAULT_TTL_SECONDS = 10800;
+/** Default key prefix. */
+const DEFAULT_KEY_PREFIX = "store";
+/**
+* Creates a generic key-value store backed by @adobe/aio-lib-state.
+* Provides fast, TTL-based caching for temporary data.
+*
+* @typeParam T - The type of data to store.
+* @param options - Configuration options for the store.
+* @returns A KeyValueStore implementation.
+*
+* @example
+* ```typescript
+* interface UserSession {
+*   userId: string;
+*   token: string;
+* }
+*
+* const store = await createStateStore<UserSession>({
+*   keyPrefix: "session",
+*   ttlSeconds: 3600, // 1 hour
+* });
+*
+* await store.put("user-123", { userId: "123", token: "abc" });
+* const session = await store.get("user-123");
+* ```
+*/
+async function createStateStore(options = {}) {
+	const { keyPrefix = DEFAULT_KEY_PREFIX, ttlSeconds = DEFAULT_TTL_SECONDS } = options;
+	return new StateStore(await (0, _adobe_aio_lib_state.init)(), keyPrefix, ttlSeconds);
+}
+/**
+* Key-value store implementation using @adobe/aio-lib-state.
+*/
+var StateStore = class {
+	constructor(state, keyPrefix, ttlSeconds) {
+		this.state = state;
+		this.keyPrefix = keyPrefix;
+		this.ttlSeconds = ttlSeconds;
+	}
+	async get(key) {
+		const fullKey = this.buildKey(key);
+		const result = await this.state.get(fullKey);
+		if (!result?.value) return null;
+		try {
+			return JSON.parse(result.value);
+		} catch {
+			return null;
+		}
+	}
+	async put(key, data) {
+		const fullKey = this.buildKey(key);
+		const value = JSON.stringify(data);
+		await this.state.put(fullKey, value, { ttl: this.ttlSeconds });
+	}
+	async delete(key) {
+		const fullKey = this.buildKey(key);
+		try {
+			await this.state.delete(fullKey);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	buildKey(key) {
+		return `${this.keyPrefix}-${key}`;
+	}
+};
+
+//#endregion
+//#region ../../packages-private/common-utils/source/storage/combined-store.ts
+/** Default TTL for cache (10 minutes). */
+const DEFAULT_CACHE_TTL_SECONDS = 600;
+/**
+* Creates a combined key-value store that uses:
+* - lib-state for fast cache during active operations
+* - lib-files for persistent storage
+*
+* Read strategy: cache first, then persistent storage
+* Write strategy:
+* - Always write to cache for fast reads
+* - Write to persistent storage based on shouldPersist predicate
+*
+* @typeParam T - The type of data to store.
+* @param options - Configuration options for the stores.
+*
+* @example
+* ```typescript
+* interface Task {
+*   id: string;
+*   status: "pending" | "completed";
+*   result?: unknown;
+* }
+*
+* const store = await createCombinedStore<Task>({
+*   cache: { keyPrefix: "task", ttlSeconds: 600 },
+*   persistent: {
+*     dirPrefix: "tasks",
+*     shouldPersist: (task) => task.status === "completed",
+*   },
+* });
+*
+* // During processing: writes to cache only
+* await store.put("task-1", { id: "1", status: "pending" });
+*
+* // On completion (as shouldPersist indicates): writes to both cache and persistent
+* await store.put("task-1", { id: "1", status: "completed", result: {} });
+* ```
+*/
+async function createCombinedStore(options = {}) {
+	const { cache = {}, persistent = {} } = options;
+	const { shouldPersist, ...filesOptions } = persistent;
+	const cacheOptions = {
+		ttlSeconds: DEFAULT_CACHE_TTL_SECONDS,
+		...cache
+	};
+	const [cacheStore, persistentStore] = await Promise.all([createStateStore(cacheOptions), createFilesStore(filesOptions)]);
+	return new CombinedStore(cacheStore, persistentStore, shouldPersist);
+}
+/**
+* Combined key-value store implementation.
+* Uses lib-state for cache and lib-files for persistence.
+*/
+var CombinedStore = class {
+	constructor(cache, persistent, shouldPersist) {
+		this.cache = cache;
+		this.persistent = persistent;
+		this.shouldPersist = shouldPersist;
+	}
+	async get(key) {
+		const cached = await this.cache.get(key);
+		if (cached !== null && cached !== void 0) return cached;
+		const persisted = await this.persistent.get(key);
+		if (persisted !== null && persisted !== void 0) {
+			await this.cache.put(key, persisted).catch(() => {});
+			return persisted;
+		}
+		return null;
+	}
+	async put(key, data) {
+		await this.cache.put(key, data);
+		if (!this.shouldPersist || this.shouldPersist(data)) await this.persistent.put(key, data);
+	}
+	async delete(key) {
+		const [cacheDeleted, persistentDeleted] = await Promise.all([this.cache.delete?.(key) ?? Promise.resolve(false), this.persistent.delete?.(key) ?? Promise.resolve(false)]);
+		return cacheDeleted || persistentDeleted;
+	}
+};
+
+//#endregion
+//#region source/management/installation/schema.ts
+/** Schema for validating Adobe I/O app credentials required for installation. */
+const AppDataSchema = valibot.object({
+	consumerOrgId: require_schemas.nonEmptyStringValueSchema("consumerOrgId"),
+	orgName: require_schemas.nonEmptyStringValueSchema("orgName"),
+	projectId: require_schemas.nonEmptyStringValueSchema("projectId"),
+	projectName: require_schemas.nonEmptyStringValueSchema("projectName"),
+	projectTitle: require_schemas.nonEmptyStringValueSchema("projectTitle"),
+	workspaceId: require_schemas.nonEmptyStringValueSchema("workspaceId"),
+	workspaceName: require_schemas.nonEmptyStringValueSchema("workspaceName"),
+	workspaceTitle: require_schemas.nonEmptyStringValueSchema("workspaceTitle")
+});
+
+//#endregion
+//#region source/actions/installation.ts
+const DEFAULT_ACTION_NAME = "app-management/installation";
+/** Creates an installation state store using lib-core combined storage. */
+function createInstallationStore() {
+	return createCombinedStore({
+		cache: { keyPrefix: "installation" },
+		persistent: {
+			dirPrefix: "installation",
+			shouldPersist: require_runner.isCompletedState
+		}
+	});
+}
+/** Returns the storage key used to store the current installation ID. */
+function getStorageKey() {
+	return "current";
+}
+/**
+* Creates hooks to sync installation state to storage.
+*/
+function createInstallationHooks(store, logFn) {
+	const logAndSave = async (message, data) => {
+		logFn(message);
+		await store.put(getStorageKey(), data);
+	};
+	return {
+		onInstallationStart: (state) => logAndSave("Installation started", state),
+		onInstallationFailure: (state) => logAndSave("Installation failed", state),
+		onInstallationSuccess: (state) => logAndSave("Installation succeeded", state),
+		onStepStart: (event, state) => logAndSave(`Step started: ${event.stepName}`, state),
+		onStepSuccess: (event, state) => logAndSave(`Step succeeded: ${event.stepName}`, state),
+		onStepFailure: (event, state) => logAndSave(`Step failed: ${event.stepName}`, state)
+	};
+}
+/**
+* Installation action router.
+*
+* Routes:
+* - POST /installation - Start installation (creates plan, invokes execution async)
+* - GET /installation/execution - Get current execution status
+* - POST /installation/execution - Execute installation (internal, called async)
+*/
+const router = new require_router.HttpActionRouter().use(require_router.logger({ name: () => "installation" }));
+/**
+* GET /installation/execution - Get current execution status
+*
+* Flow:
+* 1. Find execution in state store
+* 2. If found: return execution plan with step statuses
+* 3. If not found: return empty status
+*/
+router.get("/", { handler: async (_req, { logger }) => {
+	logger.debug("Getting installation execution status...");
+	const state = await (await createInstallationStore()).get(getStorageKey());
+	if (state) {
+		logger.debug(`Found execution: ${state.status}`);
+		return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: state });
+	}
+	logger.debug("No execution found");
+	return (0, _adobe_aio_commerce_lib_core_responses.noContent)();
+} });
+/**
+* POST / - Start installation
+*
+* Flow:
+* 1. Find execution in state store
+* 2. If found and (pending/in-progress or succeeded): return 409 Conflict
+* 3. If not found or failed: create plan, invoke execution async, return 202 Accepted
+*/
+router.post("/", {
+	body: (0, valibot.object)({
+		appData: AppDataSchema,
+		commerceBaseUrl: (0, valibot.string)(),
+		commerceEnv: (0, valibot.string)(),
+		ioEventsUrl: (0, valibot.string)(),
+		ioEventsEnv: (0, valibot.string)()
+	}),
+	handler: async (req, { logger, rawParams }) => {
+		logger.debug("Starting installation...");
+		const store = await createInstallationStore();
+		const existingState = await store.get(getStorageKey());
+		if (existingState) {
+			if (require_runner.isInProgressState(existingState)) {
+				logger.debug(`Installation already in progress: ${existingState.status}`);
+				return (0, _adobe_aio_commerce_lib_core_responses.conflict)(`Installation is already ${existingState.status}. Wait for it to complete.`);
+			}
+			if (require_runner.isSucceededState(existingState)) {
+				logger.debug("Installation already succeeded");
+				return (0, _adobe_aio_commerce_lib_core_responses.conflict)("Installation has already completed successfully.");
+			}
+			logger.debug("Previous installation failed, allowing retry");
+		}
+		const appConfig = rawParams.appConfig;
+		if (!appConfig) return (0, _adobe_aio_commerce_lib_core_responses.internalServerError)("Could not find or parse the app.commerce.manifest.json file, is it present and valid?");
+		const initialState = require_runner.createInitialInstallationState({ config: appConfig });
+		logger.debug(`Created initial state: ${initialState.id}`);
+		await store.put(getStorageKey(), initialState);
+		const activation = await (0, openwhisk.default)().actions.invoke({
+			name: DEFAULT_ACTION_NAME,
+			blocking: false,
+			result: false,
+			params: {
+				...rawParams,
+				appData: req.body.appData,
+				AIO_EVENTS_API_BASE_URL: req.body.ioEventsUrl,
+				AIO_COMMERCE_AUTH_IMS_ENVIRONMENT: req.body.ioEventsEnv,
+				AIO_COMMERCE_API_BASE_URL: req.body.commerceBaseUrl,
+				AIO_COMMERCE_API_FLAVOR: req.body.commerceEnv,
+				initialState,
+				appConfig,
+				__ow_path: "/execution",
+				__ow_method: "post"
+			}
+		});
+		logger.debug(`Async execution started: ${activation.activationId}`);
+		return (0, _adobe_aio_commerce_lib_core_responses.accepted)({ body: {
+			message: "Installation started",
+			activationId: activation.activationId,
+			...initialState
+		} });
+	}
+});
+/**
+* POST /installation/execution - Execute installation (internal)
+*
+* This endpoint is called asynchronously by POST /installation.
+* It runs the actual installation workflow and saves state.
+*/
+router.post("/execution", { handler: async (_req, { logger, rawParams }) => {
+	const { appData, ...params } = rawParams;
+	const { initialState, appConfig } = params;
+	if (!initialState) return (0, _adobe_aio_commerce_lib_core_responses.badRequest)("initialState is required for execution");
+	if (!appConfig) return (0, _adobe_aio_commerce_lib_core_responses.badRequest)("appConfig is required for execution");
+	const store = await createInstallationStore();
+	const hooks = createInstallationHooks(store, (msg) => logger.debug(msg));
+	const installationContext = {
+		appData,
+		params,
+		logger,
+		customScripts: params.customScriptsLoader?.(appConfig, logger) || {}
+	};
+	logger.debug(`Executing installation: ${initialState.id}`);
+	const result = await require_runner.runInstallation({
+		installationContext,
+		config: appConfig,
+		initialState,
+		hooks
+	});
+	await store.put(getStorageKey(), result);
+	logger.debug(`Installation completed: ${result.status}`);
+	if (require_runner.isFailedState(result)) return (0, _adobe_aio_commerce_lib_core_responses.internalServerError)({ body: {
+		message: "Installation failed",
+		error: result.error,
+		state: result
+	} });
+	return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: result });
+} });
+/**
+* DELETE / - Clear installation state
+*
+* This endpoint allows clearing the installation state.
+*/
+router.delete("/", { handler: async (_req, { logger }) => {
+	logger.debug("Clearing installation state...");
+	await (await createInstallationStore()).delete(getStorageKey());
+	logger.debug("Installation state cleared");
+	return (0, _adobe_aio_commerce_lib_core_responses.noContent)();
+} });
+/** Factory to create the route handler for the `installation` action. */
+const installationRuntimeAction = ({ appConfig, customScriptsLoader }) => async (params) => {
+	return await router.handler()({
+		...params,
+		appConfig,
+		customScriptsLoader
+	});
+};
+
+//#endregion
+exports.installationRuntimeAction = installationRuntimeAction;

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

@@ -1,15 +1,16 @@
-import { n as CommerceAppConfigOutputModel } from "../app-Dx0ca6oL.cjs";
-import { P as InstallationContext } from "../index-C5SutkJQ.cjs";
+import { n as CommerceAppConfigOutputModel } from "../app-PTKvEBea.cjs";
+import { P as InstallationContext } from "../runner-Ds2m27Q4.cjs";
 import * as _adobe_aio_commerce_lib_core_responses0 from "@adobe/aio-commerce-lib-core/responses";
 import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
 
 //#region source/actions/installation.d.ts
 type CustomScriptsLoader = (config: CommerceAppConfigOutputModel, logger: InstallationContext["logger"]) => Record<string, unknown>;
+/** Arguments for the runtime action factory. */
 type RuntimeActionFactoryArgs = {
   appConfig: CommerceAppConfigOutputModel;
   customScriptsLoader?: CustomScriptsLoader;
 };
-/** The route handler for the runtime action. */
+/** Factory to create the route handler for the `installation` action. */
 declare const installationRuntimeAction: ({
   appConfig,
   customScriptsLoader