@objectstack/plugin-approvals 16.0.0-rc.0 → 16.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-approvals",
-  "version": "16.0.0-rc.0",
+  "version": "16.0.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": "16.0.0-rc.0",
-    "@objectstack/formula": "16.0.0-rc.0",
-    "@objectstack/metadata-core": "16.0.0-rc.0",
-    "@objectstack/platform-objects": "16.0.0-rc.0",
-    "@objectstack/spec": "16.0.0-rc.0"
+    "@objectstack/core": "16.0.0",
+    "@objectstack/formula": "16.0.0",
+    "@objectstack/metadata-core": "16.0.0",
+    "@objectstack/platform-objects": "16.0.0",
+    "@objectstack/spec": "16.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@objectstack/service-automation": "16.0.0-rc.0"
+    "@objectstack/service-automation": "16.0.0"
   },
   "keywords": [
     "objectstack",

package/src/approval-service.test.ts

@@ -414,6 +414,33 @@ describe('ApprovalService (node era)', () => {
     expect(await svc.getRequest('nope', SYS)).toBeNull();
   });
 
+  // ── viewer capability (#3310) ───────────────────────────────────
+  it('getRequest: viewer.can_act is true for a pending approver, false for the submitter', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX); // submitter u1, approver u9
+    const asApprover = await svc.getRequest(req.id, { userId: 'u9', tenantId: 't1' } as any);
+    expect(asApprover!.viewer).toEqual({ can_act: true, is_submitter: false });
+    const asSubmitter = await svc.getRequest(req.id, { userId: 'u1', tenantId: 't1' } as any);
+    expect(asSubmitter!.viewer).toEqual({ can_act: false, is_submitter: true });
+    const asOther = await svc.getRequest(req.id, { userId: 'u_stranger', tenantId: 't1' } as any);
+    expect(asOther!.viewer).toEqual({ can_act: false, is_submitter: false });
+  });
+
+  it('getRequest: viewer.can_act drops to false once the request is finalized', async () => {
+    const req = await svc.openNodeRequest(openInput(['u9']), CTX);
+    await svc.decideNode(req.id, { decision: 'approve', actorId: 'u9' }, SYS); // → approved
+    const after = await svc.getRequest(req.id, { userId: 'u9', tenantId: 't1' } as any);
+    expect(after!.status).toBe('approved');
+    expect(after!.viewer!.can_act).toBe(false);
+  });
+
+  it('listRequests: attaches viewer to every row from the caller context', async () => {
+    await svc.openNodeRequest(openInput(['u9']), CTX);
+    const rows = await svc.listRequests({ status: 'pending' }, { userId: 'u9', tenantId: 't1' } as any);
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.every(r => r.viewer != null)).toBe(true);
+    expect(rows[0].viewer!.can_act).toBe(true);
+  });
+
   // ── recall ──────────────────────────────────────────────────────
 
   it('recall: submitter withdraws a pending request', async () => {

package/src/approval-service.ts

@@ -2174,6 +2174,7 @@ export class ApprovalService implements IApprovalService {
     const rows = await this.engine.find('sys_approval_request', findOpts);
     const list = Array.isArray(rows) ? rows.map(rowFromRequest) : [];
     await this.enrichRows(list);
+    this.attachViewers(list, context);
     return list;
   }
 
@@ -2221,6 +2222,7 @@ export class ApprovalService implements IApprovalService {
     await this.enrichRows([row]);
     await this.attachFlowSteps(row);
     await this.attachDecisionProgress(row, rows[0]);
+    this.attachViewers([row], context);
     return row;
   }
 
@@ -2270,6 +2272,26 @@ export class ApprovalService implements IApprovalService {
     } catch { /* display-only enrichment */ }
   }
 
+  /**
+   * Attach the per-viewer capability block (#3310) from the caller's context.
+   * `can_act` mirrors the exact authorization the decision methods enforce — the
+   * caller's user id is in the resolved `pending_approvers` while the request is
+   * still `pending` (position/team/manager approvers are already resolved to
+   * concrete user ids at open time, so a plain membership test is faithful).
+   * `is_submitter` is a straight owner check. System/tokenless contexts get a
+   * both-false block. Cheap + synchronous — safe on list reads.
+   */
+  private attachViewers(rows: ApprovalRequestRow[], context: SharingExecutionContext): void {
+    const uid = (context as any)?.userId != null ? String((context as any).userId) : null;
+    for (const row of rows) {
+      const pending = row.pending_approvers ?? [];
+      (row as any).viewer = {
+        can_act: row.status === 'pending' && !!uid && pending.includes(uid),
+        is_submitter: !!uid && row.submitter_id != null && String(row.submitter_id) === uid,
+      };
+    }
+  }
+
   /**
    * Derive approval-step progress from the owning flow's graph (single-read
    * enrichment only — list reads skip it). Walks from the start node

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

@@ -30,7 +30,7 @@ export const SysApprovalApprover = ObjectSchema.create({
   pluralLabel: 'Approval Approvers',
   icon: 'users',
   isSystem: true,
-  managedBy: 'system',
+  managedBy: 'engine-owned',
   description: 'Normalized pending-approver rows for indexed inbox queries',
   displayNameField: 'id',
   nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)

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

@@ -61,15 +61,16 @@ describe('sys_approval_request declared actions', () => {
     }
   });
 
-  it('gates submitter-only levers on the current user; approver actions only on pending', () => {
+  it('gates on the server-computed viewer block (#3310): approver actions on can_act, submitter levers on is_submitter', () => {
     for (const name of ['approval_remind', 'approval_recall', 'approval_resubmit']) {
-      expect(vis(name)).toContain('record.submitter_id == ctx.user.id');
+      expect(vis(name)).toContain('record.viewer.is_submitter');
+      expect(vis(name)).not.toContain('can_act');
     }
-    // Approver-side actions defer who-can-act to the service; they only trim the
-    // non-pending case in the UI.
     for (const name of ['approval_approve', 'approval_reject', 'approval_send_back', 'approval_request_info', 'approval_reassign']) {
-      expect(vis(name)).toContain('record.status == "pending"');
+      expect(vis(name)).toContain('record.viewer.can_act');
+      // who-can-act is server-derived, never a client identity guess
       expect(vis(name)).not.toContain('ctx.user.id');
+      expect(vis(name)).not.toContain('is_submitter');
     }
   });
 
@@ -91,4 +92,12 @@ describe('sys_approval_request declared actions', () => {
       expect(c.required ?? false).toBe(false);
     }
   });
+
+  it('approve/reject collect optional multi-file decision attachments', () => {
+    for (const name of ['approval_approve', 'approval_reject']) {
+      const att = byName(name).params.find((p: any) => p.name === 'attachments');
+      expect(att, `${name}.attachments`).toMatchObject({ type: 'file', multiple: true });
+      expect(att.required ?? false).toBe(false);
+    }
+  });
 });

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

@@ -28,7 +28,7 @@ export const SysApprovalRequest = ObjectSchema.create({
   pluralLabel: 'Approval Requests',
   icon: 'inbox',
   isSystem: true,
-  managedBy: 'system',
+  managedBy: 'engine-owned',
   description: 'Live approval instance tracked per submission',
   displayNameField: 'id',
   nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
@@ -236,8 +236,12 @@ export const SysApprovalRequest = ObjectSchema.create({
   // (and their params) ship as metadata, not as hand-written buttons. Each
   // targets the existing approvals REST route; `{id}` resolves from the row
   // and `actorId` defaults to the caller server-side. The service remains the
-  // authority on who may act (pending-approver check) — `visible` only trims
-  // the obvious non-pending case.
+  // authority on who may act; `visible` gates on the server-computed
+  // per-viewer block (#3310): approver actions on `record.viewer.can_act`
+  // (the caller is a current pending approver — same check the service
+  // authorizes a decision with, so position/team approvers resolve correctly),
+  // submitter actions on `record.viewer.is_submitter`. `viewer` is attached by
+  // getRequest/listRequests; where it is absent the predicate fails closed.
   actions: [
     {
       name: 'approval_approve',
@@ -248,8 +252,12 @@ export const SysApprovalRequest = ObjectSchema.create({
       target: '/api/v1/approvals/requests/{id}/approve',
       params: [
         { name: 'comment', label: 'Comment', type: 'textarea', required: false },
+        // Decision attachments (#3266). The console renders `type:'file'` params
+        // through the shared upload widget and POSTs the resolved `attachments:
+        // string[]`; the decision route persists them on `sys_approval_action`.
+        { name: 'attachments', label: 'Attachments', type: 'file', multiple: true, required: false },
       ],
-      visible: 'record.status == "pending"',
+      visible: 'record.viewer.can_act',
       locations: ['record_section', 'list_item'],
       successMessage: 'Approved.',
       refreshAfter: true,
@@ -263,8 +271,9 @@ export const SysApprovalRequest = ObjectSchema.create({
       target: '/api/v1/approvals/requests/{id}/reject',
       params: [
         { name: 'comment', label: 'Comment', type: 'textarea', required: false },
+        { name: 'attachments', label: 'Attachments', type: 'file', multiple: true, required: false },
       ],
-      visible: 'record.status == "pending"',
+      visible: 'record.viewer.can_act',
       confirmText: 'Reject this request? A rejection is final for every approver.',
       locations: ['record_section', 'list_item'],
       successMessage: 'Rejected.',
@@ -286,7 +295,7 @@ export const SysApprovalRequest = ObjectSchema.create({
         { field: 'submitter_id', name: 'to', label: 'New approver', required: true, helpText: 'User to hand this step to' },
         { name: 'comment', label: 'Comment', type: 'textarea', required: false },
       ],
-      visible: 'record.status == "pending"',
+      visible: 'record.viewer.can_act',
       locations: ['record_section'],
       successMessage: 'Reassigned.',
       refreshAfter: true,
@@ -294,8 +303,8 @@ export const SysApprovalRequest = ObjectSchema.create({
 
     // ── Approver secondary decisions ────────────────────────────────
     // Send back for revision / request more info (ADR-0044). Both are approver
-    // actions on a pending request; the service is the authority on who may act,
-    // so `visible` only trims the non-pending case (matching approve/reject).
+    // actions, so `visible` gates on `record.viewer.can_act` (a current pending
+    // approver) — same as approve/reject. The service stays the authority.
     {
       name: 'approval_send_back',
       label: 'Send back',
@@ -306,7 +315,7 @@ export const SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: 'comment', label: 'Reason', type: 'textarea', required: false },
       ],
-      visible: 'record.status == "pending"',
+      visible: 'record.viewer.can_act',
       locations: ['record_section'],
       successMessage: 'Sent back for revision.',
       refreshAfter: true,
@@ -321,7 +330,7 @@ export const SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: 'comment', label: 'What do you need?', type: 'textarea', required: true },
       ],
-      visible: 'record.status == "pending"',
+      visible: 'record.viewer.can_act',
       locations: ['record_section'],
       successMessage: 'Information requested.',
       refreshAfter: true,
@@ -329,10 +338,10 @@ export const SysApprovalRequest = ObjectSchema.create({
 
     // ── Submitter continuity actions ────────────────────────────────
     // Remind / recall (pending) and resubmit / recall (returned). These are the
-    // submitter's own levers, so `visible` gates on `submitter_id == ctx.user.id`
-    // — the current user is exposed via the console's predicate scope. The
-    // service re-checks ownership; the predicate keeps a non-submitter from ever
-    // seeing a button they cannot use.
+    // submitter's own levers, so `visible` gates on `record.viewer.is_submitter`
+    // (server-computed on the current viewer). The service re-checks ownership;
+    // the predicate keeps a non-submitter from ever seeing a button they cannot
+    // use.
     {
       name: 'approval_remind',
       label: 'Send reminder',
@@ -343,7 +352,7 @@ export const SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: 'comment', label: 'Note', type: 'textarea', required: false },
       ],
-      visible: 'record.status == "pending" && record.submitter_id == ctx.user.id',
+      visible: 'record.status == "pending" && record.viewer.is_submitter',
       locations: ['record_section'],
       successMessage: 'Reminder sent.',
       refreshAfter: true,
@@ -360,7 +369,7 @@ export const SysApprovalRequest = ObjectSchema.create({
       ],
       // Recall applies while the request is live for the submitter — pending
       // (withdraw) or returned (abandon the revision instead of resubmitting).
-      visible: '(record.status == "pending" || record.status == "returned") && record.submitter_id == ctx.user.id',
+      visible: '(record.status == "pending" || record.status == "returned") && record.viewer.is_submitter',
       confirmText: 'Recall this request? Approvers can no longer act on it and the record is unlocked.',
       locations: ['record_section'],
       successMessage: 'Recalled.',
@@ -376,7 +385,7 @@ export const SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: 'comment', label: 'What changed?', type: 'textarea', required: false },
       ],
-      visible: 'record.status == "returned" && record.submitter_id == ctx.user.id',
+      visible: 'record.status == "returned" && record.viewer.is_submitter',
       locations: ['record_section'],
       successMessage: 'Resubmitted.',
       refreshAfter: true,

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

@@ -19,7 +19,7 @@ export const SysApprovalToken = ObjectSchema.create({
   pluralLabel: 'Approval Action Tokens',
   icon: 'key',
   isSystem: true,
-  managedBy: 'system',
+  managedBy: 'engine-owned',
   description: 'Single-use tokens behind actionable approval links',
   displayNameField: 'id',
   nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)