hierarchical-approval 4.0.2 → 4.0.3

package/dist/index.d.cts

@@ -1,18 +1,18 @@
-export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, h as BusinessHoursCalendarOptions, C as CanApproveResult, i as CancelOptions, j as ChainExplanation, k as ConditionOperatorFn, l as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, m as ExplainedLevel, n as ExplainedRule, o as ExplainedSkip, H as HealthResult, I as IdGeneratorFn, p as IdempotencyKeyFn, q as ImportResult, O as OrgProvider, r as OutOfOfficeProvider, s as OverrideOptions, P as PreviewChainLevel, t as PreviewResult, u as ProvideInfoOptions, v as PurgeResult, R as ReassignOptions, w as RejectOptions, x as RequestInfoOptions, y as ResubmitOptions, z as RetryPolicy, S as SimulatedDecision, F as SimulationResult, G as SimulationStep, J as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, K as TemplateBundle, L as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, M as businessHoursCalendar, N as defaultIdGenerator, Q as toComparableNumber, X as validateConditionExpression, Y as weekendCalendar } from './ApprovalEngine-XgGBQLC_.cjs';
-import { I as IStorageAdapter } from './IStorageAdapter-Cjw5zDwQ.cjs';
-export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-Cjw5zDwQ.cjs';
-import { L as Logger } from './Logger-BplhlU7l.cjs';
-export { n as noopLogger } from './Logger-BplhlU7l.cjs';
-import { C as Clock } from './Clock-3FnOczFJ.cjs';
-export { s as systemClock } from './Clock-3FnOczFJ.cjs';
-export { A as AuthorizationContext, I as IAuthorizationPolicy } from './IAuthorizationPolicy-YJ_08Mof.cjs';
-export { A as ApprovalConflictError, a as ApprovalError, b as ApprovalForbiddenError, c as ApprovalNotFoundError, d as ApprovalTemplateNotFoundError, e as ApprovalValidationError, I as IOperationMiddleware, O as OperationContext } from './IOperationMiddleware-BBLk8MIz.cjs';
+export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, h as BusinessHoursCalendarOptions, C as CanApproveResult, i as CancelOptions, j as ChainExplanation, k as ConditionOperatorFn, l as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, m as ExplainedLevel, n as ExplainedRule, o as ExplainedSkip, H as HealthResult, I as IdGeneratorFn, p as IdempotencyKeyFn, q as ImportResult, O as OrgProvider, r as OutOfOfficeProvider, s as OverrideOptions, P as PreviewChainLevel, t as PreviewResult, u as ProvideInfoOptions, v as PurgeResult, R as ReassignOptions, w as RejectOptions, x as RequestInfoOptions, y as ResubmitOptions, z as RetryPolicy, S as SimulatedDecision, F as SimulationResult, G as SimulationStep, J as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, K as TemplateBundle, L as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, M as businessHoursCalendar, N as defaultIdGenerator, Q as toComparableNumber, X as validateConditionExpression, Y as weekendCalendar } from './ApprovalEngine-Djdw-JzA.cjs';
+import { I as IStorageAdapter } from './IStorageAdapter-D7cy20uD.cjs';
+export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-D7cy20uD.cjs';
+import { L as Logger } from './Logger-hqFbBCtB.cjs';
+export { n as noopLogger } from './Logger-hqFbBCtB.cjs';
+import { C as Clock } from './Clock-D8Qp39q_.cjs';
+export { s as systemClock } from './Clock-D8Qp39q_.cjs';
+export { A as AuthorizationContext, I as IAuthorizationPolicy } from './IAuthorizationPolicy-D6tTT3gv.cjs';
+export { A as ApprovalConflictError, a as ApprovalError, b as ApprovalForbiddenError, c as ApprovalNotFoundError, d as ApprovalTemplateNotFoundError, e as ApprovalValidationError, I as IOperationMiddleware, O as OperationContext } from './IOperationMiddleware-D3Yelw9R.cjs';
 export { MemoryAdapter } from './adapters/MemoryAdapter.cjs';
-export { A as ApprovalEvent, a as ApprovalEventMap, b as ApprovalEventName, c as ApprovedEvent, d as AttachmentEvent, C as CancelledEvent, e as CommentedEvent, D as DataUpdatedEvent, f as DelegatedEvent, E as EscalatedEvent, g as ExpiredEvent, H as HistoryEntry, I as INotificationAdapter, h as InfoProvidedEvent, i as InfoRequestedEvent, L as LevelAdvancedEvent, N as NotificationEvent, O as OverriddenEvent, R as ReassignedEvent, j as RejectedEvent, k as ReminderEvent, l as ResubmittedEvent, S as SlaBreachedEvent, m as SubWorkflowEvent, n as SubmittedEvent } from './INotificationAdapter-XbD69gss.cjs';
-export { I as IAuditAdapter } from './IAuditAdapter-Dt8qjkQL.cjs';
-export { I as IMetricsAdapter, M as MetricName } from './IMetricsAdapter-DWq8IFaf.cjs';
+export { A as ApprovalEvent, a as ApprovalEventMap, b as ApprovalEventName, c as ApprovedEvent, d as AttachmentEvent, C as CancelledEvent, e as CommentedEvent, D as DataUpdatedEvent, f as DelegatedEvent, E as EscalatedEvent, g as ExpiredEvent, H as HistoryEntry, I as INotificationAdapter, h as InfoProvidedEvent, i as InfoRequestedEvent, L as LevelAdvancedEvent, N as NotificationEvent, O as OverriddenEvent, R as ReassignedEvent, j as RejectedEvent, k as ReminderEvent, l as ResubmittedEvent, S as SlaBreachedEvent, m as SubWorkflowEvent, n as SubmittedEvent } from './INotificationAdapter-CBsJDk-Y.cjs';
+export { I as IAuditAdapter } from './IAuditAdapter-TT2Xhtu6.cjs';
+export { I as IMetricsAdapter, M as MetricName } from './IMetricsAdapter-WROxYSXd.cjs';
 export { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-export { a as ApprovalInstance, c as ApprovalLevelConfig, d as ApprovalLevelInstance, e as ApprovalMode, f as ApprovalStatus, A as ApprovalTemplate, g as ApprovalTemplateConfig, h as ApproverConfig, i as Attachment, j as AuditAction, k as AuditContext, b as AuditEntry, C as Comment, l as Condition, m as ConditionExpression, n as ConditionGroup, o as ConditionOperator, p as ConditionRule, E as EscalationConfig, q as EscalationStep, I as InfoRequest, L as LevelStatus, R as ResolvedApprover, r as ResolverFn, S as SubWorkflowConfig, T as TemplateSnapshot } from './instance-uUQh5XW3.cjs';
+export { a as ApprovalInstance, c as ApprovalLevelConfig, d as ApprovalLevelInstance, e as ApprovalMode, f as ApprovalStatus, A as ApprovalTemplate, g as ApprovalTemplateConfig, h as ApproverConfig, i as Attachment, j as AuditAction, k as AuditContext, b as AuditEntry, C as Comment, l as Condition, m as ConditionExpression, n as ConditionGroup, o as ConditionOperator, p as ConditionRule, E as EscalationConfig, q as EscalationStep, I as InfoRequest, L as LevelStatus, R as ResolvedApprover, r as ResolverFn, S as SubWorkflowConfig, T as TemplateSnapshot } from './instance-Dd1jQizG.cjs';
 import 'zod';
 
 interface EscalationSchedulerOpts {

package/dist/index.d.ts

@@ -1,18 +1,18 @@
-export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, h as BusinessHoursCalendarOptions, C as CanApproveResult, i as CancelOptions, j as ChainExplanation, k as ConditionOperatorFn, l as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, m as ExplainedLevel, n as ExplainedRule, o as ExplainedSkip, H as HealthResult, I as IdGeneratorFn, p as IdempotencyKeyFn, q as ImportResult, O as OrgProvider, r as OutOfOfficeProvider, s as OverrideOptions, P as PreviewChainLevel, t as PreviewResult, u as ProvideInfoOptions, v as PurgeResult, R as ReassignOptions, w as RejectOptions, x as RequestInfoOptions, y as ResubmitOptions, z as RetryPolicy, S as SimulatedDecision, F as SimulationResult, G as SimulationStep, J as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, K as TemplateBundle, L as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, M as businessHoursCalendar, N as defaultIdGenerator, Q as toComparableNumber, X as validateConditionExpression, Y as weekendCalendar } from './ApprovalEngine-Dqe-rC6K.js';
-import { I as IStorageAdapter } from './IStorageAdapter-CdXMggPK.js';
-export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-CdXMggPK.js';
-import { L as Logger } from './Logger-BplhlU7l.js';
-export { n as noopLogger } from './Logger-BplhlU7l.js';
-import { C as Clock } from './Clock-3FnOczFJ.js';
-export { s as systemClock } from './Clock-3FnOczFJ.js';
-export { A as AuthorizationContext, I as IAuthorizationPolicy } from './IAuthorizationPolicy-eo6glbpE.js';
-export { A as ApprovalConflictError, a as ApprovalError, b as ApprovalForbiddenError, c as ApprovalNotFoundError, d as ApprovalTemplateNotFoundError, e as ApprovalValidationError, I as IOperationMiddleware, O as OperationContext } from './IOperationMiddleware-CX7lo4lp.js';
+export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, h as BusinessHoursCalendarOptions, C as CanApproveResult, i as CancelOptions, j as ChainExplanation, k as ConditionOperatorFn, l as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, m as ExplainedLevel, n as ExplainedRule, o as ExplainedSkip, H as HealthResult, I as IdGeneratorFn, p as IdempotencyKeyFn, q as ImportResult, O as OrgProvider, r as OutOfOfficeProvider, s as OverrideOptions, P as PreviewChainLevel, t as PreviewResult, u as ProvideInfoOptions, v as PurgeResult, R as ReassignOptions, w as RejectOptions, x as RequestInfoOptions, y as ResubmitOptions, z as RetryPolicy, S as SimulatedDecision, F as SimulationResult, G as SimulationStep, J as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, K as TemplateBundle, L as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, M as businessHoursCalendar, N as defaultIdGenerator, Q as toComparableNumber, X as validateConditionExpression, Y as weekendCalendar } from './ApprovalEngine-BtgQDr_8.js';
+import { I as IStorageAdapter } from './IStorageAdapter-CVvNsnnD.js';
+export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-CVvNsnnD.js';
+import { L as Logger } from './Logger-hqFbBCtB.js';
+export { n as noopLogger } from './Logger-hqFbBCtB.js';
+import { C as Clock } from './Clock-D8Qp39q_.js';
+export { s as systemClock } from './Clock-D8Qp39q_.js';
+export { A as AuthorizationContext, I as IAuthorizationPolicy } from './IAuthorizationPolicy-wIE1mpTy.js';
+export { A as ApprovalConflictError, a as ApprovalError, b as ApprovalForbiddenError, c as ApprovalNotFoundError, d as ApprovalTemplateNotFoundError, e as ApprovalValidationError, I as IOperationMiddleware, O as OperationContext } from './IOperationMiddleware-C7ciNnJp.js';
 export { MemoryAdapter } from './adapters/MemoryAdapter.js';
-export { A as ApprovalEvent, a as ApprovalEventMap, b as ApprovalEventName, c as ApprovedEvent, d as AttachmentEvent, C as CancelledEvent, e as CommentedEvent, D as DataUpdatedEvent, f as DelegatedEvent, E as EscalatedEvent, g as ExpiredEvent, H as HistoryEntry, I as INotificationAdapter, h as InfoProvidedEvent, i as InfoRequestedEvent, L as LevelAdvancedEvent, N as NotificationEvent, O as OverriddenEvent, R as ReassignedEvent, j as RejectedEvent, k as ReminderEvent, l as ResubmittedEvent, S as SlaBreachedEvent, m as SubWorkflowEvent, n as SubmittedEvent } from './INotificationAdapter-BTO9FSKy.js';
-export { I as IAuditAdapter } from './IAuditAdapter-DkbyFFjb.js';
-export { I as IMetricsAdapter, M as MetricName } from './IMetricsAdapter-DWq8IFaf.js';
+export { A as ApprovalEvent, a as ApprovalEventMap, b as ApprovalEventName, c as ApprovedEvent, d as AttachmentEvent, C as CancelledEvent, e as CommentedEvent, D as DataUpdatedEvent, f as DelegatedEvent, E as EscalatedEvent, g as ExpiredEvent, H as HistoryEntry, I as INotificationAdapter, h as InfoProvidedEvent, i as InfoRequestedEvent, L as LevelAdvancedEvent, N as NotificationEvent, O as OverriddenEvent, R as ReassignedEvent, j as RejectedEvent, k as ReminderEvent, l as ResubmittedEvent, S as SlaBreachedEvent, m as SubWorkflowEvent, n as SubmittedEvent } from './INotificationAdapter-BcUskJ6z.js';
+export { I as IAuditAdapter } from './IAuditAdapter-C-04ar9A.js';
+export { I as IMetricsAdapter, M as MetricName } from './IMetricsAdapter-WROxYSXd.js';
 export { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-export { a as ApprovalInstance, c as ApprovalLevelConfig, d as ApprovalLevelInstance, e as ApprovalMode, f as ApprovalStatus, A as ApprovalTemplate, g as ApprovalTemplateConfig, h as ApproverConfig, i as Attachment, j as AuditAction, k as AuditContext, b as AuditEntry, C as Comment, l as Condition, m as ConditionExpression, n as ConditionGroup, o as ConditionOperator, p as ConditionRule, E as EscalationConfig, q as EscalationStep, I as InfoRequest, L as LevelStatus, R as ResolvedApprover, r as ResolverFn, S as SubWorkflowConfig, T as TemplateSnapshot } from './instance-uUQh5XW3.js';
+export { a as ApprovalInstance, c as ApprovalLevelConfig, d as ApprovalLevelInstance, e as ApprovalMode, f as ApprovalStatus, A as ApprovalTemplate, g as ApprovalTemplateConfig, h as ApproverConfig, i as Attachment, j as AuditAction, k as AuditContext, b as AuditEntry, C as Comment, l as Condition, m as ConditionExpression, n as ConditionGroup, o as ConditionOperator, p as ConditionRule, E as EscalationConfig, q as EscalationStep, I as InfoRequest, L as LevelStatus, R as ResolvedApprover, r as ResolverFn, S as SubWorkflowConfig, T as TemplateSnapshot } from './instance-Dd1jQizG.js';
 import 'zod';
 
 interface EscalationSchedulerOpts {

package/dist/index.js

@@ -550,6 +550,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) {
@@ -586,11 +587,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);
   }
@@ -630,6 +633,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) {
@@ -1041,7 +1070,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"
     );
   }
@@ -1049,7 +1078,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}").`
     );
   }
 }
@@ -5164,7 +5193,7 @@ function businessHoursCalendar(options = {}) {
       return cursor;
     }
     throw new Error(
-      "businessHoursCalendar: no working day found within 10 years of the start date."
+      `businessHoursCalendar: no working day found within 10 years of ${from.toISOString()} \u2014 check weekendDays and holidays.`
     );
   };
   const base = weekendCalendar(options);