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

package/dist/cjs/{management-iLQubQ7K.cjs → management-C6xG5bfl.cjs}

@@ -49,8 +49,8 @@ function isBranchStep(step) {
 * ```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);
 *   },
@@ -63,7 +63,8 @@ function defineLeafStep(options) {
 		name: options.name,
 		meta: options.meta,
 		when: options.when,
-		run: options.run,
+		install: options.install,
+		uninstall: options.uninstall,
 		validate: options.validate
 	};
 }
@@ -74,7 +75,7 @@ function defineLeafStep(options) {
 * ```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],
@@ -155,12 +156,12 @@ function createFailedState(base, error) {
 * tree structure with all steps set to "pending".
 */
 function createInitialState(options) {
-	const { rootStep, config } = options;
+	const { rootStep, config, mode } = options;
 	return {
 		id: crypto.randomUUID(),
 		startedAt: nowIsoString(),
 		status: "in-progress",
-		step: buildInitialStepStatus(rootStep, config, []),
+		step: buildInitialStepStatus(rootStep, config, [], mode),
 		data: null
 	};
 }
@@ -168,6 +169,19 @@ function createInitialState(options) {
 * Executes a workflow from an initial state. Returns the final state (never throws).
 */
 async function executeWorkflow(options) {
+	return executeWorkflowWithMode(options, "install");
+}
+/**
+* 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.
+*/
+async function executeUninstallWorkflow(options) {
+	return executeWorkflowWithMode(options, "uninstall");
+}
+/**
+* Internal implementation shared by executeWorkflow and executeUninstallWorkflow.
+*/
+async function executeWorkflowWithMode(options, mode) {
 	const { rootStep, installationContext, config, initialState, hooks } = options;
 	const step = structuredClone(initialState.step);
 	const context = {
@@ -178,7 +192,8 @@ async function executeWorkflow(options) {
 		step,
 		data: null,
 		error: null,
-		hooks
+		hooks,
+		mode
 	};
 	await callHook(hooks, "onInstallationStart", snapshot(context));
 	try {
@@ -207,18 +222,18 @@ async function executeWorkflow(options) {
 * Builds initial step status from a step definition.
 * Filters steps based on their `when` conditions.
 */
-function buildInitialStepStatus(step, config, parentPath) {
+function buildInitialStepStatus(step, config, parentPath, mode) {
 	const path = [...parentPath, step.name];
 	const children = [];
 	if (isBranchStep(step) && step.children.length > 0) for (const child of step.children) {
 		if (child.when && !child.when(config)) continue;
-		children.push(buildInitialStepStatus(child, config, path));
+		children.push(buildInitialStepStatus(child, config, path, mode));
 	}
 	return {
 		id: crypto.randomUUID(),
 		name: step.name,
 		path,
-		meta: step.meta,
+		meta: mode === "uninstall" && step.meta.uninstall ? step.meta.uninstall : step.meta.install,
 		status: "pending",
 		children
 	};
@@ -282,13 +297,17 @@ async function executeBranchStep(step, stepStatus, inherited, context) {
 		await executeStep(childStep, child, childContext, context);
 	}
 }
-/** Executes a leaf step and stores its result. */
+/** Executes a leaf step and stores its result, or runs uninstall if in uninstall mode. */
 async function executeLeafStep(step, stepStatus, inherited, context) {
 	const executionContext = {
 		...context.installationContext,
 		...inherited
 	};
-	const result = await step.run(context.config, executionContext);
+	if (context.mode === "uninstall") {
+		if (step.uninstall) await step.uninstall(context.config, executionContext);
+		return;
+	}
+	const result = await step.install(context.config, executionContext);
 	context.data ??= {};
 	setAtPath(context.data, stepStatus.path, result);
 }
@@ -349,7 +368,7 @@ async function validateStep(step, config, context, parentPath) {
 	return {
 		name: step.name,
 		path,
-		meta: step.meta,
+		meta: step.meta.install,
 		issues,
 		children
 	};
@@ -413,6 +432,12 @@ function aggregateSummary(result) {
 
 //#endregion
 //#region source/management/installation/custom-installation/custom-scripts.ts
+function isCustomInstallationStepDefinition(obj) {
+	return typeof obj === "object" && obj !== null && "install" in obj && typeof obj.install === "function";
+}
+function isCustomInstallationStepHandler(obj) {
+	return typeof obj === "function";
+}
 /**
 * Creates a leaf step for executing a single custom installation script.
 */
@@ -420,26 +445,48 @@ function createCustomScriptStep(scriptConfig) {
 	const { script, name, description } = scriptConfig;
 	return defineLeafStep({
 		name: (0, camelcase.default)(name),
-		meta: {
+		meta: { install: {
 			label: name,
 			description
-		},
-		run: async (config, context) => {
+		} },
+		install: async (config, context) => {
 			const { logger } = context;
 			const customScripts = context.customScripts || {};
 			logger.info(`Executing custom installation script: ${name}`);
 			logger.debug(`Script path: ${script}`);
 			const scriptModule = customScripts[script];
 			if (!scriptModule) throw new Error(`Script ${script} not found in customScripts context. Make sure the script is defined in the configuration and the action was generated with custom scripts support.`);
-			if (typeof scriptModule !== "object" || !("default" in scriptModule)) throw new Error(`Script ${script} must export a default function. Use defineCustomInstallationStep helper.`);
-			const runFunction = scriptModule.default;
-			if (typeof runFunction !== "function") throw new Error(`Script ${script} default export must be a function, got ${typeof runFunction}`);
+			if (typeof scriptModule !== "object" || !("default" in scriptModule)) throw new Error(`Script ${script} must export a default function or object. Use defineCustomInstallationStep helper.`);
+			const defaultExport = scriptModule.default;
+			let runFunction = null;
+			if (isCustomInstallationStepHandler(defaultExport)) runFunction = defaultExport;
+			else if (isCustomInstallationStepDefinition(defaultExport)) runFunction = defaultExport.install;
+			if (runFunction === null) throw new Error(`Script ${script} default export must be a function or an object with an install method. Use defineCustomInstallationStep helper.`);
 			const scriptResult = await runFunction(config, context);
 			logger.info(`Successfully executed script: ${name}`);
 			return {
 				script,
 				data: scriptResult
 			};
+		},
+		uninstall: async (config, context) => {
+			const { logger } = context;
+			const customScripts = context.customScripts || {};
+			logger.debug(`Uninstalling custom script: ${name}`);
+			const scriptModule = customScripts[script];
+			if (!scriptModule) throw new Error(`Script ${script} not found in customScripts context. Make sure the script is defined in the configuration and the action was generated with custom scripts support.`);
+			const defaultExport = scriptModule.default;
+			if (!isCustomInstallationStepDefinition(defaultExport)) {
+				logger.debug(`Script ${script} does not export an uninstall function, skipping uninstall.`);
+				return;
+			}
+			const { uninstall } = defaultExport;
+			if (!uninstall) {
+				logger.debug(`Script ${script} does not export an uninstall function, skipping uninstall.`);
+				return;
+			}
+			await uninstall(config, context);
+			logger.info(`Successfully uninstalled script: ${name}`);
 		}
 	});
 }
@@ -460,8 +507,14 @@ function createCustomScriptSteps(config) {
 const customInstallationStepBase = defineBranchStep({
 	name: "customInstallationSteps",
 	meta: {
-		label: "Custom Installation Steps",
-		description: "Executes custom installation scripts defined in the application configuration"
+		install: {
+			label: "Custom Installation Steps",
+			description: "Executes custom installation scripts defined in the application configuration"
+		},
+		uninstall: {
+			label: "Custom Uninstallation Steps",
+			description: "Executes custom uninstallation scripts defined in the application configuration"
+		}
 	},
 	when: require_webhooks.hasCustomInstallationSteps,
 	children: []
@@ -483,32 +536,37 @@ function createCustomInstallationStep(config) {
 * 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.
-*
-* @param handler - The installation step handler function
-* @returns The same handler function (for use as default export)
+* Accepts either a plain function (install only) or an object with `install` and optional
+* `uninstall` handlers.
 *
-* @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}...`);
+*   },
 * });
 * ```
 */
-function defineCustomInstallationStep(handler) {
-	return handler;
+function defineCustomInstallationStep(handlerOrDefinition) {
+	return handlerOrDefinition;
 }
 
 //#endregion
@@ -531,6 +589,24 @@ async function registerExtension(context) {
 	logger.info(`Admin UI SDK extension registered successfully: ${response.extensionId}`);
 	return response;
 }
+/**
+* Unregisters the extension from Commerce via DELETE /V1/adminuisdk/extension/:workspace_name/:extension_name.
+* Best-effort: errors are logged as warnings and do not stop the uninstall workflow.
+*
+* @param context - The execution context providing the Commerce HTTP client and logger.
+*/
+async function uninstallExtension(context) {
+	const { commerceClient, appData, logger } = context;
+	const extensionName = process.env.__OW_NAMESPACE;
+	const endpoint = `adminuisdk/extension/${appData.workspaceName}/${extensionName}`;
+	logger.info(`Unregistering Admin UI SDK extension "${extensionName}" from workspace "${appData.workspaceName}"...`);
+	try {
+		await commerceClient.delete(endpoint);
+		logger.info(`Admin UI SDK extension "${extensionName}" unregistered successfully.`);
+	} catch (error) {
+		logger.warn(`Failed to unregister Admin UI SDK extension "${extensionName}": ${require_error.stringifyError(error)}. Continuing uninstall.`);
+	}
+}
 
 //#endregion
 //#region source/management/installation/admin-ui-sdk/utils.ts
@@ -550,17 +626,30 @@ const createAdminUiSdkStepContext = (installation) => {
 const registerExtensionStep = defineLeafStep({
 	name: "register-extension",
 	meta: {
-		label: "Register Extension",
-		description: "Registers the Admin UI SDK extension in Adobe Commerce"
+		install: {
+			label: "Register Extension",
+			description: "Registers the Admin UI SDK extension in Adobe Commerce"
+		},
+		uninstall: {
+			label: "Unregister Extension",
+			description: "Removes the Admin UI SDK extension from Adobe Commerce"
+		}
 	},
-	run: (_, context) => registerExtension(context)
+	install: (_, context) => registerExtension(context),
+	uninstall: (_, context) => uninstallExtension(context)
 });
 /** Branch step for setting up the Admin UI SDK extension registration. */
 const adminUiSdkStep = defineBranchStep({
 	name: "admin-ui-sdk",
 	meta: {
-		label: "Admin UI SDK",
-		description: "Registers the extension with Adobe Commerce Admin UI SDK"
+		install: {
+			label: "Admin UI SDK",
+			description: "Registers the extension with Adobe Commerce Admin UI SDK"
+		},
+		uninstall: {
+			label: "Admin UI SDK",
+			description: "Removes the extension from Adobe Commerce Admin UI SDK"
+		}
 	},
 	when: require_webhooks.hasAdminUiSdk,
 	context: createAdminUiSdkStepContext,
@@ -591,6 +680,17 @@ function generateInstanceId(metadata, provider, workspaceId) {
 	return `${appId}-${provider.key ?? slugLabel}-${workspaceId}`.toLowerCase();
 }
 /**
+* Old version of instanceId generator which can be not unique within the same ORG.
+*
+* @param metadata - The metadata of the application
+* @param provider - The event provider for which to generate the instance ID
+* @deprecated use {@link generateInstanceId} instead
+*/
+function generateInstanceIdDeprecated(metadata, provider) {
+	const slugLabel = provider.label.toLowerCase().replace(/\s+/g, "-");
+	return `${metadata.id}-${provider.key ?? slugLabel}`.toLowerCase();
+}
+/**
 * Find an existing event provider by its instance ID.
 * @param allProviders - The list of all existing event providers.
 * @param instanceId - The instance ID to search for.
@@ -680,6 +780,37 @@ function findExistingSubscription(allSubscriptions, eventName) {
 	return allSubscriptions.get(eventName) ?? null;
 }
 /**
+* Builds the payload to send to Commerce when configuring Eventing.
+* Returns `null` when no update call is needed.
+*
+* @param initialParams - Initial Commerce Eventing configuration parameters.
+* @param existingData - Existing Commerce Eventing state from the API.
+*/
+function getCommerceEventingConfigurationUpdateParams(initialParams, existingData) {
+	const { isDefaultProviderConfigured, isDefaultWorkspaceConfigurationEmpty } = existingData;
+	if (isDefaultProviderConfigured && !isDefaultWorkspaceConfigurationEmpty) return null;
+	const { workspace_configuration, ...configWithoutWorkspace } = initialParams;
+	let updateParams = { enabled: true };
+	if (isDefaultWorkspaceConfigurationEmpty) {
+		if (!workspace_configuration) throw new Error("Workspace configuration is required to enable Commerce Eventing when there is not an existing one.");
+		updateParams.workspace_configuration = workspace_configuration;
+	}
+	if (!isDefaultProviderConfigured) updateParams = {
+		...updateParams,
+		...configWithoutWorkspace
+	};
+	return updateParams;
+}
+/**
+* Sanitizes a Commerce Eventing identifier.
+* Preserves underscores, converts spaces to underscores, lowercases, and strips the rest.
+*
+* @param value - The raw identifier value to normalize.
+*/
+function sanitizeEventingIdentifier(value) {
+	return value.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/g, "");
+}
+/**
 * Creates a partially filled workspace configuration object based on the app credentials and parameters.
 * This configuration is used when creating an event provider in Commerce.
 *
@@ -919,37 +1050,19 @@ async function createOrGetIoEventRegistration(params, registrations) {
 }
 /**
 * Ensures Commerce Eventing is configured with the given configuration, updating it if it already exists.
-* @param eventsClient
-* @param params
-* @param existingData
+* @param params - The parameters necessary to configure Commerce Eventing.
+* @param existingData - Existing Commerce Eventing data.
 */
 async function configureCommerceEventing(params, existingData) {
 	const { context, config } = params;
 	const { commerceEventsClient, logger } = context;
-	const { isDefaultProviderConfigured, isDefaultWorkspaceConfigurationEmpty } = existingData;
 	logger.info("Starting configuration of the Commerce Eventing Module");
-	if (isDefaultProviderConfigured && !isDefaultWorkspaceConfigurationEmpty) {
+	const updateParams = getCommerceEventingConfigurationUpdateParams(config, existingData);
+	if (updateParams === null) {
 		logger.info("Commerce Eventing Module is already configured, skipping configuration step.");
 		return;
 	}
-	const { workspace_configuration, ...configWithoutWorkspace } = config;
-	let updateParams = { enabled: true };
-	if (isDefaultWorkspaceConfigurationEmpty) {
-		if (!workspace_configuration) {
-			const message = "Workspace configuration is required to enable Commerce Eventing when there is not an existing one.";
-			logger.error(message);
-			throw new Error(message);
-		}
-		updateParams.workspace_configuration = workspace_configuration;
-		logger.info("Adding workspace configuration to Commerce Eventing configuration as it has not been set up yet.");
-	}
-	if (!isDefaultProviderConfigured) {
-		logger.info("Default provider not configured, it will be created with the provided configuration.");
-		updateParams = {
-			...updateParams,
-			...configWithoutWorkspace
-		};
-	}
+	logger.info(`Updating Commerce Eventing Module configuration with the following data: [${Object.keys(updateParams).join(", ")}]`);
 	return commerceEventsClient.updateEventingConfiguration(updateParams).then((success) => {
 		if (success) {
 			logger.info("Commerce Eventing Module configured successfully.");
@@ -1101,10 +1214,6 @@ async function onboardCommerceEventing(params, existingData) {
 	const { events, provider, workspaceConfiguration } = ioData;
 	const instanceId = provider.instance_id;
 	const subscriptions = [];
-	await configureCommerceEventing({
-		context,
-		config: { workspace_configuration: workspaceConfiguration }
-	}, existingData);
 	const { workspace_configuration: _, ...commerceProviderData } = await createOrGetCommerceProvider({
 		context,
 		provider: {
@@ -1126,6 +1235,181 @@ async function onboardCommerceEventing(params, existingData) {
 		subscriptions
 	};
 }
+/**
+* Deletes all I/O Events registrations for the given provider.
+* Registration names are reconstructed deterministically using the same logic as during installation.
+* Errors are caught and logged so that uninstall remains best-effort.
+*/
+async function deleteIoEventRegistrations(providerData, provider, events, registrations, context) {
+	const { ioEventsClient, appData, logger, params: runtimeParams } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	const actionEventsMap = groupEventsByRuntimeActions(events);
+	const registrationNames = new Set(Array.from(actionEventsMap.keys()).map((runtimeAction) => getRegistrationName(providerData, runtimeAction)));
+	const providerRegistrations = registrations.filter((reg) => reg.client_id === runtimeParams.AIO_COMMERCE_AUTH_IMS_CLIENT_ID && registrationNames.has(reg.name));
+	if (providerRegistrations.length === 0) {
+		logger.info(`No I/O Events registrations found for provider "${provider.label}" (instance ID: "${providerData.instance_id}").`);
+		return;
+	}
+	logger.info(`Deleting ${providerRegistrations.length} I/O Events registration(s) for provider "${provider.label}" (instance ID: "${providerData.instance_id}")...`);
+	for (const registration of providerRegistrations) {
+		logger.info(`Deleting registration "${registration.name}" (ID: ${registration.id})...`);
+		try {
+			await ioEventsClient.deleteRegistration({
+				...appCredentials,
+				registrationId: registration.registration_id
+			});
+			logger.info(`Deleted registration "${registration.name}" (ID: ${registration.id}).`);
+		} catch (error) {
+			logger.warn(`Failed to delete registration "${registration.name}" (ID: ${registration.id}): ${require_error.stringifyError(error)}. Continuing uninstall.`);
+		}
+	}
+}
+/**
+* Deletes all event metadata entries from the given I/O Events provider.
+* Errors are caught and logged so that uninstall remains best-effort.
+*/
+async function deleteIoEventMetadata(providerData, provider, context) {
+	const { ioEventsClient, appData, logger } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	const eventMetadataList = providerData.metadata ?? [];
+	if (eventMetadataList.length === 0) {
+		logger.info(`No event metadata found for provider "${provider.label}" (ID: ${providerData.id}).`);
+		return;
+	}
+	logger.info(`Deleting ${eventMetadataList.length} event metadata entry(s) for provider "${provider.label}" (ID: ${providerData.id})...`);
+	for (const eventMetadata of eventMetadataList) {
+		logger.info(`Deleting event metadata "${eventMetadata.event_code}" from provider "${providerData.id}"...`);
+		try {
+			await ioEventsClient.deleteEventMetadataForProvider({
+				...appCredentials,
+				providerId: providerData.id,
+				eventCode: eventMetadata.event_code
+			});
+			logger.info(`Deleted event metadata "${eventMetadata.event_code}" from provider "${providerData.id}".`);
+		} catch (error) {
+			logger.warn(`Failed to delete event metadata "${eventMetadata.event_code}" from provider "${providerData.id}": ${require_error.stringifyError(error)}. Continuing uninstall.`);
+		}
+	}
+}
+/**
+* Deletes a single I/O Events provider.
+* Errors are caught and logged so that uninstall remains best-effort.
+*/
+async function deleteIoEventProvider(providerData, provider, context) {
+	const { ioEventsClient, appData, logger } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	logger.info(`Deleting I/O Events provider "${provider.label}" (ID: ${providerData.id})...`);
+	try {
+		await ioEventsClient.deleteEventProvider({
+			...appCredentials,
+			providerId: providerData.id
+		});
+		logger.info(`Deleted I/O Events provider "${provider.label}" (ID: ${providerData.id}).`);
+	} catch (error) {
+		logger.warn(`Failed to delete I/O Events provider "${provider.label}" (ID: ${providerData.id}): ${require_error.stringifyError(error)}. Continuing uninstall.`);
+	}
+}
+/**
+* Offboards a single event source from I/O Events by deleting, in order:
+* 1. All registrations that reference events from this provider.
+* 2. All event metadata entries on the provider.
+* 3. The provider itself.
+*
+* This is the reverse of {@link onboardIoEvents} and is called during uninstall.
+* All deletion errors are caught and logged so that uninstall remains best-effort.
+*
+* @param params - Configuration identifying the provider to offboard.
+* @param existingData - Current I/O Events data (providers and registrations).
+*/
+async function offboardIoEvents(params, existingData) {
+	const { context, metadata, provider, events } = params;
+	const { appData, logger } = context;
+	const instanceId = generateInstanceId(metadata, provider, appData.workspaceId);
+	const instanceIdOldVersion = generateInstanceIdDeprecated(metadata, provider);
+	const providerData = existingData.providersWithMetadata.find((p) => p.instance_id === instanceId || p.instance_id === instanceIdOldVersion);
+	if (!providerData) {
+		logger.info(`No I/O Events provider found with instance ID "${instanceId}", skipping offboarding.`);
+		return;
+	}
+	await deleteIoEventRegistrations(providerData, provider, events, existingData.registrations, context);
+	await deleteIoEventMetadata(providerData, provider, context);
+	await deleteIoEventProvider(providerData, provider, context);
+}
+/**
+* Deletes all Commerce event subscriptions for the given events.
+* Subscriptions are matched by their namespaced name, built the same way as during installation.
+* Errors are caught and logged so that uninstall remains best-effort.
+*/
+async function deleteCommerceEventSubscriptions(events, metadata, provider, existingSubscriptions, context) {
+	const { commerceEventsClient, logger } = context;
+	logger.info(`Unsubscribing Commerce event subscriptions for provider "${provider.label}"...`);
+	for (const event of events) {
+		const eventName = getNamespacedEvent(metadata, event.name);
+		if (!existingSubscriptions.has(eventName)) {
+			logger.info(`No Commerce subscription found for event "${event.name}" (namespaced: "${eventName}"), skipping.`);
+			continue;
+		}
+		logger.info(`Unsubscribing Commerce event subscription for "${event.name}" (namespaced: "${eventName}")...`);
+		try {
+			await commerceEventsClient.deleteEventSubscription({ name: eventName });
+			logger.info(`Unsubscribed Commerce event subscription for "${eventName}".`);
+		} catch (error) {
+			logger.warn(`Failed to unsubscribe Commerce event subscription for "${eventName}": ${require_error.stringifyError(error)}. Continuing uninstall.`);
+		}
+	}
+}
+/**
+* Deletes a single Commerce-side event provider.
+* The provider is matched by its deterministic `instance_id`. If not found, deletion is skipped.
+* Errors are caught and logged so that uninstall remains best-effort.
+*/
+async function deleteCommerceEventProvider(metadata, provider, existingProviders, context) {
+	const { commerceEventsClient, appData, logger } = context;
+	const instanceId = generateInstanceId(metadata, provider, appData.workspaceId);
+	const instanceIdOldVersion = generateInstanceIdDeprecated(metadata, provider);
+	const commerceProvider = existingProviders.find((p) => p.instance_id === instanceId || p.instance_id === instanceIdOldVersion);
+	if (!commerceProvider) {
+		logger.info(`No Commerce event provider found with instance ID "${instanceId}", skipping provider deletion.`);
+		return;
+	}
+	logger.info(`Deleting Commerce event provider "${provider.label}" (provider_id: ${commerceProvider.provider_id})...`);
+	try {
+		await commerceEventsClient.deleteEventProvider({ provider_id: commerceProvider.provider_id });
+		logger.info(`Deleted Commerce event provider "${provider.label}" (provider_id: ${commerceProvider.provider_id}).`);
+	} catch (error) {
+		logger.warn(`Failed to delete Commerce event provider "${provider.label}" (provider_id: ${commerceProvider.provider_id}): ${require_error.stringifyError(error)}. Continuing uninstall.`);
+	}
+}
+/**
+* Offboards Commerce eventing for a single provider. Performs the following steps in order:
+* 1. Unsubscribes all event subscriptions that were created for the given provider.
+* 2. Deletes the Commerce-side event provider itself.
+*
+* Subscriptions are matched by their namespaced name, which is deterministic and built the
+* same way as during {@link onboardCommerceEventing}. The provider is matched by its
+* `instance_id`. Missing subscriptions or providers are silently skipped. All errors are
+* caught and logged so that uninstall remains best-effort.
+*
+* @param params - Configuration identifying the provider and its events to offboard.
+* @param existingData - Current Commerce eventing data (providers and subscriptions).
+*/
+async function offboardCommerceEventing(params, existingData) {
+	const { context, metadata, provider, events } = params;
+	await deleteCommerceEventSubscriptions(events, metadata, provider, existingData.subscriptions, context);
+	await deleteCommerceEventProvider(metadata, provider, existingData.providers, context);
+}
 
 //#endregion
 //#region source/management/installation/events/commerce.ts
@@ -1133,56 +1417,105 @@ async function onboardCommerceEventing(params, existingData) {
 const commerceEventsStep = defineLeafStep({
 	name: "commerce",
 	meta: {
-		label: "Configure Commerce Events",
-		description: "Sets up I/O Events for Adobe Commerce event sources"
+		install: {
+			label: "Configure Commerce Events",
+			description: "Sets up I/O Events for Adobe Commerce event sources"
+		},
+		uninstall: {
+			label: "Remove Commerce Events",
+			description: "Removes I/O Events for Adobe Commerce event sources"
+		}
 	},
 	when: require_webhooks.hasCommerceEvents,
-	run: async (config, context) => {
-		const { logger } = context;
-		logger.debug("Starting installation of Commerce Events with config:", config);
-		const stepData = [];
-		const workspaceConfiguration = JSON.stringify(makeWorkspaceConfig(context));
-		const existingIoEventsData = await getIoEventsExistingData(context);
-		const commerceEventingExistingData = await getCommerceEventingExistingData(context);
-		for (const { provider, events } of config.eventing.commerce) {
-			const { providerData, eventsData } = await onboardIoEvents({
-				context,
-				metadata: config.metadata,
-				provider,
-				events,
-				providerType: COMMERCE_PROVIDER_TYPE
-			}, existingIoEventsData);
-			const { commerceProvider, subscriptions } = await onboardCommerceEventing({
-				context,
-				metadata: config.metadata,
-				provider,
-				ioData: {
-					provider: providerData,
-					events: eventsData,
-					workspaceConfiguration
-				}
-			}, commerceEventingExistingData);
-			stepData.push({ provider: {
-				config: provider,
-				data: {
-					ioEvents: providerData,
-					commerce: commerceProvider,
-					events: eventsData.map(({ config, data }, index) => {
-						return {
-							config,
-							data: {
-								...data,
-								subscription: subscriptions[index]
-							}
-						};
-					})
-				}
-			} });
-		}
-		logger.debug("Completed Commerce Events installation step.");
-		return stepData;
-	}
+	install: createCommerceEvents,
+	uninstall: removeCommerceEvents
 });
+/**
+* Creates all needed entities for Eventing to work with Commerce and Adobe I/O Events.
+* @param config - The configuration of the app, with commerce events.
+* @param context - The execution context for the events installation.
+*/
+async function createCommerceEvents(config, context) {
+	const { logger } = context;
+	logger.debug("Starting installation of Commerce Events with config:", config);
+	const stepData = [];
+	const workspaceConfiguration = JSON.stringify(makeWorkspaceConfig(context));
+	const existingIoEventsData = await getIoEventsExistingData(context);
+	const commerceEventingExistingData = await getCommerceEventingExistingData(context);
+	for (let i = 0; i < config.eventing.commerce.length; i++) {
+		const { provider, events } = config.eventing.commerce[i];
+		const { providerData, eventsData } = await onboardIoEvents({
+			context,
+			metadata: config.metadata,
+			provider,
+			events,
+			providerType: COMMERCE_PROVIDER_TYPE
+		}, existingIoEventsData);
+		if (i === 0) await configureCommerceEventing({
+			context,
+			config: {
+				enabled: true,
+				merchant_id: sanitizeEventingIdentifier(context.appData.orgName),
+				environment_id: sanitizeEventingIdentifier(context.appData.projectName),
+				instance_id: providerData.instance_id,
+				workspace_configuration: workspaceConfiguration
+			}
+		}, commerceEventingExistingData);
+		const { commerceProvider, subscriptions } = await onboardCommerceEventing({
+			context,
+			metadata: config.metadata,
+			provider,
+			ioData: {
+				provider: providerData,
+				events: eventsData,
+				workspaceConfiguration
+			}
+		}, commerceEventingExistingData);
+		stepData.push({ provider: {
+			config: provider,
+			data: {
+				ioEvents: providerData,
+				commerce: commerceProvider,
+				events: eventsData.map(({ config, data }, index) => {
+					return {
+						config,
+						data: {
+							...data,
+							subscription: subscriptions[index]
+						}
+					};
+				})
+			}
+		} });
+	}
+	logger.debug("Completed Commerce Events installation step.");
+	return stepData;
+}
+/**
+* Remove all created for Commerce eventing created durint installation
+* @param config - The configuration of the app, with commerce events.
+* @param context - The execution context for the events installation.
+*/
+async function removeCommerceEvents(config, context) {
+	const { logger } = context;
+	logger.debug("Starting uninstall of Commerce Events with config:", config);
+	const [existingIoEventsData, commerceEventingExistingData] = await Promise.all([getIoEventsExistingData(context), getCommerceEventingExistingData(context)]);
+	for (const { provider, events } of config.eventing.commerce) {
+		await offboardCommerceEventing({
+			context,
+			metadata: config.metadata,
+			provider,
+			events
+		}, commerceEventingExistingData);
+		await offboardIoEvents({
+			context,
+			metadata: config.metadata,
+			provider,
+			events
+		}, existingIoEventsData);
+	}
+	logger.debug("Completed Commerce Events uninstall step.");
+}
 
 //#endregion
 //#region source/management/installation/events/context.ts
@@ -1198,6 +1531,8 @@ function createCommerceEventsApiClient(params) {
 		createEventProvider: _adobe_aio_commerce_lib_events_commerce.createEventProvider,
 		getAllEventProviders: _adobe_aio_commerce_lib_events_commerce.getAllEventProviders,
 		createEventSubscription: _adobe_aio_commerce_lib_events_commerce.createEventSubscription,
+		deleteEventProvider: _adobe_aio_commerce_lib_events_commerce.deleteEventProvider,
+		deleteEventSubscription: _adobe_aio_commerce_lib_events_commerce.deleteEventSubscription,
 		getAllEventSubscriptions: _adobe_aio_commerce_lib_events_commerce.getAllEventSubscriptions,
 		updateEventingConfiguration: _adobe_aio_commerce_lib_events_commerce.updateEventingConfiguration
 	});
@@ -1214,6 +1549,9 @@ function createIoEventsApiClient(params) {
 		createEventProvider: _adobe_aio_commerce_lib_events_io_events.createEventProvider,
 		createEventMetadataForProvider: _adobe_aio_commerce_lib_events_io_events.createEventMetadataForProvider,
 		createRegistration: _adobe_aio_commerce_lib_events_io_events.createRegistration,
+		deleteEventMetadataForProvider: _adobe_aio_commerce_lib_events_io_events.deleteEventMetadataForProvider,
+		deleteEventProvider: _adobe_aio_commerce_lib_events_io_events.deleteEventProvider,
+		deleteRegistration: _adobe_aio_commerce_lib_events_io_events.deleteRegistration,
 		getAllEventProviders: _adobe_aio_commerce_lib_events_io_events.getAllEventProviders,
 		getAllRegistrations: _adobe_aio_commerce_lib_events_io_events.getAllRegistrations
 	});
@@ -1241,38 +1579,68 @@ function createEventsStepContext(installation) {
 const externalEventsStep = defineLeafStep({
 	name: "external",
 	meta: {
-		label: "Configure External Events",
-		description: "Sets up I/O Events for external event sources"
+		install: {
+			label: "Configure External Events",
+			description: "Sets up I/O Events for external event sources"
+		},
+		uninstall: {
+			label: "Remove External Events",
+			description: "Removes I/O Events for external event sources"
+		}
 	},
 	when: require_webhooks.hasExternalEvents,
-	run: async (config, context) => {
-		const { logger } = context;
-		logger.debug("Starting installation of External Events with config:", config);
-		const stepData = [];
-		const existingIoEventsData = await getIoEventsExistingData(context);
-		for (const { provider, events } of config.eventing.external) {
-			const { providerData, eventsData } = await onboardIoEvents({
-				context,
-				metadata: config.metadata,
-				provider,
-				events,
-				providerType: EXTERNAL_PROVIDER_TYPE
-			}, existingIoEventsData);
-			stepData.push({ provider: {
-				config: provider,
-				data: {
-					ioEvents: providerData,
-					events: {
-						config: events,
-						data: eventsData
-					}
+	install: createExternalEvents,
+	uninstall: removeExternalEvents
+});
+/**
+* Creates all needed entities for External Events to work with Adobe I/O Events.
+* @param config - The configuration of the app, with external events.
+* @param context - The execution context for the events installation.
+*/
+async function createExternalEvents(config, context) {
+	const { logger } = context;
+	logger.debug("Starting installation of External Events with config:", config);
+	const stepData = [];
+	const existingIoEventsData = await getIoEventsExistingData(context);
+	for (const { provider, events } of config.eventing.external) {
+		const { providerData, eventsData } = await onboardIoEvents({
+			context,
+			metadata: config.metadata,
+			provider,
+			events,
+			providerType: EXTERNAL_PROVIDER_TYPE
+		}, existingIoEventsData);
+		stepData.push({ provider: {
+			config: provider,
+			data: {
+				ioEvents: providerData,
+				events: {
+					config: events,
+					data: eventsData
 				}
-			} });
-		}
-		logger.debug("Completed External Events installation step.");
-		return stepData;
+			}
+		} });
 	}
-});
+	logger.debug("Completed External Events installation step.");
+	return stepData;
+}
+/**
+* Removed all created entities for External Events during the installation
+* @param config - The configuration of the app, with external events.
+* @param context - The execution context for the events installation.
+*/
+async function removeExternalEvents(config, context) {
+	const { logger } = context;
+	logger.debug("Starting uninstall of External Events with config:", config);
+	const existingIoEventsData = await getIoEventsExistingData(context);
+	for (const { provider, events } of config.eventing.external) await offboardIoEvents({
+		context,
+		metadata: config.metadata,
+		provider,
+		events
+	}, existingIoEventsData);
+	logger.debug("Completed External Events uninstall step.");
+}
 
 //#endregion
 //#region source/management/installation/events/branch.ts
@@ -1280,8 +1648,14 @@ const externalEventsStep = defineLeafStep({
 const eventingStep = defineBranchStep({
 	name: "eventing",
 	meta: {
-		label: "Eventing",
-		description: "Sets up the I/O Events and the Commerce events required by the application"
+		install: {
+			label: "Eventing",
+			description: "Sets up the I/O Events and the Commerce events required by the application"
+		},
+		uninstall: {
+			label: "Eventing",
+			description: "Removes the I/O Events and Commerce events configured by the application"
+		}
 	},
 	when: require_webhooks.hasEventing,
 	context: createEventsStepContext,
@@ -1300,7 +1674,8 @@ function createCommerceWebhooksApiClient(params) {
 	commerceClientParams.fetchOptions.timeout = 1e3 * 60 * 2;
 	return (0, _adobe_aio_commerce_lib_webhooks_api.createCustomCommerceWebhooksApiClient)(commerceClientParams, {
 		getWebhookList: _adobe_aio_commerce_lib_webhooks_api.getWebhookList,
-		subscribeWebhook: _adobe_aio_commerce_lib_webhooks_api.subscribeWebhook
+		subscribeWebhook: _adobe_aio_commerce_lib_webhooks_api.subscribeWebhook,
+		unsubscribeWebhook: _adobe_aio_commerce_lib_webhooks_api.unsubscribeWebhook
 	});
 }
 /** Creates the webhooks step context with a lazy-initialized API client. */
@@ -1398,11 +1773,49 @@ async function createWebhookSubscriptions(config, context) {
 	return { subscribedWebhooks };
 }
 /**
+* Unsubscribes each webhook from the app config in Adobe Commerce.
+* If a webhook is not found in the existing list, it is silently skipped (idempotent).
+*
+* @param config - The app config (must have a non-empty `webhooks` array).
+* @param context - The webhooks execution context (provides the Commerce API client and logger).
+*/
+async function deleteWebhookSubscriptions(config, context) {
+	const { logger, commerceWebhooksClient } = context;
+	logger.info(`Unsubscribing ${config.webhooks.length} webhook(s) from Commerce...`);
+	const idPrefix = buildWebhookIdPrefix(config.metadata.id);
+	const unsubscribedWebhooks = [];
+	const existingWebhooks = await commerceWebhooksClient.getWebhookList();
+	for (const entry of config.webhooks) {
+		const { webhook } = entry;
+		const resolvedBatch = `${idPrefix}${webhook.batch_name}`;
+		const resolvedHook = `${idPrefix}${webhook.hook_name}`;
+		const params = {
+			webhook_method: webhook.webhook_method,
+			webhook_type: webhook.webhook_type,
+			batch_name: resolvedBatch,
+			hook_name: resolvedHook
+		};
+		if (!isWebhookInList(existingWebhooks, params)) {
+			logger.debug(`Webhook not found, skipping unsubscribe: ${getWebhookName(webhook)}`);
+			continue;
+		}
+		try {
+			await deleteWebhookSubscription(commerceWebhooksClient, webhook, params);
+			logger.info(`Unsubscribed webhook: ${getWebhookName(webhook)}`);
+			unsubscribedWebhooks.push(params);
+		} catch (error) {
+			logger.warn(`Failed to unsubscribe webhook "${getWebhookName(webhook)}": ${require_error.stringifyError(error)}. Continuing uninstall.`);
+		}
+	}
+	logger.info(`Webhook unsubscriptions complete: ${unsubscribedWebhooks.length} unsubscribed.`);
+	return { unsubscribedWebhooks };
+}
+/**
 * Subscribes a single webhook to Commerce, skipping the API call if the webhook
 * is already subscribed (matched by webhook_method, webhook_type, batch_name, hook_name).
 */
 async function createOrGetWebhookSubscription(existingWebhooks, client, resolvedWebhook, logger) {
-	if (isAlreadySubscribed(existingWebhooks, resolvedWebhook)) {
+	if (isWebhookInList(existingWebhooks, resolvedWebhook)) {
 		logger.info(`Webhook already subscribed, skipping: ${getWebhookName(resolvedWebhook)}`);
 		return resolvedWebhook;
 	}
@@ -1411,6 +1824,22 @@ async function createOrGetWebhookSubscription(existingWebhooks, client, resolved
 	return subscribed;
 }
 /**
+* Re-throws `err`, enriching the message with the webhook name if the error is an
+* `HTTPError` with a JSON body containing a string `message` field.
+*/
+async function rethrowWithWebhookName(err, webhookName, operation) {
+	if (err instanceof ky.HTTPError) {
+		let body;
+		try {
+			body = await err.response.json();
+		} catch {
+			throw err;
+		}
+		if (typeof body?.message === "string") throw new Error(`Webhook ${operation} failed for "${webhookName}": ${body.message}`);
+	}
+	throw err;
+}
+/**
 * Subscribes a single webhook to Commerce, enriching the error with the webhook name
 * if the API responds with a string `message`.
 */
@@ -1419,16 +1848,18 @@ async function createWebhookSubscription(client, resolvedWebhook) {
 		await client.subscribeWebhook(resolvedWebhook);
 		return resolvedWebhook;
 	} catch (err) {
-		if (err instanceof ky.HTTPError) {
-			let body;
-			try {
-				body = await err.response.json();
-			} catch {
-				throw err;
-			}
-			if (typeof body?.message === "string") throw new Error(`Webhook subscription failed for "${getWebhookName(resolvedWebhook)}": ${body.message}`);
-		}
-		throw err;
+		return await rethrowWithWebhookName(err, getWebhookName(resolvedWebhook), "subscription");
+	}
+}
+/**
+* Unsubscribes a single webhook from Commerce, enriching the error with the webhook name
+* if the API responds with a string `message`.
+*/
+async function deleteWebhookSubscription(client, resolvedWebhook, params) {
+	try {
+		await client.unsubscribeWebhook(params);
+	} catch (err) {
+		await rethrowWithWebhookName(err, getWebhookName(resolvedWebhook), "unsubscription");
 	}
 }
 /**
@@ -1449,14 +1880,14 @@ function resolveDeveloperConsoleOAuthCredentials(params) {
 	};
 }
 /**
-* Returns true when the candidate webhook is already present in the existing subscription list,
-* matched by the four-part identity: webhook_method, webhook_type, batch_name, hook_name.
+* Returns true when a webhook with the given four-part identity exists in the list.
 *
+* The identity check uses: webhook_method, webhook_type, batch_name, hook_name.
 * `webhook_method` is normalised before comparison to handle the case where Commerce strips the
 * `.magento` segment from plugin webhook methods on storage
 * (e.g. `plugin.magento.foo` and `plugin.foo` are treated as the same method).
 */
-function isAlreadySubscribed(existing, candidate) {
+function isWebhookInList(existing, candidate) {
 	const normalizedCandidate = normalizeWebhookMethod(candidate.webhook_method);
 	return existing.some((w) => normalizeWebhookMethod(w.webhook_method) === normalizedCandidate && w.webhook_type === candidate.webhook_type && w.batch_name === candidate.batch_name && w.hook_name === candidate.hook_name);
 }
@@ -1514,18 +1945,33 @@ function getWebhookName(webhook) {
 const subscriptionsStep = defineLeafStep({
 	name: "subscriptions",
 	meta: {
-		label: "Create Subscriptions",
-		description: "Creates webhook subscriptions in Adobe Commerce"
+		install: {
+			label: "Create Subscriptions",
+			description: "Creates webhook subscriptions in Adobe Commerce"
+		},
+		uninstall: {
+			label: "Delete Subscriptions",
+			description: "Deletes webhook subscriptions from Adobe Commerce"
+		}
 	},
 	validate: (config, context) => validateWebhookConflicts(config, context),
-	run: (config, context) => createWebhookSubscriptions(config, context)
+	install: (config, context) => createWebhookSubscriptions(config, context),
+	uninstall: async (config, context) => {
+		await deleteWebhookSubscriptions(config, context);
+	}
 });
 /** Branch step for setting up Commerce webhooks. */
 const webhooksStep = defineBranchStep({
 	name: "webhooks",
 	meta: {
-		label: "Webhooks",
-		description: "Sets up Commerce webhooks"
+		install: {
+			label: "Webhooks",
+			description: "Sets up Commerce webhooks"
+		},
+		uninstall: {
+			label: "Webhooks",
+			description: "Removes Commerce webhooks"
+		}
 	},
 	when: require_webhooks.hasWebhooks,
 	context: createWebhooksStepContext,
@@ -1551,10 +1997,23 @@ function createDefaultChildSteps(config) {
 function createRootInstallationStep(config) {
 	return defineBranchStep({
 		name: "installation",
-		meta: {
+		meta: { install: {
 			label: "Installation",
 			description: "App installation workflow"
-		},
+		} },
+		children: createDefaultChildSteps(config)
+	});
+}
+/**
+* Creates a root uninstallation step with dynamic children based on the config.
+*/
+function createRootUninstallationStep(config) {
+	return defineBranchStep({
+		name: "uninstallation",
+		meta: { install: {
+			label: "Uninstallation",
+			description: "App uninstallation workflow"
+		} },
 		children: createDefaultChildSteps(config)
 	});
 }
@@ -1587,6 +2046,30 @@ function runInstallation(options) {
 	});
 }
 /**
+* Creates an initial uninstallation state from the config and step definitions.
+*/
+function createInitialUninstallationState(options) {
+	const { config } = options;
+	return createInitialState({
+		rootStep: createRootUninstallationStep(config),
+		config,
+		mode: "uninstall"
+	});
+}
+/**
+* Runs the full uninstallation workflow. Returns the final state (never throws).
+*/
+function runUninstallation(options) {
+	const { installationContext, config, initialState, hooks } = options;
+	return executeUninstallWorkflow({
+		rootStep: createRootUninstallationStep(config),
+		installationContext,
+		config,
+		initialState,
+		hooks
+	});
+}
+/**
 * Runs pre-installation validation over the full step tree.
 *
 * Traverses the same step hierarchy used during installation but only calls
@@ -1610,6 +2093,12 @@ Object.defineProperty(exports, 'createInitialInstallationState', {
     return createInitialInstallationState;
   }
 });
+Object.defineProperty(exports, 'createInitialUninstallationState', {
+  enumerable: true,
+  get: function () {
+    return createInitialUninstallationState;
+  }
+});
 Object.defineProperty(exports, 'defineCustomInstallationStep', {
   enumerable: true,
   get: function () {
@@ -1646,6 +2135,12 @@ Object.defineProperty(exports, 'runInstallation', {
     return runInstallation;
   }
 });
+Object.defineProperty(exports, 'runUninstallation', {
+  enumerable: true,
+  get: function () {
+    return runUninstallation;
+  }
+});
 Object.defineProperty(exports, 'runValidation', {
   enumerable: true,
   get: function () {