hierarchical-approval 2.4.0 → 2.6.0

package/dist/{instance-DUJY_Axf.d.cts → instance-weh2w7Ji.d.cts}

@@ -59,6 +59,12 @@ interface ApprovalLevelConfig {
      */
     subWorkflow?: SubWorkflowConfig;
     escalationAfterDays?: number;
+    /**
+     * Escalate this level after this many **working hours**, for SLAs quoted in
+     * hours rather than days. Mutually exclusive with
+     * {@link escalationAfterDays}.
+     */
+    escalationAfterHours?: number;
     /**
      * Send a reminder to this level's pending approvers this many days after the
      * level opens. Escalation reassigns work; a reminder only nudges, which is
@@ -143,6 +149,15 @@ interface EscalationConfig {
     afterDays: number;
     escalateTo: ApproverConfig;
 }
+/** One rung of an escalation ladder. See {@link ApprovalTemplateConfig.escalationSteps}. */
+interface EscalationStep {
+    /** Delay from the level opening, in calendar or business days. */
+    afterDays?: number;
+    /** Delay from the level opening, in working hours. Mutually exclusive with {@link afterDays}. */
+    afterHours?: number;
+    /** Who is added to the level when this rung fires. */
+    escalateTo: ApproverConfig;
+}
 interface ApprovalTemplateConfig {
     name: string;
     /**
@@ -164,8 +179,26 @@ interface ApprovalTemplateConfig {
     levels: ApprovalLevelConfig[];
     conditions?: ConditionRule[];
     escalation?: EscalationConfig;
+    /**
+     * An escalation ladder: successive rungs, each measured from the moment the
+     * level opened, each adding another approver.
+     *
+     * A single {@link escalation} could only ever fire once, so a request that
+     * stalled past its second deadline had nowhere further to go — the usual
+     * "chase the manager, then the director, then the VP" pattern had to be built
+     * outside the engine. Steps are sorted by delay and fire in order; each adds
+     * its approver to the level without removing anyone already there.
+     *
+     * Takes precedence over {@link escalation} when both are set.
+     */
+    escalationSteps?: EscalationStep[];
     /** Overall SLA for the entire workflow in days. Emits approval:sla_breached when elapsed. */
     slaDeadlineDays?: number;
+    /**
+     * Overall SLA in **working hours**. Mutually exclusive with
+     * {@link slaDeadlineDays}.
+     */
+    slaDeadlineHours?: number;
     /** Allow emergency override (bypass remaining levels). Must be true to use engine.override(). */
     allowOverride?: boolean;
 }
@@ -227,6 +260,9 @@ interface ApprovalLevelInstance {
     weights?: Record<string, number>;
     escalationDueAt?: Date;
     escalationAfterDays?: number;
+    escalationAfterHours?: number;
+    /** How many escalation rungs have fired on this level. */
+    escalationStep?: number;
     /** When the next reminder for this level is due; cleared when the level closes. */
     reminderDueAt?: Date;
     /** How many reminders have already been sent for this level. */
@@ -280,7 +316,9 @@ interface InfoRequest {
 /** Snapshot of template configuration captured at submit time to insulate in-flight instances from template updates. */
 interface TemplateSnapshot {
     escalation?: EscalationConfig;
+    escalationSteps?: EscalationStep[];
     slaDeadlineDays?: number;
+    slaDeadlineHours?: number;
     allowOverride?: boolean;
 }
 interface ApprovalInstance {
@@ -329,4 +367,4 @@ interface ApprovalInstance {
     attachments?: Attachment[];
 }
 
-export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, SubWorkflowConfig as S, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, ResolverFn as p };
+export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, SubWorkflowConfig as S, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, EscalationStep as p, ResolverFn as q };

package/dist/{instance-DUJY_Axf.d.ts → instance-weh2w7Ji.d.ts}

@@ -59,6 +59,12 @@ interface ApprovalLevelConfig {
      */
     subWorkflow?: SubWorkflowConfig;
     escalationAfterDays?: number;
+    /**
+     * Escalate this level after this many **working hours**, for SLAs quoted in
+     * hours rather than days. Mutually exclusive with
+     * {@link escalationAfterDays}.
+     */
+    escalationAfterHours?: number;
     /**
      * Send a reminder to this level's pending approvers this many days after the
      * level opens. Escalation reassigns work; a reminder only nudges, which is
@@ -143,6 +149,15 @@ interface EscalationConfig {
     afterDays: number;
     escalateTo: ApproverConfig;
 }
+/** One rung of an escalation ladder. See {@link ApprovalTemplateConfig.escalationSteps}. */
+interface EscalationStep {
+    /** Delay from the level opening, in calendar or business days. */
+    afterDays?: number;
+    /** Delay from the level opening, in working hours. Mutually exclusive with {@link afterDays}. */
+    afterHours?: number;
+    /** Who is added to the level when this rung fires. */
+    escalateTo: ApproverConfig;
+}
 interface ApprovalTemplateConfig {
     name: string;
     /**
@@ -164,8 +179,26 @@ interface ApprovalTemplateConfig {
     levels: ApprovalLevelConfig[];
     conditions?: ConditionRule[];
     escalation?: EscalationConfig;
+    /**
+     * An escalation ladder: successive rungs, each measured from the moment the
+     * level opened, each adding another approver.
+     *
+     * A single {@link escalation} could only ever fire once, so a request that
+     * stalled past its second deadline had nowhere further to go — the usual
+     * "chase the manager, then the director, then the VP" pattern had to be built
+     * outside the engine. Steps are sorted by delay and fire in order; each adds
+     * its approver to the level without removing anyone already there.
+     *
+     * Takes precedence over {@link escalation} when both are set.
+     */
+    escalationSteps?: EscalationStep[];
     /** Overall SLA for the entire workflow in days. Emits approval:sla_breached when elapsed. */
     slaDeadlineDays?: number;
+    /**
+     * Overall SLA in **working hours**. Mutually exclusive with
+     * {@link slaDeadlineDays}.
+     */
+    slaDeadlineHours?: number;
     /** Allow emergency override (bypass remaining levels). Must be true to use engine.override(). */
     allowOverride?: boolean;
 }
@@ -227,6 +260,9 @@ interface ApprovalLevelInstance {
     weights?: Record<string, number>;
     escalationDueAt?: Date;
     escalationAfterDays?: number;
+    escalationAfterHours?: number;
+    /** How many escalation rungs have fired on this level. */
+    escalationStep?: number;
     /** When the next reminder for this level is due; cleared when the level closes. */
     reminderDueAt?: Date;
     /** How many reminders have already been sent for this level. */
@@ -280,7 +316,9 @@ interface InfoRequest {
 /** Snapshot of template configuration captured at submit time to insulate in-flight instances from template updates. */
 interface TemplateSnapshot {
     escalation?: EscalationConfig;
+    escalationSteps?: EscalationStep[];
     slaDeadlineDays?: number;
+    slaDeadlineHours?: number;
     allowOverride?: boolean;
 }
 interface ApprovalInstance {
@@ -329,4 +367,4 @@ interface ApprovalInstance {
     attachments?: Attachment[];
 }
 
-export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, SubWorkflowConfig as S, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, ResolverFn as p };
+export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, SubWorkflowConfig as S, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, EscalationStep as p, ResolverFn as q };

package/dist/nestjs.cjs

@@ -1072,6 +1072,18 @@ var ApprovalEngine = class _ApprovalEngine {
             message: `Level ${l.level} sets reminderEveryDays without reminderAfterDays, so no reminder would ever be sent.`
           });
         }
+        if (l.escalationAfterHours !== void 0 && l.escalationAfterHours <= 0) {
+          errors.push({
+            field: `levels[${i}].escalationAfterHours`,
+            message: `Level ${l.level} escalationAfterHours must be a positive number.`
+          });
+        }
+        if (l.escalationAfterDays !== void 0 && l.escalationAfterHours !== void 0) {
+          errors.push({
+            field: `levels[${i}].escalationAfterHours`,
+            message: `Level ${l.level} sets both escalationAfterDays and escalationAfterHours; pick one so the deadline is unambiguous.`
+          });
+        }
         if (l.escalationAfterDays !== void 0 && l.escalationAfterDays <= 0) {
           errors.push({
             field: `levels[${i}].escalationAfterDays`,
@@ -1136,6 +1148,18 @@ var ApprovalEngine = class _ApprovalEngine {
         }
       });
     }
+    if (config.slaDeadlineDays !== void 0 && config.slaDeadlineHours !== void 0) {
+      errors.push({
+        field: "slaDeadlineHours",
+        message: "Template sets both slaDeadlineDays and slaDeadlineHours; pick one so the SLA is unambiguous."
+      });
+    }
+    if (config.slaDeadlineHours !== void 0 && config.slaDeadlineHours <= 0) {
+      errors.push({
+        field: "slaDeadlineHours",
+        message: "slaDeadlineHours must be a positive number."
+      });
+    }
     if (config.conditions) {
       config.conditions.forEach((rule, ruleIdx) => {
         errors.push(...validateConditionExpression(rule.when, `conditions[${ruleIdx}].when`));
@@ -1249,7 +1273,9 @@ var ApprovalEngine = class _ApprovalEngine {
         threshold: cfg.threshold,
         weights: cfg.weights,
         escalationAfterDays: cfg.escalationAfterDays,
-        escalationDueAt: inFirstGroup && cfg.escalationAfterDays ? this.deadlineFrom(now, cfg.escalationAfterDays) : void 0,
+        escalationAfterHours: cfg.escalationAfterHours,
+        escalationStep: 0,
+        escalationDueAt: inFirstGroup ? this.levelEscalationDue(now, cfg, this.firstRungOf(template.escalationSteps)) : void 0,
         subWorkflowTemplate: cfg.subWorkflow?.templateName,
         reminderAfterDays: cfg.reminderAfterDays,
         reminderEveryDays: cfg.reminderEveryDays,
@@ -1279,7 +1305,7 @@ var ApprovalEngine = class _ApprovalEngine {
       timestamp: now,
       ...auditCtx
     };
-    const slaDeadlineAt = template.slaDeadlineDays ? this.deadlineFrom(now, template.slaDeadlineDays) : void 0;
+    const slaDeadlineAt = template.slaDeadlineHours ? this.deadlineFromHours(now, template.slaDeadlineHours) : template.slaDeadlineDays ? this.deadlineFrom(now, template.slaDeadlineDays) : void 0;
     const instance = {
       id: instanceId,
       tenantId: this.tenantId,
@@ -1306,7 +1332,9 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
+        slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
       }
     };
@@ -2578,7 +2606,7 @@ var ApprovalEngine = class _ApprovalEngine {
       reason: opts.reason,
       ...auditCtx
     };
-    const slaDeadlineAt = template.slaDeadlineDays ? this.deadlineFrom(now, template.slaDeadlineDays) : void 0;
+    const slaDeadlineAt = template.slaDeadlineHours ? this.deadlineFromHours(now, template.slaDeadlineHours) : template.slaDeadlineDays ? this.deadlineFrom(now, template.slaDeadlineDays) : void 0;
     const newInstance = {
       id: newInstanceId,
       tenantId: this.tenantId,
@@ -2600,7 +2628,9 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
+        slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
       }
     };
@@ -3347,10 +3377,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,
@@ -3368,10 +3402,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",
@@ -3543,6 +3580,69 @@ var ApprovalEngine = class _ApprovalEngine {
   deadlineFrom(from, days) {
     return this.calendar ? this.calendar.addBusinessDays(from, days) : new Date(from.getTime() + days * 864e5);
   }
+  /**
+   * Resolve an hour-based deadline.
+   *
+   * A calendar that only knows whole days — `weekendCalendar`, say — has no
+   * `addBusinessHours`, and this falls back to elapsed clock time rather than
+   * quietly pretending the calendar was applied. Configure
+   * `businessHoursCalendar` to have hours skip evenings and weekends.
+   */
+  deadlineFromHours(from, hours) {
+    const addHours = this.calendar?.addBusinessHours?.bind(this.calendar);
+    return addHours ? addHours(from, hours) : new Date(from.getTime() + hours * 36e5);
+  }
+  /** Level deadline from whichever of days/hours the template configured. */
+  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) {
     const instance = await this.opts.adapter.getInstance(this.tenantId, id);
     if (!instance) throw new ApprovalNotFoundError("Instance", id);
@@ -3635,6 +3735,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 = [];
@@ -3648,9 +3749,8 @@ var ApprovalEngine = class _ApprovalEngine {
           now
         );
       }
-      if (lvl.escalationAfterDays) {
-        lvl.escalationDueAt = this.deadlineFrom(now, lvl.escalationAfterDays);
-      }
+      lvl.escalationDueAt = this.levelEscalationDue(now, lvl, firstRung);
+      lvl.escalationStep = 0;
       this.scheduleReminder(lvl, now);
       lvl.status = "pending";
     }