hierarchical-approval 2.5.0 → 2.7.0

package/dist/index.cjs

@@ -1273,7 +1273,8 @@ var ApprovalEngine = class _ApprovalEngine {
         weights: cfg.weights,
         escalationAfterDays: cfg.escalationAfterDays,
         escalationAfterHours: cfg.escalationAfterHours,
-        escalationDueAt: inFirstGroup ? this.levelEscalationDue(now, cfg) : void 0,
+        escalationStep: 0,
+        escalationDueAt: inFirstGroup ? this.levelEscalationDue(now, cfg, this.firstRungOf(template.escalationSteps)) : void 0,
         subWorkflowTemplate: cfg.subWorkflow?.templateName,
         reminderAfterDays: cfg.reminderAfterDays,
         reminderEveryDays: cfg.reminderEveryDays,
@@ -1330,6 +1331,7 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
         slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
@@ -2625,6 +2627,7 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
         slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
@@ -2690,6 +2693,98 @@ var ApprovalEngine = class _ApprovalEngine {
     return { levels, conditionsApplied };
   }
   /** Check whether a user is eligible to approve a specific instance. Never throws. */
+  /**
+   * Explain why a chain resolves the way it does for a given document.
+   *
+   * `previewApprovalChain()` answers *what* the chain will be. This answers
+   * *why*: which rule added a level, which rule removed one, which rules were
+   * evaluated and did not match, and where each level's approvers came from —
+   * the question behind "why does this purchase order have a CFO level?", which
+   * previously meant reading the template and re-evaluating the conditions by
+   * hand.
+   *
+   * A rule that throws — an operator nobody registered, a malformed group — is
+   * reported against that rule rather than failing the whole explanation. The
+   * explanation is a diagnostic tool, and it is least useful at exactly the
+   * moment a broken rule makes it throw.
+   *
+   * Reads nothing and writes nothing; safe to expose to a support UI.
+   *
+   * @param templateName - Template to explain.
+   * @param data - Document data the conditions are evaluated against.
+   * @param submittedBy - Submitter, used for approver resolution.
+   */
+  async explainChain(templateName, data, submittedBy) {
+    const template = await this.registry.get(templateName);
+    const conditions = template.conditions ?? [];
+    const rules = [];
+    const addedBy = /* @__PURE__ */ new Map();
+    const skippedBy = /* @__PURE__ */ new Map();
+    conditions.forEach((rule, index) => {
+      const addsLevels = (rule.addLevels ?? []).map((l) => l.level);
+      const skipsLevels = rule.skipLevels ?? [];
+      try {
+        const outcome = evaluateConditions([rule], data);
+        const matched = outcome.addLevels.length > 0 || outcome.skipLevels.size > 0;
+        rules.push({ index, matched, addsLevels, skipsLevels });
+        if (matched) {
+          for (const l of outcome.addLevels) if (!addedBy.has(l.level)) addedBy.set(l.level, index);
+          for (const l of outcome.skipLevels) if (!skippedBy.has(l)) skippedBy.set(l, index);
+        }
+      } catch (err) {
+        rules.push({
+          index,
+          matched: false,
+          addsLevels,
+          skipsLevels,
+          error: err.message
+        });
+      }
+    });
+    let mutations;
+    try {
+      mutations = evaluateConditions(conditions, data);
+    } catch {
+      mutations = { addLevels: [], skipLevels: /* @__PURE__ */ new Set() };
+    }
+    const active = [...template.levels, ...mutations.addLevels].filter((l) => !mutations.skipLevels.has(l.level)).sort((a, b) => a.level - b.level);
+    const levels = [];
+    for (const cfg of active) {
+      const fromCondition = addedBy.has(cfg.level);
+      const base = {
+        level: cfg.level,
+        name: cfg.name,
+        mode: cfg.mode,
+        source: fromCondition ? "condition" : "template",
+        ...fromCondition ? { addedByRule: addedBy.get(cfg.level) } : {},
+        resolvedApprovers: [],
+        ...cfg.subWorkflow ? { subWorkflowTemplate: cfg.subWorkflow.templateName } : {}
+      };
+      if (cfg.subWorkflow) {
+        levels.push(base);
+        continue;
+      }
+      try {
+        base.resolvedApprovers = await this.resolver.resolveApprovers(
+          cfg.approvers,
+          submittedBy,
+          data,
+          this.opts.orgProvider,
+          this.opts.outOfOfficeProvider,
+          this.clock.now()
+        );
+      } catch (err) {
+        base.resolutionError = err.message;
+      }
+      levels.push(base);
+    }
+    const skipped = template.levels.filter((l) => mutations.skipLevels.has(l.level)).map((l) => ({
+      level: l.level,
+      name: l.name,
+      skippedByRule: skippedBy.get(l.level) ?? -1
+    })).sort((a, b) => a.level - b.level);
+    return { templateName: template.name, levels, skipped, rules };
+  }
   async canApprove(instanceId, userId) {
     let instance;
     try {
@@ -3373,10 +3468,14 @@ var ApprovalEngine = class _ApprovalEngine {
   async escalateInternal(instanceId, escalatedBy = "system", auditCtx, levelNumber) {
     return this.withOptimisticRetry(instanceId, async (instance) => {
       if (instance.status !== "pending") return instance;
-      const escalationConfig = instance.templateSnapshot?.escalation ?? (await this.registry.get(instance.templateName)).escalation;
-      if (!escalationConfig) return instance;
+      const ladder = await this.escalationLadder(instance);
+      const targetLevel = levelNumber === void 0 ? this.currentLevelInstance(instance) : instance.levels.find((l) => l.level === levelNumber) ?? this.currentLevelInstance(instance);
+      const rungIndex = targetLevel.escalationStep ?? 0;
+      const rung = ladder[rungIndex];
+      const escalateTo = rung?.escalateTo ?? (instance.templateSnapshot?.escalation ?? (await this.registry.get(instance.templateName)).escalation)?.escalateTo;
+      if (!escalateTo) return instance;
       const newApprovers = await this.resolver.resolveApprovers(
-        [escalationConfig.escalateTo],
+        [escalateTo],
         instance.submittedBy,
         instance.data,
         this.opts.orgProvider,
@@ -3394,10 +3493,13 @@ var ApprovalEngine = class _ApprovalEngine {
         );
         return instance;
       }
-      const level = levelNumber === void 0 ? this.currentLevelInstance(instance) : instance.levels.find((l) => l.level === levelNumber) ?? this.currentLevelInstance(instance);
+      const level = targetLevel;
       level.approverIds = [.../* @__PURE__ */ new Set([...level.approverIds, ...filteredApprovers])];
-      level.escalationDueAt = void 0;
       const now = this.clock.now();
+      level.escalationStep = rungIndex + 1;
+      const nextRung = ladder[rungIndex + 1];
+      const levelOpenedAt = this.levelOpenedAt(instance, level, now);
+      level.escalationDueAt = nextRung ? this.stepDueAt(levelOpenedAt, nextRung) : void 0;
       const escalatedTo = filteredApprovers[0] ?? "unknown";
       const auditEntry = {
         action: "escalated",
@@ -3582,9 +3684,54 @@ var ApprovalEngine = class _ApprovalEngine {
     return addHours ? addHours(from, hours) : new Date(from.getTime() + hours * 36e5);
   }
   /** Level deadline from whichever of days/hours the template configured. */
-  levelEscalationDue(from, level) {
+  levelEscalationDue(from, level, firstRung) {
     if (level.escalationAfterHours) return this.deadlineFromHours(from, level.escalationAfterHours);
     if (level.escalationAfterDays) return this.deadlineFrom(from, level.escalationAfterDays);
+    return firstRung ? this.stepDueAt(from, firstRung) : void 0;
+  }
+  /** First rung of a ladder, sorted by delay, or undefined when there is none. */
+  firstRungOf(steps) {
+    if (!steps || steps.length === 0) return void 0;
+    return [...steps].sort(
+      (a, b) => (a.afterHours ?? (a.afterDays ?? 0) * 24) - (b.afterHours ?? (b.afterDays ?? 0) * 24)
+    )[0];
+  }
+  /**
+   * The escalation ladder for an instance, sorted by delay.
+   *
+   * Read from the instance's template snapshot so an in-flight approval keeps
+   * the ladder it was submitted under, exactly as the single-step
+   * {@link EscalationConfig} already did.
+   */
+  async escalationLadder(instance) {
+    const snapshot = instance.templateSnapshot;
+    const steps = snapshot?.escalationSteps ?? (await this.registry.get(instance.templateName)).escalationSteps ?? [];
+    return [...steps].sort(
+      (a, b) => (a.afterHours ?? (a.afterDays ?? 0) * 24) - (b.afterHours ?? (b.afterDays ?? 0) * 24)
+    );
+  }
+  /**
+   * When a level started collecting decisions.
+   *
+   * Escalation rungs are measured from this, not from the previous rung, so a
+   * ladder reads the way it is written. Recovered from the audit trail — the
+   * `submitted` entry for the opening level, the `level_advanced` entry
+   * otherwise — and falls back to `now` when no entry exists, which only leaves
+   * the ladder no worse off than the single-step behaviour it replaces.
+   */
+  levelOpenedAt(instance, level, fallback) {
+    for (let i = instance.auditLog.length - 1; i >= 0; i--) {
+      const entry = instance.auditLog[i];
+      if (!entry) continue;
+      const opensThisLevel = (entry.action === "level_advanced" || entry.action === "submitted") && entry.level === level.level;
+      if (opensThisLevel) return new Date(entry.timestamp);
+    }
+    return fallback;
+  }
+  /** Deadline for one rung, measured from when the level opened. */
+  stepDueAt(from, step) {
+    if (step.afterHours) return this.deadlineFromHours(from, step.afterHours);
+    if (step.afterDays) return this.deadlineFrom(from, step.afterDays);
     return void 0;
   }
   async requireInstance(id) {
@@ -3679,6 +3826,7 @@ var ApprovalEngine = class _ApprovalEngine {
   }
   /** Resolve approvers for a group, set its deadlines, and mark it pending. */
   async activateGroup(instance, group, now) {
+    const firstRung = this.firstRungOf(instance.templateSnapshot?.escalationSteps);
     for (const lvl of group) {
       if (lvl.subWorkflowTemplate) {
         lvl.approverIds = [];
@@ -3692,7 +3840,8 @@ var ApprovalEngine = class _ApprovalEngine {
           now
         );
       }
-      lvl.escalationDueAt = this.levelEscalationDue(now, lvl);
+      lvl.escalationDueAt = this.levelEscalationDue(now, lvl, firstRung);
+      lvl.escalationStep = 0;
       this.scheduleReminder(lvl, now);
       lvl.status = "pending";
     }