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/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>;