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

package/dist/cjs/index-C5SutkJQ.d.cts

@@ -0,0 +1,345 @@
+import { n as CommerceAppConfigOutputModel } from "./app-Dx0ca6oL.cjs";
+import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
+import * as v from "valibot";
+import AioLogger from "@adobe/aio-lib-core-logging";
+
+//#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
+/** 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;
+/** Metadata for a step (used for UI display). */
+type StepMeta = {
+  label: string;
+  description?: string;
+};
+/** 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. */
+  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$1 = unknown> = StepBase<TName, TConfig> & {
+  type: "leaf";
+  /** The execution handler for the step. */
+  run: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput$1 | Promise<TOutput$1>;
+};
+/** 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[];
+};
+/** 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$1 = unknown> = LeafStep<TName, TConfig, TStepCtx, TOutput$1> | BranchStep<TName, TConfig, TStepCtx>;
+/** Loosely-typed step for use in non type-safe contexts. */
+interface AnyStep {
+  type: "leaf" | "branch";
+  name: string;
+  meta: StepMeta;
+  when?: (config: CommerceAppConfigOutputModel) => boolean;
+  children?: AnyStep[];
+  context?: (context: InstallationContext) => any;
+  run?: (config: any, context: any) => unknown | Promise<unknown>;
+}
+/** 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$1 = unknown> = Omit<LeafStep<TName, TConfig, TStepCtx, TOutput$1>, "type">;
+/** Options for defining a branch step. */
+type BranchStepOptions<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>> = Omit<BranchStep<TName, TConfig, TStepCtx>, "type">;
+/**
+ * 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);
+ *   },
+ * });
+ * ```
+ */
+declare function defineLeafStep<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput$1 = unknown>(options: LeafStepOptions<TName, TConfig, TStepCtx, TOutput$1>): LeafStep<TName, TConfig, TStepCtx, TOutput$1>;
+/**
+ * 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],
+ * });
+ * ```
+ */
+declare function defineBranchStep<TName extends string, TConfig extends CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>>(options: BranchStepOptions<TName, TConfig, TStepCtx>): BranchStep<TName, TConfig, TStepCtx>;
+/** 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
+//#region source/management/installation/workflow/types.d.ts
+/** Status of a step execution. */
+type ExecutionStatus = "pending" | "in-progress" | "succeeded" | "failed";
+/** Overall installation status. */
+type InstallationStatus = "pending" | "in-progress" | "succeeded" | "failed";
+/** A structured error with path to the failing step. */
+type InstallationError<TPayload = unknown> = {
+  /** Path to the step that failed (e.g., ["eventing", "commerce", "providers"]). */
+  path: string[];
+  /** Error key for easy identification. */
+  key: string;
+  /** Human-readable error message. */
+  message?: string;
+  /** Additional error payload. */
+  payload?: TPayload;
+};
+/** Status of a step in the installation tree. */
+type StepStatus = {
+  /** Step name (unique among siblings). */
+  name: string;
+  /** Unique step identifier (e.g., UUID). */
+  id: string;
+  /** Full path from root to this step. */
+  path: string[];
+  /** Step metadata (for display purposes). */
+  meta: StepMeta;
+  /** Current execution status. */
+  status: ExecutionStatus;
+  /** Child step statuses (empty for leaf steps). */
+  children: StepStatus[];
+};
+/** Data collected during installation as a nested structure following step paths. */
+type InstallationData = {
+  [key: string]: unknown | InstallationData;
+};
+/** Base properties shared by all installation states. */
+type InstallationStateBase = {
+  /** Unique installation identifier. */
+  id: string;
+  /** Root step status. */
+  step: StepStatus;
+  /** Results from executed leaf steps, keyed by path. */
+  data: InstallationData | null;
+};
+/** Installation state when in progress. */
+type InProgressInstallationState = InstallationStateBase & {
+  status: "in-progress";
+  /** ISO timestamp when installation started. */
+  startedAt: string;
+};
+/** Installation state when completed successfully. */
+type SucceededInstallationState = InstallationStateBase & {
+  status: "succeeded";
+  /** ISO timestamp when installation started. */
+  startedAt: string;
+  /** ISO timestamp when installation completed. */
+  completedAt: string;
+};
+/** Installation state when failed. */
+type FailedInstallationState = InstallationStateBase & {
+  status: "failed";
+  /** ISO timestamp when installation started. */
+  startedAt: string;
+  /** ISO timestamp when installation failed. */
+  completedAt: string;
+  /** Error information about the failure. */
+  error: InstallationError;
+};
+/**
+ * The full installation state (persisted and returned by status endpoints).
+ * Discriminated union by `status` field.
+ */
+type InstallationState = InProgressInstallationState | SucceededInstallationState | FailedInstallationState;
+/** Type guard for pending installation state. */
+/** Type guard for in-progress installation state. */
+declare function isInProgressState(state: InstallationState): state is InProgressInstallationState;
+/** Type guard for succeeded installation state. */
+declare function isSucceededState(state: InstallationState): state is SucceededInstallationState;
+/** Type guard for failed installation state. */
+declare function isFailedState(state: InstallationState): state is FailedInstallationState;
+/** Type guard for completed installation state (succeeded or failed). */
+declare function isCompletedState(state: InstallationState): state is SucceededInstallationState | FailedInstallationState;
+//#endregion
+//#region source/management/installation/workflow/hooks.d.ts
+/** Hook function that receives an event and the current state. */
+type HookFunction<TEvent> = (event: TEvent, state: InstallationState) => void | Promise<void>;
+/** Hook function that only receives the current state. */
+type InstallationHook = (state: InstallationState) => void | Promise<void>;
+/** Base event payload for step events. */
+type StepEvent = {
+  /** Full path to the step (e.g., ["eventing", "commerce", "providers"]). */
+  path: string[];
+  /** Step name (last element of path, for convenience). */
+  stepName: string;
+  /** Whether this is a leaf step (executable) or branch step (container). */
+  isLeaf: boolean;
+};
+/** Event payload when a step starts execution. */
+type StepStartedEvent = StepEvent;
+/** Event payload when a step succeeds. */
+type StepSucceededEvent = StepEvent & {
+  /** Result returned by the step (only for leaf steps). */
+  result: unknown;
+};
+/** Event payload when a step fails. */
+type StepFailedEvent = StepEvent & {
+  /** Error information. */
+  error: InstallationError;
+};
+/** Lifecycle hooks for installation execution. */
+type InstallationHooks = {
+  onInstallationStart?: InstallationHook;
+  onInstallationSuccess?: InstallationHook;
+  onInstallationFailure?: InstallationHook;
+  onStepStart?: HookFunction<StepStartedEvent>;
+  onStepSuccess?: HookFunction<StepSucceededEvent>;
+  onStepFailure?: HookFunction<StepFailedEvent>;
+};
+//#endregion
+//#region source/management/installation/workflow/runner.d.ts
+/** Options for creating an initial installation state. */
+type CreateInitialStateOptions = {
+  /** The root branch step to build the state from. */
+  rootStep: BranchStep;
+  /** The app configuration used to determine applicable steps. */
+  config: CommerceAppConfigOutputModel;
+};
+/** Options for executing a workflow. */
+type ExecuteWorkflowOptions = {
+  /** The root branch step to execute. */
+  rootStep: BranchStep;
+  /** Shared installation context (params, logger, etc.). */
+  installationContext: InstallationContext;
+  /** The app configuration. */
+  config: CommerceAppConfigOutputModel;
+  /** The initial installation state (with all steps pending). */
+  initialState: InProgressInstallationState;
+  /** Lifecycle hooks for status change notifications. */
+  hooks?: InstallationHooks;
+};
+/**
+ * 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".
+ */
+declare function createInitialState(options: CreateInitialStateOptions): InProgressInstallationState;
+/**
+ * Executes a workflow from an initial state. Returns the final state (never throws).
+ */
+declare function executeWorkflow(options: ExecuteWorkflowOptions): Promise<SucceededInstallationState | FailedInstallationState>;
+//#endregion
+//#region source/management/installation/custom-installation/define.d.ts
+/**
+ * Handler function type for custom installation steps.
+ *
+ * @param config - The validated commerce app configuration
+ * @param context - Execution context with logger, params, and other utilities
+ * @returns The result of the installation step (can be any value or Promise)
+ */
+type CustomInstallationStepHandler<TResult = unknown> = (config: CommerceAppConfigOutputModel, context: ExecutionContext) => TResult | Promise<TResult>;
+/**
+ * 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",
+ *   };
+ * });
+ * ```
+ */
+declare function defineCustomInstallationStep<TResult = unknown>(handler: CustomInstallationStepHandler<TResult>): CustomInstallationStepHandler<TResult>;
+//#endregion
+//#region source/management/installation/runner.d.ts
+/** Options for creating an initial installation state. */
+type CreateInitialInstallationStateOptions = {
+  /** The app configuration used to determine applicable steps. */
+  config: CommerceAppConfigOutputModel;
+};
+/** Options for running an installation. */
+type RunInstallationOptions = {
+  /** Shared installation context (params, logger, etc.). */
+  installationContext: InstallationContext;
+  /** The app configuration. */
+  config: CommerceAppConfigOutputModel;
+  /** The initial installation state (with all steps pending). */
+  initialState: InProgressInstallationState;
+  /** Lifecycle hooks for status change notifications. */
+  hooks?: InstallationHooks;
+};
+/**
+ * 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".
+ */
+declare function createInitialInstallationState(options: CreateInitialInstallationStateOptions): InProgressInstallationState;
+/**
+ * Runs the full installation workflow. Returns the final state (never throws).
+ */
+declare function runInstallation(options: RunInstallationOptions): Promise<SucceededInstallationState | FailedInstallationState>;
+//#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 };

package/dist/cjs/logging-DYwr5WQk.cjs

@@ -0,0 +1,25 @@
+const require_error = require('./error-Byj1DVHZ.cjs');
+let util = require("util");
+util = require_error.__toESM(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.default.inspect(obj, {
+		depth: null,
+		...params
+	});
+}
+
+//#endregion
+Object.defineProperty(exports, 'inspect', {
+  enumerable: true,
+  get: function () {
+    return inspect;
+  }
+});

package/dist/cjs/management/index.cjs

@@ -0,0 +1,9 @@
+const require_management = require('../management-Dm5h0E6l.cjs');
+
+exports.createInitialInstallationState = require_management.createInitialInstallationState;
+exports.defineCustomInstallationStep = require_management.defineCustomInstallationStep;
+exports.isCompletedState = require_management.isCompletedState;
+exports.isFailedState = require_management.isFailedState;
+exports.isInProgressState = require_management.isInProgressState;
+exports.isSucceededState = require_management.isSucceededState;
+exports.runInstallation = require_management.runInstallation;

package/dist/cjs/management/index.d.cts

@@ -0,0 +1,2 @@
+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 "../index-C5SutkJQ.cjs";
+export { AnyStep, BranchStep, BranchStepOptions, CreateInitialInstallationStateOptions, CreateInitialStateOptions, CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, RunInstallationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepStartedEvent, StepStatus, StepSucceededEvent, SucceededInstallationState, createInitialInstallationState, createInitialState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation };