261 lines
12 KiB
Markdown
261 lines
12 KiB
Markdown
---
|
|
phase: 15-multi-signer-backend
|
|
plan: 02
|
|
type: execute
|
|
wave: 2
|
|
depends_on: [15-01]
|
|
files_modified:
|
|
- teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts
|
|
autonomous: true
|
|
requirements: [MSIGN-05, MSIGN-06]
|
|
must_haves:
|
|
truths:
|
|
- "When documents.signers is populated, one signing token is created per signer with that signer's email"
|
|
- "All signing request emails are dispatched in parallel via Promise.all"
|
|
- "When documents.signers is null/empty, the existing single-signer behavior is preserved exactly"
|
|
- "The signing URL uses APP_BASE_URL (not NEXT_PUBLIC_BASE_URL)"
|
|
- "Document status is set to Sent after all emails dispatch successfully"
|
|
- "Each signer gets an audit event email_sent with metadata.signerEmail"
|
|
artifacts:
|
|
- path: "teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts"
|
|
provides: "Multi-signer send route with legacy fallback"
|
|
exports: ["POST"]
|
|
key_links:
|
|
- from: "src/app/api/documents/[id]/send/route.ts"
|
|
to: "src/lib/signing/token.ts"
|
|
via: "createSigningToken(doc.id, signer.email)"
|
|
pattern: "createSigningToken.*signerEmail"
|
|
- from: "src/app/api/documents/[id]/send/route.ts"
|
|
to: "src/lib/signing/signing-mailer.tsx"
|
|
via: "sendSigningRequestEmail in Promise.all loop"
|
|
pattern: "Promise\\.all.*sendSigningRequestEmail"
|
|
---
|
|
|
|
<objective>
|
|
Rewrite the send route to loop over document signers, create one token per signer, and dispatch all signing emails in parallel. Preserve exact legacy single-signer behavior when signers is null/empty. Fix NEXT_PUBLIC_BASE_URL to APP_BASE_URL.
|
|
|
|
Purpose: This is the entry point for multi-signer flow — without this, documents can only be sent to one recipient.
|
|
Output: Rewritten send/route.ts with multi-signer token loop + legacy fallback.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
|
@$HOME/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/phases/15-multi-signer-backend/15-CONTEXT.md
|
|
@.planning/phases/15-multi-signer-backend/15-RESEARCH.md
|
|
@.planning/phases/15-multi-signer-backend/15-01-SUMMARY.md
|
|
|
|
@teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts
|
|
@teressa-copeland-homes/src/lib/signing/token.ts
|
|
@teressa-copeland-homes/src/lib/db/schema.ts
|
|
|
|
<interfaces>
|
|
<!-- From Plan 01 — token.ts now has: -->
|
|
```typescript
|
|
export async function createSigningToken(documentId: string, signerEmail?: string): Promise<{ token: string; jti: string; expiresAt: Date }>;
|
|
```
|
|
|
|
<!-- From schema.ts — documents.signers type: -->
|
|
```typescript
|
|
export interface DocumentSigner { email: string; color: string; }
|
|
// documents.signers is jsonb().$type<DocumentSigner[]>() — nullable
|
|
```
|
|
|
|
<!-- Current send route signature (being rewritten): -->
|
|
```typescript
|
|
export async function POST(_req: Request, { params }: { params: Promise<{ id: string }> })
|
|
```
|
|
|
|
<!-- Existing imports used by send route: -->
|
|
```typescript
|
|
import { createSigningToken } from '@/lib/signing/token';
|
|
import { sendSigningRequestEmail } from '@/lib/signing/signing-mailer';
|
|
import { logAuditEvent } from '@/lib/signing/audit';
|
|
import { documents, clients } from '@/lib/db/schema';
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Rewrite send route with multi-signer token loop and legacy fallback</name>
|
|
<files>teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts</files>
|
|
<read_first>
|
|
- teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts
|
|
- teressa-copeland-homes/src/lib/signing/token.ts (confirm signerEmail param exists from Plan 01)
|
|
- teressa-copeland-homes/src/lib/signing/signing-mailer.tsx (confirm sendSigningRequestEmail signature)
|
|
- teressa-copeland-homes/src/lib/db/schema.ts (confirm DocumentSigner type, documents.signers)
|
|
- teressa-copeland-homes/node_modules/next/dist/docs/ (scan for route handler API)
|
|
</read_first>
|
|
<action>
|
|
Rewrite the POST handler in `src/app/api/documents/[id]/send/route.ts`. The structure:
|
|
|
|
**Keep unchanged:** auth guard, doc fetch, preparedFilePath guard, status === 'Signed' guard, error boundary try/catch.
|
|
|
|
**Change 1 — APP_BASE_URL (Pitfall 5, per quality gate):** Replace `process.env.NEXT_PUBLIC_BASE_URL` with `process.env.APP_BASE_URL` on the baseUrl line. Keep `?? 'http://localhost:3000'` fallback.
|
|
|
|
**Change 2 — Branching logic (D-01, D-02):** After the doc fetch and guards, branch on `doc.signers && doc.signers.length > 0`:
|
|
|
|
**Multi-signer path (D-02):**
|
|
```typescript
|
|
const signers = doc.signers as DocumentSigner[];
|
|
const baseUrl = process.env.APP_BASE_URL ?? 'http://localhost:3000';
|
|
|
|
await Promise.all(
|
|
signers.map(async (signer) => {
|
|
const { token, expiresAt } = await createSigningToken(doc.id, signer.email);
|
|
const signingUrl = `${baseUrl}/sign/${token}`;
|
|
await sendSigningRequestEmail({
|
|
to: signer.email,
|
|
documentName: doc.name,
|
|
signingUrl,
|
|
expiresAt,
|
|
});
|
|
await logAuditEvent({
|
|
documentId: doc.id,
|
|
eventType: 'email_sent',
|
|
metadata: { signerEmail: signer.email },
|
|
});
|
|
})
|
|
);
|
|
```
|
|
|
|
Note: `sendSigningRequestEmail` has an optional `clientName` param. In multi-signer mode, we do NOT have a per-signer name (DocumentSigner is `{ email, color }` only). Omitting `clientName` is fine — the email template handles it gracefully.
|
|
|
|
**Legacy single-signer path (D-01):** Keep the existing logic verbatim — resolve clientId, fetch client, create single token (no signerEmail), send email with client.name, log audit event. Only change is `APP_BASE_URL` instead of `NEXT_PUBLIC_BASE_URL`.
|
|
|
|
**After branch:** Both paths converge — update status to 'Sent' if currently 'Draft' (existing logic, unchanged). Return `{ ok: true, expiresAt }` — for multi-signer, use the last signer's expiresAt or just return `ok: true` without expiresAt (all tokens have the same 72h TTL anyway).
|
|
|
|
**Import changes:** Add `DocumentSigner` import from schema if not already imported.
|
|
|
|
**Error handling (Claude's Discretion):** Individual signer email failure should not block the entire send. Wrap each signer's map callback in try/catch — if one email fails, the others still send. Collect errors and return 207 Multi-Status if partial failure, or 502 if all fail. Alternatively, keep it simple: let Promise.all fail if any email fails (current behavior for single signer). Decision: keep Promise.all as-is for now (simple, consistent with existing pattern). If one email fails, the entire send fails and the agent retries.
|
|
|
|
Complete rewrite:
|
|
|
|
```typescript
|
|
import { NextResponse } from 'next/server';
|
|
import { auth } from '@/lib/auth';
|
|
import { db } from '@/lib/db';
|
|
import { documents, clients, DocumentSigner } from '@/lib/db/schema';
|
|
import { eq } from 'drizzle-orm';
|
|
import { createSigningToken } from '@/lib/signing/token';
|
|
import { sendSigningRequestEmail } from '@/lib/signing/signing-mailer';
|
|
import { logAuditEvent } from '@/lib/signing/audit';
|
|
|
|
export async function POST(
|
|
_req: Request,
|
|
{ params }: { params: Promise<{ id: string }> }
|
|
) {
|
|
const session = await auth();
|
|
if (!session) return new Response('Unauthorized', { status: 401 });
|
|
|
|
const { id } = await params;
|
|
|
|
try {
|
|
const doc = await db.query.documents.findFirst({
|
|
where: eq(documents.id, id),
|
|
});
|
|
if (!doc) return NextResponse.json({ error: 'Document not found' }, { status: 404 });
|
|
if (!doc.preparedFilePath)
|
|
return NextResponse.json({ error: 'Document not yet prepared' }, { status: 422 });
|
|
if (doc.status === 'Signed')
|
|
return NextResponse.json({ error: 'Already signed' }, { status: 409 });
|
|
|
|
const baseUrl = process.env.APP_BASE_URL ?? 'http://localhost:3000';
|
|
|
|
if (doc.signers && (doc.signers as DocumentSigner[]).length > 0) {
|
|
// ── Multi-signer path (D-02) ──
|
|
const signers = doc.signers as DocumentSigner[];
|
|
await Promise.all(
|
|
signers.map(async (signer) => {
|
|
const { token, expiresAt } = await createSigningToken(doc.id, signer.email);
|
|
const signingUrl = `${baseUrl}/sign/${token}`;
|
|
await sendSigningRequestEmail({
|
|
to: signer.email,
|
|
documentName: doc.name,
|
|
signingUrl,
|
|
expiresAt,
|
|
});
|
|
await logAuditEvent({
|
|
documentId: doc.id,
|
|
eventType: 'email_sent',
|
|
metadata: { signerEmail: signer.email },
|
|
});
|
|
})
|
|
);
|
|
} else {
|
|
// ── Legacy single-signer path (D-01) ──
|
|
const clientId = doc.assignedClientId ?? doc.clientId;
|
|
const client = await db.query.clients.findFirst({ where: eq(clients.id, clientId) });
|
|
if (!client) return NextResponse.json({ error: 'Client not found' }, { status: 422 });
|
|
|
|
const { token, expiresAt } = await createSigningToken(doc.id);
|
|
const signingUrl = `${baseUrl}/sign/${token}`;
|
|
await sendSigningRequestEmail({
|
|
to: client.email,
|
|
clientName: client.name,
|
|
documentName: doc.name,
|
|
signingUrl,
|
|
expiresAt,
|
|
});
|
|
await logAuditEvent({ documentId: doc.id, eventType: 'email_sent' });
|
|
}
|
|
|
|
// Update status to Sent (skip if already Sent or Signed to avoid downgrade)
|
|
if (doc.status === 'Draft') {
|
|
await db
|
|
.update(documents)
|
|
.set({ status: 'Sent', sentAt: new Date() })
|
|
.where(eq(documents.id, id));
|
|
}
|
|
|
|
return NextResponse.json({ ok: true });
|
|
} catch (err) {
|
|
console.error('[send] error:', err);
|
|
return NextResponse.json({ error: 'Failed to send signing email' }, { status: 502 });
|
|
}
|
|
}
|
|
```
|
|
</action>
|
|
<verify>
|
|
<automated>cd teressa-copeland-homes && npx tsc --noEmit 2>&1 | head -30</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- grep confirms APP_BASE_URL: `grep "APP_BASE_URL" src/app/api/documents/\[id\]/send/route.ts`
|
|
- grep confirms NO NEXT_PUBLIC_BASE_URL: `grep -c "NEXT_PUBLIC_BASE_URL" src/app/api/documents/\[id\]/send/route.ts` returns 0
|
|
- grep confirms multi-signer branch: `grep "doc.signers" src/app/api/documents/\[id\]/send/route.ts`
|
|
- grep confirms Promise.all: `grep "Promise.all" src/app/api/documents/\[id\]/send/route.ts`
|
|
- grep confirms createSigningToken with signerEmail: `grep "createSigningToken(doc.id, signer.email)" src/app/api/documents/\[id\]/send/route.ts`
|
|
- grep confirms legacy path still uses createSigningToken without signerEmail: `grep "createSigningToken(doc.id)" src/app/api/documents/\[id\]/send/route.ts`
|
|
- grep confirms metadata with signerEmail in audit: `grep "signerEmail: signer.email" src/app/api/documents/\[id\]/send/route.ts`
|
|
- grep confirms DocumentSigner import: `grep "DocumentSigner" src/app/api/documents/\[id\]/send/route.ts`
|
|
- `npx tsc --noEmit` passes with zero errors
|
|
</acceptance_criteria>
|
|
<done>Send route creates one token per signer with signerEmail written to DB, dispatches all emails in parallel. Legacy single-signer path preserved unchanged. APP_BASE_URL replaces NEXT_PUBLIC_BASE_URL.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
`cd teressa-copeland-homes && npx tsc --noEmit` passes
|
|
Send route has both multi-signer and legacy branches
|
|
APP_BASE_URL used instead of NEXT_PUBLIC_BASE_URL
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
1. Multi-signer documents: `doc.signers = [{email: 'a@x.com', color: '#f00'}, {email: 'b@x.com', color: '#0f0'}]` results in 2 tokens created, 2 emails sent, 2 audit events
|
|
2. Legacy documents: `doc.signers = null` results in 1 token (no signerEmail), 1 email to assigned client
|
|
3. `APP_BASE_URL` is the env var used for signing URLs (not `NEXT_PUBLIC_BASE_URL`)
|
|
4. `npx tsc --noEmit` passes
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/15-multi-signer-backend/15-02-SUMMARY.md`
|
|
</output>
|