@objectstack/plugin-approvals 9.0.0 → 9.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/plugin-approvals@9.0.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
+> @objectstack/plugin-approvals@9.1.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     56.08 KB
-ESM dist/index.mjs.map 98.07 KB
-ESM ⚡️ Build success in 152ms
-CJS dist/index.js     57.41 KB
-CJS dist/index.js.map 99.25 KB
-CJS ⚡️ Build success in 159ms
+ESM dist/index.mjs     63.58 KB
+ESM dist/index.mjs.map 112.27 KB
+ESM ⚡️ Build success in 137ms
+CJS dist/index.js     64.93 KB
+CJS dist/index.js.map 113.45 KB
+CJS ⚡️ Build success in 138ms
 DTS Build start
-DTS ⚡️ Build success in 19242ms
-DTS dist/index.d.mts 332.92 KB
-DTS dist/index.d.ts  332.92 KB
+DTS ⚡️ Build success in 25539ms
+DTS dist/index.d.mts 334.31 KB
+DTS dist/index.d.ts  334.31 KB

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @objectstack/plugin-approvals
 
+## 9.1.0
+
+### Patch Changes
+
+- Updated dependencies [b9062c9]
+  - @objectstack/spec@9.1.0
+  - @objectstack/core@9.1.0
+  - @objectstack/formula@9.1.0
+  - @objectstack/metadata-core@9.1.0
+  - @objectstack/platform-objects@9.1.0
+
+## 9.0.1
+
+### Patch Changes
+
+- Updated dependencies [1817845]
+  - @objectstack/spec@9.0.1
+  - @objectstack/core@9.0.1
+  - @objectstack/formula@9.0.1
+  - @objectstack/metadata-core@9.0.1
+  - @objectstack/platform-objects@9.0.1
+
 ## 9.0.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _objectstack_spec_data from '@objectstack/spec/data';
 import { ApprovalNodeConfig } from '@objectstack/spec/automation';
-import { IApprovalService, SharingExecutionContext, ApprovalRequestRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalStatus, ApprovalActionRow } from '@objectstack/spec/contracts';
+import { IApprovalService, SharingExecutionContext, ApprovalRequestRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalRecallInput, ApprovalRecallResult, ApprovalStatus, ApprovalActionRow } from '@objectstack/spec/contracts';
 export { ApprovalActionRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalRequestRow, ApprovalStatus, IApprovalService } from '@objectstack/spec/contracts';
 import { Plugin, PluginContext } from '@objectstack/core';
 
@@ -7502,6 +7502,10 @@ declare class ApprovalService implements IApprovalService {
         nodeId: string;
         config: ApprovalNodeConfig;
         flowName?: string;
+        /** Authored flow label, snapshotted for inbox display. */
+        flowLabel?: string;
+        /** Authored node label, snapshotted for inbox display. */
+        nodeLabel?: string;
         submitterId?: string | null;
         record?: any;
         organizationId?: string | null;
@@ -7530,6 +7534,28 @@ declare class ApprovalService implements IApprovalService {
      * resumes the owning flow run down the matching `approve` / `reject` edge.
      */
     decide(requestId: string, input: ApprovalDecisionInput, context: SharingExecutionContext): Promise<ApprovalDecisionResult>;
+    /**
+     * Withdraw a pending request (submitter only). Finalises the row as
+     * `recalled`, releases the record lock (keyed on pending status), mirrors
+     * the status field when configured, and resumes the owning flow run down
+     * the `reject` branch with `output.decision = 'recall'` — the engine has no
+     * run-cancel primitive, and leaving the run suspended forever would leak it.
+     */
+    recall(requestId: string, input: ApprovalRecallInput, context: SharingExecutionContext): Promise<ApprovalRecallResult>;
+    /**
+     * Resolve the schema-declared display field for an object, when the engine
+     * exposes schema metadata (`getSchema`). Falls back to common title-ish
+     * field names so plain `ApprovalEngine` fakes still enrich sensibly.
+     */
+    private resolveDisplayField;
+    private static pickTitle;
+    /**
+     * Attach inbox display fields (`record_title`, `submitter_name`) to rows.
+     * Batched: one query per distinct target object plus one `sys_user` lookup.
+     * Best-effort — a deleted record falls back to the payload snapshot, and a
+     * lookup failure leaves the field unset rather than failing the list.
+     */
+    private enrichRows;
     listRequests(filter: {
         object?: string;
         recordId?: string;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _objectstack_spec_data from '@objectstack/spec/data';
 import { ApprovalNodeConfig } from '@objectstack/spec/automation';
-import { IApprovalService, SharingExecutionContext, ApprovalRequestRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalStatus, ApprovalActionRow } from '@objectstack/spec/contracts';
+import { IApprovalService, SharingExecutionContext, ApprovalRequestRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalRecallInput, ApprovalRecallResult, ApprovalStatus, ApprovalActionRow } from '@objectstack/spec/contracts';
 export { ApprovalActionRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalRequestRow, ApprovalStatus, IApprovalService } from '@objectstack/spec/contracts';
 import { Plugin, PluginContext } from '@objectstack/core';
 
@@ -7502,6 +7502,10 @@ declare class ApprovalService implements IApprovalService {
         nodeId: string;
         config: ApprovalNodeConfig;
         flowName?: string;
+        /** Authored flow label, snapshotted for inbox display. */
+        flowLabel?: string;
+        /** Authored node label, snapshotted for inbox display. */
+        nodeLabel?: string;
         submitterId?: string | null;
         record?: any;
         organizationId?: string | null;
@@ -7530,6 +7534,28 @@ declare class ApprovalService implements IApprovalService {
      * resumes the owning flow run down the matching `approve` / `reject` edge.
      */
     decide(requestId: string, input: ApprovalDecisionInput, context: SharingExecutionContext): Promise<ApprovalDecisionResult>;
+    /**
+     * Withdraw a pending request (submitter only). Finalises the row as
+     * `recalled`, releases the record lock (keyed on pending status), mirrors
+     * the status field when configured, and resumes the owning flow run down
+     * the `reject` branch with `output.decision = 'recall'` — the engine has no
+     * run-cancel primitive, and leaving the run suspended forever would leak it.
+     */
+    recall(requestId: string, input: ApprovalRecallInput, context: SharingExecutionContext): Promise<ApprovalRecallResult>;
+    /**
+     * Resolve the schema-declared display field for an object, when the engine
+     * exposes schema metadata (`getSchema`). Falls back to common title-ish
+     * field names so plain `ApprovalEngine` fakes still enrich sensibly.
+     */
+    private resolveDisplayField;
+    private static pickTitle;
+    /**
+     * Attach inbox display fields (`record_title`, `submitter_name`) to rows.
+     * Batched: one query per distinct target object plus one `sys_user` lookup.
+     * Best-effort — a deleted record falls back to the payload snapshot, and a
+     * lookup failure leaves the field unset rather than failing the list.
+     */
+    private enrichRows;
     listRequests(filter: {
         object?: string;
         recordId?: string;

package/dist/index.js

@@ -976,7 +976,14 @@ function csvSplit(raw) {
   if (Array.isArray(raw)) return raw.map(String).filter(Boolean);
   return String(raw).split(",").map((s) => s.trim()).filter(Boolean);
 }
+function prettifyMachineName(raw) {
+  if (!raw) return void 0;
+  const base = String(raw).replace(/^flow:/, "").trim();
+  if (!base) return void 0;
+  return base.split(/[_\-\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
 function rowFromRequest(row) {
+  const cfg = parseJson(row.node_config_json, void 0);
   return {
     id: String(row.id),
     organization_id: row.organization_id ?? void 0,
@@ -994,7 +1001,11 @@ function rowFromRequest(row) {
     flow_node_id: row.flow_node_id ?? void 0,
     completed_at: row.completed_at ?? void 0,
     created_at: row.created_at ?? void 0,
-    updated_at: row.updated_at ?? void 0
+    updated_at: row.updated_at ?? void 0,
+    // The row is created at submission time; expose the stable inbox-facing name.
+    submitted_at: row.created_at ?? void 0,
+    process_label: cfg?.__flowLabel ?? prettifyMachineName(row.process_name),
+    step_label: cfg?.__nodeLabel ?? prettifyMachineName(row.current_step)
   };
 }
 function rowFromAction(row) {
@@ -1009,7 +1020,7 @@ function rowFromAction(row) {
     created_at: row.created_at ?? void 0
   };
 }
-var ApprovalService = class {
+var ApprovalService = class _ApprovalService {
   constructor(opts) {
     this.engine = opts.engine;
     this.clock = opts.clock ?? { now: () => /* @__PURE__ */ new Date() };
@@ -1211,6 +1222,9 @@ var ApprovalService = class {
     const now = this.clock.now().toISOString();
     const id = uid("areq");
     const processName = `flow:${input.flowName ?? input.nodeId}`;
+    const configSnapshot = { ...input.config };
+    if (input.flowLabel) configSnapshot.__flowLabel = input.flowLabel;
+    if (input.nodeLabel) configSnapshot.__nodeLabel = input.nodeLabel;
     const row = {
       id,
       process_name: processName,
@@ -1224,7 +1238,7 @@ var ApprovalService = class {
       payload_json: input.record != null ? JSON.stringify(input.record) : null,
       flow_run_id: input.runId,
       flow_node_id: input.nodeId,
-      node_config_json: JSON.stringify(input.config),
+      node_config_json: JSON.stringify(configSnapshot),
       organization_id: ctxOrg,
       created_at: now,
       updated_at: now
@@ -1356,6 +1370,172 @@ var ApprovalService = class {
       resumed
     };
   }
+  /**
+   * Withdraw a pending request (submitter only). Finalises the row as
+   * `recalled`, releases the record lock (keyed on pending status), mirrors
+   * the status field when configured, and resumes the owning flow run down
+   * the `reject` branch with `output.decision = 'recall'` — the engine has no
+   * run-cancel primitive, and leaving the run suspended forever would leak it.
+   */
+  async recall(requestId, input, context) {
+    if (!requestId) throw new Error("VALIDATION_FAILED: requestId is required");
+    if (!input?.actorId) throw new Error("VALIDATION_FAILED: actorId is required");
+    const rawRows = await this.engine.find("sys_approval_request", {
+      where: { id: requestId },
+      limit: 1,
+      context: SYSTEM_CTX
+    });
+    const raw = Array.isArray(rawRows) ? rawRows[0] : null;
+    if (!raw) throw new Error(`REQUEST_NOT_FOUND: ${requestId}`);
+    if (raw.status !== "pending") throw new Error(`INVALID_STATE: request is ${raw.status}`);
+    if (!context.isSystem && raw.submitter_id && String(raw.submitter_id) !== String(input.actorId)) {
+      throw new Error(`FORBIDDEN: only the submitter may recall this request`);
+    }
+    const config = parseJson(raw.node_config_json, { approvers: [], behavior: "first_response" });
+    const org = raw.organization_id ?? null;
+    const nodeId = raw.flow_node_id ?? raw.current_step ?? null;
+    const runId = raw.flow_run_id ?? null;
+    const now = this.clock.now().toISOString();
+    await this.engine.insert("sys_approval_action", {
+      id: uid("aact"),
+      request_id: requestId,
+      organization_id: org,
+      step_name: nodeId,
+      step_index: 0,
+      action: "recall",
+      actor_id: input.actorId,
+      comment: input.comment ?? null,
+      created_at: now
+    }, { context: SYSTEM_CTX });
+    await this.engine.update("sys_approval_request", {
+      id: requestId,
+      status: "recalled",
+      pending_approvers: null,
+      completed_at: now,
+      updated_at: now
+    }, { context: SYSTEM_CTX });
+    if (config.approvalStatusField) {
+      await this.mirrorStatusField(raw.object_name, raw.record_id, config.approvalStatusField, "recalled");
+    }
+    let resumed = false;
+    if (runId && typeof this.automation?.resume === "function") {
+      try {
+        await this.automation.resume(runId, {
+          branchLabel: import_automation.APPROVAL_BRANCH_LABELS.reject,
+          output: { decision: "recall", requestId }
+        });
+        resumed = true;
+      } catch (err) {
+        this.logger?.warn?.("[approvals] resume after recall failed", {
+          request: requestId,
+          run: runId,
+          error: err?.message ?? String(err)
+        });
+      }
+    }
+    const fresh = await this.getRequest(requestId, context);
+    return { request: fresh, runId, resumed };
+  }
+  // ── Display enrichment ───────────────────────────────────────
+  /**
+   * Resolve the schema-declared display field for an object, when the engine
+   * exposes schema metadata (`getSchema`). Falls back to common title-ish
+   * field names so plain `ApprovalEngine` fakes still enrich sensibly.
+   */
+  resolveDisplayField(object) {
+    try {
+      const schema = this.engine.getSchema?.(object);
+      const fields = schema?.fields ?? {};
+      const declared = schema?.displayNameField;
+      if (declared && declared !== "id" && fields[declared]) return declared;
+      for (const cand of ["name", "title", "subject", "label"]) {
+        if (fields[cand]) return cand;
+      }
+    } catch {
+    }
+    return void 0;
+  }
+  static pickTitle(rec, displayField) {
+    const candidates = displayField ? [displayField, "name", "title", "subject", "label"] : ["name", "title", "subject", "label"];
+    for (const f of candidates) {
+      const v = rec?.[f];
+      if (v != null && String(v).trim() && f !== "id") return String(v);
+    }
+    return void 0;
+  }
+  /**
+   * Attach inbox display fields (`record_title`, `submitter_name`) to rows.
+   * Batched: one query per distinct target object plus one `sys_user` lookup.
+   * Best-effort — a deleted record falls back to the payload snapshot, and a
+   * lookup failure leaves the field unset rather than failing the list.
+   */
+  async enrichRows(rows) {
+    if (!rows.length) return;
+    const byObject = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      if (!r.object_name || !r.record_id) continue;
+      let set = byObject.get(r.object_name);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        byObject.set(r.object_name, set);
+      }
+      set.add(r.record_id);
+    }
+    const titles = /* @__PURE__ */ new Map();
+    for (const [object, idSet] of byObject) {
+      const ids = Array.from(idSet);
+      const displayField = this.resolveDisplayField(object);
+      try {
+        const recs = await this.engine.find(object, {
+          where: { id: { $in: ids } },
+          limit: ids.length,
+          context: SYSTEM_CTX
+        });
+        for (const rec of recs ?? []) {
+          const title = _ApprovalService.pickTitle(rec, displayField);
+          if (rec?.id && title) titles.set(`${object}\0${rec.id}`, title);
+        }
+      } catch {
+      }
+    }
+    const submitters = Array.from(new Set(rows.map((r) => r.submitter_id).filter(Boolean)));
+    const names = /* @__PURE__ */ new Map();
+    if (submitters.length) {
+      try {
+        const users = await this.engine.find("sys_user", {
+          where: { id: { $in: submitters } },
+          fields: ["id", "name", "email"],
+          limit: submitters.length,
+          context: SYSTEM_CTX
+        });
+        for (const u of users ?? []) {
+          if (u?.id && (u.name || u.email)) names.set(String(u.id), String(u.name ?? u.email));
+        }
+      } catch {
+      }
+      const unresolvedEmails = submitters.filter((s) => !names.has(s) && s.includes("@"));
+      if (unresolvedEmails.length) {
+        try {
+          const users = await this.engine.find("sys_user", {
+            where: { email: { $in: unresolvedEmails } },
+            fields: ["email", "name"],
+            limit: unresolvedEmails.length,
+            context: SYSTEM_CTX
+          });
+          for (const u of users ?? []) {
+            if (u?.email && u.name) names.set(String(u.email), String(u.name));
+          }
+        } catch {
+        }
+      }
+    }
+    for (const r of rows) {
+      const title = titles.get(`${r.object_name}\0${r.record_id}`) ?? _ApprovalService.pickTitle(r.payload, void 0);
+      if (title) r.record_title = title;
+      const name = r.submitter_id ? names.get(String(r.submitter_id)) : void 0;
+      if (name) r.submitter_name = name;
+    }
+  }
   // ── Read API ─────────────────────────────────────────────────
   async listRequests(filter, context) {
     const f = {};
@@ -1384,6 +1564,7 @@ var ApprovalService = class {
         });
       }
     }
+    await this.enrichRows(list);
     return list;
   }
   async getRequest(requestId, context) {
@@ -1396,7 +1577,10 @@ var ApprovalService = class {
       limit: 1,
       context: SYSTEM_CTX
     });
-    return Array.isArray(rows) && rows[0] ? rowFromRequest(rows[0]) : null;
+    if (!Array.isArray(rows) || !rows[0]) return null;
+    const row = rowFromRequest(rows[0]);
+    await this.enrichRows([row]);
+    return row;
   }
   async listActions(requestId, context) {
     if (!requestId) return [];
@@ -1502,6 +1686,8 @@ function registerApprovalNode(automation, service, logger) {
       if (!runId) return { success: false, error: `Approval node '${node.id}': missing $runId` };
       if (!object) return { success: false, error: `Approval node '${node.id}': no target object in context` };
       if (!recordId) return { success: false, error: `Approval node '${node.id}': no record id in $record` };
+      const flowName = variables.get("$flowName") ?? context?.flowName;
+      const flowLabel = variables.get("$flowLabel");
       try {
         const request = await service.openNodeRequest({
           object,
@@ -1509,7 +1695,9 @@ function registerApprovalNode(automation, service, logger) {
           runId: String(runId),
           nodeId: node.id,
           config,
-          flowName: context?.flowName,
+          flowName,
+          flowLabel,
+          nodeLabel: typeof node.label === "string" ? node.label : void 0,
           submitterId: context?.userId ?? null,
           record,
           organizationId: context?.organizationId ?? context?.tenantId ?? null