feat(emails): sales send-out flows + brochures + email-from settings

Phase 7 of the berth-recommender refactor (plan §3.3, §4.8, §4.9, §5.7,
§5.8, §5.9, §11.1, §14.7, §14.9). Adds the rep-driven send-out path for
per-berth PDFs and port-wide brochures, the per-port sales SMTP/IMAP
config + body templates, and the supporting admin UI.

Migration: 0031_brochures_and_document_sends.sql

Schema additions:
  - brochures (port-wide, with isDefault marker + archive)
  - brochure_versions (versioned uploads, storageKey per §4.7a)
  - document_sends (audit log of every rep-initiated send; failures
    captured with failedAt + errorReason). berthPdfVersionId is a plain
    text column (no FK) — loose-coupled to Phase 6b's berth_pdf_versions
    so the two phases stay independent.

§14.7 critical mitigations:
  - Body XSS: rep-authored markdown goes through renderEmailBody()
    (HTML-escape first, then a tight allowlist of bold/italic/code/link
    rules). https:// + mailto: only — javascript:/data: URLs stripped.
    Tested against script/img/iframe/svg/onerror polyglots.
  - Recipient typo: strict email regex + two-step confirm modal that
    shows the exact recipient before send.
  - Unresolved merge fields: pre-send dry-run /preview endpoint blocks
    submission until findUnresolvedTokens() returns empty.
  - SMTP failure: every transport rejection writes a document_sends row
    with failedAt + errorReason; UI surfaces the message.
  - Hourly per-user rate limit: 50 sends/user/hour via existing
    checkRateLimit().
  - Size threshold fallback (§11.1): files above
    email_attach_threshold_mb (default 15) ship as a 24h signed-URL
    download link in the body instead of an attachment. Storage stream
    flows directly to nodemailer to avoid buffering 20MB+.

§14.10 critical mitigation:
  - SMTP/IMAP passwords encrypted at rest via the existing
    EMAIL_CREDENTIAL_KEY (AES-256-GCM). The /api/v1/admin/email/
    sales-config GET endpoint never returns the decrypted value — only
    a *PassIsSet boolean. PATCH treats empty string as "leave unchanged"
    and explicit null as "clear", so the masked-placeholder UI round-
    trips without forcing re-entry on every save.

system_settings keys (per-port unless noted):
  - sales_from_address, sales_smtp_{host,port,secure,user,pass_encrypted}
  - sales_imap_{host,port,user,pass_encrypted}
  - sales_auth_method (default app_password)
  - noreply_from_address
  - email_template_send_berth_pdf_body, email_template_send_brochure_body
  - brochure_max_upload_mb (default 50)
  - email_attach_threshold_mb (default 15)

UI surfaces (per §5.7, §5.8, §5.9):
  - <SendDocumentDialog> shared 2-step compose+confirm flow.
  - <SendBerthPdfDialog>, <SendDocumentsDialog>, <SendFromInterestButton>
    wrappers per detail page.
  - /[portSlug]/admin/brochures: list, upload (direct-to-storage
    presigned PUT for the 20MB+ files per §11.1), default toggle,
    archive.
  - /[portSlug]/admin/email extended with <SalesEmailConfigCard>:
    SMTP + IMAP creds, body templates, threshold/max settings.

Storage: every upload + download goes through getStorageBackend() —
no direct minio imports, per Phase 6a contract.

Tests: 1145 vitest passing (+ 50 new in
markdown-email-sanitization.test.ts, document-sends-validators.test.ts,
sales-email-config-validators.test.ts).

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

src/app/api/v1/document-sends/berth-pdf/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { sendBerthPdf } from '@/lib/services/document-sends.service';
+import { sendBerthPdfSchema } from '@/lib/validators/document-sends';
+
+/**
+ * POST /api/v1/document-sends/berth-pdf
+ *
+ * Sends the active per-berth PDF version to a client recipient. The body
+ * markdown goes through the merge-field expander + sanitizer
+ * (`renderEmailBody`) before reaching nodemailer (§14.7 critical mitigation:
+ * body XSS).
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const input = await parseBody(req, sendBerthPdfSchema);
+    const result = await sendBerthPdf({
+      portId: ctx.portId,
+      berthId: input.berthId,
+      recipient: input.recipient,
+      customBodyMarkdown: input.customBodyMarkdown,
+      sentBy: ctx.userId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/document-sends/brochure/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { sendBrochure } from '@/lib/services/document-sends.service';
+import { sendBrochureSchema } from '@/lib/validators/document-sends';
+
+/**
+ * POST /api/v1/document-sends/brochure
+ *
+ * Sends a brochure (default or specified) to a client recipient. Same
+ * sanitization + audit-row pipeline as the berth-pdf endpoint.
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const input = await parseBody(req, sendBrochureSchema);
+    const result = await sendBrochure({
+      portId: ctx.portId,
+      brochureId: input.brochureId,
+      recipient: input.recipient,
+      customBodyMarkdown: input.customBodyMarkdown,
+      sentBy: ctx.userId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/document-sends/preview/route.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { previewBody } from '@/lib/services/document-sends.service';
+import { previewBodySchema } from '@/lib/validators/document-sends';
+
+/**
+ * POST /api/v1/document-sends/preview
+ *
+ * Renders a body for the dry-run UI without actually sending. Returns the
+ * sanitized HTML, the post-merge markdown, and the list of unresolved
+ * `{{tokens}}` so the UI can block submit until the rep fills them in
+ * (§14.7 mitigation).
+ */
+export const POST = withAuth(async (req, ctx) => {
+  try {
+    const input = await parseBody(req, previewBodySchema);
+    const result = await previewBody(
+      ctx.portId,
+      input.documentKind,
+      input.recipient,
+      input.customBodyMarkdown ?? null,
+      { berthId: input.berthId, brochureLabel: input.brochureId },
+    );
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});

src/app/api/v1/document-sends/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseQuery } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listSends } from '@/lib/services/document-sends.service';
+import { listSendsQuerySchema } from '@/lib/validators/document-sends';
+
+export const GET = withAuth(async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listSendsQuerySchema);
+    const data = await listSends({
+      portId: ctx.portId,
+      clientId: query.clientId,
+      interestId: query.interestId,
+      berthId: query.berthId,
+      limit: query.limit,
+    });
+    return NextResponse.json({ data });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});