hierarchical-approval 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to `hierarchical-approval` are documented here. This project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.1] - 2026-06-26
+
+### Docs
+
+- Replace the README's Mermaid code blocks with pre-rendered PNG diagrams
+  referenced by absolute URL, so the status lifecycle, approval flow, and
+  architecture diagrams render on npmjs.com (which does not render Mermaid) as
+  well as on GitHub.
+
+## [0.3.0] - 2026-06-26
+
+### Added — enterprise plug-in layer
+
+Production-grade implementations of the existing engine extension points, each
+published on its own tree-shakeable import subpath with **zero runtime
+dependencies** (Node.js built-ins only). The core engine is unchanged.
+
+- **`hierarchical-approval/plugins/audit`**
+  - `HashChainAuditAdapter` — SHA-256 hash-chained, tamper-evident audit log.
+    `verify()` detects content tampering, deletion, reordering, **and tail
+    truncation** (via an in-process high-water mark or an explicit
+    `expectedLength` anchor). Pluggable writer/reader; in-memory by default.
+  - `RedactingAuditAdapter` — redacts configured PII field paths and free-text
+    fields before forwarding to a wrapped adapter; original entries are never
+    mutated.
+  - `CompositeAuditAdapter` — fan out to multiple audit sinks with per-child
+    fault isolation. Never throws.
+- **`hierarchical-approval/plugins/metrics`**
+  - `PrometheusMetricsAdapter` — accumulates counters/histograms and renders
+    `scrape()` in Prometheus text exposition format.
+  - `InMemoryMetricsAdapter` — `snapshot()` with count/sum/min/max/avg/p50/p95;
+    O(1) ring-buffer sample retention.
+  - `CompositeMetricsAdapter` — fan out to multiple metrics backends.
+- **`hierarchical-approval/plugins/resilience`**
+  - `RbacAuthorizationPolicy` — per-operation role rules with a default-deny
+    posture and a pluggable role provider.
+  - `CompositeAuthorizationPolicy` — combine policies with AND/OR semantics.
+  - `RateLimitMiddleware` — token-bucket throttling keyed per actor + operation,
+    with an injectable clock.
+  - `LoggingMiddleware` — structured before/after/onError logging with timings.
+- **`hierarchical-approval/plugins/notify`**
+  - `OutboxNotificationAdapter` — transactional outbox with retry, exponential
+    backoff, and a dead-letter queue for at-least-once delivery. Exposes
+    `drain()`, `pending()`, and `deadLettered()`.
+  - `TemplatedNotificationAdapter` — render a human-readable message per event
+    type via a configurable template map.
+  - `CompositeNotificationAdapter` — multi-channel fan-out with fault isolation.
+
+### Changed
+
+- `package.json` `exports` and the build now expose the four `plugins/*`
+  subpaths in ESM, CJS, and `.d.ts`.
+
+### Tests
+
+- Test suite grew from 196 to 380 passing tests covering the new plug-ins
+  (tamper detection, backoff/dead-letter, rate-limit math, RBAC, PII redaction,
+  Prometheus exposition, and the public-export surface).
+
+## [0.2.1] - 2026-06-23
+
+- Documentation and tooling fixes; audit-log de-duplication in `MemoryAdapter`.
+
+## [0.2.0] - 2026-06-23
+
+- Advanced decision modes (`quorum`, `weighted`), `reassign()`, `getStatistics()`,
+  and an injectable `BusinessCalendar`.
+
+## [0.1.1] - 2026-06-21
+
+- Initial published release line.

package/README.md

@@ -97,19 +97,9 @@ Approval workflows are deceptively simple until they aren't. Most teams start wi
 
 ### The status lifecycle
 
-```mermaid
-stateDiagram-v2
-    [*] --> pending
-    pending --> pending: approve advances a level
-    pending --> approved: final level or override
-    pending --> rejected: reject
-    pending --> cancelled: cancel
-    pending --> expired: deadline reached
-    approved --> [*]
-    rejected --> [*]
-    cancelled --> [*]
-    expired --> [*]
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/matthews-wong/hierarchical-approval/main/assets/diagrams/lifecycle.png" alt="Status lifecycle: pending advances on approve, and resolves to approved, rejected, cancelled, or expired." width="640">
+</p>
 
 > `submit()` creates the instance in `pending`; `resubmit()` on a rejected instance spawns a new linked instance starting again at level 1.
 
@@ -117,20 +107,9 @@ stateDiagram-v2
 
 A level is satisfied according to its mode (`any`, `all`, `majority`, `quorum`, or `weighted`):
 
-```mermaid
-flowchart TD
-    S[Submit] --> R[Resolve approvers for current level]
-    R --> ACT{An approver acts}
-    ACT -->|approve| MET{Level threshold met}
-    ACT -->|reject| REJ{Level rejected}
-    MET -->|not yet| ACT
-    MET -->|yes| MORE{More levels}
-    MORE -->|yes| ADV[Advance to next level]
-    ADV --> R
-    MORE -->|no| DONE[Status approved]
-    REJ -->|yes| OUT[Status rejected]
-    REJ -->|no| ACT
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/matthews-wong/hierarchical-approval/main/assets/diagrams/flow.png" alt="Approval flow: submit, resolve approvers, approvers act; when the level threshold is met advance to the next level or complete; rejection ends the instance." width="380">
+</p>
 
 ### Architecture — a small core with pluggable ports
 
@@ -138,17 +117,9 @@ The engine never talks to your database, queue, or notification service directly
 
 Solid arrow = required (storage). Dotted arrows = optional ports you can plug in:
 
-```mermaid
-flowchart LR
-    APP[Your application] --> ENG[ApprovalEngine]
-    ENG --> ST[IStorageAdapter - Memory, Postgres or custom]
-    ENG -.-> NO[INotificationAdapter]
-    ENG -.-> AU[IAuditAdapter]
-    ENG -.-> ME[IMetricsAdapter]
-    ENG -.-> SC[ISchedulerAdapter]
-    ENG -.-> AZ[IAuthorizationPolicy]
-    ENG -.-> MW[IOperationMiddleware]
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/matthews-wong/hierarchical-approval/main/assets/diagrams/architecture.png" alt="Architecture: your application calls ApprovalEngine, which requires an IStorageAdapter (Memory, Postgres, or custom) and optionally plugs into notification, audit, metrics, scheduler, authorization, and middleware ports." width="560">
+</p>
 
 ---
 
@@ -932,6 +903,109 @@ Middleware errors are caught and logged — they never propagate to callers.
 
 ---
 
+## Built-in enterprise plug-ins
+
+The interfaces above are ports. The library also ships production-grade implementations of them, each on its own import subpath so you only pull in what you use (fully tree-shakeable, zero extra dependencies — `node:crypto` only).
+
+### `plugins/audit` — tamper-evident & PII-safe audit
+
+```ts
+import {
+  HashChainAuditAdapter,
+  RedactingAuditAdapter,
+  CompositeAuditAdapter,
+} from 'hierarchical-approval/plugins/audit';
+
+// Each entry is SHA-256-chained to the previous one (per tenant+instance).
+const chain = new HashChainAuditAdapter();
+
+// Redact PII before it reaches external sinks (originals are never mutated).
+const redacted = new RedactingAuditAdapter({
+  inner: chain,
+  fieldPaths: ['newValue.applicant.ssn', 'newValue.card.*'],
+  freeTextFields: ['comment', 'reason'],
+});
+
+const engine = new ApprovalEngine({ adapter, auditAdapter: redacted });
+
+// Later — prove the log was not altered, deleted, or reordered:
+const result = chain.verify(tenantId, instanceId);
+// { ok: true } | { ok: false, brokenAt: <seq> }
+```
+
+`verify()` detects content tampering, deletion, reordering, **and tail truncation** (via an in-process high-water mark, or an explicit `expectedLength` anchor that survives restarts). Use `CompositeAuditAdapter` to fan out to several sinks (Kafka, S3, CloudTrail) with per-child fault isolation.
+
+### `plugins/metrics` — Prometheus & dashboards
+
+```ts
+import {
+  PrometheusMetricsAdapter,
+  InMemoryMetricsAdapter,
+} from 'hierarchical-approval/plugins/metrics';
+
+const metrics = new PrometheusMetricsAdapter();
+const engine = new ApprovalEngine({ adapter, metricsAdapter: metrics });
+
+// Expose on /metrics:
+res.type('text/plain').send(metrics.scrape()); // valid Prometheus exposition format
+```
+
+`InMemoryMetricsAdapter.snapshot()` returns counters and timing stats (count/sum/min/max/avg/p50/p95) for dashboards and tests; `CompositeMetricsAdapter` feeds both at once.
+
+### `plugins/resilience` — RBAC, rate limiting, structured logging
+
+```ts
+import {
+  RbacAuthorizationPolicy,
+  CompositeAuthorizationPolicy,
+  RateLimitMiddleware,
+  LoggingMiddleware,
+} from 'hierarchical-approval/plugins/resilience';
+
+const engine = new ApprovalEngine({
+  adapter,
+  authorizationPolicy: new RbacAuthorizationPolicy({
+    defaultMode: 'deny', // closed by default — unlisted operations are denied
+    rules: {
+      approve: { roles: ['manager', 'director'] }, // match: 'any' by default
+      override: { roles: ['admin'] },
+    },
+    roleProvider: (actorId, tenantId) => roleStore.rolesFor(actorId, tenantId),
+  }),
+  middleware: [
+    new RateLimitMiddleware({ capacity: 20, refillTokensPerSecond: 5 }), // token bucket per actor+op
+    new LoggingMiddleware({ logger }),
+  ],
+});
+```
+
+`CompositeAuthorizationPolicy` combines policies with AND (first denial wins) or OR (any allow) semantics.
+
+### `plugins/notify` — reliable, multi-channel delivery
+
+```ts
+import {
+  OutboxNotificationAdapter,
+  TemplatedNotificationAdapter,
+  CompositeNotificationAdapter,
+} from 'hierarchical-approval/plugins/notify';
+
+// At-least-once delivery: transactional outbox + exponential backoff + dead-letter.
+const outbox = new OutboxNotificationAdapter({
+  transport: async (event) => emailGateway.send(event),
+  maxAttempts: 5,
+});
+
+const engine = new ApprovalEngine({ adapter, notificationAdapter: outbox });
+
+await outbox.drain();         // deliver due items (call from a worker/cron)
+await outbox.deadLettered();  // inspect permanently-failed events
+```
+
+`TemplatedNotificationAdapter` renders a human-readable message per event type; `CompositeNotificationAdapter` fans out to multiple channels with fault isolation.
+
+---
+
 ## Custom storage adapter
 
 Implement `IStorageAdapter` to use any database:

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

@@ -1,87 +1,12 @@
-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DbeWhtCG.cjs';
+import { m as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-D8D7b07N.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-DVVmXU6a.cjs';
 import { z } from 'zod';
-
-interface ApprovalEvent {
-    instanceId: string;
-    documentId: string;
-    documentType: string;
-    timestamp: Date;
-}
-interface SubmittedEvent extends ApprovalEvent {
-    submittedBy: string;
-    currentApprovers: string[];
-}
-interface ApprovedEvent extends ApprovalEvent {
-    approverId: string;
-    level: number;
-    comment?: string;
-    isFinal: boolean;
-}
-interface RejectedEvent extends ApprovalEvent {
-    approverId: string;
-    level: number;
-    reason: string;
-    returnTo: 'originator' | 'previous' | null;
-}
-interface DelegatedEvent extends ApprovalEvent {
-    fromApprover: string;
-    toApprover: string;
-    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;
-}
-interface CancelledEvent extends ApprovalEvent {
-    cancelledBy: string;
-    reason: string;
-}
-interface LevelAdvancedEvent extends ApprovalEvent {
-    fromLevel: number;
-    toLevel: number;
-    newApprovers: string[];
-}
-interface ResubmittedEvent extends ApprovalEvent {
-    resubmittedBy: string;
-    originalInstanceId: string;
-}
-interface OverriddenEvent extends ApprovalEvent {
-    overriddenBy: string;
-    justification: string;
-}
-interface ExpiredEvent extends ApprovalEvent {
-    deadlineAction: 'cancel' | 'reject';
-}
-interface SlaBreachedEvent extends ApprovalEvent {
-    slaDeadlineAt: Date;
-}
-interface ApprovalEventMap {
-    'approval:submitted': SubmittedEvent;
-    'approval:approved': ApprovedEvent;
-    'approval:rejected': RejectedEvent;
-    'approval:delegated': DelegatedEvent;
-    'approval:reassigned': ReassignedEvent;
-    'approval:escalated': EscalatedEvent;
-    'approval:cancelled': CancelledEvent;
-    'approval:completed': ApprovalInstance;
-    'approval:level_advanced': LevelAdvancedEvent;
-    'approval:resubmitted': ResubmittedEvent;
-    'approval:overridden': OverriddenEvent;
-    'approval:expired': ExpiredEvent;
-    'approval:sla_breached': SlaBreachedEvent;
-}
-type ApprovalEventName = keyof ApprovalEventMap;
-interface HistoryEntry extends AuditEntry {
-    instanceId: string;
-}
+import { L as Logger } from './Logger-CIzvalFc.cjs';
+import { C as Clock } from './Clock-3FnOczFJ.cjs';
+import { I as IAuthorizationPolicy, g as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CkRh93Wf.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-B_DhuPsU.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-D9PUz4tM.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -151,19 +76,6 @@ type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
 type AddCommentOptions = z.infer<typeof AddCommentOptionsSchema>;
 type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 
-interface Logger {
-    info(msg: string, context?: Record<string, unknown>): void;
-    warn(msg: string, context?: Record<string, unknown>): void;
-    error(msg: string, err?: unknown, context?: Record<string, unknown>): void;
-    debug(msg: string, context?: Record<string, unknown>): void;
-}
-declare const noopLogger: Logger;
-
-interface Clock {
-    now(): Date;
-}
-declare const systemClock: Clock;
-
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
  * treats day offsets (escalationAfterDays, slaDeadlineDays) as plain calendar
@@ -216,67 +128,6 @@ type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
 
 type ConditionOperatorFn = (actual: unknown, expected: unknown) => boolean;
 
-declare class ApprovalError extends Error {
-    readonly code: string;
-    constructor(message: string, code: string);
-    toJSON(): {
-        code: string;
-        message: string;
-        name: string;
-    };
-    toHttpStatus(): number;
-}
-declare class ApprovalNotFoundError extends ApprovalError {
-    constructor(resource: string, id: string);
-}
-declare class ApprovalConflictError extends ApprovalError {
-    constructor(instanceId: string);
-}
-declare class ApprovalForbiddenError extends ApprovalError {
-    constructor(message: string);
-}
-declare class ApprovalValidationError extends ApprovalError {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
-}
-declare class ApprovalTemplateNotFoundError extends ApprovalError {
-    constructor(name: string);
-}
-
-interface NotificationEvent {
-    type: ApprovalEventName;
-    instanceId: string;
-    documentId: string;
-    documentType: string;
-    timestamp: Date;
-    /** Current-level approver IDs; empty for non-level events (cancelled, expired, etc.). */
-    recipients: string[];
-    templateName: string;
-    tenantId: string;
-    payload: ApprovalEventMap[ApprovalEventName];
-}
-interface INotificationAdapter {
-    /** Called after every emitted approval event. Must not throw — errors are logged and swallowed. */
-    notify(event: NotificationEvent): Promise<void>;
-}
-
-interface IAuditAdapter {
-    /**
-     * Called after every state-mutating operation, in addition to the primary storage adapter.
-     * Intended for write-once sinks: Kafka, S3, CloudTrail, WORM stores.
-     * Must not throw — errors are logged and swallowed.
-     */
-    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.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;
-    /** Record a timing measurement in milliseconds. Synchronous — never awaited. */
-    timing(metric: MetricName, durationMs: number, labels?: Record<string, string>): void;
-}
-
 interface ISchedulerAdapter {
     /**
      * Schedule a one-shot callback to run at the given date.
@@ -289,38 +140,6 @@ interface ISchedulerAdapter {
     shutdown(): Promise<void>;
 }
 
-interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
-    actorId: string;
-    instance: Readonly<ApprovalInstance>;
-    level?: Readonly<ApprovalLevelInstance>;
-    opts: Record<string, unknown>;
-}
-interface IAuthorizationPolicy {
-    /**
-     * Return undefined to allow the operation.
-     * Return a non-empty string to deny — the engine throws ApprovalForbiddenError(message).
-     * Throwing ApprovalForbiddenError directly is also permitted.
-     */
-    authorize(ctx: AuthorizationContext): Promise<string | undefined> | string | undefined;
-}
-
-interface OperationContext<T = unknown> {
-    operation: string;
-    instanceId?: string;
-    actorId?: string;
-    tenantId: string;
-    input: T;
-}
-interface IOperationMiddleware {
-    /** Runs after authorization and input validation, before state mutations. */
-    before?(ctx: OperationContext): Promise<void> | void;
-    /** Runs after successful completion of the operation. */
-    after?(ctx: OperationContext, result: ApprovalInstance | void): Promise<void> | void;
-    /** Runs when an ApprovalError is thrown. Does not suppress the error. */
-    onError?(ctx: OperationContext, error: ApprovalError): Promise<void> | void;
-}
-
 interface ValidationResult {
     valid: boolean;
     errors: Array<{
@@ -501,4 +320,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-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 };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type ISchedulerAdapter as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type IdGeneratorFn as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, weekendCalendar as w };