hierarchical-approval 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [2.2.0] - 2026-09-04
+
+### Added — template export / import
+
+- **`exportTemplates()` and `importTemplates()` move approval configuration
+  between environments.** Templates are authored in a sandbox, reviewed, then
+  promoted — but the only way to carry them across was to read `listTemplates()`
+  and re-post the rows, which dragged each environment's own `id`, `tenantId`
+  and version lineage along. Those either collided on arrival or silently
+  claimed a history the target never had.
+
+  ```ts
+  const bundle = await sandbox.exportTemplates(['PO', 'INV']);
+  await production.importTemplates(bundle, { mode: 'upsert', dryRun: true });
+  ```
+
+  A bundle is plain JSON, version-stamped, and carries no environment-specific
+  fields — they are stripped, not blanked, so a round trip cannot reintroduce a
+  stale id. The target assigns its own identity.
+
+- **`mode: 'create'`** (default) skips templates that already exist;
+  **`'upsert'`** updates them, bumping the version and recording
+  `previousVersionId` exactly as `updateTemplate()` does. `dryRun` reports
+  without writing.
+
+- **Every template is validated before any is written.** A half-applied bundle
+  is worse than one rejected outright: the tenant ends up matching neither
+  environment and the operator cannot tell which half landed. Validation
+  failures reject the whole bundle and name the offending template; storage
+  errors during the write phase are still reported per template, since those can
+  occur after validation passes.
+
+  Import also rejects an unsupported `bundleVersion`, an empty bundle, and
+  duplicate names within one bundle.
+
+  New exports: `TemplateBundle`, `ImportResult`, `TEMPLATE_BUNDLE_VERSION`.
+
 ## [2.1.0] - 2026-09-04
 
 ### Added — sub-workflows

package/README.md

@@ -468,6 +468,32 @@ The sweep is **not atomic**: it reports per-instance failures rather than rollin
 back. A partial transfer is the useful outcome — the approvals that can move
 should move, and the ones that cannot are named so a human can look at them.
 
+### Promoting templates between environments
+
+Approval configuration is authored somewhere safe, reviewed, then promoted.
+`exportTemplates()` produces a portable bundle and `importTemplates()` applies
+it:
+
+```ts
+const bundle = await sandbox.exportTemplates(['PO', 'INV']);   // omit names for all
+const result = await production.importTemplates(bundle, { mode: 'upsert', dryRun: true });
+// { created: [], updated: ['PO', 'INV'], skipped: [], errors: [], dryRun: true }
+```
+
+A bundle is plain JSON and carries **no** `id`, `tenantId`, `createdAt`,
+`version` or `previousVersionId` — those describe one row in one database, and
+importing them would either collide with the target's ids or claim a lineage the
+target never had. The target assigns its own.
+
+`mode: 'create'` (the default) skips templates that already exist; `'upsert'`
+updates them, bumping the version and recording `previousVersionId` as a normal
+`updateTemplate()` would.
+
+**Every template is validated before any is written.** A half-applied bundle
+leaves the tenant matching neither environment with no way to tell which half
+landed, so a bundle that fails validation is rejected whole, naming the
+offending template.
+
 ### Sub-workflows
 
 A level can delegate to a whole separate approval instead of to a list of

package/dist/{ApprovalEngine-CJwnpnpL.d.ts → ApprovalEngine-B3ChZxS7.d.ts}

@@ -305,6 +305,32 @@ interface ApproverWorkload {
     /** Age of that oldest item. `0` when they hold nothing. */
     oldestAgeMs: number;
 }
+/** Version stamp on an exported bundle, so an importer can reject a shape it does not understand. */
+declare const TEMPLATE_BUNDLE_VERSION = 1;
+/**
+ * A portable set of templates, safe to move between environments.
+ *
+ * Deliberately carries no `id`, `tenantId`, `createdAt`, `version` or
+ * `previousVersionId`: those describe one row in one database, and importing
+ * them would either collide with the target's own ids or silently claim a
+ * lineage the target never had.
+ */
+interface TemplateBundle {
+    bundleVersion: number;
+    exportedAt: Date;
+    templates: ApprovalTemplateConfig[];
+}
+/** Outcome of {@link ApprovalEngine.importTemplates}. */
+interface ImportResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    errors: Array<{
+        name: string;
+        message: string;
+    }>;
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -660,6 +686,36 @@ declare class ApprovalEngine {
      * @returns One row per approver holding at least one open level.
      */
     getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
+    /**
+     * Export templates as a portable bundle.
+     *
+     * Approval configuration is written once and then has to travel — authored in
+     * a sandbox, reviewed, promoted to production. Reading `listTemplates()` and
+     * re-posting the rows carried each environment's own `id`, `tenantId` and
+     * version lineage with it, which either collided on arrival or silently
+     * claimed a history the target never had. This strips all of it.
+     *
+     * @param names - Templates to include; omit for all of them.
+     */
+    exportTemplates(names?: string[]): Promise<TemplateBundle>;
+    /**
+     * Import a bundle produced by {@link exportTemplates}.
+     *
+     * **Every template is validated before any is written.** A bundle that is
+     * half-applied is worse than one rejected outright: the tenant is left in a
+     * state matching neither environment, and the operator has no way to tell
+     * which half landed. Per-template failures during the write phase are still
+     * reported individually, since a storage error can occur after validation
+     * passes.
+     *
+     * @param bundle - The bundle to apply.
+     * @param opts - `mode: 'create'` (default) refuses to touch existing
+     *   templates; `'upsert'` updates them. `dryRun` reports without writing.
+     */
+    importTemplates(bundle: TemplateBundle, opts?: {
+        mode?: 'create' | 'upsert';
+        dryRun?: boolean;
+    }): Promise<ImportResult>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -791,4 +847,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type TransferResult as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, TEMPLATE_BUNDLE_VERSION as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type ImportResult as l, type OutOfOfficeProvider as m, type OverrideOptions as n, type PreviewResult as o, type ProvideInfoOptions as p, type RejectOptions as q, type RequestInfoOptions as r, type ResubmitOptions as s, type RetryPolicy as t, type TemplateBundle as u, type TransferResult as v, defaultIdGenerator as w, toComparableNumber as x, validateConditionExpression as y, weekendCalendar as z };

package/dist/{ApprovalEngine-DqRIadYg.d.cts → ApprovalEngine-CbFBAMlO.d.cts}

@@ -305,6 +305,32 @@ interface ApproverWorkload {
     /** Age of that oldest item. `0` when they hold nothing. */
     oldestAgeMs: number;
 }
+/** Version stamp on an exported bundle, so an importer can reject a shape it does not understand. */
+declare const TEMPLATE_BUNDLE_VERSION = 1;
+/**
+ * A portable set of templates, safe to move between environments.
+ *
+ * Deliberately carries no `id`, `tenantId`, `createdAt`, `version` or
+ * `previousVersionId`: those describe one row in one database, and importing
+ * them would either collide with the target's own ids or silently claim a
+ * lineage the target never had.
+ */
+interface TemplateBundle {
+    bundleVersion: number;
+    exportedAt: Date;
+    templates: ApprovalTemplateConfig[];
+}
+/** Outcome of {@link ApprovalEngine.importTemplates}. */
+interface ImportResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    errors: Array<{
+        name: string;
+        message: string;
+    }>;
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -660,6 +686,36 @@ declare class ApprovalEngine {
      * @returns One row per approver holding at least one open level.
      */
     getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
+    /**
+     * Export templates as a portable bundle.
+     *
+     * Approval configuration is written once and then has to travel — authored in
+     * a sandbox, reviewed, promoted to production. Reading `listTemplates()` and
+     * re-posting the rows carried each environment's own `id`, `tenantId` and
+     * version lineage with it, which either collided on arrival or silently
+     * claimed a history the target never had. This strips all of it.
+     *
+     * @param names - Templates to include; omit for all of them.
+     */
+    exportTemplates(names?: string[]): Promise<TemplateBundle>;
+    /**
+     * Import a bundle produced by {@link exportTemplates}.
+     *
+     * **Every template is validated before any is written.** A bundle that is
+     * half-applied is worse than one rejected outright: the tenant is left in a
+     * state matching neither environment, and the operator has no way to tell
+     * which half landed. Per-template failures during the write phase are still
+     * reported individually, since a storage error can occur after validation
+     * passes.
+     *
+     * @param bundle - The bundle to apply.
+     * @param opts - `mode: 'create'` (default) refuses to touch existing
+     *   templates; `'upsert'` updates them. `dryRun` reports without writing.
+     */
+    importTemplates(bundle: TemplateBundle, opts?: {
+        mode?: 'create' | 'upsert';
+        dryRun?: boolean;
+    }): Promise<ImportResult>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -791,4 +847,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type TransferResult as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, TEMPLATE_BUNDLE_VERSION as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type ImportResult as l, type OutOfOfficeProvider as m, type OverrideOptions as n, type PreviewResult as o, type ProvideInfoOptions as p, type RejectOptions as q, type RequestInfoOptions as r, type ResubmitOptions as s, type RetryPolicy as t, type TemplateBundle as u, type TransferResult as v, defaultIdGenerator as w, toComparableNumber as x, validateConditionExpression as y, weekendCalendar as z };

package/dist/index.cjs

@@ -926,6 +926,7 @@ var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
 ]);
 var CYCLE_TIME_STATUSES = ["approved", "rejected", "cancelled"];
 var CYCLE_TIME_FETCH_BATCH_SIZE = 500;
+var TEMPLATE_BUNDLE_VERSION = 1;
 var ApprovalEngine = class _ApprovalEngine {
   constructor(opts) {
     this.opts = opts;
@@ -3007,6 +3008,118 @@ var ApprovalEngine = class _ApprovalEngine {
       oldestAgeMs: Number.isFinite(row.oldest) ? now.getTime() - row.oldest : 0
     })).sort((a, b) => b.pending - a.pending || a.approverId.localeCompare(b.approverId));
   }
+  /**
+   * Export templates as a portable bundle.
+   *
+   * Approval configuration is written once and then has to travel — authored in
+   * a sandbox, reviewed, promoted to production. Reading `listTemplates()` and
+   * re-posting the rows carried each environment's own `id`, `tenantId` and
+   * version lineage with it, which either collided on arrival or silently
+   * claimed a history the target never had. This strips all of it.
+   *
+   * @param names - Templates to include; omit for all of them.
+   */
+  async exportTemplates(names) {
+    const all = await this.registry.list();
+    const wanted = names ? all.filter((t) => names.includes(t.name)) : all;
+    if (names) {
+      const missing = names.filter((n) => !all.some((t) => t.name === n));
+      if (missing.length > 0) {
+        throw new ApprovalTemplateNotFoundError(missing.join(", "));
+      }
+    }
+    return {
+      bundleVersion: TEMPLATE_BUNDLE_VERSION,
+      exportedAt: this.clock.now(),
+      templates: wanted.map((t) => {
+        const {
+          id: _id,
+          tenantId: _tenantId,
+          createdAt: _createdAt,
+          version: _version,
+          previousVersionId: _previousVersionId,
+          ...config
+        } = t;
+        return config;
+      })
+    };
+  }
+  /**
+   * Import a bundle produced by {@link exportTemplates}.
+   *
+   * **Every template is validated before any is written.** A bundle that is
+   * half-applied is worse than one rejected outright: the tenant is left in a
+   * state matching neither environment, and the operator has no way to tell
+   * which half landed. Per-template failures during the write phase are still
+   * reported individually, since a storage error can occur after validation
+   * passes.
+   *
+   * @param bundle - The bundle to apply.
+   * @param opts - `mode: 'create'` (default) refuses to touch existing
+   *   templates; `'upsert'` updates them. `dryRun` reports without writing.
+   */
+  async importTemplates(bundle, opts = {}) {
+    const mode = opts.mode ?? "create";
+    const dryRun = opts.dryRun ?? false;
+    if (bundle.bundleVersion !== TEMPLATE_BUNDLE_VERSION) {
+      throw new ApprovalValidationError(
+        `Unsupported template bundle version ${bundle.bundleVersion}; this engine reads version ${TEMPLATE_BUNDLE_VERSION}.`
+      );
+    }
+    if (!Array.isArray(bundle.templates) || bundle.templates.length === 0) {
+      throw new ApprovalValidationError("Template bundle contains no templates.");
+    }
+    const duplicates = bundle.templates.map((t) => t.name).filter((name, i, all) => all.indexOf(name) !== i);
+    if (duplicates.length > 0) {
+      throw new ApprovalValidationError(
+        `Template bundle contains duplicate names: ${[...new Set(duplicates)].join(", ")}.`
+      );
+    }
+    const invalid = [];
+    for (const config of bundle.templates) {
+      const result2 = this.validateTemplate(config);
+      if (!result2.valid) {
+        invalid.push({
+          name: config.name,
+          message: result2.errors[0]?.message ?? "unknown validation error"
+        });
+      }
+    }
+    if (invalid.length > 0) {
+      throw new ApprovalValidationError(
+        `Template bundle failed validation and was not applied: ${invalid.map((e) => `${e.name}: ${e.message}`).join("; ")}`
+      );
+    }
+    const result = { created: [], updated: [], skipped: [], errors: [], dryRun };
+    for (const config of bundle.templates) {
+      const existing = await this.opts.adapter.getTemplate(this.tenantId, config.name);
+      try {
+        if (existing && mode === "create") {
+          result.skipped.push(config.name);
+          continue;
+        }
+        if (existing) {
+          if (!dryRun) await this.registry.update(config);
+          result.updated.push(config.name);
+        } else {
+          if (!dryRun) await this.registry.define(config);
+          result.created.push(config.name);
+        }
+      } catch (err) {
+        result.errors.push({ name: config.name, message: err.message });
+      }
+    }
+    this.logger.info("importTemplates: bundle applied", {
+      tenantId: this.tenantId,
+      mode,
+      dryRun,
+      created: result.created.length,
+      updated: result.updated.length,
+      skipped: result.skipped.length,
+      errors: result.errors.length
+    });
+    return result;
+  }
   async getStatistics(filter = {}) {
     const statuses = [
       "pending",
@@ -4106,6 +4219,7 @@ exports.ApprovalTemplateNotFoundError = ApprovalTemplateNotFoundError;
 exports.ApprovalValidationError = ApprovalValidationError;
 exports.EscalationScheduler = EscalationScheduler;
 exports.MemoryAdapter = MemoryAdapter;
+exports.TEMPLATE_BUNDLE_VERSION = TEMPLATE_BUNDLE_VERSION;
 exports.defaultIdGenerator = defaultIdGenerator;
 exports.noopLogger = noopLogger;
 exports.systemClock = systemClock;