hierarchical-approval 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,81 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.3.0] - 2026-09-04
+
+### Added — out-of-office cover
+
+- **`outOfOfficeProvider` swaps absent approvers for their stand-in.** An
+  approver on leave stalled the chain until somebody noticed and reassigned by
+  hand; `delegate()` needed the absent person to initiate it, and `reassign()`
+  needed an administrator to spot the problem first.
+
+  ```ts
+  new ApprovalEngine({
+    adapter,
+    outOfOfficeProvider: {
+      getDelegateFor: async (userId, at) => hr.coverFor(userId, at), // null when available
+    },
+  });
+  ```
+
+  Applied wherever approvers are resolved — at submit, when a level activates,
+  on escalation, and in `previewApprovalChain()`, so a preview cannot disagree
+  with what `submit()` goes on to do.
+
+  Kept as an injected provider rather than engine-owned state because absence
+  lives in the HR or directory system that already tracks leave; storing it here
+  too would guarantee the two disagree. The resolution time is passed to the
+  provider, so cover can be date-bound.
+
+- **Substitution is transitive but bounded.** An A→B→C chain of absences lands
+  on whoever is actually present, up to five hops. A cover *cycle* (A covers B
+  while B covers A) stops and leaves the original approver assigned — visible and
+  fixable, unlike a hang. A provider that throws is treated as "no cover known",
+  because an HR lookup failing must not stop an approval being routed at all.
+
+  New export: `OutOfOfficeProvider`.
+
+## [1.2.0] - 2026-09-04
+
+### Added — template inheritance
+
+- **`extends` derives one template from another.** ERP tenants run many
+  near-identical workflows — one per region, legal entity or document class —
+  that share a spine and differ in a level or two. Each had to be written out in
+  full, so a change to the shared part meant editing every copy and hoping none
+  were missed.
+
+  ```ts
+  await engine.defineTemplate({
+    name: 'PO-EU',
+    extends: 'PO-base',
+    documentType: 'purchase_order',
+    removeLevels: [2],
+    levels: [{ level: 3, approvers: [{ type: 'user', userId: 'eu-fin' }] }],
+  });
+  ```
+
+  Levels are keyed by number: a child level overrides the base level *field by
+  field* (so a derived template can swap just the approvers and inherit name,
+  mode and deadlines), child-only levels are appended, and `removeLevels` drops
+  inherited ones. `conditions` are replaced wholesale when supplied — merging
+  two rule lists would produce a chain neither author intended. `escalation`,
+  `slaDeadlineDays` and `allowOverride` are inherited unless the child sets them.
+
+- **Resolution happens once, at define time, and the flattened result is what
+  gets stored.** Resolving lazily on read would mean editing a base silently
+  reshapes every derived template — and every in-flight instance running against
+  one — which is exactly the surprise `templateSnapshot` exists to prevent
+  elsewhere in the engine. A base that itself extends something is already
+  flattened, so chains resolve naturally and cycles cannot form.
+
+- **Validation runs on the flattened template**, not the fragment: a derived
+  config carrying no levels of its own is valid (it inherits the chain), while
+  one whose `removeLevels` strips the chain entirely is rejected at definition
+  time. `extends` and `removeLevels` are directives for the call and are not
+  persisted.
+
 ## [1.1.0] - 2026-09-04
 
 ### Added — approval reminders

package/README.md

@@ -399,6 +399,67 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Out-of-office cover
+
+Approvers go on leave, and a chain that waits on an absent person stalls.
+Configure a provider and absent approvers are swapped for their stand-in
+wherever approvers are resolved — at submit, when a level activates, on
+escalation, and in `previewApprovalChain()`:
+
+```ts
+const engine = new ApprovalEngine({
+  adapter,
+  outOfOfficeProvider: {
+    // Return the stand-in, or null when the approver is available.
+    getDelegateFor: async (userId, at) => hr.coverFor(userId, at),
+  },
+});
+```
+
+Absence lives in the HR or directory system that already tracks leave, so this
+is an injected provider rather than engine-owned state — duplicating that data
+here would guarantee the two disagree. The resolution time is passed in, so
+cover can be date-bound.
+
+Substitution is transitive (A away → B, B away → C lands on C) up to five hops.
+A cover *cycle* stops rather than looping, and a provider that throws is treated
+as "no cover known" — an HR lookup failing must not stop an approval being
+routed at all.
+
+### Template inheritance
+
+ERP tenants run many near-identical workflows — one per region, entity or
+document class — that share a spine and differ in a level or two. `extends`
+derives one template from another:
+
+```ts
+await engine.defineTemplate({
+  name: 'PO-EU',
+  extends: 'PO-base',
+  documentType: 'purchase_order',
+  removeLevels: [2],                       // drop an inherited level
+  levels: [
+    { level: 3, approvers: [{ type: 'user', userId: 'eu-fin' }] },  // override just the approvers
+    { level: 4, name: 'EU Compliance', approvers: [...], mode: 'any' }, // add a new level
+  ],
+});
+```
+
+| Field | Merge rule |
+|---|---|
+| `levels` | Keyed by level number: a child level overrides the base level *field by field*, child-only levels are appended, `removeLevels` drops inherited ones |
+| `conditions` | Replaced wholesale when the child supplies them |
+| `escalation`, `slaDeadlineDays`, `allowOverride` | Child value if set, otherwise inherited |
+
+**Resolution happens once, at define time, and the flattened result is stored.**
+Editing a base later never silently reshapes a derived template or an instance
+already running against one — the same insulation `templateSnapshot` gives
+in-flight instances. A base that itself extends something is already flattened,
+so chains resolve naturally and cycles cannot form.
+
+Validation runs on the *flattened* template, so a derived config that strips its
+whole chain is rejected at definition time.
+
 ### Reminders
 
 Escalation reassigns work; a reminder only nudges, which is usually what an

package/dist/{ApprovalEngine-qwImBe9A.d.cts → ApprovalEngine-CfySjeuy.d.cts}

@@ -1,14 +1,14 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-BZarNxs9.cjs';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-DuEgSIIz.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BKwhxhe2.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CKV_FZFV.cjs';
+import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BsM0DUPf.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BKMeGmaG.cjs';
 import { z } from 'zod';
 import { L as Logger } from './Logger-BplhlU7l.cjs';
 import { C as Clock } from './Clock-3FnOczFJ.cjs';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-D162RiJs.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-CWdZxS3U.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BLw9Oc-S.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-B2I3CjaJ.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-QvyaKQCc.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-ChZIUJhQ.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BHDZK9QL.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -136,6 +136,23 @@ interface OrgProvider {
     /** Optional: resolve users matching a custom attribute/value pair. */
     getUsersByAttribute?(attr: string, value: unknown, tenantId?: string): Promise<string[]> | string[];
 }
+/**
+ * Supplies out-of-office cover so an approver on leave does not stall a chain.
+ *
+ * Consulted whenever a level's approvers are resolved — at submit, when a level
+ * activates, and when a chain is previewed. Kept as an injected provider rather
+ * than engine-owned state because absence lives in the HR or directory system
+ * that already knows about leave; duplicating it here would guarantee the two
+ * disagree.
+ */
+interface OutOfOfficeProvider {
+    /**
+     * @param userId - The approver about to be assigned.
+     * @param at - The moment cover is being resolved for.
+     * @returns The user to stand in, or null/undefined when the approver is available.
+     */
+    getDelegateFor(userId: string, at: Date): Promise<string | null | undefined> | string | null | undefined;
+}
 type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
     submittedBy: string;
     data: Record<string, unknown>;
@@ -296,6 +313,11 @@ interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
     orgProvider?: OrgProvider;
+    /**
+     * Supplies stand-ins for approvers who are away, so leave does not stall a
+     * chain. Consulted every time approvers are resolved.
+     */
+    outOfOfficeProvider?: OutOfOfficeProvider;
     logger?: Logger;
     escalationPollIntervalMs?: number;
     /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
@@ -546,4 +568,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-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 IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, 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 CycleTimeStats 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, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+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 IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, 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 CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type RejectOptions as n, type ResubmitOptions as o, type RetryPolicy as p, defaultIdGenerator as q, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-BDnQwKi9.d.ts → ApprovalEngine-Dhu5mlCG.d.ts}

@@ -1,14 +1,14 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DrY-rhhF.js';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-DuEgSIIz.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-CsSWiCZE.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DQJmR6Mt.js';
+import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BsM0DUPf.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BmSeB7FZ.js';
 import { z } from 'zod';
 import { L as Logger } from './Logger-BplhlU7l.js';
 import { C as Clock } from './Clock-3FnOczFJ.js';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CPkGSVfr.js';
-import { I as IAuditAdapter } from './IAuditAdapter-99JBU3Db.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BW9t8wPn.js';
+import { I as IAuditAdapter } from './IAuditAdapter-GixC9zS1.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-QvyaKQCc.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-U-jZrl2F.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-4ge9Gnxj.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -136,6 +136,23 @@ interface OrgProvider {
     /** Optional: resolve users matching a custom attribute/value pair. */
     getUsersByAttribute?(attr: string, value: unknown, tenantId?: string): Promise<string[]> | string[];
 }
+/**
+ * Supplies out-of-office cover so an approver on leave does not stall a chain.
+ *
+ * Consulted whenever a level's approvers are resolved — at submit, when a level
+ * activates, and when a chain is previewed. Kept as an injected provider rather
+ * than engine-owned state because absence lives in the HR or directory system
+ * that already knows about leave; duplicating it here would guarantee the two
+ * disagree.
+ */
+interface OutOfOfficeProvider {
+    /**
+     * @param userId - The approver about to be assigned.
+     * @param at - The moment cover is being resolved for.
+     * @returns The user to stand in, or null/undefined when the approver is available.
+     */
+    getDelegateFor(userId: string, at: Date): Promise<string | null | undefined> | string | null | undefined;
+}
 type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
     submittedBy: string;
     data: Record<string, unknown>;
@@ -296,6 +313,11 @@ interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
     orgProvider?: OrgProvider;
+    /**
+     * Supplies stand-ins for approvers who are away, so leave does not stall a
+     * chain. Consulted every time approvers are resolved.
+     */
+    outOfOfficeProvider?: OutOfOfficeProvider;
     logger?: Logger;
     escalationPollIntervalMs?: number;
     /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
@@ -546,4 +568,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-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 IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, 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 CycleTimeStats 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, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+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 IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, 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 CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type RejectOptions as n, type ResubmitOptions as o, type RetryPolicy as p, defaultIdGenerator as q, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{IAuditAdapter-CWdZxS3U.d.cts → IAuditAdapter-B2I3CjaJ.d.cts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-DuEgSIIz.cjs';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-BsM0DUPf.cjs';
 
 interface IAuditAdapter {
     /**

package/dist/{IAuditAdapter-99JBU3Db.d.ts → IAuditAdapter-GixC9zS1.d.ts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-DuEgSIIz.js';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-BsM0DUPf.js';
 
 interface IAuditAdapter {
     /**

package/dist/{IAuthorizationPolicy-U-jZrl2F.d.ts → IAuthorizationPolicy-4ge9Gnxj.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-DuEgSIIz.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BsM0DUPf.js';
 
 interface AuthorizationContext {
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData';

package/dist/{IAuthorizationPolicy-ChZIUJhQ.d.cts → IAuthorizationPolicy-BHDZK9QL.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-DuEgSIIz.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BsM0DUPf.cjs';
 
 interface AuthorizationContext {
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData';

package/dist/{INotificationAdapter-BKwhxhe2.d.cts → INotificationAdapter-BKMeGmaG.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-DuEgSIIz.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BsM0DUPf.cjs';
 
 interface ApprovalEvent {
     instanceId: string;

package/dist/{INotificationAdapter-CsSWiCZE.d.ts → INotificationAdapter-BmSeB7FZ.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-DuEgSIIz.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BsM0DUPf.js';
 
 interface ApprovalEvent {
     instanceId: string;

package/dist/{IOperationMiddleware-D162RiJs.d.cts → IOperationMiddleware-BLw9Oc-S.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-DuEgSIIz.cjs';
+import { a as ApprovalInstance } from './instance-BsM0DUPf.cjs';
 
 declare class ApprovalError extends Error {
     readonly code: string;

package/dist/{IOperationMiddleware-CPkGSVfr.d.ts → IOperationMiddleware-BW9t8wPn.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-DuEgSIIz.js';
+import { a as ApprovalInstance } from './instance-BsM0DUPf.js';
 
 declare class ApprovalError extends Error {
     readonly code: string;

package/dist/{IStorageAdapter-BZarNxs9.d.cts → IStorageAdapter-CKV_FZFV.d.cts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-DuEgSIIz.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BsM0DUPf.cjs';
 
 interface PaginationOpts {
     limit: number;

package/dist/{IStorageAdapter-DrY-rhhF.d.ts → IStorageAdapter-DQJmR6Mt.d.ts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-DuEgSIIz.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BsM0DUPf.js';
 
 interface PaginationOpts {
     limit: number;

package/dist/adapters/MemoryAdapter.d.cts

@@ -1,5 +1,5 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-BZarNxs9.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DuEgSIIz.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-CKV_FZFV.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.cjs';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

package/dist/adapters/MemoryAdapter.d.ts

@@ -1,5 +1,5 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DrY-rhhF.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DuEgSIIz.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DQJmR6Mt.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.js';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

package/dist/adapters/PostgresAdapter.d.cts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-BZarNxs9.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DuEgSIIz.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-CKV_FZFV.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.cjs';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/adapters/PostgresAdapter.d.ts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DrY-rhhF.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DuEgSIIz.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DQJmR6Mt.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.js';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/index.cjs

@@ -224,6 +224,66 @@ var TemplateRegistry = class {
     this.clock = opts?.clock ?? systemClock;
     this.generateId = opts?.generateId ?? defaultIdGenerator;
   }
+  /**
+   * Flatten a template that declares `extends` against its base.
+   *
+   * Resolution is done once, at define time, and the flattened result is what
+   * gets stored. Resolving lazily on read would mean editing a base silently
+   * reshapes every derived template — and every in-flight instance running
+   * against one — which is exactly the surprise `templateSnapshot` exists to
+   * prevent elsewhere in the engine.
+   *
+   * Merge rules:
+   * - **Levels** are keyed by level number. A child level with the same number
+   *   overrides the base level field by field, so a derived template can change
+   *   just the approvers and inherit the rest. Child-only levels are appended,
+   *   and `removeLevels` drops inherited ones.
+   * - **conditions** are replaced wholesale when the child supplies them.
+   *   Concatenating two rule lists would produce a chain neither author
+   *   intended, and there is no meaningful way to "merge" boolean rules.
+   * - **escalation**, **slaDeadlineDays** and **allowOverride** are taken from
+   *   the child when set, otherwise inherited.
+   *
+   * A base that itself extends something is already flattened in storage, so
+   * chains resolve naturally and cycles cannot form: the base must exist before
+   * the child can name it.
+   *
+   * @param config - The raw config as supplied by the caller.
+   * @returns The config with inheritance applied, or unchanged if no `extends`.
+   */
+  async resolveInheritance(config) {
+    if (!config.extends) return config;
+    if (config.extends === config.name) {
+      throw new ApprovalValidationError(`Template "${config.name}" cannot extend itself.`);
+    }
+    const base = await this.adapter.getTemplate(this.tenantId, config.extends);
+    if (!base) {
+      throw new ApprovalTemplateNotFoundError(
+        `${config.extends} (referenced by "${config.name}" via extends)`
+      );
+    }
+    const removed = new Set(config.removeLevels ?? []);
+    const byLevel = /* @__PURE__ */ new Map();
+    for (const lvl of base.levels) {
+      if (!removed.has(lvl.level)) byLevel.set(lvl.level, lvl);
+    }
+    for (const lvl of config.levels ?? []) {
+      const inherited = byLevel.get(lvl.level);
+      byLevel.set(lvl.level, inherited ? { ...inherited, ...lvl } : lvl);
+    }
+    const levels = [...byLevel.values()].sort((a, b) => a.level - b.level);
+    const resolved = {
+      ...config,
+      levels,
+      conditions: config.conditions ?? base.conditions,
+      escalation: config.escalation ?? base.escalation,
+      slaDeadlineDays: config.slaDeadlineDays ?? base.slaDeadlineDays,
+      allowOverride: config.allowOverride ?? base.allowOverride
+    };
+    delete resolved.extends;
+    delete resolved.removeLevels;
+    return resolved;
+  }
   async define(config) {
     const existing = await this.adapter.getTemplate(this.tenantId, config.name);
     if (existing) {
@@ -271,6 +331,7 @@ var TemplateRegistry = class {
 };
 
 // src/engine/LevelResolver.ts
+var MAX_OOO_HOPS = 5;
 var LevelResolver = class {
   constructor() {
     this.resolvers = /* @__PURE__ */ new Map();
@@ -282,7 +343,7 @@ var LevelResolver = class {
   registerApproverType(typeName, fn) {
     this.approverTypes.set(typeName, fn);
   }
-  async resolveApprovers(approvers, submittedBy, data, orgProvider) {
+  async resolveApprovers(approvers, submittedBy, data, orgProvider, outOfOffice, at) {
     const resolved = [];
     for (const approver of approvers) {
       switch (approver.type) {
@@ -302,7 +363,9 @@ var LevelResolver = class {
           break;
         }
         case "dynamic": {
-          const fn = this.resolvers.get(approver.resolver);
+          const fn = this.resolvers.get(
+            approver.resolver
+          );
           if (!fn) {
             throw new Error(
               `No resolver registered for "${approver.resolver}". Call engine.registerResolver("${approver.resolver}", fn) first.`
@@ -319,7 +382,11 @@ var LevelResolver = class {
               `Unknown approver type "${approver.type}". Register it with engine.registerApproverType("${approver.type}", fn) first.`
             );
           }
-          const ids = await customFn(approver, { submittedBy, data, orgProvider });
+          const ids = await customFn(approver, {
+            submittedBy,
+            data,
+            orgProvider
+          });
           resolved.push(...ids);
           break;
         }
@@ -331,7 +398,40 @@ var LevelResolver = class {
         "No approvers resolved for this level. Check your approver configuration \u2014 role may have no members or dynamic resolver returned empty."
       );
     }
-    return result;
+    return this.applyOutOfOffice(result, outOfOffice, at);
+  }
+  /**
+   * Replace approvers who are away with their cover.
+   *
+   * Substitution is transitive up to {@link MAX_OOO_HOPS} so an A→B→C chain of
+   * absences still lands on someone present, but a cycle (A covers B while B
+   * covers A) simply stops rather than looping — leaving the original approver
+   * assigned, which is visible and fixable, unlike a hang.
+   *
+   * A provider that throws is treated as "no cover known": an HR lookup failing
+   * must not block an approval from being routed at all.
+   */
+  async applyOutOfOffice(userIds, provider, at) {
+    if (!provider) return userIds;
+    const asOf = at ?? /* @__PURE__ */ new Date();
+    const covered = [];
+    for (const original of userIds) {
+      let current = original;
+      const seen = /* @__PURE__ */ new Set([current]);
+      for (let hop = 0; hop < MAX_OOO_HOPS; hop++) {
+        let delegate;
+        try {
+          delegate = await provider.getDelegateFor(current, asOf);
+        } catch {
+          break;
+        }
+        if (!delegate || delegate === current || seen.has(delegate)) break;
+        seen.add(delegate);
+        current = delegate;
+      }
+      covered.push(current);
+    }
+    return [...new Set(covered)];
   }
 };
 
@@ -855,9 +955,11 @@ var ApprovalEngine = class _ApprovalEngine {
   /** Validate a template config without persisting. Synchronous; never throws. */
   validateTemplate(config) {
     const errors = [];
-    if (!config.levels || config.levels.length === 0) {
+    const hasOwnLevels = Boolean(config.levels && config.levels.length > 0);
+    if (!hasOwnLevels && config.extends === void 0) {
       errors.push({ field: "levels", message: "Template must have at least one level." });
-    } else {
+    }
+    if (hasOwnLevels) {
       const levelNums = /* @__PURE__ */ new Set();
       config.levels.forEach((l, i) => {
         if (levelNums.has(l.level)) {
@@ -986,25 +1088,27 @@ var ApprovalEngine = class _ApprovalEngine {
     return { valid: errors.length === 0, errors };
   }
   async defineTemplate(config) {
-    const validation = this.validateTemplate(config);
+    const resolved = await this.registry.resolveInheritance(config);
+    const validation = this.validateTemplate(resolved);
     if (!validation.valid) {
       const first = validation.errors[0];
       throw new ApprovalValidationError(
         `Invalid template configuration: ${first?.message ?? "unknown error"}`
       );
     }
-    return this.registry.define(config);
+    return this.registry.define(resolved);
   }
   /** Update an existing template, incrementing its version. In-flight instances are protected by their templateSnapshot. */
   async updateTemplate(config) {
-    const validation = this.validateTemplate(config);
+    const resolved = await this.registry.resolveInheritance(config);
+    const validation = this.validateTemplate(resolved);
     if (!validation.valid) {
       const first = validation.errors[0];
       throw new ApprovalValidationError(
         `Invalid template configuration: ${first?.message ?? "unknown error"}`
       );
     }
-    return this.registry.update(config);
+    return this.registry.update(resolved);
   }
   async getTemplate(name) {
     return this.registry.get(name);
@@ -1085,7 +1189,9 @@ var ApprovalEngine = class _ApprovalEngine {
         lvl.approverConfigs,
         opts.submittedBy,
         opts.data,
-        this.opts.orgProvider
+        this.opts.orgProvider,
+        this.opts.outOfOfficeProvider,
+        now
       );
     }
     const auditEntry = {
@@ -2088,7 +2194,9 @@ var ApprovalEngine = class _ApprovalEngine {
           cfg.approvers,
           submittedBy,
           data,
-          this.opts.orgProvider
+          this.opts.orgProvider,
+          this.opts.outOfOfficeProvider,
+          this.clock.now()
         );
         levels.push({ level: cfg.level, name: cfg.name, resolvedApprovers, mode: cfg.mode });
       } catch {
@@ -2467,7 +2575,9 @@ var ApprovalEngine = class _ApprovalEngine {
         [escalationConfig.escalateTo],
         instance.submittedBy,
         instance.data,
-        this.opts.orgProvider
+        this.opts.orgProvider,
+        this.opts.outOfOfficeProvider,
+        this.clock.now()
       );
       const filteredApprovers = newApprovers.filter((id) => id !== instance.submittedBy);
       if (filteredApprovers.length === 0) {
@@ -2752,7 +2862,9 @@ var ApprovalEngine = class _ApprovalEngine {
         lvl.approverConfigs,
         instance.submittedBy,
         instance.data,
-        this.opts.orgProvider
+        this.opts.orgProvider,
+        this.opts.outOfOfficeProvider,
+        now
       );
       if (lvl.escalationAfterDays) {
         lvl.escalationDueAt = this.deadlineFrom(now, lvl.escalationAfterDays);