hierarchical-approval 4.0.5 → 4.0.6

package/CHANGELOG.md

@@ -5,6 +5,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.0.6] - 2026-09-26
+
+### Fixed
+
+- `LevelResolver.resolveApprovers`'s empty-result error now names how many
+  approver configs were attempted, instead of a message that gave no clue
+  whether the level was misconfigured or its role/resolver simply had no
+  members.
+- `transferApprovals`'s same-approver guard now names the offending id,
+  instead of a message that gave no clue which approver was passed twice.
+
 ## [4.0.5] - 2026-09-25
 
 ### Fixed

package/dist/{ApprovalEngine-BaJ2PNB7.d.cts → ApprovalEngine-BnMpoQB2.d.cts}

@@ -1,14 +1,14 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CrbVtEE-.cjs';
-import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-Cu6-qPxs.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-D9IOl9G_.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-_PjAgjFA.cjs';
+import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-MWXPSsA6.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BO6kmkyC.cjs';
 import { z } from 'zod';
 import { L as Logger } from './Logger-hqFbBCtB.cjs';
 import { C as Clock } from './Clock-D8Qp39q_.cjs';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CsF_xD4b.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-Dqpkg-Tz.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-oYhWMKMn.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-DR-WIAK6.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D5mAFBTC.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BwYBOQM3.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;

package/dist/{ApprovalEngine-CeBKYLz4.d.ts → ApprovalEngine-BqKSm1gG.d.ts}

@@ -1,14 +1,14 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DDOW9z0L.js';
-import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-Cu6-qPxs.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-B_9JFH1i.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DN78GD-1.js';
+import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-MWXPSsA6.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-DKLEDgAk.js';
 import { z } from 'zod';
 import { L as Logger } from './Logger-hqFbBCtB.js';
 import { C as Clock } from './Clock-D8Qp39q_.js';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-C-N8MpHV.js';
-import { I as IAuditAdapter } from './IAuditAdapter-ggCTPf02.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CUI6VG6r.js';
+import { I as IAuditAdapter } from './IAuditAdapter-SNpV2hdt.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BUHKvalu.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BMl0xS-j.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;

package/dist/{IAuditAdapter-Dqpkg-Tz.d.cts → IAuditAdapter-DR-WIAK6.d.cts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-Cu6-qPxs.cjs';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-MWXPSsA6.cjs';
 
 /** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {

package/dist/{IAuditAdapter-ggCTPf02.d.ts → IAuditAdapter-SNpV2hdt.d.ts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-Cu6-qPxs.js';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-MWXPSsA6.js';
 
 /** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {

package/dist/{IAuthorizationPolicy-BUHKvalu.d.ts → IAuthorizationPolicy-BMl0xS-j.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-Cu6-qPxs.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-MWXPSsA6.js';
 
 interface AuthorizationContext {
     /** The engine method the actor is attempting to call. */

package/dist/{IAuthorizationPolicy-D5mAFBTC.d.cts → IAuthorizationPolicy-BwYBOQM3.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-Cu6-qPxs.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-MWXPSsA6.cjs';
 
 interface AuthorizationContext {
     /** The engine method the actor is attempting to call. */

package/dist/{INotificationAdapter-D9IOl9G_.d.cts → INotificationAdapter-BO6kmkyC.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-Cu6-qPxs.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-MWXPSsA6.cjs';
 
 /** Common fields carried by every lifecycle event emitted for an approval instance. */
 interface ApprovalEvent {
@@ -14,6 +14,7 @@ interface ApprovalEvent {
 /** Emitted as `approval:submitted` when a new instance is raised. */
 interface SubmittedEvent extends ApprovalEvent {
     submittedBy: string;
+    /** Deduplicated union of every pending level's approvers in the opening group. */
     currentApprovers: string[];
 }
 /** Emitted as `approval:approved` when an approver accepts a level. */
@@ -21,6 +22,7 @@ interface ApprovedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     comment?: string;
+    /** True only when this was the last open branch — the instance is now fully approved. */
     isFinal: boolean;
 }
 /** Emitted as `approval:rejected` when an approver rejects a level. */
@@ -28,6 +30,11 @@ interface RejectedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     reason: string;
+    /**
+     * `'previous'` resets the chain to replay from an earlier level — the instance
+     * stays `pending`. `'originator'` and `null` are the same terminal outcome: the
+     * instance becomes `rejected`; `null` is just what an unset `returnTo` produces.
+     */
     returnTo: 'originator' | 'previous' | null;
 }
 /** Emitted as `approval:delegated` when an approver hands their decision to someone else. */
@@ -86,7 +93,9 @@ interface SlaBreachedEvent extends ApprovalEvent {
  * did not affect it.
  */
 interface DataUpdatedEvent extends ApprovalEvent {
+    /** Caller-supplied; not checked against the instance's submitter or approvers. */
     updatedBy: string;
+    /** Caller-supplied explanation for the change, if any. */
     reason?: string;
     /** Field paths whose values differ after the update. */
     changedFields: string[];
@@ -97,6 +106,7 @@ interface DataUpdatedEvent extends ApprovalEvent {
 }
 /** Emitted when a pending level's approvers are nudged. */
 interface ReminderEvent extends ApprovalEvent {
+    /** The level number being reminded. */
     level: number;
     /** Approvers who still owe a decision on this level. */
     recipients: string[];
@@ -105,8 +115,10 @@ interface ReminderEvent extends ApprovalEvent {
 }
 /** Emitted when an approver asks the submitter for clarification. */
 interface InfoRequestedEvent extends ApprovalEvent {
+    /** Must be an approver on `level` — enforced by requestInfo() before this is recorded. */
     askedBy: string;
     question: string;
+    /** The level `askedBy` was acting on when they asked. */
     level: number;
     /** Who is expected to answer — the submitter. */
     recipients: string[];

package/dist/{INotificationAdapter-B_9JFH1i.d.ts → INotificationAdapter-DKLEDgAk.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-Cu6-qPxs.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-MWXPSsA6.js';
 
 /** Common fields carried by every lifecycle event emitted for an approval instance. */
 interface ApprovalEvent {
@@ -14,6 +14,7 @@ interface ApprovalEvent {
 /** Emitted as `approval:submitted` when a new instance is raised. */
 interface SubmittedEvent extends ApprovalEvent {
     submittedBy: string;
+    /** Deduplicated union of every pending level's approvers in the opening group. */
     currentApprovers: string[];
 }
 /** Emitted as `approval:approved` when an approver accepts a level. */
@@ -21,6 +22,7 @@ interface ApprovedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     comment?: string;
+    /** True only when this was the last open branch — the instance is now fully approved. */
     isFinal: boolean;
 }
 /** Emitted as `approval:rejected` when an approver rejects a level. */
@@ -28,6 +30,11 @@ interface RejectedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     reason: string;
+    /**
+     * `'previous'` resets the chain to replay from an earlier level — the instance
+     * stays `pending`. `'originator'` and `null` are the same terminal outcome: the
+     * instance becomes `rejected`; `null` is just what an unset `returnTo` produces.
+     */
     returnTo: 'originator' | 'previous' | null;
 }
 /** Emitted as `approval:delegated` when an approver hands their decision to someone else. */
@@ -86,7 +93,9 @@ interface SlaBreachedEvent extends ApprovalEvent {
  * did not affect it.
  */
 interface DataUpdatedEvent extends ApprovalEvent {
+    /** Caller-supplied; not checked against the instance's submitter or approvers. */
     updatedBy: string;
+    /** Caller-supplied explanation for the change, if any. */
     reason?: string;
     /** Field paths whose values differ after the update. */
     changedFields: string[];
@@ -97,6 +106,7 @@ interface DataUpdatedEvent extends ApprovalEvent {
 }
 /** Emitted when a pending level's approvers are nudged. */
 interface ReminderEvent extends ApprovalEvent {
+    /** The level number being reminded. */
     level: number;
     /** Approvers who still owe a decision on this level. */
     recipients: string[];
@@ -105,8 +115,10 @@ interface ReminderEvent extends ApprovalEvent {
 }
 /** Emitted when an approver asks the submitter for clarification. */
 interface InfoRequestedEvent extends ApprovalEvent {
+    /** Must be an approver on `level` — enforced by requestInfo() before this is recorded. */
     askedBy: string;
     question: string;
+    /** The level `askedBy` was acting on when they asked. */
     level: number;
     /** Who is expected to answer — the submitter. */
     recipients: string[];

package/dist/{IOperationMiddleware-C-N8MpHV.d.ts → IOperationMiddleware-CUI6VG6r.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-Cu6-qPxs.js';
+import { a as ApprovalInstance } from './instance-MWXPSsA6.js';
 
 /** Base class for all errors thrown by this library; carries a stable machine-readable `code`. */
 declare class ApprovalError extends Error {
@@ -37,6 +37,7 @@ declare class ApprovalTemplateNotFoundError extends ApprovalError {
 type EngineOperation = 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment' | 'addComment' | 'resubmit' | 'override';
 /** Context passed to an {@link IOperationMiddleware} hook for one engine call. */
 interface OperationContext<T = unknown> {
+    /** Which engine method is running; see {@link EngineOperation}. */
     operation: EngineOperation;
     /** The target instance's id, for operations that act on an existing instance. */
     instanceId?: string;

package/dist/{IOperationMiddleware-CsF_xD4b.d.cts → IOperationMiddleware-oYhWMKMn.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-Cu6-qPxs.cjs';
+import { a as ApprovalInstance } from './instance-MWXPSsA6.cjs';
 
 /** Base class for all errors thrown by this library; carries a stable machine-readable `code`. */
 declare class ApprovalError extends Error {
@@ -37,6 +37,7 @@ declare class ApprovalTemplateNotFoundError extends ApprovalError {
 type EngineOperation = 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment' | 'addComment' | 'resubmit' | 'override';
 /** Context passed to an {@link IOperationMiddleware} hook for one engine call. */
 interface OperationContext<T = unknown> {
+    /** Which engine method is running; see {@link EngineOperation}. */
     operation: EngineOperation;
     /** The target instance's id, for operations that act on an existing instance. */
     instanceId?: string;

package/dist/{IStorageAdapter-CrbVtEE-.d.cts → IStorageAdapter-DN78GD-1.d.ts}

@@ -1,23 +1,31 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Cu6-qPxs.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-MWXPSsA6.js';
 
 /** Offset-based pagination request. */
 interface PaginationOpts {
+    /** Maximum number of items to return. */
     limit: number;
+    /** Number of matching items to skip before the page starts. */
     offset: number;
 }
 /** Offset-based pagination response, including the total matching count. */
 interface PaginatedResult<T> {
+    /** The requested page's items. */
     items: T[];
+    /** Total number of items matching the query, across all pages. */
     total: number;
 }
 /** Opaque cursor: base64(updatedAt_iso:id). Use the value from nextCursor/prevCursor. */
 interface CursorPaginationOpts {
+    /** Cursor from a previous page's `nextCursor`/`prevCursor`; omit to start from the first page. */
     cursor?: string;
+    /** Maximum number of items to return. */
     limit: number;
+    /** Which way to page from `cursor`. Defaults to `'forward'`. */
     direction?: 'forward' | 'backward';
 }
 /** Cursor-based pagination response. */
 interface CursorPaginatedResult<T> {
+    /** The requested page's items. */
     items: T[];
     /** Pass as `cursor` with `direction: 'forward'` to fetch the next page, if any. */
     nextCursor?: string;
@@ -27,11 +35,17 @@ interface CursorPaginatedResult<T> {
     hasMore: boolean;
 }
 interface InstanceFilter {
+    /** Match only instances in this status. */
     status?: ApprovalStatus;
+    /** Match only instances of this document type. */
     documentType?: string;
+    /** Match only instances submitted by this user or system id. */
     submittedBy?: string;
+    /** Match only instances created from this template. */
     templateName?: string;
+    /** Match only instances created on or after this date. */
     fromDate?: Date;
+    /** Match only instances created on or before this date. */
     toDate?: Date;
     /**
      * Match instances whose document `data` contains these field/value pairs —

package/dist/{IStorageAdapter-DDOW9z0L.d.ts → IStorageAdapter-_PjAgjFA.d.cts}

@@ -1,23 +1,31 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Cu6-qPxs.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-MWXPSsA6.cjs';
 
 /** Offset-based pagination request. */
 interface PaginationOpts {
+    /** Maximum number of items to return. */
     limit: number;
+    /** Number of matching items to skip before the page starts. */
     offset: number;
 }
 /** Offset-based pagination response, including the total matching count. */
 interface PaginatedResult<T> {
+    /** The requested page's items. */
     items: T[];
+    /** Total number of items matching the query, across all pages. */
     total: number;
 }
 /** Opaque cursor: base64(updatedAt_iso:id). Use the value from nextCursor/prevCursor. */
 interface CursorPaginationOpts {
+    /** Cursor from a previous page's `nextCursor`/`prevCursor`; omit to start from the first page. */
     cursor?: string;
+    /** Maximum number of items to return. */
     limit: number;
+    /** Which way to page from `cursor`. Defaults to `'forward'`. */
     direction?: 'forward' | 'backward';
 }
 /** Cursor-based pagination response. */
 interface CursorPaginatedResult<T> {
+    /** The requested page's items. */
     items: T[];
     /** Pass as `cursor` with `direction: 'forward'` to fetch the next page, if any. */
     nextCursor?: string;
@@ -27,11 +35,17 @@ interface CursorPaginatedResult<T> {
     hasMore: boolean;
 }
 interface InstanceFilter {
+    /** Match only instances in this status. */
     status?: ApprovalStatus;
+    /** Match only instances of this document type. */
     documentType?: string;
+    /** Match only instances submitted by this user or system id. */
     submittedBy?: string;
+    /** Match only instances created from this template. */
     templateName?: string;
+    /** Match only instances created on or after this date. */
     fromDate?: Date;
+    /** Match only instances created on or before this date. */
     toDate?: Date;
     /**
      * Match instances whose document `data` contains these field/value pairs —

package/dist/adapters/MemoryAdapter.d.cts

@@ -1,5 +1,5 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-CrbVtEE-.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Cu6-qPxs.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-_PjAgjFA.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-MWXPSsA6.cjs';
 
 /**
  * In-process {@link IStorageAdapter} backed by two `Map`s, keyed by

package/dist/adapters/MemoryAdapter.d.ts

@@ -1,5 +1,5 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DDOW9z0L.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Cu6-qPxs.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DN78GD-1.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-MWXPSsA6.js';
 
 /**
  * In-process {@link IStorageAdapter} backed by two `Map`s, keyed by