hierarchical-approval 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.8.0] - 2026-09-04
+
+### Added — `transferApprovals()`
+
+- **Move every pending approval assigned to one person over to another.**
+  Someone leaves, changes team, or goes on long-term leave, and their queue has
+  to go somewhere. Doing it by hand meant finding every open instance first —
+  across parallel branches, where one person can hold several open levels on the
+  same document — and missing one left an approval that could never complete.
+
+  ```ts
+  await engine.transferApprovals({
+    fromApprover: 'alice',
+    toApprover: 'bob',
+    transferredBy: 'workflow-admin',
+    reason: 'Alice left the company',
+    documentType: 'purchase_order',   // optional
+    dryRun: true,                     // see what would move first
+  });
+  ```
+
+  Each move goes through `reassign()`, so every guard, audit entry, event and
+  authorization check that applies to a single reassignment applies here too.
+  The sweep is deliberately **not atomic**: it reports per-instance failures
+  rather than rolling back, because a partial transfer is the useful outcome —
+  what can move should move, and what cannot is named for a human to look at.
+
+  New exports: `TransferResult`, `TransferApprovalsOptions`.
+
+### Fixed — `delegate()` and `reassign()` could not reach an upper parallel branch
+
+- **Both resolved the level via `currentLevelInstance`**, which names only the
+  lowest-numbered open level. Inside a parallel group they therefore always
+  acted on the lowest branch: an approver could not hand off their own
+  upper-branch work, and an administrator reassigning a departing user silently
+  moved the wrong branch — or failed, because that person was not an approver on
+  the branch being targeted. Introduced with parallel groups in 1.0.0; sequential
+  templates were never affected.
+
+  Both now resolve against the approver actually being moved, and take an
+  optional `level` to disambiguate when one person holds more than one open
+  branch — matching what `approve()` and `reject()` already did.
+
 ## [1.7.0] - 2026-09-04
 
 ### Added — attachment references

package/README.md

@@ -399,6 +399,33 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Transferring a person's queue
+
+Someone leaves, changes team, or goes on long-term leave, and their open
+approvals have to go somewhere:
+
+```ts
+const result = await engine.transferApprovals({
+  fromApprover: 'alice',
+  toApprover: 'bob',
+  transferredBy: 'workflow-admin',
+  reason: 'Alice left the company',
+  documentType: 'purchase_order',  // optional scoping
+  dryRun: true,                    // see what would move first
+});
+// { transferred: [{ instanceId, level, documentId }], failed: [...], scanned, dryRun }
+```
+
+Each move goes through `reassign()`, so every guard, audit entry, event and
+authorization check that applies to a single reassignment applies here too —
+there is no bulk short-cut around them. Inside a parallel group each open branch
+is moved separately, since one person can hold several open levels on the same
+document.
+
+The sweep is **not atomic**: it reports per-instance failures rather than rolling
+back. A partial transfer is the useful outcome — the approvals that can move
+should move, and the ones that cannot are named so a human can look at them.
+
 ### Attachments
 
 Attach supporting evidence — a quote PDF, a signed contract, a screenshot of a

package/dist/{ApprovalEngine-gQdFy2CO.d.ts → ApprovalEngine-CElfKXOA.d.ts}

@@ -42,12 +42,14 @@ declare const DelegateOptionsSchema: z.ZodObject<{
     toApprover: z.ZodString;
     reason: z.ZodString;
     until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const ReassignOptionsSchema: z.ZodObject<{
     reassignedBy: z.ZodString;
     fromApprover: z.ZodString;
     toApprover: z.ZodString;
     reason: z.ZodString;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const CancelOptionsSchema: z.ZodObject<{
     cancelledBy: z.ZodString;
@@ -90,6 +92,15 @@ declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
     attachmentId: z.ZodString;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+declare const TransferApprovalsOptionsSchema: z.ZodObject<{
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    transferredBy: z.ZodString;
+    reason: z.ZodString;
+    documentType: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -115,6 +126,7 @@ type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
 type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
 type AddAttachmentOptions = z.infer<typeof AddAttachmentOptionsSchema>;
 type RemoveAttachmentOptions = z.infer<typeof RemoveAttachmentOptionsSchema>;
+type TransferApprovalsOptions = z.infer<typeof TransferApprovalsOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -254,6 +266,24 @@ interface BulkResult {
     }>;
     total: number;
 }
+/** Outcome of a {@link ApprovalEngine.transferApprovals} sweep. */
+interface TransferResult {
+    /** One entry per level actually moved (an instance can hold the approver on several open branches). */
+    transferred: Array<{
+        instanceId: string;
+        level: number;
+        documentId: string;
+    }>;
+    /** Instances that could not be moved, with the reason. */
+    failed: Array<{
+        instanceId: string;
+        error: ApprovalError;
+    }>;
+    /** Instances examined. */
+    scanned: number;
+    /** True when nothing was written. */
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -539,6 +569,28 @@ declare class ApprovalEngine {
     /** 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. */
+    /**
+     * Move every pending approval assigned to one person over to another.
+     *
+     * Someone leaves, changes team, or goes on long-term leave, and their queue
+     * has to go somewhere. Doing it by hand means finding every open instance
+     * first — across parallel branches, where one person can hold several open
+     * levels on the same document — and missing one leaves an approval that can
+     * never complete.
+     *
+     * Each move goes through {@link reassign}, so every guard, audit entry, event
+     * and authorization check that applies to a single reassignment applies here
+     * too. There is no bulk short-cut around them.
+     *
+     * The sweep is **not atomic**: it reassigns one level at a time and reports
+     * per-instance failures rather than rolling back. A partial transfer is the
+     * useful outcome — the approvals that could move should move, and the ones
+     * that could not are named so a human can look at them.
+     *
+     * @param raw - Who is moving to whom, and why.
+     * @returns What moved, what did not, and why. With `dryRun` nothing is written.
+     */
+    transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
     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>;
@@ -652,4 +704,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 OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, 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 TransferResult as T, 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 ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-D16llfJv.d.cts → ApprovalEngine-cI4LP2Mx.d.cts}

@@ -42,12 +42,14 @@ declare const DelegateOptionsSchema: z.ZodObject<{
     toApprover: z.ZodString;
     reason: z.ZodString;
     until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const ReassignOptionsSchema: z.ZodObject<{
     reassignedBy: z.ZodString;
     fromApprover: z.ZodString;
     toApprover: z.ZodString;
     reason: z.ZodString;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const CancelOptionsSchema: z.ZodObject<{
     cancelledBy: z.ZodString;
@@ -90,6 +92,15 @@ declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
     attachmentId: z.ZodString;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+declare const TransferApprovalsOptionsSchema: z.ZodObject<{
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    transferredBy: z.ZodString;
+    reason: z.ZodString;
+    documentType: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -115,6 +126,7 @@ type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
 type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
 type AddAttachmentOptions = z.infer<typeof AddAttachmentOptionsSchema>;
 type RemoveAttachmentOptions = z.infer<typeof RemoveAttachmentOptionsSchema>;
+type TransferApprovalsOptions = z.infer<typeof TransferApprovalsOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -254,6 +266,24 @@ interface BulkResult {
     }>;
     total: number;
 }
+/** Outcome of a {@link ApprovalEngine.transferApprovals} sweep. */
+interface TransferResult {
+    /** One entry per level actually moved (an instance can hold the approver on several open branches). */
+    transferred: Array<{
+        instanceId: string;
+        level: number;
+        documentId: string;
+    }>;
+    /** Instances that could not be moved, with the reason. */
+    failed: Array<{
+        instanceId: string;
+        error: ApprovalError;
+    }>;
+    /** Instances examined. */
+    scanned: number;
+    /** True when nothing was written. */
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -539,6 +569,28 @@ declare class ApprovalEngine {
     /** 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. */
+    /**
+     * Move every pending approval assigned to one person over to another.
+     *
+     * Someone leaves, changes team, or goes on long-term leave, and their queue
+     * has to go somewhere. Doing it by hand means finding every open instance
+     * first — across parallel branches, where one person can hold several open
+     * levels on the same document — and missing one leaves an approval that can
+     * never complete.
+     *
+     * Each move goes through {@link reassign}, so every guard, audit entry, event
+     * and authorization check that applies to a single reassignment applies here
+     * too. There is no bulk short-cut around them.
+     *
+     * The sweep is **not atomic**: it reassigns one level at a time and reports
+     * per-instance failures rather than rolling back. A partial transfer is the
+     * useful outcome — the approvals that could move should move, and the ones
+     * that could not are named so a human can look at them.
+     *
+     * @param raw - Who is moving to whom, and why.
+     * @returns What moved, what did not, and why. With `dryRun` nothing is written.
+     */
+    transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
     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>;
@@ -652,4 +704,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 OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, 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 TransferResult as T, 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 ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/index.cjs

@@ -39,13 +39,20 @@ var DelegateOptionsSchema = zod.z.object({
   fromApprover: zod.z.string().min(1),
   toApprover: zod.z.string().min(1),
   reason: zod.z.string().min(1),
-  until: zod.z.coerce.date().optional()
+  until: zod.z.coerce.date().optional(),
+  /**
+   * Which open level to act on. Only needed inside a parallel group, where the
+   * approver may hold more than one open branch.
+   */
+  level: zod.z.number().int().optional()
 });
 var ReassignOptionsSchema = zod.z.object({
   reassignedBy: zod.z.string().min(1),
   fromApprover: zod.z.string().min(1),
   toApprover: zod.z.string().min(1),
-  reason: zod.z.string().min(1)
+  reason: zod.z.string().min(1),
+  /** Which open level to act on; see {@link DelegateOptionsSchema}. */
+  level: zod.z.number().int().optional()
 });
 var CancelOptionsSchema = zod.z.object({
   cancelledBy: zod.z.string().min(1),
@@ -90,6 +97,18 @@ var RemoveAttachmentOptionsSchema = zod.z.object({
   attachmentId: zod.z.string().min(1),
   reason: zod.z.string().optional()
 });
+var TransferApprovalsOptionsSchema = zod.z.object({
+  fromApprover: zod.z.string().min(1),
+  toApprover: zod.z.string().min(1),
+  transferredBy: zod.z.string().min(1),
+  reason: zod.z.string().min(1),
+  /** Restrict the sweep to one document type. */
+  documentType: zod.z.string().optional(),
+  /** Report what would move without changing anything. */
+  dryRun: zod.z.boolean().default(false),
+  /** Safety cap on how many instances one sweep will touch. */
+  limit: zod.z.number().int().positive().default(500)
+});
 var UpdateDataOptionsSchema = zod.z.object({
   updatedBy: zod.z.string().min(1),
   data: zod.z.record(zod.z.string(), zod.z.unknown()),
@@ -1647,7 +1666,7 @@ var ApprovalEngine = class _ApprovalEngine {
       if (opts.fromApprover === opts.toApprover) {
         throw new ApprovalForbiddenError("Cannot delegate to yourself.");
       }
-      const level = this.currentLevelInstance(instance);
+      const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       await this.runAuthorizationPolicy({
         operation: "delegate",
         actorId: opts.fromApprover,
@@ -1729,7 +1748,7 @@ var ApprovalEngine = class _ApprovalEngine {
       if (opts.fromApprover === opts.toApprover) {
         throw new ApprovalForbiddenError("Cannot reassign an approver to themselves.");
       }
-      const level = this.currentLevelInstance(instance);
+      const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       await this.runAuthorizationPolicy({
         operation: "reassign",
         actorId: opts.reassignedBy,
@@ -2365,9 +2384,7 @@ var ApprovalEngine = class _ApprovalEngine {
         input: opts
       });
       const now = this.clock.now();
-      instance.attachments = (instance.attachments ?? []).filter(
-        (a) => a.id !== opts.attachmentId
-      );
+      instance.attachments = (instance.attachments ?? []).filter((a) => a.id !== opts.attachmentId);
       instance.updatedAt = now;
       const auditEntry = {
         action: "attachment_removed",
@@ -2706,6 +2723,95 @@ var ApprovalEngine = class _ApprovalEngine {
     });
   }
   /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
+  /**
+   * Move every pending approval assigned to one person over to another.
+   *
+   * Someone leaves, changes team, or goes on long-term leave, and their queue
+   * has to go somewhere. Doing it by hand means finding every open instance
+   * first — across parallel branches, where one person can hold several open
+   * levels on the same document — and missing one leaves an approval that can
+   * never complete.
+   *
+   * Each move goes through {@link reassign}, so every guard, audit entry, event
+   * and authorization check that applies to a single reassignment applies here
+   * too. There is no bulk short-cut around them.
+   *
+   * The sweep is **not atomic**: it reassigns one level at a time and reports
+   * per-instance failures rather than rolling back. A partial transfer is the
+   * useful outcome — the approvals that could move should move, and the ones
+   * that could not are named so a human can look at them.
+   *
+   * @param raw - Who is moving to whom, and why.
+   * @returns What moved, what did not, and why. With `dryRun` nothing is written.
+   */
+  async transferApprovals(raw, auditCtx) {
+    const opts = parseOrThrow(() => TransferApprovalsOptionsSchema.parse(raw));
+    if (opts.fromApprover === opts.toApprover) {
+      throw new ApprovalValidationError(
+        "transferApprovals requires different fromApprover and toApprover."
+      );
+    }
+    const queue = await this.opts.adapter.getInstancesByApprover(this.tenantId, opts.fromApprover, {
+      limit: opts.limit,
+      offset: 0
+    });
+    const result = {
+      transferred: [],
+      failed: [],
+      scanned: 0,
+      dryRun: opts.dryRun
+    };
+    for (const instance of queue.items) {
+      if (opts.documentType && instance.documentType !== opts.documentType) continue;
+      result.scanned++;
+      const levels = instance.levels.filter(
+        (l) => l.status === "pending" && l.approverIds.includes(opts.fromApprover)
+      );
+      for (const level of levels) {
+        if (opts.dryRun) {
+          result.transferred.push({
+            instanceId: instance.id,
+            level: level.level,
+            documentId: instance.documentId
+          });
+          continue;
+        }
+        try {
+          await this.reassign(
+            instance.id,
+            {
+              reassignedBy: opts.transferredBy,
+              fromApprover: opts.fromApprover,
+              toApprover: opts.toApprover,
+              reason: opts.reason,
+              level: level.level
+            },
+            auditCtx
+          );
+          result.transferred.push({
+            instanceId: instance.id,
+            level: level.level,
+            documentId: instance.documentId
+          });
+        } catch (err) {
+          result.failed.push({
+            instanceId: instance.id,
+            error: err instanceof ApprovalError ? err : new ApprovalError(String(err), "UNKNOWN")
+          });
+        }
+      }
+    }
+    this.logger.info("transferApprovals: sweep complete", {
+      tenantId: this.tenantId,
+      fromApprover: opts.fromApprover,
+      toApprover: opts.toApprover,
+      scanned: result.scanned,
+      transferred: result.transferred.length,
+      failed: result.failed.length,
+      dryRun: opts.dryRun
+    });
+    return result;
+  }
   async bulkApprove(instanceIds, raw, auditCtx) {
     const opts = parseOrThrow(() => ApproveOptionsSchema.parse(raw));
     this.guardBulkSize(instanceIds);