@adobe/aio-commerce-lib-app 1.3.1 → 1.4.0

package/dist/es/{management-ByHvVJ12.mjs → management-CCsOfniv.mjs}

@@ -12,16 +12,16 @@
  * governing permissions and limitations under the License.
  */
 
-import { a as hasCustomInstallationSteps, c as hasEventing, d as hasAdminUiSdk, l as hasExternalEvents, n as hasWebhooks, s as hasCommerceEvents } from "./webhooks-CYo-pqbR.mjs";
+import { a as hasCustomInstallationSteps, c as hasEventing, d as hasAdminUiSdk, l as hasExternalEvents, n as hasWebhooks, s as hasCommerceEvents } from "./webhooks-Dhrkkip7.mjs";
 import { t as stringifyError } from "./error-DHlYzkbb.mjs";
 import { t as inspect } from "./logging-XIUXDK5T.mjs";
+import { unwrapHttpError } from "@adobe/aio-commerce-lib-api/utils";
 import camelcase from "camelcase";
 import { AdobeCommerceHttpClient, resolveCommerceHttpClientParams, resolveIoEventsHttpClientParams } from "@adobe/aio-commerce-lib-api";
 import { resolveAuthParams, resolveImsAuthParams } from "@adobe/aio-commerce-lib-auth";
 import { createCustomCommerceEventsApiClient, createEventProvider, createEventSubscription, deleteEventProvider, deleteEventSubscription, getAllEventProviders, getAllEventSubscriptions, updateEventingConfiguration } from "@adobe/aio-commerce-lib-events/commerce";
 import { createCustomAdobeIoEventsApiClient, createEventMetadataForProvider, createEventProvider as createEventProvider$1, createRegistration, deleteEventMetadataForProvider, deleteEventProvider as deleteEventProvider$1, deleteRegistration, getAllEventProviders as getAllEventProviders$1, getAllRegistrations } from "@adobe/aio-commerce-lib-events/io-events";
 import { createCustomCommerceWebhooksApiClient, getWebhookList, subscribeWebhook, unsubscribeWebhook } from "@adobe/aio-commerce-lib-webhooks/api";
-import { HTTPError } from "ky";
 
 //#region source/management/installation/workflow/hooks.ts
 /** Helper to call a hook if it exists. */
@@ -120,11 +120,11 @@ function getAtPath(data, path) {
 	return current;
 }
 /** Creates an installation error from an exception. */
-function createInstallationError(err, path, key = "STEP_EXECUTION_FAILED") {
+async function createInstallationError(err, path, key = "STEP_EXECUTION_FAILED") {
 	return {
 		path,
 		key,
-		message: err instanceof Error ? err.message : String(err)
+		message: await unwrapHttpError(err)
 	};
 }
 /** Creates a succeeded installation state. */
@@ -164,6 +164,28 @@ function createInitialState(options) {
 	};
 }
 /**
+* Creates a retry state from a failed state.
+* Preserves succeeded steps and their data so the workflow resumes from
+* the failed step rather than restarting from scratch.
+*/
+function createRetryState(failedState) {
+	return {
+		id: failedState.id,
+		startedAt: failedState.startedAt,
+		status: "in-progress",
+		step: resetFailedSteps(failedState.step),
+		data: failedState.data
+	};
+}
+/** Recursively resets non-succeeded steps back to "pending". */
+function resetFailedSteps(step) {
+	return {
+		...step,
+		status: step.status === "succeeded" ? "succeeded" : "pending",
+		children: step.children.map(resetFailedSteps)
+	};
+}
+/**
 * Executes a workflow from an initial state. Returns the final state (never throws).
 */
 async function executeWorkflow(options) {
@@ -188,7 +210,7 @@ async function executeWorkflowWithMode(options, mode) {
 		id: initialState.id,
 		startedAt: initialState.startedAt,
 		step,
-		data: null,
+		data: initialState.data,
 		error: null,
 		hooks,
 		mode
@@ -205,7 +227,7 @@ async function executeWorkflowWithMode(options, mode) {
 		await callHook(hooks, "onInstallationSuccess", succeeded);
 		return succeeded;
 	} catch (err) {
-		const error = context.error ?? createInstallationError(err, [], "INSTALLATION_FAILED");
+		const error = context.error ?? await createInstallationError(err, [], "INSTALLATION_FAILED");
 		const failed = createFailedState({
 			step: context.step,
 			id: context.id,
@@ -248,6 +270,7 @@ function snapshot(context) {
 }
 /** Executes a single step (branch or leaf) recursively. */
 async function executeStep(step, stepStatus, inherited, context) {
+	if (stepStatus.status === "succeeded") return;
 	const { path } = stepStatus;
 	const isLeaf = isLeafStep(step);
 	stepStatus.status = "in-progress";
@@ -269,7 +292,7 @@ async function executeStep(step, stepStatus, inherited, context) {
 		}, snapshot(context));
 	} catch (err) {
 		stepStatus.status = "failed";
-		context.error ??= createInstallationError(err, path);
+		context.error ??= await createInstallationError(err, path);
 		await callHook(context.hooks, "onStepFailure", {
 			path,
 			stepName: step.name,
@@ -567,6 +590,19 @@ function defineCustomInstallationStep(handlerOrDefinition) {
 	return handlerOrDefinition;
 }
 
+//#endregion
+//#region source/management/installation/utils/http-error.ts
+/**
+* Unwraps an error via `unwrapHttpError`, prefixes it, logs it at error level,
+* and throws a new `Error` with the enriched message. Returns `Promise<never>`
+* so it composes cleanly inside `.catch()` without widening the surrounding type.
+*/
+async function throwHttpError(logger, error, prefix) {
+	const message = `${prefix}: ${await unwrapHttpError(error)}`;
+	logger.error(message);
+	throw new Error(message);
+}
+
 //#endregion
 //#region source/management/installation/admin-ui-sdk/helpers.ts
 /**
@@ -583,7 +619,7 @@ async function registerExtension(context) {
 		extensionTitle: appData.projectTitle,
 		extensionUrl: `https://${process.env.__OW_NAMESPACE}.adobeio-static.net/index.html`,
 		extensionWorkspace: appData.workspaceName
-	} } }).json();
+	} } }).json().catch((error) => throwHttpError(logger, error, "Failed to register Admin UI SDK extension"));
 	logger.info(`Admin UI SDK extension registered successfully: ${response.extensionId}`);
 	return response;
 }
@@ -602,7 +638,8 @@ async function uninstallExtension(context) {
 		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}": ${stringifyError(error)}. Continuing uninstall.`);
+		const msg = await unwrapHttpError(error);
+		logger.warn(`Failed to unregister Admin UI SDK extension "${extensionName}": ${msg}. Continuing uninstall.`);
 	}
 }
 
@@ -924,10 +961,7 @@ async function createIoEventProvider(params) {
 	}).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;
-	});
+	}).catch((error) => throwHttpError(logger, error, `Failed to create I/O Events provider '${provider.label}'`));
 }
 /**
 * Creates or retrieves an existing I/O Events provider.
@@ -974,10 +1008,7 @@ async function createIoEventProviderEventMetadata(params) {
 	}).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;
-	});
+	}).catch((error) => throwHttpError(logger, error, `Failed to register I/O Events metadata for '${eventCode}'`));
 }
 /**
 * Creates or retrieves existing I/O Events metadata for a given provider and event.
@@ -1025,10 +1056,7 @@ async function createIoEventRegistration(params) {
 	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;
-	});
+	}).catch((error) => throwHttpError(logger, error, `Failed to create I/O Events registration '${name}'`));
 }
 /**
 * Creates or retrieves an existing I/O Events registration.
@@ -1067,10 +1095,7 @@ async function configureCommerceEventing(params, existingData) {
 			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;
-	});
+	}).catch((err) => throwHttpError(logger, err, "Failed to configure Adobe Commerce eventing"));
 }
 /**
 * Creates an event provider in Commerce for a given {@link IoEventProvider}.
@@ -1086,24 +1111,29 @@ async function createCommerceProvider(params) {
 	}).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;
-	});
+	}).catch((err) => throwHttpError(logger, err, `Failed to create Adobe Commerce event provider '${provider.label}'`));
 }
 /**
 * Creates or retrieves an existing Commerce event provider.
+*
+* Checks by `provider_id` first, since Commerce validates subscriptions against that field.
+* A previous partial run may have left multiple records sharing the same `instance_id` but
+* with different `provider_id` values; checking by `provider_id` first avoids re-creating a
+* provider that is already correctly registered.
+*
 * @param params - Parameters needed to create or get the Commerce provider.
-* @param existingData - Existing Commerce providers.
+* @param existingProviders - 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;
+	const existingByProviderId = existingProviders.find((p) => p.provider_id === provider.id);
+	if (existingByProviderId) {
+		logger.info(`Provider "${provider.label}" already exists with provider ID "${provider.id}", skipping creation.`);
+		return existingByProviderId;
 	}
+	const existingByInstanceId = findExistingProvider(existingProviders, provider.instance_id);
+	if (existingByInstanceId) logger.warn(`Provider "${provider.label}" exists (instance ID: ${provider.instance_id}) but with a different provider ID ("${existingByInstanceId.provider_id}" → "${provider.id}"). Registering updated provider in Commerce.`);
 	return createCommerceProvider(params);
 }
 /**
@@ -1129,10 +1159,7 @@ async function createCommerceEventSubscription(params) {
 	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;
-	});
+	}).catch((err) => throwHttpError(logger, err, `Failed to create Adobe Commerce event subscription for '${event.config.name}'`));
 }
 /**
 * Creates or retrieves an existing Commerce event subscription.
@@ -1262,7 +1289,8 @@ async function deleteIoEventRegistrations(providerData, provider, events, regist
 			});
 			logger.info(`Deleted registration "${registration.name}" (ID: ${registration.id}).`);
 		} catch (error) {
-			logger.warn(`Failed to delete registration "${registration.name}" (ID: ${registration.id}): ${stringifyError(error)}. Continuing uninstall.`);
+			const msg = await unwrapHttpError(error);
+			logger.warn(`Failed to delete I/O Events registration "${registration.name}" (ID: ${registration.id}): ${msg}. Continuing uninstall.`);
 		}
 	}
 }
@@ -1293,7 +1321,8 @@ async function deleteIoEventMetadata(providerData, provider, context) {
 			});
 			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}": ${stringifyError(error)}. Continuing uninstall.`);
+			const msg = await unwrapHttpError(error);
+			logger.warn(`Failed to delete I/O Events metadata "${eventMetadata.event_code}" from provider "${providerData.id}": ${msg}. Continuing uninstall.`);
 		}
 	}
 }
@@ -1316,7 +1345,8 @@ async function deleteIoEventProvider(providerData, provider, context) {
 		});
 		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}): ${stringifyError(error)}. Continuing uninstall.`);
+		const msg = await unwrapHttpError(error);
+		logger.warn(`Failed to delete I/O Events provider "${provider.label}" (ID: ${providerData.id}): ${msg}. Continuing uninstall.`);
 	}
 }
 /**
@@ -1364,7 +1394,8 @@ async function deleteCommerceEventSubscriptions(events, metadata, provider, exis
 			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}": ${stringifyError(error)}. Continuing uninstall.`);
+			const msg = await unwrapHttpError(error);
+			logger.warn(`Failed to unsubscribe Adobe Commerce event subscription for "${eventName}": ${msg}. Continuing uninstall.`);
 		}
 	}
 }
@@ -1387,7 +1418,8 @@ async function deleteCommerceEventProvider(metadata, provider, existingProviders
 		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}): ${stringifyError(error)}. Continuing uninstall.`);
+		const msg = await unwrapHttpError(error);
+		logger.warn(`Failed to delete Adobe Commerce event provider "${provider.label}" (provider_id: ${commerceProvider.provider_id}): ${msg}. Continuing uninstall.`);
 	}
 }
 /**
@@ -1474,15 +1506,13 @@ async function createCommerceEvents(config, context) {
 			data: {
 				ioEvents: providerData,
 				commerce: commerceProvider,
-				events: eventsData.map(({ config, data }, index) => {
-					return {
-						config,
-						data: {
-							...data,
-							subscription: subscriptions[index]
-						}
-					};
-				})
+				events: eventsData.map(({ config, data }, index) => ({
+					config,
+					data: {
+						...data,
+						subscription: subscriptions[index]
+					}
+				}))
 			}
 		} });
 	}
@@ -1802,7 +1832,7 @@ async function deleteWebhookSubscriptions(config, context) {
 			logger.info(`Unsubscribed webhook: ${getWebhookName(webhook)}`);
 			unsubscribedWebhooks.push(params);
 		} catch (error) {
-			logger.warn(`Failed to unsubscribe webhook "${getWebhookName(webhook)}": ${stringifyError(error)}. Continuing uninstall.`);
+			logger.warn(`${stringifyError(error)}. Continuing uninstall.`);
 		}
 	}
 	logger.info(`Webhook unsubscriptions complete: ${unsubscribedWebhooks.length} unsubscribed.`);
@@ -1822,20 +1852,12 @@ 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.
+* Re-throws `err` as a new Error with an enriched message that includes the webhook name
+* and the unwrapped HTTP response body (if available).
 */
 async function rethrowWithWebhookName(err, webhookName, operation) {
-	if (err instanceof 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;
+	const msg = await unwrapHttpError(err);
+	throw new Error(`Failed to ${operation} webhook subscription for "${webhookName}": ${msg}`);
 }
 /**
 * Subscribes a single webhook to Commerce, enriching the error with the webhook name
@@ -1846,7 +1868,7 @@ async function createWebhookSubscription(client, resolvedWebhook) {
 		await client.subscribeWebhook(resolvedWebhook);
 		return resolvedWebhook;
 	} catch (err) {
-		return await rethrowWithWebhookName(err, getWebhookName(resolvedWebhook), "subscription");
+		return await rethrowWithWebhookName(err, getWebhookName(resolvedWebhook), "create");
 	}
 }
 /**
@@ -1857,7 +1879,7 @@ async function deleteWebhookSubscription(client, resolvedWebhook, params) {
 	try {
 		await client.unsubscribeWebhook(params);
 	} catch (err) {
-		await rethrowWithWebhookName(err, getWebhookName(resolvedWebhook), "unsubscription");
+		return rethrowWithWebhookName(err, getWebhookName(resolvedWebhook), "delete");
 	}
 }
 /**
@@ -2032,16 +2054,47 @@ function createInitialInstallationState(options) {
 }
 /**
 * Runs the full installation workflow. Returns the final state (never throws).
+*
+* Retries once on failure. `onInstallationFailure` only fires if both attempts fail;
+* `isRetry: true` is set on the result when the retry succeeds.
 */
-function runInstallation(options) {
+async function runInstallation(options) {
 	const { installationContext, config, initialState, hooks } = options;
-	return executeWorkflow({
-		rootStep: createRootInstallationStep(config),
+	const rootStep = createRootInstallationStep(config);
+	const firstResult = await executeWorkflow({
+		rootStep,
 		installationContext,
 		config,
 		initialState,
-		hooks
+		hooks: {
+			...hooks,
+			onInstallationFailure: void 0,
+			onStepFailure: void 0
+		}
 	});
+	if (firstResult.status === "succeeded") return firstResult;
+	const { error } = firstResult;
+	installationContext.logger.warn(`Installation attempt 1 failed: step "${error.path.join(".")}", key "${error.key}"${error.message ? `, message "${error.message}"` : ""}. Retrying once.`);
+	return {
+		...await executeWorkflow({
+			rootStep,
+			installationContext,
+			config,
+			initialState: createRetryState(firstResult),
+			hooks: hooks && {
+				...hooks,
+				onInstallationSuccess: (state) => hooks.onInstallationSuccess?.({
+					...state,
+					metadata: { isRetry: true }
+				}),
+				onInstallationFailure: (state) => hooks.onInstallationFailure?.({
+					...state,
+					metadata: { isRetry: true }
+				})
+			}
+		}),
+		metadata: { isRetry: true }
+	};
 }
 /**
 * Creates an initial uninstallation state from the config and step definitions.

package/dist/es/step-0eI2x4C9.d.mts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { n as CommerceAppConfigOutputModel } from "./app-DcY6dJiQ.mjs";
+import AioLogger from "@adobe/aio-lib-core-logging";
+import * as v from "valibot";
+import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
+
+//#region source/management/installation/schema.d.ts
+/** Schema for validating Adobe I/O app credentials required for installation. */
+declare const AppDataSchema: v.ObjectSchema<{
+  readonly consumerOrgId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly orgName: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly projectName: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly projectTitle: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly workspaceName: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly workspaceTitle: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+}, undefined>;
+/** Type for Adobe I/O app credentials. */
+type AppData = v.InferOutput<typeof AppDataSchema>;
+//#endregion
+//#region source/management/installation/workflow/step.d.ts
+/** Severity level of a validation issue. */
+type ValidationIssueSeverity = "error" | "warning" | "info";
+/** A single validation issue reported by a step's validate handler. */
+type ValidationIssue = {
+  /** Machine-readable code identifying the issue type. */code: string; /** Human-readable description of the issue. */
+  message: string; /** Severity of the issue. Only "error" severity blocks installation. */
+  severity: ValidationIssueSeverity; /** Optional additional context about the issue. */
+  details?: Record<string, unknown>;
+};
+/** Shared context available to all steps during installation. */
+type InstallationContext = {
+  /** The credentials of the app being installed */appData: AppData; /** The raw action parameters from the App Builder runtime action. */
+  params: RuntimeActionParams & {
+    AIO_COMMERCE_AUTH_IMS_CLIENT_ID: string;
+    AIO_COMMERCE_AUTH_IMS_CLIENT_SECRETS: string | string[];
+    AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_ID: string;
+    AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_EMAIL: string;
+    AIO_COMMERCE_AUTH_IMS_ORG_ID: string;
+    AIO_COMMERCE_AUTH_IMS_SCOPES: string | string[];
+  }; /** Logger instance for installation logging. */
+  logger: ReturnType<typeof AioLogger>; /** Custom scripts defined in the configuration (if any). */
+  customScripts?: Record<string, unknown>;
+};
+/** Factory function type for creating step-specific context. */
+type StepContextFactory<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = (context: InstallationContext) => TStepCtx | Promise<TStepCtx>;
+/** The execution context passed to leaf step run handlers. */
+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, 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 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, 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. */
+  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> & {
+  type: "branch"; /** An optional factory function to setup shared context for the children steps. */
+  context?: StepContextFactory<TStepCtx>; /** The children steps of this branch. */
+  children: TChildren;
+  /**
+   * Optional pre-installation validation handler for the branch itself.
+   * Called before children are validated. Returning an empty array means
+   * the branch has no issues at this level.
+   */
+  validate?: (config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>;
+};
+/** A step in the installation tree (discriminated union by `type`). */
+type Step<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> = LeafStep<TName, TConfig, TStepCtx, TOutput> | BranchStep<TName, TConfig, TStepCtx>;
+/** Loosely-typed step for use in non type-safe contexts. */
+interface AnyStep {
+  children?: AnyStep[];
+  context?: (context: InstallationContext) => any;
+  install?: (config: any, context: any) => unknown | Promise<unknown>;
+  meta: StepMeta;
+  name: string;
+  type: "leaf" | "branch";
+  uninstall?: (config: any, context: any) => void | Promise<void>;
+  validate?: (config: any, context: any) => ValidationIssue[] | Promise<ValidationIssue[]>;
+  when?: (config: CommerceAppConfigOutputModel) => boolean;
+}
+/** Check if a step is a leaf step. */
+declare function isLeafStep(step: AnyStep): step is LeafStep;
+/** Check if a step is a branch step. */
+declare function isBranchStep(step: AnyStep): step is BranchStep;
+/** Options for defining a leaf step. */
+type LeafStepOptions<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> = Omit<LeafStep<TName, TConfig, TStepCtx, TOutput>, "type">;
+/** Options for defining a branch step. */
+type BranchStepOptions<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TChildren extends AnyStep[] = AnyStep[]> = Omit<BranchStep<TName, TConfig, TStepCtx, TChildren>, "type">;
+/**
+ * Define a leaf step (executable, no children).
+ *
+ * @example
+ * ```typescript
+ * const createProviders = defineLeafStep({
+ *   name: "providers",
+ *   meta: { install: { label: "Create Providers", description: "Creates I/O Events providers" } },
+ *   install: async ({ config, stepContext }) => {
+ *     const { eventsClient } = stepContext;
+ *     return eventsClient.createProvider(config.eventing);
+ *   },
+ * });
+ * ```
+ */
+declare function defineLeafStep<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown>(options: LeafStepOptions<TName, TConfig, TStepCtx, TOutput>): {
+  type: "leaf";
+  name: TName;
+  meta: StepMeta;
+  when: ((config: CommerceAppConfigOutputModel) => config is TConfig) | undefined;
+  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;
+};
+/**
+ * Define a branch step (container with children, no runner).
+ *
+ * @example
+ * ```typescript
+ * const eventing = defineBranchStep({
+ *   name: "eventing",
+ *   meta: { install: { label: "Eventing", description: "Sets up I/O Events" } },
+ *   when: hasEventing,
+ *   context: async (ctx) => ({ eventsClient: await createEventsClient(ctx) }),
+ *   children: [commerceEventsStep, externalEventsStep],
+ * });
+ * ```
+ */
+declare function defineBranchStep<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, const TChildren extends AnyStep[] = AnyStep[]>(options: BranchStepOptions<TName, TConfig, TStepCtx, TChildren>): {
+  type: "branch";
+  name: TName;
+  meta: StepMeta;
+  when: ((config: CommerceAppConfigOutputModel) => config is TConfig) | undefined;
+  context: StepContextFactory<TStepCtx> | undefined;
+  children: TChildren;
+  validate: ((config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>) | undefined;
+};
+/** Infer the output type from a leaf step. */
+type InferStepOutput<TStep> = TStep extends LeafStep<infer _TName, infer _TConfig, infer _TStepCtx, infer TOutput> ? Awaited<TOutput> : never;
+//#endregion
+export { defineBranchStep as _, InferStepOutput as a, isLeafStep as b, LeafStepOptions as c, StepMeta as d, StepMetaInfo as f, ValidationIssueSeverity as g, ValidationIssue as h, ExecutionContext as i, Step as l, ValidationExecutionContext as m, BranchStep as n, InstallationContext as o, ValidationContext as p, BranchStepOptions as r, LeafStep as s, AnyStep as t, StepContextFactory as u, defineLeafStep as v, isBranchStep as y };

package/dist/es/{validate-CqJdGzyZ.mjs → validate-Dn3lLTGj.mjs}

@@ -12,8 +12,8 @@
  * governing permissions and limitations under the License.
  */
 
-import { a as hasCustomInstallationSteps, d as hasAdminUiSdk, i as hasCustomInstallation, l as hasExternalEvents, n as hasWebhooks, o as EventingSchema, r as InstallationSchema, s as hasCommerceEvents, t as WebhooksSchema, u as AdminUiSdkSchema } from "./webhooks-CYo-pqbR.mjs";
-import { t as alphaNumericOrHyphenSchema } from "./schemas-CVXHgUhv.mjs";
+import { t as alphaNumericOrHyphenSchema } from "./schemas-DOcnD16x.mjs";
+import { a as hasCustomInstallationSteps, d as hasAdminUiSdk, i as hasCustomInstallation, l as hasExternalEvents, n as hasWebhooks, o as EventingSchema, r as InstallationSchema, s as hasCommerceEvents, t as WebhooksSchema, u as AdminUiSdkSchema } from "./webhooks-Dhrkkip7.mjs";
 import { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core/error";
 import * as v from "valibot";
 import { SchemaBusinessConfig } from "@adobe/aio-commerce-lib-config";