@objectstack/plugin-approvals 13.0.0 → 14.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-approvals",
-  "version": "13.0.0",
+  "version": "14.5.0",
   "license": "Apache-2.0",
   "description": "Multi-step approval engine for ObjectStack — sys_approval_process + sys_approval_request + sys_approval_action + IApprovalService.",
   "main": "dist/index.js",
@@ -13,17 +13,17 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "13.0.0",
-    "@objectstack/formula": "13.0.0",
-    "@objectstack/metadata-core": "13.0.0",
-    "@objectstack/platform-objects": "13.0.0",
-    "@objectstack/spec": "13.0.0"
+    "@objectstack/core": "14.5.0",
+    "@objectstack/formula": "14.5.0",
+    "@objectstack/metadata-core": "14.5.0",
+    "@objectstack/platform-objects": "14.5.0",
+    "@objectstack/spec": "14.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@objectstack/service-automation": "13.0.0"
+    "@objectstack/service-automation": "14.5.0"
   },
   "keywords": [
     "objectstack",

package/src/approval-service.test.ts

@@ -187,6 +187,65 @@ describe('ApprovalService (node era)', () => {
     expect(engine._tables['opportunity'][0].approval_status).toBe('pending');
   });
 
+  // ── approver expansion: position (ADR-0090 D3) ──────────────────
+
+  const positionInput = (extra: Record<string, any> = {}) => ({
+    ...openInput([]),
+    config: {
+      approvers: [{ type: 'position' as const, value: 'sales_manager' }],
+      behavior: 'first_response' as const,
+      lockRecord: true,
+    },
+    ...extra,
+  });
+
+  it('position approver: expands via sys_user_position, org-scoped', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'sales_manager', organization_id: 't1' },
+      { id: 'up2', user_id: 'u6', position: 'sales_manager', organization_id: 't1' },
+      { id: 'up3', user_id: 'u7', position: 'sales_manager', organization_id: 't2' }, // other tenant
+      { id: 'up4', user_id: 'u8', position: 'cfo', organization_id: 't1' },           // other position
+    ];
+    const req = await svc.openNodeRequest(positionInput(), CTX);
+    expect(req.pending_approvers.sort()).toEqual(['u5', 'u6']);
+  });
+
+  it('position approver: unions the sys_member.role transition source (ADR-0057 D4)', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'sales_manager', organization_id: 't1' },
+    ];
+    engine._tables['sys_member'] = [
+      { id: 'm1', user_id: 'u6', role: 'sales_manager', organization_id: 't1' },
+      { id: 'm2', user_id: 'u5', role: 'sales_manager', organization_id: 't1' }, // deduped
+    ];
+    const req = await svc.openNodeRequest(positionInput(), CTX);
+    expect(req.pending_approvers.sort()).toEqual(['u5', 'u6']);
+  });
+
+  it('position approver: falls back to a position: literal when nobody holds it', async () => {
+    const req = await svc.openNodeRequest(positionInput(), CTX);
+    expect(req.pending_approvers).toEqual(['position:sales_manager']);
+  });
+
+  it("department approver: honors the spec enum value 'department' (not just the business_unit dialect)", async () => {
+    engine._tables['sys_business_unit'] = [
+      { id: 'bu1', organization_id: 't1', active: true },
+      { id: 'bu2', parent_business_unit_id: 'bu1', organization_id: 't1', active: true },
+    ];
+    engine._tables['sys_business_unit_member'] = [
+      { id: 'bm1', business_unit_id: 'bu1', user_id: 'u5' },
+      { id: 'bm2', business_unit_id: 'bu2', user_id: 'u6' },
+    ];
+    const req = await svc.openNodeRequest(positionInput({
+      config: {
+        approvers: [{ type: 'department' as const, value: 'bu1' }],
+        behavior: 'first_response' as const,
+        lockRecord: true,
+      },
+    }), CTX);
+    expect(req.pending_approvers.sort()).toEqual(['u5', 'u6']);
+  });
+
   // ── decideNode ──────────────────────────────────────────────────
 
   it('decideNode: first_response approve finalizes immediately', async () => {
@@ -804,6 +863,40 @@ describe('ApprovalService (node era)', () => {
     expect(fresh?.pending_approvers).toEqual(['boss']);
   });
 
+  it('runEscalations: reassign expands a position escalateTo to its holders (ADR-0090 D3)', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'approvals_supervisor', organization_id: 't1' },
+      { id: 'up2', user_id: 'u6', position: 'approvals_supervisor', organization_id: 't1' },
+      { id: 'up3', user_id: 'u7', position: 'approvals_supervisor', organization_id: 't2' }, // other tenant
+    ];
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 1, action: 'reassign', escalateTo: 'approvals_supervisor', notifySubmitter: false } }), CTX,
+    );
+    makeOverdue(req.id);
+    await svc.runEscalations();
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.status).toBe('pending');
+    expect(fresh?.pending_approvers?.slice().sort()).toEqual(['u5', 'u6']);
+    // The audit trail keeps the AUTHORED target, not the expansion.
+    const actions = await svc.listActions(req.id, SYS);
+    expect(actions.find(a => a.action === 'escalate')?.comment).toBe('reassign → approvals_supervisor');
+  });
+
+  it('runEscalations: notify expands a position escalateTo into the audience', async () => {
+    engine._tables['sys_user_position'] = [
+      { id: 'up1', user_id: 'u5', position: 'approvals_supervisor', organization_id: 't1' },
+    ];
+    const emitted: any[] = [];
+    svc.attachMessaging({ async emit(input) { emitted.push(input); } });
+    const req = await svc.openNodeRequest(
+      openInput(['u9'], {}, { escalation: { timeoutHours: 2, action: 'notify', escalateTo: 'approvals_supervisor', notifySubmitter: false } }), CTX,
+    );
+    makeOverdue(req.id);
+    await svc.runEscalations();
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0].audience).toEqual(['u9', 'u5']);
+  });
+
   it('runEscalations: skips requests that are not yet due or have no SLA', async () => {
     await svc.openNodeRequest(
       openInput(['u9'], {}, { escalation: { timeoutHours: 1000, action: 'auto_approve' } }), CTX,

package/src/approval-service.ts

@@ -31,8 +31,8 @@ import type {
  * `approve` / `reject` edge.
  *
  * This service owns the durable approval *state* — `sys_approval_request` /
- * `sys_approval_action`, approver resolution (team / department / role /
- * manager graph), and the optional status-field mirror — plus the decision
+ * `sys_approval_action`, approver resolution (team / department / position /
+ * role / manager graph), and the optional status-field mirror — plus the decision
  * API. It does not author processes, submit, or walk multi-step machinery
  * anymore; that orchestration lives on the one automation engine.
  */
@@ -274,16 +274,20 @@ export class ApprovalService implements IApprovalService {
 
   /**
    * Expand the approvers on an Approval node into user IDs by querying the
-   * graph tables for `team:` / `department:` / `role:` / `manager:` approver
-   * types. Falls back to a prefixed literal (`type:value`) when graph lookups
-   * produce nothing — so existing fixtures and flows that rely on substring
-   * matching keep working.
+   * graph tables for `team:` / `department:` / `position:` / `role:` /
+   * `manager:` approver types. Falls back to a prefixed literal
+   * (`type:value`) when graph lookups produce nothing — so existing fixtures
+   * and flows that rely on substring matching keep working.
    *
    * **Graph semantics:**
    *   - `team`       → flat members of `sys_team` (better-auth; no BFS)
    *   - `department` → recursive BFS of `sys_business_unit.parent_business_unit_id`
    *                    → members of every descendant via `sys_business_unit_member`
-   *   - `role`       → users with `sys_member.role = value` in tenant
+   *   - `position`   → holders via `sys_user_position` ∪ `sys_member.role`
+   *                    transition source (ADR-0090 D3 / ADR-0057 D4)
+   *   - `role`       → users with `sys_member.role = value` in tenant — the
+   *                    better-auth MEMBERSHIP TIER (owner/admin/member), not a
+   *                    position; author `position` for org positions
    *   - `manager`    → `sys_user.manager_id` of `record[value] ?? record.owner_id`
    *   - `field`      → literal user id stored in `record[value]`
    *   - `user`       → literal value
@@ -299,9 +303,12 @@ export class ApprovalService implements IApprovalService {
         if (a.type === 'team') {
           const users = await this.expandTeamUsers(String(a.value));
           if (users.length) { for (const u of users) out.push(u); continue; }
-        } else if (a.type === 'business_unit' || a.type === 'bu') {
+        } else if (a.type === 'department' || a.type === 'business_unit' || a.type === 'bu') {
           const users = await this.expandBusinessUnitUsers(String(a.value), organizationId);
           if (users.length) { for (const u of users) out.push(u); continue; }
+        } else if (a.type === 'position') {
+          const users = await this.expandPositionUsers(String(a.value), organizationId);
+          if (users.length) { for (const u of users) out.push(u); continue; }
         } else if (a.type === 'role') {
           const users = await this.expandRoleUsers(String(a.value), organizationId);
           if (users.length) { for (const u of users) out.push(u); continue; }
@@ -377,6 +384,33 @@ export class ApprovalService implements IApprovalService {
     return Array.from(new Set((rows ?? []).map((r: any) => String(r.user_id ?? '')).filter(Boolean)));
   }
 
+  /**
+   * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
+   * assignment table, keyed by the position's machine name (ADR-0057 D4),
+   * unioned with the better-auth membership string (`sys_member.role`) as a
+   * transition source — the same semantics as `PositionGraphService` in
+   * `plugin-sharing`, so an approval routes to exactly the users the sharing
+   * engine would expand for the same position.
+   */
+  private async expandPositionUsers(positionName: string, organizationId?: string | null): Promise<string[]> {
+    if (!positionName) return [];
+    const users = new Set<string>();
+    const filter: any = { position: positionName };
+    if (organizationId) filter.organization_id = organizationId;
+    try {
+      const rows = await this.engine.find('sys_user_position', {
+        filter, fields: ['user_id'], limit: 10000, context: SYSTEM_CTX,
+      } as any);
+      for (const r of (rows ?? []) as any[]) {
+        const uid = String(r.user_id ?? '');
+        if (uid) users.add(uid);
+      }
+    } catch { /* table may not exist on minimal stacks — union source below still applies */ }
+    for (const uid of await this.expandRoleUsers(positionName, organizationId)) users.add(uid);
+    return Array.from(users);
+  }
+
+  /** better-auth org-membership tier (`sys_member.role`) — NOT positions. */
   private async expandRoleUsers(roleName: string, organizationId?: string | null): Promise<string[]> {
     if (!roleName) return [];
     const filter: any = { role: roleName };
@@ -1347,6 +1381,18 @@ export class ApprovalService implements IApprovalService {
     const now = this.clock.now().toISOString();
     const pending = csvSplit(raw.pending_approvers);
 
+    // `escalateTo` is a position machine name or a user id (same contract as
+    // the `position` ApproverType, ADR-0090 D3). Position holders win; an
+    // empty expansion falls back to the literal, so a config naming a
+    // specific user id keeps working unchanged.
+    let escalatees: string[] = [];
+    if (escalateTo) {
+      try {
+        escalatees = await this.expandPositionUsers(escalateTo, raw.organization_id ?? null);
+      } catch { escalatees = []; }
+      if (!escalatees.length) escalatees = [escalateTo];
+    }
+
     // Audit first — this row IS the idempotency marker (ADR-0042 §1).
     await this.engine.insert('sys_approval_action', {
       id: uid('aact'), request_id: raw.id, organization_id: raw.organization_id ?? null,
@@ -1356,14 +1402,14 @@ export class ApprovalService implements IApprovalService {
       created_at: now,
     }, { context: SYSTEM_CTX });
 
-    if (action === 'reassign' && escalateTo) {
+    if (action === 'reassign' && escalatees.length) {
       await this.engine.update('sys_approval_request', {
-        id: raw.id, pending_approvers: escalateTo, updated_at: now,
+        id: raw.id, pending_approvers: escalatees.join(','), updated_at: now,
       }, { context: SYSTEM_CTX });
-      await this.syncApproverIndex(raw.id, [escalateTo], raw.organization_id ?? null, now);
+      await this.syncApproverIndex(raw.id, escalatees, raw.organization_id ?? null, now);
       await this.notify({
         topic: 'approval.escalated',
-        audience: [escalateTo],
+        audience: escalatees,
         actorId: SLA_ACTOR_ID,
         source: { object: 'sys_approval_request', id: raw.id },
         payload: {
@@ -1382,7 +1428,7 @@ export class ApprovalService implements IApprovalService {
       // 'notify' (and the reassign-without-target fallback)
       await this.notify({
         topic: 'approval.sla_breached',
-        audience: [...pending, ...(escalateTo ? [escalateTo] : [])],
+        audience: [...pending, ...escalatees],
         actorId: SLA_ACTOR_ID,
         source: { object: 'sys_approval_request', id: raw.id },
         payload: {