hierarchical-approval 4.0.2 → 4.0.4

package/CHANGELOG.md

@@ -1,9 +1,3 @@
-## 4.0.2 - 2026-09-20
-
-- fix(notify): name the offending value in DigestNotificationAdapter's error
-- fix(engine): stop leaking a listener when on() double-registers it
-- fix(webhook): give the real-timer sleep test slack for CI jitter
-
 # Changelog
 
 All notable changes to `hierarchical-approval` are documented here. This project
@@ -11,6 +5,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.0.4] - 2026-09-24
+
+## [4.0.3] - 2026-09-22
+
+### Fixed
+
+- `assertStatus`'s `INVALID_STATUS` error now names the instance that failed
+  the check, instead of a message that gave no clue which instance it was.
+- `businessHoursCalendar`'s "no working day found" error now names the start
+  date that triggered it, instead of a message that gave no clue which call
+  misconfigured the calendar.
+- `assertApproverOnLevel`'s forbidden-approver error now names the level,
+  matching every sibling guard in `StateMachine.ts`, instead of a bare level
+  number with no human-readable name.
+
+## [4.0.2] - 2026-09-20
+
 ### Fixed
 
 - `EventBus` (and therefore `engine.on()`/`off()`) no longer leaks a listener
@@ -20,6 +31,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   attached.
 - `DigestNotificationAdapter`'s `intervalMs` validation error now names the
   offending value, instead of a message that gave no clue which value failed.
+- The default-sleep regression test for `WebhookNotificationAdapter` no longer
+  flakes under CI's timer coalescing, which could report elapsed time a
+  millisecond or two short of the asserted floor.
 
 ## [4.0.1] - 2026-09-14
 

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-XgGBQLC_.d.cts → ApprovalEngine-D0_F5OPZ.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-Cjw5zDwQ.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-uUQh5XW3.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-XbD69gss.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-Dhrc4ES6.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-CUZcHWK2.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-J0wSPLIC.cjs';
 import { z } from 'zod';
-import { L as Logger } from './Logger-BplhlU7l.cjs';
-import { C as Clock } from './Clock-3FnOczFJ.cjs';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BBLk8MIz.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-Dt8qjkQL.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
-import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-YJ_08Mof.cjs';
+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-UUKqztxM.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-D9WE0t7A.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.cjs';
+import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-DDmjeYV-.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -201,11 +201,16 @@ interface BusinessHoursCalendarOptions extends WeekendCalendarOptions {
  */
 declare function businessHoursCalendar(options?: BusinessHoursCalendarOptions): Required<Pick<BusinessCalendar, 'addBusinessDays' | 'addBusinessHours'>>;
 
+/** Entity kind an id is generated for: instance, template, attachment, or comment. */
 type IdGeneratorPrefix = 'inst' | 'tpl' | 'att' | 'cmt';
+/** Produces a unique id for the given entity kind. */
 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[];
     /** Optional: resolve users by department name. */
     getUsersByDepartment?(dept: string, tenantId?: string): Promise<string[]> | string[];
@@ -233,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>;
@@ -279,6 +289,7 @@ declare function validateConditionExpression(expression: ConditionExpression, pa
     message: string;
 }>;
 
+/** Outcome of {@link ApprovalEngine.validateTemplate}. */
 interface ValidationResult {
     valid: boolean;
     errors: Array<{
@@ -286,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;
 }
@@ -386,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. */
@@ -537,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';
@@ -545,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;

package/dist/{ApprovalEngine-Dqe-rC6K.d.ts → ApprovalEngine-D4bXQrKD.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-CdXMggPK.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-uUQh5XW3.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BTO9FSKy.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DSKJ1onF.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-CUZcHWK2.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-CLROEfRd.js';
 import { z } from 'zod';
-import { L as Logger } from './Logger-BplhlU7l.js';
-import { C as Clock } from './Clock-3FnOczFJ.js';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CX7lo4lp.js';
-import { I as IAuditAdapter } from './IAuditAdapter-DkbyFFjb.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
-import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-eo6glbpE.js';
+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-B32a2dwP.js';
+import { I as IAuditAdapter } from './IAuditAdapter-FI_RF_XU.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.js';
+import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BKKw7jGN.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -201,11 +201,16 @@ interface BusinessHoursCalendarOptions extends WeekendCalendarOptions {
  */
 declare function businessHoursCalendar(options?: BusinessHoursCalendarOptions): Required<Pick<BusinessCalendar, 'addBusinessDays' | 'addBusinessHours'>>;
 
+/** Entity kind an id is generated for: instance, template, attachment, or comment. */
 type IdGeneratorPrefix = 'inst' | 'tpl' | 'att' | 'cmt';
+/** Produces a unique id for the given entity kind. */
 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[];
     /** Optional: resolve users by department name. */
     getUsersByDepartment?(dept: string, tenantId?: string): Promise<string[]> | string[];
@@ -233,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>;
@@ -279,6 +289,7 @@ declare function validateConditionExpression(expression: ConditionExpression, pa
     message: string;
 }>;
 
+/** Outcome of {@link ApprovalEngine.validateTemplate}. */
 interface ValidationResult {
     valid: boolean;
     errors: Array<{
@@ -286,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;
 }
@@ -386,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. */
@@ -537,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';
@@ -545,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;

package/dist/Clock-D8Qp39q_.d.cts

@@ -0,0 +1,8 @@
+/** Time source injected into engine and plugin components, so tests can control the clock. */
+interface Clock {
+    now(): Date;
+}
+/** {@link Clock} backed by the real wall clock — the default when no clock is configured. */
+declare const systemClock: Clock;
+
+export { type Clock as C, systemClock as s };

package/dist/Clock-D8Qp39q_.d.ts

@@ -0,0 +1,8 @@
+/** Time source injected into engine and plugin components, so tests can control the clock. */
+interface Clock {
+    now(): Date;
+}
+/** {@link Clock} backed by the real wall clock — the default when no clock is configured. */
+declare const systemClock: Clock;
+
+export { type Clock as C, systemClock as s };

package/dist/{IAuditAdapter-Dt8qjkQL.d.cts → IAuditAdapter-D9WE0t7A.d.cts}

@@ -1,5 +1,6 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-uUQh5XW3.cjs';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-CUZcHWK2.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-DkbyFFjb.d.ts → IAuditAdapter-FI_RF_XU.d.ts}

@@ -1,5 +1,6 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-uUQh5XW3.js';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-CUZcHWK2.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-YJ_08Mof.d.cts → IAuthorizationPolicy-BKKw7jGN.d.ts}

@@ -1,10 +1,15 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-uUQh5XW3.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-CUZcHWK2.js';
 
 interface AuthorizationContext {
+    /** The engine method the actor is attempting to call. */
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';
+    /** Id of the user or system attempting the operation. */
     actorId: string;
+    /** The instance the operation targets, as it stood before the operation ran. */
     instance: Readonly<ApprovalInstance>;
+    /** The current level, for level-scoped operations (approve, reject, delegate, etc.); absent otherwise. */
     level?: Readonly<ApprovalLevelInstance>;
+    /** The caller's own options object for this operation, passed through unmodified. */
     opts: Record<string, unknown>;
 }
 interface IAuthorizationPolicy {

package/dist/{IAuthorizationPolicy-eo6glbpE.d.ts → IAuthorizationPolicy-DDmjeYV-.d.cts}

@@ -1,10 +1,15 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-uUQh5XW3.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-CUZcHWK2.cjs';
 
 interface AuthorizationContext {
+    /** The engine method the actor is attempting to call. */
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';
+    /** Id of the user or system attempting the operation. */
     actorId: string;
+    /** The instance the operation targets, as it stood before the operation ran. */
     instance: Readonly<ApprovalInstance>;
+    /** The current level, for level-scoped operations (approve, reject, delegate, etc.); absent otherwise. */
     level?: Readonly<ApprovalLevelInstance>;
+    /** The caller's own options object for this operation, passed through unmodified. */
     opts: Record<string, unknown>;
 }
 interface IAuthorizationPolicy {

package/dist/{IMetricsAdapter-DWq8IFaf.d.cts → IMetricsAdapter-WROxYSXd.d.cts}

@@ -1,3 +1,4 @@
+/** Closed set of metric names an {@link IMetricsAdapter} may be called with, namespaced `approval.<verb>`. */
 type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.reminded' | 'approval.info_requested' | 'approval.info_provided' | 'approval.attachment_added' | 'approval.attachment_removed' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */

package/dist/{IMetricsAdapter-DWq8IFaf.d.ts → IMetricsAdapter-WROxYSXd.d.ts}

@@ -1,3 +1,4 @@
+/** Closed set of metric names an {@link IMetricsAdapter} may be called with, namespaced `approval.<verb>`. */
 type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.reminded' | 'approval.info_requested' | 'approval.info_provided' | 'approval.attachment_added' | 'approval.attachment_removed' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */

package/dist/{INotificationAdapter-BTO9FSKy.d.ts → INotificationAdapter-CLROEfRd.d.ts}

@@ -1,33 +1,43 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-uUQh5XW3.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-CUZcHWK2.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;
 }
@@ -160,15 +177,23 @@ interface HistoryEntry extends AuditEntry {
 }
 
 interface NotificationEvent {
+    /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
+    /** Id of the approval instance the event fired for. */
     instanceId: string;
+    /** Id of the document under approval, as submitted by the caller. */
     documentId: string;
+    /** Caller-defined document category (e.g. `'purchase_order'`). */
     documentType: string;
+    /** When the underlying transition happened. */
     timestamp: Date;
     /** Current-level approver IDs; empty for non-level events (cancelled, expired, etc.). */
     recipients: string[];
+    /** Name of the template governing the instance. */
     templateName: string;
+    /** Tenant the instance belongs to, for multi-tenant deployments. */
     tenantId: string;
+    /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
 interface INotificationAdapter {

package/dist/{INotificationAdapter-XbD69gss.d.cts → INotificationAdapter-J0wSPLIC.d.cts}

@@ -1,33 +1,43 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-uUQh5XW3.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-CUZcHWK2.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;
 }
@@ -160,15 +177,23 @@ interface HistoryEntry extends AuditEntry {
 }
 
 interface NotificationEvent {
+    /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
+    /** Id of the approval instance the event fired for. */
     instanceId: string;
+    /** Id of the document under approval, as submitted by the caller. */
     documentId: string;
+    /** Caller-defined document category (e.g. `'purchase_order'`). */
     documentType: string;
+    /** When the underlying transition happened. */
     timestamp: Date;
     /** Current-level approver IDs; empty for non-level events (cancelled, expired, etc.). */
     recipients: string[];
+    /** Name of the template governing the instance. */
     templateName: string;
+    /** Tenant the instance belongs to, for multi-tenant deployments. */
     tenantId: string;
+    /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
 interface INotificationAdapter {

package/dist/{IOperationMiddleware-CX7lo4lp.d.ts → IOperationMiddleware-B32a2dwP.d.ts}

@@ -1,5 +1,6 @@
-import { a as ApprovalInstance } from './instance-uUQh5XW3.js';
+import { a as ApprovalInstance } from './instance-CUZcHWK2.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,28 +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: string;
+    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 {