hierarchical-approval 4.0.7 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-10-12
+
+### Changed
+
+- `SubmitOptions` now describes what `submit` accepts: `data` and `metadata` are
+  optional (they default to `{}`) and `expiresAt` may be a `Date`, ISO string or
+  epoch milliseconds.
+
 ## [4.0.7] - 2026-09-28
 
 ### Fixed

package/dist/{ApprovalEngine-D5ZplHsw.d.cts → ApprovalEngine-CJQAHzxb.d.cts}

@@ -113,7 +113,14 @@ declare const UpdateDataOptionsSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     recomputeChain: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
+/**
+ * Input shape: `data` and `metadata` are optional because the schema defaults
+ * them. `expiresAt` is re-declared since zod types a coerced date's input as
+ * `unknown`, which would let any value through at compile time.
+ */
+type SubmitOptions = Omit<z.input<typeof SubmitOptionsSchema>, 'expiresAt'> & {
+    expiresAt?: Date | string | number;
+};
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
 type DelegateOptions = z.infer<typeof DelegateOptionsSchema>;
@@ -723,6 +730,17 @@ declare class ApprovalEngine {
      * @throws {@link ApprovalTemplateNotFoundError} if `raw.templateName` is not defined.
      * @throws {@link ApprovalValidationError} if `raw` fails schema validation, or if
      *   condition evaluation leaves no levels (or a duplicate level number) to open.
+     *
+     * @example
+     * ```ts
+     * const instance = await engine.submit({
+     *   templateName: 'purchase-order',
+     *   documentId: 'PO-1042',
+     *   documentType: 'purchase_order',
+     *   submittedBy: 'alice',
+     *   data: { amount: 12_500 },
+     * });
+     * ```
      */
     submit(raw: SubmitOptions, auditCtx?: AuditContext, 
     /**
@@ -752,6 +770,14 @@ declare class ApprovalEngine {
      *   configured {@link IAuthorizationPolicy}.
      * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
      *   open parallel level and `opts.level` was not supplied to disambiguate.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.approve(instance.id, {
+     *   approverId: 'bob',
+     *   comment: 'Within budget',
+     * });
+     * ```
      */
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -774,6 +800,15 @@ declare class ApprovalEngine {
      * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
      *   open parallel level with `opts.level` unset, or if `opts.returnTo === 'previous'`
      *   but the failing level is already the first level in the chain.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.reject(instance.id, {
+     *   approverId: 'bob',
+     *   reason: 'Over budget',
+     *   returnTo: 'previous',
+     * });
+     * ```
      */
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -792,6 +827,16 @@ declare class ApprovalEngine {
      *   configured {@link IAuthorizationPolicy}.
      * @throws {@link ApprovalValidationError} if `opts.fromApprover` sits on more than one
      *   open parallel level and `opts.level` was not supplied to disambiguate.
+     *
+     * @example
+     * ```ts
+     * await engine.delegate(instance.id, {
+     *   fromApprover: 'bob',
+     *   toApprover: 'carol',
+     *   reason: 'On leave',
+     *   until: new Date('2026-11-01'),
+     * });
+     * ```
      */
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
     /**
@@ -1003,11 +1048,16 @@ declare class ApprovalEngine {
      * theirs away), or they already voted on it.
      *
      * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+     *
+     * @example
+     * ```ts
+     * const check = await engine.canApprove(instance.id, 'bob');
+     * if (!check.eligible) console.log(check.reason);
+     * ```
      */
     canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
     /** 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.
      *
@@ -1030,7 +1080,15 @@ declare class ApprovalEngine {
      * @returns What moved, what did not, and why. With `dryRun` nothing is written.
      */
     transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
-    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
+    /**
+     * Approve multiple instances in one call. Never throws — failures collected in result.failed.
+     *
+     * @example
+     * ```ts
+     * const { succeeded, failed } = await engine.bulkApprove(ids, { approverId: 'bob' });
+     * for (const { instanceId, error } of failed) console.warn(instanceId, error.code);
+     * ```
+     */
     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>;
@@ -1040,7 +1098,14 @@ declare class ApprovalEngine {
      * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
      */
     getInstance(instanceId: string): Promise<ApprovalInstance>;
-    /** Page through every instance with an open level assigned to one approver. */
+    /**
+     * Page through every instance with an open level assigned to one approver.
+     *
+     * @example
+     * ```ts
+     * const page = await engine.getPendingFor('bob', { limit: 20, offset: 0 });
+     * ```
+     */
     getPendingFor(approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
     /** Page through instances matching an arbitrary filter (status, document type, date range, ...). */
     queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;

package/dist/{ApprovalEngine-sUWBHas4.d.ts → ApprovalEngine-DevN2HQ6.d.ts}

@@ -113,7 +113,14 @@ declare const UpdateDataOptionsSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     recomputeChain: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
+/**
+ * Input shape: `data` and `metadata` are optional because the schema defaults
+ * them. `expiresAt` is re-declared since zod types a coerced date's input as
+ * `unknown`, which would let any value through at compile time.
+ */
+type SubmitOptions = Omit<z.input<typeof SubmitOptionsSchema>, 'expiresAt'> & {
+    expiresAt?: Date | string | number;
+};
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
 type DelegateOptions = z.infer<typeof DelegateOptionsSchema>;
@@ -723,6 +730,17 @@ declare class ApprovalEngine {
      * @throws {@link ApprovalTemplateNotFoundError} if `raw.templateName` is not defined.
      * @throws {@link ApprovalValidationError} if `raw` fails schema validation, or if
      *   condition evaluation leaves no levels (or a duplicate level number) to open.
+     *
+     * @example
+     * ```ts
+     * const instance = await engine.submit({
+     *   templateName: 'purchase-order',
+     *   documentId: 'PO-1042',
+     *   documentType: 'purchase_order',
+     *   submittedBy: 'alice',
+     *   data: { amount: 12_500 },
+     * });
+     * ```
      */
     submit(raw: SubmitOptions, auditCtx?: AuditContext, 
     /**
@@ -752,6 +770,14 @@ declare class ApprovalEngine {
      *   configured {@link IAuthorizationPolicy}.
      * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
      *   open parallel level and `opts.level` was not supplied to disambiguate.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.approve(instance.id, {
+     *   approverId: 'bob',
+     *   comment: 'Within budget',
+     * });
+     * ```
      */
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -774,6 +800,15 @@ declare class ApprovalEngine {
      * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
      *   open parallel level with `opts.level` unset, or if `opts.returnTo === 'previous'`
      *   but the failing level is already the first level in the chain.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.reject(instance.id, {
+     *   approverId: 'bob',
+     *   reason: 'Over budget',
+     *   returnTo: 'previous',
+     * });
+     * ```
      */
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -792,6 +827,16 @@ declare class ApprovalEngine {
      *   configured {@link IAuthorizationPolicy}.
      * @throws {@link ApprovalValidationError} if `opts.fromApprover` sits on more than one
      *   open parallel level and `opts.level` was not supplied to disambiguate.
+     *
+     * @example
+     * ```ts
+     * await engine.delegate(instance.id, {
+     *   fromApprover: 'bob',
+     *   toApprover: 'carol',
+     *   reason: 'On leave',
+     *   until: new Date('2026-11-01'),
+     * });
+     * ```
      */
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
     /**
@@ -1003,11 +1048,16 @@ declare class ApprovalEngine {
      * theirs away), or they already voted on it.
      *
      * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+     *
+     * @example
+     * ```ts
+     * const check = await engine.canApprove(instance.id, 'bob');
+     * if (!check.eligible) console.log(check.reason);
+     * ```
      */
     canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
     /** 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.
      *
@@ -1030,7 +1080,15 @@ declare class ApprovalEngine {
      * @returns What moved, what did not, and why. With `dryRun` nothing is written.
      */
     transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
-    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
+    /**
+     * Approve multiple instances in one call. Never throws — failures collected in result.failed.
+     *
+     * @example
+     * ```ts
+     * const { succeeded, failed } = await engine.bulkApprove(ids, { approverId: 'bob' });
+     * for (const { instanceId, error } of failed) console.warn(instanceId, error.code);
+     * ```
+     */
     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>;
@@ -1040,7 +1098,14 @@ declare class ApprovalEngine {
      * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
      */
     getInstance(instanceId: string): Promise<ApprovalInstance>;
-    /** Page through every instance with an open level assigned to one approver. */
+    /**
+     * Page through every instance with an open level assigned to one approver.
+     *
+     * @example
+     * ```ts
+     * const page = await engine.getPendingFor('bob', { limit: 20, offset: 0 });
+     * ```
+     */
     getPendingFor(approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
     /** Page through instances matching an arbitrary filter (status, document type, date range, ...). */
     queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;

package/dist/index.cjs

@@ -1570,6 +1570,17 @@ var ApprovalEngine = class _ApprovalEngine {
    * @throws {@link ApprovalTemplateNotFoundError} if `raw.templateName` is not defined.
    * @throws {@link ApprovalValidationError} if `raw` fails schema validation, or if
    *   condition evaluation leaves no levels (or a duplicate level number) to open.
+   *
+   * @example
+   * ```ts
+   * const instance = await engine.submit({
+   *   templateName: 'purchase-order',
+   *   documentId: 'PO-1042',
+   *   documentType: 'purchase_order',
+   *   submittedBy: 'alice',
+   *   data: { amount: 12_500 },
+   * });
+   * ```
    */
   async submit(raw, auditCtx, link) {
     const opts = parseOrThrow(() => SubmitOptionsSchema.parse(raw));
@@ -1739,6 +1750,14 @@ var ApprovalEngine = class _ApprovalEngine {
    *   configured {@link IAuthorizationPolicy}.
    * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
    *   open parallel level and `opts.level` was not supplied to disambiguate.
+   *
+   * @example
+   * ```ts
+   * const updated = await engine.approve(instance.id, {
+   *   approverId: 'bob',
+   *   comment: 'Within budget',
+   * });
+   * ```
    */
   async approve(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => ApproveOptionsSchema.parse(raw));
@@ -1980,6 +1999,15 @@ var ApprovalEngine = class _ApprovalEngine {
    * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
    *   open parallel level with `opts.level` unset, or if `opts.returnTo === 'previous'`
    *   but the failing level is already the first level in the chain.
+   *
+   * @example
+   * ```ts
+   * const updated = await engine.reject(instance.id, {
+   *   approverId: 'bob',
+   *   reason: 'Over budget',
+   *   returnTo: 'previous',
+   * });
+   * ```
    */
   async reject(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => RejectOptionsSchema.parse(raw));
@@ -2123,6 +2151,16 @@ var ApprovalEngine = class _ApprovalEngine {
    *   configured {@link IAuthorizationPolicy}.
    * @throws {@link ApprovalValidationError} if `opts.fromApprover` sits on more than one
    *   open parallel level and `opts.level` was not supplied to disambiguate.
+   *
+   * @example
+   * ```ts
+   * await engine.delegate(instance.id, {
+   *   fromApprover: 'bob',
+   *   toApprover: 'carol',
+   *   reason: 'On leave',
+   *   until: new Date('2026-11-01'),
+   * });
+   * ```
    */
   async delegate(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => DelegateOptionsSchema.parse(raw));
@@ -3381,6 +3419,12 @@ var ApprovalEngine = class _ApprovalEngine {
    * theirs away), or they already voted on it.
    *
    * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+   *
+   * @example
+   * ```ts
+   * const check = await engine.canApprove(instance.id, 'bob');
+   * if (!check.eligible) console.log(check.reason);
+   * ```
    */
   async canApprove(instanceId, userId) {
     let instance;
@@ -3485,7 +3529,6 @@ var ApprovalEngine = class _ApprovalEngine {
     await this.afterDecision(overridden);
     return overridden;
   }
-  /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
   /**
    * Move every pending approval assigned to one person over to another.
    *
@@ -3575,7 +3618,15 @@ var ApprovalEngine = class _ApprovalEngine {
     });
     return result;
   }
-  /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
+  /**
+   * Approve multiple instances in one call. Never throws — failures collected in result.failed.
+   *
+   * @example
+   * ```ts
+   * const { succeeded, failed } = await engine.bulkApprove(ids, { approverId: 'bob' });
+   * for (const { instanceId, error } of failed) console.warn(instanceId, error.code);
+   * ```
+   */
   async bulkApprove(instanceIds, raw, auditCtx) {
     const opts = parseOrThrow(() => ApproveOptionsSchema.parse(raw));
     this.guardBulkSize(instanceIds);
@@ -3618,7 +3669,14 @@ var ApprovalEngine = class _ApprovalEngine {
   async getInstance(instanceId) {
     return this.requireInstance(instanceId);
   }
-  /** Page through every instance with an open level assigned to one approver. */
+  /**
+   * Page through every instance with an open level assigned to one approver.
+   *
+   * @example
+   * ```ts
+   * const page = await engine.getPendingFor('bob', { limit: 20, offset: 0 });
+   * ```
+   */
   async getPendingFor(approverId, opts) {
     return this.opts.adapter.getInstancesByApprover(this.tenantId, approverId, opts);
   }