hierarchical-approval 2.4.0 → 2.6.0

package/dist/nestjs.d.cts

@@ -1,16 +1,16 @@
 import { OnModuleDestroy, DynamicModule, ModuleMetadata, InjectionToken, OptionalFactoryDependency, Inject } from '@nestjs/common';
-import { a as ApprovalEngine, b as ApprovalEngineOptions } from './ApprovalEngine-C1dUPnLM.cjs';
-import './IStorageAdapter-DdHO4Rf1.cjs';
-import './instance-DUJY_Axf.cjs';
-import './INotificationAdapter-JJAiMyMd.cjs';
+import { a as ApprovalEngine, b as ApprovalEngineOptions } from './ApprovalEngine-BWrblNQ0.cjs';
+import './IStorageAdapter-yX9ERfQE.cjs';
+import './instance-weh2w7Ji.cjs';
+import './INotificationAdapter-C6HPrzh6.cjs';
 import 'zod';
 import './Logger-BplhlU7l.cjs';
 import './Clock-3FnOczFJ.cjs';
-import './IOperationMiddleware-D0ksiFM3.cjs';
-import './IAuditAdapter-BHVKMMv6.cjs';
+import './IOperationMiddleware-CxnPzpqL.cjs';
+import './IAuditAdapter-2UU5edKG.cjs';
 import './IMetricsAdapter-DWq8IFaf.cjs';
 import './ISchedulerAdapter-DKv_QjVN.cjs';
-import './IAuthorizationPolicy-CtLkwQ8I.cjs';
+import './IAuthorizationPolicy-DPpiKzyh.cjs';
 
 /** Options for {@link HierarchicalApprovalModule.forRoot}. */
 interface HierarchicalApprovalModuleOptions extends ApprovalEngineOptions {

package/dist/nestjs.d.ts

@@ -1,16 +1,16 @@
 import { OnModuleDestroy, DynamicModule, ModuleMetadata, InjectionToken, OptionalFactoryDependency, Inject } from '@nestjs/common';
-import { a as ApprovalEngine, b as ApprovalEngineOptions } from './ApprovalEngine-Ci9urTDI.js';
-import './IStorageAdapter-BU3sau5W.js';
-import './instance-DUJY_Axf.js';
-import './INotificationAdapter-BdgfUrIn.js';
+import { a as ApprovalEngine, b as ApprovalEngineOptions } from './ApprovalEngine-D4DdSx-M.js';
+import './IStorageAdapter-ChPT7ZDp.js';
+import './instance-weh2w7Ji.js';
+import './INotificationAdapter-BNGivLgU.js';
 import 'zod';
 import './Logger-BplhlU7l.js';
 import './Clock-3FnOczFJ.js';
-import './IOperationMiddleware-BGYrAqep.js';
-import './IAuditAdapter-C4OASS6u.js';
+import './IOperationMiddleware-CXtg2wzF.js';
+import './IAuditAdapter-DSor54iY.js';
 import './IMetricsAdapter-DWq8IFaf.js';
 import './ISchedulerAdapter-DKv_QjVN.js';
-import './IAuthorizationPolicy-BA_m2Dg9.js';
+import './IAuthorizationPolicy-BOWg-3AH.js';
 
 /** Options for {@link HierarchicalApprovalModule.forRoot}. */
 interface HierarchicalApprovalModuleOptions extends ApprovalEngineOptions {

package/dist/nestjs.js

@@ -1066,6 +1066,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`,
@@ -1130,6 +1142,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`));
@@ -1243,7 +1267,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,
@@ -1273,7 +1299,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,
@@ -1300,7 +1326,9 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
+        slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
       }
     };
@@ -2572,7 +2600,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,
@@ -2594,7 +2622,9 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
+        slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
       }
     };
@@ -3341,10 +3371,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,
@@ -3362,10 +3396,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",
@@ -3537,6 +3574,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);
@@ -3629,6 +3729,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 = [];
@@ -3642,9 +3743,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";
     }