@objectstack/plugin-approvals 9.2.0 → 9.4.0

package/src/approvals-plugin.ts

@@ -3,13 +3,32 @@
 import type { Plugin, PluginContext } from '@objectstack/core';
 import { SysApprovalRequest } from './sys-approval-request.object.js';
 import { SysApprovalAction } from './sys-approval-action.object.js';
-import { ApprovalService, type ApprovalEngine } from './approval-service.js';
+import { SysApprovalApprover } from './sys-approval-approver.object.js';
+import { SysApprovalToken } from './sys-approval-token.object.js';
+import { renderConfirmPage, renderResultPage } from './action-link-pages.js';
+import {
+  ApprovalService,
+  ESCALATION_JOB_NAME,
+  ESCALATION_SCAN_INTERVAL_MS,
+  type ApprovalEngine,
+} from './approval-service.js';
 import { bindApprovalLockHook, unbindAllHooks } from './lifecycle-hooks.js';
 import { registerApprovalNode, type ApprovalAutomationSurface } from './approval-node.js';
 
 export interface ApprovalsPluginOptions {
   /** Disable runtime registration (schemas still register). */
   disableService?: boolean;
+  /**
+   * Interval between SLA escalation scans (ADR-0042). Defaults to
+   * {@link ESCALATION_SCAN_INTERVAL_MS} (5 min). Only takes effect when a
+   * `job` service is installed; without one, SLA stays display-only.
+   */
+  escalationScanIntervalMs?: number;
+  /**
+   * Absolute origin for actionable links in outbound notifications
+   * (ADR-0043), e.g. `https://app.example.com`. Relative by default.
+   */
+  publicBaseUrl?: string;
   /**
    * Disable the record-lock hook. Schema + service stay intact; only the
    * engine-level lock wiring is suppressed. Useful when a caller wants the
@@ -36,6 +55,7 @@ export class ApprovalsServicePlugin implements Plugin {
   private readonly options: ApprovalsPluginOptions;
   private service?: ApprovalService;
   private engine?: any;
+  private escalationJobScheduled = false;
 
   constructor(options: ApprovalsPluginOptions = {}) {
     this.options = options;
@@ -50,7 +70,7 @@ export class ApprovalsServicePlugin implements Plugin {
       scope: 'system',
       defaultDatasource: 'cloud',
       namespace: 'sys',
-      objects: [SysApprovalRequest, SysApprovalAction],
+      objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken],
       // ADR-0029 D7 — contribute the Approvals entries into the Setup app's
       // `group_approvals` slot. This plugin owns these objects (K2.b), so it
       // ships their menu too; when the plugin isn't installed the slot is empty.
@@ -98,6 +118,7 @@ export class ApprovalsServicePlugin implements Plugin {
     this.service = new ApprovalService({
       engine: engine as ApprovalEngine,
       logger: ctx.logger,
+      publicBaseUrl: this.options.publicBaseUrl,
     });
 
     // Record lock: block edits to a record while it has a pending request.
@@ -113,6 +134,99 @@ export class ApprovalsServicePlugin implements Plugin {
     ctx.registerService('approvals', this.service);
     ctx.logger.info('ApprovalsServicePlugin: service registered');
 
+    // Optional messaging service (ADR-0012): thread interactions (reassign /
+    // remind / request-info / comment) notify users when present; without it
+    // they degrade to audit-only.
+    try {
+      const messaging = ctx.getService<any>('messaging');
+      if (messaging && typeof messaging.emit === 'function') {
+        this.service.attachMessaging(messaging);
+      }
+    } catch { /* messaging not installed */ }
+
+    // SLA escalation clock (ADR-0042): a plugin-internal job, deliberately
+    // NOT a flow trigger (ADR-0041 §1). Interval sweep + one catch-up scan at
+    // boot so a restart doesn't extend a breach by a scan period. Wired on
+    // kernel:ready — the job service may start after this plugin. No `job`
+    // service → SLA stays display-only.
+    const wireEscalationClock = async () => {
+      try {
+        const jobs = ctx.getService<any>('job');
+        if (!jobs || typeof jobs.schedule !== 'function' || !this.service) return;
+        const svc = this.service;
+        const intervalMs = this.options.escalationScanIntervalMs ?? ESCALATION_SCAN_INTERVAL_MS;
+        await jobs.schedule(ESCALATION_JOB_NAME, { type: 'interval', intervalMs }, async () => {
+          await svc.runEscalations();
+        });
+        this.escalationJobScheduled = true;
+        void svc.runEscalations().catch((err: any) => {
+          ctx.logger.warn?.('[approvals] boot escalation sweep failed', { error: err?.message });
+        });
+        ctx.logger.info('ApprovalsServicePlugin: SLA escalation scan scheduled', { intervalMs });
+      } catch { /* job service not installed */ }
+    };
+    // Actionable-link pages (ADR-0043): session-less confirm + redemption,
+    // mounted straight on the host Hono app. GET only renders; the decision
+    // happens exclusively on the POST (mail-gateway prefetch safe).
+    const mountActionPages = async () => {
+      try {
+        const http = ctx.getService<any>('http-server');
+        const rawApp = http && typeof http.getRawApp === 'function' ? http.getRawApp() : null;
+        if (!rawApp || !this.service) return;
+        const svc = this.service;
+        const ACT_PATH = '/api/v1/approvals/act';
+        const html = (c: any, body: string, status = 200) =>
+          c.body(body, status, { 'Content-Type': 'text/html; charset=utf-8' });
+        rawApp.get(ACT_PATH, async (c: any) => {
+          const token = String(c.req.query('token') ?? '');
+          const peek = await svc.peekActionToken(token);
+          if (!peek.ok) return html(c, renderResultPage(peek.reason, peek.request), 200);
+          return html(c, renderConfirmPage({
+            request: peek.request, action: peek.action, approverId: peek.approverId,
+            token, actPath: ACT_PATH,
+          }));
+        });
+        rawApp.post(ACT_PATH, async (c: any) => {
+          let token = '';
+          try {
+            const body = await c.req.parseBody();
+            token = String(body?.token ?? '');
+          } catch { /* fall through to invalid */ }
+          const out = await svc.redeemActionToken(token);
+          if (!out.ok) return html(c, renderResultPage(out.reason, out.request), 200);
+          return html(c, renderResultPage(out.action === 'approve' ? 'approved' : 'rejected', out.request));
+        });
+        ctx.logger.info(`ApprovalsServicePlugin: actionable-link pages mounted at ${ACT_PATH}`);
+      } catch { /* http server not installed */ }
+    };
+
+    // Pending-approver index backfill (issue #1745): rebuild the normalized
+    // sys_approval_approver rows from the pending_approvers CSV so requests
+    // written before the index existed (or drifted past a crashed sync) are
+    // queryable. Idempotent; cost tracks the live pending queue.
+    const backfillApproverIndex = async () => {
+      try {
+        const svc = this.service;
+        if (!svc) return;
+        const out = await svc.rebuildApproverIndex();
+        if (out.inserted > 0 || out.deleted > 0) {
+          ctx.logger.info('ApprovalsServicePlugin: approver index rebuilt', out);
+        }
+      } catch (err: any) {
+        ctx.logger.warn?.('[approvals] approver index backfill failed', { error: err?.message });
+      }
+    };
+
+    if (typeof (ctx as any).hook === 'function') {
+      (ctx as any).hook('kernel:ready', wireEscalationClock);
+      (ctx as any).hook('kernel:ready', mountActionPages);
+      (ctx as any).hook('kernel:ready', backfillApproverIndex);
+    } else {
+      await wireEscalationClock();
+      await mountActionPages();
+      await backfillApproverIndex();
+    }
+
     // ADR-0019: contribute the `approval` node to the flow engine when one is
     // present. The node lets a flow suspend on an approval and resume on
     // decision; the service is wired to the same engine so `decide()` can
@@ -128,7 +242,14 @@ export class ApprovalsServicePlugin implements Plugin {
     }
   }
 
-  async stop(_ctx: PluginContext): Promise<void> {
+  async stop(ctx: PluginContext): Promise<void> {
+    if (this.escalationJobScheduled) {
+      try {
+        const jobs = ctx.getService<any>('job');
+        await jobs?.cancel?.(ESCALATION_JOB_NAME);
+      } catch { /* ignore */ }
+      this.escalationJobScheduled = false;
+    }
     if (this.engine) {
       try { unbindAllHooks(this.engine); } catch { /* ignore */ }
     }

package/src/index.ts

@@ -12,6 +12,7 @@
 
 export { SysApprovalRequest } from './sys-approval-request.object.js';
 export { SysApprovalAction } from './sys-approval-action.object.js';
+export { SysApprovalApprover } from './sys-approval-approver.object.js';
 export {
   ApprovalService,
   type ApprovalEngine,

package/src/nav-contribution.test.ts

@@ -24,10 +24,12 @@ describe('ApprovalsServicePlugin schema + nav contribution (ADR-0029 K2.b)', ()
     expect(registered).toHaveLength(1);
     const manifest = registered[0];
 
-    // Owns both approval objects (moved out of platform-objects).
+    // Owns the approval objects (moved out of platform-objects).
     expect(manifest.objects.map((o: any) => o.name).sort()).toEqual([
       'sys_approval_action',
+      'sys_approval_approver',
       'sys_approval_request',
+      'sys_approval_token',
     ]);
 
     // Contributes its menu into the Setup app's approvals slot.

package/src/sys-approval-action.object.ts

@@ -88,7 +88,11 @@ export const SysApprovalAction = ObjectSchema.create({
     }),
 
     action: Field.select(
-      ['submit', 'approve', 'reject', 'recall', 'escalate'],
+      // Keep in sync with `ApprovalActionKind` (spec/contracts). reassign /
+      // remind / request_info / comment are thread interactions — they never
+      // move the flow. revise / resubmit (ADR-0044) DO move it: send back for
+      // revision and the later resubmission.
+      ['submit', 'approve', 'reject', 'recall', 'escalate', 'reassign', 'remind', 'request_info', 'comment', 'revise', 'resubmit'],
       {
         label: 'Action',
         required: true,

package/src/sys-approval-approver.object.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_approval_approver — Pending-approver index (issue #1745).
+ *
+ * One row per (request, approver identity) while the request is **pending**.
+ * `sys_approval_request.pending_approvers` stays the human-readable source of
+ * truth (a CSV column), but CSV substring matching can neither be indexed nor
+ * pushed into an engine query — which made "my pending" a post-filter in
+ * memory and broke pagination beyond the scan window.
+ *
+ * This table is that CSV, normalized: the service mirrors every change to
+ * `pending_approvers` here (open / decide / recall / send-back / reassign /
+ * escalate), and clears the rows when the request leaves `pending`. So the
+ * table only ever holds the live work queue — its size tracks the number of
+ * open approvals, not the append-only request history.
+ *
+ * `approver` holds one identity literal exactly as it appears in the CSV:
+ * a user id, an email, or a `role:<name>` / `team:<name>` style literal.
+ * Equality (or `$in`) on this column is the indexed replacement for the old
+ * per-row substring match.
+ *
+ * @namespace sys
+ */
+export const SysApprovalApprover = ObjectSchema.create({
+  name: 'sys_approval_approver',
+  label: 'Approval Approver',
+  pluralLabel: 'Approval Approvers',
+  icon: 'users',
+  isSystem: true,
+  managedBy: 'system',
+  description: 'Normalized pending-approver rows for indexed inbox queries',
+  displayNameField: 'id',
+  titleFormat: '{approver} · {request_id}',
+  compactLayout: ['request_id', 'approver', 'created_at'],
+
+  fields: {
+    id: Field.text({ label: 'Row ID', required: true, readonly: true, group: 'System' }),
+
+    organization_id: Field.lookup('sys_organization', {
+      label: 'Organization',
+      required: false,
+      group: 'System',
+      description: 'Tenant that owns this row (mirrors the parent request)',
+    }),
+
+    request_id: Field.lookup('sys_approval_request', {
+      label: 'Request',
+      required: true,
+      group: 'Target',
+    }),
+
+    approver: Field.text({
+      label: 'Approver',
+      required: true,
+      maxLength: 255,
+      description: 'One pending-approver identity: user id, email, or role:/team: literal',
+      group: 'Target',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+  },
+
+  indexes: [
+    // "My pending" inbox: equality on the identity literal, scoped by tenant.
+    { fields: ['approver', 'organization_id'] },
+    // Sync path: rewrite all rows of one request on each approver-set change.
+    { fields: ['request_id'] },
+  ],
+});

package/src/sys-approval-request.object.ts

@@ -127,7 +127,9 @@ export const SysApprovalRequest = ObjectSchema.create({
     }),
 
     status: Field.select(
-      ['pending', 'approved', 'rejected', 'recalled'],
+      // Keep in sync with `ApprovalStatus` (spec/contracts). `returned` =
+      // sent back for revision (ADR-0044) — terminal for this round.
+      ['pending', 'approved', 'rejected', 'recalled', 'returned'],
       {
         label: 'Status',
         required: true,
@@ -218,9 +220,11 @@ export const SysApprovalRequest = ObjectSchema.create({
     // guard on submit and on edit-while-locked checks.
     { fields: ['object_name', 'record_id'] },
     { fields: ['status', 'object_name'] },
-    // "My approvals" inbox — pending_approvers is a CSV string so this
-    // index only helps with status pre-filtering; the engine does a
-    // post-filter substring match per row.
+    // Status-windowed listings (escalation sweep, "All" tab ordering).
+    // "My approvals" matching no longer scans this table: the service keeps
+    // a normalized per-approver index in `sys_approval_approver` (#1745) and
+    // resolves approver filters there; `pending_approvers` stays the
+    // human-readable CSV source of truth only.
     { fields: ['status', 'updated_at'] },
     { fields: ['submitter_id', 'status'] },
   ],

package/src/sys-approval-token.object.ts

@@ -0,0 +1,94 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_approval_token — single-use actionable-link tokens (ADR-0043).
+ *
+ * One row per issued approve/reject link. Only the SHA-256 **hash** of the
+ * raw token is stored — a database leak yields no usable links. A token is
+ * dead once any of these holds: `consumed_at` set, `expires_at` passed, the
+ * request left `pending`, or the bound approver no longer holds a slot
+ * (the last two are re-checked at redemption, not materialized here).
+ *
+ * @namespace sys
+ */
+export const SysApprovalToken = ObjectSchema.create({
+  name: 'sys_approval_token',
+  label: 'Approval Action Token',
+  pluralLabel: 'Approval Action Tokens',
+  icon: 'key',
+  isSystem: true,
+  managedBy: 'system',
+  description: 'Single-use tokens behind actionable approval links',
+  displayNameField: 'id',
+
+  fields: {
+    id: Field.text({ label: 'Token ID', required: true, readonly: true, group: 'System' }),
+
+    organization_id: Field.lookup('sys_organization', {
+      label: 'Organization',
+      required: false,
+      group: 'System',
+    }),
+
+    token_hash: Field.text({
+      label: 'Token Hash',
+      required: true,
+      maxLength: 100,
+      readonly: true,
+      description: 'SHA-256 hex of the raw token — the raw value is never stored',
+      group: 'Token',
+    }),
+
+    request_id: Field.text({
+      label: 'Request',
+      required: true,
+      maxLength: 100,
+      readonly: true,
+      group: 'Token',
+    }),
+
+    action: Field.select(['approve', 'reject'], {
+      label: 'Action',
+      required: true,
+      readonly: true,
+      group: 'Token',
+    }),
+
+    approver_id: Field.text({
+      label: 'Approver',
+      required: true,
+      maxLength: 200,
+      readonly: true,
+      description: 'Identity the token is bound to; the decision is audited as this approver',
+      group: 'Token',
+    }),
+
+    expires_at: Field.datetime({
+      label: 'Expires At',
+      required: true,
+      readonly: true,
+      group: 'Lifecycle',
+    }),
+
+    consumed_at: Field.datetime({
+      label: 'Consumed At',
+      required: false,
+      group: 'Lifecycle',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+      group: 'System',
+    }),
+  },
+
+  indexes: [
+    { fields: ['token_hash'] },
+    { fields: ['request_id'] },
+  ],
+});