hierarchical-approval 4.0.2 → 4.0.3

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

@@ -13,8 +13,10 @@ 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;
 }
 type ResolverFn = (submittedBy: string, data: Record<string, unknown>) => Promise<string> | string;
@@ -145,8 +147,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 +220,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). */

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

@@ -13,8 +13,10 @@ 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;
 }
 type ResolverFn = (submittedBy: string, data: Record<string, unknown>) => Promise<string> | string;
@@ -145,8 +147,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 +220,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). */

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}").`
     );
   }
 }