hierarchical-approval 4.0.2 → 4.0.4

package/dist/index.cjs

@@ -556,6 +556,7 @@ var TemplateRegistry = class {
     delete resolved.removeLevels;
     return resolved;
   }
+  /** Register a new template. Throws if a template with this name already exists for the tenant. */
   async define(config) {
     const existing = await this.adapter.getTemplate(this.tenantId, config.name);
     if (existing) {
@@ -592,11 +593,13 @@ var TemplateRegistry = class {
     await this.adapter.saveTemplate(updated);
     return newId;
   }
+  /** Fetch a template by name. Throws if no template with this name exists for the tenant. */
   async get(name) {
     const template = await this.adapter.getTemplate(this.tenantId, name);
     if (!template) throw new ApprovalTemplateNotFoundError(name);
     return template;
   }
+  /** List every template registered for the tenant. */
   async list() {
     return this.adapter.listTemplates(this.tenantId);
   }
@@ -636,6 +639,32 @@ var LevelResolver = class {
     for (const [name, fn] of this.resolvers) target.register(name, fn);
     for (const [name, fn] of this.approverTypes) target.registerApproverType(name, fn);
   }
+  /**
+   * Resolve a level's `approvers` config down to a deduplicated list of user
+   * ids, applying out-of-office cover last so a substitute never sees a stale
+   * approver id.
+   *
+   * @param approvers - The level's approver configs (`user`, `role`,
+   *   `dynamic`, or a custom type registered via {@link registerApproverType}).
+   * @param submittedBy - Passed through to `dynamic` resolvers and custom
+   *   approver-type functions as routing context.
+   * @param data - The instance's document data, passed through the same way.
+   * @param orgProvider - Required to resolve `role` approvers; omit only when
+   *   the template uses no `role` approvers.
+   * @param outOfOffice - Optional cover lookup, consulted after every other
+   *   approver type has resolved.
+   * @param at - The moment out-of-office cover is resolved for. Defaults to
+   *   now.
+   * @param substitutions - Filled with `original -> stand-in` for each
+   *   approver replaced by out-of-office cover, so the caller can carry
+   *   anything keyed by the original id (such as a weighted level's vote
+   *   weight) across to the substitute.
+   * @returns The resolved, deduplicated approver ids (post-substitution).
+   * @throws {ApprovalValidationError} If no approvers resolve at all, a
+   *   `role` approver is configured without an `orgProvider`, a `dynamic`
+   *   approver names a resolver that was never registered, or a custom
+   *   approver type was never registered.
+   */
   async resolveApprovers(approvers, submittedBy, data, orgProvider, outOfOffice, at, substitutions) {
     const resolved = [];
     for (const approver of approvers) {
@@ -1047,7 +1076,7 @@ function evaluateConditions(conditions, data) {
 function assertStatus(instance, expected) {
   if (instance.status !== expected) {
     throw new ApprovalError(
-      `Expected instance status "${expected}" but got "${instance.status}".`,
+      `Instance "${instance.id}": expected status "${expected}" but got "${instance.status}".`,
       "INVALID_STATUS"
     );
   }
@@ -1055,7 +1084,7 @@ function assertStatus(instance, expected) {
 function assertApproverOnLevel(level, approverId) {
   if (!level.approverIds.includes(approverId)) {
     throw new ApprovalForbiddenError(
-      `User "${approverId}" is not an approver for level ${level.level}.`
+      `User "${approverId}" is not an approver for level ${level.level} ("${level.name}").`
     );
   }
 }
@@ -2099,7 +2128,7 @@ var ApprovalEngine = class _ApprovalEngine {
     await this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.fromApprover === opts.toApprover) {
-        throw new ApprovalForbiddenError("Cannot delegate to yourself.");
+        throw new ApprovalForbiddenError(`Cannot delegate to yourself: "${opts.fromApprover}".`);
       }
       const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       this.inheritWeight(level, opts.fromApprover, opts.toApprover);
@@ -2182,7 +2211,9 @@ var ApprovalEngine = class _ApprovalEngine {
     return this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.fromApprover === opts.toApprover) {
-        throw new ApprovalForbiddenError("Cannot reassign an approver to themselves.");
+        throw new ApprovalForbiddenError(
+          `Cannot reassign an approver to themselves: "${opts.fromApprover}".`
+        );
       }
       const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       this.inheritWeight(level, opts.fromApprover, opts.toApprover);
@@ -3008,7 +3039,15 @@ var ApprovalEngine = class _ApprovalEngine {
     }
     const levelNums = new Set(allLevelCfgs.map((l) => l.level));
     if (levelNums.size !== allLevelCfgs.length) {
-      throw new ApprovalValidationError("Duplicate level numbers after condition evaluation.");
+      const seen = /* @__PURE__ */ new Set();
+      const duplicates = /* @__PURE__ */ new Set();
+      for (const l of allLevelCfgs) {
+        if (seen.has(l.level)) duplicates.add(l.level);
+        seen.add(l.level);
+      }
+      throw new ApprovalValidationError(
+        `Duplicate level numbers after condition evaluation: ${[...duplicates].join(", ")}.`
+      );
     }
     const now = this.clock.now();
     const newInstanceId = this.generateId("inst");
@@ -3380,7 +3419,9 @@ var ApprovalEngine = class _ApprovalEngine {
         );
       }
       if (opts.overriddenBy === instance.submittedBy) {
-        throw new ApprovalForbiddenError("Override cannot be performed by the original submitter.");
+        throw new ApprovalForbiddenError(
+          `Override cannot be performed by the original submitter: "${opts.overriddenBy}".`
+        );
       }
       await this.runAuthorizationPolicy({
         operation: "override",
@@ -3874,7 +3915,9 @@ var ApprovalEngine = class _ApprovalEngine {
     const dryRun = opts.dryRun ?? false;
     const limit = opts.limit ?? DEFAULT_PURGE_LIMIT;
     if (!(opts.olderThan instanceof Date) || Number.isNaN(opts.olderThan.getTime())) {
-      throw new ApprovalValidationError("purgeInstances requires a valid olderThan date.");
+      throw new ApprovalValidationError(
+        `purgeInstances requires a valid olderThan date, got ${String(opts.olderThan)}.`
+      );
     }
     const requested = opts.statuses ?? [...TERMINAL_STATUSES];
     const nonTerminal = requested.filter((st) => !TERMINAL_STATUSES.has(st));
@@ -5170,7 +5213,7 @@ function businessHoursCalendar(options = {}) {
       return cursor;
     }
     throw new Error(
-      "businessHoursCalendar: no working day found within 10 years of the start date."
+      `businessHoursCalendar: no working day found within 10 years of ${from.toISOString()} \u2014 check weekendDays and holidays.`
     );
   };
   const base = weekendCalendar(options);