hierarchical-approval 2.4.0 → 2.6.0

package/dist/index.cjs

@@ -1071,6 +1071,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`,
@@ -1135,6 +1147,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`));
@@ -1248,7 +1272,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,
@@ -1278,7 +1304,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,
@@ -1305,7 +1331,9 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
+        slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
       }
     };
@@ -2577,7 +2605,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,
@@ -2599,7 +2627,9 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
+        slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
       }
     };
@@ -3346,10 +3376,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,
@@ -3367,10 +3401,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",
@@ -3542,6 +3579,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);
@@ -3634,6 +3734,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 = [];
@@ -3647,9 +3748,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";
     }
@@ -4290,6 +4390,73 @@ function weekendCalendar(options = {}) {
     }
   };
 }
+var HOUR_MS = 36e5;
+function businessHoursCalendar(options = {}) {
+  const startHour = options.workdayStartHour ?? 9;
+  const endHour = options.workdayEndHour ?? 17;
+  if (!(endHour > startHour)) {
+    throw new Error(
+      `businessHoursCalendar: workdayEndHour (${endHour}) must be greater than workdayStartHour (${startHour}).`
+    );
+  }
+  const weekend = new Set(options.weekendDays ?? [0, 6]);
+  const holidays = new Set((options.holidays ?? []).map(dayKey));
+  const isBusinessDay = (d) => !weekend.has(d.getDay()) && !holidays.has(dayKey(d));
+  const startOfWorkday = (d) => {
+    const out = new Date(d.getTime());
+    out.setHours(startHour, 0, 0, 0);
+    return out;
+  };
+  const endOfWorkday = (d) => {
+    const out = new Date(d.getTime());
+    out.setHours(endHour, 0, 0, 0);
+    return out;
+  };
+  const toWorkingMoment = (from) => {
+    const cursor = new Date(from.getTime());
+    for (let guard = 0; guard < 3660; guard++) {
+      if (!isBusinessDay(cursor)) {
+        cursor.setDate(cursor.getDate() + 1);
+        cursor.setHours(startHour, 0, 0, 0);
+        continue;
+      }
+      if (cursor.getTime() < startOfWorkday(cursor).getTime()) return startOfWorkday(cursor);
+      if (cursor.getTime() >= endOfWorkday(cursor).getTime()) {
+        cursor.setDate(cursor.getDate() + 1);
+        cursor.setHours(startHour, 0, 0, 0);
+        continue;
+      }
+      return cursor;
+    }
+    throw new Error(
+      "businessHoursCalendar: no working day found within 10 years of the start date."
+    );
+  };
+  const base = weekendCalendar(options);
+  return {
+    addBusinessDays: base.addBusinessDays,
+    addBusinessHours(from, hours) {
+      if (hours <= 0 || Number.isNaN(hours)) return new Date(from.getTime());
+      let cursor = toWorkingMoment(from);
+      let remainingMs = Math.round(hours * HOUR_MS);
+      for (let guard = 0; remainingMs > 0 && guard < 3660; guard++) {
+        const dayEnd = endOfWorkday(cursor);
+        const availableMs = dayEnd.getTime() - cursor.getTime();
+        if (remainingMs <= availableMs) {
+          return new Date(cursor.getTime() + remainingMs);
+        }
+        remainingMs -= availableMs;
+        const next = new Date(cursor.getTime());
+        next.setDate(next.getDate() + 1);
+        next.setHours(startHour, 0, 0, 0);
+        cursor = toWorkingMoment(next);
+      }
+      throw new Error(
+        `businessHoursCalendar: ${hours} working hours could not be scheduled within 10 years \u2014 check weekendDays and holidays.`
+      );
+    }
+  };
+}
 
 exports.ApprovalConflictError = ApprovalConflictError;
 exports.ApprovalEngine = ApprovalEngine;
@@ -4301,6 +4468,7 @@ exports.ApprovalValidationError = ApprovalValidationError;
 exports.EscalationScheduler = EscalationScheduler;
 exports.MemoryAdapter = MemoryAdapter;
 exports.TEMPLATE_BUNDLE_VERSION = TEMPLATE_BUNDLE_VERSION;
+exports.businessHoursCalendar = businessHoursCalendar;
 exports.defaultIdGenerator = defaultIdGenerator;
 exports.noopLogger = noopLogger;
 exports.systemClock = systemClock;