hierarchical-approval 4.0.5 → 4.0.7

package/CHANGELOG.md

@@ -5,6 +5,29 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.0.7] - 2026-09-28
+
+### Fixed
+
+- `RbacAuthorizationPolicy`'s roleProvider-failure denial message now names
+  the offending actor id, instead of a message that gave no clue which actor
+  triggered the fail-closed denial.
+- `ImportResult` and `PreviewResult`'s array fields are now typed as
+  `readonly T[]`, not just `readonly` properties holding a mutable array —
+  callers could previously still `push`/`splice` the returned arrays in
+  place even though the property itself couldn't be reassigned.
+
+## [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-D5ZplHsw.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-DYFj85oL.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-Du-TGRH_.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-rBeUKnBa.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 IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-RGAqQ31Q.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-Bv7jIph1.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DN9rYsoq.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D5mAFBTC.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D0Phw1c_.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -302,7 +302,7 @@ 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. */
+/** One entry in a {@link ApprovalEngine.previewApprovalChain} result, resolved against the given data without persisting anything. */
 interface PreviewChainLevel {
     level: number;
     name: string;
@@ -310,10 +310,12 @@ interface PreviewChainLevel {
     resolvedApprovers: string[];
     mode: ApprovalMode;
 }
+/** Return value of {@link ApprovalEngine.previewApprovalChain}. */
 interface PreviewResult {
-    levels: PreviewChainLevel[];
+    /** The resolved chain, in level order. */
+    readonly levels: readonly PreviewChainLevel[];
     /** Indices (0-based) of conditions that fired for this data. */
-    conditionsApplied: number[];
+    readonly conditionsApplied: readonly number[];
 }
 /** Where one level in an explained chain came from. */
 interface ExplainedLevel {
@@ -468,14 +470,14 @@ interface TemplateBundle {
 }
 /** Outcome of {@link ApprovalEngine.importTemplates}. */
 interface ImportResult {
-    created: string[];
-    updated: string[];
-    skipped: string[];
-    errors: Array<{
+    readonly created: readonly string[];
+    readonly updated: readonly string[];
+    readonly skipped: readonly string[];
+    readonly errors: readonly Readonly<{
         name: string;
         message: string;
-    }>;
-    dryRun: boolean;
+    }>[];
+    readonly dryRun: boolean;
 }
 /** Outcome of a {@link ApprovalEngine.purgeInstances} sweep. */
 interface PurgeResult {
@@ -577,6 +579,7 @@ interface RetryPolicy {
 }
 /** 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;
+/** Constructor options for {@link ApprovalEngine}. Only `adapter` is required. */
 interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
@@ -631,6 +634,11 @@ interface ApprovalEngineOptions {
     /** Middleware chain: before/after/onError hooks for every operation. */
     middleware?: IOperationMiddleware[];
 }
+/**
+ * Runs multi-level approval workflows against a pluggable {@link IStorageAdapter}:
+ * submitting instances against a template, resolving and notifying approvers,
+ * recording decisions, and driving escalation, expiry and sub-workflows.
+ */
 declare class ApprovalEngine {
     private readonly opts;
     private readonly bus;

package/dist/{ApprovalEngine-CeBKYLz4.d.ts → ApprovalEngine-sUWBHas4.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-Bje_7c62.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-Du-TGRH_.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-D_b-H3bB.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 IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BuRYpQdL.js';
+import { I as IAuditAdapter } from './IAuditAdapter-Bg6e0_ME.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DN9rYsoq.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BUHKvalu.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-abLdaLzR.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -302,7 +302,7 @@ 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. */
+/** One entry in a {@link ApprovalEngine.previewApprovalChain} result, resolved against the given data without persisting anything. */
 interface PreviewChainLevel {
     level: number;
     name: string;
@@ -310,10 +310,12 @@ interface PreviewChainLevel {
     resolvedApprovers: string[];
     mode: ApprovalMode;
 }
+/** Return value of {@link ApprovalEngine.previewApprovalChain}. */
 interface PreviewResult {
-    levels: PreviewChainLevel[];
+    /** The resolved chain, in level order. */
+    readonly levels: readonly PreviewChainLevel[];
     /** Indices (0-based) of conditions that fired for this data. */
-    conditionsApplied: number[];
+    readonly conditionsApplied: readonly number[];
 }
 /** Where one level in an explained chain came from. */
 interface ExplainedLevel {
@@ -468,14 +470,14 @@ interface TemplateBundle {
 }
 /** Outcome of {@link ApprovalEngine.importTemplates}. */
 interface ImportResult {
-    created: string[];
-    updated: string[];
-    skipped: string[];
-    errors: Array<{
+    readonly created: readonly string[];
+    readonly updated: readonly string[];
+    readonly skipped: readonly string[];
+    readonly errors: readonly Readonly<{
         name: string;
         message: string;
-    }>;
-    dryRun: boolean;
+    }>[];
+    readonly dryRun: boolean;
 }
 /** Outcome of a {@link ApprovalEngine.purgeInstances} sweep. */
 interface PurgeResult {
@@ -577,6 +579,7 @@ interface RetryPolicy {
 }
 /** 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;
+/** Constructor options for {@link ApprovalEngine}. Only `adapter` is required. */
 interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
@@ -631,6 +634,11 @@ interface ApprovalEngineOptions {
     /** Middleware chain: before/after/onError hooks for every operation. */
     middleware?: IOperationMiddleware[];
 }
+/**
+ * Runs multi-level approval workflows against a pluggable {@link IStorageAdapter}:
+ * submitting instances against a template, resolving and notifying approvers,
+ * recording decisions, and driving escalation, expiry and sub-workflows.
+ */
 declare class ApprovalEngine {
     private readonly opts;
     private readonly bus;

package/dist/{IAuditAdapter-ggCTPf02.d.ts → IAuditAdapter-Bg6e0_ME.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-Du-TGRH_.js';
 
 /** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {

package/dist/{IAuditAdapter-Dqpkg-Tz.d.cts → IAuditAdapter-Bv7jIph1.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-Du-TGRH_.cjs';
 
 /** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {

package/dist/{IAuthorizationPolicy-D5mAFBTC.d.cts → IAuthorizationPolicy-D0Phw1c_.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-Du-TGRH_.cjs';
 
 interface AuthorizationContext {
     /** The engine method the actor is attempting to call. */

package/dist/{IAuthorizationPolicy-BUHKvalu.d.ts → IAuthorizationPolicy-abLdaLzR.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-Du-TGRH_.js';
 
 interface AuthorizationContext {
     /** The engine method the actor is attempting to call. */

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

@@ -1,5 +1,6 @@
 /** 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';
+/** Sink for engine metrics. Implementations are called synchronously and must not throw. */
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

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

@@ -1,5 +1,6 @@
 /** 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';
+/** Sink for engine metrics. Implementations are called synchronously and must not throw. */
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

package/dist/{INotificationAdapter-B_9JFH1i.d.ts → INotificationAdapter-D_b-H3bB.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-Du-TGRH_.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[];
@@ -147,6 +159,7 @@ interface CommentedEvent extends ApprovalEvent {
     /** Users named in the comment. */
     recipients: string[];
 }
+/** Maps each lifecycle event name to its payload type. Keys are what {@link ApprovalEngine.on} accepts; see {@link ApprovalEventName}. */
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -172,10 +185,12 @@ interface ApprovalEventMap {
     'approval:commented': CommentedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
+/** An {@link AuditEntry} tagged with the instance it belongs to, for callers aggregating history across several instances. */
 interface HistoryEntry extends AuditEntry {
     instanceId: string;
 }
 
+/** Normalized envelope passed to {@link INotificationAdapter.notify} for every approval event. */
 interface NotificationEvent {
     /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
@@ -196,6 +211,7 @@ interface NotificationEvent {
     /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
+/** Sink for approval-event notifications (email, Slack, webhooks, ...). */
 interface INotificationAdapter {
     /** Called after every emitted approval event. Must not throw — errors are logged and swallowed. */
     notify(event: NotificationEvent): Promise<void>;

package/dist/{INotificationAdapter-D9IOl9G_.d.cts → INotificationAdapter-rBeUKnBa.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-Du-TGRH_.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[];
@@ -147,6 +159,7 @@ interface CommentedEvent extends ApprovalEvent {
     /** Users named in the comment. */
     recipients: string[];
 }
+/** Maps each lifecycle event name to its payload type. Keys are what {@link ApprovalEngine.on} accepts; see {@link ApprovalEventName}. */
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -172,10 +185,12 @@ interface ApprovalEventMap {
     'approval:commented': CommentedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
+/** An {@link AuditEntry} tagged with the instance it belongs to, for callers aggregating history across several instances. */
 interface HistoryEntry extends AuditEntry {
     instanceId: string;
 }
 
+/** Normalized envelope passed to {@link INotificationAdapter.notify} for every approval event. */
 interface NotificationEvent {
     /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
@@ -196,6 +211,7 @@ interface NotificationEvent {
     /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
+/** Sink for approval-event notifications (email, Slack, webhooks, ...). */
 interface INotificationAdapter {
     /** Called after every emitted approval event. Must not throw — errors are logged and swallowed. */
     notify(event: NotificationEvent): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-Cu6-qPxs.js';
+import { a as ApprovalInstance } from './instance-Du-TGRH_.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-RGAqQ31Q.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-Cu6-qPxs.cjs';
+import { a as ApprovalInstance } from './instance-Du-TGRH_.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-Bje_7c62.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-Du-TGRH_.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;
@@ -26,12 +34,19 @@ interface CursorPaginatedResult<T> {
     /** Whether another page exists in the requested direction. */
     hasMore: boolean;
 }
+/** Query filter for listing/counting instances; every set field narrows the match. */
 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-DYFj85oL.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-Du-TGRH_.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;
@@ -26,12 +34,19 @@ interface CursorPaginatedResult<T> {
     /** Whether another page exists in the requested direction. */
     hasMore: boolean;
 }
+/** Query filter for listing/counting instances; every set field narrows the match. */
 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-DYFj85oL.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Du-TGRH_.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-Bje_7c62.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Du-TGRH_.js';
 
 /**
  * In-process {@link IStorageAdapter} backed by two `Map`s, keyed by