hierarchical-approval 4.0.3 → 4.0.5

package/CHANGELOG.md

@@ -1,9 +1,3 @@
-## 4.0.3 - 2026-09-22
-
-- fix(engine): name the level in assertApproverOnLevel's error
-- fix(utils): name the offending start date in businessHoursCalendar's error
-- fix(engine): name the offending instance id in assertStatus's error
-
 # Changelog
 
 All notable changes to `hierarchical-approval` are documented here. This project
@@ -11,6 +5,34 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.0.5] - 2026-09-25
+
+### Fixed
+
+- `RateLimitMiddleware`'s constructor validation now throws
+  `ApprovalValidationError`, instead of a plain `Error` a caller catching
+  `ApprovalValidationError` to distinguish config problems would miss.
+- `DigestNotificationAdapter`'s `intervalMs` validation now throws
+  `ApprovalValidationError` for the same reason.
+- `HashChainAuditAdapter`'s missing-`reader` validation now throws
+  `ApprovalValidationError` for the same reason.
+- `businessHoursCalendar`'s three configuration guards now throw
+  `ApprovalValidationError` for the same reason.
+
+## [4.0.4] - 2026-09-24
+
+### Fixed
+
+- `resubmit`'s duplicate-level error now names the offending level numbers,
+  instead of a message that gave no clue which levels collided.
+- `purgeInstances`'s date-validation error now names the offending value,
+  instead of a message that gave no clue which value failed.
+- `delegate`'s, `reassign`'s, and `override`'s self-action guards now name
+  the offending id, matching every sibling guard in the same methods that
+  already named theirs.
+
+## [4.0.3] - 2026-09-22
+
 ### Fixed
 
 - `assertStatus`'s `INVALID_STATUS` error now names the instance that failed

package/README.md

@@ -11,7 +11,7 @@ Multi-tenant · audit-ready · fully pluggable · zero runtime dependencies you
 [![types](https://img.shields.io/npm/types/hierarchical-approval.svg?logo=typescript&logoColor=white&color=3178c6)](https://www.typescriptlang.org/)
 [![minzipped size](https://img.shields.io/bundlephobia/minzip/hierarchical-approval?color=44cc11)](https://bundlephobia.com/package/hierarchical-approval)
 [![license](https://img.shields.io/npm/l/hierarchical-approval.svg?color=blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-1256%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
+[![tests](https://img.shields.io/badge/tests-1271%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
 
 [**Documentation**](https://hierarchical-approval.matthewswong.com) ·
 [**npm**](https://www.npmjs.com/package/hierarchical-approval) ·

package/dist/{ApprovalEngine-Djdw-JzA.d.cts → ApprovalEngine-BaJ2PNB7.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-D7cy20uD.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-Dd1jQizG.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-CBsJDk-Y.cjs';
+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 { 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-D3Yelw9R.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-TT2Xhtu6.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 IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.cjs';
-import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D6tTT3gv.cjs';
+import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D5mAFBTC.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -208,6 +208,7 @@ type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 /** {@link IdGeneratorFn} used when no custom generator is configured. */
 declare const defaultIdGenerator: IdGeneratorFn;
 
+/** Backs `{ type: 'role' }` approvers, so a level can name an org role instead of a fixed user id. */
 interface OrgProvider {
     /** Required: resolve users holding a named role. */
     getUsersByRole(role: string, tenantId?: string): Promise<string[]> | string[];
@@ -237,6 +238,11 @@ interface OutOfOfficeProvider {
      */
     getDelegateFor(userId: string, at: Date): Promise<string | null | undefined> | string | null | undefined;
 }
+/**
+ * Resolves a custom approver type's config to concrete user ids. Registered
+ * via {@link ApprovalEngine.registerApproverType} to back a level whose
+ * approver config carries an app-defined `type`.
+ */
 type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
     submittedBy: string;
     data: Record<string, unknown>;
@@ -283,6 +289,7 @@ declare function validateConditionExpression(expression: ConditionExpression, pa
     message: string;
 }>;
 
+/** Outcome of {@link ApprovalEngine.validateTemplate}. */
 interface ValidationResult {
     valid: boolean;
     errors: Array<{
@@ -290,13 +297,16 @@ interface ValidationResult {
         message: string;
     }>;
 }
+/** Outcome of {@link ApprovalEngine.canApprove}. */
 interface CanApproveResult {
     eligible: boolean;
     reason?: 'not_an_approver' | 'already_acted' | 'self_approval' | 'wrong_status' | 'delegated_away';
 }
+/** One entry in a {@link ApprovalEngine.preview} result, resolved against the given data without persisting anything. */
 interface PreviewChainLevel {
     level: number;
     name: string;
+    /** Approver ids resolved as of preview time; dynamic/role approvers may resolve differently at submit time. */
     resolvedApprovers: string[];
     mode: ApprovalMode;
 }
@@ -390,12 +400,16 @@ interface SimulationResult {
     /** True when the script ran out before the approval finished. */
     incomplete: boolean;
 }
+/** Outcome of a {@link ApprovalEngine.bulkApprove}/{@link ApprovalEngine.bulkReject} sweep. */
 interface BulkResult {
+    /** Instances that reached the requested decision. */
     succeeded: ApprovalInstance[];
+    /** Instances that could not be decided, with the reason. */
     failed: Array<{
         instanceId: string;
         error: ApprovalError;
     }>;
+    /** Number of instance ids passed in, equal to `succeeded.length + failed.length`. */
     total: number;
 }
 /** Outcome of a {@link ApprovalEngine.transferApprovals} sweep. */
@@ -541,6 +555,7 @@ interface CycleTimeStats {
     /** Largest observed time-to-decision. `0` when {@link count} is `0`. */
     maxMs: number;
 }
+/** Outcome of {@link ApprovalEngine.healthCheck}. */
 interface HealthResult {
     status: 'healthy' | 'degraded' | 'unhealthy';
     adapter: 'connected' | 'error';
@@ -549,12 +564,18 @@ interface HealthResult {
     escalationRunning: boolean;
     lastTickAt?: Date;
 }
+/** Controls how {@link ApprovalEngine}'s optimistic-lock retry backs off on write conflicts. Defaults to 3 attempts with a 50ms base delay. */
 interface RetryPolicy {
+    /** Number of attempts before giving up and rethrowing the conflict. */
     maxAttempts: number;
+    /** Linear backoff unit; attempt N waits roughly `baseDelayMs * N` before retrying. */
     baseDelayMs: number;
+    /** Upper bound on the computed delay. Defaults to unbounded. */
     maxDelayMs?: number;
+    /** Adds up to one `baseDelayMs` of random jitter to each delay. Defaults to `true`. */
     jitter?: boolean;
 }
+/** Derives the idempotency key used to dedupe a {@link ApprovalEngine.submit} call from its tenant and document identity. */
 type IdempotencyKeyFn = (tenantId: string, documentType: string, documentId: string, templateName: string, data: Record<string, unknown>) => string;
 interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
@@ -566,6 +587,7 @@ interface ApprovalEngineOptions {
      */
     outOfOfficeProvider?: OutOfOfficeProvider;
     logger?: Logger;
+    /** Interval, in milliseconds, between automatic escalation sweeps. Default: 60000 (1 minute). */
     escalationPollIntervalMs?: number;
     /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
     maxBulkItems?: number;

package/dist/{ApprovalEngine-BtgQDr_8.d.ts → ApprovalEngine-CeBKYLz4.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-CVvNsnnD.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-Dd1jQizG.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BcUskJ6z.js';
+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 { 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-C7ciNnJp.js';
-import { I as IAuditAdapter } from './IAuditAdapter-C-04ar9A.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-C-N8MpHV.js';
+import { I as IAuditAdapter } from './IAuditAdapter-ggCTPf02.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.js';
-import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-wIE1mpTy.js';
+import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BUHKvalu.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -208,6 +208,7 @@ type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 /** {@link IdGeneratorFn} used when no custom generator is configured. */
 declare const defaultIdGenerator: IdGeneratorFn;
 
+/** Backs `{ type: 'role' }` approvers, so a level can name an org role instead of a fixed user id. */
 interface OrgProvider {
     /** Required: resolve users holding a named role. */
     getUsersByRole(role: string, tenantId?: string): Promise<string[]> | string[];
@@ -237,6 +238,11 @@ interface OutOfOfficeProvider {
      */
     getDelegateFor(userId: string, at: Date): Promise<string | null | undefined> | string | null | undefined;
 }
+/**
+ * Resolves a custom approver type's config to concrete user ids. Registered
+ * via {@link ApprovalEngine.registerApproverType} to back a level whose
+ * approver config carries an app-defined `type`.
+ */
 type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
     submittedBy: string;
     data: Record<string, unknown>;
@@ -283,6 +289,7 @@ declare function validateConditionExpression(expression: ConditionExpression, pa
     message: string;
 }>;
 
+/** Outcome of {@link ApprovalEngine.validateTemplate}. */
 interface ValidationResult {
     valid: boolean;
     errors: Array<{
@@ -290,13 +297,16 @@ interface ValidationResult {
         message: string;
     }>;
 }
+/** Outcome of {@link ApprovalEngine.canApprove}. */
 interface CanApproveResult {
     eligible: boolean;
     reason?: 'not_an_approver' | 'already_acted' | 'self_approval' | 'wrong_status' | 'delegated_away';
 }
+/** One entry in a {@link ApprovalEngine.preview} result, resolved against the given data without persisting anything. */
 interface PreviewChainLevel {
     level: number;
     name: string;
+    /** Approver ids resolved as of preview time; dynamic/role approvers may resolve differently at submit time. */
     resolvedApprovers: string[];
     mode: ApprovalMode;
 }
@@ -390,12 +400,16 @@ interface SimulationResult {
     /** True when the script ran out before the approval finished. */
     incomplete: boolean;
 }
+/** Outcome of a {@link ApprovalEngine.bulkApprove}/{@link ApprovalEngine.bulkReject} sweep. */
 interface BulkResult {
+    /** Instances that reached the requested decision. */
     succeeded: ApprovalInstance[];
+    /** Instances that could not be decided, with the reason. */
     failed: Array<{
         instanceId: string;
         error: ApprovalError;
     }>;
+    /** Number of instance ids passed in, equal to `succeeded.length + failed.length`. */
     total: number;
 }
 /** Outcome of a {@link ApprovalEngine.transferApprovals} sweep. */
@@ -541,6 +555,7 @@ interface CycleTimeStats {
     /** Largest observed time-to-decision. `0` when {@link count} is `0`. */
     maxMs: number;
 }
+/** Outcome of {@link ApprovalEngine.healthCheck}. */
 interface HealthResult {
     status: 'healthy' | 'degraded' | 'unhealthy';
     adapter: 'connected' | 'error';
@@ -549,12 +564,18 @@ interface HealthResult {
     escalationRunning: boolean;
     lastTickAt?: Date;
 }
+/** Controls how {@link ApprovalEngine}'s optimistic-lock retry backs off on write conflicts. Defaults to 3 attempts with a 50ms base delay. */
 interface RetryPolicy {
+    /** Number of attempts before giving up and rethrowing the conflict. */
     maxAttempts: number;
+    /** Linear backoff unit; attempt N waits roughly `baseDelayMs * N` before retrying. */
     baseDelayMs: number;
+    /** Upper bound on the computed delay. Defaults to unbounded. */
     maxDelayMs?: number;
+    /** Adds up to one `baseDelayMs` of random jitter to each delay. Defaults to `true`. */
     jitter?: boolean;
 }
+/** Derives the idempotency key used to dedupe a {@link ApprovalEngine.submit} call from its tenant and document identity. */
 type IdempotencyKeyFn = (tenantId: string, documentType: string, documentId: string, templateName: string, data: Record<string, unknown>) => string;
 interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
@@ -566,6 +587,7 @@ interface ApprovalEngineOptions {
      */
     outOfOfficeProvider?: OutOfOfficeProvider;
     logger?: Logger;
+    /** Interval, in milliseconds, between automatic escalation sweeps. Default: 60000 (1 minute). */
     escalationPollIntervalMs?: number;
     /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
     maxBulkItems?: number;

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

@@ -1,5 +1,6 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-Dd1jQizG.cjs';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-Cu6-qPxs.cjs';
 
+/** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {
     /**
      * Called after every state-mutating operation, in addition to the primary storage adapter.

package/dist/{IAuditAdapter-C-04ar9A.d.ts → IAuditAdapter-ggCTPf02.d.ts}

@@ -1,5 +1,6 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-Dd1jQizG.js';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-Cu6-qPxs.js';
 
+/** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {
     /**
      * Called after every state-mutating operation, in addition to the primary storage adapter.

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

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

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

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

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

@@ -1,33 +1,43 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-Dd1jQizG.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-Cu6-qPxs.js';
 
+/** Common fields carried by every lifecycle event emitted for an approval instance. */
 interface ApprovalEvent {
+    /** The `ApprovalInstance.id` this event pertains to. */
     instanceId: string;
+    /** The id of the business document the instance was raised against. */
     documentId: string;
+    /** The document type, matching the template used to raise the instance. */
     documentType: string;
+    /** When the event occurred. */
     timestamp: Date;
 }
+/** Emitted as `approval:submitted` when a new instance is raised. */
 interface SubmittedEvent extends ApprovalEvent {
     submittedBy: string;
     currentApprovers: string[];
 }
+/** Emitted as `approval:approved` when an approver accepts a level. */
 interface ApprovedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     comment?: string;
     isFinal: boolean;
 }
+/** Emitted as `approval:rejected` when an approver rejects a level. */
 interface RejectedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     reason: string;
     returnTo: 'originator' | 'previous' | null;
 }
+/** Emitted as `approval:delegated` when an approver hands their decision to someone else. */
 interface DelegatedEvent extends ApprovalEvent {
     fromApprover: string;
     toApprover: string;
     level: number;
     reason: string;
 }
+/** Emitted as `approval:reassigned` when an admin moves a level to a different approver. */
 interface ReassignedEvent extends ApprovalEvent {
     reassignedBy: string;
     fromApprover: string;
@@ -35,30 +45,37 @@ interface ReassignedEvent extends ApprovalEvent {
     level: number;
     reason: string;
 }
+/** Emitted as `approval:escalated` when a level's SLA rung hands off to a new approver. */
 interface EscalatedEvent extends ApprovalEvent {
     level: number;
     escalatedTo: string;
 }
+/** Emitted as `approval:cancelled` when the instance is withdrawn before completion. */
 interface CancelledEvent extends ApprovalEvent {
     cancelledBy: string;
     reason: string;
 }
+/** Emitted as `approval:level_advanced` when the chain moves to its next open level. */
 interface LevelAdvancedEvent extends ApprovalEvent {
     fromLevel: number;
     toLevel: number;
     newApprovers: string[];
 }
+/** Emitted as `approval:resubmitted` when a rejected instance is raised again. */
 interface ResubmittedEvent extends ApprovalEvent {
     resubmittedBy: string;
     originalInstanceId: string;
 }
+/** Emitted as `approval:overridden` when an admin force-approves past the normal chain. */
 interface OverriddenEvent extends ApprovalEvent {
     overriddenBy: string;
     justification: string;
 }
+/** Emitted as `approval:expired` when the instance's deadline passes unresolved. */
 interface ExpiredEvent extends ApprovalEvent {
     deadlineAction: 'cancel' | 'reject';
 }
+/** Emitted as `approval:sla_breached` when a level's deadline passes without expiring the instance. */
 interface SlaBreachedEvent extends ApprovalEvent {
     slaDeadlineAt: Date;
 }

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

@@ -1,33 +1,43 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-Dd1jQizG.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-Cu6-qPxs.cjs';
 
+/** Common fields carried by every lifecycle event emitted for an approval instance. */
 interface ApprovalEvent {
+    /** The `ApprovalInstance.id` this event pertains to. */
     instanceId: string;
+    /** The id of the business document the instance was raised against. */
     documentId: string;
+    /** The document type, matching the template used to raise the instance. */
     documentType: string;
+    /** When the event occurred. */
     timestamp: Date;
 }
+/** Emitted as `approval:submitted` when a new instance is raised. */
 interface SubmittedEvent extends ApprovalEvent {
     submittedBy: string;
     currentApprovers: string[];
 }
+/** Emitted as `approval:approved` when an approver accepts a level. */
 interface ApprovedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     comment?: string;
     isFinal: boolean;
 }
+/** Emitted as `approval:rejected` when an approver rejects a level. */
 interface RejectedEvent extends ApprovalEvent {
     approverId: string;
     level: number;
     reason: string;
     returnTo: 'originator' | 'previous' | null;
 }
+/** Emitted as `approval:delegated` when an approver hands their decision to someone else. */
 interface DelegatedEvent extends ApprovalEvent {
     fromApprover: string;
     toApprover: string;
     level: number;
     reason: string;
 }
+/** Emitted as `approval:reassigned` when an admin moves a level to a different approver. */
 interface ReassignedEvent extends ApprovalEvent {
     reassignedBy: string;
     fromApprover: string;
@@ -35,30 +45,37 @@ interface ReassignedEvent extends ApprovalEvent {
     level: number;
     reason: string;
 }
+/** Emitted as `approval:escalated` when a level's SLA rung hands off to a new approver. */
 interface EscalatedEvent extends ApprovalEvent {
     level: number;
     escalatedTo: string;
 }
+/** Emitted as `approval:cancelled` when the instance is withdrawn before completion. */
 interface CancelledEvent extends ApprovalEvent {
     cancelledBy: string;
     reason: string;
 }
+/** Emitted as `approval:level_advanced` when the chain moves to its next open level. */
 interface LevelAdvancedEvent extends ApprovalEvent {
     fromLevel: number;
     toLevel: number;
     newApprovers: string[];
 }
+/** Emitted as `approval:resubmitted` when a rejected instance is raised again. */
 interface ResubmittedEvent extends ApprovalEvent {
     resubmittedBy: string;
     originalInstanceId: string;
 }
+/** Emitted as `approval:overridden` when an admin force-approves past the normal chain. */
 interface OverriddenEvent extends ApprovalEvent {
     overriddenBy: string;
     justification: string;
 }
+/** Emitted as `approval:expired` when the instance's deadline passes unresolved. */
 interface ExpiredEvent extends ApprovalEvent {
     deadlineAction: 'cancel' | 'reject';
 }
+/** Emitted as `approval:sla_breached` when a level's deadline passes without expiring the instance. */
 interface SlaBreachedEvent extends ApprovalEvent {
     slaDeadlineAt: Date;
 }

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

@@ -1,5 +1,6 @@
-import { a as ApprovalInstance } from './instance-Dd1jQizG.js';
+import { a as ApprovalInstance } from './instance-Cu6-qPxs.js';
 
+/** Base class for all errors thrown by this library; carries a stable machine-readable `code`. */
 declare class ApprovalError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -10,29 +11,40 @@ declare class ApprovalError extends Error {
     };
     toHttpStatus(): number;
 }
+/** Thrown when a requested resource (instance, template, etc.) does not exist. */
 declare class ApprovalNotFoundError extends ApprovalError {
     constructor(resource: string, id: string);
 }
+/** Thrown when an instance was modified by another process since it was last read. */
 declare class ApprovalConflictError extends ApprovalError {
     constructor(instanceId: string);
 }
+/** Thrown when the caller is not authorized to perform the requested action. */
 declare class ApprovalForbiddenError extends ApprovalError {
     constructor(message: string);
 }
+/** Thrown when input or configuration fails validation; `cause` may hold the originating error. */
 declare class ApprovalValidationError extends ApprovalError {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
+/** Thrown when a template lookup by name finds no registered template. */
 declare class ApprovalTemplateNotFoundError extends ApprovalError {
     constructor(name: string);
 }
 
+/** The engine method a middleware hook is running around. */
 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> {
     operation: EngineOperation;
+    /** The target instance's id, for operations that act on an existing instance. */
     instanceId?: string;
+    /** Id of the user or system performing the operation, when known. */
     actorId?: string;
+    /** The engine's configured tenant id (defaults to `'default'`). */
     tenantId: string;
+    /** The caller's own input for this operation, e.g. the submit payload or decision comment. */
     input: T;
 }
 interface IOperationMiddleware {

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

@@ -1,5 +1,6 @@
-import { a as ApprovalInstance } from './instance-Dd1jQizG.cjs';
+import { a as ApprovalInstance } from './instance-Cu6-qPxs.cjs';
 
+/** Base class for all errors thrown by this library; carries a stable machine-readable `code`. */
 declare class ApprovalError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -10,29 +11,40 @@ declare class ApprovalError extends Error {
     };
     toHttpStatus(): number;
 }
+/** Thrown when a requested resource (instance, template, etc.) does not exist. */
 declare class ApprovalNotFoundError extends ApprovalError {
     constructor(resource: string, id: string);
 }
+/** Thrown when an instance was modified by another process since it was last read. */
 declare class ApprovalConflictError extends ApprovalError {
     constructor(instanceId: string);
 }
+/** Thrown when the caller is not authorized to perform the requested action. */
 declare class ApprovalForbiddenError extends ApprovalError {
     constructor(message: string);
 }
+/** Thrown when input or configuration fails validation; `cause` may hold the originating error. */
 declare class ApprovalValidationError extends ApprovalError {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
+/** Thrown when a template lookup by name finds no registered template. */
 declare class ApprovalTemplateNotFoundError extends ApprovalError {
     constructor(name: string);
 }
 
+/** The engine method a middleware hook is running around. */
 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> {
     operation: EngineOperation;
+    /** The target instance's id, for operations that act on an existing instance. */
     instanceId?: string;
+    /** Id of the user or system performing the operation, when known. */
     actorId?: string;
+    /** The engine's configured tenant id (defaults to `'default'`). */
     tenantId: string;
+    /** The caller's own input for this operation, e.g. the submit payload or decision comment. */
     input: T;
 }
 interface IOperationMiddleware {

package/dist/{ISchedulerAdapter-DKv_QjVN.d.cts → ISchedulerAdapter-CLMdBA-5.d.cts}

@@ -1,3 +1,4 @@
+/** Pluggable port for escalation-tick scheduling, so the engine can be backed by BullMQ, Temporal, a cron job, or an in-process timer. */
 interface ISchedulerAdapter {
     /**
      * Schedule a one-shot callback to run at the given date.

package/dist/{ISchedulerAdapter-DKv_QjVN.d.ts → ISchedulerAdapter-CLMdBA-5.d.ts}

@@ -1,3 +1,4 @@
+/** Pluggable port for escalation-tick scheduling, so the engine can be backed by BullMQ, Temporal, a cron job, or an in-process timer. */
 interface ISchedulerAdapter {
     /**
      * Schedule a one-shot callback to run at the given date.

package/dist/{IStorageAdapter-D7cy20uD.d.cts → IStorageAdapter-CrbVtEE-.d.cts}

@@ -1,9 +1,11 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Dd1jQizG.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Cu6-qPxs.cjs';
 
+/** Offset-based pagination request. */
 interface PaginationOpts {
     limit: number;
     offset: number;
 }
+/** Offset-based pagination response, including the total matching count. */
 interface PaginatedResult<T> {
     items: T[];
     total: number;
@@ -14,10 +16,14 @@ interface CursorPaginationOpts {
     limit: number;
     direction?: 'forward' | 'backward';
 }
+/** Cursor-based pagination response. */
 interface CursorPaginatedResult<T> {
     items: T[];
+    /** Pass as `cursor` with `direction: 'forward'` to fetch the next page, if any. */
     nextCursor?: string;
+    /** Pass as `cursor` with `direction: 'backward'` to fetch the previous page, if any. */
     prevCursor?: string;
+    /** Whether another page exists in the requested direction. */
     hasMore: boolean;
 }
 interface InstanceFilter {
@@ -38,6 +44,7 @@ interface InstanceFilter {
      */
     data?: Record<string, unknown>;
 }
+/** The primary persistence contract `ApprovalEngine` reads and writes through — implement this to bring your own store. */
 interface IStorageAdapter {
     saveTemplate(template: ApprovalTemplate): Promise<void>;
     getTemplate(tenantId: string, name: string): Promise<ApprovalTemplate | null>;