@objectstack/plugin-approvals 7.3.0 → 7.4.1

package/src/approval-node.test.ts

@@ -0,0 +1,182 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AutomationEngine } from '@objectstack/service-automation';
+import { ApprovalService } from './approval-service.js';
+import { registerApprovalNode } from './approval-node.js';
+
+const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as any;
+
+const noopLogger = {
+  info() {}, warn() {}, error() {}, debug() {},
+};
+
+/**
+ * Tiny in-memory ObjectQL stand-in — supports the `where`-equality + `$in`
+ * queries the approval service issues, enough to drive the node bridge.
+ */
+function makeFakeEngine() {
+  const tables = new Map<string, any[]>();
+  const rows = (o: string) => (tables.get(o) ?? (tables.set(o, []), tables.get(o)!));
+  const matches = (row: any, where: any) => Object.entries(where ?? {}).every(([k, v]) => {
+    if (v && typeof v === 'object' && '$in' in (v as any)) return (v as any).$in.includes(row[k]);
+    if (v && typeof v === 'object' && '$ne' in (v as any)) return row[k] !== (v as any).$ne;
+    return row[k] === v;
+  });
+  return {
+    tables,
+    async find(object: string, opts: any = {}) {
+      const where = opts.where ?? opts.filter ?? {};
+      let out = rows(object).filter(r => matches(r, where));
+      if (opts.limit) out = out.slice(0, opts.limit);
+      return out.map(r => ({ ...r }));
+    },
+    async insert(object: string, data: any) {
+      rows(object).push({ ...data });
+      return { ...data };
+    },
+    async update(object: string, idOrData: any) {
+      const id = idOrData.id;
+      const row = rows(object).find(r => r.id === id);
+      if (row) Object.assign(row, idOrData);
+      return row ? { ...row } : null;
+    },
+    async delete(object: string, opts: any = {}) {
+      const where = opts.where ?? {};
+      const list = rows(object);
+      for (let i = list.length - 1; i >= 0; i--) if (matches(list[i], where)) list.splice(i, 1);
+      return { affected: 1 };
+    },
+  };
+}
+
+function registerDecisionFlow(engine: AutomationEngine, approvers: Array<{ type: string; value?: string }>, behavior?: 'first_response' | 'unanimous') {
+  engine.registerFlow('deal_approval', {
+    name: 'deal_approval',
+    label: 'Deal Approval',
+    type: 'autolaunched',
+    nodes: [
+      { id: 'start', type: 'start', label: 'Start' },
+      { id: 'approve_step', type: 'approval', label: 'Manager Approval', config: { approvers, behavior } },
+      { id: 'on_approved', type: 'mark', label: 'Approved' },
+      { id: 'on_rejected', type: 'mark', label: 'Rejected' },
+      { id: 'end', type: 'end', label: 'End' },
+    ],
+    edges: [
+      { id: 'e1', source: 'start', target: 'approve_step' },
+      { id: 'e2', source: 'approve_step', target: 'on_approved', label: 'approve' },
+      { id: 'e3', source: 'approve_step', target: 'on_rejected', label: 'reject' },
+      { id: 'e4', source: 'on_approved', target: 'end' },
+      { id: 'e5', source: 'on_rejected', target: 'end' },
+    ],
+  });
+}
+
+describe('Approval node bridge (ADR-0019)', () => {
+  let automation: AutomationEngine;
+  let service: ApprovalService;
+  let fake: ReturnType<typeof makeFakeEngine>;
+  const marks: string[] = [];
+
+  beforeEach(() => {
+    marks.length = 0;
+    automation = new AutomationEngine(noopLogger as any);
+    fake = makeFakeEngine();
+    service = new ApprovalService({ engine: fake as any, logger: noopLogger });
+    // The contract `decide()` resumes via the attached automation surface.
+    service.attachAutomation(automation);
+    registerApprovalNode(automation, service, noopLogger);
+    // A terminal "mark" node records which branch ran.
+    automation.registerNodeExecutor({
+      type: 'mark',
+      async execute(node: any) { marks.push(node.id); return { success: true }; },
+    });
+  });
+
+  it('publishes an approval action descriptor that supports pause', () => {
+    const descriptors = automation.getActionDescriptors();
+    const approval = descriptors.find(d => d.type === 'approval');
+    expect(approval).toBeDefined();
+    expect(approval!.supportsPause).toBe(true);
+    expect(approval!.category).toBe('human');
+  });
+
+  it('suspends the run on entry and opens a pending request', async () => {
+    registerDecisionFlow(automation, [{ type: 'user', value: 'u1' }]);
+    const result = await automation.execute('deal_approval', {
+      object: 'crm_deal',
+      record: { id: 'd1', amount: 100 },
+      userId: 'submitter',
+    });
+    expect(result.status).toBe('paused');
+    expect(result.runId).toBeDefined();
+    expect(marks).toHaveLength(0);
+
+    const requests = await fake.find('sys_approval_request', { where: { status: 'pending' } });
+    expect(requests).toHaveLength(1);
+    expect(requests[0]).toMatchObject({
+      object_name: 'crm_deal', record_id: 'd1', flow_run_id: result.runId, flow_node_id: 'approve_step',
+    });
+    // Surfaced as a suspended run with the request id as correlation.
+    const suspended = automation.listSuspendedRuns();
+    expect(suspended[0]).toMatchObject({ nodeId: 'approve_step', correlation: requests[0].id });
+  });
+
+  it('resumes down the approve branch on approval', async () => {
+    registerDecisionFlow(automation, [{ type: 'user', value: 'u1' }]);
+    const paused = await automation.execute('deal_approval', {
+      object: 'crm_deal', record: { id: 'd1' }, userId: 'submitter',
+    });
+    const request = (await fake.find('sys_approval_request', { where: { status: 'pending' } }))[0];
+
+    const out = await service.decide(request.id, { decision: 'approve', actorId: 'u1' }, SYSTEM_CTX);
+
+    expect(out).toMatchObject({ finalized: true, decision: 'approve', resumed: true });
+    expect(marks).toEqual(['on_approved']);
+    expect(automation.listSuspendedRuns()).toHaveLength(0);
+
+    const finalReq = (await fake.find('sys_approval_request', { where: { id: request.id } }))[0];
+    expect(finalReq.status).toBe('approved');
+    expect(paused.runId).toBeDefined();
+  });
+
+  it('resumes down the reject branch on rejection', async () => {
+    registerDecisionFlow(automation, [{ type: 'user', value: 'u1' }]);
+    await automation.execute('deal_approval', { object: 'crm_deal', record: { id: 'd1' } });
+    const request = (await fake.find('sys_approval_request', { where: { status: 'pending' } }))[0];
+
+    const out = await service.decide(request.id, { decision: 'reject', actorId: 'u1' }, SYSTEM_CTX);
+
+    expect(out).toMatchObject({ finalized: true, decision: 'reject', resumed: true });
+    expect(marks).toEqual(['on_rejected']);
+  });
+
+  it('holds a unanimous step until every approver acts, then resumes', async () => {
+    registerDecisionFlow(automation, [
+      { type: 'user', value: 'u1' },
+      { type: 'user', value: 'u2' },
+    ], 'unanimous');
+    await automation.execute('deal_approval', { object: 'crm_deal', record: { id: 'd1' } });
+    const request = (await fake.find('sys_approval_request', { where: { status: 'pending' } }))[0];
+
+    const first = await service.decide(request.id, { decision: 'approve', actorId: 'u1' }, SYSTEM_CTX);
+    expect(first.finalized).toBe(false);
+    expect(first.resumed).toBe(false);
+    expect(marks).toHaveLength(0);
+
+    const second = await service.decide(request.id, { decision: 'approve', actorId: 'u2' }, SYSTEM_CTX);
+    expect(second.finalized).toBe(true);
+    expect(second.resumed).toBe(true);
+    expect(marks).toEqual(['on_approved']);
+  });
+
+  it('rejects a decision from a non-approver', async () => {
+    registerDecisionFlow(automation, [{ type: 'user', value: 'u1' }]);
+    await automation.execute('deal_approval', { object: 'crm_deal', record: { id: 'd1' } });
+    const request = (await fake.find('sys_approval_request', { where: { status: 'pending' } }))[0];
+
+    await expect(
+      service.decideNode(request.id, { decision: 'approve', actorId: 'intruder' }, { isSystem: false, roles: [], permissions: [] } as any),
+    ).rejects.toThrow(/FORBIDDEN/);
+  });
+});

package/src/approval-node.ts

@@ -0,0 +1,131 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Approval-as-flow-node provider (ADR-0019).
+ *
+ * Registers an `approval` node executor on the automation engine so an approval
+ * rides the one flow engine as a durable-pause node:
+ *
+ *   1. On entry the node opens a `sys_approval_request` (reusing the mature
+ *      approver-resolution / audit / lock / status-mirror machinery) and returns
+ *      `{ suspend: true }` — the engine persists the run and stops traversal.
+ *   2. A decision (`ApprovalService.decide`) finalizes the request and resumes
+ *      the run down the matching `approve` / `reject` out-edge.
+ *
+ * The approval *state* (request/action rows) stays first-class and owned by this
+ * plugin — a flow-run log can't drive an inbox / recall / audit. Only the
+ * orchestration (when to pause, which branch to take) moves onto the engine.
+ */
+
+import {
+  defineActionDescriptor,
+  ApprovalNodeConfigSchema,
+  getApprovalNodeConfigJsonSchema,
+  APPROVAL_NODE_TYPE,
+  type ApprovalNodeConfig,
+} from '@objectstack/spec/automation';
+import type { SharingExecutionContext } from '@objectstack/spec/contracts';
+import type { ApprovalService } from './approval-service.js';
+
+/** Minimal surface of the automation engine this provider depends on. */
+export interface ApprovalAutomationSurface {
+  registerNodeExecutor(executor: {
+    type: string;
+    descriptor?: unknown;
+    execute(node: any, variables: Map<string, unknown>, context: any): Promise<{
+      success: boolean;
+      output?: Record<string, unknown>;
+      error?: string;
+      suspend?: boolean;
+      correlation?: string;
+    }>;
+  }): void;
+  resume?(runId: string, signal?: { output?: Record<string, unknown>; branchLabel?: string }): Promise<unknown>;
+}
+
+interface MinimalLogger {
+  info?: (msg: any, ...rest: any[]) => void;
+  warn?: (msg: any, ...rest: any[]) => void;
+}
+
+const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+
+/**
+ * Register the `approval` node executor on the automation engine. Idempotent at
+ * the engine level (re-registering replaces). Safe to skip when no automation
+ * service is present.
+ */
+export function registerApprovalNode(
+  automation: ApprovalAutomationSurface,
+  service: ApprovalService,
+  logger?: MinimalLogger,
+): void {
+  automation.registerNodeExecutor({
+    type: APPROVAL_NODE_TYPE,
+    descriptor: defineActionDescriptor({
+      type: APPROVAL_NODE_TYPE,
+      version: '1.0.0',
+      name: 'Approval',
+      description: 'Route a record for human approval; suspends the flow until a decision, '
+        + 'then continues down the approve / reject branch.',
+      icon: 'check-circle',
+      category: 'human',
+      paradigms: ['flow'],
+      source: 'plugin',
+      // Human decision: the run suspends here awaiting an external reply.
+      supportsPause: true,
+      isAsync: true,
+      // Publish the node's config contract (ADR-0018 §configSchema) so the
+      // Studio flow designer renders the Approval property form from the engine
+      // rather than a hardcoded client form — the engine owns the shape.
+      configSchema: getApprovalNodeConfigJsonSchema(),
+    }),
+    async execute(node, variables, context) {
+      const parsed = ApprovalNodeConfigSchema.safeParse(node.config ?? {});
+      if (!parsed.success) {
+        const msg = parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ');
+        return { success: false, error: `Approval node '${node.id}' has invalid config: ${msg}` };
+      }
+      const config = parsed.data as ApprovalNodeConfig;
+
+      const runId = variables.get('$runId');
+      const record = (variables.get('$record') ?? context?.record ?? {}) as Record<string, unknown>;
+      const object = (context?.object ?? (record as any)?.object_name) as string | undefined;
+      const recordId = (record as any)?.id as string | undefined;
+
+      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` };
+
+      try {
+        const request = await service.openNodeRequest({
+          object,
+          recordId: String(recordId),
+          runId: String(runId),
+          nodeId: node.id,
+          config,
+          flowName: context?.flowName,
+          submitterId: context?.userId ?? null,
+          record,
+          organizationId: context?.organizationId ?? context?.tenantId ?? null,
+        }, {
+          ...SYSTEM_CTX,
+          userId: context?.userId,
+          organizationId: context?.organizationId,
+          tenantId: context?.tenantId,
+        } as unknown as SharingExecutionContext);
+
+        logger?.info?.('[approvals] approval node suspended run', {
+          node: node.id, request: request.id, run: String(runId),
+        });
+        // Suspend the run; the request id is the correlation key surfaced on
+        // the suspended-run record for lookup.
+        return { success: true, suspend: true, correlation: request.id };
+      } catch (err: any) {
+        return { success: false, error: `Approval node '${node.id}': ${err?.message ?? String(err)}` };
+      }
+    },
+  });
+
+  logger?.info?.('[approvals] approval node executor registered');
+}