hierarchical-approval 0.1.0

package/dist/ApprovalEngine-DdZtyeB5.d.ts

@@ -0,0 +1,426 @@
+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 { 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 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: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;
+}
+
+declare const SubmitOptionsSchema: z.ZodObject<{
+    templateName: z.ZodString;
+    documentId: z.ZodString;
+    documentType: z.ZodString;
+    submittedBy: z.ZodString;
+    data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    expiresAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    deadlineAction: z.ZodOptional<z.ZodEnum<{
+        cancel: "cancel";
+        reject: "reject";
+    }>>;
+}, z.core.$strip>;
+declare const ApproveOptionsSchema: z.ZodObject<{
+    approverId: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const RejectOptionsSchema: z.ZodObject<{
+    approverId: z.ZodString;
+    reason: z.ZodString;
+    returnTo: z.ZodOptional<z.ZodEnum<{
+        originator: "originator";
+        previous: "previous";
+    }>>;
+}, z.core.$strip>;
+declare const DelegateOptionsSchema: z.ZodObject<{
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    reason: z.ZodString;
+    until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+declare const CancelOptionsSchema: z.ZodObject<{
+    cancelledBy: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+declare const EscalateOptionsSchema: z.ZodObject<{
+    escalatedBy: z.ZodString;
+}, z.core.$strip>;
+declare const ResubmitOptionsSchema: z.ZodObject<{
+    resubmittedBy: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    updatedData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const AddCommentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    comment: z.ZodString;
+}, z.core.$strip>;
+declare const OverrideOptionsSchema: z.ZodObject<{
+    overriddenBy: z.ZodString;
+    justification: z.ZodString;
+}, z.core.$strip>;
+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 CancelOptions = z.infer<typeof CancelOptionsSchema>;
+type EscalateOptions = z.infer<typeof EscalateOptionsSchema>;
+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;
+
+type IdGeneratorFn = (prefix: 'inst' | 'tpl') => string;
+declare const defaultIdGenerator: IdGeneratorFn;
+
+interface OrgProvider {
+    getUsersByRole(role: string, tenantId?: string): Promise<string[]> | string[];
+    /** Optional: resolve users by department name. */
+    getUsersByDepartment?(dept: string, tenantId?: string): Promise<string[]> | string[];
+    /** Optional: resolve the direct manager of a user. */
+    getManagerOf?(userId: string, tenantId?: string): Promise<string | null> | string | null;
+    /** Optional: resolve the skip-level manager of a user. */
+    getSkipLevelManagerOf?(userId: string, tenantId?: string): Promise<string | null> | string | null;
+    /** Optional: resolve users matching a custom attribute/value pair. */
+    getUsersByAttribute?(attr: string, value: unknown, tenantId?: string): Promise<string[]> | string[];
+}
+type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
+    submittedBy: string;
+    data: Record<string, unknown>;
+    orgProvider?: OrgProvider;
+}) => Promise<string[]> | string[];
+
+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.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.
+     * Returns an opaque handle that can be passed to cancel().
+     */
+    scheduleAt(id: string, runAt: Date, callback: () => Promise<void>): Promise<string>;
+    /** Cancel a previously scheduled callback by its handle. */
+    cancel(handle: string): Promise<void>;
+    /** Gracefully shut down the scheduler and release resources. */
+    shutdown(): Promise<void>;
+}
+
+interface AuthorizationContext {
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | '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<{
+        field: string;
+        message: string;
+    }>;
+}
+interface CanApproveResult {
+    eligible: boolean;
+    reason?: 'not_an_approver' | 'already_acted' | 'self_approval' | 'wrong_status' | 'delegated_away';
+}
+interface PreviewChainLevel {
+    level: number;
+    name: string;
+    resolvedApprovers: string[];
+    mode: ApprovalMode;
+}
+interface PreviewResult {
+    levels: PreviewChainLevel[];
+    /** Indices (0-based) of conditions that fired for this data. */
+    conditionsApplied: number[];
+}
+interface BulkResult {
+    succeeded: ApprovalInstance[];
+    failed: Array<{
+        instanceId: string;
+        error: ApprovalError;
+    }>;
+    total: number;
+}
+interface HealthResult {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    adapter: 'connected' | 'error';
+    pendingCount: number;
+    overdueCount: number;
+    escalationRunning: boolean;
+    lastTickAt?: Date;
+}
+interface RetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+}
+type IdempotencyKeyFn = (tenantId: string, documentType: string, documentId: string, templateName: string, data: Record<string, unknown>) => string;
+interface ApprovalEngineOptions {
+    adapter: IStorageAdapter;
+    tenantId?: string;
+    orgProvider?: OrgProvider;
+    logger?: Logger;
+    escalationPollIntervalMs?: number;
+    /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
+    maxBulkItems?: number;
+    /** Injectable clock — defaults to system clock. Enables deterministic tests and custom time sources. */
+    clock?: Clock;
+    /** Custom ID generator for instances and templates. Defaults to timestamp+random. */
+    generateId?: IdGeneratorFn;
+    /** Custom optimistic locking retry policy. */
+    retryPolicy?: RetryPolicy;
+    /** Custom idempotency key derivation function. Default: SHA-256 of tenant+documentType+documentId+templateName. */
+    idempotencyKeyFn?: IdempotencyKeyFn;
+    /** Notification adapter called after every approval event. */
+    notificationAdapter?: INotificationAdapter;
+    /** Separate append-only audit sink (Kafka, S3, CloudTrail). Called alongside storage adapter. */
+    auditAdapter?: IAuditAdapter;
+    /** Metrics adapter for Prometheus / Datadog / OpenTelemetry. */
+    metricsAdapter?: IMetricsAdapter;
+    /** Custom scheduler adapter (BullMQ, Temporal, cron). Replaces built-in setInterval polling. */
+    schedulerAdapter?: ISchedulerAdapter;
+    /** Authorization policy called before every mutating operation. */
+    authorizationPolicy?: IAuthorizationPolicy;
+    /** Middleware chain: before/after/onError hooks for every operation. */
+    middleware?: IOperationMiddleware[];
+}
+declare class ApprovalEngine {
+    private readonly opts;
+    private readonly bus;
+    private readonly registry;
+    private readonly resolver;
+    private readonly escalation;
+    private readonly tenantId;
+    private readonly logger;
+    private readonly clock;
+    private readonly generateId;
+    private readonly maxBulkItems;
+    private readonly retryPolicy;
+    private readonly idempotencyKeyFn;
+    constructor(opts: ApprovalEngineOptions);
+    on<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
+    off<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
+    registerResolver(name: string, fn: ResolverFn): void;
+    registerApproverType(typeName: string, fn: ApproverResolverFn): void;
+    registerConditionOperator(name: string, fn: ConditionOperatorFn): void;
+    /** Validate a template config without persisting. Synchronous; never throws. */
+    validateTemplate(config: ApprovalTemplateConfig): ValidationResult;
+    defineTemplate(config: ApprovalTemplateConfig): Promise<string>;
+    /** Update an existing template, incrementing its version. In-flight instances are protected by their templateSnapshot. */
+    updateTemplate(config: ApprovalTemplateConfig): Promise<string>;
+    getTemplate(name: string): Promise<ApprovalTemplate>;
+    listTemplates(): Promise<ApprovalTemplate[]>;
+    submit(raw: SubmitOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    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>;
+    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. */
+    addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
+    /** Resubmit a rejected instance, creating a new linked instance from level 1. */
+    resubmit(instanceId: string, raw: ResubmitOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /** Preview the resolved approval chain for a template and document data, without creating an instance. */
+    previewApprovalChain(templateName: string, data: Record<string, unknown>, submittedBy: string): Promise<PreviewResult>;
+    /** Check whether a user is eligible to approve a specific instance. Never throws. */
+    canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
+    /** Emergency bypass — completes the instance as 'approved', skipping remaining levels. Requires template.allowOverride = true. */
+    override(instanceId: string, raw: OverrideOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
+    bulkApprove(instanceIds: string[], raw: ApproveOptions, auditCtx?: AuditContext): Promise<BulkResult>;
+    /** Reject multiple instances in one call. Never throws — failures collected in result.failed. */
+    bulkReject(instanceIds: string[], raw: RejectOptions, auditCtx?: AuditContext): Promise<BulkResult>;
+    getInstance(instanceId: string): Promise<ApprovalInstance>;
+    getPendingFor(approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    queryInstancesByCursor(filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
+    getHistory(instanceId: string): Promise<AuditEntry[]>;
+    getCurrentApprovers(instanceId: string): Promise<string[]>;
+    /** Check adapter connectivity and escalation scheduler health. */
+    healthCheck(): Promise<HealthResult>;
+    shutdown(): Promise<void>;
+    private escalateInternal;
+    private expireInstance;
+    private markSlaBreached;
+    private revertDelegation;
+    /** Read-modify-write with optimistic locking retry. */
+    private withOptimisticRetry;
+    private requireInstance;
+    private currentLevelInstance;
+    private findNextLevel;
+    private findPreviousLevel;
+    private guardBulkSize;
+    private runAuthorizationPolicy;
+    private runMiddlewareBefore;
+    private runMiddlewareAfter;
+    private notifyAdapters;
+    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 };

package/dist/IStorageAdapter-RAiLF8bc.d.cts

@@ -0,0 +1,192 @@
+type ApproverConfig = {
+    type: 'user';
+    userId: string;
+} | {
+    type: 'role';
+    role: string;
+} | {
+    type: 'dynamic';
+    resolver: string;
+}
+/** Custom approver type registered via engine.registerApproverType(). */
+ | {
+    type: string;
+    [key: string]: unknown;
+};
+interface ResolvedApprover {
+    userId: string;
+    source: ApproverConfig;
+}
+type ResolverFn = (submittedBy: string, data: Record<string, unknown>) => Promise<string> | string;
+
+type ApprovalMode = 'all' | 'any' | 'majority';
+/** Built-in operators. Use engine.registerConditionOperator() to add custom ones. */
+type ConditionOperator = '>' | '<' | '>=' | '<=' | '==' | '!=' | 'in' | 'not_in' | (string & {});
+interface Condition {
+    field: string;
+    operator: ConditionOperator;
+    value: unknown;
+}
+interface ApprovalLevelConfig {
+    level: number;
+    name: string;
+    approvers: ApproverConfig[];
+    mode: ApprovalMode;
+    escalationAfterDays?: number;
+}
+interface ConditionRule {
+    when: Condition | Condition[];
+    addLevels?: ApprovalLevelConfig[];
+    skipLevels?: number[];
+}
+interface EscalationConfig {
+    afterDays: number;
+    escalateTo: ApproverConfig;
+}
+interface ApprovalTemplateConfig {
+    name: string;
+    documentType: string;
+    levels: ApprovalLevelConfig[];
+    conditions?: ConditionRule[];
+    escalation?: EscalationConfig;
+    /** Overall SLA for the entire workflow in days. Emits approval:sla_breached when elapsed. */
+    slaDeadlineDays?: number;
+    /** Allow emergency override (bypass remaining levels). Must be true to use engine.override(). */
+    allowOverride?: boolean;
+}
+interface ApprovalTemplate extends ApprovalTemplateConfig {
+    id: string;
+    tenantId: string;
+    createdAt: Date;
+    /** Starts at 1; incremented on each call to engine.updateTemplate(). */
+    version: number;
+    /** ID of the previous version of this template, for audit trail. */
+    previousVersionId?: string;
+}
+
+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';
+interface AuditEntry {
+    action: AuditAction;
+    actorId: string;
+    actorRole?: string;
+    actorIp?: string;
+    actorUserAgent?: string;
+    level: number;
+    timestamp: Date;
+    traceId?: string;
+    comment?: string;
+    reason?: string;
+    delegateTo?: string;
+    oldValue?: Record<string, unknown>;
+    newValue?: Record<string, unknown>;
+}
+/** Context injected by the caller on each mutating operation (for SOX/SOC2 compliance). */
+interface AuditContext {
+    actorRole?: string;
+    actorIp?: string;
+    actorUserAgent?: string;
+    traceId?: string;
+}
+interface ApprovalLevelInstance {
+    level: number;
+    name: string;
+    mode: ApprovalMode;
+    approverConfigs: ApproverConfig[];
+    approverIds: string[];
+    approvedBy: string[];
+    rejectedBy: string[];
+    status: LevelStatus;
+    escalationDueAt?: Date;
+    escalationAfterDays?: number;
+    /** Set when a delegation has a time limit — the original approver is restored when this date passes. */
+    delegatedUntil?: Date;
+    /** The approver who delegated away from this slot; used to revert when delegatedUntil expires. */
+    delegatedFrom?: string;
+    /** The delegate who received this slot; used to revert when delegatedUntil expires. */
+    delegatedTo?: string;
+}
+/** Snapshot of template configuration captured at submit time to insulate in-flight instances from template updates. */
+interface TemplateSnapshot {
+    escalation?: EscalationConfig;
+    slaDeadlineDays?: number;
+    allowOverride?: boolean;
+}
+interface ApprovalInstance {
+    id: string;
+    tenantId: string;
+    templateId: string;
+    templateName: string;
+    documentId: string;
+    documentType: string;
+    submittedBy: string;
+    status: ApprovalStatus;
+    currentLevel: number;
+    version: number;
+    idempotencyKey?: string;
+    levels: ApprovalLevelInstance[];
+    auditLog: AuditEntry[];
+    data: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+    /** Snapshot of template config at submit time — prevents template changes from affecting in-flight instances. */
+    templateSnapshot?: TemplateSnapshot;
+    /** ID of the rejected instance this was resubmitted from. */
+    parentInstanceId?: string;
+    /** Auto-cancel or auto-reject if not resolved by this time. */
+    expiresAt?: Date;
+    /** What happens when expiresAt is reached (default: 'cancel'). */
+    deadlineAction?: 'cancel' | 'reject';
+    /** Set from template.slaDeadlineDays at submit time; breached when passed without resolution. */
+    slaDeadlineAt?: Date;
+    /** Timestamp when the SLA deadline was first breached; set by the scheduler. */
+    slaBreachedAt?: Date;
+}
+
+interface PaginationOpts {
+    limit: number;
+    offset: number;
+}
+interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+}
+/** Opaque cursor: base64(updatedAt_iso:id). Use the value from nextCursor/prevCursor. */
+interface CursorPaginationOpts {
+    cursor?: string;
+    limit: number;
+    direction?: 'forward' | 'backward';
+}
+interface CursorPaginatedResult<T> {
+    items: T[];
+    nextCursor?: string;
+    prevCursor?: string;
+    hasMore: boolean;
+}
+interface InstanceFilter {
+    status?: ApprovalStatus;
+    documentType?: string;
+    submittedBy?: string;
+    fromDate?: Date;
+    toDate?: Date;
+}
+interface IStorageAdapter {
+    saveTemplate(template: ApprovalTemplate): Promise<void>;
+    getTemplate(tenantId: string, name: string): Promise<ApprovalTemplate | null>;
+    listTemplates(tenantId: string): Promise<ApprovalTemplate[]>;
+    saveInstance(instance: ApprovalInstance): Promise<void>;
+    /** Conditional update — throws ApprovalConflictError if stored version !== expectedVersion. */
+    updateInstance(instance: ApprovalInstance, expectedVersion: number): Promise<void>;
+    getInstance(tenantId: string, id: string): Promise<ApprovalInstance | null>;
+    getInstancesByApprover(tenantId: string, approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    getInstancesByFilter(tenantId: string, filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /** Optional cursor-based pagination — more efficient than offset at scale. */
+    getInstancesByCursor?(tenantId: string, filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
+    getOverdueInstances(tenantId: string, asOf: Date): Promise<ApprovalInstance[]>;
+    getIdempotentInstance(tenantId: string, idempotencyKey: string): Promise<ApprovalInstance | null>;
+    appendAuditEntry(tenantId: string, instanceId: string, entry: AuditEntry): Promise<void>;
+}
+
+export type { ApprovalTemplate as A, CursorPaginationOpts as C, EscalationConfig as E, IStorageAdapter as I, LevelStatus as L, PaginationOpts as P, ResolvedApprover as R, TemplateSnapshot as T, ApprovalInstance as a, PaginatedResult as b, InstanceFilter as c, AuditEntry as d, CursorPaginatedResult as e, ApprovalLevelConfig as f, ApprovalLevelInstance as g, ApprovalMode as h, ApprovalStatus as i, ApprovalTemplateConfig as j, ApproverConfig as k, AuditAction as l, AuditContext as m, Condition as n, ConditionOperator as o, ConditionRule as p, ResolverFn as q };