feat(documents): entity-aggregated query params + signing-details API

GET /api/v1/files?entityType=client&entityId=… and the same params on
the documents route return the owner-aggregated projection
{ groups: [{ label, source, files|workflows, total }] }. folderId
remains for direct-folder listing; the two modes are mutually
exclusive (zod refine).

GET /api/v1/documents/[id]/signing-details returns
{ workflow, signers, events } for the "view signing details" dialog
on signed-PDF rows.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/v1/documents/[id]/signing-details/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  getDocumentById,
+  listDocumentSigners,
+  listDocumentEvents,
+} from '@/lib/services/documents.service';
+
+export const GET = withAuth(
+  withPermission('documents', 'view', async (_req, ctx, params) => {
+    try {
+      const id = params.id!;
+      const [workflow, signers, events] = await Promise.all([
+        getDocumentById(id, ctx.portId),
+        listDocumentSigners(id, ctx.portId),
+        listDocumentEvents(id, ctx.portId),
+      ]);
+      return NextResponse.json({ data: { workflow, signers, events } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/documents/route.ts

@@ -3,13 +3,27 @@ import { NextResponse } from 'next/server';
 import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseQuery, parseBody } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
-import { listDocuments, createDocument } from '@/lib/services/documents.service';
+import {
+  listDocuments,
+  createDocument,
+  listInflightWorkflowsAggregatedByEntity,
+} from '@/lib/services/documents.service';
 import { listDocumentsSchema, createDocumentSchema } from '@/lib/validators/documents';
 
 export const GET = withAuth(
   withPermission('documents', 'view', async (req, ctx) => {
     try {
       const query = parseQuery(req, listDocumentsSchema);
+
+      if (query.entityType && query.entityId) {
+        const result = await listInflightWorkflowsAggregatedByEntity(
+          ctx.portId,
+          query.entityType,
+          query.entityId,
+        );
+        return NextResponse.json({ data: result });
+      }
+
       const result = await listDocuments(ctx.portId, query, {
         currentUserEmail: ctx.user.email,
       });

src/app/api/v1/files/route.ts

@@ -3,13 +3,23 @@ import { NextResponse } from 'next/server';
 import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseQuery } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
-import { listFiles } from '@/lib/services/files';
+import { listFiles, listFilesAggregatedByEntity } from '@/lib/services/files';
 import { listFilesSchema } from '@/lib/validators/files';
 
 export const GET = withAuth(
   withPermission('files', 'view', async (req, ctx) => {
     try {
       const query = parseQuery(req, listFilesSchema);
+
+      if (query.entityType && query.entityId) {
+        const result = await listFilesAggregatedByEntity(
+          ctx.portId,
+          query.entityType,
+          query.entityId,
+        );
+        return NextResponse.json({ data: result });
+      }
+
       const result = await listFiles(ctx.portId, query);
 
       const { page, limit } = query;

src/lib/validators/documents.ts

@@ -81,25 +81,36 @@ export const documentsHubTabs = [
 ] as const;
 export type DocumentsHubTab = (typeof documentsHubTabs)[number];
 
-export const listDocumentsSchema = baseListQuerySchema.extend({
-  interestId: z.string().optional(),
-  clientId: z.string().optional(),
-  documentType: z.string().optional(),
-  folderId: z.string().nullable().optional(),
-  includeDescendants: z.coerce.boolean().optional(),
-  status: z.string().optional(),
-  /** Hub tab filter - applies tab-specific status / signer-membership constraints. */
-  tab: z.enum(documentsHubTabs).optional(),
-  /** Restrict to docs being watched by this user id. */
-  watcherUserId: z.string().optional(),
-  /** When true, only docs intended for signing (default true on hub). */
-  signatureOnly: z
-    .enum(['true', 'false'])
-    .optional()
-    .transform((v) => (v === undefined ? undefined : v === 'true')),
-  sentSince: z.string().datetime().optional(),
-  sentUntil: z.string().datetime().optional(),
-});
+export const listDocumentsSchema = baseListQuerySchema
+  .extend({
+    interestId: z.string().optional(),
+    clientId: z.string().optional(),
+    documentType: z.string().optional(),
+    folderId: z.string().nullable().optional(),
+    includeDescendants: z.coerce.boolean().optional(),
+    status: z.string().optional(),
+    /** Hub tab filter - applies tab-specific status / signer-membership constraints. */
+    tab: z.enum(documentsHubTabs).optional(),
+    /** Restrict to docs being watched by this user id. */
+    watcherUserId: z.string().optional(),
+    /** When true, only docs intended for signing (default true on hub). */
+    signatureOnly: z
+      .enum(['true', 'false'])
+      .optional()
+      .transform((v) => (v === undefined ? undefined : v === 'true')),
+    sentSince: z.string().datetime().optional(),
+    sentUntil: z.string().datetime().optional(),
+    /** Entity-aggregated projection params — mutually exclusive with folderId. */
+    entityType: z.enum(['client', 'company', 'yacht']).optional(),
+    entityId: z.string().uuid().optional(),
+  })
+  .refine(
+    (q) => !(q.folderId !== undefined && (q.entityType !== undefined || q.entityId !== undefined)),
+    { message: 'folderId is mutually exclusive with entityType/entityId' },
+  )
+  .refine((q) => Boolean(q.entityType) === Boolean(q.entityId), {
+    message: 'entityType and entityId must be provided together',
+  });
 
 export const uploadSignedSchema = z.object({
   documentId: z.string().min(1),

src/lib/validators/files.ts

@@ -18,14 +18,24 @@ export const updateFileSchema = z.object({
   category: z.string().optional(),
 });
 
-export const listFilesSchema = baseListQuerySchema.extend({
-  clientId: z.string().optional(),
-  yachtId: z.string().optional(),
-  companyId: z.string().optional(),
-  category: z.string().optional(),
-  entityType: z.string().optional(),
-  entityId: z.string().optional(),
-});
+export const listFilesSchema = baseListQuerySchema
+  .extend({
+    clientId: z.string().optional(),
+    yachtId: z.string().optional(),
+    companyId: z.string().optional(),
+    category: z.string().optional(),
+    folderId: z.string().uuid().optional(),
+    /** Entity-aggregated projection params — mutually exclusive with folderId. */
+    entityType: z.enum(['client', 'company', 'yacht']).optional(),
+    entityId: z.string().uuid().optional(),
+  })
+  .refine(
+    (q) => !(q.folderId !== undefined && (q.entityType !== undefined || q.entityId !== undefined)),
+    { message: 'folderId is mutually exclusive with entityType/entityId' },
+  )
+  .refine((q) => Boolean(q.entityType) === Boolean(q.entityId), {
+    message: 'entityType and entityId must be provided together',
+  });
 
 export type UploadFileInput = z.infer<typeof uploadFileSchema>;
 export type UpdateFileInput = z.infer<typeof updateFileSchema>;