hierarchical-approval 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthews Wong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,24 @@
+<div align="center">
+
 # hierarchical-approval
 
-TypeScript-first multi-level approval workflows for enterprise systems. Multi-tenant, audit-ready, fully pluggable.
+**TypeScript-first multi-level approval workflows for enterprise systems.**
+Multi-tenant · audit-ready · fully pluggable · zero runtime dependencies you don't opt into.
+
+[![npm version](https://img.shields.io/npm/v/hierarchical-approval.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/hierarchical-approval)
+[![npm downloads](https://img.shields.io/npm/dm/hierarchical-approval.svg?color=cb3837)](https://www.npmjs.com/package/hierarchical-approval)
+[![CI](https://github.com/matthews-wong/hierarchical-approval/actions/workflows/ci.yml/badge.svg)](https://github.com/matthews-wong/hierarchical-approval/actions/workflows/ci.yml)
+[![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-195%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
+
+[**Documentation**](https://hierarchical-approval.matthewswong.com) ·
+[**npm**](https://www.npmjs.com/package/hierarchical-approval) ·
+[**Changelog**](./IMPROVEMENTS.md) ·
+[**Examples**](./examples)
+
+</div>
 
 ```sh
 npm install hierarchical-approval
@@ -8,6 +26,8 @@ npm install hierarchical-approval
 npm install pg @types/pg
 ```
 
+> 📖 Full docs & live guides: **[hierarchical-approval.matthewswong.com](https://hierarchical-approval.matthewswong.com)**
+
 ---
 
 ## Why another approval library?
@@ -33,7 +53,7 @@ Approval workflows are deceptively simple until they aren't. Most teams start wi
 **`approval-flow`** — Single-level only; no multi-tenancy; no audit trail; last published 2020.  
 **`workflow-engine`** — Generic state machine; you implement every guard, every condition, every audit entry yourself.  
 **`node-approval`** — No TypeScript; no idempotency; no optimistic locking.  
-**Hand-rolled** — You *will* hit the concurrent-approval race condition eventually. This library has 167 tests covering it.
+**Hand-rolled** — You *will* hit the concurrent-approval race condition eventually. This library has 195 tests covering it.
 
 ---
 
@@ -137,11 +157,44 @@ An **instance** is a single document moving through a template. Key fields:
 
 Each level's `mode` field controls how many approvers are required:
 
-| Mode | Required |
-|---|---|
-| `'any'` | One approver is enough |
-| `'all'` | Every listed approver must act |
-| `'majority'` | More than half must approve |
+| Mode | Required | Extra config |
+|---|---|---|
+| `'any'` | One approver is enough | — |
+| `'all'` | Every listed approver must act | — |
+| `'majority'` | More than half must approve | — |
+| `'quorum'` | A fixed **N-of-M** threshold approves | `minApprovals` |
+| `'weighted'` | Cumulative approver **weight** meets a threshold | `threshold`, optional `weights` |
+
+A level is **rejected** as soon as the outcome becomes mathematically impossible — e.g. a `quorum` of 2-of-3 is rejected after the second rejection (only one approver remains), and a `weighted` level is rejected once the weight still achievable falls below `threshold`.
+
+```ts
+// Quorum: any 2 of these 3 directors must approve
+{
+  level: 1,
+  name: 'Board',
+  mode: 'quorum',
+  minApprovals: 2,
+  approvers: [
+    { type: 'user', userId: 'd1' },
+    { type: 'user', userId: 'd2' },
+    { type: 'user', userId: 'd3' },
+  ],
+}
+
+// Weighted: the CFO's vote (weight 3) clears the threshold alone;
+// otherwise three default-weight (1) approvers are needed.
+{
+  level: 1,
+  name: 'Exec Committee',
+  mode: 'weighted',
+  threshold: 3,
+  weights: { cfo: 3 }, // unlisted approvers default to weight 1
+  approvers: [
+    { type: 'user', userId: 'cfo' },
+    { type: 'user', userId: 'mgr' },
+  ],
+}
+```
 
 ### Conditional chains
 
@@ -344,6 +397,21 @@ await engine.delegate(instanceId, {
 });
 ```
 
+### Reassign
+
+Administratively swap an approver on the current level — for when an assigned approver is unavailable and a third party (e.g. an admin) needs to hand the task to someone else. Unlike `delegate`, the original approver doesn't initiate it. The approver being replaced must still be pending (one who has already approved or rejected cannot be reassigned), and the new approver must not already be on the level.
+
+```ts
+await engine.reassign(instanceId, {
+  reassignedBy: 'workflow-admin',
+  fromApprover: 'mgr-1',
+  toApprover: 'mgr-2',
+  reason: 'Approver left the company',
+});
+```
+
+Emits `approval:reassigned` and records a `reassigned` audit entry.
+
 ### Escalate
 
 ```ts
@@ -352,6 +420,24 @@ await engine.escalate(instanceId, { escalatedBy: 'system' });
 
 Adds the escalation approver (from `template.escalation.escalateTo`) to the current level's approver list. Also fires automatically via the scheduler when `escalationAfterDays` elapses.
 
+#### Business-day deadlines
+
+By default `escalationAfterDays` and `slaDeadlineDays` count plain calendar days. Pass a `calendar` to the engine to count **business days** instead — skipping weekends and holidays:
+
+```ts
+import { ApprovalEngine, weekendCalendar } from 'hierarchical-approval';
+
+const engine = new ApprovalEngine({
+  adapter,
+  calendar: weekendCalendar({
+    holidays: [new Date('2026-12-25'), new Date('2027-01-01')],
+    // weekendDays: [5, 6], // optional — e.g. Fri/Sat weekend
+  }),
+});
+```
+
+With this calendar, a level whose `escalationAfterDays: 2` is submitted on a Friday becomes due the following Tuesday rather than Sunday. Provide your own `BusinessCalendar` implementation for region-specific rules.
+
 ### Cancel
 
 ```ts
@@ -535,6 +621,20 @@ const result = await engine.canApprove(instanceId, 'mgr-1');
 
 Never throws — always returns a structured result.
 
+### Statistics
+
+Aggregate counts for dashboards. Pass an optional filter (`documentType`, `submittedBy`, `fromDate`/`toDate`) to scope the numbers; `status` is ignored since every status is counted.
+
+```ts
+const stats = await engine.getStatistics({ documentType: 'purchase_order' });
+// {
+//   total: number,
+//   byStatus: { pending, approved, rejected, cancelled, expired },
+//   overdue: number,        // pending past an escalation/expiry deadline
+//   approvalRate: number,   // approved / (approved + rejected); 0 when none resolved
+// }
+```
+
 ### Health check
 
 ```ts
@@ -567,6 +667,7 @@ engine.on('approval:approved',       (payload) => { /* level or fully approved *
 engine.on('approval:rejected',       (payload) => { /* level rejected */ });
 engine.on('approval:level_advanced', (payload) => { /* moved to next level */ });
 engine.on('approval:delegated',      (payload) => { /* approver delegated */ });
+engine.on('approval:reassigned',     (payload) => { /* approver reassigned by admin */ });
 engine.on('approval:escalated',      (payload) => { /* escalated to new approver */ });
 engine.on('approval:cancelled',      (payload) => { /* cancelled */ });
 engine.on('approval:expired',        (payload) => { /* deadline passed */ });
@@ -681,7 +782,7 @@ import { ApprovalForbiddenError } from 'hierarchical-approval';
 
 class SigningAuthorityPolicy implements IAuthorizationPolicy {
   async authorize(ctx: AuthorizationContext): Promise<string | undefined> {
-    // ctx.operation — 'approve' | 'reject' | 'delegate' | 'cancel' | 'escalate'
+    // ctx.operation — 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate'
     //               | 'override' | 'resubmit' | 'addComment' | 'submit'
     // ctx.actorId   — who is performing the action
     // ctx.instance  — current instance (read-only)
@@ -956,7 +1057,10 @@ interface ApprovalLevelConfig {
   level: number;                        // execution order (must be unique within template)
   name: string;                         // display name
   approvers: ApproverConfig[];          // at least one required
-  mode: 'any' | 'all' | 'majority';
+  mode: 'any' | 'all' | 'majority' | 'quorum' | 'weighted';
+  minApprovals?: number;                // required when mode is 'quorum' (N-of-M threshold)
+  threshold?: number;                   // required when mode is 'weighted' (cumulative weight to pass)
+  weights?: Record<string, number>;     // optional per-approver weights for 'weighted'; default 1
   escalationAfterDays?: number;         // per-level escalation (overrides template.escalation timing)
 }
 ```

package/dist/{ApprovalEngine-DdZtyeB5.d.ts → ApprovalEngine-CSxLWZ5h.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as AuditEntry, g as ApprovalLevelInstance, I as IStorageAdapter, q as ResolverFn, j as ApprovalTemplateConfig, A as ApprovalTemplate, m as AuditContext, h as ApprovalMode, P as PaginationOpts, b as PaginatedResult, c as InstanceFilter, C as CursorPaginationOpts, e as CursorPaginatedResult } from './IStorageAdapter-RAiLF8bc.js';
+import { a as ApprovalInstance, d as AuditEntry, g as ApprovalLevelInstance, I as IStorageAdapter, q as ResolverFn, j as ApprovalTemplateConfig, A as ApprovalTemplate, m as AuditContext, h as ApprovalMode, P as PaginationOpts, b as PaginatedResult, c as InstanceFilter, C as CursorPaginationOpts, e as CursorPaginatedResult } from './IStorageAdapter-B2xGuaKi.cjs';
 import { z } from 'zod';
 
 interface ApprovalEvent {
@@ -29,6 +29,13 @@ interface DelegatedEvent extends ApprovalEvent {
     level: number;
     reason: string;
 }
+interface ReassignedEvent extends ApprovalEvent {
+    reassignedBy: string;
+    fromApprover: string;
+    toApprover: string;
+    level: number;
+    reason: string;
+}
 interface EscalatedEvent extends ApprovalEvent {
     level: number;
     escalatedTo: string;
@@ -61,6 +68,7 @@ interface ApprovalEventMap {
     'approval:approved': ApprovedEvent;
     'approval:rejected': RejectedEvent;
     'approval:delegated': DelegatedEvent;
+    'approval:reassigned': ReassignedEvent;
     'approval:escalated': EscalatedEvent;
     'approval:cancelled': CancelledEvent;
     'approval:completed': ApprovalInstance;
@@ -106,6 +114,12 @@ declare const DelegateOptionsSchema: z.ZodObject<{
     reason: z.ZodString;
     until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
 }, z.core.$strip>;
+declare const ReassignOptionsSchema: z.ZodObject<{
+    reassignedBy: z.ZodString;
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
 declare const CancelOptionsSchema: z.ZodObject<{
     cancelledBy: z.ZodString;
     reason: z.ZodString;
@@ -130,6 +144,7 @@ type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
 type DelegateOptions = z.infer<typeof DelegateOptionsSchema>;
+type ReassignOptions = z.infer<typeof ReassignOptionsSchema>;
 type CancelOptions = z.infer<typeof CancelOptionsSchema>;
 type EscalateOptions = z.infer<typeof EscalateOptionsSchema>;
 type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
@@ -149,6 +164,36 @@ interface Clock {
 }
 declare const systemClock: Clock;
 
+/**
+ * Computes deadline dates from a number of days. The default engine behaviour
+ * treats day offsets (escalationAfterDays, slaDeadlineDays) as plain calendar
+ * days; provide a BusinessCalendar on ApprovalEngine to interpret them as
+ * business days instead — skipping weekends and configured holidays.
+ */
+interface BusinessCalendar {
+    /**
+     * Return the date that is `days` business days after `from`. A fractional
+     * `days` adds whole business days first, then the remaining fraction as
+     * elapsed clock time within the resulting business day.
+     */
+    addBusinessDays(from: Date, days: number): Date;
+}
+interface WeekendCalendarOptions {
+    /** Dates to treat as non-working days (compared by local calendar date). */
+    holidays?: Date[];
+    /**
+     * Weekday numbers (0 = Sunday … 6 = Saturday) that count as weekend.
+     * Defaults to [0, 6]. Override for regions with different work weeks
+     * (e.g. [5, 6] for a Friday/Saturday weekend).
+     */
+    weekendDays?: number[];
+}
+/**
+ * A calendar that skips weekends (Sat/Sun by default) and any supplied
+ * holidays. Day arithmetic is performed in the host's local timezone.
+ */
+declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
+
 type IdGeneratorFn = (prefix: 'inst' | 'tpl') => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -224,7 +269,7 @@ interface IAuditAdapter {
     append(tenantId: string, instanceId: string, entry: AuditEntry, instance: Readonly<ApprovalInstance>): Promise<void>;
 }
 
-type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.overridden' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
+type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;
@@ -245,7 +290,7 @@ interface ISchedulerAdapter {
 }
 
 interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
     actorId: string;
     instance: Readonly<ApprovalInstance>;
     level?: Readonly<ApprovalLevelInstance>;
@@ -306,6 +351,16 @@ interface BulkResult {
     }>;
     total: number;
 }
+interface ApprovalStatistics {
+    /** Total instances matching the filter (across all statuses). */
+    total: number;
+    /** Count per status. */
+    byStatus: Record<ApprovalInstance['status'], number>;
+    /** Instances still pending past their escalation/expiry deadline. */
+    overdue: number;
+    /** approved / (approved + rejected); 0 when nothing has been resolved. */
+    approvalRate: number;
+}
 interface HealthResult {
     status: 'healthy' | 'degraded' | 'unhealthy';
     adapter: 'connected' | 'error';
@@ -331,6 +386,12 @@ interface ApprovalEngineOptions {
     maxBulkItems?: number;
     /** Injectable clock — defaults to system clock. Enables deterministic tests and custom time sources. */
     clock?: Clock;
+    /**
+     * Optional business-day calendar. When provided, escalationAfterDays and
+     * slaDeadlineDays are interpreted as business days (skipping weekends and
+     * holidays) instead of plain calendar days. See weekendCalendar().
+     */
+    calendar?: BusinessCalendar;
     /** Custom ID generator for instances and templates. Defaults to timestamp+random. */
     generateId?: IdGeneratorFn;
     /** Custom optimistic locking retry policy. */
@@ -359,6 +420,7 @@ declare class ApprovalEngine {
     private readonly tenantId;
     private readonly logger;
     private readonly clock;
+    private readonly calendar?;
     private readonly generateId;
     private readonly maxBulkItems;
     private readonly retryPolicy;
@@ -380,6 +442,14 @@ declare class ApprovalEngine {
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
+    /**
+     * Administratively replace an approver on the current level. Unlike delegate(),
+     * this is performed by a third party (e.g. an admin handling an unavailable
+     * approver) and does not require the original approver to initiate it. The
+     * target approver must still be pending — an approver who has already acted
+     * cannot be reassigned.
+     */
+    reassign(instanceId: string, raw: ReassignOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     cancel(instanceId: string, raw: CancelOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     escalate(instanceId: string, raw: EscalateOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /** Add a comment to an instance without approving or rejecting. */
@@ -404,6 +474,12 @@ declare class ApprovalEngine {
     getCurrentApprovers(instanceId: string): Promise<string[]>;
     /** Check adapter connectivity and escalation scheduler health. */
     healthCheck(): Promise<HealthResult>;
+    /**
+     * Aggregate counts for dashboards. Accepts an optional filter (documentType,
+     * submittedBy, date range) — `status` is ignored since every status is counted.
+     * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
+     */
+    getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     private escalateInternal;
     private expireInstance;
@@ -411,6 +487,8 @@ declare class ApprovalEngine {
     private revertDelegation;
     /** Read-modify-write with optimistic locking retry. */
     private withOptimisticRetry;
+    /** Compute a deadline `days` from `from`, honouring the business calendar if one is configured. */
+    private deadlineFrom;
     private requireInstance;
     private currentLevelInstance;
     private findNextLevel;
@@ -423,4 +501,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type SubmitOptions as $, type AddCommentOptions as A, type BulkResult as B, type Clock as C, type DelegateOptions as D, type EscalateOptions as E, type IOperationMiddleware as F, type ISchedulerAdapter as G, type HealthResult as H, type IAuditAdapter as I, type IdGeneratorFn as J, type IdempotencyKeyFn as K, type Logger as L, type LevelAdvancedEvent as M, type MetricName as N, type NotificationEvent as O, type OperationContext as P, type OrgProvider as Q, type OverriddenEvent as R, type OverrideOptions as S, type PreviewChainLevel as T, type PreviewResult as U, type RejectOptions as V, type RejectedEvent as W, type ResubmitOptions as X, type ResubmittedEvent as Y, type RetryPolicy as Z, type SlaBreachedEvent as _, ApprovalConflictError as a, type SubmittedEvent as a0, type ValidationResult as a1, defaultIdGenerator as a2, noopLogger as a3, systemClock as a4, ApprovalEngine as b, type ApprovalEngineOptions as c, ApprovalError as d, type ApprovalEvent as e, type ApprovalEventMap as f, type ApprovalEventName as g, ApprovalForbiddenError as h, ApprovalNotFoundError as i, ApprovalTemplateNotFoundError as j, ApprovalValidationError as k, type ApproveOptions as l, type ApprovedEvent as m, type ApproverResolverFn as n, type AuthorizationContext as o, type CanApproveResult as p, type CancelOptions as q, type CancelledEvent as r, type ConditionOperatorFn as s, type DelegatedEvent as t, type EscalatedEvent as u, type ExpiredEvent as v, type HistoryEntry as w, type IAuthorizationPolicy as x, type IMetricsAdapter as y, type INotificationAdapter as z };
+export { type ResubmitOptions as $, type AddCommentOptions as A, type BulkResult as B, type Clock as C, type DelegateOptions as D, type EscalateOptions as E, type IMetricsAdapter as F, type INotificationAdapter as G, type HealthResult as H, type IAuditAdapter as I, type IOperationMiddleware as J, type ISchedulerAdapter as K, type Logger as L, type IdGeneratorFn as M, type IdempotencyKeyFn as N, type LevelAdvancedEvent as O, type MetricName as P, type NotificationEvent as Q, type OperationContext as R, type OrgProvider as S, type OverriddenEvent as T, type OverrideOptions as U, type PreviewChainLevel as V, type PreviewResult as W, type ReassignOptions as X, type ReassignedEvent as Y, type RejectOptions as Z, type RejectedEvent as _, ApprovalConflictError as a, type ResubmittedEvent as a0, type RetryPolicy as a1, type SlaBreachedEvent as a2, type SubmitOptions as a3, type SubmittedEvent as a4, type ValidationResult as a5, type WeekendCalendarOptions as a6, defaultIdGenerator as a7, noopLogger as a8, systemClock as a9, weekendCalendar as aa, ApprovalEngine as b, type ApprovalEngineOptions as c, ApprovalError as d, type ApprovalEvent as e, type ApprovalEventMap as f, type ApprovalEventName as g, ApprovalForbiddenError as h, ApprovalNotFoundError as i, type ApprovalStatistics as j, ApprovalTemplateNotFoundError as k, ApprovalValidationError as l, type ApproveOptions as m, type ApprovedEvent as n, type ApproverResolverFn as o, type AuthorizationContext as p, type BusinessCalendar as q, type CanApproveResult as r, type CancelOptions as s, type CancelledEvent as t, type ConditionOperatorFn as u, type DelegatedEvent as v, type EscalatedEvent as w, type ExpiredEvent as x, type HistoryEntry as y, type IAuthorizationPolicy as z };

package/dist/{ApprovalEngine-BcnLzfAU.d.cts → ApprovalEngine-DICBgdIp.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as AuditEntry, g as ApprovalLevelInstance, I as IStorageAdapter, q as ResolverFn, j as ApprovalTemplateConfig, A as ApprovalTemplate, m as AuditContext, h as ApprovalMode, P as PaginationOpts, b as PaginatedResult, c as InstanceFilter, C as CursorPaginationOpts, e as CursorPaginatedResult } from './IStorageAdapter-RAiLF8bc.cjs';
+import { a as ApprovalInstance, d as AuditEntry, g as ApprovalLevelInstance, I as IStorageAdapter, q as ResolverFn, j as ApprovalTemplateConfig, A as ApprovalTemplate, m as AuditContext, h as ApprovalMode, P as PaginationOpts, b as PaginatedResult, c as InstanceFilter, C as CursorPaginationOpts, e as CursorPaginatedResult } from './IStorageAdapter-B2xGuaKi.js';
 import { z } from 'zod';
 
 interface ApprovalEvent {
@@ -29,6 +29,13 @@ interface DelegatedEvent extends ApprovalEvent {
     level: number;
     reason: string;
 }
+interface ReassignedEvent extends ApprovalEvent {
+    reassignedBy: string;
+    fromApprover: string;
+    toApprover: string;
+    level: number;
+    reason: string;
+}
 interface EscalatedEvent extends ApprovalEvent {
     level: number;
     escalatedTo: string;
@@ -61,6 +68,7 @@ interface ApprovalEventMap {
     'approval:approved': ApprovedEvent;
     'approval:rejected': RejectedEvent;
     'approval:delegated': DelegatedEvent;
+    'approval:reassigned': ReassignedEvent;
     'approval:escalated': EscalatedEvent;
     'approval:cancelled': CancelledEvent;
     'approval:completed': ApprovalInstance;
@@ -106,6 +114,12 @@ declare const DelegateOptionsSchema: z.ZodObject<{
     reason: z.ZodString;
     until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
 }, z.core.$strip>;
+declare const ReassignOptionsSchema: z.ZodObject<{
+    reassignedBy: z.ZodString;
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
 declare const CancelOptionsSchema: z.ZodObject<{
     cancelledBy: z.ZodString;
     reason: z.ZodString;
@@ -130,6 +144,7 @@ type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
 type DelegateOptions = z.infer<typeof DelegateOptionsSchema>;
+type ReassignOptions = z.infer<typeof ReassignOptionsSchema>;
 type CancelOptions = z.infer<typeof CancelOptionsSchema>;
 type EscalateOptions = z.infer<typeof EscalateOptionsSchema>;
 type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
@@ -149,6 +164,36 @@ interface Clock {
 }
 declare const systemClock: Clock;
 
+/**
+ * Computes deadline dates from a number of days. The default engine behaviour
+ * treats day offsets (escalationAfterDays, slaDeadlineDays) as plain calendar
+ * days; provide a BusinessCalendar on ApprovalEngine to interpret them as
+ * business days instead — skipping weekends and configured holidays.
+ */
+interface BusinessCalendar {
+    /**
+     * Return the date that is `days` business days after `from`. A fractional
+     * `days` adds whole business days first, then the remaining fraction as
+     * elapsed clock time within the resulting business day.
+     */
+    addBusinessDays(from: Date, days: number): Date;
+}
+interface WeekendCalendarOptions {
+    /** Dates to treat as non-working days (compared by local calendar date). */
+    holidays?: Date[];
+    /**
+     * Weekday numbers (0 = Sunday … 6 = Saturday) that count as weekend.
+     * Defaults to [0, 6]. Override for regions with different work weeks
+     * (e.g. [5, 6] for a Friday/Saturday weekend).
+     */
+    weekendDays?: number[];
+}
+/**
+ * A calendar that skips weekends (Sat/Sun by default) and any supplied
+ * holidays. Day arithmetic is performed in the host's local timezone.
+ */
+declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
+
 type IdGeneratorFn = (prefix: 'inst' | 'tpl') => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -224,7 +269,7 @@ interface IAuditAdapter {
     append(tenantId: string, instanceId: string, entry: AuditEntry, instance: Readonly<ApprovalInstance>): Promise<void>;
 }
 
-type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.overridden' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
+type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;
@@ -245,7 +290,7 @@ interface ISchedulerAdapter {
 }
 
 interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
     actorId: string;
     instance: Readonly<ApprovalInstance>;
     level?: Readonly<ApprovalLevelInstance>;
@@ -306,6 +351,16 @@ interface BulkResult {
     }>;
     total: number;
 }
+interface ApprovalStatistics {
+    /** Total instances matching the filter (across all statuses). */
+    total: number;
+    /** Count per status. */
+    byStatus: Record<ApprovalInstance['status'], number>;
+    /** Instances still pending past their escalation/expiry deadline. */
+    overdue: number;
+    /** approved / (approved + rejected); 0 when nothing has been resolved. */
+    approvalRate: number;
+}
 interface HealthResult {
     status: 'healthy' | 'degraded' | 'unhealthy';
     adapter: 'connected' | 'error';
@@ -331,6 +386,12 @@ interface ApprovalEngineOptions {
     maxBulkItems?: number;
     /** Injectable clock — defaults to system clock. Enables deterministic tests and custom time sources. */
     clock?: Clock;
+    /**
+     * Optional business-day calendar. When provided, escalationAfterDays and
+     * slaDeadlineDays are interpreted as business days (skipping weekends and
+     * holidays) instead of plain calendar days. See weekendCalendar().
+     */
+    calendar?: BusinessCalendar;
     /** Custom ID generator for instances and templates. Defaults to timestamp+random. */
     generateId?: IdGeneratorFn;
     /** Custom optimistic locking retry policy. */
@@ -359,6 +420,7 @@ declare class ApprovalEngine {
     private readonly tenantId;
     private readonly logger;
     private readonly clock;
+    private readonly calendar?;
     private readonly generateId;
     private readonly maxBulkItems;
     private readonly retryPolicy;
@@ -380,6 +442,14 @@ declare class ApprovalEngine {
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
+    /**
+     * Administratively replace an approver on the current level. Unlike delegate(),
+     * this is performed by a third party (e.g. an admin handling an unavailable
+     * approver) and does not require the original approver to initiate it. The
+     * target approver must still be pending — an approver who has already acted
+     * cannot be reassigned.
+     */
+    reassign(instanceId: string, raw: ReassignOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     cancel(instanceId: string, raw: CancelOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     escalate(instanceId: string, raw: EscalateOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /** Add a comment to an instance without approving or rejecting. */
@@ -404,6 +474,12 @@ declare class ApprovalEngine {
     getCurrentApprovers(instanceId: string): Promise<string[]>;
     /** Check adapter connectivity and escalation scheduler health. */
     healthCheck(): Promise<HealthResult>;
+    /**
+     * Aggregate counts for dashboards. Accepts an optional filter (documentType,
+     * submittedBy, date range) — `status` is ignored since every status is counted.
+     * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
+     */
+    getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     private escalateInternal;
     private expireInstance;
@@ -411,6 +487,8 @@ declare class ApprovalEngine {
     private revertDelegation;
     /** Read-modify-write with optimistic locking retry. */
     private withOptimisticRetry;
+    /** Compute a deadline `days` from `from`, honouring the business calendar if one is configured. */
+    private deadlineFrom;
     private requireInstance;
     private currentLevelInstance;
     private findNextLevel;
@@ -423,4 +501,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type SubmitOptions as $, type AddCommentOptions as A, type BulkResult as B, type Clock as C, type DelegateOptions as D, type EscalateOptions as E, type IOperationMiddleware as F, type ISchedulerAdapter as G, type HealthResult as H, type IAuditAdapter as I, type IdGeneratorFn as J, type IdempotencyKeyFn as K, type Logger as L, type LevelAdvancedEvent as M, type MetricName as N, type NotificationEvent as O, type OperationContext as P, type OrgProvider as Q, type OverriddenEvent as R, type OverrideOptions as S, type PreviewChainLevel as T, type PreviewResult as U, type RejectOptions as V, type RejectedEvent as W, type ResubmitOptions as X, type ResubmittedEvent as Y, type RetryPolicy as Z, type SlaBreachedEvent as _, ApprovalConflictError as a, type SubmittedEvent as a0, type ValidationResult as a1, defaultIdGenerator as a2, noopLogger as a3, systemClock as a4, ApprovalEngine as b, type ApprovalEngineOptions as c, ApprovalError as d, type ApprovalEvent as e, type ApprovalEventMap as f, type ApprovalEventName as g, ApprovalForbiddenError as h, ApprovalNotFoundError as i, ApprovalTemplateNotFoundError as j, ApprovalValidationError as k, type ApproveOptions as l, type ApprovedEvent as m, type ApproverResolverFn as n, type AuthorizationContext as o, type CanApproveResult as p, type CancelOptions as q, type CancelledEvent as r, type ConditionOperatorFn as s, type DelegatedEvent as t, type EscalatedEvent as u, type ExpiredEvent as v, type HistoryEntry as w, type IAuthorizationPolicy as x, type IMetricsAdapter as y, type INotificationAdapter as z };
+export { type ResubmitOptions as $, type AddCommentOptions as A, type BulkResult as B, type Clock as C, type DelegateOptions as D, type EscalateOptions as E, type IMetricsAdapter as F, type INotificationAdapter as G, type HealthResult as H, type IAuditAdapter as I, type IOperationMiddleware as J, type ISchedulerAdapter as K, type Logger as L, type IdGeneratorFn as M, type IdempotencyKeyFn as N, type LevelAdvancedEvent as O, type MetricName as P, type NotificationEvent as Q, type OperationContext as R, type OrgProvider as S, type OverriddenEvent as T, type OverrideOptions as U, type PreviewChainLevel as V, type PreviewResult as W, type ReassignOptions as X, type ReassignedEvent as Y, type RejectOptions as Z, type RejectedEvent as _, ApprovalConflictError as a, type ResubmittedEvent as a0, type RetryPolicy as a1, type SlaBreachedEvent as a2, type SubmitOptions as a3, type SubmittedEvent as a4, type ValidationResult as a5, type WeekendCalendarOptions as a6, defaultIdGenerator as a7, noopLogger as a8, systemClock as a9, weekendCalendar as aa, ApprovalEngine as b, type ApprovalEngineOptions as c, ApprovalError as d, type ApprovalEvent as e, type ApprovalEventMap as f, type ApprovalEventName as g, ApprovalForbiddenError as h, ApprovalNotFoundError as i, type ApprovalStatistics as j, ApprovalTemplateNotFoundError as k, ApprovalValidationError as l, type ApproveOptions as m, type ApprovedEvent as n, type ApproverResolverFn as o, type AuthorizationContext as p, type BusinessCalendar as q, type CanApproveResult as r, type CancelOptions as s, type CancelledEvent as t, type ConditionOperatorFn as u, type DelegatedEvent as v, type EscalatedEvent as w, type ExpiredEvent as x, type HistoryEntry as y, type IAuthorizationPolicy as z };

package/dist/{IStorageAdapter-RAiLF8bc.d.cts → IStorageAdapter-B2xGuaKi.d.cts}

@@ -19,7 +19,7 @@ interface ResolvedApprover {
 }
 type ResolverFn = (submittedBy: string, data: Record<string, unknown>) => Promise<string> | string;
 
-type ApprovalMode = 'all' | 'any' | 'majority';
+type ApprovalMode = 'all' | 'any' | 'majority' | 'quorum' | 'weighted';
 /** Built-in operators. Use engine.registerConditionOperator() to add custom ones. */
 type ConditionOperator = '>' | '<' | '>=' | '<=' | '==' | '!=' | 'in' | 'not_in' | (string & {});
 interface Condition {
@@ -33,6 +33,23 @@ interface ApprovalLevelConfig {
     approvers: ApproverConfig[];
     mode: ApprovalMode;
     escalationAfterDays?: number;
+    /**
+     * Required when mode is 'quorum'. The minimum number of approvals needed to
+     * pass this level (an N-of-M threshold). The level is rejected as soon as it
+     * becomes impossible to reach this count.
+     */
+    minApprovals?: number;
+    /**
+     * Required when mode is 'weighted'. The cumulative approver weight needed to
+     * pass this level. The level is rejected once the remaining achievable weight
+     * can no longer reach this threshold.
+     */
+    threshold?: number;
+    /**
+     * Optional per-approver voting weights for 'weighted' mode, keyed by approver
+     * id. Approvers not listed default to a weight of 1.
+     */
+    weights?: Record<string, number>;
 }
 interface ConditionRule {
     when: Condition | Condition[];
@@ -66,7 +83,7 @@ interface ApprovalTemplate extends ApprovalTemplateConfig {
 
 type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
 type LevelStatus = 'waiting' | 'pending' | 'approved' | 'rejected' | 'skipped';
-type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'expired';
+type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'expired';
 interface AuditEntry {
     action: AuditAction;
     actorId: string;
@@ -98,6 +115,12 @@ interface ApprovalLevelInstance {
     approvedBy: string[];
     rejectedBy: string[];
     status: LevelStatus;
+    /** Minimum approvals required to pass this level (set when mode is 'quorum'). */
+    minApprovals?: number;
+    /** Cumulative approver weight required to pass this level (set when mode is 'weighted'). */
+    threshold?: number;
+    /** Per-approver voting weights for 'weighted' mode; unlisted approvers default to 1. */
+    weights?: Record<string, number>;
     escalationDueAt?: Date;
     escalationAfterDays?: number;
     /** Set when a delegation has a time limit — the original approver is restored when this date passes. */