@adobe/aio-commerce-lib-app 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @adobe/aio-commerce-lib-app
 
+## 1.3.0
+
+### Minor Changes
+
+- [#369](https://github.com/adobe/aio-commerce-sdk/pull/369) [`d8b0fa9`](https://github.com/adobe/aio-commerce-sdk/commit/d8b0fa9e3370b7abd0fb71b42d0078c375f63fb3) Thanks [@oshmyheliuk](https://github.com/oshmyheliuk)! - Add uninstallation flow for both native steps and custom steps. `defineCustomInstallationStep` now accepts an object with `install` and an optional `uninstall` handler in addition to a plain function, enabling per-step cleanup logic.
+
+- [#387](https://github.com/adobe/aio-commerce-sdk/pull/387) [`0803ecb`](https://github.com/adobe/aio-commerce-sdk/commit/0803ecb143ee6a0e6d4113cb380d625e20ee4e2f) Thanks [@obarcelonap](https://github.com/obarcelonap)! - Adding new PATCH endpoint for configuration which allows to partially set configuration values. Deprecating PUT endpoint in favor of PATCH.
+
+### Patch Changes
+
+- [#375](https://github.com/adobe/aio-commerce-sdk/pull/375) [`f5ac1a1`](https://github.com/adobe/aio-commerce-sdk/commit/f5ac1a1a400a6e609f296ef8de21ef6b20602120) Thanks [@iivvaannxx](https://github.com/iivvaannxx)! - Fix an issue where the Commerce Eventing module was constantly being updated for each provider of an app.
+
+- Updated dependencies [[`d8b0fa9`](https://github.com/adobe/aio-commerce-sdk/commit/d8b0fa9e3370b7abd0fb71b42d0078c375f63fb3), [`0803ecb`](https://github.com/adobe/aio-commerce-sdk/commit/0803ecb143ee6a0e6d4113cb380d625e20ee4e2f)]:
+  - @adobe/aio-commerce-lib-events@1.1.0
+  - @adobe/aio-commerce-lib-config@1.2.0
+
 ## 1.2.0
 
 ### Minor Changes

package/dist/cjs/actions/config.cjs

@@ -59,7 +59,11 @@ router.get("/", {
 		} });
 	}
 });
-/** POST / - Set configuration */
+/**
+* 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: valibot.object({
 		scopeId: require_schemas.nonEmptyStringValueSchema("scopeId"),
@@ -73,8 +77,35 @@ router.put("/", {
 		const { configSchema } = rawParams;
 		logger.debug(`Setting configuration with scope id: ${req.body.scopeId}`);
 		const { scopeId, config } = req.body;
+		(0, _adobe_aio_commerce_lib_config.initialize)({ schema: require_validate.validateCommerceAppConfigDomain(configSchema, "businessConfig.schema") });
 		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",
+				Deprecation: "Wed, 15 Apr 2026 00:00:00 GMT"
+			}
+		});
+	}
+});
+/** PATCH / - Partially update configuration */
+router.patch("/", {
+	body: valibot.object({
+		scopeId: require_schemas.nonEmptyStringValueSchema("scopeId"),
+		config: valibot.array(valibot.object({
+			name: require_schemas.nonEmptyStringValueSchema("config.name"),
+			value: valibot.nullable(valibot.union([valibot.string(), valibot.array(valibot.string())]))
+		}))
+	}),
+	handler: async (req, ctx) => {
+		const { logger, rawParams } = ctx;
+		const { configSchema } = rawParams;
+		logger.debug(`Patching configuration with scope id: ${req.body.scopeId}`);
+		const { scopeId, config } = req.body;
+		(0, _adobe_aio_commerce_lib_config.initialize)({ schema: require_validate.validateCommerceAppConfigDomain(configSchema, "businessConfig.schema") });
+		const result = await (0, _adobe_aio_commerce_lib_config.setConfiguration)({ config }, (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" }

package/dist/cjs/actions/installation.cjs

@@ -15,7 +15,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_schemas = require('../schemas-nkIxa8sL.cjs');
 const require_router = require('../router-KeQRduO3.cjs');
-const require_management = require('../management-iLQubQ7K.cjs');
+const require_management = require('../management-C6xG5bfl.cjs');
 let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
 let valibot = require("valibot");
 valibot = require_schemas.__toESM(valibot);
@@ -268,21 +268,68 @@ const InstallationRequestBodySchema = (0, valibot.object)({
 	ioEventsUrl: (0, valibot.string)(),
 	ioEventsEnv: (0, valibot.string)()
 });
-/** Creates an installation state store using lib-core combined storage. */
-function createInstallationStore() {
+/** Creates a workflow state store with the given prefix. */
+function createWorkflowStore(prefix) {
 	return createCombinedStore({
-		cache: { keyPrefix: "installation" },
+		cache: { keyPrefix: prefix },
 		persistent: {
-			dirPrefix: "installation",
+			dirPrefix: prefix,
 			shouldPersist: require_management.isCompletedState
 		}
 	});
 }
+/** Creates the installation state store. */
+function createInstallationStore() {
+	return createWorkflowStore("installation");
+}
+/** Creates the uninstallation state store. */
+function createUninstallationStore() {
+	return createWorkflowStore("uninstallation");
+}
 /** Returns the storage key used to store the current installation ID. */
 function getStorageKey() {
 	return "current";
 }
 /**
+* Merges rawParams with body fields, overriding API URLs.
+* Shared by POST /, POST /execution, POST /uninstallation, POST /uninstallation/execution.
+*/
+function buildWorkflowParams(body, rawParams) {
+	return {
+		...rawParams,
+		appData: body.appData,
+		AIO_EVENTS_API_BASE_URL: body.ioEventsUrl,
+		AIO_COMMERCE_AUTH_IMS_ENVIRONMENT: body.ioEventsEnv,
+		AIO_COMMERCE_API_BASE_URL: body.commerceBaseUrl,
+		AIO_COMMERCE_API_FLAVOR: body.commerceEnv
+	};
+}
+/**
+* Builds an InstallationContext from merged workflow params.
+* Shared by POST /execution and POST /uninstallation/execution.
+*/
+function buildInstallationContext(params, appConfig, logFn) {
+	return {
+		appData: params.appData,
+		params,
+		logger: logFn,
+		customScripts: params.customScriptsLoader?.(appConfig, logFn) ?? {}
+	};
+}
+/**
+* Reads state from a store and returns 200 with body or 204.
+* Shared by GET / and GET /uninstallation.
+*/
+async function readStateFromStore(store, logFn) {
+	const state = await store.get(getStorageKey());
+	if (state) {
+		logFn(`Found state: ${state.status}`);
+		return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: state });
+	}
+	logFn("No state found");
+	return (0, _adobe_aio_commerce_lib_core_responses.noContent)();
+}
+/**
 * Creates hooks to sync installation state to storage.
 */
 function createInstallationHooks(store, logFn) {
@@ -303,9 +350,14 @@ function createInstallationHooks(store, logFn) {
 * 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)
+* - 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)
 */
 const router = new require_router.HttpActionRouter().use(require_router.logger({ name: () => "installation" }));
 /**
@@ -318,13 +370,7 @@ const router = new require_router.HttpActionRouter().use(require_router.logger({
 */
 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)();
+	return readStateFromStore(await createInstallationStore(), (msg) => logger.debug(msg));
 } });
 /**
 * POST / - Start installation
@@ -356,17 +402,14 @@ router.post("/", {
 		const initialState = require_management.createInitialInstallationState({ config: appConfig });
 		logger.debug(`Created initial state: ${initialState.id}`);
 		await store.put(getStorageKey(), initialState);
-		const activation = await (0, openwhisk.default)().actions.invoke({
+		const ow = (0, openwhisk.default)();
+		const mergedParams = buildWorkflowParams(req.body, rawParams);
+		const activation = await ow.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,
+				...mergedParams,
 				initialState,
 				appConfig,
 				__ow_path: "/execution",
@@ -388,18 +431,13 @@ router.post("/", {
 * It runs the actual installation workflow and saves state.
 */
 router.post("/execution", { handler: async (_req, { logger, rawParams }) => {
-	const { appData, ...params } = rawParams;
+	const 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) || {}
-	};
+	const installationContext = buildInstallationContext(params, appConfig, logger);
 	logger.debug(`Executing installation: ${initialState.id}`);
 	const result = await require_management.runInstallation({
 		installationContext,
@@ -434,14 +472,7 @@ router.post("/validation", {
 		logger.debug("Running pre-installation validation...");
 		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 { appData, ...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
-		};
+		const { appData, ...params } = buildWorkflowParams(req.body, rawParams);
 		const result = await require_management.runValidation({
 			validationContext: {
 				appData,
@@ -455,14 +486,107 @@ router.post("/validation", {
 	}
 });
 /**
-* DELETE / - Clear installation state
+* GET /uninstallation - Get current uninstallation status
+*
+* Returns 200 with state if an uninstallation has been started, 204 otherwise.
+*/
+router.get("/uninstallation", { handler: async (_req, { logger }) => {
+	logger.debug("Getting uninstallation execution status...");
+	return readStateFromStore(await createUninstallationStore(), (msg) => logger.debug(msg));
+} });
+/**
+* POST /uninstallation - Start uninstallation (async)
+*
+* Flow:
+* 1. Check uninstallation store for existing state
+* 2. If in-progress: return 409 Conflict
+* 3. Create initial uninstall state, save to store
+* 4. Invoke POST /uninstallation/execution async via openwhisk
+* 5. Return 202 Accepted with initial state
+*/
+router.post("/uninstallation", {
+	body: InstallationRequestBodySchema,
+	handler: async (req, { logger, rawParams }) => {
+		logger.debug("Starting async uninstallation...");
+		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 store = await createUninstallationStore();
+		const existingState = await store.get(getStorageKey());
+		if (existingState && require_management.isInProgressState(existingState)) {
+			logger.debug(`Uninstallation already in progress: ${existingState.status}`);
+			return (0, _adobe_aio_commerce_lib_core_responses.conflict)("Uninstallation is already in progress. Wait for it to complete.");
+		}
+		const initialState = require_management.createInitialUninstallationState({ config: appConfig });
+		logger.debug(`Created initial uninstall state: ${initialState.id}`);
+		await store.put(getStorageKey(), initialState);
+		const workflowParams = buildWorkflowParams(req.body, rawParams);
+		const activation = await (0, openwhisk.default)().actions.invoke({
+			name: DEFAULT_ACTION_NAME,
+			blocking: false,
+			result: false,
+			params: {
+				...workflowParams,
+				initialState,
+				appConfig,
+				__ow_path: "/uninstallation/execution",
+				__ow_method: "post"
+			}
+		});
+		logger.debug(`Async uninstallation started: ${activation.activationId}`);
+		return (0, _adobe_aio_commerce_lib_core_responses.accepted)({ body: {
+			message: "Uninstallation started",
+			activationId: activation.activationId,
+			...initialState
+		} });
+	}
+});
+/**
+* POST /uninstallation/execution - Execute uninstallation (internal, called async by POST /uninstallation)
+*
+* Flow:
+* 1. Build InstallationContext from params
+* 2. Run uninstallation workflow with hooks (hooks persist state per step)
+* 3. Save final state to uninstallation store
+* 4. On success, clear installation store
+* 5. Return 200 on success, 500 on failure
+*/
+router.post("/uninstallation/execution", { handler: async (_req, { logger, rawParams }) => {
+	const 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 createUninstallationStore();
+	const hooks = createInstallationHooks(store, (msg) => logger.debug(msg));
+	const installationContext = buildInstallationContext(params, appConfig, logger);
+	logger.debug(`Executing uninstallation: ${initialState.id}`);
+	const result = await require_management.runUninstallation({
+		installationContext,
+		config: appConfig,
+		initialState,
+		hooks
+	});
+	await store.put(getStorageKey(), result);
+	logger.debug(`Uninstallation completed: ${result.status}`);
+	if (require_management.isSucceededState(result)) {
+		await (await createInstallationStore()).delete(getStorageKey());
+		logger.debug("Cleared installation state after successful uninstallation");
+	}
+	if (require_management.isFailedState(result)) return (0, _adobe_aio_commerce_lib_core_responses.internalServerError)({ body: {
+		message: "Uninstallation failed",
+		error: result.error,
+		state: result
+	} });
+	return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body: result });
+} });
+/**
+* DELETE /uninstallation - Clear uninstallation state
 *
-* This endpoint allows clearing the installation state.
+* Removes the stored uninstallation state without triggering any offboarding.
 */
-router.delete("/", { handler: async (_req, { logger }) => {
-	logger.debug("Clearing installation state...");
-	await (await createInstallationStore()).delete(getStorageKey());
-	logger.debug("Installation state cleared");
+router.delete("/uninstallation", { handler: async (_req, { logger }) => {
+	logger.debug("Clearing uninstallation state...");
+	await (await createUninstallationStore()).delete(getStorageKey());
+	logger.debug("Uninstallation state cleared");
 	return (0, _adobe_aio_commerce_lib_core_responses.noContent)();
 } });
 /** Factory to create the route handler for the `installation` action. */

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

@@ -13,7 +13,7 @@
  */
 
 import { n as CommerceAppConfigOutputModel } from "../app-DcQMhW2N.cjs";
-import { V as InstallationContext } from "../index-DZxladgt.cjs";
+import { q as InstallationContext } from "../index-BVwQk9bx.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";
 

package/dist/cjs/{index-DZxladgt.d.cts → index-BVwQk9bx.d.cts}

@@ -62,32 +62,43 @@ type StepContextFactory<TStepCtx extends Record<string, unknown> = Record<string
 type ExecutionContext<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = InstallationContext & TStepCtx;
 /**
  * A narrowed context available to step `validate` handlers.
- * Excludes `customScripts` — those only apply during installation `run`, not pre-flight validation.
+ * Excludes `customScripts` — those only apply during installation, not pre-flight validation.
  */
 type ValidationContext = Omit<InstallationContext, "customScripts">;
 /** The context passed to step `validate` handlers (base validation context merged with step-level context). */
 type ValidationExecutionContext<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = ValidationContext & TStepCtx;
-/** Metadata for a step (used for UI display). */
-type StepMeta = {
+/** Metadata info for a step (used for UI display). */
+type StepMetaInfo = {
   label: string;
   description?: string;
 };
+/** Step metadata keyed by execution mode. */
+type StepMeta = {
+  install: StepMetaInfo;
+  uninstall?: StepMetaInfo;
+};
 /** Defines the base properties of a step. */
 type StepBase<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel> = {
-  /** The name of this step. */name: TName; /** Metadata associated with the step. */
+  /** The name of this step. */name: TName; /** Metadata associated with the step, keyed by execution mode. */
   meta: StepMeta; /** Whether the step should be taken into consideration. */
   when?: (config: CommerceAppConfigOutputModel) => config is TConfig;
 };
 /** A leaf step that executes work (no children). */
 type LeafStep<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> = StepBase<TName, TConfig> & {
   type: "leaf"; /** The execution handler for the step. */
-  run: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
+  install: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
   /**
    * Optional pre-installation validation handler.
    * Called before installation begins to surface issues (errors or warnings).
    * Returning an empty array means the step has no issues.
    */
   validate?: (config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>;
+  /**
+   * Optional uninstall handler for the step.
+   * Called during uninstallation to reverse the work done by `install`.
+   * If absent, the step is silently skipped during uninstallation.
+   */
+  uninstall?: (config: TConfig, context: ExecutionContext<TStepCtx>) => void | Promise<void>;
 };
 /** A branch step that contains children (no execution). */
 type BranchStep<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TChildren extends AnyStep[] = AnyStep[]> = StepBase<TName, TConfig> & {
@@ -107,10 +118,11 @@ type Step<TName extends string = string, TConfig extends CommerceAppConfigOutput
 interface AnyStep {
   children?: AnyStep[];
   context?: (context: InstallationContext) => any;
+  install?: (config: any, context: any) => unknown | Promise<unknown>;
   meta: StepMeta;
   name: string;
-  run?: (config: any, context: any) => unknown | Promise<unknown>;
   type: "leaf" | "branch";
+  uninstall?: (config: any, context: any) => void | Promise<void>;
   validate?: (config: any, context: any) => ValidationIssue[] | Promise<ValidationIssue[]>;
   when?: (config: CommerceAppConfigOutputModel) => boolean;
 }
@@ -129,8 +141,8 @@ type BranchStepOptions<TName extends string, TConfig extends CommerceAppConfigOu
  * ```typescript
  * const createProviders = defineLeafStep({
  *   name: "providers",
- *   meta: { label: "Create Providers", description: "Creates I/O Events providers" },
- *   run: async ({ config, stepContext }) => {
+ *   meta: { install: { label: "Create Providers", description: "Creates I/O Events providers" } },
+ *   install: async ({ config, stepContext }) => {
  *     const { eventsClient } = stepContext;
  *     return eventsClient.createProvider(config.eventing);
  *   },
@@ -142,7 +154,8 @@ declare function defineLeafStep<TName extends string, TConfig extends CommerceAp
   name: TName;
   meta: StepMeta;
   when: ((config: CommerceAppConfigOutputModel) => config is TConfig) | undefined;
-  run: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
+  install: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
+  uninstall: ((config: TConfig, context: ExecutionContext<TStepCtx>) => void | Promise<void>) | undefined;
   validate: ((config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>) | undefined;
 };
 /**
@@ -152,7 +165,7 @@ declare function defineLeafStep<TName extends string, TConfig extends CommerceAp
  * ```typescript
  * const eventing = defineBranchStep({
  *   name: "eventing",
- *   meta: { label: "Eventing", description: "Sets up I/O Events" },
+ *   meta: { install: { label: "Eventing", description: "Sets up I/O Events" } },
  *   when: hasEventing,
  *   context: async (ctx) => ({ eventsClient: await createEventsClient(ctx) }),
  *   children: [commerceEventsStep, externalEventsStep],
@@ -188,7 +201,7 @@ type StepStatus = {
   /** Step name (unique among siblings). */name: string; /** Unique step identifier (e.g., UUID). */
   id: string; /** Full path from root to this step. */
   path: string[]; /** Step metadata (for display purposes). */
-  meta: StepMeta; /** Current execution status. */
+  meta: StepMetaInfo; /** Current execution status. */
   status: ExecutionStatus; /** Child step statuses (empty for leaf steps). */
   children: StepStatus[];
 };
@@ -270,7 +283,8 @@ type InstallationHooks = {
 /** Options for creating an initial installation state. */
 type CreateInitialStateOptions = {
   /** The root branch step to build the state from. */rootStep: BranchStep; /** The app configuration used to determine applicable steps. */
-  config: CommerceAppConfigOutputModel;
+  config: CommerceAppConfigOutputModel; /** The execution mode. When "uninstall", steps use `meta.uninstall` if defined; defaults to "install". */
+  mode?: ExecutionMode;
 };
 /** Options for executing a workflow. */
 type ExecuteWorkflowOptions = {
@@ -280,6 +294,8 @@ type ExecuteWorkflowOptions = {
   initialState: InProgressInstallationState; /** Lifecycle hooks for status change notifications. */
   hooks?: InstallationHooks;
 };
+/** Execution mode: "install" or "uninstall". */
+type ExecutionMode = "install" | "uninstall";
 /**
  * Creates an initial installation state from a root step and config.
  *
@@ -291,13 +307,18 @@ declare function createInitialState(options: CreateInitialStateOptions): InProgr
  * Executes a workflow from an initial state. Returns the final state (never throws).
  */
 declare function executeWorkflow(options: ExecuteWorkflowOptions): Promise<SucceededInstallationState | FailedInstallationState>;
+/**
+ * Executes an uninstall workflow from an initial state. Returns the final state (never throws).
+ * Steps with an `uninstall` handler get it called; steps without are silently skipped.
+ */
+declare function executeUninstallWorkflow(options: ExecuteWorkflowOptions): Promise<SucceededInstallationState | FailedInstallationState>;
 //#endregion
 //#region source/management/installation/workflow/validation.d.ts
 /** Validation result for a single step, mirroring the step hierarchy. */
 type StepValidationResult = {
   /** Step name (unique among siblings). */name: string; /** Full path from root to this step. */
   path: string[]; /** Step metadata (for display purposes). */
-  meta: StepMeta; /** Issues found for this specific step (not including children). */
+  meta: StepMetaInfo; /** Issues found for this specific step (not including children). */
   issues: ValidationIssue[]; /** Validation results for child steps (empty for leaf steps). */
   children: StepValidationResult[];
 };
@@ -342,35 +363,49 @@ declare function validateStepTree(options: ValidateStepTreeOptions): Promise<Val
  * @returns The result of the installation step (can be any value or Promise)
  */
 type CustomInstallationStepHandler<TResult = unknown> = (config: CommerceAppConfigOutputModel, context: ExecutionContext) => TResult | Promise<TResult>;
+/**
+ * Object form for defining a custom installation step with both install and uninstall handlers.
+ *
+ * @template TResult - The return type of the install handler
+ */
+type CustomInstallationStepDefinition<TResult = unknown> = {
+  /** The installation handler, called when the app is installed. */install: CustomInstallationStepHandler<TResult>; /** The optional uninstall handler, called when the app is uninstalled. */
+  uninstall?: CustomInstallationStepHandler<void>;
+};
 /**
  * Define a custom installation step with type-safe parameters.
  *
  * This helper provides type safety and IDE autocompletion for custom installation scripts.
- * The handler function receives properly typed `config` and `context` parameters.
+ * Accepts either a plain function (install only) or an object with `install` and optional
+ * `uninstall` handlers.
  *
- * @param handler - The installation step handler function
- * @returns The same handler function (for use as default export)
- *
- * @example
+ * @example Plain function (install only):
  * ```typescript
  * import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";
  *
  * export default defineCustomInstallationStep(async (config, context) => {
  *   const { logger, params } = context;
- *
  *   logger.info(`Setting up ${config.metadata.displayName}...`);
+ *   return { status: "success" };
+ * });
+ * ```
  *
- *   // Your installation logic here
- *   // TypeScript will provide autocompletion for config and context
+ * @example Object form with install and uninstall:
+ * ```typescript
+ * import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";
  *
- *   return {
- *     status: "success",
- *     message: "Setup completed",
- *   };
+ * export default defineCustomInstallationStep({
+ *   install: async (config, context) => {
+ *     context.logger.info(`Registering ${config.metadata.displayName}...`);
+ *     return { status: "success" };
+ *   },
+ *   uninstall: async (config, context) => {
+ *     context.logger.info(`Removing ${config.metadata.displayName}...`);
+ *   },
  * });
  * ```
  */
-declare function defineCustomInstallationStep<TResult = unknown>(handler: CustomInstallationStepHandler<TResult>): CustomInstallationStepHandler<TResult>;
+declare function defineCustomInstallationStep<TResult = unknown>(handlerOrDefinition: CustomInstallationStepHandler<TResult> | CustomInstallationStepDefinition<TResult>): CustomInstallationStepHandler<TResult> | CustomInstallationStepDefinition<TResult>;
 //#endregion
 //#region source/management/installation/runner.d.ts
 /** Options for creating an initial installation state. */
@@ -394,6 +429,25 @@ declare function createInitialInstallationState(options: CreateInitialInstallati
  * Runs the full installation workflow. Returns the final state (never throws).
  */
 declare function runInstallation(options: RunInstallationOptions): Promise<SucceededInstallationState | FailedInstallationState>;
+/** Options for creating an initial uninstallation state. */
+type CreateInitialUninstallationStateOptions = {
+  /** The app configuration used to determine applicable steps. */config: CommerceAppConfigOutputModel;
+};
+/** Options for running an uninstallation. */
+type RunUninstallationOptions = {
+  /** Shared installation context (params, logger, etc.). */installationContext: InstallationContext; /** The app configuration. */
+  config: CommerceAppConfigOutputModel; /** The initial uninstallation state (with all steps pending). */
+  initialState: InProgressInstallationState; /** Lifecycle hooks for status change notifications. */
+  hooks?: InstallationHooks;
+};
+/**
+ * Creates an initial uninstallation state from the config and step definitions.
+ */
+declare function createInitialUninstallationState(options: CreateInitialUninstallationStateOptions): InProgressInstallationState;
+/**
+ * Runs the full uninstallation workflow. Returns the final state (never throws).
+ */
+declare function runUninstallation(options: RunUninstallationOptions): Promise<SucceededInstallationState | FailedInstallationState>;
 /** Options for running pre-installation validation. */
 type RunValidationOptions = {
   /** Validation context (params, logger, appData — no customScripts). */validationContext: ValidationContext; /** The app configuration. */
@@ -409,4 +463,4 @@ type RunValidationOptions = {
  */
 declare function runValidation(options: RunValidationOptions): Promise<ValidationResult>;
 //#endregion
-export { isBranchStep as $, StepStatus as A, InferStepOutput as B, ExecutionStatus as C, InstallationError as D, InstallationData as E, isSucceededState as F, StepContextFactory as G, LeafStep as H, AnyStep as I, ValidationExecutionContext as J, StepMeta as K, BranchStep as L, isCompletedState as M, isFailedState as N, InstallationState as O, isInProgressState as P, defineLeafStep as Q, BranchStepOptions as R, StepSucceededEvent as S, InProgressInstallationState as T, LeafStepOptions as U, InstallationContext as V, Step as W, ValidationIssueSeverity as X, ValidationIssue as Y, defineBranchStep as Z, executeWorkflow as _, runInstallation as a, StepFailedEvent as b, defineCustomInstallationStep as c, ValidationResult as d, isLeafStep as et, ValidationSummary as f, createInitialState as g, ExecuteWorkflowOptions as h, createInitialInstallationState as i, SucceededInstallationState as j, InstallationStatus as k, StepValidationResult as l, CreateInitialStateOptions as m, RunInstallationOptions as n, runValidation as o, validateStepTree as p, ValidationContext as q, RunValidationOptions as r, CustomInstallationStepHandler as s, CreateInitialInstallationStateOptions as t, ValidateStepTreeOptions as u, InstallationHooks as v, FailedInstallationState as w, StepStartedEvent as x, StepEvent as y, ExecutionContext as z };
+export { StepMetaInfo as $, FailedInstallationState as A, isInProgressState as B, executeWorkflow as C, StepStartedEvent as D, StepFailedEvent as E, InstallationStatus as F, ExecutionContext as G, AnyStep as H, StepStatus as I, LeafStep as J, InferStepOutput as K, SucceededInstallationState as L, InstallationData as M, InstallationError as N, StepSucceededEvent as O, InstallationState as P, StepMeta as Q, isCompletedState as R, executeUninstallWorkflow as S, StepEvent as T, BranchStep as U, isSucceededState as V, BranchStepOptions as W, Step as X, LeafStepOptions as Y, StepContextFactory as Z, ValidationSummary as _, RunValidationOptions as a, defineLeafStep as at, ExecuteWorkflowOptions as b, runInstallation as c, CustomInstallationStepDefinition as d, ValidationContext as et, CustomInstallationStepHandler as f, ValidationResult as g, ValidateStepTreeOptions as h, RunUninstallationOptions as i, defineBranchStep as it, InProgressInstallationState as j, ExecutionStatus as k, runUninstallation as l, StepValidationResult as m, CreateInitialUninstallationStateOptions as n, ValidationIssue as nt, createInitialInstallationState as o, isBranchStep as ot, defineCustomInstallationStep as p, InstallationContext as q, RunInstallationOptions as r, ValidationIssueSeverity as rt, createInitialUninstallationState as s, isLeafStep as st, CreateInitialInstallationStateOptions as t, ValidationExecutionContext as tt, runValidation as u, validateStepTree as v, InstallationHooks as w, createInitialState as x, CreateInitialStateOptions as y, isFailedState as z };

package/dist/cjs/management/index.cjs

@@ -13,13 +13,15 @@
  */
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_management = require('../management-iLQubQ7K.cjs');
+const require_management = require('../management-C6xG5bfl.cjs');
 
 exports.createInitialInstallationState = require_management.createInitialInstallationState;
+exports.createInitialUninstallationState = require_management.createInitialUninstallationState;
 exports.defineCustomInstallationStep = require_management.defineCustomInstallationStep;
 exports.isCompletedState = require_management.isCompletedState;
 exports.isFailedState = require_management.isFailedState;
 exports.isInProgressState = require_management.isInProgressState;
 exports.isSucceededState = require_management.isSucceededState;
 exports.runInstallation = require_management.runInstallation;
+exports.runUninstallation = require_management.runUninstallation;
 exports.runValidation = require_management.runValidation;

package/dist/cjs/management/index.d.cts

@@ -12,5 +12,5 @@
  * governing permissions and limitations under the License.
  */
 
-import { $ as isBranchStep, A as StepStatus, B as InferStepOutput, C as ExecutionStatus, D as InstallationError, E as InstallationData, F as isSucceededState, G as StepContextFactory, H as LeafStep, I as AnyStep, J as ValidationExecutionContext, K as StepMeta, L as BranchStep, M as isCompletedState, N as isFailedState, O as InstallationState, P as isInProgressState, Q as defineLeafStep, R as BranchStepOptions, S as StepSucceededEvent, T as InProgressInstallationState, U as LeafStepOptions, V as InstallationContext, W as Step, X as ValidationIssueSeverity, Y as ValidationIssue, Z as defineBranchStep, _ as executeWorkflow, a as runInstallation, b as StepFailedEvent, c as defineCustomInstallationStep, d as ValidationResult, et as isLeafStep, f as ValidationSummary, g as createInitialState, h as ExecuteWorkflowOptions, i as createInitialInstallationState, j as SucceededInstallationState, k as InstallationStatus, l as StepValidationResult, m as CreateInitialStateOptions, n as RunInstallationOptions, o as runValidation, p as validateStepTree, q as ValidationContext, r as RunValidationOptions, s as CustomInstallationStepHandler, t as CreateInitialInstallationStateOptions, u as ValidateStepTreeOptions, v as InstallationHooks, w as FailedInstallationState, x as StepStartedEvent, y as StepEvent, z as ExecutionContext } from "../index-DZxladgt.cjs";
-export { AnyStep, BranchStep, BranchStepOptions, CreateInitialInstallationStateOptions, CreateInitialStateOptions, CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, RunInstallationOptions, RunValidationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepStartedEvent, StepStatus, StepSucceededEvent, StepValidationResult, SucceededInstallationState, ValidateStepTreeOptions, ValidationContext, ValidationExecutionContext, ValidationIssue, ValidationIssueSeverity, ValidationResult, ValidationSummary, createInitialInstallationState, createInitialState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation, runValidation, validateStepTree };
+import { $ as StepMetaInfo, A as FailedInstallationState, B as isInProgressState, C as executeWorkflow, D as StepStartedEvent, E as StepFailedEvent, F as InstallationStatus, G as ExecutionContext, H as AnyStep, I as StepStatus, J as LeafStep, K as InferStepOutput, L as SucceededInstallationState, M as InstallationData, N as InstallationError, O as StepSucceededEvent, P as InstallationState, Q as StepMeta, R as isCompletedState, S as executeUninstallWorkflow, T as StepEvent, U as BranchStep, V as isSucceededState, W as BranchStepOptions, X as Step, Y as LeafStepOptions, Z as StepContextFactory, _ as ValidationSummary, a as RunValidationOptions, at as defineLeafStep, b as ExecuteWorkflowOptions, c as runInstallation, d as CustomInstallationStepDefinition, et as ValidationContext, f as CustomInstallationStepHandler, g as ValidationResult, h as ValidateStepTreeOptions, i as RunUninstallationOptions, it as defineBranchStep, j as InProgressInstallationState, k as ExecutionStatus, l as runUninstallation, m as StepValidationResult, n as CreateInitialUninstallationStateOptions, nt as ValidationIssue, o as createInitialInstallationState, ot as isBranchStep, p as defineCustomInstallationStep, q as InstallationContext, r as RunInstallationOptions, rt as ValidationIssueSeverity, s as createInitialUninstallationState, st as isLeafStep, t as CreateInitialInstallationStateOptions, tt as ValidationExecutionContext, u as runValidation, v as validateStepTree, w as InstallationHooks, x as createInitialState, y as CreateInitialStateOptions, z as isFailedState } from "../index-BVwQk9bx.cjs";
+export { AnyStep, BranchStep, BranchStepOptions, CreateInitialInstallationStateOptions, CreateInitialStateOptions, CreateInitialUninstallationStateOptions, CustomInstallationStepDefinition, CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, RunInstallationOptions, RunUninstallationOptions, RunValidationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepMetaInfo, StepStartedEvent, StepStatus, StepSucceededEvent, StepValidationResult, SucceededInstallationState, ValidateStepTreeOptions, ValidationContext, ValidationExecutionContext, ValidationIssue, ValidationIssueSeverity, ValidationResult, ValidationSummary, createInitialInstallationState, createInitialState, createInitialUninstallationState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeUninstallWorkflow, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation, runUninstallation, runValidation, validateStepTree };