hierarchical-approval 0.1.0

package/dist/ApprovalEngine-BcnLzfAU.d.cts

@@ -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.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 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 };