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

package/dist/es/{runner-vwAhjD5r.mjs → management-DSexEPTW.mjs}

@@ -1,11 +1,27 @@
-import { a as hasCommerceEvents, o as hasEventing, r as hasCustomInstallationSteps, s as hasExternalEvents } from "./installation-BTL9X7iv.mjs";
-import { t as stringifyError } from "./error-CMV3IjBz.mjs";
-import { t as inspect } from "./logging-CzmXDzxI.mjs";
+/**
+ * @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 { a as hasCustomInstallationSteps, c as hasEventing, d as hasAdminUiSdk, l as hasExternalEvents, n as hasWebhooks, s as hasCommerceEvents } from "./webhooks-CYo-pqbR.mjs";
+import { t as stringifyError } from "./error-DHlYzkbb.mjs";
+import { t as inspect } from "./logging-XIUXDK5T.mjs";
 import camelcase from "camelcase";
-import { resolveAuthParams } from "@adobe/aio-commerce-lib-auth";
-import { resolveCommerceHttpClientParams, resolveIoEventsHttpClientParams } from "@adobe/aio-commerce-lib-api";
+import { AdobeCommerceHttpClient, resolveCommerceHttpClientParams, resolveIoEventsHttpClientParams } from "@adobe/aio-commerce-lib-api";
+import { resolveAuthParams, resolveImsAuthParams } from "@adobe/aio-commerce-lib-auth";
 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";
+import { createCustomCommerceWebhooksApiClient, getWebhookList, subscribeWebhook } 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. */
@@ -45,7 +61,8 @@ function defineLeafStep(options) {
 		name: options.name,
 		meta: options.meta,
 		when: options.when,
-		run: options.run
+		run: options.run,
+		validate: options.validate
 	};
 }
 /**
@@ -69,7 +86,8 @@ function defineBranchStep(options) {
 		meta: options.meta,
 		when: options.when,
 		context: options.context,
-		children: options.children
+		children: options.children,
+		validate: options.validate
 	};
 }
 
@@ -293,6 +311,104 @@ function isCompletedState(state) {
 	return state.status === "succeeded" || state.status === "failed";
 }
 
+//#endregion
+//#region source/management/installation/workflow/validation.ts
+/**
+* Runs validation over the full step tree, returning a structured result.
+*
+* - Respects `when` conditions (skips steps that don't apply to the config)
+* - Calls each step's optional `validate` handler
+* - Sets up branch context factories before validating children
+* - Never throws; all errors from validate handlers are caught and reported as issues
+*/
+async function validateStepTree(options) {
+	const { rootStep, validationContext, config } = options;
+	const result = await validateStep(rootStep, config, validationContext, []);
+	const summary = aggregateSummary(result);
+	return {
+		valid: summary.errors === 0 && summary.warnings === 0,
+		result,
+		summary
+	};
+}
+/** Recursively validates a single step and its children. */
+async function validateStep(step, config, context, parentPath) {
+	const path = [...parentPath, step.name];
+	const issues = await runStepValidation(step, config, context);
+	const children = [];
+	if (isBranchStep(step) && step.children.length > 0) {
+		const resolved = await resolveBranchContext(step, context);
+		issues.push(...resolved.issues);
+		for (const child of step.children) {
+			if (child.when && !child.when(config)) continue;
+			children.push(await validateStep(child, config, resolved.childContext, path));
+		}
+	}
+	return {
+		name: step.name,
+		path,
+		meta: step.meta,
+		issues,
+		children
+	};
+}
+/** Resolves the child context for a branch step, reporting errors as issues. */
+async function resolveBranchContext(step, context) {
+	if (!step.context) return {
+		childContext: context,
+		issues: []
+	};
+	try {
+		const stepContext = await step.context(context);
+		return {
+			childContext: {
+				...context,
+				...stepContext
+			},
+			issues: []
+		};
+	} catch (err) {
+		return {
+			childContext: context,
+			issues: [{
+				code: "VALIDATION_CONTEXT_ERROR",
+				message: err instanceof Error ? err.message : String(err),
+				severity: "error"
+			}]
+		};
+	}
+}
+/** Runs a step's validate handler, catching any thrown errors as issues. */
+async function runStepValidation(step, config, context) {
+	if (!step.validate) return [];
+	try {
+		return await step.validate(config, context);
+	} catch (err) {
+		return [{
+			code: "VALIDATION_HANDLER_ERROR",
+			message: err instanceof Error ? err.message : String(err),
+			severity: "error"
+		}];
+	}
+}
+/** Recursively aggregates issue counts across the full validation tree. */
+function aggregateSummary(result) {
+	let errors = 0;
+	let warnings = 0;
+	for (const issue of result.issues) if (issue.severity === "error") errors++;
+	else if (issue.severity === "warning") warnings++;
+	for (const child of result.children) {
+		const childSummary = aggregateSummary(child);
+		errors += childSummary.errors;
+		warnings += childSummary.warnings;
+	}
+	return {
+		totalIssues: errors + warnings,
+		errors,
+		warnings
+	};
+}
+
 //#endregion
 //#region source/management/installation/custom-installation/custom-scripts.ts
 /**
@@ -393,6 +509,62 @@ function defineCustomInstallationStep(handler) {
 	return handler;
 }
 
+//#endregion
+//#region source/management/installation/admin-ui-sdk/helpers.ts
+/**
+* Registers the extension with Commerce via POST /V1/adminuisdk/extension.
+*
+* @param context - The execution context providing the Commerce HTTP client and logger.
+* @returns The response from the Commerce API.
+*/
+async function registerExtension(context) {
+	const { commerceClient, appData, logger } = context;
+	logger.info(`Registering Admin UI SDK extension: ${appData.projectName}`);
+	const response = await commerceClient.post("adminuisdk/extension", { json: { extension: {
+		extensionName: process.env.__OW_NAMESPACE,
+		extensionTitle: appData.projectTitle,
+		extensionUrl: `https://${process.env.__OW_NAMESPACE}.adobeio-static.net/index.html`,
+		extensionWorkspace: appData.workspaceName
+	} } }).json();
+	logger.info(`Admin UI SDK extension registered successfully: ${response.extensionId}`);
+	return response;
+}
+
+//#endregion
+//#region source/management/installation/admin-ui-sdk/utils.ts
+/** Creates the Admin UI SDK step context with a lazy-initialized Commerce HTTP client. */
+const createAdminUiSdkStepContext = (installation) => {
+	const { params } = installation;
+	let commerceClient = null;
+	return { get commerceClient() {
+		if (commerceClient === null) commerceClient = new AdobeCommerceHttpClient(resolveCommerceHttpClientParams(params, { tryForwardAuthProvider: true }));
+		return commerceClient;
+	} };
+};
+
+//#endregion
+//#region source/management/installation/admin-ui-sdk/branch.ts
+/** Leaf step that calls POST /V1/adminuisdk/extension to register the extension. */
+const registerExtensionStep = defineLeafStep({
+	name: "register-extension",
+	meta: {
+		label: "Register Extension",
+		description: "Registers the Admin UI SDK extension in Adobe Commerce"
+	},
+	run: (_, context) => registerExtension(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"
+	},
+	when: hasAdminUiSdk,
+	context: createAdminUiSdkStepContext,
+	children: [registerExtensionStep]
+});
+
 //#endregion
 //#region source/management/installation/events/utils.ts
 const COMMERCE_PROVIDER_TYPE = "dx_commerce_events";
@@ -401,14 +573,20 @@ const PROVIDER_TYPE_TO_LABEL = {
 	[COMMERCE_PROVIDER_TYPE]: "Commerce",
 	[EXTERNAL_PROVIDER_TYPE]: "External"
 };
+/** Max characters taken from `metadata.id` in the I/O Events provider `instance_id`. */
+const METADATA_ID_MAX_LENGTH_FOR_INSTANCE_ID = 100;
 /**
-* Generates a unique instance ID for the given event provider within the context of the provided config.
+* Generates a unique instance ID for I/O Events for this app deployment.
+* Uses `{metadata.id (first 100 chars)}-{providerKeyOrSlug}-{workspaceId}` (lowercased).
+*
 * @param metadata - The metadata of the application
-* @param provider - The event provider for which to generate the instance ID
+* @param provider - The event provider (optional `key`, else label is slugified)
+* @param workspaceId - Adobe I/O Developer Console workspace ID for this deployment
 */
-function generateInstanceId(metadata, provider) {
+function generateInstanceId(metadata, provider, workspaceId) {
+	const appId = metadata.id.slice(0, METADATA_ID_MAX_LENGTH_FOR_INSTANCE_ID);
 	const slugLabel = provider.label.toLowerCase().replace(/\s+/g, "-");
-	return `${metadata.id}-${provider.key ?? slugLabel}`;
+	return `${appId}-${provider.key ?? slugLabel}-${workspaceId}`.toLowerCase();
 }
 /**
 * Find an existing event provider by its instance ID.
@@ -427,7 +605,6 @@ 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.
@@ -442,7 +619,7 @@ function findExistingRegistrations(allRegistrations, clientId, name) {
 * @param name
 */
 function getNamespacedEvent(metadata, name) {
-	return `${metadata.id}.${name}`;
+	return `${metadata.id}.${name}`.toLowerCase();
 }
 /**
 * Get the fully qualified name of an event for I/O Events based on the provider type.
@@ -450,7 +627,7 @@ function getNamespacedEvent(metadata, name) {
 * @param providerType - The type of the event provider.
 */
 function getIoEventCode(name, providerType) {
-	return providerType === COMMERCE_PROVIDER_TYPE ? `com.adobe.commerce.${name}` : name;
+	return providerType === "dx_commerce_events" ? `com.adobe.commerce.${name}` : name;
 }
 /**
 * Generates a registration name and description based on the provider, events, and runtime action.
@@ -458,7 +635,7 @@ function getIoEventCode(name, providerType) {
 * @param runtimeAction - The runtime action this registration points to.
 */
 function getRegistrationName(provider, runtimeAction) {
-	const providerLabel = PROVIDER_TYPE_TO_LABEL[provider.provider_metadata] ?? "Unknown";
+	const providerLabel = PROVIDER_TYPE_TO_LABEL[provider.provider_metadata];
 	const [packageName, actionName] = runtimeAction.split("/").map(kebabToTitleCase);
 	return `${providerLabel} Event Registration: ${actionName} (${packageName})`;
 }
@@ -582,8 +759,11 @@ async function getCommerceEventingExistingData(context) {
 	const { commerceEventsClient } = context;
 	const existingProviders = await commerceEventsClient.getAllEventProviders();
 	const existingSubscriptions = await commerceEventsClient.getAllEventSubscriptions();
+	const defaultProvider = existingProviders.find((provider) => !("id" in provider)) ?? null;
+	const isDefaultProviderConfigured = defaultProvider !== null;
 	return {
-		isDefaultWorkspaceConfigurationEmpty: existingProviders.some((provider) => !("id" in provider) && !provider.workspace_configuration?.trim()),
+		isDefaultProviderConfigured,
+		isDefaultWorkspaceConfigurationEmpty: isDefaultProviderConfigured ? !defaultProvider.workspace_configuration?.trim() : true,
 		providers: existingProviders,
 		subscriptions: new Map(existingSubscriptions.map((subscription) => [subscription.name, subscription]))
 	};
@@ -744,22 +924,30 @@ async function createOrGetIoEventRegistration(params, registrations) {
 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");
-	let updateParams = {
-		...config,
-		enabled: true
-	};
-	if (existingData.isDefaultWorkspaceConfigurationEmpty) {
-		if (!config.workspace_configuration) {
+	if (isDefaultProviderConfigured && !isDefaultWorkspaceConfigurationEmpty) {
+		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);
 		}
-		logger.info("Default provider workspace configuration already present, it will not be overriden");
-		const { workspace_configuration, ...rest } = updateParams;
-		updateParams = rest;
+		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 configuration with provided workspace configuration.");
 	return commerceEventsClient.updateEventingConfiguration(updateParams).then((success) => {
 		if (success) {
 			logger.info("Commerce Eventing Module configured successfully.");
@@ -858,7 +1046,7 @@ async function createOrGetCommerceEventSubscription(params, existingData) {
 async function onboardIoEvents(params, existingData) {
 	const { providersWithMetadata, registrations } = existingData;
 	const { context, metadata, provider, providerType, events } = params;
-	const instanceId = generateInstanceId(metadata, provider);
+	const instanceId = generateInstanceId(metadata, provider, context.appData.workspaceId);
 	const providerData = await createOrGetIoEventProvider({
 		context,
 		provider: {
@@ -1099,19 +1287,224 @@ const eventingStep = defineBranchStep({
 });
 
 //#endregion
-//#region source/management/installation/webhooks/helpers.ts
-function createWebhookSubscriptions(context) {
-	const { logger } = context;
-	logger.info("Creating webhooks in Commerce");
-	return { subscriptionsCreated: true };
+//#region source/management/installation/webhooks/context.ts
+/**
+* Create a custom Commerce Webhooks API Client with only the operations needed for installation.
+* @param params - The runtime action params to resolve the client params from.
+*/
+function createCommerceWebhooksApiClient(params) {
+	const commerceClientParams = resolveCommerceHttpClientParams(params, { tryForwardAuthProvider: true });
+	commerceClientParams.fetchOptions ??= {};
+	commerceClientParams.fetchOptions.timeout = 1e3 * 60 * 2;
+	return createCustomCommerceWebhooksApiClient(commerceClientParams, {
+		getWebhookList,
+		subscribeWebhook
+	});
+}
+/** Creates the webhooks step context with a lazy-initialized API client. */
+function createWebhooksStepContext(installation) {
+	const { params } = installation;
+	let commerceWebhooksClient = null;
+	return { get commerceWebhooksClient() {
+		if (commerceWebhooksClient === null) commerceWebhooksClient = createCommerceWebhooksApiClient(params);
+		return commerceWebhooksClient;
+	} };
 }
 
 //#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;
+//#region source/management/installation/webhooks/helpers.ts
+/** Matches any character that is not a valid identifier character (letter, digit, or underscore). */
+const NON_IDENTIFIER_CHAR_REGEX = /[^a-zA-Z0-9_]/g;
+/** Matches two or more consecutive underscores. */
+const MULTIPLE_UNDERSCORES_REGEX = /_+/g;
+/** Matches the `.magento` segment in plugin webhook method names (e.g. `plugin.magento.foo`). */
+const PLUGIN_MAGENTO_REGEX = /^plugin\.magento\./;
+const ENVIRONMENT_PRODUCTION = "production";
+const ENVIRONMENT_STAGING = "staging";
+/**
+* Validates that no modification webhooks in the app config conflict with webhooks
+* already registered in Commerce by another app.
+*
+* A conflict is: Commerce has a webhook with the same `webhook_method` and `webhook_type`
+* that does NOT belong to this app (i.e. different `batch_name` or `hook_name` after prefix).
+*
+* Returns a `ValidationIssue` with code `WEBHOOK_CONFLICTS` and `details.conflictedWebhooks` listing
+* every conflicting Commerce webhook when conflicts are found, or an empty array otherwise.
+*
+* @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 validateWebhookConflicts(config, context) {
+	const { logger, commerceWebhooksClient } = context;
+	const modificationWebhooks = config.webhooks.filter((entry) => entry.category === "modification");
+	if (modificationWebhooks.length === 0) {
+		logger.debug("No modification webhooks to validate, skipping conflict check.");
+		return [];
+	}
+	logger.debug(`Validating ${modificationWebhooks.length} modification webhook(s) for conflicts...`);
+	const existingWebhooks = await commerceWebhooksClient.getWebhookList();
+	const idPrefix = buildWebhookIdPrefix(config.metadata.id);
+	const conflictedWebhooks = [];
+	for (const entry of modificationWebhooks) {
+		const { webhook } = entry;
+		const resolvedBatch = `${idPrefix}${webhook.batch_name}`;
+		const resolvedHook = `${idPrefix}${webhook.hook_name}`;
+		for (const existing of existingWebhooks) if (existing.webhook_method === webhook.webhook_method && existing.webhook_type === webhook.webhook_type && !(existing.batch_name === resolvedBatch && existing.hook_name === resolvedHook)) {
+			conflictedWebhooks.push({
+				label: entry.label,
+				...existing
+			});
+			break;
+		}
+	}
+	if (conflictedWebhooks.length > 0) return [{
+		code: "WEBHOOK_CONFLICTS",
+		message: `Webhook conflicts detected: ${conflictedWebhooks.length} webhook(s) already registered for the same method and type by another app`,
+		severity: "warning",
+		details: { conflictedWebhooks }
+	}];
+	logger.info("No webhook conflicts found.");
+	return [];
+}
+/**
+* Subscribes each webhook from the app config to Adobe Commerce.
+* Throws on the first failure, aborting any remaining subscriptions.
+*
+* @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 createWebhookSubscriptions(config, context) {
+	const { logger, commerceWebhooksClient, params } = context;
+	logger.info(`Subscribing ${config.webhooks.length} webhook(s) to Commerce...`);
+	const idPrefix = buildWebhookIdPrefix(config.metadata.id);
+	const subscribedWebhooks = [];
+	const existingWebhooks = await commerceWebhooksClient.getWebhookList();
+	for (const entry of config.webhooks) {
+		const { webhook } = entry;
+		const resolvedUrl = "runtimeAction" in entry ? generateUrlForRuntimeAction(entry.runtimeAction) : entry.webhook.url;
+		logger.debug(`Subscribing webhook "${getWebhookName(webhook)}" (runtimeAction: ${"runtimeAction" in entry ? entry.runtimeAction : "none"})`);
+		const resolvedWebhook = {
+			...webhook,
+			url: resolvedUrl,
+			batch_name: `${idPrefix}${webhook.batch_name}`,
+			hook_name: `${idPrefix}${webhook.hook_name}`,
+			..."runtimeAction" in entry && entry.requireAdobeAuth !== false && { developer_console_oauth: resolveDeveloperConsoleOAuthCredentials(params) }
+		};
+		subscribedWebhooks.push(await createOrGetWebhookSubscription(existingWebhooks, commerceWebhooksClient, resolvedWebhook, logger));
+	}
+	logger.info(`Webhook subscriptions complete: ${subscribedWebhooks.length} subscribed.`);
+	return { subscribedWebhooks };
+}
+/**
+* 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)) {
+		logger.info(`Webhook already subscribed, skipping: ${getWebhookName(resolvedWebhook)}`);
+		return resolvedWebhook;
+	}
+	const subscribed = await createWebhookSubscription(client, resolvedWebhook);
+	logger.info(`Subscribed webhook: ${getWebhookName(resolvedWebhook)}`);
+	return subscribed;
+}
+/**
+* Subscribes a single webhook to Commerce, enriching the error with the webhook name
+* if the API responds with a string `message`.
+*/
+async function createWebhookSubscription(client, resolvedWebhook) {
+	try {
+		await client.subscribeWebhook(resolvedWebhook);
+		return resolvedWebhook;
+	} catch (err) {
+		if (err instanceof 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;
+	}
+}
+/**
+* Resolves and validates the IMS credentials required for `developer_console_oauth`.
+*
+* Delegates parsing and validation to `resolveImsAuthParams` from `aio-commerce-lib-auth`,
+* which correctly handles `AIO_COMMERCE_AUTH_IMS_CLIENT_SECRETS` whether it arrives as a
+* real array or as a JSON-stringified array string.
+*/
+function resolveDeveloperConsoleOAuthCredentials(params) {
+	const { AIO_COMMERCE_AUTH_IMS_ENVIRONMENT: imsEnvironment, ...imsParams } = params;
+	const { clientId, clientSecrets, imsOrgId } = resolveImsAuthParams(imsParams);
+	return {
+		client_id: clientId,
+		client_secret: clientSecrets[0],
+		org_id: imsOrgId,
+		environment: !imsEnvironment || String(imsEnvironment).startsWith("prod") ? ENVIRONMENT_PRODUCTION : ENVIRONMENT_STAGING
+	};
+}
+/**
+* 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.
+*
+* `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) {
+	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);
+}
+/**
+* Normalises a webhook method name by removing the `.magento` segment that Commerce
+* may drop when persisting plugin webhook methods.
+*
+* @example
+* normalizeWebhookMethod("plugin.magento.foo.bar") // → "plugin.foo.bar"
+* normalizeWebhookMethod("plugin.foo.bar")         // → "plugin.foo.bar" (unchanged)
+*/
+function normalizeWebhookMethod(method) {
+	return method.replace(PLUGIN_MAGENTO_REGEX, "plugin.");
+}
+/**
+* Generates a URL for a given runtime action using the AIO Runtime API host and namespace.
+* @param runtimeAction
+* @return The generated URL for the runtime action.
+*/
+function generateUrlForRuntimeAction(runtimeAction) {
+	const namespace = process.env.__OW_NAMESPACE;
+	if (!namespace) throw new Error(`Cannot generate URL for runtime action "${runtimeAction}": namespace environment variable is not set.`);
+	return `https://${namespace}.adobeioruntime.net/api/v1/web/${runtimeAction}`;
+}
+/**
+* Builds a prefix string from the app ID to namespace webhook batch/hook names.
+* Non-identifier characters are replaced with underscores; consecutive underscores
+* are collapsed to one; a trailing underscore is appended. The result is lowercased
+* to ensure consistent matching regardless of input casing.
+*
+* @example
+* ```typescript
+* buildWebhookIdPrefix("my--app.v2") // => "my_app_v2_"
+* buildWebhookIdPrefix("MyApp") // => "myapp_"
+* ```
+* @param appId - The app ID to build the prefix from.
+* @return The built prefix string.
+*/
+function buildWebhookIdPrefix(appId) {
+	const prefix = appId.toLowerCase().replace(NON_IDENTIFIER_CHAR_REGEX, "_").replace(MULTIPLE_UNDERSCORES_REGEX, "_");
+	return prefix.endsWith("_") ? prefix : `${prefix}_`;
+}
+/**
+* Generates a name for a webhook based on its method and type.
+*
+* @param webhook
+* @return A string in the format "webhook_method:webhook_type" to identify the webhook.
+*/
+function getWebhookName(webhook) {
+	return `${webhook.webhook_method}:${webhook.webhook_type}`;
 }
 
 //#endregion
@@ -1122,11 +1515,8 @@ const subscriptionsStep = defineLeafStep({
 		label: "Create Subscriptions",
 		description: "Creates webhook subscriptions in Adobe Commerce"
 	},
-	run: (config, context) => {
-		const { logger } = context;
-		logger.debug(config);
-		return createWebhookSubscriptions(context);
-	}
+	validate: (config, context) => validateWebhookConflicts(config, context),
+	run: (config, context) => createWebhookSubscriptions(config, context)
 });
 /** Branch step for setting up Commerce webhooks. */
 const webhooksStep = defineBranchStep({
@@ -1136,6 +1526,7 @@ const webhooksStep = defineBranchStep({
 		description: "Sets up Commerce webhooks"
 	},
 	when: hasWebhooks,
+	context: createWebhooksStepContext,
 	children: [subscriptionsStep]
 });
 
@@ -1148,6 +1539,7 @@ function createDefaultChildSteps(config) {
 	return [
 		eventingStep,
 		webhooksStep,
+		adminUiSdkStep,
 		createCustomInstallationStep(config)
 	];
 }
@@ -1192,6 +1584,22 @@ function runInstallation(options) {
 		hooks
 	});
 }
+/**
+* Runs pre-installation validation over the full step tree.
+*
+* Traverses the same step hierarchy used during installation but only calls
+* each step's optional `validate` handler rather than executing side effects.
+* Always resolves (never throws). Returns a structured result with per-step
+* issues and an aggregated summary.
+*/
+function runValidation(options) {
+	const { validationContext, config } = options;
+	return validateStepTree({
+		rootStep: createRootInstallationStep(config),
+		validationContext,
+		config
+	});
+}
 
 //#endregion
-export { isFailedState as a, isCompletedState as i, runInstallation as n, isInProgressState as o, defineCustomInstallationStep as r, isSucceededState as s, createInitialInstallationState as t };
+export { isCompletedState as a, isSucceededState as c, defineCustomInstallationStep as i, runInstallation as n, isFailedState as o, runValidation as r, isInProgressState as s, createInitialInstallationState as t };

package/dist/es/{router-CJ4VWoCt.mjs → router-BxaxEEu3.mjs}

@@ -1,3 +1,17 @@
+/**
+ * @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 { badRequest, internalServerError, methodNotAllowed, notFound } from "@adobe/aio-commerce-lib-core/responses";
 import AioLogger from "@adobe/aio-lib-core-logging";
 import { parse } from "regexparam";