@adobe/aio-commerce-lib-app 1.0.1 → 1.1.0

package/dist/es/config/index.mjs

@@ -1,5 +1,19 @@
-import { a as hasConfigDomain, c as hasBusinessConfigSchema, i as getConfigDomains, n as validateCommerceAppConfigDomain, o as hasMetadata, r as CommerceAppConfigSchemas, s as hasBusinessConfig, t as validateCommerceAppConfig } from "../validate-DKnju9-R.mjs";
-import { a as hasCommerceEvents, n as hasCustomInstallation, o as hasEventing, r as hasCustomInstallationSteps, s as hasExternalEvents } from "../installation-BTL9X7iv.mjs";
-import { d as defineConfig, n as readCommerceAppConfig, r as resolveCommerceAppConfig, t as parseCommerceAppConfig } from "../parser-CQZTVG6i.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.
+ */
 
-export { CommerceAppConfigSchemas, defineConfig, getConfigDomains, hasBusinessConfig, hasBusinessConfigSchema, hasCommerceEvents, hasConfigDomain, hasCustomInstallation, hasCustomInstallationSteps, hasEventing, hasExternalEvents, hasMetadata, parseCommerceAppConfig, readCommerceAppConfig, resolveCommerceAppConfig, validateCommerceAppConfig, validateCommerceAppConfigDomain };
+import { a as hasConfigDomain, c as hasBusinessConfigSchema, i as getConfigDomains, n as validateCommerceAppConfigDomain, o as hasMetadata, r as CommerceAppConfigSchemas, s as hasBusinessConfig, t as validateCommerceAppConfig } from "../validate-qRpfubPo.mjs";
+import { a as hasCustomInstallationSteps, c as hasEventing, i as hasCustomInstallation, l as hasExternalEvents, n as hasWebhooks, s as hasCommerceEvents } from "../webhooks-NgM6k3_r.mjs";
+import { d as defineConfig, n as readCommerceAppConfig, r as resolveCommerceAppConfig, t as parseCommerceAppConfig } from "../config-BbrkH0Xt.mjs";
+
+export { CommerceAppConfigSchemas, defineConfig, getConfigDomains, hasBusinessConfig, hasBusinessConfigSchema, hasCommerceEvents, hasConfigDomain, hasCustomInstallation, hasCustomInstallationSteps, hasEventing, hasExternalEvents, hasMetadata, hasWebhooks, parseCommerceAppConfig, readCommerceAppConfig, resolveCommerceAppConfig, validateCommerceAppConfig, validateCommerceAppConfigDomain };

package/dist/es/{parser-CQZTVG6i.mjs → config-BbrkH0Xt.mjs}

@@ -1,5 +1,19 @@
-import { t as validateCommerceAppConfig } from "./validate-DKnju9-R.mjs";
-import { t as stringifyError } from "./error-CMV3IjBz.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 { t as validateCommerceAppConfig } from "./validate-qRpfubPo.mjs";
+import { t as stringifyError } from "./error-DHlYzkbb.mjs";
 import { dirname, join, parse } from "path";
 import { existsSync } from "fs";
 import { access, mkdir, readFile } from "fs/promises";

package/dist/es/error-DHlYzkbb.mjs

@@ -0,0 +1,32 @@
+/**
+ * @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 { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core/error";
+
+//#region ../../packages-private/scripting-utils/source/error.ts
+/**
+* This module exports shared error utilities for the AIO Commerce SDK.
+* @packageDocumentation
+*/
+/**
+* Stringify an error to a human-friendly string.
+* @param error - The error to stringify.
+*/
+function stringifyError(error) {
+	if (error instanceof CommerceSdkValidationError) return error.display();
+	return error instanceof Error ? error.message : String(error);
+}
+
+//#endregion
+export { stringifyError as t };

package/dist/{cjs/runner-DemKouFJ.d.cts → es/index-D33OCH0D.d.mts}

@@ -1,7 +1,21 @@
-import { n as CommerceAppConfigOutputModel } from "./app-DWX5-Hsf.cjs";
-import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
-import * as v from "valibot";
+/**
+ * @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-Ct7Y0NP8.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. */
@@ -19,6 +33,15 @@ declare const AppDataSchema: v.ObjectSchema<{
 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. */
@@ -37,6 +60,13 @@ type InstallationContext = {
 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 `run`, not pre-flight validation.
+ */
+type ValidationContext = Omit<InstallationContext, "customScripts">;
+/** The context passed to step `validate` handlers (base validation context merged with step-level context). */
+type ValidationExecutionContext<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = ValidationContext & TStepCtx;
 /** Metadata for a step (used for UI display). */
 type StepMeta = {
   label: string;
@@ -52,12 +82,24 @@ type StepBase<TName extends string = string, TConfig extends CommerceAppConfigOu
 type LeafStep<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> = StepBase<TName, TConfig> & {
   type: "leaf"; /** The execution handler for the step. */
   run: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
+  /**
+   * 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[]>;
 };
 /** 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>> = 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: AnyStep[];
+  /**
+   * 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>;
@@ -69,6 +111,7 @@ interface AnyStep {
   name: string;
   run?: (config: any, context: any) => unknown | Promise<unknown>;
   type: "leaf" | "branch";
+  validate?: (config: any, context: any) => ValidationIssue[] | Promise<ValidationIssue[]>;
   when?: (config: CommerceAppConfigOutputModel) => boolean;
 }
 /** Check if a step is a leaf step. */
@@ -234,6 +277,47 @@ declare function createInitialState(options: CreateInitialStateOptions): InProgr
  */
 declare function executeWorkflow(options: ExecuteWorkflowOptions): Promise<SucceededInstallationState | FailedInstallationState>;
 //#endregion
+//#region source/management/installation/workflow/validation.d.ts
+/** Validation result for a single step, mirroring the step hierarchy. */
+type StepValidationResult = {
+  /** Step name (unique among siblings). */name: string; /** Full path from root to this step. */
+  path: string[]; /** Step metadata (for display purposes). */
+  meta: StepMeta; /** Issues found for this specific step (not including children). */
+  issues: ValidationIssue[]; /** Validation results for child steps (empty for leaf steps). */
+  children: StepValidationResult[];
+};
+/** Aggregated summary counts across the entire validation tree. */
+type ValidationSummary = {
+  /** Total number of issues across all steps. */totalIssues: number; /** Number of error-severity issues (these block installation). */
+  errors: number; /** Number of warning-severity issues (allow proceeding with confirmation). */
+  warnings: number;
+};
+/** The complete validation result returned by the validation endpoint. */
+type ValidationResult = {
+  /**
+   * Whether installation can proceed without any confirmation.
+   * False if there are any error or warning severity issues.
+   */
+  valid: boolean; /** The full validation tree mirroring the step structure. */
+  result: StepValidationResult; /** Flat summary of issue counts for quick frontend decisions. */
+  summary: ValidationSummary;
+};
+/** Options for running validation over the step tree. */
+type ValidateStepTreeOptions = {
+  /** The root branch step to validate. */rootStep: BranchStep; /** Validation context (params, logger, appData). */
+  validationContext: ValidationContext; /** The app configuration used to determine applicable steps. */
+  config: CommerceAppConfigOutputModel;
+};
+/**
+ * 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
+ */
+declare function validateStepTree(options: ValidateStepTreeOptions): Promise<ValidationResult>;
+//#endregion
 //#region source/management/installation/custom-installation/define.d.ts
 /**
  * Handler function type for custom installation steps.
@@ -295,5 +379,19 @@ declare function createInitialInstallationState(options: CreateInitialInstallati
  * Runs the full installation workflow. Returns the final state (never throws).
  */
 declare function runInstallation(options: RunInstallationOptions): Promise<SucceededInstallationState | FailedInstallationState>;
+/** Options for running pre-installation validation. */
+type RunValidationOptions = {
+  /** Validation context (params, logger, appData — no customScripts). */validationContext: ValidationContext; /** The app configuration. */
+  config: CommerceAppConfigOutputModel;
+};
+/**
+ * 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.
+ */
+declare function runValidation(options: RunValidationOptions): Promise<ValidationResult>;
 //#endregion
-export { BranchStep as A, defineBranchStep as B, StepStatus as C, isInProgressState as D, isFailedState as E, LeafStep as F, isBranchStep as H, LeafStepOptions as I, Step as L, ExecutionContext as M, InferStepOutput as N, isSucceededState as O, InstallationContext as P, StepContextFactory as R, InstallationStatus as S, isCompletedState as T, isLeafStep as U, defineLeafStep as V, FailedInstallationState as _, CustomInstallationStepHandler as a, InstallationError as b, ExecuteWorkflowOptions as c, InstallationHooks as d, StepEvent as f, ExecutionStatus as g, StepSucceededEvent as h, runInstallation as i, BranchStepOptions as j, AnyStep as k, createInitialState as l, StepStartedEvent as m, RunInstallationOptions as n, defineCustomInstallationStep as o, StepFailedEvent as p, createInitialInstallationState as r, CreateInitialStateOptions as s, CreateInitialInstallationStateOptions as t, executeWorkflow as u, InProgressInstallationState as v, SucceededInstallationState as w, InstallationState as x, InstallationData as y, StepMeta as z };
+export { isBranchStep as $, StepStatus as A, InferStepOutput as B, ExecutionStatus as C, InstallationError as D, InstallationData as E, isSucceededState as F, StepContextFactory as G, LeafStep as H, AnyStep as I, ValidationExecutionContext as J, StepMeta as K, BranchStep as L, isCompletedState as M, isFailedState as N, InstallationState as O, isInProgressState as P, defineLeafStep as Q, BranchStepOptions as R, StepSucceededEvent as S, InProgressInstallationState as T, LeafStepOptions as U, InstallationContext as V, Step as W, ValidationIssueSeverity as X, ValidationIssue as Y, defineBranchStep as Z, executeWorkflow as _, runInstallation as a, StepFailedEvent as b, defineCustomInstallationStep as c, ValidationResult as d, isLeafStep as et, ValidationSummary as f, createInitialState as g, ExecuteWorkflowOptions as h, createInitialInstallationState as i, SucceededInstallationState as j, InstallationStatus as k, StepValidationResult as l, CreateInitialStateOptions as m, RunInstallationOptions as n, runValidation as o, validateStepTree as p, ValidationContext as q, RunValidationOptions as r, CustomInstallationStepHandler as s, CreateInitialInstallationStateOptions as t, ValidateStepTreeOptions as u, InstallationHooks as v, FailedInstallationState as w, StepStartedEvent as x, StepEvent as y, ExecutionContext as z };

package/dist/es/logging-XIUXDK5T.mjs

@@ -0,0 +1,32 @@
+/**
+ * @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 util from "util";
+
+//#region ../../packages-private/common-utils/source/logging.ts
+/**
+* Shorthand to inspect an object.
+*
+* @param obj - The object to inspect.
+* @returns A string representation of the object.
+*/
+function inspect(obj, params = {}) {
+	return util.inspect(obj, {
+		depth: null,
+		...params
+	});
+}
+
+//#endregion
+export { inspect as t };

package/dist/es/management/index.d.mts

@@ -1,2 +1,16 @@
-import { A as BranchStep, B as defineBranchStep, C as StepStatus, D as isInProgressState, E as isFailedState, F as LeafStep, H as isBranchStep, I as LeafStepOptions, L as Step, M as ExecutionContext, N as InferStepOutput, O as isSucceededState, P as InstallationContext, R as StepContextFactory, S as InstallationStatus, T as isCompletedState, U as isLeafStep, V as defineLeafStep, _ as FailedInstallationState, a as CustomInstallationStepHandler, b as InstallationError, c as ExecuteWorkflowOptions, d as InstallationHooks, f as StepEvent, g as ExecutionStatus, h as StepSucceededEvent, i as runInstallation, j as BranchStepOptions, k as AnyStep, l as createInitialState, m as StepStartedEvent, n as RunInstallationOptions, o as defineCustomInstallationStep, p as StepFailedEvent, r as createInitialInstallationState, s as CreateInitialStateOptions, t as CreateInitialInstallationStateOptions, u as executeWorkflow, v as InProgressInstallationState, w as SucceededInstallationState, x as InstallationState, y as InstallationData, z as StepMeta } from "../runner-BD-lItnK.mjs";
-export { AnyStep, BranchStep, BranchStepOptions, type CreateInitialInstallationStateOptions, CreateInitialStateOptions, type CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, type RunInstallationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepStartedEvent, StepStatus, StepSucceededEvent, SucceededInstallationState, createInitialInstallationState, createInitialState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation };
+/**
+ * @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 { $ as isBranchStep, A as StepStatus, B as InferStepOutput, C as ExecutionStatus, D as InstallationError, E as InstallationData, F as isSucceededState, G as StepContextFactory, H as LeafStep, I as AnyStep, J as ValidationExecutionContext, K as StepMeta, L as BranchStep, M as isCompletedState, N as isFailedState, O as InstallationState, P as isInProgressState, Q as defineLeafStep, R as BranchStepOptions, S as StepSucceededEvent, T as InProgressInstallationState, U as LeafStepOptions, V as InstallationContext, W as Step, X as ValidationIssueSeverity, Y as ValidationIssue, Z as defineBranchStep, _ as executeWorkflow, a as runInstallation, b as StepFailedEvent, c as defineCustomInstallationStep, d as ValidationResult, et as isLeafStep, f as ValidationSummary, g as createInitialState, h as ExecuteWorkflowOptions, i as createInitialInstallationState, j as SucceededInstallationState, k as InstallationStatus, l as StepValidationResult, m as CreateInitialStateOptions, n as RunInstallationOptions, o as runValidation, p as validateStepTree, q as ValidationContext, r as RunValidationOptions, s as CustomInstallationStepHandler, t as CreateInitialInstallationStateOptions, u as ValidateStepTreeOptions, v as InstallationHooks, w as FailedInstallationState, x as StepStartedEvent, y as StepEvent, z as ExecutionContext } from "../index-D33OCH0D.mjs";
+export { AnyStep, BranchStep, BranchStepOptions, CreateInitialInstallationStateOptions, CreateInitialStateOptions, CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, RunInstallationOptions, RunValidationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepStartedEvent, StepStatus, StepSucceededEvent, StepValidationResult, SucceededInstallationState, ValidateStepTreeOptions, ValidationContext, ValidationExecutionContext, ValidationIssue, ValidationIssueSeverity, ValidationResult, ValidationSummary, createInitialInstallationState, createInitialState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation, runValidation, validateStepTree };

package/dist/es/management/index.mjs

@@ -1,3 +1,17 @@
-import { a as isFailedState, i as isCompletedState, n as runInstallation, o as isInProgressState, r as defineCustomInstallationStep, s as isSucceededState, t as createInitialInstallationState } from "../runner-vwAhjD5r.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.
+ */
 
-export { createInitialInstallationState, defineCustomInstallationStep, isCompletedState, isFailedState, isInProgressState, isSucceededState, runInstallation };
+import { a as isCompletedState, c as isSucceededState, i as defineCustomInstallationStep, n as runInstallation, o as isFailedState, r as runValidation, s as isInProgressState, t as createInitialInstallationState } from "../management-CIoVWirU.mjs";
+
+export { createInitialInstallationState, defineCustomInstallationStep, isCompletedState, isFailedState, isInProgressState, isSucceededState, runInstallation, runValidation };