hierarchical-approval 2.0.0 → 2.2.0

package/dist/index.cjs

@@ -914,6 +914,7 @@ function computeTimingStats(samples) {
 }
 
 // src/engine/ApprovalEngine.ts
+var MAX_SUBWORKFLOW_DEPTH = 5;
 var DEFAULT_MAX_REMINDERS = 3;
 var DEFAULT_MAX_ATTEMPTS = 3;
 var DEFAULT_BASE_DELAY_MS = 50;
@@ -925,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;
@@ -1018,12 +1020,32 @@ var ApprovalEngine = class _ApprovalEngine {
           });
         }
         levelNums.add(l.level);
-        if (!l.approvers || l.approvers.length === 0) {
+        if (!l.subWorkflow && (!l.approvers || l.approvers.length === 0)) {
           errors.push({
             field: `levels[${i}].approvers`,
             message: `Level ${l.level} must have at least one approver.`
           });
         }
+        if (l.subWorkflow) {
+          if (!l.subWorkflow.templateName) {
+            errors.push({
+              field: `levels[${i}].subWorkflow.templateName`,
+              message: `Level ${l.level} declares a subWorkflow without a templateName.`
+            });
+          }
+          if (l.subWorkflow.templateName === config.name) {
+            errors.push({
+              field: `levels[${i}].subWorkflow.templateName`,
+              message: `Level ${l.level} would spawn a sub-workflow of its own template ("${config.name}"), which cannot terminate.`
+            });
+          }
+          if (l.approvers && l.approvers.length > 0) {
+            errors.push({
+              field: `levels[${i}].approvers`,
+              message: `Level ${l.level} sets both approvers and subWorkflow; a sub-workflow level is decided by its child approval, so its approvers would never be asked.`
+            });
+          }
+        }
         if (l.reminderAfterDays !== void 0 && l.reminderAfterDays <= 0) {
           errors.push({
             field: `levels[${i}].reminderAfterDays`,
@@ -1166,7 +1188,7 @@ var ApprovalEngine = class _ApprovalEngine {
     return this.registry.list();
   }
   // ─── Lifecycle ────────────────────────────────────────────────────────────
-  async submit(raw, auditCtx) {
+  async submit(raw, auditCtx, link) {
     const opts = parseOrThrow(() => SubmitOptionsSchema.parse(raw));
     const startMs = this.clock.now().getTime();
     const template = await this.registry.get(opts.templateName);
@@ -1226,6 +1248,7 @@ var ApprovalEngine = class _ApprovalEngine {
         weights: cfg.weights,
         escalationAfterDays: cfg.escalationAfterDays,
         escalationDueAt: inFirstGroup && cfg.escalationAfterDays ? this.deadlineFrom(now, cfg.escalationAfterDays) : void 0,
+        subWorkflowTemplate: cfg.subWorkflow?.templateName,
         reminderAfterDays: cfg.reminderAfterDays,
         reminderEveryDays: cfg.reminderEveryDays,
         maxReminders: cfg.maxReminders,
@@ -1234,6 +1257,10 @@ var ApprovalEngine = class _ApprovalEngine {
       };
     });
     for (const lvl of levels.filter((l) => l.status === "pending")) {
+      if (lvl.subWorkflowTemplate) {
+        lvl.approverIds = [];
+        continue;
+      }
       lvl.approverIds = await this.resolver.resolveApprovers(
         lvl.approverConfigs,
         opts.submittedBy,
@@ -1254,6 +1281,9 @@ var ApprovalEngine = class _ApprovalEngine {
     const instance = {
       id: instanceId,
       tenantId: this.tenantId,
+      parentInstanceId: link?.parentInstanceId,
+      parentLevel: link?.parentLevel,
+      subWorkflowDepth: link?.depth,
       templateId: template.id,
       templateName: template.name,
       documentId: opts.documentId,
@@ -1318,12 +1348,13 @@ var ApprovalEngine = class _ApprovalEngine {
       { operation: "submit", actorId: opts.submittedBy, tenantId: this.tenantId, input: opts },
       instance
     );
+    await this.startSubWorkflows(instance);
     return instance;
   }
   async approve(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => ApproveOptionsSchema.parse(raw));
     const startMs = this.clock.now().getTime();
-    return this.withOptimisticRetry(instanceId, async (instance) => {
+    const decided = await this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.approverId === instance.submittedBy) {
         throw new ApprovalForbiddenError(
@@ -1536,10 +1567,12 @@ var ApprovalEngine = class _ApprovalEngine {
       }
       return instance;
     });
+    await this.afterDecision(decided);
+    return decided;
   }
   async reject(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => RejectOptionsSchema.parse(raw));
-    return this.withOptimisticRetry(instanceId, async (instance) => {
+    const decided = await this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.approverId === instance.submittedBy) {
         throw new ApprovalForbiddenError(
@@ -1658,6 +1691,8 @@ var ApprovalEngine = class _ApprovalEngine {
       }
       return instance;
     });
+    await this.afterDecision(decided);
+    return decided;
   }
   async delegate(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => DelegateOptionsSchema.parse(raw));
@@ -1835,7 +1870,8 @@ var ApprovalEngine = class _ApprovalEngine {
   }
   async cancel(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => CancelOptionsSchema.parse(raw));
-    return this.withOptimisticRetry(instanceId, async (instance) => {
+    let cancelled = null;
+    const result = await this.withOptimisticRetry(instanceId, async (instance) => {
       if (instance.status === "approved" || instance.status === "rejected") {
         throw new ApprovalError(`Cannot cancel a "${instance.status}" approval.`, "CANNOT_CANCEL");
       }
@@ -1889,8 +1925,11 @@ var ApprovalEngine = class _ApprovalEngine {
         },
         instance
       );
+      cancelled = instance;
       return instance;
     });
+    if (cancelled) await this.propagateToParent(cancelled);
+    return result;
   }
   async escalate(instanceId, raw, auditCtx) {
     parseOrThrow(() => EscalateOptionsSchema.parse(raw));
@@ -2969,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",
@@ -3407,14 +3558,18 @@ var ApprovalEngine = class _ApprovalEngine {
   /** Resolve approvers for a group, set its deadlines, and mark it pending. */
   async activateGroup(instance, group, now) {
     for (const lvl of group) {
-      lvl.approverIds = await this.resolver.resolveApprovers(
-        lvl.approverConfigs,
-        instance.submittedBy,
-        instance.data,
-        this.opts.orgProvider,
-        this.opts.outOfOfficeProvider,
-        now
-      );
+      if (lvl.subWorkflowTemplate) {
+        lvl.approverIds = [];
+      } else {
+        lvl.approverIds = await this.resolver.resolveApprovers(
+          lvl.approverConfigs,
+          instance.submittedBy,
+          instance.data,
+          this.opts.orgProvider,
+          this.opts.outOfOfficeProvider,
+          now
+        );
+      }
       if (lvl.escalationAfterDays) {
         lvl.escalationDueAt = this.deadlineFrom(now, lvl.escalationAfterDays);
       }
@@ -3501,6 +3656,222 @@ var ApprovalEngine = class _ApprovalEngine {
       this.logger.error("reminder: failed to send", err, { tenantId: this.tenantId, instanceId });
     }
   }
+  /**
+   * Start child approvals for any open level that delegates to a sub-workflow.
+   *
+   * Run after the parent has been persisted, never inside the same optimistic
+   * write: the child's own `submit()` performs its own reads and writes, and
+   * nesting them under the parent's compare-and-set would make a slow child
+   * template a source of spurious version conflicts on the parent.
+   */
+  async startSubWorkflows(instance) {
+    const pendingSubs = instance.levels.filter(
+      (l) => l.status === "pending" && l.subWorkflowTemplate && !l.childInstanceId
+    );
+    if (pendingSubs.length === 0) return;
+    const depth = (instance.subWorkflowDepth ?? 0) + 1;
+    if (depth > MAX_SUBWORKFLOW_DEPTH) {
+      throw new ApprovalValidationError(
+        `Sub-workflow nesting exceeded ${MAX_SUBWORKFLOW_DEPTH} levels at template "${instance.templateName}". Check for a template that reaches itself.`
+      );
+    }
+    for (const level of pendingSubs) {
+      const templateName = level.subWorkflowTemplate;
+      const childTemplate = await this.registry.get(templateName);
+      const child = await this.submit(
+        {
+          templateName,
+          // Unique per parent level, so a resubmitted parent does not collide
+          // with the child it spawned last time.
+          documentId: `${instance.documentId}#L${level.level}`,
+          documentType: childTemplate.documentType,
+          submittedBy: instance.submittedBy,
+          data: instance.data,
+          metadata: { ...instance.metadata, parentInstanceId: instance.id }
+        },
+        void 0,
+        { parentInstanceId: instance.id, parentLevel: level.level, depth }
+      );
+      await this.withOptimisticRetry(instance.id, async (parent) => {
+        const lvl = parent.levels.find((l) => l.level === level.level);
+        if (!lvl || lvl.childInstanceId) return parent;
+        lvl.childInstanceId = child.id;
+        parent.updatedAt = this.clock.now();
+        await this.opts.adapter.updateInstance(parent, parent.version);
+        return parent;
+      });
+      const payload = {
+        instanceId: instance.id,
+        documentId: instance.documentId,
+        documentType: instance.documentType,
+        timestamp: this.clock.now(),
+        level: level.level,
+        childInstanceId: child.id,
+        childTemplateName: templateName
+      };
+      this.bus.emit("approval:subworkflow_started", payload);
+      await this.notifyAdapters("approval:subworkflow_started", instance, payload);
+      this.logger.info("subWorkflow: child approval started", {
+        tenantId: this.tenantId,
+        instanceId: instance.id,
+        level: level.level,
+        childInstanceId: child.id
+      });
+    }
+  }
+  /**
+   * Return a finished child's outcome to the parent level that is waiting on it.
+   *
+   * An approved child approves its parent level and lets the chain advance; any
+   * other terminal outcome — rejected, cancelled, expired — rejects the parent,
+   * because the approval the parent was waiting for did not happen. Collapsing
+   * those into one rejection is deliberate: a parent that treated a cancelled
+   * child as "carry on" would advance past a gate nobody cleared.
+   */
+  async propagateToParent(child) {
+    if (!child.parentInstanceId || child.parentLevel === void 0) return;
+    const outcome = child.status;
+    const parentId = child.parentInstanceId;
+    const parentLevelNumber = child.parentLevel;
+    try {
+      const parent = await this.opts.adapter.getInstance(this.tenantId, parentId);
+      if (!parent || parent.status !== "pending") return;
+      const payload = {
+        instanceId: parentId,
+        documentId: parent.documentId,
+        documentType: parent.documentType,
+        timestamp: this.clock.now(),
+        level: parentLevelNumber,
+        childInstanceId: child.id,
+        childTemplateName: child.templateName,
+        outcome
+      };
+      if (outcome === "approved") {
+        await this.completeSubWorkflowLevel(parentId, parentLevelNumber, child);
+      } else {
+        await this.rejectFromSubWorkflow(parentId, parentLevelNumber, child);
+      }
+      const refreshed = await this.opts.adapter.getInstance(this.tenantId, parentId);
+      this.bus.emit("approval:subworkflow_completed", payload);
+      if (refreshed) {
+        await this.notifyAdapters("approval:subworkflow_completed", refreshed, payload);
+      }
+    } catch (err) {
+      this.logger.error("subWorkflow: failed to propagate outcome to parent", err, {
+        tenantId: this.tenantId,
+        childInstanceId: child.id,
+        parentInstanceId: parentId
+      });
+    }
+  }
+  /** Mark a sub-workflow level approved and advance the parent chain. */
+  async completeSubWorkflowLevel(parentId, levelNumber, child) {
+    let advanced = null;
+    await this.withOptimisticRetry(parentId, async (parent) => {
+      const level = parent.levels.find((l) => l.level === levelNumber);
+      if (!level || level.status !== "pending") return parent;
+      const now = this.clock.now();
+      level.status = "approved";
+      level.reminderDueAt = void 0;
+      level.escalationDueAt = void 0;
+      const auditEntry = {
+        action: "subworkflow_completed",
+        actorId: "system",
+        level: levelNumber,
+        timestamp: now,
+        newValue: { childInstanceId: child.id, outcome: "approved" }
+      };
+      parent.auditLog.push(auditEntry);
+      parent.updatedAt = now;
+      const siblingsOpen = this.groupMembers(parent, level).some(
+        (l) => l.status === "pending" || l.status === "waiting"
+      );
+      if (!siblingsOpen) {
+        const nextGroup = this.findNextGroup(parent);
+        if (nextGroup.length === 0) {
+          parent.status = "approved";
+        } else {
+          await this.activateGroup(parent, nextGroup, now);
+        }
+      }
+      await this.opts.adapter.updateInstance(parent, parent.version);
+      await this.opts.adapter.appendAuditEntry(this.tenantId, parentId, auditEntry);
+      await this.runExternalAudit(parent, auditEntry);
+      advanced = parent;
+      return parent;
+    });
+    if (advanced) {
+      const parent = advanced;
+      if (parent.status === "approved") {
+        this.bus.emit("approval:completed", parent);
+        await this.notifyAdapters("approval:completed", parent, parent);
+        await this.propagateToParent(parent);
+      } else {
+        await this.startSubWorkflows(parent);
+      }
+    }
+  }
+  /** Reject a parent because the child approval it was waiting on did not succeed. */
+  async rejectFromSubWorkflow(parentId, levelNumber, child) {
+    let rejected = null;
+    await this.withOptimisticRetry(parentId, async (parent) => {
+      const level = parent.levels.find((l) => l.level === levelNumber);
+      if (!level || level.status !== "pending") return parent;
+      const now = this.clock.now();
+      level.status = "rejected";
+      level.reminderDueAt = void 0;
+      level.escalationDueAt = void 0;
+      parent.status = "rejected";
+      parent.updatedAt = now;
+      const auditEntry = {
+        action: "subworkflow_completed",
+        actorId: "system",
+        level: levelNumber,
+        timestamp: now,
+        reason: `Child approval ${child.id} ended as "${child.status}".`,
+        newValue: { childInstanceId: child.id, outcome: child.status }
+      };
+      parent.auditLog.push(auditEntry);
+      await this.opts.adapter.updateInstance(parent, parent.version);
+      await this.opts.adapter.appendAuditEntry(this.tenantId, parentId, auditEntry);
+      await this.runExternalAudit(parent, auditEntry);
+      rejected = parent;
+      return parent;
+    });
+    if (rejected) {
+      const parent = rejected;
+      const payload = {
+        instanceId: parent.id,
+        documentId: parent.documentId,
+        documentType: parent.documentType,
+        timestamp: this.clock.now(),
+        approverId: "system",
+        level: levelNumber,
+        reason: `Child approval ${child.id} ended as "${child.status}".`,
+        returnTo: null
+      };
+      this.bus.emit("approval:rejected", payload);
+      await this.notifyAdapters("approval:rejected", parent, payload);
+      await this.propagateToParent(parent);
+    }
+  }
+  /**
+   * Work that must happen after a decision is durably recorded, not inside it.
+   *
+   * Both branches touch other instances — a newly opened level may spawn a
+   * child approval, and a finished instance may be a child that owes its
+   * outcome to a parent. Doing either inside the deciding instance's
+   * compare-and-set would nest writes under a version guard that knows nothing
+   * about them, so a slow child template would surface as a spurious conflict
+   * on the decision the user just made.
+   */
+  async afterDecision(instance) {
+    if (TERMINAL_STATUSES.has(instance.status)) {
+      await this.propagateToParent(instance);
+      return;
+    }
+    await this.startSubWorkflows(instance);
+  }
   findNextLevel(instance) {
     return instance.levels.find((l) => l.level > instance.currentLevel && l.status === "waiting") ?? null;
   }
@@ -3848,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;