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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/dist/cjs/actions/app-config.cjs +3 -3
  3. package/dist/cjs/actions/app-config.d.cts +1 -1
  4. package/dist/cjs/actions/config.cjs +31 -9
  5. package/dist/cjs/actions/installation.cjs +16 -13
  6. package/dist/cjs/actions/installation.d.cts +2 -2
  7. package/dist/cjs/actions/registration.cjs +41 -0
  8. package/dist/cjs/actions/registration.d.cts +33 -0
  9. package/dist/cjs/actions/scope-tree.cjs +5 -4
  10. package/dist/cjs/admin-ui-sdk-BiSopnKI.d.cts +665 -0
  11. package/dist/cjs/{app-DcQMhW2N.d.cts → app-C6kImBl7.d.cts} +242 -16
  12. package/dist/cjs/chunk-DS2yp5vX.cjs +48 -0
  13. package/dist/cjs/commands/index.cjs +582 -319
  14. package/dist/cjs/commands/templates/admin-ui-sdk/registration.js.template +20 -0
  15. package/dist/cjs/config/index.cjs +4 -3
  16. package/dist/cjs/config/index.d.cts +558 -62
  17. package/dist/cjs/{config-BppBKCFj.cjs → config-ct-qMOGj.cjs} +56 -25
  18. package/dist/cjs/{error-Dn7ool6k.cjs → error-C5LNOZ4f.cjs} +1 -1
  19. package/dist/cjs/{index-BVwQk9bx.d.cts → index-B5WKJ3hJ.d.cts} +20 -174
  20. package/dist/cjs/{logging-4s36JTiN.cjs → logging-BTevALnL.cjs} +2 -2
  21. package/dist/cjs/management/index.cjs +1 -1
  22. package/dist/cjs/management/index.d.cts +3 -2
  23. package/dist/cjs/{management-C6xG5bfl.cjs → management-D1QXg4YU.cjs} +128 -75
  24. package/dist/cjs/{router-KeQRduO3.cjs → router-CFErodHU.cjs} +2 -2
  25. package/dist/cjs/{schemas-nkIxa8sL.cjs → schemas-CukVpc19.cjs} +2 -34
  26. package/dist/cjs/step-CWYnKbga.d.cts +187 -0
  27. package/dist/cjs/{validate-CeUCT_7k.cjs → validate-b_bI4mDb.cjs} +4 -3
  28. package/dist/cjs/{webhooks-CLtDxwMa.cjs → webhooks-DS1BtgED.cjs} +157 -17
  29. package/dist/es/actions/app-config.d.mts +1 -1
  30. package/dist/es/actions/app-config.mjs +1 -1
  31. package/dist/es/actions/config.mjs +28 -7
  32. package/dist/es/actions/installation.d.mts +2 -2
  33. package/dist/es/actions/installation.mjs +12 -10
  34. package/dist/es/actions/registration.d.mts +33 -0
  35. package/dist/es/actions/registration.mjs +39 -0
  36. package/dist/es/actions/scope-tree.mjs +1 -1
  37. package/dist/es/admin-ui-sdk-CCo2SWiL.d.mts +667 -0
  38. package/dist/es/{app-DJr-mN9d.d.mts → app-DcY6dJiQ.d.mts} +242 -16
  39. package/dist/es/commands/index.mjs +575 -314
  40. package/dist/es/commands/templates/admin-ui-sdk/registration.js.template +20 -0
  41. package/dist/es/config/index.d.mts +558 -62
  42. package/dist/es/config/index.mjs +4 -4
  43. package/dist/es/{config-BohwKkQS.mjs → config-DGPFTk6w.mjs} +51 -20
  44. package/dist/es/{index-BENO5T7n.d.mts → index-CCov0odd.d.mts} +20 -174
  45. package/dist/es/management/index.d.mts +3 -2
  46. package/dist/es/management/index.mjs +1 -1
  47. package/dist/es/{management-ByHvVJ12.mjs → management-CCsOfniv.mjs} +124 -71
  48. package/dist/es/step-0eI2x4C9.d.mts +187 -0
  49. package/dist/es/{validate-CqJdGzyZ.mjs → validate-Dn3lLTGj.mjs} +2 -2
  50. package/dist/es/{webhooks-CYo-pqbR.mjs → webhooks-Dhrkkip7.mjs} +155 -16
  51. package/package.json +12 -9
  52. /package/dist/cjs/commands/{generate/actions/templates → templates}/app-management/app-config.js.template +0 -0
  53. /package/dist/cjs/commands/{generate/actions/templates → templates}/app-management/custom-scripts.js.template +0 -0
  54. /package/dist/cjs/commands/{generate/actions/templates → templates}/app-management/installation.js.template +0 -0
  55. /package/dist/cjs/commands/{generate/actions/templates → templates}/business-configuration/config.js.template +0 -0
  56. /package/dist/cjs/commands/{generate/actions/templates → templates}/business-configuration/scope-tree.js.template +0 -0
  57. /package/dist/es/commands/{generate/actions/templates → templates}/app-management/app-config.js.template +0 -0
  58. /package/dist/es/commands/{generate/actions/templates → templates}/app-management/custom-scripts.js.template +0 -0
  59. /package/dist/es/commands/{generate/actions/templates → templates}/app-management/installation.js.template +0 -0
  60. /package/dist/es/commands/{generate/actions/templates → templates}/business-configuration/config.js.template +0 -0
  61. /package/dist/es/commands/{generate/actions/templates → templates}/business-configuration/scope-tree.js.template +0 -0
  62. /package/dist/es/{schemas-CVXHgUhv.mjs → schemas-DOcnD16x.mjs} +0 -0
@@ -12,8 +12,8 @@
12
12
  * governing permissions and limitations under the License.
13
13
  */
14
14
 
15
- import { a as hasCustomInstallationSteps, c as hasEventing, i as hasCustomInstallation, l as hasExternalEvents, n as hasWebhooks, s as hasCommerceEvents } from "../webhooks-CYo-pqbR.mjs";
16
- 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-CqJdGzyZ.mjs";
17
- import { d as defineConfig, n as readCommerceAppConfig, r as resolveCommerceAppConfig, t as parseCommerceAppConfig } from "../config-BohwKkQS.mjs";
15
+ import { a as hasCustomInstallationSteps, c as hasEventing, d as hasAdminUiSdk, i as hasCustomInstallation, l as hasExternalEvents, n as hasWebhooks, s as hasCommerceEvents } from "../webhooks-Dhrkkip7.mjs";
16
+ 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-Dn3lLTGj.mjs";
17
+ import { d as defineConfig, n as readCommerceAppConfig, r as resolveCommerceAppConfig, t as parseCommerceAppConfig } from "../config-DGPFTk6w.mjs";
18
18
 
19
- export { CommerceAppConfigSchemas, defineConfig, getConfigDomains, hasBusinessConfig, hasBusinessConfigSchema, hasCommerceEvents, hasConfigDomain, hasCustomInstallation, hasCustomInstallationSteps, hasEventing, hasExternalEvents, hasMetadata, hasWebhooks, parseCommerceAppConfig, readCommerceAppConfig, resolveCommerceAppConfig, validateCommerceAppConfig, validateCommerceAppConfigDomain };
19
+ export { CommerceAppConfigSchemas, defineConfig, getConfigDomains, hasAdminUiSdk, hasBusinessConfig, hasBusinessConfigSchema, hasCommerceEvents, hasConfigDomain, hasCustomInstallation, hasCustomInstallationSteps, hasEventing, hasExternalEvents, hasMetadata, hasWebhooks, parseCommerceAppConfig, readCommerceAppConfig, resolveCommerceAppConfig, validateCommerceAppConfig, validateCommerceAppConfigDomain };
@@ -12,11 +12,13 @@
12
12
  * governing permissions and limitations under the License.
13
13
  */
14
14
 
15
- import { t as validateCommerceAppConfig } from "./validate-CqJdGzyZ.mjs";
15
+ import { t as validateCommerceAppConfig } from "./validate-Dn3lLTGj.mjs";
16
16
  import { t as stringifyError } from "./error-DHlYzkbb.mjs";
17
17
  import { dirname, join, parse } from "path";
18
18
  import { existsSync } from "fs";
19
19
  import { access, mkdir, readFile } from "fs/promises";
20
+ import { resolveCommand } from "package-manager-detector";
21
+ import { detect, getUserAgent } from "package-manager-detector/detect";
20
22
  import { createJiti } from "jiti";
21
23
 
22
24
  //#region source/config/lib/define.ts
@@ -113,27 +115,56 @@ async function makeOutputDirFor(fileOrFolder) {
113
115
  if (!existsSync(outputDir)) await mkdir(outputDir, { recursive: true });
114
116
  return outputDir;
115
117
  }
116
- /** Detect the package manager by checking for lock files */
118
+ const VALID_PACKAGE_MANAGERS = [
119
+ "npm",
120
+ "pnpm",
121
+ "yarn",
122
+ "bun"
123
+ ];
124
+ /**
125
+ * Type guard asserting that a value is a supported `PackageManager`.
126
+ * @param value - The value to check
127
+ */
128
+ function isValidPackageManager(value) {
129
+ return value !== void 0 && VALID_PACKAGE_MANAGERS.includes(value);
130
+ }
131
+ /**
132
+ * Detect the package manager for a project.
133
+ * @param cwd - Directory to start detection from; defaults to `process.cwd()`
134
+ */
117
135
  async function detectPackageManager(cwd = process.cwd()) {
118
- const rootDirectory = await getProjectRootDirectory(cwd);
119
- const lockFileMap = {
120
- "bun.lockb": "bun",
121
- "pnpm-lock.yaml": "pnpm",
122
- "yarn.lock": "yarn",
123
- "package-lock.json": "npm"
124
- };
125
- const lockFileName = Object.keys(lockFileMap).find((name) => existsSync(join(rootDirectory, name)));
126
- if (!lockFileName) return "npm";
127
- return lockFileMap[lockFileName];
136
+ const result = await detect({ cwd: await getProjectRootDirectory(cwd) });
137
+ if (isValidPackageManager(result?.name)) return result.name;
138
+ const fromUserAgent = getUserAgent() ?? void 0;
139
+ if (isValidPackageManager(fromUserAgent)) return fromUserAgent;
140
+ return "npm";
128
141
  }
129
- /** Get the appropriate exec command based on package manager */
142
+ /**
143
+ * Get the exec command that runs a **locally installed** binary from
144
+ * `node_modules/.bin` for the given package manager.
145
+ * @param packageManager - The detected package manager
146
+ */
130
147
  function getExecCommand(packageManager) {
148
+ const resolved = resolveCommand(packageManager, "execute-local", []);
149
+ if (!resolved) return "npx";
150
+ return [resolved.command, ...resolved.args].filter(Boolean).join(" ");
151
+ }
152
+ /**
153
+ * Get the command to install the given dependencies with the given package
154
+ * manager (e.g. `pnpm add foo bar`, `npm i foo bar`).
155
+ * @param packageManager - The detected package manager
156
+ * @param packages - Package specifiers to install (e.g. `["foo@^1.0"]`)
157
+ */
158
+ function getInstallCommand(packageManager, packages) {
159
+ const resolved = resolveCommand(packageManager, "add", packages);
160
+ if (!resolved) return {
161
+ command: "npm",
162
+ args: ["install", ...packages]
163
+ };
131
164
  return {
132
- pnpm: "pnpx",
133
- yarn: "yarn dlx",
134
- bun: "bunx",
135
- npm: "npx"
136
- }[packageManager];
165
+ args: resolved.args.filter((a) => Boolean(a)),
166
+ command: resolved.command
167
+ };
137
168
  }
138
169
 
139
170
  //#endregion
@@ -194,7 +225,7 @@ async function readCommerceAppConfig(cwd = process.cwd()) {
194
225
  const message = stringifyError(error);
195
226
  throw new Error(`Failed to read commerce app config file at ${configFilePath}: ${message}`, { cause: error });
196
227
  }
197
- if (!(config && "default" in config) || config.default === void 0 || config.default === null || typeof config.default === "object" && Object.keys(config.default).length === 0) throw new Error("Commerce app config file does not export a default export. Make sure you use `export default` or `module.exports = { /* your config */ }`");
228
+ if (!(config && "default" in config) || config.default === void 0 || config.default === null || typeof config.default === "object" && Object.keys(config.default).length === 0) throw new Error("Commerce app config file does not export a default export or exports an empty object. Make sure you use `export default` or `module.exports = { /* your config */ }`");
198
229
  return config.default;
199
230
  }
200
231
  /**
@@ -212,4 +243,4 @@ async function parseCommerceAppConfig(cwd = process.cwd()) {
212
243
  }
213
244
 
214
245
  //#endregion
215
- export { findNearestPackageJson as a, isESM as c, defineConfig as d, detectPackageManager as i, makeOutputDirFor as l, readCommerceAppConfig as n, getExecCommand as o, resolveCommerceAppConfig as r, getProjectRootDirectory as s, parseCommerceAppConfig as t, readPackageJson as u };
246
+ export { getExecCommand as a, isESM as c, defineConfig as d, detectPackageManager as i, makeOutputDirFor as l, readCommerceAppConfig as n, getInstallCommand as o, resolveCommerceAppConfig as r, getProjectRootDirectory as s, parseCommerceAppConfig as t, readPackageJson as u };
@@ -12,178 +12,9 @@
12
12
  * governing permissions and limitations under the License.
13
13
  */
14
14
 
15
- import { n as CommerceAppConfigOutputModel } from "./app-DJr-mN9d.mjs";
16
- import AioLogger from "@adobe/aio-lib-core-logging";
17
- import * as v from "valibot";
18
- import { RuntimeActionParams } from "@adobe/aio-commerce-lib-core/params";
15
+ import { n as CommerceAppConfigOutputModel } from "./app-DcY6dJiQ.mjs";
16
+ import { f as StepMetaInfo, h as ValidationIssue, i as ExecutionContext, n as BranchStep, o as InstallationContext, p as ValidationContext } from "./step-0eI2x4C9.mjs";
19
17
 
20
- //#region source/management/installation/schema.d.ts
21
- /** Schema for validating Adobe I/O app credentials required for installation. */
22
- declare const AppDataSchema: v.ObjectSchema<{
23
- readonly consumerOrgId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
24
- readonly orgName: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
25
- readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
26
- readonly projectName: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
27
- readonly projectTitle: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
28
- readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
29
- readonly workspaceName: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
30
- readonly workspaceTitle: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
31
- }, undefined>;
32
- /** Type for Adobe I/O app credentials. */
33
- type AppData = v.InferOutput<typeof AppDataSchema>;
34
- //#endregion
35
- //#region source/management/installation/workflow/step.d.ts
36
- /** Severity level of a validation issue. */
37
- type ValidationIssueSeverity = "error" | "warning" | "info";
38
- /** A single validation issue reported by a step's validate handler. */
39
- type ValidationIssue = {
40
- /** Machine-readable code identifying the issue type. */code: string; /** Human-readable description of the issue. */
41
- message: string; /** Severity of the issue. Only "error" severity blocks installation. */
42
- severity: ValidationIssueSeverity; /** Optional additional context about the issue. */
43
- details?: Record<string, unknown>;
44
- };
45
- /** Shared context available to all steps during installation. */
46
- type InstallationContext = {
47
- /** The credentials of the app being installed */appData: AppData; /** The raw action parameters from the App Builder runtime action. */
48
- params: RuntimeActionParams & {
49
- AIO_COMMERCE_AUTH_IMS_CLIENT_ID: string;
50
- AIO_COMMERCE_AUTH_IMS_CLIENT_SECRETS: string | string[];
51
- AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_ID: string;
52
- AIO_COMMERCE_AUTH_IMS_TECHNICAL_ACCOUNT_EMAIL: string;
53
- AIO_COMMERCE_AUTH_IMS_ORG_ID: string;
54
- AIO_COMMERCE_AUTH_IMS_SCOPES: string | string[];
55
- }; /** Logger instance for installation logging. */
56
- logger: ReturnType<typeof AioLogger>; /** Custom scripts defined in the configuration (if any). */
57
- customScripts?: Record<string, unknown>;
58
- };
59
- /** Factory function type for creating step-specific context. */
60
- type StepContextFactory<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = (context: InstallationContext) => TStepCtx | Promise<TStepCtx>;
61
- /** The execution context passed to leaf step run handlers. */
62
- type ExecutionContext<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = InstallationContext & TStepCtx;
63
- /**
64
- * A narrowed context available to step `validate` handlers.
65
- * Excludes `customScripts` — those only apply during installation, not pre-flight validation.
66
- */
67
- type ValidationContext = Omit<InstallationContext, "customScripts">;
68
- /** The context passed to step `validate` handlers (base validation context merged with step-level context). */
69
- type ValidationExecutionContext<TStepCtx extends Record<string, unknown> = Record<string, unknown>> = ValidationContext & TStepCtx;
70
- /** Metadata info for a step (used for UI display). */
71
- type StepMetaInfo = {
72
- label: string;
73
- description?: string;
74
- };
75
- /** Step metadata keyed by execution mode. */
76
- type StepMeta = {
77
- install: StepMetaInfo;
78
- uninstall?: StepMetaInfo;
79
- };
80
- /** Defines the base properties of a step. */
81
- type StepBase<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel> = {
82
- /** The name of this step. */name: TName; /** Metadata associated with the step, keyed by execution mode. */
83
- meta: StepMeta; /** Whether the step should be taken into consideration. */
84
- when?: (config: CommerceAppConfigOutputModel) => config is TConfig;
85
- };
86
- /** A leaf step that executes work (no children). */
87
- type LeafStep<TName extends string = string, TConfig extends CommerceAppConfigOutputModel = CommerceAppConfigOutputModel, TStepCtx extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown> = StepBase<TName, TConfig> & {
88
- type: "leaf"; /** The execution handler for the step. */
89
- install: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
90
- /**
91
- * Optional pre-installation validation handler.
92
- * Called before installation begins to surface issues (errors or warnings).
93
- * Returning an empty array means the step has no issues.
94
- */
95
- validate?: (config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>;
96
- /**
97
- * Optional uninstall handler for the step.
98
- * Called during uninstallation to reverse the work done by `install`.
99
- * If absent, the step is silently skipped during uninstallation.
100
- */
101
- uninstall?: (config: TConfig, context: ExecutionContext<TStepCtx>) => void | Promise<void>;
102
- };
103
- /** A branch step that contains children (no execution). */
104
- 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> & {
105
- type: "branch"; /** An optional factory function to setup shared context for the children steps. */
106
- context?: StepContextFactory<TStepCtx>; /** The children steps of this branch. */
107
- children: TChildren;
108
- /**
109
- * Optional pre-installation validation handler for the branch itself.
110
- * Called before children are validated. Returning an empty array means
111
- * the branch has no issues at this level.
112
- */
113
- validate?: (config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>;
114
- };
115
- /** A step in the installation tree (discriminated union by `type`). */
116
- 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>;
117
- /** Loosely-typed step for use in non type-safe contexts. */
118
- interface AnyStep {
119
- children?: AnyStep[];
120
- context?: (context: InstallationContext) => any;
121
- install?: (config: any, context: any) => unknown | Promise<unknown>;
122
- meta: StepMeta;
123
- name: string;
124
- type: "leaf" | "branch";
125
- uninstall?: (config: any, context: any) => void | Promise<void>;
126
- validate?: (config: any, context: any) => ValidationIssue[] | Promise<ValidationIssue[]>;
127
- when?: (config: CommerceAppConfigOutputModel) => boolean;
128
- }
129
- /** Check if a step is a leaf step. */
130
- declare function isLeafStep(step: AnyStep): step is LeafStep;
131
- /** Check if a step is a branch step. */
132
- declare function isBranchStep(step: AnyStep): step is BranchStep;
133
- /** Options for defining a leaf step. */
134
- 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">;
135
- /** Options for defining a branch step. */
136
- 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">;
137
- /**
138
- * Define a leaf step (executable, no children).
139
- *
140
- * @example
141
- * ```typescript
142
- * const createProviders = defineLeafStep({
143
- * name: "providers",
144
- * meta: { install: { label: "Create Providers", description: "Creates I/O Events providers" } },
145
- * install: async ({ config, stepContext }) => {
146
- * const { eventsClient } = stepContext;
147
- * return eventsClient.createProvider(config.eventing);
148
- * },
149
- * });
150
- * ```
151
- */
152
- 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>): {
153
- type: "leaf";
154
- name: TName;
155
- meta: StepMeta;
156
- when: ((config: CommerceAppConfigOutputModel) => config is TConfig) | undefined;
157
- install: (config: TConfig, context: ExecutionContext<TStepCtx>) => TOutput | Promise<TOutput>;
158
- uninstall: ((config: TConfig, context: ExecutionContext<TStepCtx>) => void | Promise<void>) | undefined;
159
- validate: ((config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>) | undefined;
160
- };
161
- /**
162
- * Define a branch step (container with children, no runner).
163
- *
164
- * @example
165
- * ```typescript
166
- * const eventing = defineBranchStep({
167
- * name: "eventing",
168
- * meta: { install: { label: "Eventing", description: "Sets up I/O Events" } },
169
- * when: hasEventing,
170
- * context: async (ctx) => ({ eventsClient: await createEventsClient(ctx) }),
171
- * children: [commerceEventsStep, externalEventsStep],
172
- * });
173
- * ```
174
- */
175
- 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>): {
176
- type: "branch";
177
- name: TName;
178
- meta: StepMeta;
179
- when: ((config: CommerceAppConfigOutputModel) => config is TConfig) | undefined;
180
- context: StepContextFactory<TStepCtx> | undefined;
181
- children: TChildren;
182
- validate: ((config: TConfig, context: ValidationExecutionContext<TStepCtx>) => ValidationIssue[] | Promise<ValidationIssue[]>) | undefined;
183
- };
184
- /** Infer the output type from a leaf step. */
185
- type InferStepOutput<TStep> = TStep extends LeafStep<infer _TName, infer _TConfig, infer _TStepCtx, infer TOutput> ? Awaited<TOutput> : never;
186
- //#endregion
187
18
  //#region source/management/installation/workflow/types.d.ts
188
19
  /** Status of a step execution. */
189
20
  type ExecutionStatus = "pending" | "in-progress" | "succeeded" | "failed";
@@ -220,18 +51,24 @@ type InProgressInstallationState = InstallationStateBase & {
220
51
  status: "in-progress"; /** ISO timestamp when installation started. */
221
52
  startedAt: string;
222
53
  };
54
+ /** Metadata set when a retry was attempted, regardless of outcome. */
55
+ type InstallationRetryMetadata = {
56
+ /** True when installation was attempted more than once. */isRetry: boolean;
57
+ };
223
58
  /** Installation state when completed successfully. */
224
59
  type SucceededInstallationState = InstallationStateBase & {
225
60
  status: "succeeded"; /** ISO timestamp when installation started. */
226
61
  startedAt: string; /** ISO timestamp when installation completed. */
227
- completedAt: string;
62
+ completedAt: string; /** Retry metadata, present when a retry was attempted. */
63
+ metadata?: InstallationRetryMetadata;
228
64
  };
229
65
  /** Installation state when failed. */
230
66
  type FailedInstallationState = InstallationStateBase & {
231
67
  status: "failed"; /** ISO timestamp when installation started. */
232
68
  startedAt: string; /** ISO timestamp when installation failed. */
233
69
  completedAt: string; /** Error information about the failure. */
234
- error: InstallationError;
70
+ error: InstallationError; /** Retry metadata, present when a retry was attempted. */
71
+ metadata?: InstallationRetryMetadata;
235
72
  };
236
73
  /**
237
74
  * The full installation state (persisted and returned by status endpoints).
@@ -303,6 +140,12 @@ type ExecutionMode = "install" | "uninstall";
303
140
  * tree structure with all steps set to "pending".
304
141
  */
305
142
  declare function createInitialState(options: CreateInitialStateOptions): InProgressInstallationState;
143
+ /**
144
+ * Creates a retry state from a failed state.
145
+ * Preserves succeeded steps and their data so the workflow resumes from
146
+ * the failed step rather than restarting from scratch.
147
+ */
148
+ declare function createRetryState(failedState: FailedInstallationState): InProgressInstallationState;
306
149
  /**
307
150
  * Executes a workflow from an initial state. Returns the final state (never throws).
308
151
  */
@@ -427,6 +270,9 @@ type RunInstallationOptions = {
427
270
  declare function createInitialInstallationState(options: CreateInitialInstallationStateOptions): InProgressInstallationState;
428
271
  /**
429
272
  * Runs the full installation workflow. Returns the final state (never throws).
273
+ *
274
+ * Retries once on failure. `onInstallationFailure` only fires if both attempts fail;
275
+ * `isRetry: true` is set on the result when the retry succeeds.
430
276
  */
431
277
  declare function runInstallation(options: RunInstallationOptions): Promise<SucceededInstallationState | FailedInstallationState>;
432
278
  /** Options for creating an initial uninstallation state. */
@@ -463,4 +309,4 @@ type RunValidationOptions = {
463
309
  */
464
310
  declare function runValidation(options: RunValidationOptions): Promise<ValidationResult>;
465
311
  //#endregion
466
- export { StepMetaInfo as $, FailedInstallationState as A, isInProgressState as B, executeWorkflow as C, StepStartedEvent as D, StepFailedEvent as E, InstallationStatus as F, ExecutionContext as G, AnyStep as H, StepStatus as I, LeafStep as J, InferStepOutput as K, SucceededInstallationState as L, InstallationData as M, InstallationError as N, StepSucceededEvent as O, InstallationState as P, StepMeta as Q, isCompletedState as R, executeUninstallWorkflow as S, StepEvent as T, BranchStep as U, isSucceededState as V, BranchStepOptions as W, Step as X, LeafStepOptions as Y, StepContextFactory as Z, ValidationSummary as _, RunValidationOptions as a, defineLeafStep as at, ExecuteWorkflowOptions as b, runInstallation as c, CustomInstallationStepDefinition as d, ValidationContext as et, CustomInstallationStepHandler as f, ValidationResult as g, ValidateStepTreeOptions as h, RunUninstallationOptions as i, defineBranchStep as it, InProgressInstallationState as j, ExecutionStatus as k, runUninstallation as l, StepValidationResult as m, CreateInitialUninstallationStateOptions as n, ValidationIssue as nt, createInitialInstallationState as o, isBranchStep as ot, defineCustomInstallationStep as p, InstallationContext as q, RunInstallationOptions as r, ValidationIssueSeverity as rt, createInitialUninstallationState as s, isLeafStep as st, CreateInitialInstallationStateOptions as t, ValidationExecutionContext as tt, runValidation as u, validateStepTree as v, InstallationHooks as w, createInitialState as x, CreateInitialStateOptions as y, isFailedState as z };
312
+ export { ExecutionStatus as A, isCompletedState as B, executeUninstallWorkflow as C, StepFailedEvent as D, StepEvent as E, InstallationRetryMetadata as F, isInProgressState as H, InstallationState as I, InstallationStatus as L, InProgressInstallationState as M, InstallationData as N, StepStartedEvent as O, InstallationError as P, StepStatus as R, createRetryState as S, InstallationHooks as T, isSucceededState as U, isFailedState as V, ValidationSummary as _, RunValidationOptions as a, ExecuteWorkflowOptions as b, runInstallation as c, CustomInstallationStepDefinition as d, CustomInstallationStepHandler as f, ValidationResult as g, ValidateStepTreeOptions as h, RunUninstallationOptions as i, FailedInstallationState as j, StepSucceededEvent as k, runUninstallation as l, StepValidationResult as m, CreateInitialUninstallationStateOptions as n, createInitialInstallationState as o, defineCustomInstallationStep as p, RunInstallationOptions as r, createInitialUninstallationState as s, CreateInitialInstallationStateOptions as t, runValidation as u, validateStepTree as v, executeWorkflow as w, createInitialState as x, CreateInitialStateOptions as y, SucceededInstallationState as z };
@@ -12,5 +12,6 @@
12
12
  * governing permissions and limitations under the License.
13
13
  */
14
14
 
15
- import { $ as StepMetaInfo, A as FailedInstallationState, B as isInProgressState, C as executeWorkflow, D as StepStartedEvent, E as StepFailedEvent, F as InstallationStatus, G as ExecutionContext, H as AnyStep, I as StepStatus, J as LeafStep, K as InferStepOutput, L as SucceededInstallationState, M as InstallationData, N as InstallationError, O as StepSucceededEvent, P as InstallationState, Q as StepMeta, R as isCompletedState, S as executeUninstallWorkflow, T as StepEvent, U as BranchStep, V as isSucceededState, W as BranchStepOptions, X as Step, Y as LeafStepOptions, Z as StepContextFactory, _ as ValidationSummary, a as RunValidationOptions, at as defineLeafStep, b as ExecuteWorkflowOptions, c as runInstallation, d as CustomInstallationStepDefinition, et as ValidationContext, f as CustomInstallationStepHandler, g as ValidationResult, h as ValidateStepTreeOptions, i as RunUninstallationOptions, it as defineBranchStep, j as InProgressInstallationState, k as ExecutionStatus, l as runUninstallation, m as StepValidationResult, n as CreateInitialUninstallationStateOptions, nt as ValidationIssue, o as createInitialInstallationState, ot as isBranchStep, p as defineCustomInstallationStep, q as InstallationContext, r as RunInstallationOptions, rt as ValidationIssueSeverity, s as createInitialUninstallationState, st as isLeafStep, t as CreateInitialInstallationStateOptions, tt as ValidationExecutionContext, u as runValidation, v as validateStepTree, w as InstallationHooks, x as createInitialState, y as CreateInitialStateOptions, z as isFailedState } from "../index-BENO5T7n.mjs";
16
- export { AnyStep, BranchStep, BranchStepOptions, CreateInitialInstallationStateOptions, CreateInitialStateOptions, CreateInitialUninstallationStateOptions, CustomInstallationStepDefinition, CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, RunInstallationOptions, RunUninstallationOptions, RunValidationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepMetaInfo, StepStartedEvent, StepStatus, StepSucceededEvent, StepValidationResult, SucceededInstallationState, ValidateStepTreeOptions, ValidationContext, ValidationExecutionContext, ValidationIssue, ValidationIssueSeverity, ValidationResult, ValidationSummary, createInitialInstallationState, createInitialState, createInitialUninstallationState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeUninstallWorkflow, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation, runUninstallation, runValidation, validateStepTree };
15
+ import { _ as defineBranchStep, a as InferStepOutput, b as isLeafStep, c as LeafStepOptions, d as StepMeta, f as StepMetaInfo, g as ValidationIssueSeverity, h as ValidationIssue, i as ExecutionContext, l as Step, m as ValidationExecutionContext, n as BranchStep, o as InstallationContext, p as ValidationContext, r as BranchStepOptions, s as LeafStep, t as AnyStep, u as StepContextFactory, v as defineLeafStep, y as isBranchStep } from "../step-0eI2x4C9.mjs";
16
+ import { A as ExecutionStatus, B as isCompletedState, C as executeUninstallWorkflow, D as StepFailedEvent, E as StepEvent, F as InstallationRetryMetadata, H as isInProgressState, I as InstallationState, L as InstallationStatus, M as InProgressInstallationState, N as InstallationData, O as StepStartedEvent, P as InstallationError, R as StepStatus, S as createRetryState, T as InstallationHooks, U as isSucceededState, V as isFailedState, _ as ValidationSummary, a as RunValidationOptions, b as ExecuteWorkflowOptions, c as runInstallation, d as CustomInstallationStepDefinition, f as CustomInstallationStepHandler, g as ValidationResult, h as ValidateStepTreeOptions, i as RunUninstallationOptions, j as FailedInstallationState, k as StepSucceededEvent, l as runUninstallation, m as StepValidationResult, n as CreateInitialUninstallationStateOptions, o as createInitialInstallationState, p as defineCustomInstallationStep, r as RunInstallationOptions, s as createInitialUninstallationState, t as CreateInitialInstallationStateOptions, u as runValidation, v as validateStepTree, w as executeWorkflow, x as createInitialState, y as CreateInitialStateOptions, z as SucceededInstallationState } from "../index-CCov0odd.mjs";
17
+ export { AnyStep, BranchStep, BranchStepOptions, CreateInitialInstallationStateOptions, CreateInitialStateOptions, CreateInitialUninstallationStateOptions, CustomInstallationStepDefinition, CustomInstallationStepHandler, ExecuteWorkflowOptions, ExecutionContext, ExecutionStatus, FailedInstallationState, InProgressInstallationState, InferStepOutput, InstallationContext, InstallationData, InstallationError, InstallationHooks, InstallationRetryMetadata, InstallationState, InstallationStatus, LeafStep, LeafStepOptions, RunInstallationOptions, RunUninstallationOptions, RunValidationOptions, Step, StepContextFactory, StepEvent, StepFailedEvent, StepMeta, StepMetaInfo, StepStartedEvent, StepStatus, StepSucceededEvent, StepValidationResult, SucceededInstallationState, ValidateStepTreeOptions, ValidationContext, ValidationExecutionContext, ValidationIssue, ValidationIssueSeverity, ValidationResult, ValidationSummary, createInitialInstallationState, createInitialState, createInitialUninstallationState, createRetryState, defineBranchStep, defineCustomInstallationStep, defineLeafStep, executeUninstallWorkflow, executeWorkflow, isBranchStep, isCompletedState, isFailedState, isInProgressState, isLeafStep, isSucceededState, runInstallation, runUninstallation, runValidation, validateStepTree };
@@ -12,6 +12,6 @@
12
12
  * governing permissions and limitations under the License.
13
13
  */
14
14
 
15
- import { a as runValidation, c as isFailedState, i as runUninstallation, l as isInProgressState, n as createInitialUninstallationState, o as defineCustomInstallationStep, r as runInstallation, s as isCompletedState, t as createInitialInstallationState, u as isSucceededState } from "../management-ByHvVJ12.mjs";
15
+ import { a as runValidation, c as isFailedState, i as runUninstallation, l as isInProgressState, n as createInitialUninstallationState, o as defineCustomInstallationStep, r as runInstallation, s as isCompletedState, t as createInitialInstallationState, u as isSucceededState } from "../management-CCsOfniv.mjs";
16
16
 
17
17
  export { createInitialInstallationState, createInitialUninstallationState, defineCustomInstallationStep, isCompletedState, isFailedState, isInProgressState, isSucceededState, runInstallation, runUninstallation, runValidation };