diff --git a/CLAUDE.md b/CLAUDE.md index cc075dae..000b2f94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -88,7 +88,7 @@ src/ - **Polymorphic ownership:** Yachts and invoice billing-entities use `_type` + `_id` column pairs (`'client' | 'company'`). Resolve owner identity through `src/lib/services/yachts.service.ts` / `eoi-context.ts` rather than reading the columns ad hoc — those services apply the type discriminator. - **EOI generation:** Two pathways share the same `EoiContext` (`src/lib/services/eoi-context.ts`). Documenso pathway calls the template-generate endpoint via `documenso-payload.ts`; in-app pathway fills the same source PDF (`assets/eoi-template.pdf`) via `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm). Routed through `generateAndSign(...)` in `src/lib/services/document-templates.ts` with a `pathway` parameter. - **Merge fields:** Token catalog lives in `src/lib/templates/merge-fields.ts`; the `createTemplateSchema` validator uses `VALID_MERGE_TOKENS` as an allow-list, so unknown tokens are rejected at template creation time. -- **Documenso webhooks:** Documenso (both v1.13 and 2.x) authenticates outbound webhooks by sending the configured secret in plaintext via the `X-Documenso-Secret` header — there is no HMAC. The receiver at `src/app/api/webhooks/documenso/route.ts` does a timing-safe equality check via `verifyDocumensoSecret`. Event names arrive as the uppercase Prisma enum on the wire (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED`, etc.) even though the UI displays them as lowercase-dotted. The route also normalizes lowercase-dotted variants for forward-compat. +- **Documenso webhooks:** Documenso (both v1.13 and 2.x) authenticates outbound webhooks by sending the configured secret in plaintext via the `X-Documenso-Secret` header — there is no HMAC. The receiver at `src/app/api/webhooks/documenso/route.ts` does a timing-safe equality check via `verifyDocumensoSecret`. Event names arrive as the uppercase Prisma enum on the wire (`DOCUMENT_SIGNED`, `DOCUMENT_COMPLETED`, etc.) even though the UI displays them as lowercase-dotted. The route also normalizes lowercase-dotted variants for forward-compat. `handleDocumentCompleted` is **idempotent** — early-returns when `doc.status === 'completed' && doc.signedFileId` so Documenso retries on 5xx don't insert duplicate file rows + orphan blobs. The switch handles `DOCUMENT_SIGNED|COMPLETED|REJECTED|DECLINED|OPENED|EXPIRED`, plus v2 aliases `RECIPIENT_VIEWED` / `RECIPIENT_SIGNED` (logged + routed to v1 equivalents). - **Documenso API responses:** 2.x renamed `id` → `documentId` and recipient `id` → `recipientId`; v1.13 still uses `id`. `src/lib/services/documenso-client.ts` runs every response through `normalizeDocument()` which reads either field name and surfaces the legacy `id` form to downstream consumers. - **Email templates:** Branded HTML lives in `src/lib/email/templates/`. The portal-auth flow uses `portal-auth.ts` (activation + reset). All templates use the legacy table-based layout with the Port Nimara logo + blurred overhead background, max-width 600px and `width:100%` for responsive shrink. The `` URLs reference `s3.portnimara.com` directly (will move to `/public` later). - **Portal auth pages:** `/portal/login`, `/portal/activate`, `/portal/reset-password` and the CRM `/login`, `/reset-password`, `/set-password` all wrap their content in `` (`src/components/shared/branded-auth-shell.tsx`) which renders the same blurred background + logo + white card the email templates use, so the in-app and email surfaces look unified. @@ -112,8 +112,9 @@ src/ - **Mooring number canonical format:** `^[A-Z]+\d+$` (e.g. `A1`, `B12`, `E18`) — no hyphen, no leading zeros. Stored, displayed, URL-encoded, and rendered in EOIs in this exact form. Phase 0 normalized the entire CRM dataset; the mooring-pattern regex gates the public `/api/public/berths/[mooringNumber]` route before any DB hit. - **Public berths API:** `/api/public/berths` (list) and `/api/public/berths/[mooringNumber]` (single) are the public-facing data feed for the marketing website. Output shape mirrors the legacy NocoDB Berths shape verbatim (`"Mooring Number"`, `"Side Pontoon"`, etc.) — see `src/lib/services/public-berths.ts`. Cache headers: `s-maxage=300, stale-while-revalidate=60`. Status mapping: `"Sold"` (berth.status=sold) > `"Under Offer"` (status=under_offer OR has any active `interest_berths.is_specific_interest=true` link with `interests.outcome IS NULL`) > `"Available"`. The companion `/api/public/health` endpoint is dual-mode: anonymous callers get `{status, timestamp}` (uptime monitors, never 503); requests carrying a timing-safe-matched `X-Intake-Secret` (compared against `WEBSITE_INTAKE_SECRET`) get the full `{status, env, appUrl, timestamp, checks: {db, redis}}` payload and a 503 if any dependency is down. The website uses the authenticated form on startup so it refuses to start when its `CRM_PUBLIC_URL` points at a different deployment env. - **Berth recommender:** Pure SQL ranking (no AI). Lives in `src/lib/services/berth-recommender.service.ts`. Tier ladder A/B/C/D classifies each feasible berth based on its `interest_berths` aggregates. Heat scoring (recency / furthest stage / interest count / EOI count) only fires for tier B (lost/cancelled-only history); per-port admin tunes weights via `system_settings` keys (`heat_weight_*`, `recommender_max_oversize_pct`, `recommender_top_n_default`, `fallthrough_policy`, `fallthrough_cooldown_days`, `tier_ladder_hide_late_stage`). The recommender enforces multi-port isolation both at the entry point (rejects cross-port interest lookups) AND inside the SQL aggregates CTE (defense-in-depth `i.port_id` filter). +- **Berth rules engine:** Per-port `system_settings` rules in `src/lib/services/berth-rules-engine.ts`. Seven triggers, all wired: `eoi_sent`, `eoi_signed`, `deposit_received` (invoices.ts), `contract_signed` (documents.service.ts), `interest_archived` / `interest_completed` (interests.service.ts), `berth_unlinked` (interest-berths.service.ts). Service callers fire `evaluateRule(trigger, interestId, portId, meta)` via dynamic import to avoid circular deps. Default modes vary (`auto` for state changes, `suggest` for recommendations, `off` for `berth_unlinked`); admins tune via `berth_rules` system_settings key. Webhook auto-advance pairs the rule with `advanceStageIfBehind` so the pipeline stage and berth status move together. - **EOI bundle / range formatter:** Multi-berth EOIs render the in-bundle berth set as a compact range string ("A1-A3, B5-B7") via `formatBerthRange()` in `src/lib/templates/berth-range.ts`. Used only inside the Documenso `Berth Range` form field — CRM UI always shows berths as individual chips. The `{{eoi.berthRange}}` token is in `VALID_MERGE_TOKENS`. -- **Pluggable storage backend:** Code never imports MinIO/S3 directly. All file I/O goes through `getStorageBackend()` from `src/lib/storage/`. Configured via `system_settings.storage_backend` ('s3' | 'filesystem'). Switching backends is a settings change + `pnpm tsx scripts/migrate-storage.ts` run. **Filesystem backend is single-node only**: refuses to start when `MULTI_NODE_DEPLOYMENT=true`. Multi-node deployments must use the s3-compatible backend. +- **Pluggable storage backend:** Code never imports MinIO/S3 directly. All file I/O goes through `getStorageBackend()` from `src/lib/storage/`. The `StorageBackend` interface requires `put`, `get`, `head`, `delete`, `listByPrefix`, `presignUpload`, `presignDownload` — any new backend must implement all seven. Configured via `system_settings.storage_backend` ('s3' | 'filesystem'). Switching backends is a settings change + `pnpm tsx scripts/migrate-storage.ts` run (the migrator round-trips every blob in `files`, `berth_pdf_versions`, `brochure_versions`, `gdpr_exports` and verifies SHA-256 — `TABLES_WITH_STORAGE_KEYS` populated in 9a5ba87; was no-op before). MinIO ops are wrapped in a 30s `withTimeout` to prevent TCP-blackhole worker stalls. **Filesystem backend is single-node only**: refuses to start when `MULTI_NODE_DEPLOYMENT=true`. Multi-node deployments must use the s3-compatible backend. - **Per-berth PDFs:** Versioned via `berth_pdf_versions`; `berths.current_pdf_version_id` always points to the latest active version. Storage key is UUID-based per upload (not version-numbered) so concurrent uploads can't collide on blob paths; `pg_advisory_xact_lock` per berth_id serializes the version-number allocation. 3-tier parser: AcroForm → OCR (Tesseract.js with positional heuristics) → optional AI (rep clicks "AI parse" only when OCR confidence is low). Magic-byte (`%PDF-`) check enforced on BOTH the in-server upload path AND the presigned-PUT path (the post-upload service streams the first 5 bytes via the storage backend). Mooring-number mismatch between PDF and target berth surfaces as a service-level `ConflictError` unless the apply call passes `confirmMooringMismatch: true`. - **Brochures:** Per-port; default brochure marked via `is_default` (enforced by partial unique index on `(port_id) WHERE is_default=true AND archived_at IS NULL`). Archived brochures retain version history. Same upload flow as berth PDFs (presign + magic-byte verification on the post-upload register endpoint). - **Send-from accounts (sales send-outs):** Configurable via `system_settings`; defaults to `sales@portnimara.com` for human-touch and `noreply@portnimara.com` for automation. SMTP/IMAP passwords are AES-256-GCM encrypted at rest; the API never returns decrypted secrets — only `*PassIsSet` boolean markers. Send-out audit goes to `document_sends` (separate from `audit_logs` because of volume + binary refs). Body markdown is XSS-safe via `renderEmailBody()` (escape-then-allowlist; tested against the standard XSS vector list). Rate limit: 50 sends/user/hour individual. Pre-send size threshold: files > `email_attach_threshold_mb` ship as a 24h signed-URL link rather than an attachment (avoids the duplicate-send race from async bounces). The download-link fallback HTML-escapes the filename to prevent injection from admin-supplied brochure names. Bounce monitoring requires IMAP credentials in addition to SMTP — without them, the size-rejection banner stays disabled. @@ -131,6 +132,10 @@ When you run a `db:push` or apply a migration via `psql` against a running dev s Copy `.env.example` to `.env` for local dev. See `src/lib/env.ts` for the full schema. Set `SKIP_ENV_VALIDATION=1` to bypass validation (used in Docker build). +Required env gotchas: + +- `DOCUMENSO_API_URL` — **bare host only**, never include `/api/v1`. The client appends versioned paths based on `DOCUMENSO_API_VERSION` (`v1` for 1.13.x, `v2` for 2.x). A double-pathed URL returns 404 on every call with no useful diagnostic. + Optional dev/test-only env vars (not in `.env.example`): - `EMAIL_REDIRECT_TO=
` — when set, every outbound email is rerouted to this address regardless of the requested recipient and the subject is prefixed with `[redirected from ]`. Dev safety net so seeded fake-client emails don't escape; **must be unset in production**. diff --git a/src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx b/src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx index 20424d11..185478c5 100644 --- a/src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx +++ b/src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx @@ -1,15 +1,19 @@ +import { CheckCircle2, Info } from 'lucide-react'; + import { SettingsFormCard, type SettingFieldDef, } from '@/components/admin/shared/settings-form-card'; import { DocumensoTestButton } from '@/components/admin/documenso/documenso-test-button'; import { PageHeader } from '@/components/shared/page-header'; +import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'; const API_FIELDS: SettingFieldDef[] = [ { key: 'documenso_api_url_override', label: 'API URL override', - description: 'Optional. Falls back to DOCUMENSO_API_URL env when blank.', + description: + 'Optional. Falls back to DOCUMENSO_API_URL env when blank. Bare host only — never include /api/v1; the client appends versioned paths based on the API version below.', type: 'string', placeholder: 'https://documenso.example.com', defaultValue: '', @@ -25,11 +29,11 @@ const API_FIELDS: SettingFieldDef[] = [ key: 'documenso_api_version_override', label: 'API version', description: - 'Which Documenso REST API to call against this port. v1 supports Documenso 1.x (per-field PIXEL placement, /api/v1/templates and /api/v1/documents). v2 unlocks the envelope/embed endpoints introduced in Documenso 2.x. Use the test-connection button below after switching to confirm the chosen version actually works against this port’s instance.', + "Which Documenso REST API this port targets. v1 = Documenso 1.13.x stable. v2 = Documenso 2.x with the envelope model and richer per-field metadata. Test the connection after switching. See the v2 benefits card above for what changes when you flip this — and note that template-based EOI generation still uses the v1 formValues shape regardless of this setting (v2 template/use migration is on the roadmap).", type: 'select', options: [ - { value: 'v1', label: 'v1 — Documenso 1.x (legacy stable)' }, - { value: 'v2', label: 'v2 — Documenso 2.x (envelope + embedded signing)' }, + { value: 'v1', label: 'v1 — Documenso 1.13.x (default, stable)' }, + { value: 'v2', label: 'v2 — Documenso 2.x (envelope, recommended for new ports)' }, ], defaultValue: 'v1', }, @@ -148,6 +152,108 @@ export default function DocumensoSettingsPage() { description="API credentials, signer identities, and document generation behaviour. Use the test-connection button to verify a saved configuration before relying on it." /> + + + + + + +

+ The CRM supports both Documenso 1.13.x (v1) and 2.x (v2). v1 is the default for + backwards compatibility. v2 is recommended for new ports and unlocks the features + below. Switching versions does not require any code changes — + version-aware client methods pick the right endpoint per port. Switch, save, then run + the test-connection button to confirm the chosen instance is actually on the matching + Documenso version. +

+ +
+

+ v2-only capabilities the CRM already uses when you pick v2 +

+
    +
  • +
    • +
  • +
    • +
  • +
    • +
  • +
    • +
  • +
    • +
+
+ +
+

+ v2 capabilities on the roadmap (not yet wired) +

+
    +
  • + Sequential signing (signingOrder: SEQUENTIAL) — would + force client → developer → approver order on EOIs instead of all-at-once. +
    • +
  • + Post-signing redirect URL (redirectUrl) — would land + signed clients back on the portal rather than Documenso's page. +
    • +
  • + Single-shot /template/use (v2 prefillFields by ID + replacing v1 formValues by name) — currently the EOI flow still uses the v1 + template path even when API version is v2. Needs per-template field-ID mapping in + the template config before we can switch. +
    • +
  • + Update envelope metadata (/envelope/update) — change + title / subject / redirectUrl after creation without re-generating. +
    • +
  • + Recipient roles beyond SIGNER (APPROVER / CC / VIEWER) — would let + sales managers receive copies without a signature slot. +
    • +
+

+ These items have no admin setting yet because they need code changes first. They + live here so you know what's in the pipeline. +

+
+ + + { await handleDocumentExpired({ documentId: documensoId, ...portScope }); break; + case 'DOCUMENT_REMINDER_SENT': + // Documenso auto-reminded a recipient. We don't mutate state — the + // reminder is informational. Structured log line is enough for + // telemetry without polluting the audit_logs table on every + // auto-reminder Documenso sends across all ports. + logger.info( + { + documensoId, + recipients: recipients.map((r) => r.email), + ...portScope, + }, + 'Documenso auto-reminder sent', + ); + break; + + case 'DOCUMENT_CREATED': + case 'DOCUMENT_SENT': + // Created + sent are informational — we initiated these from our + // side so the state is already authoritative in our DB. Log for + // forward-compat / out-of-band-creation telemetry. + logger.info({ event, documensoId, ...portScope }, 'Documenso lifecycle event'); + break; + default: logger.info({ event }, 'Unhandled Documenso webhook event type'); } diff --git a/src/lib/services/documenso-client.ts b/src/lib/services/documenso-client.ts index 351a5a5e..e5d6ae77 100644 --- a/src/lib/services/documenso-client.ts +++ b/src/lib/services/documenso-client.ts @@ -229,7 +229,12 @@ export async function sendDocument(docId: string, portId?: string): Promise { - return documensoFetch(`/api/v1/documents/${docId}`, undefined, portId).then(normalizeDocument); + const { apiVersion } = await resolveCreds(portId); + // v1: GET /api/v1/documents/{id} + // v2: GET /api/v2/envelope/{id} — same response normalizer (id ↔ documentId, + // recipientId ↔ id handled by normalizeDocument). + const path = apiVersion === 'v2' ? `/api/v2/envelope/${docId}` : `/api/v1/documents/${docId}`; + return documensoFetch(path, undefined, portId).then(normalizeDocument); } /** @@ -295,13 +300,16 @@ export async function downloadSignedPdf(docId: string, portId?: string): Promise /** Convenience health-check used by the admin "Test connection" button. */ export async function checkDocumensoHealth( portId?: string, -): Promise<{ ok: boolean; status?: number; error?: string }> { +): Promise<{ ok: boolean; status?: number; error?: string; apiVersion?: DocumensoApiVersion }> { try { - const { baseUrl, apiKey } = await resolveCreds(portId); + const { baseUrl, apiKey, apiVersion } = await resolveCreds(portId); + // Both v1 and v2 expose /api/v1/health (v2 keeps the v1 path for + // backward compat). If a v2 deployment ever moves this we'll add a + // v2 branch — but as of Documenso 2.x there isn't a v2 health path. const res = await fetchWithTimeout(`${baseUrl}/api/v1/health`, { headers: { Authorization: `Bearer ${apiKey}` }, }); - return { ok: res.ok, status: res.status }; + return { ok: res.ok, status: res.status, apiVersion }; } catch (err) { return { ok: false, error: err instanceof Error ? err.message : 'Unknown error' }; }