# Documenso integration audit Reference for the multi-port Documenso signing pipeline in this CRM. Mirrors the legacy client portal's flow ([generate-quick-eoi.ts](../client-portal/server/api/eoi/generate-quick-eoi.ts), [documeso.ts](../client-portal/server/utils/documeso.ts), [documenso.post.ts](../client-portal/server/api/webhooks/documenso.post.ts), [website /sign/[type]/[token].vue](../../Port%20Nimara/Website/pages/sign/%5Btype%5D/%5Btoken%5D.vue)) but rewired for multi-tenant + better-auth + Drizzle. --- ## Per-port configuration All Documenso settings live in `system_settings` keyed by `(key, port_id)` and are read via [`getPortDocumensoConfig(portId)`](../src/lib/services/port-config.ts). Falls back to env vars when no per-port row exists. Surfaced in the admin UI at `/[portSlug]/admin/documenso`. | Setting key | Type | Purpose | | ----------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------- | | `documenso_api_url_override` | string | Per-port Documenso instance URL. Falls back to `DOCUMENSO_API_URL` env. | | `documenso_api_key_override` | string | API key. Stored plaintext. | | `documenso_api_version_override` | `'v1' \| 'v2'` | Different ports may run different Documenso versions. | | `documenso_eoi_template_id` | int | Template ID for EOI generation. | | `documenso_client_recipient_id` | int | Template recipient slot — client (signing order 1). | | `documenso_developer_recipient_id` | int | Template recipient slot — developer (signing order 2). | | `documenso_approval_recipient_id` | int | Template recipient slot — approver (signing order 3). | | `documenso_developer_name` | string | Display name for developer signer (legacy hardcoded "David Mizrahi"). | | `documenso_developer_email` | string | Developer signer email. | | `documenso_approver_name` | string | Approver display name. | | `documenso_approver_email` | string | Approver email. | | `documenso_webhook_secret` | string | Per-port webhook secret. Receiver tries each enabled secret with timing-safe equal. | | `eoi_default_pathway` | `'documenso-template' \| 'inapp'` | Which path is used when EOI is generated without explicit choice. | | `eoi_send_mode` | `'auto' \| 'manual'` | Auto = send branded invitation email immediately; manual = rep clicks Send. | | `embedded_signing_host` | string | Public host that wraps Documenso URLs into `{host}/sign//`. | | `documenso_contract_template_id` | int (optional) | Optional template for sales contracts. Blank = upload-and-place-fields per deal. | | `documenso_reservation_template_id` | int (optional) | Optional template for reservation agreements. Same logic as contract. | --- ## Document type matrix | Type | Generation flow | Signers | Field placement | | --------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------- | | **EOI** | Documenso template (`eoi_template_id`) + form-fill values | Static: client, developer, approver (per-port) | Templated — fields baked into Documenso template | | **Contract** | Per-deal upload (drafted custom). Template fallback if configured | Custom per deal — rep specifies | Per-deal placement — default footer-anchored fallback | | **Reservation** | Per-deal upload OR template if configured | Custom per deal | Per-deal placement | ## Documenso field types Custom-uploaded documents (contracts, reservations) need a per-deal field placement step — different documents need different mixes. The CRM exposes the full Documenso-supported field palette so reps can place whatever the document calls for without code changes. | Field type | Use case | Needs `fieldMeta`? | What goes in meta | | ---------------- | ------------------------------------------------------- | ------------------ | --------------------------------------------------- | | `SIGNATURE` | Drawn signature — almost every signing flow | No | — | | `FREE_SIGNATURE` | Type-or-draw signature variant | No | — | | `INITIALS` | Per-page initials block | No | — | | `DATE` | Auto-fills the date when the recipient signs | No | — | | `EMAIL` | Auto-fills the recipient's email | No | — | | `NAME` | Auto-fills the recipient's name | No | — | | `TEXT` | Free text input (e.g. address, notes, place of signing) | Yes | `{ text?, label?, required?, readOnly? }` | | `NUMBER` | Numeric input with optional min/max | Yes | `{ numberFormat?, min?, max?, required? }` | | `CHECKBOX` | Boolean / single checkbox | Yes | `{ values: [{ checked, value }], validationRule? }` | | `DROPDOWN` | Pick from a fixed list | Yes | `{ values: [{ value }], defaultValue? }` | | `RADIO` | Mutually-exclusive options | Yes | `{ values: [{ checked, value }] }` | Helper: [`fieldTypeNeedsMeta(type)`](../src/lib/services/documenso-client.ts) returns true for the configurable types so the placement UI knows when to surface a config side-panel. `fieldMeta` is forwarded verbatim by [`placeFields()`](../src/lib/services/documenso-client.ts) on the v2 path. v1 silently ignores the property — fields render as blank inputs. Configurable behaviour (validation, defaults) only fires on v2 instances. --- ## Documenso v1 vs v2 endpoint mapping The [`documenso-client.ts`](../src/lib/services/documenso-client.ts) abstracts both. Each function picks v1 or v2 from `getPortDocumensoConfig(portId).apiVersion`. | Operation | v1 (1.13–1.32) | v2.x | | ------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | | Create document from upload | `POST /api/v1/documents` (body: `{ title, document, recipients }`) | `POST /api/v2/envelope` | | Generate document from template | `POST /api/v1/templates/{id}/generate-document` | (template-from-envelope path) | | Send for signing | `POST /api/v1/documents/{id}/send` | `POST /api/v2/envelope/{id}/send` | | Place a field | `POST /api/v1/documents/{id}/fields` (PIXEL coords, one at a time) | `POST /api/v2/envelope/field/create-many` (PERCENT, bulk) | | Get document state | `GET /api/v1/documents/{id}` | `GET /api/v2/envelope/{id}` | | Send reminder to one recipient | `POST /api/v1/documents/{id}/recipients/{rid}/remind` | `POST /api/v2/envelope/{id}/recipient/{rid}/remind` | | Download finalized PDF | `GET /api/v1/documents/{id}/download` → `{ downloadUrl }` then GET that URL | `GET /api/v2/envelope/{id}/download` (same shape) | | Cancel / void | `DELETE /api/v1/documents/{id}` | `DELETE /api/v2/envelope/{id}` | | Healthcheck | `GET /api/v1/health` | (v1 path used) | **Field key rename in v2 responses**: `id` → `documentId` and recipient `id` → `recipientId`. Our [`normalizeDocument()`](../src/lib/services/documenso-client.ts) handles both shapes. --- ## Signing-flow lifecycle ``` [rep clicks Generate] (CRM) │ ▼ buildEoiContext(interestId, portId) service │ ▼ generateAndSign(templateId, ctx, signers) creates Documenso doc │ ▼ POST /documents/{id}/send {sendEmail:false} Documenso starts the chain; it does NOT email signers │ ▼ extract signing URLs from response service │ ▼ transformSigningUrl(url, host, role) wrap as {host}/sign// │ ▼ if eoi_send_mode === 'auto': sendSigningInvitation(client) our branded HTML email goes out else: UI shows the URL + Send button rep dispatches manually ``` When the client signs: ``` Documenso fires DOCUMENT_SIGNED webhook ──► /api/webhooks/documenso │ ▼ verify x-documenso-secret (per-port lookup) │ ▼ update document_signers row: status='signed', signedAt=... │ ▼ if next signer in chain has not been notified: sendSigningInvitation(developer) cascading "your turn" email ``` When the document reaches fully-signed: ``` Documenso fires DOCUMENT_COMPLETED webhook │ ▼ download signed PDF from Documenso │ ▼ store in storage backend → creates files row │ ▼ update document: status='completed', completedAt=... │ ▼ sendSigningCompleted([client, developer, approver], pdfFileId) all parties get the signed PDF │ ▼ update interest: pipelineStage='eoi_signed' (or contract_signed, etc) ``` --- ## Embedded signing on the marketing website The CRM emits signing URLs in the form `{embeddedSigningHost}/sign//`. The marketing website ([Port Nimara/Website/pages/sign/[type]/[token].vue](../../Port%20Nimara/Website/pages/sign/%5Btype%5D/%5Btoken%5D.vue)) hosts the page, embeds Documenso via `@documenso/embed-vue`'s ``, and POSTs back to the CRM webhook on completion. For the embed to work, the Documenso instance MUST send `Access-Control-Allow-Origin` headers permitting the website origin. ### nginx CORS block to apply on `signatures.portnimara.dev` Add to the relevant `server { ... }` block: ```nginx location / { # CORS for embedded signing — allow the marketing-website origin # to load the Documenso signing iframe. add_header 'Access-Control-Allow-Origin' 'https://portnimara.com' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always; add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization' always; add_header 'Access-Control-Allow-Credentials' 'true' always; # Preflight if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Origin' 'https://portnimara.com' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always; add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization' always; add_header 'Access-Control-Max-Age' 1728000; add_header 'Content-Type' 'text/plain charset=UTF-8'; add_header 'Content-Length' 0; return 204; } # ... your existing proxy_pass block to Documenso } ``` To support multiple website origins (e.g. Port Amador hosted on a different domain), use a regex: ```nginx set $cors_origin ""; if ($http_origin ~* "^https://(portnimara\.com|portamador\.com)$") { set $cors_origin $http_origin; } add_header 'Access-Control-Allow-Origin' $cors_origin always; ``` --- ## What's deferred vs landed in this build **Landed:** - Per-port admin settings — every Documenso config knob is exposed at `/admin/documenso` - Branded invitation, completion, and reminder email templates - `transformSigningUrl()` for `{host}/sign//` URL wrapping - Documenso v1 + v2 dual-version client (existing) - Webhook handler with timing-safe per-port secret resolution (existing) - Contract + Reservation tab UI shells with paper-signed upload + "send for signing" placeholder - Stage-conditional tab visibility for EOI / Contract / Reservation **Landed in Phase 2-4 (2026-05-13):** - **Phase 2** — Webhook cascade + on-completion PDF distribution. `handleRecipientSigned` now finds the next pending signer and fires `sendSigningInvitation`; `handleDocumentCompleted` calls `sendSigningCompleted` to all recipients with the signed PDF attached (resolved via `getStorageBackend()` so MinIO + filesystem backends both work). Recipient matching prefers the Documenso recipient `token` captured at send-time (`document_signers.signing_token`); falls back to email match. - **Phase 3** — `lib/services/custom-document-upload.service.ts` + `POST /api/v1/interests/[id]/upload-for-signing`. Magic-byte verifies the PDF, stores via `getStorageBackend`, inserts the `documents` row, runs the full Documenso round-trip (`createDocument → sendDocument → placeFields`), captures recipient tokens, auto-sends invitation when port `sendMode === 'auto'`. - **Phase 4** — `` (`src/components/documents/upload-for-signing-dialog.tsx`). Three-step state machine (file → recipients → fields). Auto-detect runs server-side via `lib/services/document-field-detector.ts` (pdfjs text-extraction + anchor patterns); rep can drag/place/delete fields via native DOM events. Wired into the Contract + Reservation tabs. - **Phase 7** — Project Director RBAC binding. Admin UI exposes `documenso_developer_user_id` / `approver_user_id` / `_label` settings; webhook cascade fires an in-CRM `document_signing_your_turn` notification for linked users alongside the email. **Phase 5 — Embedded signing URL emission verification:** - `transformSigningUrl()` validated via 10 unit tests in `tests/unit/services/document-signing-urls.test.ts`. Maps signer-role → URL segment as: - `client → /sign/client/` - `developer → /sign/developer/` - `approver → /sign/cc/` — funnels through the CC page with passive copy - `witness → /sign/witness/` — website must handle this segment - `other → /sign/cc/` — same as approver - Hardened to reject malformed source URLs: the function now uses `extractSigningToken()` (rejects tails <8 chars or with non-URL-safe punctuation), so a bare `https://sig.example.com` is returned untouched rather than producing the malformed `/sign//sig.example.com`. **Phase 5 — coordination on the marketing-website side (NOT in this repo):** These are tracked here so the CRM stays the source of truth on the contract — the actual edits land in the website repo. 1. **Website `/sign/[type]/[token].vue` must handle `type ∈ {client, cc, developer, witness}`.** The CRM emits `cc` for both `approver` and `other` roles, and `witness` for explicit witness signers. Anything else lands on the website's `/sign/error` fallback. 2. **`signerMessages` map must be keyed on `(documentType, role)`** so a contract recipient hitting `/sign/client/` sees "Sign Your Sales Contract" rather than the EOI default. Until the website is updated, the URL emits `(role, token)` only; the website can resolve documentType from the Documenso embed payload. 3. **Post-sign callback** — the legacy portal POSTed to `client-portal.portnimara.com/api/webhook/document-signed`. The CRM no longer needs this — the Documenso webhook at `/api/webhooks/documenso` handles all state updates server-side. The website's POST is now optional; if it's still in place, point it at the CRM's webhook receiver as a real-time UI signal. 4. **Apply the nginx CORS block above** on the prod Documenso instance. **Genuinely deferred (Phase 6 polish):** - Auto-send delay (`eoi_send_delay_minutes` per-port setting + scheduled BullMQ job). - Document expiration toggle (`documents.expires_at` + Documenso `expiresAt` passthrough). - Per-document custom invitation message (textarea on the upload dialog → `documents.invitation_message`). - Reminder rate-limit display ("next reminder available in X days" badge on each unsigned signer in the signing-progress UI). - Failed-webhook recovery admin surface — the BullMQ webhook DLQ exists; needs an admin page with a Replay button. - Per-field metadata side panel for DROPDOWN/RADIO option lists in the Phase 4 dialog. - Pinch-zoom + zoom-out controls on the field-placement canvas. - Recipient drag-reorder via dnd-kit (current UI uses an order number input). **Manual ops work for you:** - Apply the nginx CORS block above on your prod Documenso instance. - Decide whether to upgrade prod Documenso to v2 (would unlock cleaner field placement + better envelope semantics). - Configure each port's developer/approver names and template IDs at `/[portSlug]/admin/documenso`.