@adobe/aio-commerce-lib-app 0.2.0 → 0.3.0

package/dist/es/management-Y7pwEbNI.mjs

@@ -0,0 +1,1204 @@
+import { a as hasExternalEvents, c as hasCustomInstallationSteps, i as hasEventing, r as hasCommerceEvents, t as stringifyError } from "./error-P7JgUTds.mjs";
+import { t as inspect } from "./logging-VgerMhp6.mjs";
+import camelcase from "camelcase";
+import { resolveAuthParams } from "@adobe/aio-commerce-lib-auth";
+import { resolveCommerceHttpClientParams, resolveIoEventsHttpClientParams } from "@adobe/aio-commerce-lib-api";
+import { createCustomCommerceEventsApiClient, createEventProvider, createEventSubscription, getAllEventProviders, getAllEventSubscriptions, updateEventingConfiguration } from "@adobe/aio-commerce-lib-events/commerce";
+import { createCustomAdobeIoEventsApiClient, createEventMetadataForProvider, createEventProvider as createEventProvider$1, createRegistration, getAllEventProviders as getAllEventProviders$1, getAllRegistrations } from "@adobe/aio-commerce-lib-events/io-events";
+
+//#region source/management/installation/workflow/hooks.ts
+/** Helper to call a hook if it exists. */
+async function callHook(hooks, hookName, ...args) {
+	const hook = hooks?.[hookName];
+	if (hook) await hook(...args);
+}
+
+//#endregion
+//#region source/management/installation/workflow/step.ts
+/** Check if a step is a leaf step. */
+function isLeafStep(step) {
+	return step.type === "leaf";
+}
+/** Check if a step is a branch step. */
+function isBranchStep(step) {
+	return step.type === "branch";
+}
+/**
+* Define a leaf step (executable, no children).
+*
+* @example
+* ```typescript
+* const createProviders = defineLeafStep({
+*   name: "providers",
+*   meta: { label: "Create Providers", description: "Creates I/O Events providers" },
+*   run: async ({ config, stepContext }) => {
+*     const { eventsClient } = stepContext;
+*     return eventsClient.createProvider(config.eventing);
+*   },
+* });
+* ```
+*/
+function defineLeafStep(options) {
+	return {
+		type: "leaf",
+		name: options.name,
+		meta: options.meta,
+		when: options.when,
+		run: options.run
+	};
+}
+/**
+* Define a branch step (container with children, no runner).
+*
+* @example
+* ```typescript
+* const eventing = defineBranchStep({
+*   name: "eventing",
+*   meta: { label: "Eventing", description: "Sets up I/O Events" },
+*   when: hasEventing,
+*   context: async (ctx) => ({ eventsClient: await createEventsClient(ctx) }),
+*   children: [commerceEventsStep, externalEventsStep],
+* });
+* ```
+*/
+function defineBranchStep(options) {
+	return {
+		type: "branch",
+		name: options.name,
+		meta: options.meta,
+		when: options.when,
+		context: options.context,
+		children: options.children
+	};
+}
+
+//#endregion
+//#region source/management/installation/workflow/utils.ts
+/** Returns the current time as an ISO string. */
+function nowIsoString() {
+	return (/* @__PURE__ */ new Date()).toISOString();
+}
+/** Sets a value at a nested path in the data object. */
+function setAtPath(data, path, value) {
+	const lastKey = path.at(-1);
+	if (!lastKey) return;
+	let current = data;
+	for (let i = 0; i < path.length - 1; i++) {
+		const key = path[i];
+		current[key] ??= {};
+		current = current[key];
+	}
+	current[lastKey] = value;
+}
+/** Gets a value at a nested path in the data object. */
+function getAtPath(data, path) {
+	let current = data;
+	for (const key of path) {
+		if (current == null || typeof current !== "object") return;
+		current = current[key];
+	}
+	return current;
+}
+/** Creates an installation error from an exception. */
+function createInstallationError(err, path, key = "STEP_EXECUTION_FAILED") {
+	return {
+		path,
+		key,
+		message: err instanceof Error ? err.message : String(err)
+	};
+}
+/** Creates a succeeded installation state. */
+function createSucceededState(base) {
+	return {
+		...base,
+		status: "succeeded",
+		completedAt: nowIsoString()
+	};
+}
+/** Creates a failed installation state. */
+function createFailedState(base, error) {
+	return {
+		...base,
+		status: "failed",
+		completedAt: nowIsoString(),
+		error
+	};
+}
+
+//#endregion
+//#region source/management/installation/workflow/runner.ts
+/**
+* Creates an initial installation state from a root step and config.
+*
+* Filters steps based on their `when` conditions and builds a
+* tree structure with all steps set to "pending".
+*/
+function createInitialState(options) {
+	const { rootStep, config } = options;
+	return {
+		id: crypto.randomUUID(),
+		startedAt: nowIsoString(),
+		status: "in-progress",
+		step: buildInitialStepStatus(rootStep, config, []),
+		data: null
+	};
+}
+/**
+* Executes a workflow from an initial state. Returns the final state (never throws).
+*/
+async function executeWorkflow(options) {
+	const { rootStep, installationContext, config, initialState, hooks } = options;
+	const step = structuredClone(initialState.step);
+	const context = {
+		installationContext,
+		config,
+		id: initialState.id,
+		startedAt: initialState.startedAt,
+		step,
+		data: null,
+		error: null,
+		hooks
+	};
+	await callHook(hooks, "onInstallationStart", snapshot(context));
+	try {
+		await executeStep(rootStep, context.step, {}, context);
+		const succeeded = createSucceededState({
+			id: context.id,
+			startedAt: context.startedAt,
+			step: context.step,
+			data: context.data
+		});
+		await callHook(hooks, "onInstallationSuccess", succeeded);
+		return succeeded;
+	} catch (err) {
+		const error = context.error ?? createInstallationError(err, [], "INSTALLATION_FAILED");
+		const failed = createFailedState({
+			step: context.step,
+			id: context.id,
+			startedAt: context.startedAt,
+			data: context.data
+		}, error);
+		await callHook(hooks, "onInstallationFailure", failed);
+		return failed;
+	}
+}
+/**
+* Builds initial step status from a step definition.
+* Filters steps based on their `when` conditions.
+*/
+function buildInitialStepStatus(step, config, parentPath) {
+	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));
+	}
+	return {
+		id: crypto.randomUUID(),
+		name: step.name,
+		path,
+		meta: step.meta,
+		status: "pending",
+		children
+	};
+}
+/** Snapshot current execution as InProgressInstallationState. */
+function snapshot(context) {
+	return {
+		id: context.id,
+		startedAt: context.startedAt,
+		status: "in-progress",
+		step: context.step,
+		data: context.data
+	};
+}
+/** Executes a single step (branch or leaf) recursively. */
+async function executeStep(step, stepStatus, inherited, context) {
+	const { path } = stepStatus;
+	const isLeaf = isLeafStep(step);
+	stepStatus.status = "in-progress";
+	await callHook(context.hooks, "onStepStart", {
+		path,
+		stepName: step.name,
+		isLeaf
+	}, snapshot(context));
+	try {
+		if (isBranchStep(step)) await executeBranchStep(step, stepStatus, inherited, context);
+		else if (isLeafStep(step)) await executeLeafStep(step, stepStatus, inherited, context);
+		stepStatus.status = "succeeded";
+		context.data ??= {};
+		await callHook(context.hooks, "onStepSuccess", {
+			path,
+			stepName: step.name,
+			isLeaf,
+			result: getAtPath(context.data, path)
+		}, snapshot(context));
+	} catch (err) {
+		stepStatus.status = "failed";
+		context.error ??= createInstallationError(err, path);
+		await callHook(context.hooks, "onStepFailure", {
+			path,
+			stepName: step.name,
+			isLeaf,
+			error: context.error
+		}, snapshot(context));
+		throw err;
+	}
+}
+/** Executes a branch step by processing its children. */
+async function executeBranchStep(step, stepStatus, inherited, context) {
+	let childContext = inherited;
+	if (step.context) {
+		const stepContext = await step.context(context.installationContext);
+		childContext = {
+			...inherited,
+			...stepContext
+		};
+	}
+	for (const child of stepStatus.children) {
+		const childStep = step.children.find((c) => c.name === child.name);
+		if (!childStep) throw new Error(`Step "${child.name}" not found`);
+		await executeStep(childStep, child, childContext, context);
+	}
+}
+/** Executes a leaf step and stores its result. */
+async function executeLeafStep(step, stepStatus, inherited, context) {
+	const executionContext = {
+		...context.installationContext,
+		...inherited
+	};
+	const result = await step.run(context.config, executionContext);
+	context.data ??= {};
+	setAtPath(context.data, stepStatus.path, result);
+}
+
+//#endregion
+//#region source/management/installation/workflow/types.ts
+/** Type guard for pending installation state. */
+/** Type guard for in-progress installation state. */
+function isInProgressState(state) {
+	return state.status === "in-progress";
+}
+/** Type guard for succeeded installation state. */
+function isSucceededState(state) {
+	return state.status === "succeeded";
+}
+/** Type guard for failed installation state. */
+function isFailedState(state) {
+	return state.status === "failed";
+}
+/** Type guard for completed installation state (succeeded or failed). */
+function isCompletedState(state) {
+	return state.status === "succeeded" || state.status === "failed";
+}
+
+//#endregion
+//#region source/management/installation/custom-installation/custom-scripts.ts
+/**
+* Creates a leaf step for executing a single custom installation script.
+*/
+function createCustomScriptStep(scriptConfig) {
+	const { script, name, description } = scriptConfig;
+	return defineLeafStep({
+		name: camelcase(name),
+		meta: {
+			label: name,
+			description
+		},
+		run: 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}`);
+			const scriptResult = await runFunction(config, context);
+			logger.info(`Successfully executed script: ${name}`);
+			return {
+				script,
+				data: scriptResult
+			};
+		}
+	});
+}
+/**
+* Creates child steps dynamically based on the custom installation scripts
+* defined in the configuration. Each script becomes a separate leaf step.
+*/
+function createCustomScriptSteps(config) {
+	if (!hasCustomInstallationSteps(config)) return [];
+	const steps = config.installation.customInstallationSteps;
+	if (new Set(steps.map((step) => step.name)).size !== steps.length) throw new Error("Duplicate step names detected in custom installation steps. Each step must have a unique name.");
+	return steps.map((scriptConfig) => createCustomScriptStep(scriptConfig));
+}
+
+//#endregion
+//#region source/management/installation/custom-installation/branch.ts
+/** Root custom installation step that executes custom installation scripts. */
+const customInstallationStepBase = defineBranchStep({
+	name: "customInstallationSteps",
+	meta: {
+		label: "Custom Installation Steps",
+		description: "Executes custom installation scripts defined in the application configuration"
+	},
+	when: hasCustomInstallationSteps,
+	children: []
+});
+/**
+* Creates the custom installation step with dynamic children based on config.
+* Each custom script becomes a direct child step.
+*/
+function createCustomInstallationStep(config) {
+	return {
+		...customInstallationStepBase,
+		children: createCustomScriptSteps(config)
+	};
+}
+
+//#endregion
+//#region source/management/installation/custom-installation/define.ts
+/**
+* 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)
+*
+* @example
+* ```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}...`);
+*
+*   // Your installation logic here
+*   // TypeScript will provide autocompletion for config and context
+*
+*   return {
+*     status: "success",
+*     message: "Setup completed",
+*   };
+* });
+* ```
+*/
+function defineCustomInstallationStep(handler) {
+	return handler;
+}
+
+//#endregion
+//#region source/management/installation/events/utils.ts
+const COMMERCE_PROVIDER_TYPE = "dx_commerce_events";
+const EXTERNAL_PROVIDER_TYPE = "3rd_party_custom_events";
+const PROVIDER_TYPE_TO_LABEL = {
+	[COMMERCE_PROVIDER_TYPE]: "Commerce",
+	[EXTERNAL_PROVIDER_TYPE]: "External"
+};
+/**
+* Generates a unique instance ID for the given event provider within the context of the provided config.
+* @param metadata - The metadata of the application
+* @param provider - The event provider for which to generate the instance ID
+*/
+function generateInstanceId(metadata, provider) {
+	const slugLabel = provider.label.toLowerCase().replace(/\s+/g, "-");
+	return `${metadata.id}-${provider.key ?? slugLabel}`;
+}
+/**
+* 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.
+*/
+function findExistingProvider(allProviders, instanceId) {
+	return allProviders.find((provider) => provider.instance_id === instanceId) ?? null;
+}
+/**
+* Find existing event metadata by its event name.
+* @param allMetadata - The list of all existing event metadata.
+* @param eventName - The event name to search for.
+*/
+function findExistingProviderMetadata(allMetadata, eventName) {
+	return allMetadata.find((meta) => meta.event_code === eventName) ?? null;
+}
+/**
+<<<<<<< HEAD
+* Find existing event registrations by client ID and name.
+* @param allRegistrations - The list of all existing event registrations.
+* @param clientId - The client ID of the workspace where the registration was created.
+* @param name - The name of the registration to search for.
+*/
+function findExistingRegistrations(allRegistrations, clientId, name) {
+	return allRegistrations.find((reg) => reg.client_id === clientId && reg.name === name);
+}
+/**
+* Generates a namespaced event name by combining the application ID with the event name.
+* @param metadata
+* @param name
+*/
+function getNamespacedEvent(metadata, name) {
+	return `${metadata.id}.${name}`;
+}
+/**
+* Get the fully qualified name of an event for I/O Events based on the provider type.
+* @param name - The name of the event.
+* @param providerType - The type of the event provider.
+*/
+function getIoEventCode(name, providerType) {
+	return providerType === COMMERCE_PROVIDER_TYPE ? `com.adobe.commerce.${name}` : name;
+}
+/**
+* Generates a registration name and description based on the provider, events, and runtime action.
+* @param provider - The provider this registration is associated to.
+* @param runtimeAction - The runtime action this registration points to.
+*/
+function getRegistrationName(provider, runtimeAction) {
+	const providerLabel = PROVIDER_TYPE_TO_LABEL[provider.provider_metadata] ?? "Unknown";
+	const [packageName, actionName] = runtimeAction.split("/").map(kebabToTitleCase);
+	return `${providerLabel} Event Registration: ${actionName} (${packageName})`;
+}
+/**
+* Generates a registration name and description based on the provider, events, and runtime action.
+* @param provider - The provider this registration is associated to.
+* @param events - The events routed by this registration.
+* @param runtimeAction - The runtime action this registration points to.
+*/
+function getRegistrationDescription(provider, events, runtimeAction) {
+	return [
+		"This registration was automatically created by @adobe/aio-commerce-lib-app. ",
+		`It belongs to the provider "${provider.label}" (instance ID: ${provider.instance_id}). `,
+		`It routes ${events.length} event(s) to the runtime action "${runtimeAction}".`
+	].join("\n");
+}
+/**
+* Converts a kebab-case string to Title Case.
+* @param str - The kebab-case string to convert.
+*/
+function kebabToTitleCase(str) {
+	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+/**
+* Groups events by their runtime actions. Since each event can have multiple
+* runtime actions, this function creates a mapping where each unique runtime
+* action points to all events that target it.
+*
+* @param events - The events to group by runtime actions.
+*/
+function groupEventsByRuntimeActions(events) {
+	const actionEventsMap = /* @__PURE__ */ new Map();
+	for (const event of events) for (const runtimeAction of event.runtimeActions) {
+		const existingEvents = actionEventsMap.get(runtimeAction) ?? [];
+		actionEventsMap.set(runtimeAction, [...existingEvents, event]);
+	}
+	return actionEventsMap;
+}
+function findExistingSubscription(allSubscriptions, eventName) {
+	return allSubscriptions.get(eventName) ?? null;
+}
+/**
+* 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.
+*
+* @param context - The execution context containing app credentials and parameters.
+*/
+function makeWorkspaceConfig(context) {
+	const { appData, params } = context;
+	const { consumerOrgId, orgName, projectId, projectName, projectTitle, workspaceId, workspaceName, workspaceTitle } = appData;
+	const authParams = resolveAuthParams(params);
+	if (authParams.strategy !== "ims") throw new Error("Failed to resolve IMS authentication parameters from the runtime action inputs.");
+	const { clientId, clientSecrets, technicalAccountEmail, technicalAccountId, imsOrgId, scopes } = authParams;
+	return { project: {
+		id: projectId,
+		name: projectName,
+		title: projectTitle,
+		org: {
+			id: consumerOrgId,
+			name: orgName,
+			ims_org_id: imsOrgId
+		},
+		workspace: {
+			id: workspaceId,
+			name: workspaceName,
+			title: workspaceTitle,
+			action_url: `https://${process.env.__OW_NAMESPACE}.adobeioruntime.net`,
+			app_url: `https://${process.env.__OW_NAMESPACE}.adobeio-static.net`,
+			details: { credentials: [{
+				id: "000000",
+				name: `aio-${workspaceId}`,
+				integration_type: "oauth_server_to_server",
+				oauth_server_to_server: {
+					client_id: clientId,
+					client_secrets: clientSecrets,
+					technical_account_email: technicalAccountEmail,
+					technical_account_id: technicalAccountId,
+					scopes: scopes.map((scope) => scope.trim())
+				}
+			}] }
+		}
+	} };
+}
+/**
+* Retrieves the current existing data and returns it in a normalized way.
+* @param context The execution context.
+*/
+async function getIoEventsExistingData(context) {
+	const { ioEventsClient, appData } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	const { _embedded: { providers: existingProviders } } = await ioEventsClient.getAllEventProviders({
+		consumerOrgId: appData.consumerOrgId,
+		withEventMetadata: true
+	});
+	const providersWithMetadata = existingProviders.map((providerHal) => {
+		const { _embedded, _links, ...providerData } = providerHal;
+		const actualMetadata = (_embedded?.eventmetadata ?? []).map(({ _embedded: _embedded$1, _links: _links$1, ...meta }) => ({
+			...meta,
+			sample: _embedded$1?.sample_event ?? null
+		}));
+		return {
+			...providerData,
+			metadata: actualMetadata
+		};
+	});
+	const { _embedded: { registrations: registrationsHal } } = await ioEventsClient.getAllRegistrations(appCredentials);
+	return {
+		providersWithMetadata,
+		registrations: registrationsHal.map(({ _links, ...reg }) => reg)
+	};
+}
+/**
+* Retrieves the current existing Commerce eventing data and returns it in a normalized way.
+* @param context - The execution context.
+*/
+async function getCommerceEventingExistingData(context) {
+	const { commerceEventsClient } = context;
+	const existingProviders = await commerceEventsClient.getAllEventProviders();
+	const existingSubscriptions = await commerceEventsClient.getAllEventSubscriptions();
+	return {
+		isDefaultWorkspaceConfigurationEmpty: existingProviders.some((provider) => !("id" in provider) && !provider.workspace_configuration?.trim()),
+		providers: existingProviders,
+		subscriptions: new Map(existingSubscriptions.map((subscription) => [subscription.name, subscription]))
+	};
+}
+
+//#endregion
+//#region source/management/installation/events/helpers.ts
+/**
+* Creates an event provider if it does not already exist.
+* @param params - The parameters necessary to create the provider.
+*/
+async function createIoEventProvider(params) {
+	const { context, provider } = params;
+	const { appData, ioEventsClient, logger } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	logger.info(`Creating provider "${provider.label}" with instance ID "${provider.instanceId}"`);
+	return ioEventsClient.createEventProvider({
+		...appCredentials,
+		label: provider.label,
+		providerType: provider.type,
+		instanceId: provider.instanceId,
+		description: provider.description
+	}).then((res) => {
+		logger.info(`Provider "${provider.label}" created with ID '${res.id}'`);
+		return res;
+	}).catch((error) => {
+		logger.error(`Failed to create provider "${provider.label}": ${stringifyError(error)}`);
+		throw error;
+	});
+}
+/**
+* Creates or retrieves an existing I/O Events provider.
+* @param params - Parameters needed to create or get the provider.
+* @param existingData - Existing I/O Events data.
+*/
+async function createOrGetIoEventProvider(params, existingData) {
+	const { context, provider } = params;
+	const { logger } = context;
+	const { instanceId, ...providerData } = provider;
+	const existing = findExistingProvider(existingData, instanceId);
+	if (existing) {
+		logger.info(`Provider "${provider.label}" already exists with ID "${existing.id}", skipping creation.`);
+		return existing;
+	}
+	return createIoEventProvider({
+		context,
+		provider: {
+			...providerData,
+			instanceId
+		}
+	});
+}
+/**
+* Creates an event metadata for a given provider and event.
+* @param params - The parameters necessary to create the event metadata.
+*/
+async function createIoEventProviderEventMetadata(params) {
+	const { context, event, provider, type, metadata } = params;
+	const { appData, ioEventsClient, logger } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	const eventCode = getIoEventCode(getNamespacedEvent(metadata, event.name), type);
+	logger.info(`Creating event metadata (${eventCode}) for provider "${provider.label}" (instance ID: ${provider.instance_id}))`);
+	return ioEventsClient.createEventMetadataForProvider({
+		...appCredentials,
+		providerId: provider.id,
+		label: event.label,
+		description: event.description,
+		eventCode
+	}).then((res) => {
+		logger.info(`Event metadata "${event.label}" created for provider "${provider.label}"`);
+		return res;
+	}).catch((error) => {
+		logger.error(`Failed to create event metadata "${event.label}" for provider "${provider.label}": ${stringifyError(error)}`);
+		throw error;
+	});
+}
+/**
+* Creates or retrieves existing I/O Events metadata for a given provider and event.
+* @param params - The parameters necessary to create or get the event metadata.
+* @param existingData - Existing I/O Events metadata for the provider.
+*/
+async function createOrGetIoProviderEventMetadata(params, existingData) {
+	const { context, event, provider, type, metadata } = params;
+	const { logger } = context;
+	const existing = findExistingProviderMetadata(existingData, getIoEventCode(getNamespacedEvent(metadata, event.name), type));
+	if (existing) {
+		logger.info(`Event metadata "${event.label}" already exists for provider "${provider.label}" (instance ID: ${provider.instance_id}), skipping creation.`);
+		return existing;
+	}
+	return createIoEventProviderEventMetadata(params);
+}
+/**
+* Creates an event registration bound to the given provider ID for a set of events targeting the given runtime action.
+* @param params - The parameters necessary to create the registration.
+*/
+async function createIoEventRegistration(params) {
+	const { context, events, provider, runtimeAction, metadata } = params;
+	const { appData, ioEventsClient, logger, params: runtimeParams } = context;
+	const appCredentials = {
+		consumerOrgId: appData.consumerOrgId,
+		projectId: appData.projectId,
+		workspaceId: appData.workspaceId
+	};
+	logger.info(`Creating registration(s) to runtime action "${runtimeAction}" for ${events.length} event(s) with provider "${provider.label}" (instance ID: ${provider.instance_id}))`);
+	const name = getRegistrationName(provider, runtimeAction);
+	const description = getRegistrationDescription(provider, events, runtimeAction);
+	const payload = {
+		...appCredentials,
+		name,
+		clientId: runtimeParams.AIO_COMMERCE_AUTH_IMS_CLIENT_ID,
+		description,
+		deliveryType: "webhook",
+		runtimeAction,
+		enabled: true,
+		eventsOfInterest: events.map((event) => ({
+			providerId: provider.id,
+			eventCode: getIoEventCode(getNamespacedEvent(metadata, event.name), provider.provider_metadata)
+		}))
+	};
+	return ioEventsClient.createRegistration(payload).then((res) => {
+		logger.info(`Registration "${name}" created for provider "${provider.label}" with ID '${res.id}'`);
+		return res;
+	}).catch((error) => {
+		logger.error(`Failed to create registration "${name}" for provider "${provider.label}": ${stringifyError(error)}`);
+		throw error;
+	});
+}
+/**
+* Creates or retrieves an existing I/O Events registration.
+* @param params - Parameters needed to create or get the registration.
+* @param existingData - Existing I/O Events data.
+*/
+async function createOrGetIoEventRegistration(params, registrations) {
+	const { context, provider, runtimeAction } = params;
+	const { logger, params: runtimeParams } = context;
+	const name = getRegistrationName(provider, runtimeAction);
+	const existing = findExistingRegistrations(registrations, runtimeParams.AIO_COMMERCE_AUTH_IMS_CLIENT_ID, name);
+	if (existing) {
+		logger.info(`Registration "${name}" already exists for provider "${provider.label}" with ID '${existing.id}', skipping creation.`);
+		return existing;
+	}
+	return createIoEventRegistration(params);
+}
+/**
+* Ensures Commerce Eventing is configured with the given configuration, updating it if it already exists.
+* @param eventsClient
+* @param params
+* @param existingData
+*/
+async function configureCommerceEventing(params, existingData) {
+	const { context, config } = params;
+	const { commerceEventsClient, logger } = context;
+	logger.info("Starting configuration of the Commerce Eventing Module");
+	let updateParams = {
+		...config,
+		enabled: true
+	};
+	if (existingData.isDefaultWorkspaceConfigurationEmpty) {
+		if (!config.workspaceConfiguration) {
+			const message = "Workspace configuration is required to enable Commerce Eventing when there is not an existing one.";
+			logger.error(message);
+			throw new Error(message);
+		}
+		logger.info("Default provider workspace configuration already present, it will not be overriden");
+		const { workspaceConfiguration, ...rest } = updateParams;
+		updateParams = rest;
+	}
+	logger.info("Updating Commerce Eventing configuration with provided workspace configuration.");
+	return commerceEventsClient.updateEventingConfiguration(updateParams).then((success) => {
+		if (success) {
+			logger.info("Commerce Eventing Module configured successfully.");
+			return;
+		}
+		throw new Error("Something went wrong while configuring Commerce Eventing Module. Response was not successful but no error was thrown.");
+	}).catch((err) => {
+		logger.error(`Failed to configure Commerce Eventing Module: ${stringifyError(err)}`);
+		throw err;
+	});
+}
+/**
+* Creates an event provider in Commerce for a given {@link IoEventProvider}.
+* @param params - The parameters necessary to create the Commerce provider.
+*/
+async function createCommerceProvider(params) {
+	const { context, provider } = params;
+	const { commerceEventsClient, logger } = context;
+	logger.info(`Creating Commerce provider "${provider.label}" with instance ID "${provider.instance_id}"`);
+	return commerceEventsClient.createEventProvider({
+		providerId: provider.id,
+		instanceId: provider.instance_id,
+		label: provider.label,
+		description: provider.description,
+		associatedWorkspaceConfiguration: provider.workspaceConfiguration
+	}).then((res) => {
+		logger.info(`Commerce provider "${provider.label}" created with ID '${res.provider_id}'`);
+		return res;
+	}).catch((err) => {
+		logger.error(`Failed to create Commerce provider "${provider.label}": ${stringifyError(err)}`);
+		throw err;
+	});
+}
+/**
+* Creates or retrieves an existing Commerce event provider.
+* @param params - Parameters needed to create or get the Commerce provider.
+* @param existingData - Existing Commerce providers.
+*/
+async function createOrGetCommerceProvider(params, existingProviders) {
+	const { context, provider } = params;
+	const { logger } = context;
+	const existing = findExistingProvider(existingProviders, provider.instance_id);
+	if (existing) {
+		logger.info(`Provider "${provider.label}" already exists with ID "${existing.id}", skipping creation.`);
+		return existing;
+	}
+	return createCommerceProvider(params);
+}
+/**
+* Creates an event subscription in Commerce for the given event and provider.
+* @param params - The parameters necessary to create the Commerce event subscription.
+*/
+async function createCommerceEventSubscription(params) {
+	const { context, metadata, provider, event } = params;
+	const { logger, commerceEventsClient } = context;
+	const eventName = getNamespacedEvent(metadata, event.config.name);
+	logger.info(`Creating event subscription for event "${event.config.name}" to provider "${provider.label}" (instance ID: ${provider.instance_id})`);
+	const eventSpec = {
+		name: eventName,
+		parent: event.config.name,
+		fields: event.config.fields,
+		providerId: provider.id,
+		destination: event.config.destination,
+		hipaaAuditRequired: event.config.hipaaAuditRequired,
+		prioritary: event.config.prioritary,
+		force: event.config.force
+	};
+	logger.debug(`Event subscription specification for event "${event.config.name}": ${inspect(eventSpec)}`);
+	return commerceEventsClient.createEventSubscription(eventSpec).then((_res) => {
+		logger.info(`Created event subscription for event "${event.config.name}" to provider "${provider.label} (instance ID: ${provider.instance_id})"`);
+		return eventSpec;
+	}).catch((err) => {
+		logger.error(`Failed to create event subscription for event "${event.config.name}" to provider "${provider.label}": ${stringifyError(err)}`);
+		throw err;
+	});
+}
+/**
+* Creates or retrieves an existing Commerce event subscription.
+* @param params - Parameters needed to create or get the subscription.
+* @param existingData - Map of existing Commerce subscriptions keyed by event name.
+*/
+async function createOrGetCommerceEventSubscription(params, existingData) {
+	const { context, metadata, event } = params;
+	const { logger } = context;
+	const existing = findExistingSubscription(existingData, getNamespacedEvent(metadata, event.config.name));
+	if (existing) {
+		logger.info(`Subscription for event "${event.config.name}" already exists, skipping creation.`);
+		return {
+			name: existing.name,
+			parent: existing.parent,
+			fields: existing.fields,
+			providerId: existing.provider_id
+		};
+	}
+	return createCommerceEventSubscription(params);
+}
+/**
+* Onboards a single event source to I/O Events by creating/retrieving the provider and its event metadata.
+* This is the shared logic inside the loop for both commerce and external event installation steps.
+*
+* @param params - Configuration for onboarding a single event source
+* @param existingData - Existing I/O Events data
+*/
+async function onboardIoEvents(params, existingData) {
+	const { providersWithMetadata, registrations } = existingData;
+	const { context, metadata, provider, providerType, events } = params;
+	const instanceId = generateInstanceId(metadata, provider);
+	const providerData = await createOrGetIoEventProvider({
+		context,
+		provider: {
+			...provider,
+			instanceId,
+			type: providerType
+		}
+	}, providersWithMetadata);
+	const metadataPromises = events.map((event) => createOrGetIoProviderEventMetadata({
+		metadata,
+		context,
+		type: providerType,
+		provider: providerData,
+		event
+	}, providersWithMetadata.find((p) => p.id === providerData.id)?.metadata ?? []));
+	const actionEventsMap = groupEventsByRuntimeActions(events);
+	const registrationPromises = Array.from(actionEventsMap.entries()).map(([runtimeAction, groupedEvents]) => createOrGetIoEventRegistration({
+		metadata,
+		context,
+		events: groupedEvents,
+		provider: providerData,
+		runtimeAction
+	}, registrations));
+	const [metadataData, registrationsData] = await Promise.all([Promise.all(metadataPromises), Promise.all(registrationPromises)]);
+	return {
+		providerData,
+		eventsData: events.map((event, index) => {
+			const eventRegistrations = event.runtimeActions.map((runtimeAction) => {
+				return registrationsData[Array.from(actionEventsMap.keys()).indexOf(runtimeAction)];
+			});
+			return {
+				config: {
+					...event,
+					providerType
+				},
+				data: {
+					metadata: metadataData[index],
+					registrations: eventRegistrations
+				}
+			};
+		})
+	};
+}
+/**
+* Onboards Commerce Eventing by creating event subscriptions and configuring the Eventing Module.
+* @param params - The parameters necessary to onboard Commerce Eventing.
+*/
+async function onboardCommerceEventing(params, existingData) {
+	const { context, metadata, ioData } = params;
+	const { events, provider, workspaceConfiguration } = ioData;
+	const instanceId = provider.instance_id;
+	const subscriptions = [];
+	await configureCommerceEventing({
+		context,
+		config: { workspaceConfiguration }
+	}, existingData);
+	const { workspace_configuration: _, ...commerceProviderData } = await createOrGetCommerceProvider({
+		context,
+		provider: {
+			id: provider.id,
+			instance_id: instanceId,
+			label: provider.label,
+			description: provider.description,
+			workspaceConfiguration
+		}
+	}, existingData.providers);
+	for (const event of events) subscriptions.push(await createOrGetCommerceEventSubscription({
+		context,
+		metadata,
+		provider,
+		event
+	}, existingData.subscriptions));
+	return {
+		commerceProvider: commerceProviderData,
+		subscriptions
+	};
+}
+
+//#endregion
+//#region source/management/installation/events/commerce.ts
+/** Leaf step for installing commerce event sources. */
+const commerceEventsStep = defineLeafStep({
+	name: "commerce",
+	meta: {
+		label: "Configure Commerce Events",
+		description: "Sets up I/O Events for Adobe Commerce event sources"
+	},
+	when: 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: config$1, data }, index) => {
+						return {
+							config: config$1,
+							data: {
+								...data,
+								subscription: subscriptions[index]
+							}
+						};
+					})
+				}
+			} });
+		}
+		logger.debug("Completed Commerce Events installation step.");
+		return stepData;
+	}
+});
+
+//#endregion
+//#region source/management/installation/events/context.ts
+/**
+* Create a custom Commerce API Client with only the operations we need for optimal package size.
+* @param params - The runtime action params to resolve the client params from.
+*/
+function createCommerceEventsApiClient(params) {
+	const commerceClientParams = resolveCommerceHttpClientParams(params, { tryForwardAuthProvider: true });
+	commerceClientParams.fetchOptions ??= {};
+	commerceClientParams.fetchOptions.timeout = 1e3 * 60 * 2;
+	return createCustomCommerceEventsApiClient(commerceClientParams, {
+		createEventProvider,
+		getAllEventProviders,
+		createEventSubscription,
+		getAllEventSubscriptions,
+		updateEventingConfiguration
+	});
+}
+/**
+* Create a custom Adobe I/O Events API Client with only the operations we need for optimal package size.
+* @param params - The runtime action params to resolve the client params from.
+*/
+function createIoEventsApiClient(params) {
+	const ioEventsClientParams = resolveIoEventsHttpClientParams(params);
+	ioEventsClientParams.fetchOptions ??= {};
+	ioEventsClientParams.fetchOptions.timeout = 1e3 * 60 * 2;
+	return createCustomAdobeIoEventsApiClient(ioEventsClientParams, {
+		createEventProvider: createEventProvider$1,
+		createEventMetadataForProvider,
+		createRegistration,
+		getAllEventProviders: getAllEventProviders$1,
+		getAllRegistrations
+	});
+}
+/** Creates the events step context with lazy-initialized API clients. */
+function createEventsStepContext(installation) {
+	const { params } = installation;
+	let commerceEventsClient = null;
+	let ioEventsClient = null;
+	return {
+		get commerceEventsClient() {
+			if (commerceEventsClient === null) commerceEventsClient = createCommerceEventsApiClient(params);
+			return commerceEventsClient;
+		},
+		get ioEventsClient() {
+			if (ioEventsClient === null) ioEventsClient = createIoEventsApiClient(params);
+			return ioEventsClient;
+		}
+	};
+}
+
+//#endregion
+//#region source/management/installation/events/external.ts
+/** Leaf step for installing external event sources. */
+const externalEventsStep = defineLeafStep({
+	name: "external",
+	meta: {
+		label: "Configure External Events",
+		description: "Sets up I/O Events for external event sources"
+	},
+	when: 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
+					}
+				}
+			} });
+		}
+		logger.debug("Completed External Events installation step.");
+		return stepData;
+	}
+});
+
+//#endregion
+//#region source/management/installation/events/branch.ts
+/** Root eventing step that contains commerce and external event sub-steps. */
+const eventingStep = defineBranchStep({
+	name: "eventing",
+	meta: {
+		label: "Eventing",
+		description: "Sets up the I/O Events and the Commerce events required by the application"
+	},
+	when: hasEventing,
+	context: createEventsStepContext,
+	children: [commerceEventsStep, externalEventsStep]
+});
+
+//#endregion
+//#region source/management/installation/webhooks/helpers.ts
+function createWebhookSubscriptions(context) {
+	const { logger } = context;
+	logger.info("Creating webhooks in Commerce");
+	return { subscriptionsCreated: true };
+}
+
+//#endregion
+//#region source/management/installation/webhooks/utils.ts
+/** Check if config has webhooks. */
+function hasWebhooks(config) {
+	"webhooks" in config && Array.isArray(config.webhooks) && config.webhooks.length;
+	return false;
+}
+
+//#endregion
+//#region source/management/installation/webhooks/branch.ts
+const subscriptionsStep = defineLeafStep({
+	name: "subscriptions",
+	meta: {
+		label: "Create Subscriptions",
+		description: "Creates webhook subscriptions in Adobe Commerce"
+	},
+	run: (config, context) => {
+		const { logger } = context;
+		logger.debug(config);
+		return createWebhookSubscriptions(context);
+	}
+});
+/** Branch step for setting up Commerce webhooks. */
+const webhooksStep = defineBranchStep({
+	name: "webhooks",
+	meta: {
+		label: "Webhooks",
+		description: "Sets up Commerce webhooks"
+	},
+	when: hasWebhooks,
+	children: [subscriptionsStep]
+});
+
+//#endregion
+//#region source/management/installation/root.ts
+/**
+* Creates the default child steps built-in in the library with dynamic children based on the config.
+*/
+function createDefaultChildSteps(config) {
+	return [
+		eventingStep,
+		webhooksStep,
+		createCustomInstallationStep(config)
+	];
+}
+/**
+* Creates a root installation step with dynamic children based on the config.
+*/
+function createRootInstallationStep(config) {
+	return defineBranchStep({
+		name: "installation",
+		meta: {
+			label: "Installation",
+			description: "App installation workflow"
+		},
+		children: createDefaultChildSteps(config)
+	});
+}
+
+//#endregion
+//#region source/management/installation/runner.ts
+/**
+* Creates an initial installation state from the config and step definitions.
+* Filters steps based on their `when` conditions and builds a tree structure
+* with all steps set to "pending".
+*/
+function createInitialInstallationState(options) {
+	const { config } = options;
+	return createInitialState({
+		rootStep: createRootInstallationStep(config),
+		config
+	});
+}
+/**
+* Runs the full installation workflow. Returns the final state (never throws).
+*/
+function runInstallation(options) {
+	const { installationContext, config, initialState, hooks } = options;
+	return executeWorkflow({
+		rootStep: createRootInstallationStep(config),
+		installationContext,
+		config,
+		initialState,
+		hooks
+	});
+}
+
+//#endregion
+export { isFailedState as a, isCompletedState as i, runInstallation as n, isInProgressState as o, defineCustomInstallationStep as r, isSucceededState as s, createInitialInstallationState as t };