hierarchical-approval 4.0.2 → 4.0.4

package/dist/{instance-uUQh5XW3.d.cts → instance-CUZcHWK2.d.cts}

@@ -13,18 +13,28 @@ type ApproverConfig = {
     type: string;
     [key: string]: unknown;
 };
+/** An {@link ApproverConfig} resolved down to a concrete user. */
 interface ResolvedApprover {
     userId: string;
+    /** The config entry this approver was resolved from. */
     source: ApproverConfig;
 }
+/**
+ * Resolves a `{ type: 'dynamic' }` approver to a concrete user id, given the
+ * submitter and the document's data. Registered via
+ * {@link ApprovalEngine.registerResolver}.
+ */
 type ResolverFn = (submittedBy: string, data: Record<string, unknown>) => Promise<string> | string;
 
 type ApprovalMode = 'all' | 'any' | 'majority' | 'quorum' | 'weighted';
 /** Built-in operators. Use engine.registerConditionOperator() to add custom ones. */
 type ConditionOperator = '>' | '<' | '>=' | '<=' | '==' | '!=' | 'in' | 'not_in' | (string & {});
+/** A single test comparing a field on the evaluated document against a value. */
 interface Condition {
+    /** Dot path into the document being evaluated, e.g. `"amount"` or `"header.total"`. */
     field: string;
     operator: ConditionOperator;
+    /** The value `field` is compared against; its shape depends on `operator`. */
     value: unknown;
 }
 interface ApprovalLevelConfig {
@@ -145,8 +155,11 @@ interface ConditionRule {
     addLevels?: ApprovalLevelConfig[];
     skipLevels?: number[];
 }
+/** A single-rung escalation. See {@link EscalationStep} for a multi-rung ladder. */
 interface EscalationConfig {
+    /** Delay from the level opening, in calendar or business days. */
     afterDays: number;
+    /** Who is added to the level once `afterDays` elapses. */
     escalateTo: ApproverConfig;
 }
 /** One rung of an escalation ladder. See {@link ApprovalTemplateConfig.escalationSteps}. */
@@ -215,19 +228,33 @@ interface ApprovalTemplate extends ApprovalTemplateConfig {
 type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
 type LevelStatus = 'waiting' | 'pending' | 'approved' | 'rejected' | 'skipped';
 type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'data_updated' | 'reminded' | 'info_requested' | 'info_provided' | 'attachment_added' | 'attachment_removed' | 'subworkflow_started' | 'subworkflow_completed' | 'expired';
+/** One row of an {@link ApprovalInstance}'s audit log, recording a single state change. */
 interface AuditEntry {
+    /** What happened. */
     action: AuditAction;
+    /** Id of the user or system that performed the action. */
     actorId: string;
+    /** Role the actor held at the time, when supplied via {@link AuditContext}. */
     actorRole?: string;
+    /** IP address the action originated from, when supplied via {@link AuditContext}. */
     actorIp?: string;
+    /** User agent the action originated from, when supplied via {@link AuditContext}. */
     actorUserAgent?: string;
+    /** Level the action applied to, or the current level for instance-wide actions. */
     level: number;
+    /** When the action happened. */
     timestamp: Date;
+    /** Caller-supplied trace id for correlating this entry with external logs. */
     traceId?: string;
+    /** Free-text comment attached to the action, if any. */
     comment?: string;
+    /** Reason given for the action (e.g. a rejection or override reason), if any. */
     reason?: string;
+    /** Id of the user this action routed to, for `'delegated'`/`'reassigned'`/`'escalated'` actions. */
     delegateTo?: string;
+    /** State the action changed from, shaped differently per {@link action}. */
     oldValue?: Record<string, unknown>;
+    /** State the action changed to, shaped differently per {@link action}. */
     newValue?: Record<string, unknown>;
 }
 /** Context injected by the caller on each mutating operation (for SOX/SOC2 compliance). */
@@ -237,6 +264,7 @@ interface AuditContext {
     actorUserAgent?: string;
     traceId?: string;
 }
+/** Runtime state of one level within an {@link ApprovalInstance} — its resolved approvers and how far it has progressed. */
 interface ApprovalLevelInstance {
     level: number;
     name: string;

package/dist/{instance-uUQh5XW3.d.ts → instance-CUZcHWK2.d.ts}

@@ -13,18 +13,28 @@ type ApproverConfig = {
     type: string;
     [key: string]: unknown;
 };
+/** An {@link ApproverConfig} resolved down to a concrete user. */
 interface ResolvedApprover {
     userId: string;
+    /** The config entry this approver was resolved from. */
     source: ApproverConfig;
 }
+/**
+ * Resolves a `{ type: 'dynamic' }` approver to a concrete user id, given the
+ * submitter and the document's data. Registered via
+ * {@link ApprovalEngine.registerResolver}.
+ */
 type ResolverFn = (submittedBy: string, data: Record<string, unknown>) => Promise<string> | string;
 
 type ApprovalMode = 'all' | 'any' | 'majority' | 'quorum' | 'weighted';
 /** Built-in operators. Use engine.registerConditionOperator() to add custom ones. */
 type ConditionOperator = '>' | '<' | '>=' | '<=' | '==' | '!=' | 'in' | 'not_in' | (string & {});
+/** A single test comparing a field on the evaluated document against a value. */
 interface Condition {
+    /** Dot path into the document being evaluated, e.g. `"amount"` or `"header.total"`. */
     field: string;
     operator: ConditionOperator;
+    /** The value `field` is compared against; its shape depends on `operator`. */
     value: unknown;
 }
 interface ApprovalLevelConfig {
@@ -145,8 +155,11 @@ interface ConditionRule {
     addLevels?: ApprovalLevelConfig[];
     skipLevels?: number[];
 }
+/** A single-rung escalation. See {@link EscalationStep} for a multi-rung ladder. */
 interface EscalationConfig {
+    /** Delay from the level opening, in calendar or business days. */
     afterDays: number;
+    /** Who is added to the level once `afterDays` elapses. */
     escalateTo: ApproverConfig;
 }
 /** One rung of an escalation ladder. See {@link ApprovalTemplateConfig.escalationSteps}. */
@@ -215,19 +228,33 @@ interface ApprovalTemplate extends ApprovalTemplateConfig {
 type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
 type LevelStatus = 'waiting' | 'pending' | 'approved' | 'rejected' | 'skipped';
 type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'data_updated' | 'reminded' | 'info_requested' | 'info_provided' | 'attachment_added' | 'attachment_removed' | 'subworkflow_started' | 'subworkflow_completed' | 'expired';
+/** One row of an {@link ApprovalInstance}'s audit log, recording a single state change. */
 interface AuditEntry {
+    /** What happened. */
     action: AuditAction;
+    /** Id of the user or system that performed the action. */
     actorId: string;
+    /** Role the actor held at the time, when supplied via {@link AuditContext}. */
     actorRole?: string;
+    /** IP address the action originated from, when supplied via {@link AuditContext}. */
     actorIp?: string;
+    /** User agent the action originated from, when supplied via {@link AuditContext}. */
     actorUserAgent?: string;
+    /** Level the action applied to, or the current level for instance-wide actions. */
     level: number;
+    /** When the action happened. */
     timestamp: Date;
+    /** Caller-supplied trace id for correlating this entry with external logs. */
     traceId?: string;
+    /** Free-text comment attached to the action, if any. */
     comment?: string;
+    /** Reason given for the action (e.g. a rejection or override reason), if any. */
     reason?: string;
+    /** Id of the user this action routed to, for `'delegated'`/`'reassigned'`/`'escalated'` actions. */
     delegateTo?: string;
+    /** State the action changed from, shaped differently per {@link action}. */
     oldValue?: Record<string, unknown>;
+    /** State the action changed to, shaped differently per {@link action}. */
     newValue?: Record<string, unknown>;
 }
 /** Context injected by the caller on each mutating operation (for SOX/SOC2 compliance). */
@@ -237,6 +264,7 @@ interface AuditContext {
     actorUserAgent?: string;
     traceId?: string;
 }
+/** Runtime state of one level within an {@link ApprovalInstance} — its resolved approvers and how far it has progressed. */
 interface ApprovalLevelInstance {
     level: number;
     name: string;

package/dist/nestjs.cjs

@@ -557,6 +557,7 @@ var TemplateRegistry = class {
     delete resolved.removeLevels;
     return resolved;
   }
+  /** Register a new template. Throws if a template with this name already exists for the tenant. */
   async define(config) {
     const existing = await this.adapter.getTemplate(this.tenantId, config.name);
     if (existing) {
@@ -593,11 +594,13 @@ var TemplateRegistry = class {
     await this.adapter.saveTemplate(updated);
     return newId;
   }
+  /** Fetch a template by name. Throws if no template with this name exists for the tenant. */
   async get(name) {
     const template = await this.adapter.getTemplate(this.tenantId, name);
     if (!template) throw new ApprovalTemplateNotFoundError(name);
     return template;
   }
+  /** List every template registered for the tenant. */
   async list() {
     return this.adapter.listTemplates(this.tenantId);
   }
@@ -637,6 +640,32 @@ var LevelResolver = class {
     for (const [name, fn] of this.resolvers) target.register(name, fn);
     for (const [name, fn] of this.approverTypes) target.registerApproverType(name, fn);
   }
+  /**
+   * Resolve a level's `approvers` config down to a deduplicated list of user
+   * ids, applying out-of-office cover last so a substitute never sees a stale
+   * approver id.
+   *
+   * @param approvers - The level's approver configs (`user`, `role`,
+   *   `dynamic`, or a custom type registered via {@link registerApproverType}).
+   * @param submittedBy - Passed through to `dynamic` resolvers and custom
+   *   approver-type functions as routing context.
+   * @param data - The instance's document data, passed through the same way.
+   * @param orgProvider - Required to resolve `role` approvers; omit only when
+   *   the template uses no `role` approvers.
+   * @param outOfOffice - Optional cover lookup, consulted after every other
+   *   approver type has resolved.
+   * @param at - The moment out-of-office cover is resolved for. Defaults to
+   *   now.
+   * @param substitutions - Filled with `original -> stand-in` for each
+   *   approver replaced by out-of-office cover, so the caller can carry
+   *   anything keyed by the original id (such as a weighted level's vote
+   *   weight) across to the substitute.
+   * @returns The resolved, deduplicated approver ids (post-substitution).
+   * @throws {ApprovalValidationError} If no approvers resolve at all, a
+   *   `role` approver is configured without an `orgProvider`, a `dynamic`
+   *   approver names a resolver that was never registered, or a custom
+   *   approver type was never registered.
+   */
   async resolveApprovers(approvers, submittedBy, data, orgProvider, outOfOffice, at, substitutions) {
     const resolved = [];
     for (const approver of approvers) {
@@ -1048,7 +1077,7 @@ function evaluateConditions(conditions, data) {
 function assertStatus(instance, expected) {
   if (instance.status !== expected) {
     throw new ApprovalError(
-      `Expected instance status "${expected}" but got "${instance.status}".`,
+      `Instance "${instance.id}": expected status "${expected}" but got "${instance.status}".`,
       "INVALID_STATUS"
     );
   }
@@ -1056,7 +1085,7 @@ function assertStatus(instance, expected) {
 function assertApproverOnLevel(level, approverId) {
   if (!level.approverIds.includes(approverId)) {
     throw new ApprovalForbiddenError(
-      `User "${approverId}" is not an approver for level ${level.level}.`
+      `User "${approverId}" is not an approver for level ${level.level} ("${level.name}").`
     );
   }
 }
@@ -2100,7 +2129,7 @@ var ApprovalEngine = class _ApprovalEngine {
     await this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.fromApprover === opts.toApprover) {
-        throw new ApprovalForbiddenError("Cannot delegate to yourself.");
+        throw new ApprovalForbiddenError(`Cannot delegate to yourself: "${opts.fromApprover}".`);
       }
       const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       this.inheritWeight(level, opts.fromApprover, opts.toApprover);
@@ -2183,7 +2212,9 @@ var ApprovalEngine = class _ApprovalEngine {
     return this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.fromApprover === opts.toApprover) {
-        throw new ApprovalForbiddenError("Cannot reassign an approver to themselves.");
+        throw new ApprovalForbiddenError(
+          `Cannot reassign an approver to themselves: "${opts.fromApprover}".`
+        );
       }
       const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       this.inheritWeight(level, opts.fromApprover, opts.toApprover);
@@ -3009,7 +3040,15 @@ var ApprovalEngine = class _ApprovalEngine {
     }
     const levelNums = new Set(allLevelCfgs.map((l) => l.level));
     if (levelNums.size !== allLevelCfgs.length) {
-      throw new ApprovalValidationError("Duplicate level numbers after condition evaluation.");
+      const seen = /* @__PURE__ */ new Set();
+      const duplicates = /* @__PURE__ */ new Set();
+      for (const l of allLevelCfgs) {
+        if (seen.has(l.level)) duplicates.add(l.level);
+        seen.add(l.level);
+      }
+      throw new ApprovalValidationError(
+        `Duplicate level numbers after condition evaluation: ${[...duplicates].join(", ")}.`
+      );
     }
     const now = this.clock.now();
     const newInstanceId = this.generateId("inst");
@@ -3381,7 +3420,9 @@ var ApprovalEngine = class _ApprovalEngine {
         );
       }
       if (opts.overriddenBy === instance.submittedBy) {
-        throw new ApprovalForbiddenError("Override cannot be performed by the original submitter.");
+        throw new ApprovalForbiddenError(
+          `Override cannot be performed by the original submitter: "${opts.overriddenBy}".`
+        );
       }
       await this.runAuthorizationPolicy({
         operation: "override",
@@ -3875,7 +3916,9 @@ var ApprovalEngine = class _ApprovalEngine {
     const dryRun = opts.dryRun ?? false;
     const limit = opts.limit ?? DEFAULT_PURGE_LIMIT;
     if (!(opts.olderThan instanceof Date) || Number.isNaN(opts.olderThan.getTime())) {
-      throw new ApprovalValidationError("purgeInstances requires a valid olderThan date.");
+      throw new ApprovalValidationError(
+        `purgeInstances requires a valid olderThan date, got ${String(opts.olderThan)}.`
+      );
     }
     const requested = opts.statuses ?? [...TERMINAL_STATUSES];
     const nonTerminal = requested.filter((st) => !TERMINAL_STATUSES.has(st));
@@ -5114,6 +5157,11 @@ var HierarchicalApprovalModule = class _HierarchicalApprovalModule {
   constructor(engine) {
     this.engine = engine;
   }
+  /**
+   * Build the module synchronously from a fixed set of engine options.
+   * @param options - Engine configuration plus {@link HierarchicalApprovalModuleOptions.isGlobal}.
+   * @returns A Nest `DynamicModule` exporting the engine under {@link APPROVAL_ENGINE}.
+   */
   static forRoot(options) {
     const { isGlobal, ...engineOptions } = options;
     const engineProvider = {
@@ -5127,6 +5175,12 @@ var HierarchicalApprovalModule = class _HierarchicalApprovalModule {
       exports: [APPROVAL_ENGINE]
     };
   }
+  /**
+   * Build the module with engine options resolved asynchronously, e.g. from a
+   * `ConfigService` injected via {@link HierarchicalApprovalModuleAsyncOptions.inject}.
+   * @param options - Async factory and its imports/injected providers.
+   * @returns A Nest `DynamicModule` exporting the engine under {@link APPROVAL_ENGINE}.
+   */
   static forRootAsync(options) {
     const engineProvider = {
       provide: APPROVAL_ENGINE,