Documenso reliability + signer-UX bundle from the 2026-05-26 live UAT.
Each piece detailed in docs/superpowers/audits/active-uat.md with full
file:line + root cause + alternatives.
Webhook + poll convergence
- DocumensoRecipient (webhook payload type) gains rejectionReason +
declineReason. The DOCUMENT_REJECTED / DOCUMENT_DECLINED handler
coalesces them at the boundary so downstream code sees one stable
field. Empty/whitespace normalised to null.
- DocumensoDocument.recipients[] (normalized client output) gains
rejectionReason. normalizeDocument coalesces v2 + v1 field names the
same way so poller consumers see identical shape.
- handleDocumentRejected signature gains rejectionReason. Stored on
document_events.eventData, persisted in audit_logs metadata, quoted
inline in the in-CRM rep notification (truncated 120 chars; full
reason still on the audit row). New 'transfer' AuditAction added
alongside.
- signature-poll job now handles REJECTED / DECLINED. Previously only
SIGNED / COMPLETED / EXPIRED were reconciled, so a missed rejection
webhook (stale tunnel URL is the typical dev cause) left documents
stuck in 'sent' forever. The 5-min poll cycle now closes that gap —
webhook becomes an optimisation, not a correctness requirement.
placeFields rollback gap
- custom-document-upload.service moved the synchronous field-placement
map() INSIDE the same try/catch that wraps placeFields(). Previously
the map's throw bubbled past the catch-and-rollback block, leaving
Documenso with a live envelope + recipients but no fields, and the
CRM document row stuck in 'sent' with no signing UI for the signers.
Logger captures looked-up email + map keys on miss for diagnosis.
- Comment documents Documenso's by-email dedupe semantic so future
readers don't reintroduce the per-recipient-row map assumption.
UploadForSigningDialog recipient UX
- New RECIPIENT_ROLE_META + RecipientRoleBadge helpers. Placement-step
sidebar list rebuilt as a two-line layout (name + role badge / email
on its own line) so duplicate-named recipients are visually
distinguishable. FieldSidePanel dropdown SelectItem mirrors the same
stacked shape.
- "Recipient" label renamed to "Assign this field to" with an explainer
paragraph below.
SigningProgress copy-link parity
- Copy-link button now always renders for pending signers (disabled +
explainer tooltip when signingUrl not yet issued). Reps can copy
even when the URL hasn't been distributed via email yet.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Matt
cae5d39607