feat(documents): detail page with signers, watchers, activity, actions

Replaces the PR4 stub at /documents/[id] with the full Phase A detail
view: gradient header strip, status-aware action bar (Cancel /
Download / Email signatories), per-signer remind + copy-link, watcher
list with remove, and activity timeline. Adds the supporting endpoints
(cancel, compose-completion-email, watchers GET/POST/DELETE) and
listDocumentWatchers / addDocumentWatcher / removeDocumentWatcher
service helpers. The document GET now serves the aggregator shape
when ?detail=true.

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

src/app/(dashboard)/[portSlug]/documents/[id]/page.tsx

@@ -1,6 +1,4 @@
-import Link from 'next/link';
-import { Button } from '@/components/ui/button';
-import { PageHeader } from '@/components/shared/page-header';
+import { DocumentDetail } from '@/components/documents/document-detail';
 
 interface PageProps {
   params: Promise<{ portSlug: string; id: string }>;
@@ -8,17 +6,5 @@ interface PageProps {
 
 export default async function DocumentDetailPage({ params }: PageProps) {
   const { portSlug, id } = await params;
-  return (
-    <div className="flex flex-col gap-4">
-      <PageHeader
-        title="Document detail"
-        description={`Document ${id} — full detail view ships in PR5 of the Phase A rollout.`}
-        actions={
-          <Button asChild variant="outline">
-            <Link href={`/${portSlug}/documents`}>Back to documents</Link>
-          </Button>
-        }
-      />
-    </div>
-  );
+  return <DocumentDetail documentId={id} portSlug={portSlug} />;
 }

src/app/api/v1/documents/[id]/cancel/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { cancelDocument } from '@/lib/services/documents.service';
+
+export const POST = withAuth(
+  withPermission('documents', 'edit', async (_req, ctx, params) => {
+    try {
+      const doc = await cancelDocument(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: doc });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/documents/[id]/compose-completion-email/route.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { composeSignedDocEmail } from '@/lib/services/documents.service';
+
+export const POST = withAuth(
+  withPermission('documents', 'view', async (_req, ctx, params) => {
+    try {
+      const draft = await composeSignedDocEmail(params.id!, ctx.portId);
+      return NextResponse.json({ data: draft });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

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

@@ -5,6 +5,7 @@ import { parseBody } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
 import {
   getDocumentById,
+  getDocumentDetail,
   updateDocument,
   deleteDocument,
 } from '@/lib/services/documents.service';
@@ -13,6 +14,11 @@ import { updateDocumentSchema } from '@/lib/validators/documents';
 export const GET = withAuth(
   withPermission('documents', 'view', async (req, ctx, params) => {
     try {
+      const url = new URL(req.url);
+      if (url.searchParams.get('detail') === 'true') {
+        const detail = await getDocumentDetail(params.id!, ctx.portId);
+        return NextResponse.json({ data: detail });
+      }
       const doc = await getDocumentById(params.id!, ctx.portId);
       return NextResponse.json({ data: doc });
     } catch (error) {

src/app/api/v1/documents/[id]/watchers/[userId]/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { removeDocumentWatcher } from '@/lib/services/documents.service';
+
+export const DELETE = withAuth(
+  withPermission('documents', 'edit', async (_req, ctx, params) => {
+    try {
+      await removeDocumentWatcher(params.id!, ctx.portId, params.userId!, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: { ok: true } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/documents/[id]/watchers/route.ts

@@ -0,0 +1,39 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { addDocumentWatcher, listDocumentWatchers } from '@/lib/services/documents.service';
+
+const addWatcherSchema = z.object({
+  userId: z.string().min(1),
+});
+
+export const GET = withAuth(
+  withPermission('documents', 'view', async (_req, ctx, params) => {
+    try {
+      const watchers = await listDocumentWatchers(params.id!, ctx.portId);
+      return NextResponse.json({ data: watchers });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('documents', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, addWatcherSchema);
+      const watcher = await addDocumentWatcher(params.id!, ctx.portId, body.userId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: watcher }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);