perf(approvals): accept multiple approverIds in one listRequests call

The Console topbar badge resolved "my pending approvals" by looping one
GET /approvals/requests per identity (user id, email, each role:<r>),
firing N near-simultaneous requests every poll — a dominant source of
duplicate control-plane traffic.

Widen the listRequests filter (spec contract + service + client) and the
REST handler to accept `approverId` as a single value, a comma-separated
list, or a repeated query param, matching a request when ANY identity is
a pending approver. The client now sends one request for all identities.

Backward compatible: a single approverId still works. Adds a test
covering list matching + empty-id handling.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

packages/client/src/index.ts

@@ -2519,7 +2519,7 @@ export class ObjectStackClient {
       object?: string;
       recordId?: string;
       status?: ApprovalStatus | ApprovalStatus[];
-      approverId?: string;
+      approverId?: string | string[];
       submitterId?: string;
     }): Promise<ApprovalRequestRow[]> => {
       const route = this.getRoute('approvals');
@@ -2529,7 +2529,9 @@ export class ObjectStackClient {
       if (filter?.status) {
         params.set('status', Array.isArray(filter.status) ? filter.status.join(',') : filter.status);
       }
-      if (filter?.approverId) params.set('approverId', filter.approverId);
+      if (filter?.approverId) {
+        params.set('approverId', Array.isArray(filter.approverId) ? filter.approverId.join(',') : filter.approverId);
+      }
       if (filter?.submitterId) params.set('submitterId', filter.submitterId);
       const qs = params.toString();
       const res = await this.fetch(`${this.baseUrl}${route}/requests${qs ? `?${qs}` : ''}`);

packages/plugins/plugin-approvals/src/approval-service.test.ts

@@ -264,6 +264,22 @@ describe('ApprovalService (node era)', () => {
     expect(none).toHaveLength(0);
   });
 
+  it('listRequests: approverId accepts a list and matches ANY identity', async () => {
+    await svc.openNodeRequest(openInput(['u9']), CTX);
+    // None of these identities individually except the last is the approver.
+    const hit = await svc.listRequests(
+      { status: 'pending', approverId: ['someone-else', 'user@example.com', 'u9'] },
+      SYS,
+    );
+    expect(hit).toHaveLength(1);
+    // A list with no matching identity returns nothing.
+    const miss = await svc.listRequests({ approverId: ['a', 'b', 'role:viewer'] }, SYS);
+    expect(miss).toHaveLength(0);
+    // Empty / whitespace-only ids are ignored, not treated as a match-all.
+    const ignored = await svc.listRequests({ approverId: ['', '  '] }, SYS);
+    expect(ignored).toHaveLength(1);
+  });
+
   it('listActions: returns the audit trail for a request', async () => {
     const req = await svc.openNodeRequest(openInput(['u9']), CTX);
     await svc.decideNode(req.id, { decision: 'approve', actorId: 'u9' }, SYS);

packages/plugins/plugin-approvals/src/approval-service.ts

@@ -470,7 +470,7 @@ export class ApprovalService implements IApprovalService {
       object?: string;
       recordId?: string;
       status?: ApprovalStatus | ApprovalStatus[];
-      approverId?: string;
+      approverId?: string | string[];
       submitterId?: string;
     } | undefined,
     context: SharingExecutionContext,
@@ -498,8 +498,20 @@ export class ApprovalService implements IApprovalService {
     let list = Array.isArray(rows) ? rows.map(rowFromRequest) : [];
     if (statusFilter) list = list.filter(r => statusFilter!.includes(r.status));
     if (filter?.approverId) {
-      const target = filter.approverId;
-      list = list.filter(r => (r.pending_approvers ?? []).includes(target));
+      // Accept one identity or a list: a request matches when ANY of the
+      // caller's identities (user id / email / role:<r>) is a pending
+      // approver. This lets the Console badge fetch "my pending approvals"
+      // in a single request instead of one-per-identity (previously the
+      // client looped, firing N near-simultaneous calls per poll).
+      const targets = (Array.isArray(filter.approverId) ? filter.approverId : [filter.approverId])
+        .map(t => String(t).trim())
+        .filter(Boolean);
+      if (targets.length) {
+        list = list.filter(r => {
+          const pending = r.pending_approvers ?? [];
+          return targets.some(t => pending.includes(t));
+        });
+      }
     }
     return list;
   }

packages/rest/src/rest-server.ts

@@ -3990,11 +3990,21 @@ export class RestServer {
                         return;
                     }
                     const q = req.query ?? {};
+                    // `approverId` accepts a single id, a comma-separated
+                    // list, or the param repeated (→ array). Normalise all
+                    // three to a string[] so the Console can resolve "my
+                    // pending approvals" across every identity (user id /
+                    // email / role:<r>) in ONE request rather than looping.
+                    const rawApprover = q.approverId ?? q.approver_id;
+                    const approverIds = (Array.isArray(rawApprover) ? rawApprover : (rawApprover != null ? [rawApprover] : []))
+                        .flatMap((s: any) => String(s).split(','))
+                        .map((s: string) => s.trim())
+                        .filter(Boolean);
                     const rows = await svc.listRequests({
                         object: q.object,
                         recordId: q.recordId ?? q.record_id,
                         status: q.status,
-                        approverId: q.approverId ?? q.approver_id,
+                        approverId: approverIds.length ? approverIds : undefined,
                         submitterId: q.submitterId ?? q.submitter_id,
                     }, context ?? {});
                     res.json({ data: rows });

packages/spec/src/contracts/approval-service.ts

@@ -88,7 +88,14 @@ export interface IApprovalService {
       object?: string;
       recordId?: string;
       status?: ApprovalStatus | ApprovalStatus[];
-      approverId?: string;
+      /**
+       * Match requests where ANY of these identities is a pending approver.
+       * Accepts a single id or a list (a user typically has several
+       * identities: their user id, email, and `role:<r>` entries). Passing
+       * the list lets a caller resolve "my pending approvals" in ONE request
+       * instead of one request per identity.
+       */
+      approverId?: string | string[];
       submitterId?: string;
     } | undefined,
     context: SharingExecutionContext,