hierarchical-approval 2.1.0 → 2.3.0

package/dist/nestjs.cjs

@@ -916,6 +916,7 @@ function computeTimingStats(samples) {
 
 // src/engine/ApprovalEngine.ts
 var MAX_SUBWORKFLOW_DEPTH = 5;
+var DEFAULT_PURGE_LIMIT = 1e3;
 var DEFAULT_MAX_REMINDERS = 3;
 var DEFAULT_MAX_ATTEMPTS = 3;
 var DEFAULT_BASE_DELAY_MS = 50;
@@ -927,6 +928,7 @@ var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
 ]);
 var CYCLE_TIME_STATUSES = ["approved", "rejected", "cancelled"];
 var CYCLE_TIME_FETCH_BATCH_SIZE = 500;
+var TEMPLATE_BUNDLE_VERSION = 1;
 var ApprovalEngine = class _ApprovalEngine {
   constructor(opts) {
     this.opts = opts;
@@ -3008,6 +3010,194 @@ var ApprovalEngine = class _ApprovalEngine {
       oldestAgeMs: Number.isFinite(row.oldest) ? now.getTime() - row.oldest : 0
     })).sort((a, b) => b.pending - a.pending || a.approverId.localeCompare(b.approverId));
   }
+  /**
+   * Export templates as a portable bundle.
+   *
+   * Approval configuration is written once and then has to travel — authored in
+   * a sandbox, reviewed, promoted to production. Reading `listTemplates()` and
+   * re-posting the rows carried each environment's own `id`, `tenantId` and
+   * version lineage with it, which either collided on arrival or silently
+   * claimed a history the target never had. This strips all of it.
+   *
+   * @param names - Templates to include; omit for all of them.
+   */
+  async exportTemplates(names) {
+    const all = await this.registry.list();
+    const wanted = names ? all.filter((t) => names.includes(t.name)) : all;
+    if (names) {
+      const missing = names.filter((n) => !all.some((t) => t.name === n));
+      if (missing.length > 0) {
+        throw new ApprovalTemplateNotFoundError(missing.join(", "));
+      }
+    }
+    return {
+      bundleVersion: TEMPLATE_BUNDLE_VERSION,
+      exportedAt: this.clock.now(),
+      templates: wanted.map((t) => {
+        const {
+          id: _id,
+          tenantId: _tenantId,
+          createdAt: _createdAt,
+          version: _version,
+          previousVersionId: _previousVersionId,
+          ...config
+        } = t;
+        return config;
+      })
+    };
+  }
+  /**
+   * Import a bundle produced by {@link exportTemplates}.
+   *
+   * **Every template is validated before any is written.** A bundle that is
+   * half-applied is worse than one rejected outright: the tenant is left in a
+   * state matching neither environment, and the operator has no way to tell
+   * which half landed. Per-template failures during the write phase are still
+   * reported individually, since a storage error can occur after validation
+   * passes.
+   *
+   * @param bundle - The bundle to apply.
+   * @param opts - `mode: 'create'` (default) refuses to touch existing
+   *   templates; `'upsert'` updates them. `dryRun` reports without writing.
+   */
+  async importTemplates(bundle, opts = {}) {
+    const mode = opts.mode ?? "create";
+    const dryRun = opts.dryRun ?? false;
+    if (bundle.bundleVersion !== TEMPLATE_BUNDLE_VERSION) {
+      throw new ApprovalValidationError(
+        `Unsupported template bundle version ${bundle.bundleVersion}; this engine reads version ${TEMPLATE_BUNDLE_VERSION}.`
+      );
+    }
+    if (!Array.isArray(bundle.templates) || bundle.templates.length === 0) {
+      throw new ApprovalValidationError("Template bundle contains no templates.");
+    }
+    const duplicates = bundle.templates.map((t) => t.name).filter((name, i, all) => all.indexOf(name) !== i);
+    if (duplicates.length > 0) {
+      throw new ApprovalValidationError(
+        `Template bundle contains duplicate names: ${[...new Set(duplicates)].join(", ")}.`
+      );
+    }
+    const invalid = [];
+    for (const config of bundle.templates) {
+      const result2 = this.validateTemplate(config);
+      if (!result2.valid) {
+        invalid.push({
+          name: config.name,
+          message: result2.errors[0]?.message ?? "unknown validation error"
+        });
+      }
+    }
+    if (invalid.length > 0) {
+      throw new ApprovalValidationError(
+        `Template bundle failed validation and was not applied: ${invalid.map((e) => `${e.name}: ${e.message}`).join("; ")}`
+      );
+    }
+    const result = { created: [], updated: [], skipped: [], errors: [], dryRun };
+    for (const config of bundle.templates) {
+      const existing = await this.opts.adapter.getTemplate(this.tenantId, config.name);
+      try {
+        if (existing && mode === "create") {
+          result.skipped.push(config.name);
+          continue;
+        }
+        if (existing) {
+          if (!dryRun) await this.registry.update(config);
+          result.updated.push(config.name);
+        } else {
+          if (!dryRun) await this.registry.define(config);
+          result.created.push(config.name);
+        }
+      } catch (err) {
+        result.errors.push({ name: config.name, message: err.message });
+      }
+    }
+    this.logger.info("importTemplates: bundle applied", {
+      tenantId: this.tenantId,
+      mode,
+      dryRun,
+      created: result.created.length,
+      updated: result.updated.length,
+      skipped: result.skipped.length,
+      errors: result.errors.length
+    });
+    return result;
+  }
+  /**
+   * Permanently remove finished approvals older than a cut-off.
+   *
+   * Approval tables only grow, and data-minimisation rules eventually require
+   * old records to go. There was no way to remove one, so operators reached
+   * around the library and deleted rows directly — which is exactly where
+   * orphaned audit rows and half-deleted instances come from.
+   *
+   * **Only terminal instances are eligible.** A pending approval is live work;
+   * deleting one would strand a document with no way to finish and no record of
+   * why. Passing a non-terminal status is rejected rather than quietly ignored,
+   * because a caller who asked to purge pending work has misunderstood
+   * something and should hear about it.
+   *
+   * This is irreversible and removes the audit trail with the instance. In many
+   * deployments that trail *is* the compliance record, which is why the
+   * underlying `deleteInstance` is an optional adapter method: an adapter that
+   * does not implement it makes the whole operation unavailable, and this
+   * throws rather than reporting a successful purge of nothing.
+   *
+   * @param opts - Cut-off, optional status/type scoping, safety limit, dry run.
+   * @returns What was removed, or would be under `dryRun`.
+   */
+  async purgeInstances(opts) {
+    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.");
+    }
+    const requested = opts.statuses ?? [...TERMINAL_STATUSES];
+    const nonTerminal = requested.filter((st) => !TERMINAL_STATUSES.has(st));
+    if (nonTerminal.length > 0) {
+      throw new ApprovalValidationError(
+        `purgeInstances refuses non-terminal statuses (${nonTerminal.join(", ")}): a pending approval is live work, and removing it would strand the document it belongs to.`
+      );
+    }
+    const deleteInstance = this.opts.adapter.deleteInstance?.bind(this.opts.adapter);
+    if (!deleteInstance && !dryRun) {
+      throw new ApprovalValidationError(
+        "The configured storage adapter does not implement deleteInstance(), so instances cannot be purged."
+      );
+    }
+    const result = { purged: [], scanned: 0, dryRun };
+    for (const status of requested) {
+      if (result.purged.length >= limit) break;
+      const page = await this.opts.adapter.getInstancesByFilter(
+        this.tenantId,
+        {
+          status,
+          toDate: opts.olderThan,
+          ...opts.documentType ? { documentType: opts.documentType } : {}
+        },
+        { limit, offset: 0 }
+      );
+      for (const instance of page.items) {
+        if (result.purged.length >= limit) break;
+        result.scanned++;
+        if (!TERMINAL_STATUSES.has(instance.status)) continue;
+        if (new Date(instance.createdAt) > opts.olderThan) continue;
+        if (!dryRun) await deleteInstance(this.tenantId, instance.id);
+        result.purged.push({
+          instanceId: instance.id,
+          documentId: instance.documentId,
+          status: instance.status
+        });
+      }
+    }
+    this.logger.info("purgeInstances: sweep complete", {
+      tenantId: this.tenantId,
+      olderThan: opts.olderThan.toISOString(),
+      scanned: result.scanned,
+      purged: result.purged.length,
+      dryRun
+    });
+    return result;
+  }
   async getStatistics(filter = {}) {
     const statuses = [
       "pending",