From b92c53dbb23b89d3cfd89a6b38d2282cf273dfba Mon Sep 17 00:00:00 2001 From: Lucas Smith Date: Fri, 27 Feb 2026 22:05:27 +1100 Subject: [PATCH] feat: docs v2 (#2460) Co-authored-by: Catalin Pit --- .../plans/pale-lemon-rock-pnpm-migration.md | 312 +++ .agents/skills/agent-browser/SKILL.md | 207 ++ .../references/authentication.md | 202 ++ .../agent-browser/references/commands.md | 259 +++ .../agent-browser/references/proxy-support.md | 188 ++ .../references/session-management.md | 193 ++ .../agent-browser/references/snapshot-refs.md | 194 ++ .../references/video-recording.md | 173 ++ .../templates/authenticated-session.sh | 97 + .../templates/capture-workflow.sh | 69 + .../templates/form-automation.sh | 62 + .gitignore | 3 + .opencode/skills/agent-browser | 1 + .prettierignore | 3 + ARCHITECTURE.md | 359 +++ WRITING_STYLE.md | 343 +++ apps/docs/.gitignore | 26 + apps/docs/README.md | 45 + apps/docs/cli.json | 13 + .../docs/compliance/certifications.mdx | 57 + apps/docs/content/docs/compliance/esign.mdx | 187 ++ apps/docs/content/docs/compliance/gdpr.mdx | 174 ++ apps/docs/content/docs/compliance/index.mdx | 58 + apps/docs/content/docs/compliance/meta.json | 4 + .../docs/compliance/signature-levels.mdx | 284 +++ .../content/docs/compliance/standards.mdx | 108 + .../docs/concepts/document-lifecycle.mdx | 97 + .../content/docs/concepts/field-types.mdx | 314 +++ apps/docs/content/docs/concepts/index.mdx | 70 + apps/docs/content/docs/concepts/meta.json | 10 + .../content/docs/concepts/recipient-roles.mdx | 171 ++ .../docs/concepts/signing-certificates.mdx | 123 + .../docs/concepts/signing-workflow.mdx | 260 +++ .../docs/developers/api/developer-mode.mdx | 37 + .../content/docs/developers/api/documents.mdx | 815 +++++++ .../content/docs/developers/api/fields.mdx | 738 ++++++ .../content/docs/developers/api/index.mdx | 72 + .../content/docs/developers/api/meta.json | 13 + .../docs/developers/api/rate-limits.mdx | 67 + .../docs/developers/api/recipients.mdx | 504 ++++ .../content/docs/developers/api/teams.mdx | 373 +++ .../content/docs/developers/api/templates.mdx | 1026 ++++++++ .../docs/developers/api/versioning.mdx | 25 + .../contributing-translations.mdx | 91 + .../docs/developers/contributing/index.mdx | 152 ++ .../docs/developers/contributing/meta.json | 4 + .../developers/demo-environment/index.mdx | 64 + .../docs/developers/embedding/authoring.mdx | 306 +++ .../developers/embedding/css-variables.mdx | 215 ++ .../developers/embedding/direct-links.mdx | 514 ++++ .../docs/developers/embedding/index.mdx | 242 ++ .../docs/developers/embedding/meta.json | 4 + .../developers/embedding/sdks/angular.mdx | 92 + .../docs/developers/embedding/sdks/index.mdx | 37 + .../docs/developers/embedding/sdks/meta.json | 4 + .../docs/developers/embedding/sdks/preact.mdx | 96 + .../docs/developers/embedding/sdks/react.mdx | 136 ++ .../docs/developers/embedding/sdks/solid.mdx | 96 + .../docs/developers/embedding/sdks/svelte.mdx | 104 + .../docs/developers/embedding/sdks/vue.mdx | 107 + .../developers/examples/common-workflows.mdx | 1157 +++++++++ .../docs/developers/examples/index.mdx | 12 + .../docs/developers/examples/meta.json | 4 + .../getting-started/authentication.mdx | 202 ++ .../getting-started/first-api-call.mdx | 519 +++++ .../docs/developers/getting-started/index.mdx | 17 + .../docs/developers/getting-started/meta.json | 4 + apps/docs/content/docs/developers/index.mdx | 87 + .../developers/local-development/gitpod.mdx | 13 + .../developers/local-development/index.mdx | 66 + .../developers/local-development/manual.mdx | 111 + .../developers/local-development/meta.json | 4 + .../local-development/quickstart.mdx | 91 + .../local-development/signing-certificate.mdx | 92 + .../local-development/translations.mdx | 93 + apps/docs/content/docs/developers/meta.json | 15 + .../docs/developers/webhooks/events.mdx | 679 ++++++ .../docs/developers/webhooks/index.mdx | 55 + .../docs/developers/webhooks/meta.json | 4 + .../docs/developers/webhooks/setup.mdx | 355 +++ .../docs/developers/webhooks/verification.mdx | 290 +++ apps/docs/content/docs/index.mdx | 163 ++ apps/docs/content/docs/meta.json | 13 + .../docs/policies/community-edition.mdx | 205 ++ .../docs/policies/enterprise-edition.mdx | 244 ++ apps/docs/content/docs/policies/fair-use.mdx | 68 + apps/docs/content/docs/policies/index.mdx | 47 + apps/docs/content/docs/policies/licenses.mdx | 173 ++ apps/docs/content/docs/policies/meta.json | 13 + apps/docs/content/docs/policies/privacy.mdx | 6 + apps/docs/content/docs/policies/security.mdx | 242 ++ apps/docs/content/docs/policies/support.mdx | 240 ++ apps/docs/content/docs/policies/terms.mdx | 6 + .../configuration/advanced/ai-features.mdx | 106 + .../configuration/advanced/index.mdx | 17 + .../configuration/advanced/meta.json | 4 + .../advanced/oauth-providers.mdx | 155 ++ .../self-hosting/configuration/database.mdx | 490 ++++ .../docs/self-hosting/configuration/email.mdx | 473 ++++ .../configuration/environment.mdx | 339 +++ .../docs/self-hosting/configuration/index.mdx | 47 + .../docs/self-hosting/configuration/meta.json | 12 + .../signing-certificate/google-cloud-hsm.mdx | 95 + .../signing-certificate/index.mdx | 85 + .../signing-certificate/local.mdx | 202 ++ .../signing-certificate/meta.json | 4 + .../signing-certificate/timestamp-server.mdx | 68 + .../signing-certificate/troubleshooting.mdx | 91 + .../self-hosting/configuration/storage.mdx | 569 +++++ .../self-hosting/configuration/telemetry.mdx | 123 + .../deployment/docker-compose.mdx | 483 ++++ .../docs/self-hosting/deployment/docker.mdx | 307 +++ .../docs/self-hosting/deployment/index.mdx | 39 + .../self-hosting/deployment/kubernetes.mdx | 868 +++++++ .../docs/self-hosting/deployment/manual.mdx | 162 ++ .../docs/self-hosting/deployment/meta.json | 4 + .../docs/self-hosting/deployment/railway.mdx | 469 ++++ .../self-hosting/getting-started/index.mdx | 17 + .../self-hosting/getting-started/meta.json | 4 + .../getting-started/quick-start.mdx | 186 ++ .../getting-started/requirements.mdx | 174 ++ .../self-hosting/getting-started/tips.mdx | 182 ++ apps/docs/content/docs/self-hosting/index.mdx | 144 ++ .../docs/self-hosting/maintenance/backups.mdx | 674 ++++++ .../docs/self-hosting/maintenance/index.mdx | 22 + .../docs/self-hosting/maintenance/meta.json | 4 + .../maintenance/troubleshooting.mdx | 1222 ++++++++++ .../self-hosting/maintenance/upgrades.mdx | 651 ++++++ apps/docs/content/docs/self-hosting/meta.json | 6 + .../docs/users/documents/add-fields.mdx | 296 +++ .../docs/users/documents/add-recipients.mdx | 187 ++ .../users/documents/advanced/ai-detection.mdx | 132 ++ .../documents/advanced/default-recipients.mdx | 54 + .../advanced/document-visibility.mdx | 74 + .../docs/users/documents/advanced/index.mdx | 27 + .../docs/users/documents/advanced/meta.json | 10 + .../documents/advanced/pdf-placeholders.mdx | 188 ++ .../docs/users/documents/direct-links.mdx | 226 ++ .../content/docs/users/documents/index.mdx | 30 + .../content/docs/users/documents/meta.json | 4 + .../content/docs/users/documents/send.mdx | 236 ++ .../content/docs/users/documents/upload.mdx | 158 ++ .../users/getting-started/create-account.mdx | 109 + .../docs/users/getting-started/index.mdx | 17 + .../docs/users/getting-started/meta.json | 4 + .../getting-started/send-first-document.mdx | 108 + apps/docs/content/docs/users/index.mdx | 145 ++ apps/docs/content/docs/users/meta.json | 6 + .../docs/users/organisations/billing.mdx | 24 + .../docs/users/organisations/create-team.mdx | 166 ++ .../users/organisations/email-domains.mdx | 145 ++ .../docs/users/organisations/groups.mdx | 150 ++ .../docs/users/organisations/index.mdx | 55 + .../docs/users/organisations/members.mdx | 183 ++ .../docs/users/organisations/meta.json | 13 + .../docs/users/organisations/overview.mdx | 99 + .../organisations/preferences/branding.mdx | 149 ++ .../organisations/preferences/document.mdx | 54 + .../users/organisations/preferences/email.mdx | 32 + .../users/organisations/preferences/index.mdx | 26 + .../users/organisations/preferences/meta.json | 4 + .../single-sign-on/configuration.mdx | 259 +++ .../organisations/single-sign-on/index.mdx | 25 + .../organisations/single-sign-on/meta.json | 4 + .../single-sign-on/microsoft-entra-id.mdx | 125 + .../docs/users/settings/api-tokens.mdx | 26 + .../docs/users/settings/delete-account.mdx | 44 + .../content/docs/users/settings/index.mdx | 43 + .../content/docs/users/settings/meta.json | 4 + .../content/docs/users/settings/profile.mdx | 78 + .../docs/users/settings/public-profile.mdx | 67 + .../content/docs/users/settings/security.mdx | 166 ++ .../content/docs/users/settings/sessions.mdx | 82 + .../content/docs/users/templates/create.mdx | 215 ++ .../content/docs/users/templates/index.mdx | 34 + .../content/docs/users/templates/meta.json | 4 + .../docs/content/docs/users/templates/use.mdx | 147 ++ apps/docs/next.config.mjs | 462 ++++ apps/docs/package.json | 36 + apps/docs/postcss.config.mjs | 5 + apps/docs/public/apple-touch-icon.png | Bin 0 -> 14365 bytes ...nisation-default-recipients-role-step.webp | Bin 0 -> 568498 bytes ...sation-default-recipients-select-step.webp | Bin 0 -> 949854 bytes .../team-default-recipients.webp | Bin 0 -> 918374 bytes .../field-coordinates-legacy-editor.webp | Bin 0 -> 610065 bytes .../field-coordinates-new-editor.webp | Bin 0 -> 585032 bytes ...hoose-direct-link-recipient-documenso.webp | Bin 0 -> 56154 bytes .../direct-links/documenso-profile.webp | Bin 0 -> 46152 bytes .../document-direct-link-documenso.webp | Bin 0 -> 83720 bytes .../enable-document-direct-link-modal.webp | Bin 0 -> 70696 bytes .../ai-field-detection-button.webp | Bin 0 -> 476784 bytes .../ai-field-detection-dialog.webp | Bin 0 -> 378836 bytes .../ai-recipient-detect-button.webp | Bin 0 -> 259778 bytes .../checkbox-field-document-editor-view.webp | Bin 0 -> 90500 bytes .../date-field-document-editor-view.webp | Bin 0 -> 77478 bytes .../documenso-document-email-settings.webp | Bin 0 -> 103376 bytes .../documenso-document-fields.webp | Bin 0 -> 114736 bytes .../documenso-documents-dashboard.webp | Bin 0 -> 60108 bytes .../documenso-editor-email-settings.webp | Bin 0 -> 102516 bytes .../documenso-editor-general-settings.webp | Bin 0 -> 106826 bytes .../documenso-editor-preview.webp | Bin 0 -> 73006 bytes .../documenso-editor-security-settings.webp | Bin 0 -> 94552 bytes .../documenso-sign-email.webp | Bin 0 -> 45126 bytes .../documenso-signing-links.webp | Bin 0 -> 99816 bytes .../dropdown-field-document-editor-view.webp | Bin 0 -> 90858 bytes .../document-signing/editor-overview.webp | Bin 0 -> 85482 bytes .../editor-upload-recipients.webp | Bin 0 -> 111670 bytes .../email-field-document-editor-view.webp | Bin 0 -> 77932 bytes .../initials-field-document-editor-view.webp | Bin 0 -> 77894 bytes .../name-field-document-editor-view.webp | Bin 0 -> 82396 bytes .../number-field-document-editor-view.webp | Bin 0 -> 81452 bytes .../radio-field-document-editor-view.webp | Bin 0 -> 87738 bytes .../signature-field-document-editor-view.webp | Bin 0 -> 83656 bytes .../text-field-document-editor-view.webp | Bin 0 -> 82320 bytes .../email-domains/email-domain-sync.webp | Bin 0 -> 58868 bytes .../email-domains-manage-create-email.webp | Bin 0 -> 59832 bytes .../email-domains/email-domains-manage.webp | Bin 0 -> 61682 bytes .../email-domains/email-domains-record.webp | Bin 0 -> 97152 bytes .../email-domains-settings-page.webp | Bin 0 -> 122708 bytes .../public/embedding/copy-recipient-token.png | Bin 0 -> 172213 bytes .../public/embedding/enable-direct-link.png | Bin 0 -> 83567 bytes apps/docs/public/embedding/team-templates.png | Bin 0 -> 139608 bytes apps/docs/public/favicon-16x16.png | Bin 0 -> 529 bytes apps/docs/public/favicon-32x32.png | Bin 0 -> 1345 bytes apps/docs/public/fonts/inter-bold.ttf | Bin 0 -> 316100 bytes apps/docs/public/fonts/inter-regular.ttf | Bin 0 -> 309828 bytes apps/docs/public/fonts/inter-semibold.ttf | Bin 0 -> 315756 bytes .../documenso-account-security-page.webp | Bin 0 -> 146176 bytes .../documenso-add-passkey-box.webp | Bin 0 -> 109972 bytes ...umenso-enable-2-factor-authentication.webp | Bin 0 -> 114600 bytes .../documenso-passkeys-page.webp | Bin 0 -> 105708 bytes apps/docs/public/logo.png | Bin 0 -> 4119 bytes .../organisations/organisation-branding.webp | Bin 0 -> 81918 bytes .../organisation-document-preferences.webp | Bin 0 -> 93516 bytes .../organisation-document-visibility.webp | Bin 0 -> 88098 bytes .../organisation-email-preferences.webp | Bin 0 -> 71996 bytes .../organisation-group-assignment.webp | Bin 0 -> 62316 bytes .../organisation-group-create.webp | Bin 0 -> 80880 bytes .../organisation-group-manage.webp | Bin 0 -> 70736 bytes .../organisations-basic-diagram.webp | Bin 0 -> 40346 bytes .../organisations/organisations-billing.webp | Bin 0 -> 58336 bytes .../organisations/organisations-create.webp | Bin 0 -> 52084 bytes .../organisations-member-invite.webp | Bin 0 -> 76190 bytes .../organisations-sso-settings.webp | Bin 0 -> 179112 bytes .../api-tokens-page-documenso.webp | Bin 0 -> 72306 bytes .../documenso-api-key-blurred.webp | Bin 0 -> 89468 bytes .../documenso-user-dropdown-menu.webp | Bin 0 -> 73894 bytes ...umenso-enable-public-profile-settings.webp | Bin 0 -> 69136 bytes .../documenso-public-profile-settings.webp | Bin 0 -> 74442 bytes .../teams/document-visibility-settings.webp | Bin 0 -> 99048 bytes .../docs/public/teams/team-create-dialog.webp | Bin 0 -> 31908 bytes apps/docs/public/teams/team-create.webp | Bin 0 -> 51916 bytes ...menso-template-page-uploaded-document.webp | Bin 0 -> 86394 bytes .../templates/documenso-template-page.webp | Bin 0 -> 49720 bytes .../documenso-template-recipients.webp | Bin 0 -> 90544 bytes .../templates/documenso-use-template.webp | Bin 0 -> 106330 bytes .../webhook-images/create-webhook-dialog.webp | Bin 0 -> 72894 bytes .../webhook-images/documenso-main-page.webp | Bin 0 -> 78092 bytes .../webhook-images/webhook-detail-page.webp | Bin 0 -> 604010 bytes .../webhook-images/webhook-run-page.webp | Bin 0 -> 370152 bytes .../webhook-images/webhook-test-trigger.webp | Bin 0 -> 317116 bytes .../webhook-images/webhooks-main-page.webp | Bin 0 -> 68562 bytes .../public/webhook-images/webhooks-page.webp | Bin 0 -> 393088 bytes apps/docs/source.config.ts | 23 + apps/docs/src/app/(home)/layout.tsx | 6 + apps/docs/src/app/(home)/page.tsx | 271 +++ apps/docs/src/app/api/search/route.ts | 7 + apps/docs/src/app/apple-icon.png | Bin 0 -> 14365 bytes apps/docs/src/app/docs/[[...slug]]/page.tsx | 72 + apps/docs/src/app/docs/layout.tsx | 119 + apps/docs/src/app/favicon.ico | Bin 0 -> 5430 bytes apps/docs/src/app/global.css | 181 ++ apps/docs/src/app/layout.tsx | 41 + apps/docs/src/app/llms-full.txt/route.ts | 10 + .../app/llms.mdx/docs/[[...slug]]/route.ts | 24 + apps/docs/src/app/llms.txt/route.ts | 16 + apps/docs/src/app/not-found.tsx | 26 + apps/docs/src/app/og/docs/[...slug]/route.tsx | 154 ++ apps/docs/src/app/robots.ts | 12 + apps/docs/src/app/sitemap.ts | 20 + apps/docs/src/components/ai/page-actions.tsx | 168 ++ apps/docs/src/components/mdx/mermaid.tsx | 65 + apps/docs/src/lib/cn.ts | 1 + apps/docs/src/lib/layout.shared.tsx | 23 + apps/docs/src/lib/merge-refs.ts | 13 + apps/docs/src/lib/source.ts | 84 + apps/docs/src/mdx-components.tsx | 14 + apps/docs/tsconfig.json | 46 + package-lock.json | 2061 ++++++++++++++--- package.json | 5 +- 290 files changed, 32521 insertions(+), 266 deletions(-) create mode 100644 .agents/plans/pale-lemon-rock-pnpm-migration.md create mode 100644 .agents/skills/agent-browser/SKILL.md create mode 100644 .agents/skills/agent-browser/references/authentication.md create mode 100644 .agents/skills/agent-browser/references/commands.md create mode 100644 .agents/skills/agent-browser/references/proxy-support.md create mode 100644 .agents/skills/agent-browser/references/session-management.md create mode 100644 .agents/skills/agent-browser/references/snapshot-refs.md create mode 100644 .agents/skills/agent-browser/references/video-recording.md create mode 100755 .agents/skills/agent-browser/templates/authenticated-session.sh create mode 100755 .agents/skills/agent-browser/templates/capture-workflow.sh create mode 100755 .agents/skills/agent-browser/templates/form-automation.sh create mode 120000 .opencode/skills/agent-browser create mode 100644 ARCHITECTURE.md create mode 100644 WRITING_STYLE.md create mode 100644 apps/docs/.gitignore create mode 100644 apps/docs/README.md create mode 100644 apps/docs/cli.json create mode 100644 apps/docs/content/docs/compliance/certifications.mdx create mode 100644 apps/docs/content/docs/compliance/esign.mdx create mode 100644 apps/docs/content/docs/compliance/gdpr.mdx create mode 100644 apps/docs/content/docs/compliance/index.mdx create mode 100644 apps/docs/content/docs/compliance/meta.json create mode 100644 apps/docs/content/docs/compliance/signature-levels.mdx create mode 100644 apps/docs/content/docs/compliance/standards.mdx create mode 100644 apps/docs/content/docs/concepts/document-lifecycle.mdx create mode 100644 apps/docs/content/docs/concepts/field-types.mdx create mode 100644 apps/docs/content/docs/concepts/index.mdx create mode 100644 apps/docs/content/docs/concepts/meta.json create mode 100644 apps/docs/content/docs/concepts/recipient-roles.mdx create mode 100644 apps/docs/content/docs/concepts/signing-certificates.mdx create mode 100644 apps/docs/content/docs/concepts/signing-workflow.mdx create mode 100644 apps/docs/content/docs/developers/api/developer-mode.mdx create mode 100644 apps/docs/content/docs/developers/api/documents.mdx create mode 100644 apps/docs/content/docs/developers/api/fields.mdx create mode 100644 apps/docs/content/docs/developers/api/index.mdx create mode 100644 apps/docs/content/docs/developers/api/meta.json create mode 100644 apps/docs/content/docs/developers/api/rate-limits.mdx create mode 100644 apps/docs/content/docs/developers/api/recipients.mdx create mode 100644 apps/docs/content/docs/developers/api/teams.mdx create mode 100644 apps/docs/content/docs/developers/api/templates.mdx create mode 100644 apps/docs/content/docs/developers/api/versioning.mdx create mode 100644 apps/docs/content/docs/developers/contributing/contributing-translations.mdx create mode 100644 apps/docs/content/docs/developers/contributing/index.mdx create mode 100644 apps/docs/content/docs/developers/contributing/meta.json create mode 100644 apps/docs/content/docs/developers/demo-environment/index.mdx create mode 100644 apps/docs/content/docs/developers/embedding/authoring.mdx create mode 100644 apps/docs/content/docs/developers/embedding/css-variables.mdx create mode 100644 apps/docs/content/docs/developers/embedding/direct-links.mdx create mode 100644 apps/docs/content/docs/developers/embedding/index.mdx create mode 100644 apps/docs/content/docs/developers/embedding/meta.json create mode 100644 apps/docs/content/docs/developers/embedding/sdks/angular.mdx create mode 100644 apps/docs/content/docs/developers/embedding/sdks/index.mdx create mode 100644 apps/docs/content/docs/developers/embedding/sdks/meta.json create mode 100644 apps/docs/content/docs/developers/embedding/sdks/preact.mdx create mode 100644 apps/docs/content/docs/developers/embedding/sdks/react.mdx create mode 100644 apps/docs/content/docs/developers/embedding/sdks/solid.mdx create mode 100644 apps/docs/content/docs/developers/embedding/sdks/svelte.mdx create mode 100644 apps/docs/content/docs/developers/embedding/sdks/vue.mdx create mode 100644 apps/docs/content/docs/developers/examples/common-workflows.mdx create mode 100644 apps/docs/content/docs/developers/examples/index.mdx create mode 100644 apps/docs/content/docs/developers/examples/meta.json create mode 100644 apps/docs/content/docs/developers/getting-started/authentication.mdx create mode 100644 apps/docs/content/docs/developers/getting-started/first-api-call.mdx create mode 100644 apps/docs/content/docs/developers/getting-started/index.mdx create mode 100644 apps/docs/content/docs/developers/getting-started/meta.json create mode 100644 apps/docs/content/docs/developers/index.mdx create mode 100644 apps/docs/content/docs/developers/local-development/gitpod.mdx create mode 100644 apps/docs/content/docs/developers/local-development/index.mdx create mode 100644 apps/docs/content/docs/developers/local-development/manual.mdx create mode 100644 apps/docs/content/docs/developers/local-development/meta.json create mode 100644 apps/docs/content/docs/developers/local-development/quickstart.mdx create mode 100644 apps/docs/content/docs/developers/local-development/signing-certificate.mdx create mode 100644 apps/docs/content/docs/developers/local-development/translations.mdx create mode 100644 apps/docs/content/docs/developers/meta.json create mode 100644 apps/docs/content/docs/developers/webhooks/events.mdx create mode 100644 apps/docs/content/docs/developers/webhooks/index.mdx create mode 100644 apps/docs/content/docs/developers/webhooks/meta.json create mode 100644 apps/docs/content/docs/developers/webhooks/setup.mdx create mode 100644 apps/docs/content/docs/developers/webhooks/verification.mdx create mode 100644 apps/docs/content/docs/index.mdx create mode 100644 apps/docs/content/docs/meta.json create mode 100644 apps/docs/content/docs/policies/community-edition.mdx create mode 100644 apps/docs/content/docs/policies/enterprise-edition.mdx create mode 100644 apps/docs/content/docs/policies/fair-use.mdx create mode 100644 apps/docs/content/docs/policies/index.mdx create mode 100644 apps/docs/content/docs/policies/licenses.mdx create mode 100644 apps/docs/content/docs/policies/meta.json create mode 100644 apps/docs/content/docs/policies/privacy.mdx create mode 100644 apps/docs/content/docs/policies/security.mdx create mode 100644 apps/docs/content/docs/policies/support.mdx create mode 100644 apps/docs/content/docs/policies/terms.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/advanced/ai-features.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/advanced/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/advanced/meta.json create mode 100644 apps/docs/content/docs/self-hosting/configuration/advanced/oauth-providers.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/database.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/email.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/environment.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/meta.json create mode 100644 apps/docs/content/docs/self-hosting/configuration/signing-certificate/google-cloud-hsm.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/signing-certificate/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/signing-certificate/local.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/signing-certificate/meta.json create mode 100644 apps/docs/content/docs/self-hosting/configuration/signing-certificate/timestamp-server.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/signing-certificate/troubleshooting.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/storage.mdx create mode 100644 apps/docs/content/docs/self-hosting/configuration/telemetry.mdx create mode 100644 apps/docs/content/docs/self-hosting/deployment/docker-compose.mdx create mode 100644 apps/docs/content/docs/self-hosting/deployment/docker.mdx create mode 100644 apps/docs/content/docs/self-hosting/deployment/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/deployment/kubernetes.mdx create mode 100644 apps/docs/content/docs/self-hosting/deployment/manual.mdx create mode 100644 apps/docs/content/docs/self-hosting/deployment/meta.json create mode 100644 apps/docs/content/docs/self-hosting/deployment/railway.mdx create mode 100644 apps/docs/content/docs/self-hosting/getting-started/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/getting-started/meta.json create mode 100644 apps/docs/content/docs/self-hosting/getting-started/quick-start.mdx create mode 100644 apps/docs/content/docs/self-hosting/getting-started/requirements.mdx create mode 100644 apps/docs/content/docs/self-hosting/getting-started/tips.mdx create mode 100644 apps/docs/content/docs/self-hosting/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/maintenance/backups.mdx create mode 100644 apps/docs/content/docs/self-hosting/maintenance/index.mdx create mode 100644 apps/docs/content/docs/self-hosting/maintenance/meta.json create mode 100644 apps/docs/content/docs/self-hosting/maintenance/troubleshooting.mdx create mode 100644 apps/docs/content/docs/self-hosting/maintenance/upgrades.mdx create mode 100644 apps/docs/content/docs/self-hosting/meta.json create mode 100644 apps/docs/content/docs/users/documents/add-fields.mdx create mode 100644 apps/docs/content/docs/users/documents/add-recipients.mdx create mode 100644 apps/docs/content/docs/users/documents/advanced/ai-detection.mdx create mode 100644 apps/docs/content/docs/users/documents/advanced/default-recipients.mdx create mode 100644 apps/docs/content/docs/users/documents/advanced/document-visibility.mdx create mode 100644 apps/docs/content/docs/users/documents/advanced/index.mdx create mode 100644 apps/docs/content/docs/users/documents/advanced/meta.json create mode 100644 apps/docs/content/docs/users/documents/advanced/pdf-placeholders.mdx create mode 100644 apps/docs/content/docs/users/documents/direct-links.mdx create mode 100644 apps/docs/content/docs/users/documents/index.mdx create mode 100644 apps/docs/content/docs/users/documents/meta.json create mode 100644 apps/docs/content/docs/users/documents/send.mdx create mode 100644 apps/docs/content/docs/users/documents/upload.mdx create mode 100644 apps/docs/content/docs/users/getting-started/create-account.mdx create mode 100644 apps/docs/content/docs/users/getting-started/index.mdx create mode 100644 apps/docs/content/docs/users/getting-started/meta.json create mode 100644 apps/docs/content/docs/users/getting-started/send-first-document.mdx create mode 100644 apps/docs/content/docs/users/index.mdx create mode 100644 apps/docs/content/docs/users/meta.json create mode 100644 apps/docs/content/docs/users/organisations/billing.mdx create mode 100644 apps/docs/content/docs/users/organisations/create-team.mdx create mode 100644 apps/docs/content/docs/users/organisations/email-domains.mdx create mode 100644 apps/docs/content/docs/users/organisations/groups.mdx create mode 100644 apps/docs/content/docs/users/organisations/index.mdx create mode 100644 apps/docs/content/docs/users/organisations/members.mdx create mode 100644 apps/docs/content/docs/users/organisations/meta.json create mode 100644 apps/docs/content/docs/users/organisations/overview.mdx create mode 100644 apps/docs/content/docs/users/organisations/preferences/branding.mdx create mode 100644 apps/docs/content/docs/users/organisations/preferences/document.mdx create mode 100644 apps/docs/content/docs/users/organisations/preferences/email.mdx create mode 100644 apps/docs/content/docs/users/organisations/preferences/index.mdx create mode 100644 apps/docs/content/docs/users/organisations/preferences/meta.json create mode 100644 apps/docs/content/docs/users/organisations/single-sign-on/configuration.mdx create mode 100644 apps/docs/content/docs/users/organisations/single-sign-on/index.mdx create mode 100644 apps/docs/content/docs/users/organisations/single-sign-on/meta.json create mode 100644 apps/docs/content/docs/users/organisations/single-sign-on/microsoft-entra-id.mdx create mode 100644 apps/docs/content/docs/users/settings/api-tokens.mdx create mode 100644 apps/docs/content/docs/users/settings/delete-account.mdx create mode 100644 apps/docs/content/docs/users/settings/index.mdx create mode 100644 apps/docs/content/docs/users/settings/meta.json create mode 100644 apps/docs/content/docs/users/settings/profile.mdx create mode 100644 apps/docs/content/docs/users/settings/public-profile.mdx create mode 100644 apps/docs/content/docs/users/settings/security.mdx create mode 100644 apps/docs/content/docs/users/settings/sessions.mdx create mode 100644 apps/docs/content/docs/users/templates/create.mdx create mode 100644 apps/docs/content/docs/users/templates/index.mdx create mode 100644 apps/docs/content/docs/users/templates/meta.json create mode 100644 apps/docs/content/docs/users/templates/use.mdx create mode 100644 apps/docs/next.config.mjs create mode 100644 apps/docs/package.json create mode 100644 apps/docs/postcss.config.mjs create mode 100644 apps/docs/public/apple-touch-icon.png create mode 100644 apps/docs/public/default-recipients/organisation-default-recipients-role-step.webp create mode 100644 apps/docs/public/default-recipients/organisation-default-recipients-select-step.webp create mode 100644 apps/docs/public/default-recipients/team-default-recipients.webp create mode 100644 apps/docs/public/developer-mode/field-coordinates-legacy-editor.webp create mode 100644 apps/docs/public/developer-mode/field-coordinates-new-editor.webp create mode 100644 apps/docs/public/direct-links/choose-direct-link-recipient-documenso.webp create mode 100644 apps/docs/public/direct-links/documenso-profile.webp create mode 100644 apps/docs/public/direct-links/document-direct-link-documenso.webp create mode 100644 apps/docs/public/direct-links/enable-document-direct-link-modal.webp create mode 100644 apps/docs/public/document-signing/ai-field-detection-button.webp create mode 100644 apps/docs/public/document-signing/ai-field-detection-dialog.webp create mode 100644 apps/docs/public/document-signing/ai-recipient-detect-button.webp create mode 100644 apps/docs/public/document-signing/checkbox-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/date-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/documenso-document-email-settings.webp create mode 100644 apps/docs/public/document-signing/documenso-document-fields.webp create mode 100644 apps/docs/public/document-signing/documenso-documents-dashboard.webp create mode 100644 apps/docs/public/document-signing/documenso-editor-email-settings.webp create mode 100644 apps/docs/public/document-signing/documenso-editor-general-settings.webp create mode 100644 apps/docs/public/document-signing/documenso-editor-preview.webp create mode 100644 apps/docs/public/document-signing/documenso-editor-security-settings.webp create mode 100644 apps/docs/public/document-signing/documenso-sign-email.webp create mode 100644 apps/docs/public/document-signing/documenso-signing-links.webp create mode 100644 apps/docs/public/document-signing/dropdown-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/editor-overview.webp create mode 100644 apps/docs/public/document-signing/editor-upload-recipients.webp create mode 100644 apps/docs/public/document-signing/email-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/initials-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/name-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/number-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/radio-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/signature-field-document-editor-view.webp create mode 100644 apps/docs/public/document-signing/text-field-document-editor-view.webp create mode 100644 apps/docs/public/email-domains/email-domain-sync.webp create mode 100644 apps/docs/public/email-domains/email-domains-manage-create-email.webp create mode 100644 apps/docs/public/email-domains/email-domains-manage.webp create mode 100644 apps/docs/public/email-domains/email-domains-record.webp create mode 100644 apps/docs/public/email-domains/email-domains-settings-page.webp create mode 100644 apps/docs/public/embedding/copy-recipient-token.png create mode 100644 apps/docs/public/embedding/enable-direct-link.png create mode 100644 apps/docs/public/embedding/team-templates.png create mode 100644 apps/docs/public/favicon-16x16.png create mode 100644 apps/docs/public/favicon-32x32.png create mode 100644 apps/docs/public/fonts/inter-bold.ttf create mode 100644 apps/docs/public/fonts/inter-regular.ttf create mode 100644 apps/docs/public/fonts/inter-semibold.ttf create mode 100644 apps/docs/public/get-started-images/documenso-account-security-page.webp create mode 100644 apps/docs/public/get-started-images/documenso-add-passkey-box.webp create mode 100644 apps/docs/public/get-started-images/documenso-enable-2-factor-authentication.webp create mode 100644 apps/docs/public/get-started-images/documenso-passkeys-page.webp create mode 100644 apps/docs/public/logo.png create mode 100644 apps/docs/public/organisations/organisation-branding.webp create mode 100644 apps/docs/public/organisations/organisation-document-preferences.webp create mode 100644 apps/docs/public/organisations/organisation-document-visibility.webp create mode 100644 apps/docs/public/organisations/organisation-email-preferences.webp create mode 100644 apps/docs/public/organisations/organisation-group-assignment.webp create mode 100644 apps/docs/public/organisations/organisation-group-create.webp create mode 100644 apps/docs/public/organisations/organisation-group-manage.webp create mode 100644 apps/docs/public/organisations/organisations-basic-diagram.webp create mode 100644 apps/docs/public/organisations/organisations-billing.webp create mode 100644 apps/docs/public/organisations/organisations-create.webp create mode 100644 apps/docs/public/organisations/organisations-member-invite.webp create mode 100644 apps/docs/public/organisations/organisations-sso-settings.webp create mode 100644 apps/docs/public/public-api-images/api-tokens-page-documenso.webp create mode 100644 apps/docs/public/public-api-images/documenso-api-key-blurred.webp create mode 100644 apps/docs/public/public-api-images/documenso-user-dropdown-menu.webp create mode 100644 apps/docs/public/public-profile/documenso-enable-public-profile-settings.webp create mode 100644 apps/docs/public/public-profile/documenso-public-profile-settings.webp create mode 100644 apps/docs/public/teams/document-visibility-settings.webp create mode 100644 apps/docs/public/teams/team-create-dialog.webp create mode 100644 apps/docs/public/teams/team-create.webp create mode 100644 apps/docs/public/templates/documenso-template-page-uploaded-document.webp create mode 100644 apps/docs/public/templates/documenso-template-page.webp create mode 100644 apps/docs/public/templates/documenso-template-recipients.webp create mode 100644 apps/docs/public/templates/documenso-use-template.webp create mode 100644 apps/docs/public/webhook-images/create-webhook-dialog.webp create mode 100644 apps/docs/public/webhook-images/documenso-main-page.webp create mode 100644 apps/docs/public/webhook-images/webhook-detail-page.webp create mode 100644 apps/docs/public/webhook-images/webhook-run-page.webp create mode 100644 apps/docs/public/webhook-images/webhook-test-trigger.webp create mode 100644 apps/docs/public/webhook-images/webhooks-main-page.webp create mode 100644 apps/docs/public/webhook-images/webhooks-page.webp create mode 100644 apps/docs/source.config.ts create mode 100644 apps/docs/src/app/(home)/layout.tsx create mode 100644 apps/docs/src/app/(home)/page.tsx create mode 100644 apps/docs/src/app/api/search/route.ts create mode 100644 apps/docs/src/app/apple-icon.png create mode 100644 apps/docs/src/app/docs/[[...slug]]/page.tsx create mode 100644 apps/docs/src/app/docs/layout.tsx create mode 100644 apps/docs/src/app/favicon.ico create mode 100644 apps/docs/src/app/global.css create mode 100644 apps/docs/src/app/layout.tsx create mode 100644 apps/docs/src/app/llms-full.txt/route.ts create mode 100644 apps/docs/src/app/llms.mdx/docs/[[...slug]]/route.ts create mode 100644 apps/docs/src/app/llms.txt/route.ts create mode 100644 apps/docs/src/app/not-found.tsx create mode 100644 apps/docs/src/app/og/docs/[...slug]/route.tsx create mode 100644 apps/docs/src/app/robots.ts create mode 100644 apps/docs/src/app/sitemap.ts create mode 100644 apps/docs/src/components/ai/page-actions.tsx create mode 100644 apps/docs/src/components/mdx/mermaid.tsx create mode 100644 apps/docs/src/lib/cn.ts create mode 100644 apps/docs/src/lib/layout.shared.tsx create mode 100644 apps/docs/src/lib/merge-refs.ts create mode 100644 apps/docs/src/lib/source.ts create mode 100644 apps/docs/src/mdx-components.tsx create mode 100644 apps/docs/tsconfig.json diff --git a/.agents/plans/pale-lemon-rock-pnpm-migration.md b/.agents/plans/pale-lemon-rock-pnpm-migration.md new file mode 100644 index 000000000..7052cb7ba --- /dev/null +++ b/.agents/plans/pale-lemon-rock-pnpm-migration.md @@ -0,0 +1,312 @@ +--- +date: 2026-02-26 +title: pnpm Migration +--- + +## Overview + +Migrate from npm to pnpm to eliminate dependency resolution duplication issues that cause bundler problems. The current npm workspace setup results in nested `node_modules` copies that don't deduplicate reliably, requiring manual hoisting and `npm dedupe` cycles. pnpm's content-addressable store and strict symlink structure eliminates this class of problem entirely. + +## Current State + +- **Package manager:** npm@10.7.0 with `legacy-peer-deps=true` and `prefer-dedupe=true` +- **Workspaces:** 18 total (3 apps, 15 packages) declared in root `package.json` `workspaces` field +- **Lockfile:** `package-lock.json` +- **Patches:** `patch-package` with one patch (`@ai-sdk+google-vertex+3.0.81`) +- **Overrides:** `lodash`, `pdfjs-dist`, `typescript`, `zod` in root `package.json` +- **Syncpack:** installed but unconfigured (no `.syncpackrc`) +- **Heavy duplication:** `zod` in 7 workspaces, `ts-pattern` in 9, `luxon` in 8, `react` in 6, etc. +- **Docker:** `turbo prune` → `npm ci` → `npm ci --only=production` multi-stage build +- **Existing Dockerfiles:** `docker/Dockerfile` (primary, npm), `apps/remix/Dockerfile.pnpm` (already exists, needs review) + +## Migration Steps + +### Phase 1: Core Migration + +#### Step 1: Enable pnpm via corepack + +```bash +corepack enable pnpm +corepack use pnpm@latest +``` + +This adds a `"packageManager"` field to root `package.json` (e.g. `"packageManager": "pnpm@10.x.x"`). Remove the existing `"engines"` npm constraint if present. + +#### Step 2: Create `pnpm-workspace.yaml` + +```yaml +packages: + - apps/* + - packages/* +``` + +Remove the `"workspaces"` field from root `package.json` — pnpm uses `pnpm-workspace.yaml` instead. + +#### Step 3: Convert lockfile + +```bash +pnpm import +``` + +This reads `package-lock.json` and generates `pnpm-lock.yaml`. After verifying, delete `package-lock.json`. + +#### Step 4: Create `.npmrc` for pnpm + +Replace the current `.npmrc` contents. The existing settings (`legacy-peer-deps=true`, `prefer-dedupe=true`) are npm-specific. + +```ini +# Hoist packages that expect to be resolvable from any workspace. +# Start strict, add patterns here only as needed. +shamefully-hoist=true +``` + +> **Note:** `shamefully-hoist=true` is the pragmatic starting point. It mimics npm's flat `node_modules` layout. Once the migration is stable, this can be tightened to `hoist-pattern[]` entries for specific packages that need it, moving toward pnpm's strict isolation model. + +#### Step 5: Clean install + +```bash +rm -rf node_modules apps/*/node_modules packages/*/node_modules +pnpm install +``` + +Verify the install completes without errors. Fix any peer dependency warnings — pnpm is stricter than npm with `legacy-peer-deps=true`. + +#### Step 6: Convert `overrides` to `pnpm.overrides` + +In root `package.json`, move the `overrides` block under `pnpm`: + +```json +{ + "pnpm": { + "overrides": { + "lodash": "4.17.23", + "pdfjs-dist": "5.4.296", + "typescript": "5.6.2", + "zod": "^3.25.76" + } + } +} +``` + +Remove the top-level `overrides` field (that's npm-specific). + +#### Step 7: Convert patch-package to pnpm patches + +pnpm has native patching. Convert the existing `@ai-sdk+google-vertex+3.0.81` patch: + +```bash +# Remove patch-package dependency and postinstall script +# Then use pnpm's native patching: +pnpm patch @ai-sdk/google-vertex@3.0.81 +# Apply the same changes from patches/@ai-sdk+google-vertex+3.0.81.patch +pnpm patch-commit +``` + +This adds a `pnpm.patchedDependencies` entry to root `package.json` and stores the patch in a `patches/` directory (pnpm's own format). Remove `patch-package` from dependencies and the `postinstall` script. + +### Phase 2: Catalogs + +#### Step 8: Identify catalog candidates + +Packages duplicated across 3+ workspaces are prime candidates: + +| Package | Workspaces | Catalog? | +| ----------------------------------------------- | ---------- | ---------------------- | +| `zod` | 7 | Yes | +| `ts-pattern` | 9 | Yes | +| `luxon` | 8 | Yes | +| `react` / `react-dom` | 6 / 3 | Yes | +| `typescript` | 6 | Yes | +| `nanoid` | 4 | Yes | +| `@lingui/core` / `macro` / `react` | 2-3 | Yes | +| `@simplewebauthn/server` | 3 | Yes | +| `@documenso/*` (internal) | varies | No (use `workspace:*`) | +| `@aws-sdk/*` | 2 | Yes | +| `hono` | 2 | Yes | +| `posthog-node` / `posthog-js` | 2 | Yes | +| `remeda` | 3 | Yes | +| `@tanstack/react-query` | 2 | Yes | +| `@trpc/*` | 2 | Yes | +| `superjson` | 2 | Yes | +| `kysely` | 2 | Yes | +| `@types/react` / `@types/node` / `@types/luxon` | 3-4 | Yes | + +#### Step 9: Define catalogs in `pnpm-workspace.yaml` + +```yaml +packages: + - apps/* + - packages/* + +catalog: + # Core + react: ^18 + react-dom: ^18 + typescript: 5.6.2 + zod: ^3.25.76 + + # Shared utilities + ts-pattern: + luxon: ^3.7.2 + nanoid: ^5.1.6 + remeda: + superjson: ^2.2.5 + + # AWS + '@aws-sdk/client-s3': ^3.998.0 + '@aws-sdk/client-sesv2': ^3.998.0 + '@aws-sdk/cloudfront-signer': ^3.998.0 + '@aws-sdk/s3-request-presigner': ^3.998.0 + '@aws-sdk/signature-v4-crt': ^3.998.0 + + # Framework + hono: 4.12.2 + '@tanstack/react-query': + '@trpc/client': 11.8.1 + '@trpc/react-query': 11.8.1 + '@trpc/server': 11.8.1 + + # i18n + '@lingui/core': ^5.6.0 + '@lingui/macro': ^5.6.0 + '@lingui/react': ^5.6.0 + + # Auth + '@simplewebauthn/server': + + # Observability + posthog-node: 4.18.0 + posthog-js: + + # Database + kysely: + '@prisma/client': ^6.19.0 + prisma: ^6.19.0 + + # Types + '@types/react': + '@types/react-dom': + '@types/node': ^20 + '@types/luxon': +``` + +#### Step 10: Update workspace `package.json` files + +Replace pinned versions with `catalog:` protocol for all cataloged packages: + +```json +{ + "dependencies": { + "zod": "catalog:", + "ts-pattern": "catalog:", + "luxon": "catalog:" + } +} +``` + +This is a mechanical find-and-replace across all workspace `package.json` files. + +### Phase 3: Internal Workspace References + +#### Step 11: Convert internal references to `workspace:*` + +All `@documenso/*` internal package references currently use `"*"`. Convert to pnpm's `workspace:*` protocol: + +```json +{ + "dependencies": { + "@documenso/lib": "workspace:*", + "@documenso/prisma": "workspace:*" + } +} +``` + +This makes the workspace resolution explicit and prevents accidental resolution to a published version. + +### Phase 4: Docker & CI + +#### Step 12: Update primary Dockerfile (`docker/Dockerfile`) + +The existing multi-stage build needs to change: + +1. **base:** Add pnpm — `corepack enable pnpm` or install via `npm i -g pnpm` +2. **builder:** `turbo prune` still works with pnpm. Output structure is the same. +3. **installer:** + - Replace `npm ci` with `pnpm install --frozen-lockfile` + - Copy `pnpm-lock.yaml` and `pnpm-workspace.yaml` instead of `package-lock.json` + - Remove `patch-package` from postinstall (pnpm patches are applied natively) +4. **runner:** + - Replace `npm ci --only=production` with `pnpm install --frozen-lockfile --prod` + - Or use `pnpm deploy` for standalone output (copies only production deps to a flat directory) + +Review `apps/remix/Dockerfile.pnpm` — it already exists and may have most of this solved. Reconcile with the primary `docker/Dockerfile`. + +#### Step 13: Update CI workflows + +Search for all `npm ci`, `npm install`, `npm run` in CI config files (`.github/workflows/`, etc.) and replace with `pnpm install --frozen-lockfile`, `pnpm run`, etc. + +Ensure corepack is enabled in CI runners: + +```yaml +- run: corepack enable pnpm +``` + +#### Step 14: Update turborepo config + +Turbo works with pnpm out of the box. The `turbo.json` should not need changes. Verify `turbo prune` generates correct output with pnpm lockfile. + +### Phase 5: Cleanup & Tighten + +#### Step 15: Remove npm-specific tooling + +- Remove `syncpack` (catalogs replace its purpose) +- Remove `patch-package` (pnpm native patches replace it) +- Remove `"workspaces"` from root `package.json` if not already done +- Delete `package-lock.json` +- Update `.gitignore` if needed (pnpm store is outside the repo by default) + +#### Step 16: Tighten hoisting (optional, future) + +Once stable, replace `shamefully-hoist=true` with targeted hoist patterns: + +```ini +shamefully-hoist=false +hoist-pattern[]=*eslint* +hoist-pattern[]=*prettier* +# Add others as discovered +``` + +This moves toward strict isolation where each package can only import what it declares. Catches phantom dependency issues. Do this incrementally — let the bundler tell you what breaks. + +#### Step 17: Remove root-level dependency hoisting + +With catalogs and strict resolution, dependencies currently hoisted to root `package.json` for deduplication purposes can be moved back to the workspaces that actually use them. The root `package.json` should only contain tooling deps (`turbo`, `prettier`, `eslint`, etc.) and `pnpm.overrides`. + +## Risks and Mitigations + +1. **Phantom dependencies surface:** pnpm's strict isolation will expose imports that work today only because npm hoisted them. `shamefully-hoist=true` defers this, but tightening later will reveal them. + - **Mitigation:** Start with `shamefully-hoist=true`. Tighten incrementally after the migration is stable. + +2. **Peer dependency strictness:** pnpm enforces peer deps by default. The current `.npmrc` has `legacy-peer-deps=true` which suppresses all peer dep errors. + - **Mitigation:** Run `pnpm install` and address peer dep warnings. Most will be resolvable by adding missing peer deps to the relevant workspace. + +3. **Docker build breakage:** The `turbo prune` + `npm ci` pipeline is battle-tested. Switching to pnpm changes the install semantics. + - **Mitigation:** The existing `Dockerfile.pnpm` in `apps/remix/` provides a reference. Test the Docker build in CI before merging. + +4. **CI cache invalidation:** Switching lockfiles invalidates all CI dependency caches. + - **Mitigation:** Update cache keys to use `pnpm-lock.yaml` hash. First CI run will be slower, subsequent runs will cache normally. + +5. **Turbo + pnpm compatibility:** Turbo has first-class pnpm support, but `turbo prune` output format may differ slightly. + - **Mitigation:** Test `turbo prune --scope=@documenso/remix --docker` and verify output structure before updating Dockerfile. + +## Verification Checklist + +- [ ] `pnpm install` succeeds with no errors +- [ ] `pnpm run build` succeeds (all workspaces) +- [ ] `pnpm run lint` passes +- [ ] `pnpm run dev` starts correctly +- [ ] Docker build produces a working image +- [ ] E2E tests pass (`pnpm run test:e2e`) +- [ ] No duplicate package copies in `node_modules` for key deps (`zod`, `react`, `typescript`) +- [ ] `pnpm audit` shows same or better results than current npm audit +- [ ] CI pipeline passes end-to-end diff --git a/.agents/skills/agent-browser/SKILL.md b/.agents/skills/agent-browser/SKILL.md new file mode 100644 index 000000000..f07d3f70b --- /dev/null +++ b/.agents/skills/agent-browser/SKILL.md @@ -0,0 +1,207 @@ +--- +name: agent-browser +description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. +allowed-tools: Bash(agent-browser:*) +--- + +# Browser Automation with agent-browser + +## Core Workflow + +Every browser automation follows this pattern: + +1. **Navigate**: `agent-browser open ` +2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`) +3. **Interact**: Use refs to click, fill, select +4. **Re-snapshot**: After navigation or DOM changes, get fresh refs + +```bash +agent-browser open https://example.com/form +agent-browser snapshot -i +# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit" + +agent-browser fill @e1 "user@example.com" +agent-browser fill @e2 "password123" +agent-browser click @e3 +agent-browser wait --load networkidle +agent-browser snapshot -i # Check result +``` + +## Essential Commands + +```bash +# Navigation +agent-browser open # Navigate (aliases: goto, navigate) +agent-browser close # Close browser + +# Snapshot +agent-browser snapshot -i # Interactive elements with refs (recommended) +agent-browser snapshot -s "#selector" # Scope to CSS selector + +# Interaction (use @refs from snapshot) +agent-browser click @e1 # Click element +agent-browser fill @e2 "text" # Clear and type text +agent-browser type @e2 "text" # Type without clearing +agent-browser select @e1 "option" # Select dropdown option +agent-browser check @e1 # Check checkbox +agent-browser press Enter # Press key +agent-browser scroll down 500 # Scroll page + +# Get information +agent-browser get text @e1 # Get element text +agent-browser get url # Get current URL +agent-browser get title # Get page title + +# Wait +agent-browser wait @e1 # Wait for element +agent-browser wait --load networkidle # Wait for network idle +agent-browser wait --url "**/page" # Wait for URL pattern +agent-browser wait 2000 # Wait milliseconds + +# Capture +agent-browser screenshot # Screenshot to temp dir +agent-browser screenshot --full # Full page screenshot +agent-browser pdf output.pdf # Save as PDF +``` + +## Common Patterns + +### Form Submission + +```bash +agent-browser open https://example.com/signup +agent-browser snapshot -i +agent-browser fill @e1 "Jane Doe" +agent-browser fill @e2 "jane@example.com" +agent-browser select @e3 "California" +agent-browser check @e4 +agent-browser click @e5 +agent-browser wait --load networkidle +``` + +### Authentication with State Persistence + +```bash +# Login once and save state +agent-browser open https://app.example.com/login +agent-browser snapshot -i +agent-browser fill @e1 "$USERNAME" +agent-browser fill @e2 "$PASSWORD" +agent-browser click @e3 +agent-browser wait --url "**/dashboard" +agent-browser state save auth.json + +# Reuse in future sessions +agent-browser state load auth.json +agent-browser open https://app.example.com/dashboard +``` + +### Data Extraction + +```bash +agent-browser open https://example.com/products +agent-browser snapshot -i +agent-browser get text @e5 # Get specific element text +agent-browser get text body > page.txt # Get all page text + +# JSON output for parsing +agent-browser snapshot -i --json +agent-browser get text @e1 --json +``` + +### Parallel Sessions + +```bash +agent-browser --session site1 open https://site-a.com +agent-browser --session site2 open https://site-b.com + +agent-browser --session site1 snapshot -i +agent-browser --session site2 snapshot -i + +agent-browser session list +``` + +### Visual Browser (Debugging) + +```bash +agent-browser --headed open https://example.com +agent-browser highlight @e1 # Highlight element +agent-browser record start demo.webm # Record session +``` + +### iOS Simulator (Mobile Safari) + +```bash +# List available iOS simulators +agent-browser device list + +# Launch Safari on a specific device +agent-browser -p ios --device "iPhone 16 Pro" open https://example.com + +# Same workflow as desktop - snapshot, interact, re-snapshot +agent-browser -p ios snapshot -i +agent-browser -p ios tap @e1 # Tap (alias for click) +agent-browser -p ios fill @e2 "text" +agent-browser -p ios swipe up # Mobile-specific gesture + +# Take screenshot +agent-browser -p ios screenshot mobile.png + +# Close session (shuts down simulator) +agent-browser -p ios close +``` + +**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`) + +**Real devices:** Works with physical iOS devices if pre-configured. Use `--device ""` where UDID is from `xcrun xctrace list devices`. + +## Ref Lifecycle (Important) + +Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after: + +- Clicking links or buttons that navigate +- Form submissions +- Dynamic content loading (dropdowns, modals) + +```bash +agent-browser click @e5 # Navigates to new page +agent-browser snapshot -i # MUST re-snapshot +agent-browser click @e1 # Use new refs +``` + +## Semantic Locators (Alternative to Refs) + +When refs are unavailable or unreliable, use semantic locators: + +```bash +agent-browser find text "Sign In" click +agent-browser find label "Email" fill "user@test.com" +agent-browser find role button click --name "Submit" +agent-browser find placeholder "Search" type "query" +agent-browser find testid "submit-btn" click +``` + +## Deep-Dive Documentation + +| Reference | When to Use | +|-----------|-------------| +| [references/commands.md](references/commands.md) | Full command reference with all options | +| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting | +| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping | +| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse | +| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation | +| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies | + +## Ready-to-Use Templates + +| Template | Description | +|----------|-------------| +| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation | +| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state | +| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots | + +```bash +./templates/form-automation.sh https://example.com/form +./templates/authenticated-session.sh https://app.example.com/login +./templates/capture-workflow.sh https://example.com ./output +``` diff --git a/.agents/skills/agent-browser/references/authentication.md b/.agents/skills/agent-browser/references/authentication.md new file mode 100644 index 000000000..12ef5e41b --- /dev/null +++ b/.agents/skills/agent-browser/references/authentication.md @@ -0,0 +1,202 @@ +# Authentication Patterns + +Login flows, session persistence, OAuth, 2FA, and authenticated browsing. + +**Related**: [session-management.md](session-management.md) for state persistence details, [SKILL.md](../SKILL.md) for quick start. + +## Contents + +- [Basic Login Flow](#basic-login-flow) +- [Saving Authentication State](#saving-authentication-state) +- [Restoring Authentication](#restoring-authentication) +- [OAuth / SSO Flows](#oauth--sso-flows) +- [Two-Factor Authentication](#two-factor-authentication) +- [HTTP Basic Auth](#http-basic-auth) +- [Cookie-Based Auth](#cookie-based-auth) +- [Token Refresh Handling](#token-refresh-handling) +- [Security Best Practices](#security-best-practices) + +## Basic Login Flow + +```bash +# Navigate to login page +agent-browser open https://app.example.com/login +agent-browser wait --load networkidle + +# Get form elements +agent-browser snapshot -i +# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In" + +# Fill credentials +agent-browser fill @e1 "user@example.com" +agent-browser fill @e2 "password123" + +# Submit +agent-browser click @e3 +agent-browser wait --load networkidle + +# Verify login succeeded +agent-browser get url # Should be dashboard, not login +``` + +## Saving Authentication State + +After logging in, save state for reuse: + +```bash +# Login first (see above) +agent-browser open https://app.example.com/login +agent-browser snapshot -i +agent-browser fill @e1 "user@example.com" +agent-browser fill @e2 "password123" +agent-browser click @e3 +agent-browser wait --url "**/dashboard" + +# Save authenticated state +agent-browser state save ./auth-state.json +``` + +## Restoring Authentication + +Skip login by loading saved state: + +```bash +# Load saved auth state +agent-browser state load ./auth-state.json + +# Navigate directly to protected page +agent-browser open https://app.example.com/dashboard + +# Verify authenticated +agent-browser snapshot -i +``` + +## OAuth / SSO Flows + +For OAuth redirects: + +```bash +# Start OAuth flow +agent-browser open https://app.example.com/auth/google + +# Handle redirects automatically +agent-browser wait --url "**/accounts.google.com**" +agent-browser snapshot -i + +# Fill Google credentials +agent-browser fill @e1 "user@gmail.com" +agent-browser click @e2 # Next button +agent-browser wait 2000 +agent-browser snapshot -i +agent-browser fill @e3 "password" +agent-browser click @e4 # Sign in + +# Wait for redirect back +agent-browser wait --url "**/app.example.com**" +agent-browser state save ./oauth-state.json +``` + +## Two-Factor Authentication + +Handle 2FA with manual intervention: + +```bash +# Login with credentials +agent-browser open https://app.example.com/login --headed # Show browser +agent-browser snapshot -i +agent-browser fill @e1 "user@example.com" +agent-browser fill @e2 "password123" +agent-browser click @e3 + +# Wait for user to complete 2FA manually +echo "Complete 2FA in the browser window..." +agent-browser wait --url "**/dashboard" --timeout 120000 + +# Save state after 2FA +agent-browser state save ./2fa-state.json +``` + +## HTTP Basic Auth + +For sites using HTTP Basic Authentication: + +```bash +# Set credentials before navigation +agent-browser set credentials username password + +# Navigate to protected resource +agent-browser open https://protected.example.com/api +``` + +## Cookie-Based Auth + +Manually set authentication cookies: + +```bash +# Set auth cookie +agent-browser cookies set session_token "abc123xyz" + +# Navigate to protected page +agent-browser open https://app.example.com/dashboard +``` + +## Token Refresh Handling + +For sessions with expiring tokens: + +```bash +#!/bin/bash +# Wrapper that handles token refresh + +STATE_FILE="./auth-state.json" + +# Try loading existing state +if [[ -f "$STATE_FILE" ]]; then + agent-browser state load "$STATE_FILE" + agent-browser open https://app.example.com/dashboard + + # Check if session is still valid + URL=$(agent-browser get url) + if [[ "$URL" == *"/login"* ]]; then + echo "Session expired, re-authenticating..." + # Perform fresh login + agent-browser snapshot -i + agent-browser fill @e1 "$USERNAME" + agent-browser fill @e2 "$PASSWORD" + agent-browser click @e3 + agent-browser wait --url "**/dashboard" + agent-browser state save "$STATE_FILE" + fi +else + # First-time login + agent-browser open https://app.example.com/login + # ... login flow ... +fi +``` + +## Security Best Practices + +1. **Never commit state files** - They contain session tokens + ```bash + echo "*.auth-state.json" >> .gitignore + ``` + +2. **Use environment variables for credentials** + ```bash + agent-browser fill @e1 "$APP_USERNAME" + agent-browser fill @e2 "$APP_PASSWORD" + ``` + +3. **Clean up after automation** + ```bash + agent-browser cookies clear + rm -f ./auth-state.json + ``` + +4. **Use short-lived sessions for CI/CD** + ```bash + # Don't persist state in CI + agent-browser open https://app.example.com/login + # ... login and perform actions ... + agent-browser close # Session ends, nothing persisted + ``` diff --git a/.agents/skills/agent-browser/references/commands.md b/.agents/skills/agent-browser/references/commands.md new file mode 100644 index 000000000..8744accf7 --- /dev/null +++ b/.agents/skills/agent-browser/references/commands.md @@ -0,0 +1,259 @@ +# Command Reference + +Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md. + +## Navigation + +```bash +agent-browser open # Navigate to URL (aliases: goto, navigate) + # Supports: https://, http://, file://, about:, data:// + # Auto-prepends https:// if no protocol given +agent-browser back # Go back +agent-browser forward # Go forward +agent-browser reload # Reload page +agent-browser close # Close browser (aliases: quit, exit) +agent-browser connect 9222 # Connect to browser via CDP port +``` + +## Snapshot (page analysis) + +```bash +agent-browser snapshot # Full accessibility tree +agent-browser snapshot -i # Interactive elements only (recommended) +agent-browser snapshot -c # Compact output +agent-browser snapshot -d 3 # Limit depth to 3 +agent-browser snapshot -s "#main" # Scope to CSS selector +``` + +## Interactions (use @refs from snapshot) + +```bash +agent-browser click @e1 # Click +agent-browser dblclick @e1 # Double-click +agent-browser focus @e1 # Focus element +agent-browser fill @e2 "text" # Clear and type +agent-browser type @e2 "text" # Type without clearing +agent-browser press Enter # Press key (alias: key) +agent-browser press Control+a # Key combination +agent-browser keydown Shift # Hold key down +agent-browser keyup Shift # Release key +agent-browser hover @e1 # Hover +agent-browser check @e1 # Check checkbox +agent-browser uncheck @e1 # Uncheck checkbox +agent-browser select @e1 "value" # Select dropdown option +agent-browser select @e1 "a" "b" # Select multiple options +agent-browser scroll down 500 # Scroll page (default: down 300px) +agent-browser scrollintoview @e1 # Scroll element into view (alias: scrollinto) +agent-browser drag @e1 @e2 # Drag and drop +agent-browser upload @e1 file.pdf # Upload files +``` + +## Get Information + +```bash +agent-browser get text @e1 # Get element text +agent-browser get html @e1 # Get innerHTML +agent-browser get value @e1 # Get input value +agent-browser get attr @e1 href # Get attribute +agent-browser get title # Get page title +agent-browser get url # Get current URL +agent-browser get count ".item" # Count matching elements +agent-browser get box @e1 # Get bounding box +agent-browser get styles @e1 # Get computed styles (font, color, bg, etc.) +``` + +## Check State + +```bash +agent-browser is visible @e1 # Check if visible +agent-browser is enabled @e1 # Check if enabled +agent-browser is checked @e1 # Check if checked +``` + +## Screenshots and PDF + +```bash +agent-browser screenshot # Save to temporary directory +agent-browser screenshot path.png # Save to specific path +agent-browser screenshot --full # Full page +agent-browser pdf output.pdf # Save as PDF +``` + +## Video Recording + +```bash +agent-browser record start ./demo.webm # Start recording +agent-browser click @e1 # Perform actions +agent-browser record stop # Stop and save video +agent-browser record restart ./take2.webm # Stop current + start new +``` + +## Wait + +```bash +agent-browser wait @e1 # Wait for element +agent-browser wait 2000 # Wait milliseconds +agent-browser wait --text "Success" # Wait for text (or -t) +agent-browser wait --url "**/dashboard" # Wait for URL pattern (or -u) +agent-browser wait --load networkidle # Wait for network idle (or -l) +agent-browser wait --fn "window.ready" # Wait for JS condition (or -f) +``` + +## Mouse Control + +```bash +agent-browser mouse move 100 200 # Move mouse +agent-browser mouse down left # Press button +agent-browser mouse up left # Release button +agent-browser mouse wheel 100 # Scroll wheel +``` + +## Semantic Locators (alternative to refs) + +```bash +agent-browser find role button click --name "Submit" +agent-browser find text "Sign In" click +agent-browser find text "Sign In" click --exact # Exact match only +agent-browser find label "Email" fill "user@test.com" +agent-browser find placeholder "Search" type "query" +agent-browser find alt "Logo" click +agent-browser find title "Close" click +agent-browser find testid "submit-btn" click +agent-browser find first ".item" click +agent-browser find last ".item" click +agent-browser find nth 2 "a" hover +``` + +## Browser Settings + +```bash +agent-browser set viewport 1920 1080 # Set viewport size +agent-browser set device "iPhone 14" # Emulate device +agent-browser set geo 37.7749 -122.4194 # Set geolocation (alias: geolocation) +agent-browser set offline on # Toggle offline mode +agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers +agent-browser set credentials user pass # HTTP basic auth (alias: auth) +agent-browser set media dark # Emulate color scheme +agent-browser set media light reduced-motion # Light mode + reduced motion +``` + +## Cookies and Storage + +```bash +agent-browser cookies # Get all cookies +agent-browser cookies set name value # Set cookie +agent-browser cookies clear # Clear cookies +agent-browser storage local # Get all localStorage +agent-browser storage local key # Get specific key +agent-browser storage local set k v # Set value +agent-browser storage local clear # Clear all +``` + +## Network + +```bash +agent-browser network route # Intercept requests +agent-browser network route --abort # Block requests +agent-browser network route --body '{}' # Mock response +agent-browser network unroute [url] # Remove routes +agent-browser network requests # View tracked requests +agent-browser network requests --filter api # Filter requests +``` + +## Tabs and Windows + +```bash +agent-browser tab # List tabs +agent-browser tab new [url] # New tab +agent-browser tab 2 # Switch to tab by index +agent-browser tab close # Close current tab +agent-browser tab close 2 # Close tab by index +agent-browser window new # New window +``` + +## Frames + +```bash +agent-browser frame "#iframe" # Switch to iframe +agent-browser frame main # Back to main frame +``` + +## Dialogs + +```bash +agent-browser dialog accept [text] # Accept dialog +agent-browser dialog dismiss # Dismiss dialog +``` + +## JavaScript + +```bash +agent-browser eval "document.title" # Simple expressions only +agent-browser eval -b "" # Any JavaScript (base64 encoded) +agent-browser eval --stdin # Read script from stdin +``` + +Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone. + +```bash +# Base64 encode your script, then: +agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ==" + +# Or use stdin with heredoc for multiline scripts: +cat <<'EOF' | agent-browser eval --stdin +const links = document.querySelectorAll('a'); +Array.from(links).map(a => a.href); +EOF +``` + +## State Management + +```bash +agent-browser state save auth.json # Save cookies, storage, auth state +agent-browser state load auth.json # Restore saved state +``` + +## Global Options + +```bash +agent-browser --session ... # Isolated browser session +agent-browser --json ... # JSON output for parsing +agent-browser --headed ... # Show browser window (not headless) +agent-browser --full ... # Full page screenshot (-f) +agent-browser --cdp ... # Connect via Chrome DevTools Protocol +agent-browser -p ... # Cloud browser provider (--provider) +agent-browser --proxy ... # Use proxy server +agent-browser --headers ... # HTTP headers scoped to URL's origin +agent-browser --executable-path

# Custom browser executable +agent-browser --extension ... # Load browser extension (repeatable) +agent-browser --ignore-https-errors # Ignore SSL certificate errors +agent-browser --help # Show help (-h) +agent-browser --version # Show version (-V) +agent-browser --help # Show detailed help for a command +``` + +## Debugging + +```bash +agent-browser --headed open example.com # Show browser window +agent-browser --cdp 9222 snapshot # Connect via CDP port +agent-browser connect 9222 # Alternative: connect command +agent-browser console # View console messages +agent-browser console --clear # Clear console +agent-browser errors # View page errors +agent-browser errors --clear # Clear errors +agent-browser highlight @e1 # Highlight element +agent-browser trace start # Start recording trace +agent-browser trace stop trace.zip # Stop and save trace +``` + +## Environment Variables + +```bash +AGENT_BROWSER_SESSION="mysession" # Default session name +AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path +AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # Comma-separated extension paths +AGENT_BROWSER_PROVIDER="browserbase" # Cloud browser provider +AGENT_BROWSER_STREAM_PORT="9223" # WebSocket streaming port +AGENT_BROWSER_HOME="/path/to/agent-browser" # Custom install location +``` diff --git a/.agents/skills/agent-browser/references/proxy-support.md b/.agents/skills/agent-browser/references/proxy-support.md new file mode 100644 index 000000000..05cc9d538 --- /dev/null +++ b/.agents/skills/agent-browser/references/proxy-support.md @@ -0,0 +1,188 @@ +# Proxy Support + +Proxy configuration for geo-testing, rate limiting avoidance, and corporate environments. + +**Related**: [commands.md](commands.md) for global options, [SKILL.md](../SKILL.md) for quick start. + +## Contents + +- [Basic Proxy Configuration](#basic-proxy-configuration) +- [Authenticated Proxy](#authenticated-proxy) +- [SOCKS Proxy](#socks-proxy) +- [Proxy Bypass](#proxy-bypass) +- [Common Use Cases](#common-use-cases) +- [Verifying Proxy Connection](#verifying-proxy-connection) +- [Troubleshooting](#troubleshooting) +- [Best Practices](#best-practices) + +## Basic Proxy Configuration + +Set proxy via environment variable before starting: + +```bash +# HTTP proxy +export HTTP_PROXY="http://proxy.example.com:8080" +agent-browser open https://example.com + +# HTTPS proxy +export HTTPS_PROXY="https://proxy.example.com:8080" +agent-browser open https://example.com + +# Both +export HTTP_PROXY="http://proxy.example.com:8080" +export HTTPS_PROXY="http://proxy.example.com:8080" +agent-browser open https://example.com +``` + +## Authenticated Proxy + +For proxies requiring authentication: + +```bash +# Include credentials in URL +export HTTP_PROXY="http://username:password@proxy.example.com:8080" +agent-browser open https://example.com +``` + +## SOCKS Proxy + +```bash +# SOCKS5 proxy +export ALL_PROXY="socks5://proxy.example.com:1080" +agent-browser open https://example.com + +# SOCKS5 with auth +export ALL_PROXY="socks5://user:pass@proxy.example.com:1080" +agent-browser open https://example.com +``` + +## Proxy Bypass + +Skip proxy for specific domains: + +```bash +# Bypass proxy for local addresses +export NO_PROXY="localhost,127.0.0.1,.internal.company.com" +agent-browser open https://internal.company.com # Direct connection +agent-browser open https://external.com # Via proxy +``` + +## Common Use Cases + +### Geo-Location Testing + +```bash +#!/bin/bash +# Test site from different regions using geo-located proxies + +PROXIES=( + "http://us-proxy.example.com:8080" + "http://eu-proxy.example.com:8080" + "http://asia-proxy.example.com:8080" +) + +for proxy in "${PROXIES[@]}"; do + export HTTP_PROXY="$proxy" + export HTTPS_PROXY="$proxy" + + region=$(echo "$proxy" | grep -oP '^\w+-\w+') + echo "Testing from: $region" + + agent-browser --session "$region" open https://example.com + agent-browser --session "$region" screenshot "./screenshots/$region.png" + agent-browser --session "$region" close +done +``` + +### Rotating Proxies for Scraping + +```bash +#!/bin/bash +# Rotate through proxy list to avoid rate limiting + +PROXY_LIST=( + "http://proxy1.example.com:8080" + "http://proxy2.example.com:8080" + "http://proxy3.example.com:8080" +) + +URLS=( + "https://site.com/page1" + "https://site.com/page2" + "https://site.com/page3" +) + +for i in "${!URLS[@]}"; do + proxy_index=$((i % ${#PROXY_LIST[@]})) + export HTTP_PROXY="${PROXY_LIST[$proxy_index]}" + export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}" + + agent-browser open "${URLS[$i]}" + agent-browser get text body > "output-$i.txt" + agent-browser close + + sleep 1 # Polite delay +done +``` + +### Corporate Network Access + +```bash +#!/bin/bash +# Access internal sites via corporate proxy + +export HTTP_PROXY="http://corpproxy.company.com:8080" +export HTTPS_PROXY="http://corpproxy.company.com:8080" +export NO_PROXY="localhost,127.0.0.1,.company.com" + +# External sites go through proxy +agent-browser open https://external-vendor.com + +# Internal sites bypass proxy +agent-browser open https://intranet.company.com +``` + +## Verifying Proxy Connection + +```bash +# Check your apparent IP +agent-browser open https://httpbin.org/ip +agent-browser get text body +# Should show proxy's IP, not your real IP +``` + +## Troubleshooting + +### Proxy Connection Failed + +```bash +# Test proxy connectivity first +curl -x http://proxy.example.com:8080 https://httpbin.org/ip + +# Check if proxy requires auth +export HTTP_PROXY="http://user:pass@proxy.example.com:8080" +``` + +### SSL/TLS Errors Through Proxy + +Some proxies perform SSL inspection. If you encounter certificate errors: + +```bash +# For testing only - not recommended for production +agent-browser open https://example.com --ignore-https-errors +``` + +### Slow Performance + +```bash +# Use proxy only when necessary +export NO_PROXY="*.cdn.com,*.static.com" # Direct CDN access +``` + +## Best Practices + +1. **Use environment variables** - Don't hardcode proxy credentials +2. **Set NO_PROXY appropriately** - Avoid routing local traffic through proxy +3. **Test proxy before automation** - Verify connectivity with simple requests +4. **Handle proxy failures gracefully** - Implement retry logic for unstable proxies +5. **Rotate proxies for large scraping jobs** - Distribute load and avoid bans diff --git a/.agents/skills/agent-browser/references/session-management.md b/.agents/skills/agent-browser/references/session-management.md new file mode 100644 index 000000000..bb5312dbd --- /dev/null +++ b/.agents/skills/agent-browser/references/session-management.md @@ -0,0 +1,193 @@ +# Session Management + +Multiple isolated browser sessions with state persistence and concurrent browsing. + +**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start. + +## Contents + +- [Named Sessions](#named-sessions) +- [Session Isolation Properties](#session-isolation-properties) +- [Session State Persistence](#session-state-persistence) +- [Common Patterns](#common-patterns) +- [Default Session](#default-session) +- [Session Cleanup](#session-cleanup) +- [Best Practices](#best-practices) + +## Named Sessions + +Use `--session` flag to isolate browser contexts: + +```bash +# Session 1: Authentication flow +agent-browser --session auth open https://app.example.com/login + +# Session 2: Public browsing (separate cookies, storage) +agent-browser --session public open https://example.com + +# Commands are isolated by session +agent-browser --session auth fill @e1 "user@example.com" +agent-browser --session public get text body +``` + +## Session Isolation Properties + +Each session has independent: +- Cookies +- LocalStorage / SessionStorage +- IndexedDB +- Cache +- Browsing history +- Open tabs + +## Session State Persistence + +### Save Session State + +```bash +# Save cookies, storage, and auth state +agent-browser state save /path/to/auth-state.json +``` + +### Load Session State + +```bash +# Restore saved state +agent-browser state load /path/to/auth-state.json + +# Continue with authenticated session +agent-browser open https://app.example.com/dashboard +``` + +### State File Contents + +```json +{ + "cookies": [...], + "localStorage": {...}, + "sessionStorage": {...}, + "origins": [...] +} +``` + +## Common Patterns + +### Authenticated Session Reuse + +```bash +#!/bin/bash +# Save login state once, reuse many times + +STATE_FILE="/tmp/auth-state.json" + +# Check if we have saved state +if [[ -f "$STATE_FILE" ]]; then + agent-browser state load "$STATE_FILE" + agent-browser open https://app.example.com/dashboard +else + # Perform login + agent-browser open https://app.example.com/login + agent-browser snapshot -i + agent-browser fill @e1 "$USERNAME" + agent-browser fill @e2 "$PASSWORD" + agent-browser click @e3 + agent-browser wait --load networkidle + + # Save for future use + agent-browser state save "$STATE_FILE" +fi +``` + +### Concurrent Scraping + +```bash +#!/bin/bash +# Scrape multiple sites concurrently + +# Start all sessions +agent-browser --session site1 open https://site1.com & +agent-browser --session site2 open https://site2.com & +agent-browser --session site3 open https://site3.com & +wait + +# Extract from each +agent-browser --session site1 get text body > site1.txt +agent-browser --session site2 get text body > site2.txt +agent-browser --session site3 get text body > site3.txt + +# Cleanup +agent-browser --session site1 close +agent-browser --session site2 close +agent-browser --session site3 close +``` + +### A/B Testing Sessions + +```bash +# Test different user experiences +agent-browser --session variant-a open "https://app.com?variant=a" +agent-browser --session variant-b open "https://app.com?variant=b" + +# Compare +agent-browser --session variant-a screenshot /tmp/variant-a.png +agent-browser --session variant-b screenshot /tmp/variant-b.png +``` + +## Default Session + +When `--session` is omitted, commands use the default session: + +```bash +# These use the same default session +agent-browser open https://example.com +agent-browser snapshot -i +agent-browser close # Closes default session +``` + +## Session Cleanup + +```bash +# Close specific session +agent-browser --session auth close + +# List active sessions +agent-browser session list +``` + +## Best Practices + +### 1. Name Sessions Semantically + +```bash +# GOOD: Clear purpose +agent-browser --session github-auth open https://github.com +agent-browser --session docs-scrape open https://docs.example.com + +# AVOID: Generic names +agent-browser --session s1 open https://github.com +``` + +### 2. Always Clean Up + +```bash +# Close sessions when done +agent-browser --session auth close +agent-browser --session scrape close +``` + +### 3. Handle State Files Securely + +```bash +# Don't commit state files (contain auth tokens!) +echo "*.auth-state.json" >> .gitignore + +# Delete after use +rm /tmp/auth-state.json +``` + +### 4. Timeout Long Sessions + +```bash +# Set timeout for automated scripts +timeout 60 agent-browser --session long-task get text body +``` diff --git a/.agents/skills/agent-browser/references/snapshot-refs.md b/.agents/skills/agent-browser/references/snapshot-refs.md new file mode 100644 index 000000000..c13d53a89 --- /dev/null +++ b/.agents/skills/agent-browser/references/snapshot-refs.md @@ -0,0 +1,194 @@ +# Snapshot and Refs + +Compact element references that reduce context usage dramatically for AI agents. + +**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start. + +## Contents + +- [How Refs Work](#how-refs-work) +- [Snapshot Command](#the-snapshot-command) +- [Using Refs](#using-refs) +- [Ref Lifecycle](#ref-lifecycle) +- [Best Practices](#best-practices) +- [Ref Notation Details](#ref-notation-details) +- [Troubleshooting](#troubleshooting) + +## How Refs Work + +Traditional approach: +``` +Full DOM/HTML → AI parses → CSS selector → Action (~3000-5000 tokens) +``` + +agent-browser approach: +``` +Compact snapshot → @refs assigned → Direct interaction (~200-400 tokens) +``` + +## The Snapshot Command + +```bash +# Basic snapshot (shows page structure) +agent-browser snapshot + +# Interactive snapshot (-i flag) - RECOMMENDED +agent-browser snapshot -i +``` + +### Snapshot Output Format + +``` +Page: Example Site - Home +URL: https://example.com + +@e1 [header] + @e2 [nav] + @e3 [a] "Home" + @e4 [a] "Products" + @e5 [a] "About" + @e6 [button] "Sign In" + +@e7 [main] + @e8 [h1] "Welcome" + @e9 [form] + @e10 [input type="email"] placeholder="Email" + @e11 [input type="password"] placeholder="Password" + @e12 [button type="submit"] "Log In" + +@e13 [footer] + @e14 [a] "Privacy Policy" +``` + +## Using Refs + +Once you have refs, interact directly: + +```bash +# Click the "Sign In" button +agent-browser click @e6 + +# Fill email input +agent-browser fill @e10 "user@example.com" + +# Fill password +agent-browser fill @e11 "password123" + +# Submit the form +agent-browser click @e12 +``` + +## Ref Lifecycle + +**IMPORTANT**: Refs are invalidated when the page changes! + +```bash +# Get initial snapshot +agent-browser snapshot -i +# @e1 [button] "Next" + +# Click triggers page change +agent-browser click @e1 + +# MUST re-snapshot to get new refs! +agent-browser snapshot -i +# @e1 [h1] "Page 2" ← Different element now! +``` + +## Best Practices + +### 1. Always Snapshot Before Interacting + +```bash +# CORRECT +agent-browser open https://example.com +agent-browser snapshot -i # Get refs first +agent-browser click @e1 # Use ref + +# WRONG +agent-browser open https://example.com +agent-browser click @e1 # Ref doesn't exist yet! +``` + +### 2. Re-Snapshot After Navigation + +```bash +agent-browser click @e5 # Navigates to new page +agent-browser snapshot -i # Get new refs +agent-browser click @e1 # Use new refs +``` + +### 3. Re-Snapshot After Dynamic Changes + +```bash +agent-browser click @e1 # Opens dropdown +agent-browser snapshot -i # See dropdown items +agent-browser click @e7 # Select item +``` + +### 4. Snapshot Specific Regions + +For complex pages, snapshot specific areas: + +```bash +# Snapshot just the form +agent-browser snapshot @e9 +``` + +## Ref Notation Details + +``` +@e1 [tag type="value"] "text content" placeholder="hint" +│ │ │ │ │ +│ │ │ │ └─ Additional attributes +│ │ │ └─ Visible text +│ │ └─ Key attributes shown +│ └─ HTML tag name +└─ Unique ref ID +``` + +### Common Patterns + +``` +@e1 [button] "Submit" # Button with text +@e2 [input type="email"] # Email input +@e3 [input type="password"] # Password input +@e4 [a href="/page"] "Link Text" # Anchor link +@e5 [select] # Dropdown +@e6 [textarea] placeholder="Message" # Text area +@e7 [div class="modal"] # Container (when relevant) +@e8 [img alt="Logo"] # Image +@e9 [checkbox] checked # Checked checkbox +@e10 [radio] selected # Selected radio +``` + +## Troubleshooting + +### "Ref not found" Error + +```bash +# Ref may have changed - re-snapshot +agent-browser snapshot -i +``` + +### Element Not Visible in Snapshot + +```bash +# Scroll to reveal element +agent-browser scroll --bottom +agent-browser snapshot -i + +# Or wait for dynamic content +agent-browser wait 1000 +agent-browser snapshot -i +``` + +### Too Many Elements + +```bash +# Snapshot specific container +agent-browser snapshot @e5 + +# Or use get text for content-only extraction +agent-browser get text @e5 +``` diff --git a/.agents/skills/agent-browser/references/video-recording.md b/.agents/skills/agent-browser/references/video-recording.md new file mode 100644 index 000000000..e6a9fb4e2 --- /dev/null +++ b/.agents/skills/agent-browser/references/video-recording.md @@ -0,0 +1,173 @@ +# Video Recording + +Capture browser automation as video for debugging, documentation, or verification. + +**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start. + +## Contents + +- [Basic Recording](#basic-recording) +- [Recording Commands](#recording-commands) +- [Use Cases](#use-cases) +- [Best Practices](#best-practices) +- [Output Format](#output-format) +- [Limitations](#limitations) + +## Basic Recording + +```bash +# Start recording +agent-browser record start ./demo.webm + +# Perform actions +agent-browser open https://example.com +agent-browser snapshot -i +agent-browser click @e1 +agent-browser fill @e2 "test input" + +# Stop and save +agent-browser record stop +``` + +## Recording Commands + +```bash +# Start recording to file +agent-browser record start ./output.webm + +# Stop current recording +agent-browser record stop + +# Restart with new file (stops current + starts new) +agent-browser record restart ./take2.webm +``` + +## Use Cases + +### Debugging Failed Automation + +```bash +#!/bin/bash +# Record automation for debugging + +agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm + +# Run your automation +agent-browser open https://app.example.com +agent-browser snapshot -i +agent-browser click @e1 || { + echo "Click failed - check recording" + agent-browser record stop + exit 1 +} + +agent-browser record stop +``` + +### Documentation Generation + +```bash +#!/bin/bash +# Record workflow for documentation + +agent-browser record start ./docs/how-to-login.webm + +agent-browser open https://app.example.com/login +agent-browser wait 1000 # Pause for visibility + +agent-browser snapshot -i +agent-browser fill @e1 "demo@example.com" +agent-browser wait 500 + +agent-browser fill @e2 "password" +agent-browser wait 500 + +agent-browser click @e3 +agent-browser wait --load networkidle +agent-browser wait 1000 # Show result + +agent-browser record stop +``` + +### CI/CD Test Evidence + +```bash +#!/bin/bash +# Record E2E test runs for CI artifacts + +TEST_NAME="${1:-e2e-test}" +RECORDING_DIR="./test-recordings" +mkdir -p "$RECORDING_DIR" + +agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm" + +# Run test +if run_e2e_test; then + echo "Test passed" +else + echo "Test failed - recording saved" +fi + +agent-browser record stop +``` + +## Best Practices + +### 1. Add Pauses for Clarity + +```bash +# Slow down for human viewing +agent-browser click @e1 +agent-browser wait 500 # Let viewer see result +``` + +### 2. Use Descriptive Filenames + +```bash +# Include context in filename +agent-browser record start ./recordings/login-flow-2024-01-15.webm +agent-browser record start ./recordings/checkout-test-run-42.webm +``` + +### 3. Handle Recording in Error Cases + +```bash +#!/bin/bash +set -e + +cleanup() { + agent-browser record stop 2>/dev/null || true + agent-browser close 2>/dev/null || true +} +trap cleanup EXIT + +agent-browser record start ./automation.webm +# ... automation steps ... +``` + +### 4. Combine with Screenshots + +```bash +# Record video AND capture key frames +agent-browser record start ./flow.webm + +agent-browser open https://example.com +agent-browser screenshot ./screenshots/step1-homepage.png + +agent-browser click @e1 +agent-browser screenshot ./screenshots/step2-after-click.png + +agent-browser record stop +``` + +## Output Format + +- Default format: WebM (VP8/VP9 codec) +- Compatible with all modern browsers and video players +- Compressed but high quality + +## Limitations + +- Recording adds slight overhead to automation +- Large recordings can consume significant disk space +- Some headless environments may have codec limitations diff --git a/.agents/skills/agent-browser/templates/authenticated-session.sh b/.agents/skills/agent-browser/templates/authenticated-session.sh new file mode 100755 index 000000000..ebbfc1fae --- /dev/null +++ b/.agents/skills/agent-browser/templates/authenticated-session.sh @@ -0,0 +1,97 @@ +#!/bin/bash +# Template: Authenticated Session Workflow +# Purpose: Login once, save state, reuse for subsequent runs +# Usage: ./authenticated-session.sh [state-file] +# +# Environment variables: +# APP_USERNAME - Login username/email +# APP_PASSWORD - Login password +# +# Two modes: +# 1. Discovery mode (default): Shows form structure so you can identify refs +# 2. Login mode: Performs actual login after you update the refs +# +# Setup steps: +# 1. Run once to see form structure (discovery mode) +# 2. Update refs in LOGIN FLOW section below +# 3. Set APP_USERNAME and APP_PASSWORD +# 4. Delete the DISCOVERY section + +set -euo pipefail + +LOGIN_URL="${1:?Usage: $0 [state-file]}" +STATE_FILE="${2:-./auth-state.json}" + +echo "Authentication workflow: $LOGIN_URL" + +# ================================================================ +# SAVED STATE: Skip login if valid saved state exists +# ================================================================ +if [[ -f "$STATE_FILE" ]]; then + echo "Loading saved state from $STATE_FILE..." + agent-browser state load "$STATE_FILE" + agent-browser open "$LOGIN_URL" + agent-browser wait --load networkidle + + CURRENT_URL=$(agent-browser get url) + if [[ "$CURRENT_URL" != *"login"* ]] && [[ "$CURRENT_URL" != *"signin"* ]]; then + echo "Session restored successfully" + agent-browser snapshot -i + exit 0 + fi + echo "Session expired, performing fresh login..." + rm -f "$STATE_FILE" +fi + +# ================================================================ +# DISCOVERY MODE: Shows form structure (delete after setup) +# ================================================================ +echo "Opening login page..." +agent-browser open "$LOGIN_URL" +agent-browser wait --load networkidle + +echo "" +echo "Login form structure:" +echo "---" +agent-browser snapshot -i +echo "---" +echo "" +echo "Next steps:" +echo " 1. Note the refs: username=@e?, password=@e?, submit=@e?" +echo " 2. Update the LOGIN FLOW section below with your refs" +echo " 3. Set: export APP_USERNAME='...' APP_PASSWORD='...'" +echo " 4. Delete this DISCOVERY MODE section" +echo "" +agent-browser close +exit 0 + +# ================================================================ +# LOGIN FLOW: Uncomment and customize after discovery +# ================================================================ +# : "${APP_USERNAME:?Set APP_USERNAME environment variable}" +# : "${APP_PASSWORD:?Set APP_PASSWORD environment variable}" +# +# agent-browser open "$LOGIN_URL" +# agent-browser wait --load networkidle +# agent-browser snapshot -i +# +# # Fill credentials (update refs to match your form) +# agent-browser fill @e1 "$APP_USERNAME" +# agent-browser fill @e2 "$APP_PASSWORD" +# agent-browser click @e3 +# agent-browser wait --load networkidle +# +# # Verify login succeeded +# FINAL_URL=$(agent-browser get url) +# if [[ "$FINAL_URL" == *"login"* ]] || [[ "$FINAL_URL" == *"signin"* ]]; then +# echo "Login failed - still on login page" +# agent-browser screenshot /tmp/login-failed.png +# agent-browser close +# exit 1 +# fi +# +# # Save state for future runs +# echo "Saving state to $STATE_FILE" +# agent-browser state save "$STATE_FILE" +# echo "Login successful" +# agent-browser snapshot -i diff --git a/.agents/skills/agent-browser/templates/capture-workflow.sh b/.agents/skills/agent-browser/templates/capture-workflow.sh new file mode 100755 index 000000000..3bc93ad0c --- /dev/null +++ b/.agents/skills/agent-browser/templates/capture-workflow.sh @@ -0,0 +1,69 @@ +#!/bin/bash +# Template: Content Capture Workflow +# Purpose: Extract content from web pages (text, screenshots, PDF) +# Usage: ./capture-workflow.sh [output-dir] +# +# Outputs: +# - page-full.png: Full page screenshot +# - page-structure.txt: Page element structure with refs +# - page-text.txt: All text content +# - page.pdf: PDF version +# +# Optional: Load auth state for protected pages + +set -euo pipefail + +TARGET_URL="${1:?Usage: $0 [output-dir]}" +OUTPUT_DIR="${2:-.}" + +echo "Capturing: $TARGET_URL" +mkdir -p "$OUTPUT_DIR" + +# Optional: Load authentication state +# if [[ -f "./auth-state.json" ]]; then +# echo "Loading authentication state..." +# agent-browser state load "./auth-state.json" +# fi + +# Navigate to target +agent-browser open "$TARGET_URL" +agent-browser wait --load networkidle + +# Get metadata +TITLE=$(agent-browser get title) +URL=$(agent-browser get url) +echo "Title: $TITLE" +echo "URL: $URL" + +# Capture full page screenshot +agent-browser screenshot --full "$OUTPUT_DIR/page-full.png" +echo "Saved: $OUTPUT_DIR/page-full.png" + +# Get page structure with refs +agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt" +echo "Saved: $OUTPUT_DIR/page-structure.txt" + +# Extract all text content +agent-browser get text body > "$OUTPUT_DIR/page-text.txt" +echo "Saved: $OUTPUT_DIR/page-text.txt" + +# Save as PDF +agent-browser pdf "$OUTPUT_DIR/page.pdf" +echo "Saved: $OUTPUT_DIR/page.pdf" + +# Optional: Extract specific elements using refs from structure +# agent-browser get text @e5 > "$OUTPUT_DIR/main-content.txt" + +# Optional: Handle infinite scroll pages +# for i in {1..5}; do +# agent-browser scroll down 1000 +# agent-browser wait 1000 +# done +# agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png" + +# Cleanup +agent-browser close + +echo "" +echo "Capture complete:" +ls -la "$OUTPUT_DIR" diff --git a/.agents/skills/agent-browser/templates/form-automation.sh b/.agents/skills/agent-browser/templates/form-automation.sh new file mode 100755 index 000000000..6784fcd3a --- /dev/null +++ b/.agents/skills/agent-browser/templates/form-automation.sh @@ -0,0 +1,62 @@ +#!/bin/bash +# Template: Form Automation Workflow +# Purpose: Fill and submit web forms with validation +# Usage: ./form-automation.sh +# +# This template demonstrates the snapshot-interact-verify pattern: +# 1. Navigate to form +# 2. Snapshot to get element refs +# 3. Fill fields using refs +# 4. Submit and verify result +# +# Customize: Update the refs (@e1, @e2, etc.) based on your form's snapshot output + +set -euo pipefail + +FORM_URL="${1:?Usage: $0 }" + +echo "Form automation: $FORM_URL" + +# Step 1: Navigate to form +agent-browser open "$FORM_URL" +agent-browser wait --load networkidle + +# Step 2: Snapshot to discover form elements +echo "" +echo "Form structure:" +agent-browser snapshot -i + +# Step 3: Fill form fields (customize these refs based on snapshot output) +# +# Common field types: +# agent-browser fill @e1 "John Doe" # Text input +# agent-browser fill @e2 "user@example.com" # Email input +# agent-browser fill @e3 "SecureP@ss123" # Password input +# agent-browser select @e4 "Option Value" # Dropdown +# agent-browser check @e5 # Checkbox +# agent-browser click @e6 # Radio button +# agent-browser fill @e7 "Multi-line text" # Textarea +# agent-browser upload @e8 /path/to/file.pdf # File upload +# +# Uncomment and modify: +# agent-browser fill @e1 "Test User" +# agent-browser fill @e2 "test@example.com" +# agent-browser click @e3 # Submit button + +# Step 4: Wait for submission +# agent-browser wait --load networkidle +# agent-browser wait --url "**/success" # Or wait for redirect + +# Step 5: Verify result +echo "" +echo "Result:" +agent-browser get url +agent-browser snapshot -i + +# Optional: Capture evidence +agent-browser screenshot /tmp/form-result.png +echo "Screenshot saved: /tmp/form-result.png" + +# Cleanup +agent-browser close +echo "Done" diff --git a/.gitignore b/.gitignore index 961230226..29c50622f 100644 --- a/.gitignore +++ b/.gitignore @@ -67,3 +67,6 @@ scripts/output* # license .documenso-license.json .documenso-license-backup.json + +# tmp +tmp/ diff --git a/.opencode/skills/agent-browser b/.opencode/skills/agent-browser new file mode 120000 index 000000000..e298b7be3 --- /dev/null +++ b/.opencode/skills/agent-browser @@ -0,0 +1 @@ +../../.agents/skills/agent-browser \ No newline at end of file diff --git a/.prettierignore b/.prettierignore index 15f517b75..f5c70c1d5 100644 --- a/.prettierignore +++ b/.prettierignore @@ -15,3 +15,6 @@ packages/lib/translations/**/*.js .prettierignore .DS_Store .eslintignore + +# Docs MDX - Prettier strips indentation from code blocks inside components +apps/docs/content/**/*.mdx diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 000000000..b3710da55 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,359 @@ +# Documenso Architecture + +This document provides a high-level overview of the Documenso codebase to help humans and agents understand how the application is structured. + +## Overview + +Documenso is an open-source document signing platform built as a **monorepo** using npm workspaces and Turborepo. The application enables users to create, send, and sign documents electronically. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Remix App (Hono Server) │ +│ apps/remix │ +├─────────────┬─────────────┬─────────────┬─────────────┬─────────────────────┤ +│ /api/v1/* │ /api/v2/* │ /api/trpc/* │ /api/jobs/* │ React Router UI │ +│ (ts-rest) │ (tRPC) │ (tRPC) │ (Jobs API) │ │ +├─────────────┴─────────────┴─────────────┴─────────────┴─────────────────────┤ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ +│ │ @api │ │ @trpc │ │ @lib │ │ @email │ │ @signing │ │ +│ │ (REST) │ │ (RPC) │ │ (CORE) │ │ │ │ │ │ +│ └─────────┘ └─────────┘ └────┬────┘ └─────────┘ └─────────────────┘ │ +│ │ │ +│ ┌──────────────────┼──────────────────┐ │ +│ │ │ │ │ +│ ┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐ │ +│ │ Storage │ │ Jobs │ │ PDF │ │ +│ │Provider │ │ Provider │ │ Signing │ │ +│ └────┬────┘ └─────┬─────┘ └─────┬─────┘ │ +│ │ │ │ │ +└──────────────┼──────────────────┼──────────────────┼────────────────────────┘ + │ │ │ + ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐ + │ Database │ │ Inngest/ │ │ Google KMS/ │ + │ S3 │ │ Local │ │ Local │ + └─────────────┘ └─────────────┘ └─────────────┘ +``` + +## Monorepo Structure + +### Applications (`apps/`) + +| Package | Description | Port | +| -------------------------- | -------------------------------------------------------- | ---- | +| `@documenso/remix` | Main application - React Router (Remix) with Hono server | 3000 | +| `@documenso/documentation` | Documentation site (Next.js + Nextra) | 3002 | +| `@documenso/openpage-api` | Public analytics API | 3003 | + +### Core Packages (`packages/`) + +| Package | Description | +| -------------------- | --------------------------------------------------------- | +| `@documenso/lib` | Core business logic (server-only, client-only, universal) | +| `@documenso/trpc` | tRPC API layer with OpenAPI support (API V2) | +| `@documenso/api` | REST API layer using ts-rest (API V1) | +| `@documenso/prisma` | Database layer (Prisma ORM + Kysely) | +| `@documenso/ui` | UI component library (Shadcn + Radix + Tailwind) | +| `@documenso/email` | Email templates and mailer (React Email) | +| `@documenso/auth` | Authentication (OAuth via Arctic, WebAuthn/Passkeys) | +| `@documenso/signing` | PDF signing (Local P12, Google Cloud KMS) | +| `@documenso/ee` | Enterprise Edition features | +| `@documenso/assets` | Static assets | + +### Supporting Packages + +| Package | Description | +| ---------------------------- | ------------------------- | +| `@documenso/app-tests` | E2E tests (Playwright) | +| `@documenso/eslint-config` | Shared ESLint config | +| `@documenso/prettier-config` | Shared Prettier config | +| `@documenso/tailwind-config` | Shared Tailwind config | +| `@documenso/tsconfig` | Shared TypeScript configs | + +## Tech Stack + +| Category | Technology | +| -------- | --------------------------------- | +| Frontend | React 18, React Router v7 (Remix) | +| Server | Hono | +| Database | PostgreSQL 15, Prisma, Kysely | +| API | tRPC, ts-rest, OpenAPI | +| Styling | Tailwind CSS, Radix UI, Shadcn UI | +| Auth | Arctic (OAuth), WebAuthn/Passkeys | +| Email | React Email, Nodemailer | +| Jobs | Inngest / Local | +| Storage | S3-compatible / Database | +| PDF | @libpdf/core, pdfjs-dist | +| i18n | Lingui | +| Build | Turborepo, Vite | +| Testing | Playwright | + +## API Architecture + +### API V1 (Deprecated) + +- **Location**: `packages/api/v1/` +- **Framework**: ts-rest (contract-based REST) +- **Mount**: `/api/v1/*` +- **Auth**: API Token (Bearer header) +- **Status**: Deprecated but maintained + +**Routes** (RESTful pattern): + +- `GET/POST/DELETE /api/v1/documents/*` +- `GET/POST/DELETE /api/v1/templates/*` +- Recipients and fields nested under documents + +### API V2 (Current) + +- **Location**: `packages/trpc/server/` +- **Framework**: tRPC with trpc-to-openapi +- **Mount**: `/api/v2/*`, `/api/v2-beta/*` +- **Auth**: API Token or Session Cookie +- **Status**: Active + +**Routes** (action-based pattern): + +- `GET/POST /api/v2/document/*` - Document operations +- `GET/POST /api/v2/template/*` - Template operations +- `GET/POST /api/v2/envelope/*` - Envelope operations (multi-document) +- `GET/POST /api/v2/folder/*` - Folder management + +**Route Organization**: + +``` +packages/trpc/server/ +├── document-router/ +│ ├── get-document.ts +│ ├── get-document.types.ts +│ └── ... +├── template-router/ +├── envelope-router/ +├── recipient-router/ +├── field-router/ +└── ... +``` + +### Internal tRPC API + +- **Mount**: `/api/trpc/*` +- **Usage**: Frontend-to-backend communication +- **Auth**: Session-based + +## Background Jobs + +Jobs handle async operations like email sending, document sealing, and webhooks. + +### Architecture + +``` +┌─────────────────┐ ┌───────────────────────────────────────┐ +│ triggerJob() │────▶│ Job Provider │ +│ │ │ ┌─────────────┬─────────────────┐ │ +│ - name │ │ │ Inngest │ Local │ │ +│ - payload │ │ │ (Cloud) │ (Database) │ │ +└─────────────────┘ │ └─────────────┴─────────────────┘ │ + │ │ │ + │ ▼ │ + │ ┌─────────────────────┐ │ + │ │ Job Handler │ │ + │ │ (async processing) │ │ + │ └─────────────────────┘ │ + └───────────────────────────────────────┘ +``` + +### Location + +- `packages/lib/jobs/client/` - Provider implementations +- `packages/lib/jobs/definitions/` - Job definitions + +### Job Types + +**Email Jobs**: + +- `send.signing.requested.email` - Signing invitation +- `send-confirmation-email` - Email verification +- `send-recipient-signed-email` - Notify on signature +- `send-rejection-emails` - Rejection notifications +- `send-document-cancelled-emails` - Cancellation notices + +**Internal Jobs**: + +- `internal.seal-document` - Finalize signed documents +- `internal.bulk-send-template` - Bulk document sending +- `internal.execute-webhook` - External webhook calls + +## Swappable Providers + +The codebase uses a **strategy pattern** with `ts-pattern` for provider selection via environment variables. + +### Storage Provider + +Handles file uploads and downloads. + +| Provider | Description | Env Value | +| -------- | ------------------------------------ | ---------- | +| Database | Store files as Base64 in DB | `database` | +| S3 | S3-compatible storage (+ CloudFront) | `s3` | + +**Config**: `NEXT_PUBLIC_UPLOAD_TRANSPORT` + +**Location**: `packages/lib/universal/upload/` + +### PDF Signing Provider + +Cryptographically signs PDF documents. + +| Provider | Description | Env Value | +| ---------------- | -------------------- | ------------ | +| Local | P12 certificate file | `local` | +| Google Cloud HSM | Google Cloud KMS | `gcloud-hsm` | + +**Config**: `NEXT_PRIVATE_SIGNING_TRANSPORT` + +**Location**: `packages/signing/` + +### Email Provider + +Sends transactional emails. + +| Provider | Description | Env Value | +| ------------ | ------------------------------ | -------------- | +| SMTP Auth | Standard SMTP with credentials | `smtp-auth` | +| SMTP API | SMTP with API key | `smtp-api` | +| Resend | Resend API | `resend` | +| MailChannels | MailChannels API | `mailchannels` | + +**Config**: `NEXT_PRIVATE_SMTP_TRANSPORT` + +**Location**: `packages/email/mailer.ts` + +### Background Jobs Provider + +Processes async jobs. + +| Provider | Description | Env Value | +| -------- | --------------------- | ----------------- | +| Local | Database-backed queue | `local` (default) | +| Inngest | Managed cloud service | `inngest` | + +**Config**: `NEXT_PRIVATE_JOBS_PROVIDER` + +**Location**: `packages/lib/jobs/client/` + +## Request Flow + +### Web Application Request + +``` +Browser + │ + ▼ +Hono Server (apps/remix/server/) + │ + ├──▶ /api/v1/* ──▶ ts-rest handlers (packages/api/) + │ + ├──▶ /api/v2/* ──▶ tRPC OpenAPI handlers (packages/trpc/) + │ + ├──▶ /api/trpc/* ──▶ tRPC handlers (packages/trpc/) + │ + ├──▶ /api/jobs/* ──▶ Job handlers (packages/lib/jobs/) + │ + └──▶ /* ──▶ React Router (apps/remix/app/routes/) + │ + ▼ + React Components (packages/ui/) +``` + +### Document Signing Flow + +``` +1. Upload Document ──▶ Storage Provider (DB/S3) + │ +2. Add Recipients ────────────────┤ + │ +3. Add Fields ────────────────────┤ + │ +4. Send Document ─────────────────┤ + │ │ + ▼ │ + Email Job ──▶ Email Provider | + │ | +5. Recipient Signs ───────────────┤ + │ │ + ▼ │ + seal-document Job │ + │ │ + ▼ │ + Signing Provider ◀─────────────┘ + │ + ▼ + Signed PDF ──▶ Storage Provider +``` + +## Key Directories + +``` +documenso/ +├── apps/ +│ └── remix/ +│ ├── app/ +│ │ └── routes/ # React Router routes +│ │ ├── _authenticated+/ # Protected routes +│ │ ├── _unauthenticated+/ # Public routes +│ │ └── _recipient+/ # Signing routes +│ └── server/ +│ ├── router.ts # Hono route mounting +│ └── main.js # Entry point +├── packages/ +│ ├── api/v1/ # API V1 (ts-rest) +│ ├── trpc/server/ # API V2 + Internal (tRPC) +│ ├── lib/ +│ │ ├── server-only/ # Server business logic +│ │ ├── client-only/ # Client utilities +│ │ ├── universal/ # Shared code +│ │ └── jobs/ # Background jobs +│ ├── prisma/ # Database schema & client +│ ├── signing/ # PDF signing +│ ├── email/ # Email templates +│ └── ui/ # Component library +└── docker/ # Docker configs +``` + +## Development + +```bash +# Full setup (install, docker, migrate, seed, dev) +npm run d + +# Start development server +npm run dev + +# Database GUI +npm run prisma:studio + +# Type checking (faster than build) +npx tsc --noEmit + +# E2E tests +npm run test:e2e +``` + +### Docker Services (Development) + +| Service | Port | +| --------------- | ---------- | +| PostgreSQL | 54320 | +| Inbucket (Mail) | 9000 | +| MinIO (S3) | 9001, 9002 | + +## Environment Variables Summary + +| Variable | Purpose | Options | +| -------------------------------- | ---------------- | ------------------------------------------------- | +| `NEXT_PUBLIC_UPLOAD_TRANSPORT` | Storage provider | `database`, `s3` | +| `NEXT_PRIVATE_SIGNING_TRANSPORT` | Signing provider | `local`, `gcloud-hsm` | +| `NEXT_PRIVATE_SMTP_TRANSPORT` | Email provider | `smtp-auth`, `smtp-api`, `resend`, `mailchannels` | +| `NEXT_PRIVATE_JOBS_PROVIDER` | Jobs provider | `local`, `inngest` | + +See `.env.example` for the complete list of configuration options. diff --git a/WRITING_STYLE.md b/WRITING_STYLE.md new file mode 100644 index 000000000..cc9c21419 --- /dev/null +++ b/WRITING_STYLE.md @@ -0,0 +1,343 @@ +# Documentation Writing Style Guide + +This document defines the writing conventions for Documenso documentation. + +Documentation lives in `apps/docs/` as MDX files and uses [Fumadocs](https://fumadocs.dev). + +## Core Principles + +1. **Task-based navigation** - Organize by what users want to do, not by feature hierarchy +2. **Progressive examples** - Start simple, build to complex +3. **Explicit limitations** - List what's NOT supported clearly +4. **Real-world context** - Explain document signing concepts with familiar comparisons + +## Tone + +- Direct and action-oriented +- Second person ("you") with imperative voice +- Technical but accessible +- Acknowledge complexity without condescension +- No emojis or excessive personality + +## Anti-Patterns to Avoid + +- Assuming document signing domain knowledge +- Hiding default values +- Separate "TypeScript" sections (types integrated throughout) +- Monolithic single-page references +- Examples that don't work with current API + +## Documentation Audiences + +The docs serve three distinct audiences: + +1. **Users** - People using the Documenso web application to send and sign documents +2. **Developers** - Building integrations with the API or SDKs +3. **Self-hosters** - Running their own Documenso instance + +Tailor content to the audience: + +- User docs: Focus on UI workflows, no code required +- Developer docs: API/SDK examples, authentication, webhooks +- Self-hosting docs: Deployment, configuration, infrastructure + +## File Structure + +``` +apps/docs/ +├── index.mdx # Landing page with audience navigation +├── getting-started/ # Quick starts for each audience +├── users/ # Application usage guides +│ ├── documents/ # Creating and managing documents +│ ├── templates/ # Working with templates +│ ├── signing/ # Signing documents +│ └── settings/ # Account and team settings +├── developers/ # API and SDK documentation +│ ├── api/ # REST API reference +│ ├── sdk/ # SDK guides +│ ├── webhooks/ # Webhook integration +│ └── examples/ # Code examples and recipes +├── self-hosting/ # Self-hosting documentation +│ ├── deployment/ # Deployment guides +│ ├── configuration/ # Environment and settings +│ └── maintenance/ # Upgrades and backups +├── concepts/ # Shared concepts across audiences +└── migration/ # Migration guides +``` + +Each directory has a `meta.json` controlling navigation order: + +```json +{ + "title": "Section Title", + "pages": ["index", "page-one", "page-two"] +} +``` + +Use `---Label---` for section dividers in `meta.json`. + +## MDX Frontmatter + +Every page needs frontmatter for search and SEO: + +```yaml +--- +title: Working with Pages +description: Add, remove, reorder, copy, and merge PDF pages. +--- +``` + +## Page Structure + +### User Documentation + +```mdx +--- +title: Feature Name +description: Brief description for SEO and previews. +--- + +# Feature Name + +Brief description of what this does and when to use it. + +## Steps + +1. Navigate to **Settings > Feature** +2. Click **Add New** +3. Fill in the required fields + +--- + +## See Also + +- [Related Guide](/docs/users/related) +``` + +### Developer Documentation + +```mdx +--- +title: Feature Name +description: Brief description for SEO and previews. +--- + +# Feature Name + +Brief description of what this does and when to use it. + +## Quick Start + +\`\`\`typescript +// Minimal working example +\`\`\` + +--- + +## Section Name + +Content organized by task or concept. + +--- + +## See Also + +- [Related Guide](/docs/developers/related) +``` + +### Self-Hosting Documentation + +```mdx +--- +title: Configuration Topic +description: Brief description for SEO and previews. +--- + +# Configuration Topic + +Brief description of what this configures. + +## Environment Variables + +| Variable | Required | Default | Description | +| ---------- | -------- | ------- | ------------ | +| `VAR_NAME` | Yes | - | What it does | + +--- + +## See Also + +- [Related Guide](/docs/self-hosting/related) +``` + +## Parameter Tables + +Use Sharp-style nested parameter tables for developer documentation (API/SDK): + +```markdown +### methodName(param, options?) + +Description of what the method does. + +| Param | Type | Default | Description | +| ------------------- | --------- | -------- | --------------------- | +| `param` | `string` | required | What it does | +| `[options]` | `Options` | | | +| `[options.setting]` | `boolean` | `false` | Nested option | +| `[options.timeout]` | `number` | `5000` | Another nested option | + +**Returns**: `Promise` + +**Throws**: + +- `SpecificError` - When something goes wrong +``` + +Key conventions: + +- Square brackets `[param]` indicate optional parameters +- Nested options indented with `[options.name]` pattern +- Always show default values +- Group related options under their parent + +## Code Examples + +For developer documentation, use progressive complexity: + +```typescript +// Basic usage +const document = await documenso.documents.create({ + title: "Contract", + file: pdfBuffer, +}); + +// With recipients +const document = await documenso.documents.create({ + title: "Contract", + file: pdfBuffer, + recipients: [{ email: "signer@example.com", name: "John Doe" }], +}); + +// Full example with error handling +try { + const document = await documenso.documents.create({ + title: "Contract", + file: pdfBuffer, + recipients: [{ email: "signer@example.com", name: "John Doe" }], + }); +} catch (error) { + if (error instanceof DocumentError) { + // Handle document creation error + } +} +``` + +### Example Guidelines + +- All examples must be valid TypeScript +- Show imports when not obvious +- Include expected output in comments where helpful +- Use realistic values, not `foo`/`bar` + +## UI Instructions + +For user documentation, use clear step-by-step instructions: + +- Bold UI elements: **Settings**, **Save**, **Documents** +- Use `>` for navigation paths: **Settings > Team > Members** +- Number sequential steps +- Include screenshots sparingly for complex workflows +- Describe what the user should see after each action + +## Callouts + +Use Fumadocs callouts sparingly for important information: + +```mdx +Informational note about behavior. + +Warning about potential issues or breaking changes. + +Critical warning about data loss or security. +``` + +Reserve callouts for: + +- Beta/unstable features +- Security considerations +- Common mistakes +- Breaking changes + +## Tables + +Use tables for: + +- Feature matrices +- Parameter documentation +- Comparison charts +- Error catalogs + +```markdown +| Feature | Status | Notes | +| ---------------- | ------ | ------------------------ | +| Email signing | Full | All recipient types | +| Embedded signing | Full | Via SDK or direct links | +| Templates | Full | Create and use templates | +``` + +## Linking + +- Link to related docs: `[Documents](/docs/api/documents)` +- Use relative paths within docs +- Add "See Also" sections for discoverability + +## Error Documentation + +Categorize errors by when they occur: + +```markdown +## Document Errors + +Thrown when creating or updating documents. + +### InvalidDocumentError + +Document could not be processed. + +**Common causes:** + +- File is not a valid PDF +- File exceeds size limits + +**Solution:** Verify the file is a valid PDF within size limits. +``` + +## Concept Explanations + +Use analogies for document signing concepts: + +```markdown +Think of a **signing workflow** like passing a physical document around an office. + +Each recipient gets the document in turn, adds their signature or initials, +and passes it to the next person. The **document status** tracks where it +is in this journey. +``` + +## Self-Hosting Specific + +For self-hosting documentation: + +- Always specify required vs optional environment variables +- Include example `.env` snippets +- Document Docker and non-Docker approaches where applicable +- Link to troubleshooting for common deployment issues +- Specify minimum system requirements + +## Maintenance + +- Include types inline so docs don't get stale +- Reference source file locations for complex behavior +- Update examples when API changes +- Test all code examples work +- Keep environment variable documentation in sync with actual defaults diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore new file mode 100644 index 000000000..9e429e498 --- /dev/null +++ b/apps/docs/.gitignore @@ -0,0 +1,26 @@ +# deps +/node_modules + +# generated content +.source + +# test & build +/coverage +/.next/ +/out/ +/build +*.tsbuildinfo + +# misc +.DS_Store +*.pem +/.pnp +.pnp.js +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# others +.env*.local +.vercel +next-env.d.ts \ No newline at end of file diff --git a/apps/docs/README.md b/apps/docs/README.md new file mode 100644 index 000000000..9b7bba9e0 --- /dev/null +++ b/apps/docs/README.md @@ -0,0 +1,45 @@ +# docs + +This is a Next.js application generated with +[Create Fumadocs](https://github.com/fuma-nama/fumadocs). + +Run development server: + +```bash +npm run dev +# or +pnpm dev +# or +yarn dev +``` + +Open http://localhost:3000 with your browser to see the result. + +## Explore + +In the project, you can see: + +- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content. +- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep. + +| Route | Description | +| ------------------------- | ------------------------------------------------------ | +| `app/(home)` | The route group for your landing page and other pages. | +| `app/docs` | The documentation layout and pages. | +| `app/api/search/route.ts` | The Route Handler for search. | + +### Fumadocs MDX + +A `source.config.ts` config file has been included, you can customise different options like frontmatter schema. + +Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details. + +## Learn More + +To learn more about Next.js and Fumadocs, take a look at the following +resources: + +- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js + features and API. +- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs diff --git a/apps/docs/cli.json b/apps/docs/cli.json new file mode 100644 index 000000000..89d51513d --- /dev/null +++ b/apps/docs/cli.json @@ -0,0 +1,13 @@ +{ + "$schema": "node_modules/@fumadocs/cli/dist/schema/src.json", + "aliases": { + "uiDir": "./components/ui", + "componentsDir": "./components", + "blockDir": "./components", + "cssDir": "./styles", + "libDir": "./lib" + }, + "baseDir": "src", + "uiLibrary": "radix-ui", + "commands": {} +} \ No newline at end of file diff --git a/apps/docs/content/docs/compliance/certifications.mdx b/apps/docs/content/docs/compliance/certifications.mdx new file mode 100644 index 000000000..5c6f936b9 --- /dev/null +++ b/apps/docs/content/docs/compliance/certifications.mdx @@ -0,0 +1,57 @@ +--- +title: Certifications & Regulatory Compliance +description: Documenso's compliance status for industry certifications and regulatory frameworks. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +### Compliance Status Overview + +| Certification | Status | +| -------------- | ---------------------- | +| 21 CFR Part 11 | Compliant (Enterprise) | +| SOC 2 | Compliant | +| ISO 27001 | Planned | +| HIPAA | Planned | + +## 21 CFR Part 11 + +Status: Compliant (Enterprise License) + +21 CFR Part 11 is a regulation by the FDA that establishes the criteria for electronic records and electronic signatures to ensure their authenticity, integrity, and confidentiality in the pharmaceutical, medical device, and other FDA-regulated industries. + +Read more about [21 CFR Part 11 with Documenso](https://documen.so/21-CFR-Part-11). + +### Main Requirements + +- Strong Identity Checks for each Signature +- Signature and Audit Trails +- User Access Management +- Quality Assurance Documentation + +## SOC 2 + +Status: [Compliant](https://documen.so/trust) + +SOC 2 is a framework for managing and auditing the security, availability, processing integrity, confidentiality, and data privacy in cloud and IT service organizations, established by the American Institute of Certified Public Accountants (AICPA). + +## ISO 27001 + +Status: [Planned](https://github.com/documenso/backlog/issues/26) + +ISO 27001 is an international standard for managing information security, specifying requirements for establishing, implementing, maintaining, and continually improving an information security management system (ISMS). + +## HIPAA + +Status: [Planned](https://github.com/documenso/backlog/issues/25) + +The HIPAA (Health Insurance Portability and Accountability Act) is a U.S. law designed to protect patient health information's privacy and security and improve the healthcare system's efficiency and effectiveness. + +--- + +## See Also + +- [Standards](/docs/compliance/standards) - Technical signing standards (PDF/A, PAdES, X.509) +- [Signature Levels](/docs/compliance/signature-levels) - eIDAS and other signature level compliance +- [Enterprise Edition](/docs/policies/enterprise-edition) - Enterprise licensing for compliance features +- [GDPR](/docs/compliance/gdpr) - Data protection compliance diff --git a/apps/docs/content/docs/compliance/esign.mdx b/apps/docs/content/docs/compliance/esign.mdx new file mode 100644 index 000000000..c4f503d88 --- /dev/null +++ b/apps/docs/content/docs/compliance/esign.mdx @@ -0,0 +1,187 @@ +--- +title: E-Sign Compliance +description: Understand ESIGN, UETA, eIDAS, and other electronic signature laws that govern digital documents. +--- + +## ESIGN Act (United States) + +The Electronic Signatures in Global and National Commerce Act (ESIGN Act) is a U.S. federal law enacted in 2000. It ensures that electronic signatures and records have the same legal validity as paper documents and handwritten signatures in interstate and foreign commerce. + +### Key Requirements + +| Requirement | Description | +| ----------------------- | ----------------------------------------------------------------------------------------- | +| **Intent to Sign** | Signers must demonstrate clear intent to sign the document | +| **Consent** | All parties must agree to conduct the transaction electronically | +| **Consumer Disclosure** | For consumer transactions, specific disclosures must be provided before obtaining consent | +| **Record Retention** | Electronic records must be accurately preserved and accessible for later reference | +| **Association** | The signature must be associated with the record being signed | + +### Exclusions + +The ESIGN Act does not apply to certain document types, including: + +- Wills, codicils, and testamentary trusts +- Family law documents (adoption, divorce) +- Court orders and official court documents +- Cancellation of utility services +- Documents related to hazardous materials transportation + +--- + +## UETA (United States) + +The Uniform Electronic Transactions Act (UETA) is a model law adopted by 49 U.S. states (all except New York, which has its own Electronic Signatures and Records Act). UETA provides a legal framework for electronic signatures and records at the state level. + +### Relationship to ESIGN + +UETA and the ESIGN Act have similar requirements and purposes. The federal ESIGN Act allows states to modify or supersede certain ESIGN provisions if they adopt UETA or an equivalent law. In practice, the requirements for electronic signatures under both laws align closely. + +### Key Requirements + +- Intent to sign demonstrated by the signer +- Consent to conduct transactions electronically +- Retention of records in their original electronic form +- Attribution of the signature to the signer + +--- + +## eIDAS (European Union) + +The Electronic Identification, Authentication and Trust Services (eIDAS) regulation governs electronic signatures across all EU member states. eIDAS establishes three levels of electronic signatures, each with different requirements and legal effects. + +### Signature Levels + +| Level | Description | Legal Effect | +| ------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- | +| **Simple (SES)** | Basic electronic signature with no specific technical requirements | Admissible as evidence; legal effect varies by use | +| **Advanced (AES)** | Uniquely linked to signer, capable of identifying signer, under sole control | Higher evidentiary weight than SES | +| **Qualified (QES)** | AES created by a qualified signature creation device, based on a qualified certificate | Equivalent to handwritten signature across the EU | + +### Simple Electronic Signatures (SES) + +SES is the baseline level. Any data in electronic form attached to or logically associated with other electronic data, used by the signatory to sign, qualifies as an SES. There are no specific technical requirements beyond demonstrating intent to sign. + +### Advanced Electronic Signatures (AES) + +AES must meet additional criteria: + +- Uniquely linked to the signatory +- Capable of identifying the signatory +- Created using signature creation data under the signatory's sole control +- Linked to the signed data in a way that detects subsequent changes + +### Qualified Electronic Signatures (QES) + +QES requires: + +- A qualified certificate issued by a qualified trust service provider +- Creation using a qualified electronic signature creation device +- Identity verification compliant with eIDAS requirements + +QES carries the same legal standing as a handwritten signature in all EU member states. + +--- + +## Other Jurisdictions + +Electronic signature laws exist in most countries. Below are selected examples: + +| Jurisdiction | Framework | Notes | +| ------------------ | --------------------------------------------- | ------------------------------------------------------------ | +| **United Kingdom** | UK eIDAS / Electronic Communications Act 2000 | Post-Brexit, UK maintains eIDAS-like framework | +| **Canada** | PIPEDA, provincial laws | Federal and provincial laws govern e-signatures | +| **Australia** | Electronic Transactions Act 1999 | Generally technology-neutral approach | +| **Switzerland** | ZertES | Swiss federal law with qualified signature requirements | +| **Brazil** | MP 2200-2, ICP-Brasil | PKI-based framework for digital signatures | +| **India** | IT Act 2000, Aadhaar e-KYC | Recognizes electronic signatures; Aadhaar-based verification | +| **China** | Electronic Signature Law | Requires reliable electronic signatures for certain uses | +| **Japan** | Electronic Signatures Act | Three-tier system similar to eIDAS | + +Requirements vary significantly by jurisdiction. Some transactions may require specific signature types or have exclusions similar to the ESIGN Act. + +--- + +## How Documenso Supports Compliance + +Documenso provides features that support compliance with e-signature laws across jurisdictions: + +### Intent to Sign + +- Signers must actively interact with signature fields to apply their signature +- The signing interface clearly indicates the document being signed +- Signers receive a copy of the completed document + +### Consent + +- Recipients receive clear notification that they are being asked to sign electronically +- The signing process requires affirmative action from the signer + +### Record Retention + +- Signed documents are stored and accessible to all parties +- Original documents and audit trails are preserved +- Documents can be downloaded in their signed form at any time + +### Document Integrity + +- All completed documents are cryptographically sealed +- Any modification after signing invalidates the digital signature +- PDF readers can verify the document has not been altered + +### Signer Identification + +- Email-based delivery establishes signer identity +- Optional access codes add verification +- Signing activity is logged with timestamps and metadata + +--- + +## Audit Trails + +Documenso maintains an audit trail for each document, recording: + +| Event | Recorded Data | +| ------------------ | -------------------------------------- | +| Document creation | Timestamp, creator identity | +| Recipient addition | Recipient details, assigned fields | +| Document sent | Timestamp, delivery method | +| Document viewed | Timestamp, viewer identity, IP address | +| Field completed | Timestamp, field type, signer identity | +| Document completed | Timestamp, final document hash | + +The audit trail provides evidence of the signing process, including who signed, when they signed, and the sequence of events. This information supports the legal enforceability of the signed document. + +--- + +## What Documenso Does NOT Provide + +Documenso supports compliance with Simple Electronic Signature (SES) requirements. The following are not currently provided: + +| Capability | Status | +| ----------------------------------------- | ------------------------------------------------------------------------------------- | +| **Qualified Electronic Signatures (QES)** | Not supported; requires integration with qualified trust service providers | +| **Advanced Electronic Signatures (AES)** | Partial support; full AES requires identity verification services | +| **Identity Verification (KYC)** | Not built-in; optional integrations may be available | +| **Qualified Certificates** | Not issued; would require becoming a qualified trust service provider | +| **Industry-Specific Compliance** | Features for specific regulations (e.g., healthcare, finance) depend on configuration | + +For transactions requiring AES or QES, consult with legal counsel about appropriate solutions. + +--- + +## Disclaimer + +This page provides general information about electronic signature laws for educational purposes. It does not constitute legal advice. + +Electronic signature requirements vary by jurisdiction, transaction type, and specific circumstances. Some documents may have specific legal requirements that electronic signatures cannot satisfy. + +Consult qualified legal counsel in your jurisdiction to determine whether electronic signatures are appropriate for your specific use case and what requirements must be met. + +--- + +## Related + +- [Signature Levels](/docs/compliance/signature-levels) - Simple, Advanced, and Qualified electronic signatures explained +- [Standards & Regulations](/docs/compliance/standards) - SOC 2, 21 CFR Part 11, and other compliance frameworks +- [Signing Certificates](/docs/concepts/signing-certificates) - How documents are digitally signed and verified diff --git a/apps/docs/content/docs/compliance/gdpr.mdx b/apps/docs/content/docs/compliance/gdpr.mdx new file mode 100644 index 000000000..7b5502bf3 --- /dev/null +++ b/apps/docs/content/docs/compliance/gdpr.mdx @@ -0,0 +1,174 @@ +--- +title: GDPR +description: Understand how Documenso handles GDPR compliance for data processing and storage. +--- + +import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + +## Documenso's Role + +When using Documenso for document signing, two distinct data processing roles apply: + +| Role | Description | +| ------------------- | ------------------------------------------------------------------------------------- | +| **Data Controller** | You (the organisation using Documenso) determine the purposes and means of processing | +| **Data Processor** | Documenso processes personal data on your behalf according to your instructions | + +As the data controller, you are responsible for: + +- Obtaining appropriate consent or legal basis for processing +- Informing data subjects about how their data is used +- Responding to data subject access requests +- Ensuring compliance with GDPR requirements + +As the data processor, Documenso: + +- Processes data only according to your instructions +- Implements appropriate security measures +- Assists with data subject requests when needed +- Maintains records of processing activities + +## Data Processing + +Documenso processes personal data necessary to provide document signing services: + +| Data Category | Examples | Purpose | +| ------------------ | ---------------------------------------------- | --------------------------------------- | +| **Identity Data** | Name, email address | User accounts, recipient identification | +| **Document Data** | Uploaded PDFs, field values | Document storage and signing | +| **Signature Data** | Signature images, signing timestamps | Recording signing actions | +| **Audit Data** | IP addresses, browser information, action logs | Audit trail and verification | + +Data is processed for the following purposes: + +- Delivering documents to recipients +- Recording signatures and other recipient actions +- Generating signed documents with audit trails +- Sending email notifications + +## Data Storage Locations + +Where your data is stored depends on how you use Documenso: + + + + +For the hosted cloud service: + +- Application data is stored in data centres within the European Union +- Document storage uses EU-based infrastructure +- Backups are maintained in geographically separate EU locations + +Contact Documenso for specific information about sub-processors and data centre locations. + + + + +When you self-host Documenso: + +- You control all data storage locations +- No data is transmitted to Documenso's infrastructure +- You choose your own database, file storage, and backup locations + +Self-hosting provides complete control over data residency, which may be required for certain compliance scenarios. + + + + +## Data Subject Rights + +GDPR grants individuals specific rights regarding their personal data. As the data controller, you are responsible for fulfilling these requests: + +| Right | Description | +| ----------------- | -------------------------------------------------------------------------- | +| **Access** | Data subjects can request a copy of their personal data | +| **Rectification** | Data subjects can request correction of inaccurate data | +| **Erasure** | Data subjects can request deletion of their data ("right to be forgotten") | +| **Portability** | Data subjects can request their data in a machine-readable format | +| **Restriction** | Data subjects can request limited processing of their data | +| **Objection** | Data subjects can object to certain types of processing | + +When you receive a data subject request, you can: + +- Export user and document data from your Documenso account +- Delete user accounts and associated documents +- Contact Documenso support for assistance with cloud-hosted data + +## Data Deletion + +Documenso supports data deletion to help fulfill erasure requests: + + + + - Users can delete their own accounts + - Account deletion removes profile data and authentication credentials + - Team owners can remove members from teams + + + - Document owners can delete documents in draft state + - Completed documents can be deleted by the owner + - Deletion removes the document, recipient data, and associated audit logs + + + For signed documents, you may need to balance deletion requests against: + + - Legal requirements to retain signed contracts + - Your organisation's record-keeping policies + - The rights of other parties to the signed document + + Consult with legal counsel to establish appropriate retention policies. + + + + +## Self-Hosting for GDPR Compliance + +Self-hosting Documenso can simplify GDPR compliance: + +- **Data residency** - Store all data in your chosen jurisdiction +- **Sub-processor control** - No third-party data processors beyond your own infrastructure +- **Direct access** - Full database access for data subject requests +- **Retention control** - Implement custom data retention and deletion policies + +See the [Self-Hosting Guide](/docs/self-hosting) for deployment options. + +## Data Processing Agreement + +A Data Processing Agreement (DPA) is a contract required by GDPR when a data controller engages a data processor. + + + + +- A DPA is available upon request +- Contact [support@documenso.com](mailto:support@documenso.com) to request a DPA +- The DPA covers Documenso's obligations as a data processor + + + + +No DPA with Documenso is required since no personal data is processed by Documenso. + + + + +--- + +## Disclaimer + +This documentation is provided for informational purposes only and does not constitute legal advice. GDPR compliance depends on your specific circumstances, including how you use Documenso, what data you process, and your organisation's obligations. + +Consult with qualified legal counsel to: + +- Determine your GDPR obligations +- Draft appropriate privacy notices +- Establish lawful bases for processing +- Implement compliant data handling procedures + +--- + +## Related + +- [Standards & Regulations](/docs/compliance/standards) - eIDAS, ESIGN Act, and other compliance frameworks +- [Self-Hosting Guide](/docs/self-hosting) - Deploy Documenso on your own infrastructure +- [Security Settings](/docs/users/settings/security) - Configure authentication and security options diff --git a/apps/docs/content/docs/compliance/index.mdx b/apps/docs/content/docs/compliance/index.mdx new file mode 100644 index 000000000..5364c5854 --- /dev/null +++ b/apps/docs/content/docs/compliance/index.mdx @@ -0,0 +1,58 @@ +--- +title: Compliance +description: Legal and regulatory compliance information for electronic signatures. +--- + +## Overview + + + + + + +## Additional Topics + + + + + + + +## Disclaimer + +This documentation is provided for informational purposes only. It does not constitute legal advice and should not be relied upon as such. + +Compliance requirements vary based on: + +- Your jurisdiction and applicable laws +- The type of documents being signed +- Industry-specific regulations +- The parties involved in the transaction + +Consult with qualified legal counsel to determine the specific requirements for your use case. + +## Related + +- [Privacy Policy](/docs/policies/privacy) - How Documenso handles personal data +- [Security](/docs/policies/security) - Security practices and measures +- [Terms of Service](/docs/policies/terms) - Terms governing use of Documenso diff --git a/apps/docs/content/docs/compliance/meta.json b/apps/docs/content/docs/compliance/meta.json new file mode 100644 index 000000000..efc47b54e --- /dev/null +++ b/apps/docs/content/docs/compliance/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Compliance", + "pages": ["esign", "standards", "signature-levels", "gdpr", "certifications"] +} diff --git a/apps/docs/content/docs/compliance/signature-levels.mdx b/apps/docs/content/docs/compliance/signature-levels.mdx new file mode 100644 index 000000000..8fc89f59f --- /dev/null +++ b/apps/docs/content/docs/compliance/signature-levels.mdx @@ -0,0 +1,284 @@ +--- +title: Signature Levels +description: Understand the three eIDAS signature levels — SES, AES, and QES — their requirements, legal effect, and when to use each. +--- + +import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; +import { Callout } from 'fumadocs-ui/components/callout'; + + + Documenso seals all signed documents cryptographically, regardless of signature level, to prevent + any alterations after signing. + + +### Compliance Status Overview + +| Regulation | Status | +| ------------ | --------- | +| ESIGN / UETA | Compliant | +| eIDAS SES | Compliant | +| eIDAS AES | Planned | +| eIDAS QES | Planned | +| ZertES | Planned | + +## U.S. ESIGN Act + +Status: Compliant + +The Electronic Signatures in Global and National Commerce Act (ESIGN Act) is a U.S. federal law that ensures the legal validity and enforceability of electronic signatures and records in commerce. + +### Main Requirements + +- **Intent to Sign** - Parties must demonstrate their intent to sign +- **Consent** - All parties must consent to the use of electronic signatures and records +- **Consumer Disclosures** - Financial institutions must provide clear statements informing consumers before obtaining consent +- **Record Retention** - Electronic records must be maintained for later access by signers +- **Security** - Parties must take reasonable steps to ensure the security and integrity of electronic signatures and records + +## UETA (Uniform Electronic Transactions Act) + +Status: Compliant + +The Uniform Electronic Transactions Act provides a legal framework for the use of electronic signatures and records in electronic transactions, ensuring they have the same validity and enforceability as paper documents and handwritten signatures. + +UETA shares the same core requirements as the [ESIGN Act](#us-esign-act). + +## Simple Electronic Signatures (SES) + +A Simple Electronic Signature is the most basic form of electronic signature. It includes any data in electronic form that is attached to or logically associated with other electronic data and used by the signatory to sign. + +### Characteristics + +| Aspect | Description | +| -------------------------- | ------------------------------------------------------------------------------------- | +| **Technical Requirements** | No specific technical requirements beyond demonstrating intent to sign | +| **Identity Verification** | None required; relies on email delivery or other indirect identification | +| **Legal Status** | Admissible as evidence; cannot be denied legal effect solely because it is electronic | +| **Examples** | Typed name, scanned signature image, checkbox acceptance, click-to-sign | + +### When SES Is Appropriate + +SES is suitable for many common business transactions: + +- Standard contracts and agreements +- Internal approvals and sign-offs +- Terms of service acceptance +- Non-disclosure agreements +- Purchase orders and invoices +- Employment documents (in most jurisdictions) + +The legal validity of SES depends on the specific transaction and jurisdiction. Many everyday business documents do not require higher signature levels. + +--- + +## Advanced Electronic Signatures (AES) + +An Advanced Electronic Signature meets additional technical and procedural requirements that provide stronger evidence of the signer's identity and the document's integrity. + +### Requirements + +Under eIDAS, an AES must satisfy four criteria: + +1. **Uniquely linked to the signatory** - The signature is associated with a specific individual +2. **Capable of identifying the signatory** - The signature data reveals who signed +3. **Created using signature creation data under the signatory's sole control** - Only the signer can create the signature (e.g., private key, secure device) +4. **Linked to the data in such a way that any subsequent change is detectable** - Tampering invalidates the signature + +### Characteristics + +| Aspect | Description | +| -------------------------- | -------------------------------------------------------------------------- | +| **Technical Requirements** | Cryptographic signature with signer identification | +| **Identity Verification** | Required; must establish signer identity through verification process | +| **Legal Status** | Higher evidentiary weight than SES; stronger presumption of validity | +| **Implementation** | Typically requires identity verification service and personal certificates | + +### Compliance Status + + + Status: [Planned](https://github.com/documenso/backlog/issues/9) via third party until [Let's + Sign](https://github.com/documenso/backlog/issues/21) is realized. + + +Current AES progress: + +- Cryptographic signature sealing the document against tampering +- Signing using dedicated hardware (Hardware Security Module) +- Embedding signer identity in the cryptographic signature (planned) +- Being a government-audited trusted qualified services provider (planned) + +### When AES Is Appropriate + +AES is used when stronger proof of identity and intent is needed: + +- Financial services agreements +- Real estate transactions (in some jurisdictions) +- Healthcare consent forms +- Government submissions +- High-value contracts +- Cross-border agreements within the EU + +--- + +## Qualified Electronic Signatures (QES) + +A Qualified Electronic Signature is the highest level of electronic signature under eIDAS. It is legally equivalent to a handwritten signature in all EU member states and carries a presumption of validity. + +### Requirements + +QES must meet all AES requirements plus: + +1. **Qualified Certificate** - Issued by a Qualified Trust Service Provider (QTSP) that is accredited by an EU member state +2. **Qualified Electronic Signature Creation Device (QSCD)** - The signature is created using hardware or software that meets specific security standards +3. **Identity Verification** - In-person or equivalent remote verification compliant with eIDAS requirements + +### Characteristics + +| Aspect | Description | +| -------------------------- | --------------------------------------------------------------------- | +| **Technical Requirements** | Qualified certificate + qualified signature creation device | +| **Identity Verification** | Strict verification by a Qualified Trust Service Provider | +| **Legal Status** | Equivalent to handwritten signature across all EU member states | +| **Implementation** | Requires integration with a QTSP; typically involves external service | + +### Compliance Status + + + Status: [Planned](https://github.com/documenso/backlog/issues/32) via third party until [Let's + Sign](https://github.com/documenso/backlog/issues/21) is realized. + + +### When QES Is Required + +Certain transactions require or benefit from QES: + +- Documents that legally require a handwritten signature under national law +- Court filings and legal documents +- Company formation documents +- Land registry transactions +- Notarized documents +- Regulated financial transactions +- Cross-border transactions requiring guaranteed recognition + +--- + +## Comparison of Signature Levels + +| Aspect | SES | AES | QES | +| ------------------------- | ------------ | ------------------------ | --------------------- | +| **Technical Complexity** | Low | Medium | High | +| **Identity Verification** | None | Required | Strict (QTSP) | +| **Legal Effect (EU)** | Admissible | Higher evidentiary value | Equal to handwritten | +| **Cost** | Low | Medium | Higher | +| **User Experience** | Simple | More steps | Most steps | +| **Signer Requirements** | Email access | Identity verification | Certificate from QTSP | + +### Legal Recognition + +| Jurisdiction | SES | AES | QES | +| ------------------ | ------------------------------- | -------------------------- | ------------------------------------ | +| **European Union** | Valid, evidentiary value varies | Enhanced evidentiary value | Equivalent to handwritten | +| **United States** | Valid under ESIGN/UETA | No formal distinction | No formal distinction | +| **United Kingdom** | Valid | Enhanced value | Equivalent to handwritten (UK eIDAS) | +| **Switzerland** | Valid | Valid | Equivalent to handwritten (ZertES) | + +--- + +## What Documenso Provides + +Documenso supports Simple Electronic Signatures (SES) with features that enhance evidentiary value: + +### SES Features + +- **Intent to Sign** - Signers actively interact with signature fields +- **Email-Based Delivery** - Documents sent to specific email addresses +- **Audit Trail** - Complete record of signing events, timestamps, and IP addresses +- **Document Integrity** - Cryptographic sealing detects any post-signing modifications +- **Record Retention** - Signed documents stored and accessible to all parties + +### Additional Verification Options + +- **Access Codes** - Require signers to enter a code before accessing documents +- **Signing Order** - Control the sequence of signatures + +### What Documenso Does Not Provide + +| Capability | Status | +| ----------------------------------------- | --------------------------------------------------------- | +| **Qualified Electronic Signatures (QES)** | Not supported; requires QTSP integration | +| **Advanced Electronic Signatures (AES)** | Partial; full AES requires identity verification services | +| **Identity Verification (KYC)** | Not built-in | +| **Qualified Certificates** | Not issued; would require QTSP status | + +For transactions requiring AES or QES, you would need to integrate with external identity verification services or Qualified Trust Service Providers. + +--- + +## ZertES (Swiss Federal Law) + +Status: [Planned](https://github.com/documenso/backlog/issues/34) + +ZertES is a Swiss federal law that regulates electronic signature compliance. It defines requirements similar to eIDAS for qualified electronic signatures within Switzerland. + +--- + +## When You Need Higher Signature Levels + +Consider using AES or QES when: + + + + - National law requires a handwritten signature (QES may substitute) + - Regulations specify signature requirements (e.g., certain financial or healthcare documents) + - Cross-border enforceability is critical + + + - High contract value or significant liability + - Higher likelihood of disputes + - Need for stronger non-repudiation + - Counterparty or regulatory requirements specify higher levels + + + - Financial services with regulatory oversight + - Healthcare with patient consent requirements + - Government or public sector contracts + - Real estate transactions in regulated markets + + + Most business transactions do not require AES or QES. Consider: + + 1. What does your jurisdiction require for this document type? + 2. What do your counterparties or customers expect? + 3. What is the risk if the signature is disputed? + 4. Does your industry have specific requirements? + + When in doubt, consult with legal counsel to determine the appropriate signature level for your specific use case. + + + + +--- + +## Disclaimer + +This documentation is provided for informational purposes only and does not constitute legal advice. + +The appropriate signature level for your documents depends on: + +- Your jurisdiction and applicable laws +- The type of document being signed +- Industry-specific regulations +- Contractual requirements from counterparties +- Risk tolerance and dispute likelihood + +Electronic signature requirements vary significantly across jurisdictions and document types. Some transactions have specific legal requirements that may mandate particular signature levels or exclude electronic signatures entirely. + +Consult with qualified legal counsel to determine the signature level requirements for your specific use case. + +--- + +## Related + +- [E-Sign Compliance](/docs/compliance/esign) - ESIGN Act, UETA, eIDAS, and electronic signature laws +- [Signing Certificates](/docs/concepts/signing-certificates) - How documents are digitally signed and verified +- [Standards & Regulations](/docs/compliance/standards) - SOC 2, 21 CFR Part 11, and other frameworks diff --git a/apps/docs/content/docs/compliance/standards.mdx b/apps/docs/content/docs/compliance/standards.mdx new file mode 100644 index 000000000..e2e30f887 --- /dev/null +++ b/apps/docs/content/docs/compliance/standards.mdx @@ -0,0 +1,108 @@ +--- +title: Standards & Regulations +description: Key technical standards that ensure digital signatures are secure, interoperable, and valid long-term. +--- + +## PDF/A for Archival + +PDF/A is an ISO-standardized version of PDF designed for long-term archival of electronic documents. Unlike standard PDFs, PDF/A files are self-contained and do not rely on external resources. + +Key characteristics: + +- All fonts must be embedded +- No external content references allowed +- No encryption that would prevent future access +- Metadata must be embedded in XMP format +- Color spaces must be device-independent or include ICC profiles + +PDF/A has several conformance levels (PDF/A-1, PDF/A-2, PDF/A-3) with increasing capabilities. PDF/A-3, for example, allows embedding of arbitrary file formats as attachments. + +For signed documents intended for long-term storage, PDF/A ensures the document remains readable and verifiable years or decades after signing. + +## PAdES (PDF Advanced Electronic Signatures) + +PAdES is a set of standards (ETSI EN 319 142) that defines profiles for electronic signatures in PDF documents. It builds on the PDF signature capabilities defined in ISO 32000 and adds requirements for long-term validity. + +PAdES defines several signature profiles: + +| Profile | Description | +| --------- | ---------------------------------------------------- | +| PAdES-B | Basic signature with signing certificate | +| PAdES-T | Adds a trusted timestamp | +| PAdES-LT | Adds validation data (certificates, revocation info) | +| PAdES-LTA | Adds long-term archival timestamps | + +Each level builds upon the previous, with PAdES-LTA providing the strongest guarantees for long-term signature validity. The inclusion of validation data and archival timestamps allows signatures to be verified even after certificates expire or CAs cease operations. + +## ISO 32000 (PDF Standard) + +ISO 32000 is the international standard that defines the PDF format. It specifies the technical foundation for digital signatures in PDF documents. + +Relevant signature capabilities defined in ISO 32000: + +- Signature field dictionaries and appearance streams +- Cryptographic signature handlers +- Certificate and timestamp embedding +- Incremental updates for signature preservation +- Document modification detection + +ISO 32000-2 (PDF 2.0) introduced additional features including support for more signature algorithms and improved encryption options. + +## X.509 Certificates + +X.509 is the standard format for public key certificates used in digital signatures. These certificates bind a public key to an identity and are issued by Certificate Authorities (CAs). + +A typical X.509 certificate contains: + +- Subject (identity information) +- Issuer (the CA that issued the certificate) +- Public key +- Validity period (not before / not after dates) +- Serial number +- Signature algorithm +- Extensions (key usage, policies, etc.) + +For document signing, certificates typically include the "digital signature" key usage extension. Qualified certificates under eIDAS regulations have additional requirements and provide higher levels of assurance. + +Certificate validation involves checking: + +1. The certificate chain up to a trusted root CA +2. That no certificate in the chain has expired +3. Revocation status via CRL or OCSP + +## RFC 3161 (Timestamping) + +RFC 3161 defines the Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP). Timestamps prove that a document existed in a specific state at a particular point in time. + +A timestamp token contains: + +- Hash of the signed data +- Time of issuance (from a trusted time source) +- Identifier of the Time Stamping Authority (TSA) +- TSA's digital signature + +Timestamps serve two purposes in document signing: + +1. **Proof of existence**: Demonstrates the document was signed before a certain time +2. **Signature validity extension**: Allows signature verification after the signing certificate expires + +Without a trusted timestamp, a signature can only be verified while the signing certificate remains valid. With a timestamp, the signature remains verifiable as long as the timestamp can be validated. + +## What Documenso Implements + +Documenso implements digital signatures with the following characteristics: + +- **PDF signatures**: Documents are signed using the PDF signature capabilities defined in ISO 32000 +- **X.509 certificates**: Signatures use X.509 certificates for signer identification +- **Timestamps**: RFC 3161 timestamps can be applied to signatures +- **Signature visualization**: Signed documents include visual signature representations + +For specific implementation details and configuration options, refer to the [signing certificates](/signing-certificates/overview) documentation. + +Self-hosted deployments can configure their own signing certificates and timestamp authorities to meet specific compliance requirements. + +## Related + +- [Legal Validity](/compliance/legal-validity) - Legal frameworks for electronic signatures +- [Signing Certificates Overview](/signing-certificates/overview) - Certificate configuration +- [Audit Log](/features/audit-log) - Document activity tracking diff --git a/apps/docs/content/docs/concepts/document-lifecycle.mdx b/apps/docs/content/docs/concepts/document-lifecycle.mdx new file mode 100644 index 000000000..b642c2138 --- /dev/null +++ b/apps/docs/content/docs/concepts/document-lifecycle.mdx @@ -0,0 +1,97 @@ +--- +title: Document Lifecycle +description: Track document progress through draft, pending, completed, and rejected states. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +## Document States + +A document can be in one of four states: + +| State | Description | +| ------------- | ----------------------------------------------------------------- | +| **Draft** | Document is being prepared and has not been sent | +| **Pending** | Document has been sent and is awaiting recipient actions | +| **Completed** | All recipients have completed their required actions | +| **Rejected** | A recipient has rejected the document (when rejection is enabled) | + +## How a Document Moves Through States + +```mermaid +flowchart LR + Draft -- Send --> Pending + Pending -- All recipients complete --> Completed + Pending -- Recipient rejects --> Rejected +``` + +## Draft + +When you upload a document or create one from a template, it starts in the **Draft** state. In this state, you can: + +- Add and remove recipients +- Assign roles to recipients (signer, approver, viewer, CC) +- Add, move, and configure fields +- Set signing order +- Configure document settings (expiration, reminders, rejection) +- Delete the document + +A draft document is only visible to you (the owner) and team members with appropriate permissions. Recipients cannot see or access the document until you send it. + +**Transition:** A draft becomes **Pending** when you send it to recipients. + +## Pending + +Once sent, a document enters the **Pending** state. Recipients receive email notifications with links to view and complete their assigned actions. + +While pending, you can: + +- View recipient progress +- Resend notifications to recipients +- Void the document (cancels all pending actions) + + + You cannot modify the document content, recipients, or fields while it is pending. + + +**Transitions:** + +- Becomes **Completed** when all recipients finish their required actions +- Becomes **Rejected** if any recipient rejects the document (requires rejection to be enabled) + +## Completed + +A document reaches the **Completed** state when all recipients have fulfilled their roles: + +- Signers have signed +- Approvers have approved +- Viewers have viewed (if view confirmation is required) + +At completion: + +- All parties receive a copy of the signed document +- The document is sealed with a digital certificate +- An audit log is attached showing all actions taken + + + Completed documents cannot be modified. You can download the signed PDF or view the audit trail. + + +## Rejected + +If you enable document rejection in settings, recipients can reject instead of signing. When any recipient rejects: + +- The document immediately moves to **Rejected** state +- Other pending recipients can no longer act on the document +- The document owner is notified + + + Rejected documents cannot be modified or reactivated. To proceed, you need to create a new + document. + + +## Related Concepts + +- [Recipient Roles](/docs/concepts/recipient-roles) - The different roles recipients can have +- [Field Types](/docs/concepts/field-types) - Fields you can add to documents +- [Signing Workflow](/docs/concepts/signing-workflow) - How the signing process works for recipients diff --git a/apps/docs/content/docs/concepts/field-types.mdx b/apps/docs/content/docs/concepts/field-types.mdx new file mode 100644 index 000000000..54516d90b --- /dev/null +++ b/apps/docs/content/docs/concepts/field-types.mdx @@ -0,0 +1,314 @@ +--- +title: Field Types +description: Placeholder types for capturing signatures, text, dates, and selections during signing. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +## Field Types Overview + +| Field Type | Description | Auto-filled | +| ---------- | ------------------------------------------------- | ----------- | +| Signature | Recipient's signature (drawn, typed, or uploaded) | No | +| Initials | Recipient's initials | No | +| Email | Recipient's email address | Yes | +| Name | Recipient's full name | Yes | +| Date | Date the field was completed | Yes | +| Text | Free-form text input | No | +| Number | Numeric input with optional validation | No | +| Radio | Single selection from a list of options | No | +| Checkbox | Multiple selections from a list of options | No | +| Dropdown | Single selection from a dropdown menu | No | + +## Signature + +![Signature field in the document editor](/document-signing/signature-field-document-editor-view.webp) + +The signature field captures the recipient's legally binding signature. Recipients can: + +- **Draw** their signature using a mouse or touchscreen +- **Type** their name and select a font style +- **Upload** an image of their signature + +### Configuration Options + +| Option | Description | +| --------- | -------------------------------------------------- | +| Required | Whether the field must be completed before signing | +| Read-only | Lock the field with a pre-filled value | +| Label | Display text shown above the field | + +### Common Use Cases + +- Contract execution +- Agreement acceptance +- Authorization approvals + +Each signer must have at least one Signature field assigned to them. + +## Initials + +The initials field captures abbreviated signatures, typically used to acknowledge individual pages or clauses. + +### Configuration Options + +| Option | Description | +| -------------- | -------------------------------------- | +| Required | Whether the field must be completed | +| Read-only | Lock the field with a pre-filled value | +| Label | Display text shown above the field | +| Text alignment | Left, center, or right alignment | + +### Common Use Cases + +- Page acknowledgment +- Clause acceptance +- Change or amendment approval + +## Email + +The email field displays the recipient's email address. This field is automatically populated with the email address used to send the signing request. + +### Configuration Options + +| Option | Description | +| -------------- | --------------------------------------------------- | +| Required | Whether the field must be completed | +| Read-only | Lock the field (recommended for auto-filled values) | +| Label | Display text shown above the field | +| Text alignment | Left, center, or right alignment | + +### Common Use Cases + +- Contact information sections +- Identity verification +- Record keeping + +## Name + +The name field captures the recipient's full name. When the recipient has a name on file, the field can be auto-populated. + +### Configuration Options + +| Option | Description | +| -------------- | -------------------------------------- | +| Required | Whether the field must be completed | +| Read-only | Lock the field with a pre-filled value | +| Label | Display text shown above the field | +| Text alignment | Left, center, or right alignment | + +### Common Use Cases + +- Signature blocks +- Party identification +- Contact details + +## Date + +The date field records when the recipient completed the field or signed the document. By default, it auto-fills with the current date. + +### Configuration Options + +| Option | Description | +| -------------- | -------------------------------------- | +| Required | Whether the field must be completed | +| Read-only | Lock the field with a pre-filled value | +| Label | Display text shown above the field | +| Text alignment | Left, center, or right alignment | + +### Common Use Cases + +- Signature date +- Agreement effective date +- Timestamp records + +## Text + +![Text field in the document editor](/document-signing/text-field-document-editor-view.webp) + +The text field accepts free-form text input from recipients. Use this for any information that doesn't fit other field types. + +### Configuration Options + +| Option | Description | +| --------------- | ------------------------------------------ | +| Required | Whether the field must be completed | +| Read-only | Lock the field with a pre-filled value | +| Label | Display text shown above the field | +| Placeholder | Hint text shown when the field is empty | +| Default value | Pre-filled text that recipients can modify | +| Character limit | Maximum number of characters allowed | +| Text alignment | Left, center, or right alignment | +| Line height | Spacing between lines of text | +| Letter spacing | Spacing between characters | + +### Rules + +- A field cannot be both required and read-only at the same time +- A read-only field must have a default text value (it cannot be empty) +- The field is inserted automatically into the document if there is a default text value +- The text field character count cannot exceed the character limit +- The signer cannot modify a read-only field + +### Common Use Cases + +- Address input +- Company names +- Job titles +- Custom information + +## Number + +The number field accepts numeric input with optional validation constraints. + +### Configuration Options + +| Option | Description | +| -------------- | -------------------------------------------- | +| Required | Whether the field must be completed | +| Read-only | Lock the field with a pre-filled value | +| Label | Display text shown above the field | +| Placeholder | Hint text shown when the field is empty | +| Default value | Pre-filled number that recipients can modify | +| Minimum value | Lowest allowed number | +| Maximum value | Highest allowed number | +| Number format | Display format for the number | +| Text alignment | Left, center, or right alignment | + +### Rules + +- The value must be a number +- A field cannot be both required and read-only at the same time +- A read-only field must have a default number value +- If a default number and a maximum value are set, the default must be less than the maximum +- If a default number and a minimum value are set, the default must be greater than the minimum +- The value must match the number format if a number format is set + +### Common Use Cases + +- Quantities +- Pricing +- Phone numbers +- Employee IDs + +## Radio + +The radio field presents a list of options where the recipient can select exactly one. + +### Configuration Options + +| Option | Description | +| ----------------- | ---------------------------------------- | +| Required | Whether a selection must be made | +| Read-only | Lock the field with a pre-selected value | +| Label | Display text shown above the field | +| Options | List of selectable values | +| Default selection | Pre-selected option | +| Direction | Vertical or horizontal layout | + +### Rules + +- A field cannot be both required and read-only at the same time +- A read-only field must have at least one option +- The field auto-signs if there is a default value +- The signer cannot select a value that's not in the options list +- Only one option can be selected at a time + +### Common Use Cases + +- Yes/No questions +- Single-choice selections +- Status indicators +- Plan or tier selection + +## Checkbox + +![Checkbox field in the document editor](/document-signing/checkbox-field-document-editor-view.webp) + +The checkbox field presents a list of options where the recipient can select multiple items. + +### Configuration Options + +| Option | Description | +| ------------------ | ------------------------------------------- | +| Required | Whether at least one selection must be made | +| Read-only | Lock the field with pre-selected values | +| Label | Display text shown above the field | +| Options | List of selectable values | +| Default selections | Pre-selected options | +| Validation rule | Rules for minimum/maximum selections | +| Direction | Vertical or horizontal layout | + +### Rules + +- A field cannot be both required and read-only at the same time +- A read-only field must have at least one checked option +- The field auto-signs if there are default values +- The validation rule enforces selection counts: "At least", "At most", or "Exactly" a specified number of options +- The signer cannot select a value that's not in the options list + +### Common Use Cases + +- Terms and conditions acceptance +- Multiple acknowledgments +- Feature selection +- Preference lists + +## Dropdown + +![Dropdown field in the document editor](/document-signing/dropdown-field-document-editor-view.webp) + +The dropdown field presents a list of options in a collapsible menu. Recipients select one option from the list. + +### Configuration Options + +| Option | Description | +| ------------- | ---------------------------------------- | +| Required | Whether a selection must be made | +| Read-only | Lock the field with a pre-selected value | +| Label | Display text shown above the field | +| Options | List of selectable values | +| Default value | Pre-selected option | + +### Rules + +- A field cannot be both required and read-only at the same time +- A read-only field must have a default value +- The default value must be one of the options +- The field auto-signs if there is a default value +- The signer cannot select a value that's not in the options list + +### Common Use Cases + +- Country or state selection +- Department selection +- Category classification +- Status selection + +## Common Configuration Options + +All field types share these base configuration options: + +| Option | Description | Default | +| --------- | --------------------------------------------------- | ------- | +| Required | Recipient must complete the field to finish signing | `false` | +| Read-only | Field value cannot be changed by the recipient | `false` | +| Label | Text displayed above or near the field | None | +| Font size | Size of the text in the field (8-96px) | 12px | + +## Validation + +Fields validate input based on their type and configuration: + +- **Required fields** must be completed before the recipient can finish signing +- **Read-only fields** display pre-filled values that cannot be modified +- **Number fields** validate against minimum and maximum values when configured +- **Checkbox fields** can enforce a minimum or maximum number of selections + +If validation fails, the recipient sees an error message and must correct the input before proceeding. + +## Related + +- [Add Fields to Documents](/docs/users/documents/add-fields) - Learn how to place fields on your documents +- [Recipient Roles](/docs/concepts/recipient-roles) - Understand who can be assigned fields +- [Fields API](/docs/developers/api/fields) - Programmatically add fields via the API diff --git a/apps/docs/content/docs/concepts/index.mdx b/apps/docs/content/docs/concepts/index.mdx new file mode 100644 index 000000000..4b0b1453d --- /dev/null +++ b/apps/docs/content/docs/concepts/index.mdx @@ -0,0 +1,70 @@ +--- +title: Concepts +description: Foundational concepts behind document signing, recipient roles, field types, and certificates. +--- + +## Core Concepts + + + + + + + + + +--- + +## How These Concepts Apply + +These concepts work consistently across all ways you interact with Documenso: + +- **Web application**: When you create documents in the UI, you'll select recipient roles, add fields, and track documents through their lifecycle states. + +- **API integration**: The same concepts map directly to API endpoints. Documents have status fields, recipients have role properties, and fields have type configurations. + +- **Self-hosting**: The signing certificate concept becomes particularly relevant when you deploy your own instance and configure your own certificates for document signing. + +Understanding these fundamentals will make the rest of the documentation easier to follow. + +--- + +## Related Sections + + + + + + diff --git a/apps/docs/content/docs/concepts/meta.json b/apps/docs/content/docs/concepts/meta.json new file mode 100644 index 000000000..925998a98 --- /dev/null +++ b/apps/docs/content/docs/concepts/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Concepts", + "pages": [ + "document-lifecycle", + "recipient-roles", + "field-types", + "signing-workflow", + "signing-certificates" + ] +} diff --git a/apps/docs/content/docs/concepts/recipient-roles.mdx b/apps/docs/content/docs/concepts/recipient-roles.mdx new file mode 100644 index 000000000..0841423c2 --- /dev/null +++ b/apps/docs/content/docs/concepts/recipient-roles.mdx @@ -0,0 +1,171 @@ +--- +title: Recipient Roles +description: Signers, approvers, viewers, assistants, and CC recipients. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + +## Role Overview + +| Role | Action Required | Can Sign | Description | +| --------- | --------------- | -------- | ---------------------------------------- | +| Signer | Yes | Yes | Must sign the document | +| Approver | Yes | Optional | Must approve the document | +| Viewer | Yes | No | Must view the document | +| Assistant | Yes | No | Can pre-fill fields for other recipients | +| CC | No | No | Receives a copy after completion | + +## Role Details + + + + +Signers are the primary recipients of a document. They must complete all signature fields assigned to them before the document can be finalized. + +**What they can do:** + +- Sign signature fields assigned to them +- Fill out any other fields assigned to them (text, date, checkbox, etc.) +- Download the document after signing + +**What they cannot do:** + +- Sign on behalf of other recipients +- Modify fields assigned to other recipients + +**When to use this role:** + +- Contracts requiring a legally binding signature +- Agreements where the recipient must formally consent +- Any document that requires a signature to be valid + + + + +Approvers must review and approve the document, but signing is optional. The document cannot be completed until all approvers have given their approval. + +**What they can do:** + +- Approve or reject the document +- Optionally add a signature if signature fields are assigned +- Fill out fields assigned to them +- Download the document after approval + +**What they cannot do:** + +- Complete the document without explicitly approving it +- Modify fields assigned to other recipients + +**When to use this role:** + +- Documents requiring manager or supervisor approval +- Workflows where review is required before final signatures +- Compliance processes requiring sign-off from multiple parties + + + + +Viewers must acknowledge that they have viewed the document. They cannot add signatures but must confirm they have reviewed the content. + +**What they can do:** + +- View the complete document +- Confirm they have viewed it +- Download the document after viewing + +**What they cannot do:** + +- Sign the document +- Fill out fields (no fields can be assigned to viewers) +- Modify the document in any way + +**When to use this role:** + +- Informational documents that require acknowledgment +- Policies or disclosures that recipients must review +- Documents where you need proof of receipt without a signature + + + + +Assistants can prepare the document by pre-filling fields on behalf of other signers. This role is only available when sequential signing is enabled. + +**What they can do:** + +- Pre-fill suggested values in fields assigned to later signers +- Help prepare the document for the actual signers +- Fill out any fields specifically assigned to them + +**What they cannot do:** + +- Sign on behalf of other recipients +- Submit the document as complete +- Be used in parallel signing mode + +**When to use this role:** + +- Administrative staff preparing documents for executives to sign +- Workflows where one person gathers information and another signs +- Situations where you want to reduce the burden on the final signer + + + The Assistant role requires sequential signing to be enabled. You cannot use this role when + recipients sign in parallel. + + + + + +CC recipients receive a copy of the completed document but do not need to take any action. They are notified when the document is fully signed. + +**What they can do:** + +- Receive a copy of the completed document +- Download the signed document + +**What they cannot do:** + +- Sign or approve the document +- View the document before it is completed +- Take any action that affects document completion + +**When to use this role:** + +- Keeping stakeholders informed about signed agreements +- Sending copies to legal or compliance teams +- Archiving completed documents with relevant parties + + + + +## Signing Order + +You can control the sequence in which recipients receive and act on a document by enabling signing order. + + + + +All recipients receive the document simultaneously and can act in any order. The document is completed when all required recipients have finished their actions. + + + + +Recipients receive the document one at a time, in the order you specify. Each recipient must complete their action before the next recipient is notified. + +To enable sequential signing: + +1. When adding recipients, check the "Enable signing order" option +2. Assign an order number to each recipient +3. Recipients with the same order number can act simultaneously +4. The document proceeds to the next order number only when all recipients at the current level have completed their actions + +Sequential signing is required if you want to use the Assistant role. + + + + +## Related + +- [Add Recipients](/users/documents/add-recipients) - How to add recipients to a document +- [Field Types](/concepts/field-types) - Learn about the different field types you can assign to recipients diff --git a/apps/docs/content/docs/concepts/signing-certificates.mdx b/apps/docs/content/docs/concepts/signing-certificates.mdx new file mode 100644 index 000000000..7eb3e407e --- /dev/null +++ b/apps/docs/content/docs/concepts/signing-certificates.mdx @@ -0,0 +1,123 @@ +--- +title: Signing Certificates +description: Documenso digitally signs completed documents using X.509 certificates, providing cryptographic proof of authenticity and integrity. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + +## How Documenso Signs Documents + +Documenso applies a digital signature to the PDF when all recipients complete their actions. + +{/* prettier-ignore */} + + +### Create hash + +Creates a cryptographic hash of the document content. + + + + +### Sign the hash + +Signs the hash using the certificate's private key. + + + + +### Embed signature + +Embeds the signature and certificate information into the PDF. + + + + +The signature is applied at the platform level, not by individual signers. Each signer's actions (signature image, text, checkboxes) are recorded and sealed together in the final signed document. + +## What the Signature Proves + +The digital signature provides two guarantees: + +| Guarantee | Description | +| ---------------- | -------------------------------------------------------------------------- | +| **Integrity** | The document has not been altered since signing | +| **Authenticity** | The document was signed by the certificate holder (the Documenso instance) | + +If anyone modifies the PDF after signing, the signature becomes invalid. PDF readers will display a warning that the document has been changed. + +## Timestamps + +Documenso can include a trusted timestamp from a Time Stamping Authority (TSA) in the signature. This proves when the document was signed, independent of the signer's system clock. Timestamps are important for: + +- Legal evidence of when signing occurred +- Long-term validation (LTV) of signatures +- Compliance with archival requirements + +## Viewing the Signature in PDF Readers + +You can verify a signed document's signature in any PDF reader that supports digital signatures. + + + + +1. Open the signed PDF +2. Click the signature panel on the left, or click on a signature field +3. View certificate details, signing time, and validation status + + + + +Preview, Foxit, and other PDF readers also display signature information, though the interface varies. Look for a signatures or security panel in the application menu. + + + + +The signature panel shows who signed (certificate subject), when it was signed, whether the document has been modified, and certificate trust status. + +## Certificate Trust and Validation + +PDF readers validate signatures against their list of trusted Certificate Authorities (CAs). You may see different validation results depending on the certificate type: + +| Certificate Type | Validation Result | +| ---------------- | ---------------------------------------------------------------------- | +| **CA-issued** | Green checkmark in Adobe if the CA is on the Adobe Approved Trust List | +| **Self-signed** | Warning that the certificate is not from a trusted source | + + + A self-signed certificate still provides integrity verification. The document cannot be modified without invalidating the signature. The warning only indicates that a third-party CA has not verified the certificate issuer's identity. + +For most use cases, self-signed certificates are sufficient. The signature still proves the document came from your Documenso instance and has not been tampered with. + + + +## Using Custom Certificates + +If you self-host Documenso, you can use your own signing certificate. + + + + +Free and suitable for most use cases. The signature still proves document integrity and authenticity. + +You may see a warning in PDF readers that the certificate is not from a trusted source, but the document cannot be modified without invalidating the signature. + + + + +Provides trusted validation in PDF readers (e.g. green checkmark in Adobe) when the CA is on the Adobe Approved Trust List. + +Required for some compliance scenarios where third-party verification of the certificate issuer is needed. + + + + +See [Signing Certificate Configuration](/docs/self-hosting/configuration/signing-certificate) for setup instructions. + +## Related + +- [Signature Levels](/docs/compliance/signature-levels) - Simple, Advanced, and Qualified electronic signatures +- [Standards and Regulations](/docs/compliance/standards) - ESIGN, eIDAS, and other compliance frameworks +- [Signing Certificate Configuration](/docs/self-hosting/configuration/signing-certificate) - Self-hosting certificate setup diff --git a/apps/docs/content/docs/concepts/signing-workflow.mdx b/apps/docs/content/docs/concepts/signing-workflow.mdx new file mode 100644 index 000000000..adade3717 --- /dev/null +++ b/apps/docs/content/docs/concepts/signing-workflow.mdx @@ -0,0 +1,260 @@ +--- +title: Signing Workflow +description: The complete process from preparing a document to collecting signatures and sealing the final PDF. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + +## Workflow Overview + +A typical signing workflow follows these steps: + +```mermaid +flowchart LR + A[Prepare Document] --> B[Send Document] --> C[Notify Recipients] --> D[Recipients Sign] --> E[Seal & Finalize] --> F[Document Completed] +``` + +1. **Prepare** - Upload the document, add recipients, and place fields +2. **Send** - Distribute the document to recipients +3. **Notify** - Recipients receive signing requests +4. **Sign** - Recipients complete their assigned fields +5. **Complete** - Document is sealed and distributed to all parties + +{/* prettier-ignore */} + + +### Prepare the document + +Document preparation involves three main tasks: uploading, adding recipients, and placing fields. + +**Upload the document** + +Start by uploading a PDF. You can upload directly: + +- from your device +- create from an existing template +- or duplicate a previously sent document. + +Once uploaded, the document enters the **Draft** state. + +**Add recipients** + +Add the people who need to interact with the document. Each recipient needs: + +- an email address +- a name +- a role + +Available roles are: + +| Role | Purpose | +| --------- | --------------------------------------------------- | +| Signer | Must sign the document | +| Approver | Must approve (signature optional) | +| Viewer | Must confirm they viewed the document | +| Assistant | Pre-fills fields for other recipients | +| CC | Receives a copy after completion (no action needed) | + +**Place fields** + +Add fields that recipients will complete. At minimum, each signer needs one signature field. You can also add: + +- name +- email +- date +- text +- number +- dropdown +- checkbox +- radio +- initials fields + +Each field is assigned to a specific recipient, indicated by color coding in the editor. + + + The document cannot be sent until every signer has at least one signature field assigned to them. + + + + + +### Send the document + +When the document is ready, you send it to recipients. You have two distribution options: + + + + +Recipients receive an email notification with a link to sign. + +You can customize the email: + +- subject line +- message body with personalized variables +- reply-to address for recipient responses + + + + +Generate signing links without sending emails. + +Use this when you want to: + +- send links via SMS or messaging apps +- embed links in your own application +- control notification timing yourself + + + + +After sending, the document moves from **Draft** to **Pending** status. + + + + +### Recipients are notified + +When you send a document via email, each recipient receives a notification containing: + +- the document title +- your name and email (or team name) +- your custom message (or a role-specific default) +- a unique signing link + +The signing link is specific to each recipient and cannot be used by others. Links remain active until the document is completed, deleted, or expired. + +**Signing order** + +By default, all recipients are notified simultaneously (parallel signing). If you enable sequential signing, only recipients in the first signing position receive notifications initially. When they complete their actions, the next group is notified. + +This continues until all recipients have been notified and completed their actions. + + + + +### Recipients sign + +When a recipient clicks their signing link, they see the document with their assigned fields highlighted. The signing experience depends on their role: + + + + +Signers must complete all required fields before they can finish. For signature fields, they can: + +- draw a signature using mouse or touchscreen +- type their name and select a font style +- upload an image of their existing signature + +After completing all fields, the signer clicks a button to submit. They receive a confirmation and can download a copy of the document showing their completed fields. + + + + +Approvers review the document and must explicitly approve it. If signature fields are assigned, they can optionally sign. + +The document cannot proceed until all approvers have given approval. + + + + +Viewers see the full document and must confirm they have viewed it. They cannot add signatures or modify any content. + + + + +**Authentication** + +You can require recipients to verify their identity before signing through: + +- email verification (confirm access to the email address) +- access code (enter a code you provide separately) +- passkey (authenticate with a hardware or software passkey) + + + + +### Document is completed + +Once all recipients with required actions have completed them, the document is finalized. + +| Aspect | Description | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Sealing** | The completed document is sealed with a digital certificate that cryptographically signs the PDF, prevents modification without detection, and provides proof of authenticity. | +| **Audit trail** | An audit log is generated and can be attached to the document. It records when the document was created and sent, when each recipient viewed and signed, IP addresses and timestamps for each action, and any authentication methods used. | +| **Distribution** | All parties receive the completed document: signers, approvers, and viewers receive their copy via email; CC recipients receive their first notification with the completed document; the document owner can download the signed PDF from their dashboard. | + + + + +## Workflow Variations + +Documenso supports several workflow variations to handle different signing scenarios. + + + + +When recipients must sign in a specific order, enable signing order: + +1. Assign each recipient a signing position (1, 2, 3, etc.) +2. Recipients at position 1 sign first +3. Recipients at position 2 are notified only after position 1 completes +4. Multiple recipients can share the same position to sign in parallel within that step + +Use sequential signing when later signers: + +- need to see what earlier signers entered +- approval must happen before final signatures +- company policy requires a specific signing order + + + + +Combine approver and signer roles to create approval workflows: + +1. Add approvers at signing position 1 +2. Add signers at signing position 2 +3. Approvers review and approve first +4. Signers are notified only after approval is complete + + + If an approver rejects the document (when rejection is enabled), the workflow stops and signers + are never notified. + + + + + +Use assistants to have one person prepare the document for another: + +1. Add an assistant at signing position 1 +2. Add the final signer at signing position 2 +3. The assistant pre-fills fields with suggested values +4. The signer reviews and completes their signature + +This is useful when administrative staff prepare documents for executives or when gathering information from one person while another signs. + + + The Assistant role is only available when sequential signing is enabled. + + + + + +For high-volume signing scenarios, you can create direct links that allow anyone to sign without receiving an individual invitation: + +- Generate a public signing link for a document or template +- Share the link on your website, in emails, or through other channels +- Each person who accesses the link creates their own signing instance +- Useful for waivers, consent forms, and public agreements + + + + +## Related Concepts + +- [Document Lifecycle](/docs/concepts/document-lifecycle) - Understanding document states from draft to completion +- [Recipient Roles](/docs/concepts/recipient-roles) - Detailed explanation of each role type +- [Field Types](/docs/concepts/field-types) - All available field types and their configuration options +- [Signing Certificates](/docs/concepts/signing-certificates) - How documents are digitally sealed diff --git a/apps/docs/content/docs/developers/api/developer-mode.mdx b/apps/docs/content/docs/developers/api/developer-mode.mdx new file mode 100644 index 000000000..f5bd2e871 --- /dev/null +++ b/apps/docs/content/docs/developers/api/developer-mode.mdx @@ -0,0 +1,37 @@ +--- +title: Developer Mode +description: Advanced development tools for debugging field coordinates and integrating with the Documenso API. +--- + +## Overview + +Developer mode provides additional tools and features to help you integrate and debug Documenso. + +## Field Coordinates + +Field coordinates represent the position of a field in a document. They are returned in the `pageX`, `pageY`, `width` and `height` properties of the field. + +To enable field coordinates, add the `devmode=true` query parameter to the editor URL. + +```bash +# Legacy editor + +https://app.documenso.com/t//documents//legacy_editor?devmode=true +``` + +![Field Coordinates Legacy Editor](/developer-mode/field-coordinates-legacy-editor.webp) + +```bash +# New editor + +https://app.documenso.com/t//documents//edit?step=addFields&devmode=true +``` + +![Field Coordinates New Editor](/developer-mode/field-coordinates-new-editor.webp) + +--- + +## See Also + +- [Fields API](/docs/developers/api/fields) - Create and position fields via API +- [Field Types](/docs/concepts/field-types) - Detailed field type reference diff --git a/apps/docs/content/docs/developers/api/documents.mdx b/apps/docs/content/docs/developers/api/documents.mdx new file mode 100644 index 000000000..05433cc3c --- /dev/null +++ b/apps/docs/content/docs/developers/api/documents.mdx @@ -0,0 +1,815 @@ +--- +title: Documents API +description: Create, manage, and send documents for signing via the API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + + This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, + see the [OpenAPI Reference](https://openapi.documenso.com). + + +## Overview + +[Documents](/docs/users/documents) (called "envelopes" in the API) are the core resource in Documenso. You can: + +1. create documents with recipients and fields +2. send them for signing +3. track their status +4. retrieve the completed PDFs + +Each document contains one or more PDF files, a list of recipients, and the fields they need to fill. + +## Document Object + +A document object contains the following properties: + +| Property | Type | Description | +| --------------- | -------------- | -------------------------------------------------------------- | +| `id` | string | Unique identifier (e.g., `envelope_abc123`) | +| `type` | string | `DOCUMENT` or `TEMPLATE` | +| `status` | string | Current status: `DRAFT`, `PENDING`, `COMPLETED`, or `REJECTED` | +| `title` | string | Document title | +| `source` | string | How the document was created: `DOCUMENT`, `TEMPLATE`, `API` | +| `visibility` | string | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE` | +| `externalId` | string \| null | Your custom identifier for the document | +| `createdAt` | string | ISO 8601 timestamp | +| `updatedAt` | string | ISO 8601 timestamp | +| `completedAt` | string \| null | Timestamp when all recipients completed signing | +| `deletedAt` | string \| null | Timestamp if soft-deleted | +| `recipients` | array | List of recipients and their signing status | +| `fields` | array | Signature and form fields on the document | +| `envelopeItems` | array | PDF files attached to the document | +| `documentMeta` | object | Email settings, redirect URL, signing options | + +### Example Document Object + +```json +{ + "id": "envelope_abc123xyz", + "type": "DOCUMENT", + "status": "PENDING", + "source": "API", + "visibility": "EVERYONE", + "title": "Service Agreement", + "externalId": "contract-2025-001", + "createdAt": "2025-01-15T10:30:00.000Z", + "updatedAt": "2025-01-15T10:35:00.000Z", + "completedAt": null, + "deletedAt": null, + "recipients": [ + { + "id": 1, + "email": "signer@example.com", + "name": "John Smith", + "role": "SIGNER", + "signingStatus": "NOT_SIGNED", + "signingOrder": 1 + } + ], + "fields": [ + { + "id": "field_123", + "type": "SIGNATURE", + "page": 1, + "positionX": 10, + "positionY": 80, + "width": 30, + "height": 5, + "recipientId": 1 + } + ], + "envelopeItems": [ + { + "id": "envelope_item_xyz", + "title": "contract.pdf", + "order": 1 + } + ], + "documentMeta": { + "subject": "Please sign this document", + "message": "Hi, please review and sign this agreement.", + "timezone": "America/New_York", + "redirectUrl": "https://example.com/thank-you" + } +} +``` + +## List Documents + +Retrieve a paginated list of documents. + +``` +GET /envelope +``` + +### Query Parameters + +| Parameter | Type | Description | +| ------------------ | ------- | ------------------------------------------------------------- | +| `page` | integer | Page number (default: 1) | +| `perPage` | integer | Results per page (default: 10, max: 100) | +| `type` | string | Filter by `DOCUMENT` or `TEMPLATE` | +| `status` | string | Filter by status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` | +| `source` | string | Filter by creation source | +| `folderId` | string | Filter by folder ID | +| `orderByColumn` | string | Sort field (only `createdAt` supported) | +| `orderByDirection` | string | Sort direction: `asc` or `desc` (default: `desc`) | + +### Code Examples + + + +```bash +# List all documents +curl -X GET "https://app.documenso.com/api/v2/envelope" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" + +# Filter by status and paginate + +curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING&page=1&perPage=20" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" + +# List only documents (not templates) + +curl -X GET "https://app.documenso.com/api/v2/envelope?type=DOCUMENT" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" + +```` + + +```typescript +const API_TOKEN = process.env.DOCUMENSO_API_TOKEN; +const BASE_URL = 'https://app.documenso.com/api/v2'; + +// List all documents +const response = await fetch(`${BASE_URL}/envelope`, { + method: 'GET', + headers: { + Authorization: API_TOKEN, + }, +}); + +const { data, pagination } = await response.json(); +console.log(`Found ${pagination.totalItems} documents`); + +// Filter by status +const pendingResponse = await fetch( + `${BASE_URL}/envelope?status=PENDING&page=1&perPage=20`, + { + method: 'GET', + headers: { + Authorization: API_TOKEN, + }, + } +); + +const pendingDocs = await pendingResponse.json(); +```` + + + + +### Response + +```json +{ + "data": [ + { + "id": "envelope_abc123", + "type": "DOCUMENT", + "status": "PENDING", + "title": "Service Agreement", + "createdAt": "2025-01-15T10:30:00.000Z", + "updatedAt": "2025-01-15T10:35:00.000Z", + "recipients": [ + { + "id": 1, + "email": "signer@example.com", + "name": "John Smith", + "role": "SIGNER", + "signingStatus": "NOT_SIGNED" + } + ] + } + ], + "pagination": { + "page": 1, + "perPage": 10, + "totalPages": 5, + "totalItems": 42 + } +} +``` + +--- + +## Get Document + +Retrieve a single document by ID. + +``` +GET /envelope/{envelopeId} +``` + +### Path Parameters + +| Parameter | Type | Description | +| ------------ | ------ | ----------------------------------------- | +| `envelopeId` | string | The document ID (e.g., `envelope_abc123`) | + +### Code Examples + + + +```bash +curl -X GET "https://app.documenso.com/api/v2/envelope/envelope_abc123" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" +``` + + +```typescript +const envelopeId = 'envelope_abc123'; + +const response = await fetch(`https://app.documenso.com/api/v2/envelope/${envelopeId}`, { + method: 'GET', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + }, +}); + +const document = await response.json(); +console.log(document.title, document.status); +```` + + + +### Response + +Returns the full document object including recipients, fields, and envelope items. + +```json +{ + "id": "envelope_abc123", + "type": "DOCUMENT", + "status": "PENDING", + "title": "Service Agreement", + "recipients": [...], + "fields": [...], + "envelopeItems": [...], + "documentMeta": {...} +} +```` + +--- + +## Create Document + +Create a new document with optional recipients and fields in a single request. + +``` +POST /envelope/create +Content-Type: multipart/form-data +``` + +### Request Body + +The request uses `multipart/form-data` with two parts: + +| Part | Type | Description | +| --------- | ------- | ---------------------- | +| `payload` | JSON | Document configuration | +| `files` | File(s) | One or more PDF files | + +### Payload Schema + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | ------------------------------------------- | +| `type` | string | Yes | Must be `DOCUMENT` | +| `title` | string | Yes | Document title | +| `externalId` | string | No | Your custom identifier | +| `visibility` | string | No | `EVERYONE`, `ADMIN`, or `MANAGER_AND_ABOVE` | +| `folderId` | string | No | Folder ID to create the document in | +| `recipients` | array | No | Recipients with optional fields | +| `meta` | object | No | Email subject, message, redirect URL, etc. | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/create" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: multipart/form-data" \ + -F 'payload={ + "type": "DOCUMENT", + "title": "Service Agreement", + "externalId": "contract-2025-001", + "recipients": [ + { + "email": "signer@example.com", + "name": "John Smith", + "role": "SIGNER", + "fields": [ + { + "identifier": 0, + "type": "SIGNATURE", + "page": 1, + "positionX": 10, + "positionY": 80, + "width": 30, + "height": 5 + }, + { + "identifier": 0, + "type": "DATE", + "page": 1, + "positionX": 50, + "positionY": 80, + "width": 20, + "height": 3 + } + ] + } + ], + "meta": { + "subject": "Please sign this agreement", + "message": "Hi John, please review and sign the attached agreement.", + "redirectUrl": "https://example.com/thank-you" + } + }' \ + -F "files=@./contract.pdf;type=application/pdf" +``` + + +```typescript +import fs from 'fs'; +import FormData from 'form-data'; + +const form = new FormData(); + +const payload = { + type: 'DOCUMENT', + title: 'Service Agreement', + externalId: 'contract-2025-001', + recipients: [ + { + email: 'signer@example.com', + name: 'John Smith', + role: 'SIGNER', + fields: [ + { + identifier: 0, + type: 'SIGNATURE', + page: 1, + positionX: 10, + positionY: 80, + width: 30, + height: 5, + }, + { + identifier: 0, + type: 'DATE', + page: 1, + positionX: 50, + positionY: 80, + width: 20, + height: 3, + }, + ], + }, + ], + meta: { + subject: 'Please sign this agreement', + message: 'Hi John, please review and sign the attached agreement.', + redirectUrl: 'https://example.com/thank-you', + }, +}; + +form.append('payload', JSON.stringify(payload)); +form.append('files', fs.createReadStream('./contract.pdf'), { + contentType: 'application/pdf', +}); + +const response = await fetch('https://app.documenso.com/api/v2/envelope/create', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + }, + body: form, +}); + +const { id } = await response.json(); +console.log('Created document:', id); +```` + + + +### Response + +```json +{ + "id": "envelope_abc123xyz" +} +```` + +### Field Positioning + +Field positions use percentage values (0-100) relative to the PDF page: + +| Parameter | Description | +| ------------ | ---------------------------------------------------------- | +| `positionX` | Horizontal position from left edge (0 = left, 100 = right) | +| `positionY` | Vertical position from top edge (0 = top, 100 = bottom) | +| `width` | Field width as percentage of page width | +| `height` | Field height as percentage of page height | +| `page` | Page number (1-indexed) | +| `identifier` | File index (0 for first file) or filename | + +### Field Types + +| Type | Description | +| ----------- | --------------------------- | +| `SIGNATURE` | Signature field | +| `INITIALS` | Initials field | +| `NAME` | Auto-filled recipient name | +| `EMAIL` | Auto-filled recipient email | +| `DATE` | Signing date | +| `TEXT` | Free text input | +| `NUMBER` | Numeric input | +| `CHECKBOX` | Checkbox selection | +| `RADIO` | Radio button group | +| `DROPDOWN` | Dropdown selection | + +### Recipient Roles + +| Role | Description | +| ---------- | ----------------------------------------- | +| `SIGNER` | Must sign the document | +| `APPROVER` | Must approve before signers can sign | +| `CC` | Receives a copy but doesn't sign | +| `VIEWER` | Can view the document but takes no action | + +--- + +## Update Document + +Update a document's properties. Only works on documents in `DRAFT` status. + +``` +POST /envelope/update +``` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | ------------------------------------ | +| `envelopeId` | string | Yes | Document ID | +| `data` | object | No | Document properties to update | +| `meta` | object | No | Email and signing settings to update | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/update" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "envelope_abc123", + "data": { + "title": "Updated Service Agreement", + "externalId": "contract-2025-001-v2" + }, + "meta": { + "subject": "Updated: Please sign this agreement", + "redirectUrl": "https://example.com/signed" + } + }' +``` + + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope/update', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'envelope_abc123', + data: { + title: 'Updated Service Agreement', + externalId: 'contract-2025-001-v2', + }, + meta: { + subject: 'Updated: Please sign this agreement', + redirectUrl: 'https://example.com/signed', + }, + }), +}); + +const document = await response.json(); + +``` + + + +--- + +## Send Document + +Send a document to recipients for signing. This changes the status from `DRAFT` to `PENDING`. + +``` + +POST /envelope/distribute + +```` + +### Request Body + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `envelopeId` | string | Yes | Document ID | +| `meta` | object | No | Override email settings for this send | + +### Code Examples + + + +```bash +# Basic send +curl -X POST "https://app.documenso.com/api/v2/envelope/distribute" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "envelope_abc123" + }' + +# Send with custom email settings +curl -X POST "https://app.documenso.com/api/v2/envelope/distribute" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "envelope_abc123", + "meta": { + "subject": "Action Required: Sign Agreement", + "message": "Please sign this document by end of day.", + "timezone": "America/New_York" + } + }' +```` + + + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope/distribute', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'envelope_abc123', + meta: { + subject: 'Action Required: Sign Agreement', + message: 'Please sign this document by end of day.', + }, + }), +}); + +const { id, recipients } = await response.json(); + +// Recipients now include signing URLs +recipients.forEach((r) => { + console.log(`${r.email}: ${r.signingUrl}`); +}); + +```` + + + +### Response + +The response includes signing URLs for each recipient: + +```json +{ + "success": true, + "id": "envelope_abc123", + "recipients": [ + { + "id": 1, + "name": "John Smith", + "email": "signer@example.com", + "token": "abc123xyz", + "role": "SIGNER", + "signingOrder": 1, + "signingUrl": "https://app.documenso.com/sign/abc123xyz" + } + ] +} +```` + + + Use the `signingUrl` to redirect recipients directly to the signing page, or let them use the + email link. + + +--- + +## Delete Document + +Delete a document. Completed documents cannot be deleted. + +``` +POST /envelope/delete +``` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | ----------- | +| `envelopeId` | string | Yes | Document ID | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/delete" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "envelope_abc123" + }' +``` + + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope/delete', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'envelope_abc123', + }), +}); + +const { success } = await response.json(); + +```` + + + +### Response + +```json +{ + "success": true +} +```` + +--- + +## Get Multiple Documents + +Retrieve multiple documents by their IDs in a single request. + +``` +POST /envelope/get-many +``` + +### Request Body + +| Field | Type | Required | Description | +| ------------- | ----- | -------- | --------------------- | +| `envelopeIds` | array | Yes | Array of document IDs | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/get-many" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeIds": ["envelope_abc123", "envelope_def456", "envelope_ghi789"] + }' +``` + + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope/get-many', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeIds: ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'], + }), +}); + +const documents = await response.json(); + +```` + + + +--- + +## Document Statuses + +| Status | Description | +| --- | --- | +| `DRAFT` | Document is being prepared. Recipients have not been notified. | +| `PENDING` | Document has been sent. Waiting for recipients to sign. | +| `COMPLETED` | All recipients have signed. Document is sealed. | +| `REJECTED` | A recipient rejected the document. | + +### Status Transitions + +```mermaid +flowchart LR + DRAFT --> PENDING --> COMPLETED + PENDING --> REJECTED +``` + +- **DRAFT to PENDING**: Call the distribute endpoint +- **PENDING to COMPLETED**: All recipients complete their signing +- **PENDING to REJECTED**: A recipient rejects the document + + + You cannot modify recipients or fields after a document moves to `PENDING` status. + + +--- + +## Filtering and Pagination + +### Pagination Parameters + +| Parameter | Type | Default | Description | +| --------- | ------- | ------- | --------------------------- | +| `page` | integer | 1 | Page number | +| `perPage` | integer | 10 | Results per page (max: 100) | + +### Filter Parameters + +| Parameter | Values | Description | +| ---------- | ------------------------------------------- | ------------------------- | +| `type` | `DOCUMENT`, `TEMPLATE` | Filter by envelope type | +| `status` | `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` | Filter by status | +| `source` | `DOCUMENT`, `TEMPLATE`, `API` | Filter by creation source | +| `folderId` | string | Filter by folder | + +### Sorting + +| Parameter | Values | Description | +| ------------------ | ------------- | -------------------------------- | +| `orderByColumn` | `createdAt` | Field to sort by | +| `orderByDirection` | `asc`, `desc` | Sort direction (default: `desc`) | + +### Example: Fetch All Pending Documents + +```typescript +async function getAllPendingDocuments() { + const documents = []; + let page = 1; + let hasMore = true; + + while (hasMore) { + const response = await fetch( + `https://app.documenso.com/api/v2/envelope?status=PENDING&page=${page}&perPage=100`, + { + headers: { Authorization: 'api_xxxxxxxxxxxxxxxx' }, + }, + ); + + const { data, pagination } = await response.json(); + documents.push(...data); + + hasMore = page < pagination.totalPages; + page++; + } + + return documents; +} +``` + +--- + +## See Also + +- [Recipients API](/docs/developers/api/recipients) - Add and manage document recipients +- [Fields API](/docs/developers/api/fields) - Add signature and form fields +- [Templates API](/docs/developers/api/templates) - Create reusable document templates +- [Webhooks](/docs/developers/webhooks) - Get notified when documents are signed diff --git a/apps/docs/content/docs/developers/api/fields.mdx b/apps/docs/content/docs/developers/api/fields.mdx new file mode 100644 index 000000000..6d55fb2d7 --- /dev/null +++ b/apps/docs/content/docs/developers/api/fields.mdx @@ -0,0 +1,738 @@ +--- +title: Fields API +description: Add signature and form fields to documents via API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + + This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, + see the [OpenAPI Reference](https://openapi.documenso.com). + + +## Field Object + +| Property | Type | Description | +| ---------------- | -------------- | -------------------------------------------- | +| `id` | number | Unique field identifier | +| `secondaryId` | string | Secondary identifier for audit logs | +| `type` | string | Field type (see [Field Types](#field-types)) | +| `recipientId` | number | ID of the recipient assigned to this field | +| `envelopeId` | number | ID of the parent envelope | +| `envelopeItemId` | string | ID of the PDF item the field is placed on | +| `page` | number | Page number (1-indexed) | +| `positionX` | number | X coordinate as percentage (0-100) | +| `positionY` | number | Y coordinate as percentage (0-100) | +| `width` | number | Width as percentage of page (0-100) | +| `height` | number | Height as percentage of page (0-100) | +| `customText` | string | Value entered by the recipient | +| `inserted` | boolean | Whether the field has been completed | +| `fieldMeta` | object \| null | Type-specific configuration options | + +### Example Field Object + +```json +{ + "id": 456, + "secondaryId": "field_abc123", + "type": "SIGNATURE", + "recipientId": 123, + "envelopeId": 789, + "envelopeItemId": "envelope_item_xyz", + "page": 1, + "positionX": 10, + "positionY": 80, + "width": 30, + "height": 5, + "customText": "", + "inserted": false, + "fieldMeta": { + "type": "signature", + "required": true + } +} +``` + +--- + +## Field Types + +| Type | Description | Auto-filled | +| ---------------- | ----------------------------------------- | ----------- | +| `SIGNATURE` | Drawn, typed, or uploaded signature | No | +| `FREE_SIGNATURE` | Unrestricted signature without validation | No | +| `INITIALS` | Recipient's initials | No | +| `NAME` | Recipient's full name | Yes | +| `EMAIL` | Recipient's email address | Yes | +| `DATE` | Date the field was completed | Yes | +| `TEXT` | Free-form text input | No | +| `NUMBER` | Numeric input with optional validation | No | +| `RADIO` | Single selection from options | No | +| `CHECKBOX` | Multiple selections from options | No | +| `DROPDOWN` | Single selection from a dropdown menu | No | + +--- + +## Get Field + +Retrieve a single field by ID. + +``` +GET /envelope/field/{fieldId} +``` + +### Path Parameters + +| Parameter | Type | Description | +| --------- | ------ | ------------ | +| `fieldId` | number | The field ID | + +### Code Examples + + + +```bash +curl -X GET "https://app.documenso.com/api/v2/envelope/field/456" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" +``` + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/field/456', + { + method: 'GET', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + }, + } +); + +const field = await response.json(); +console.log(field.type, field.page); + +``` + + + +### Response + +Returns the field object. + +--- + +## Create Fields + +Add one or more fields to a document. + +``` + +POST /envelope/field/create-many + +```` + +### Request Body + +| Field | Type | Required | Description | +| ----------- | ------ | -------- | ------------------------------- | +| `documentId`| number | Yes | The document ID | +| `fields` | array | Yes | Array of field configurations | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/field/create-many" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "documentId": 123, + "fields": [ + { + "type": "SIGNATURE", + "recipientId": 456, + "pageNumber": 1, + "pageX": 10, + "pageY": 80, + "width": 30, + "height": 5 + }, + { + "type": "DATE", + "recipientId": 456, + "pageNumber": 1, + "pageX": 50, + "pageY": 80, + "width": 20, + "height": 3 + }, + { + "type": "TEXT", + "recipientId": 456, + "pageNumber": 1, + "pageX": 10, + "pageY": 70, + "width": 40, + "height": 4, + "fieldMeta": { + "type": "text", + "label": "Job Title", + "placeholder": "Enter your job title", + "required": true + } + } + ] + }' +```` + + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/field/create-many', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + documentId: 123, + fields: [ + { + type: 'SIGNATURE', + recipientId: 456, + pageNumber: 1, + pageX: 10, + pageY: 80, + width: 30, + height: 5, + }, + { + type: 'DATE', + recipientId: 456, + pageNumber: 1, + pageX: 50, + pageY: 80, + width: 20, + height: 3, + }, + { + type: 'TEXT', + recipientId: 456, + pageNumber: 1, + pageX: 10, + pageY: 70, + width: 40, + height: 4, + fieldMeta: { + type: 'text', + label: 'Job Title', + placeholder: 'Enter your job title', + required: true, + }, + }, + ], + }), + } +); + +const { fields } = await response.json(); +console.log(`Created ${fields.length} fields`); + +```` + + + +### Response + +```json +{ + "fields": [ + { + "id": 101, + "type": "SIGNATURE", + "recipientId": 456, + "page": 1, + "positionX": 10, + "positionY": 80, + "width": 30, + "height": 5 + }, + { + "id": 102, + "type": "DATE", + "recipientId": 456, + "page": 1, + "positionX": 50, + "positionY": 80, + "width": 20, + "height": 3 + }, + { + "id": 103, + "type": "TEXT", + "recipientId": 456, + "page": 1, + "positionX": 10, + "positionY": 70, + "width": 40, + "height": 4 + } + ] +} +```` + +--- + +## Update Fields + +Update one or more fields in a single request. + +``` +POST /envelope/field/update-many +``` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | ----------------------------- | +| `documentId` | number | Yes | The document ID | +| `fields` | array | Yes | Array of field update objects | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/field/update-many" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "documentId": 123, + "fields": [ + { + "id": 101, + "type": "SIGNATURE", + "pageY": 85 + }, + { + "id": 102, + "type": "DATE", + "pageY": 85 + } + ] + }' +``` + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/field/update-many', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + documentId: 123, + fields: [ + { id: 101, type: 'SIGNATURE', pageY: 85 }, + { id: 102, type: 'DATE', pageY: 85 }, + ], + }), + } +); + +const { fields } = await response.json(); + +```` + + + +### Response + +```json +{ + "fields": [ + { "id": 101, "type": "SIGNATURE", "positionY": 85 }, + { "id": 102, "type": "DATE", "positionY": 85 } + ] +} +```` + +--- + +## Delete Field + +Remove a field from a document. + +``` +POST /envelope/field/delete +``` + +### Request Body + +| Field | Type | Required | Description | +| --------- | ------ | -------- | ------------ | +| `fieldId` | number | Yes | The field ID | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/field/delete" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "fieldId": 456 + }' +``` + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/field/delete', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + fieldId: 456, + }), + } +); + +const { success } = await response.json(); + +```` + + + +### Response + +```json +{ + "success": true +} +```` + +--- + +## Field Positioning + +Fields use percentage-based coordinates relative to the PDF page dimensions. + +| Property | Range | Description | +| ----------- | ----- | -------------------------------------------------- | +| `positionX` | 0-100 | Horizontal position from left edge (0 = left edge) | +| `positionY` | 0-100 | Vertical position from top edge (0 = top edge) | +| `width` | 0-100 | Field width as percentage of page width | +| `height` | 0-100 | Field height as percentage of page height | +| `page` | 1+ | Page number (1-indexed) | + +### Coordinate System + +``` +(0,0) ─────────────────────────── (100,0) + │ │ + │ ┌─────────┐ │ + │ │ Field │ (pageX: 10, │ + │ │ │ pageY: 20, │ + │ └─────────┘ width: 30, │ + │ height: 5) │ + │ │ +(0,100) ─────────────────────────(100,100) +``` + +### Example: Position a Signature at Bottom Right + +```typescript +const field = { + type: 'SIGNATURE', + recipientId: 123, + pageNumber: 1, + pageX: 60, // 60% from left + pageY: 85, // 85% from top (near bottom) + width: 30, // 30% of page width + height: 8, // 8% of page height +}; +``` + +--- + +## Placeholder-Based Field Positioning + +Instead of specifying exact coordinates, you can position fields using placeholder text embedded in your PDF. Include placeholder markers such as `{{signature, r1}}` in your document, and Documenso will create fields at those locations when the document is uploaded. + +This approach is useful when generating PDFs programmatically or using templates with consistent layouts. + +See the [PDF Placeholders](/docs/users/documents/advanced/pdf-placeholders) guide for the full placeholder format reference, including supported field types, recipient identifiers, and field options. + +--- + +## Field Meta Options + +Each field type supports specific configuration through `fieldMeta`. + +### Common Options + +All field types support these base options: + +| Option | Type | Description | +| ------------- | ------- | --------------------------------------- | +| `label` | string | Display text shown near the field | +| `placeholder` | string | Hint text when field is empty | +| `required` | boolean | Whether field must be completed | +| `readOnly` | boolean | Lock field with a pre-filled value | +| `fontSize` | number | Text size in pixels (8-96, default: 12) | + +### Signature Field + +```json +{ + "type": "SIGNATURE", + "fieldMeta": { + "type": "signature", + "required": true + } +} +``` + +### Text Field + +```json +{ + "type": "TEXT", + "fieldMeta": { + "type": "text", + "label": "Company Name", + "placeholder": "Enter company name", + "text": "Default value", + "characterLimit": 100, + "textAlign": "left", + "required": true + } +} +``` + +| Option | Type | Description | +| ---------------- | ------ | ---------------------------------- | +| `text` | string | Default value | +| `characterLimit` | number | Maximum characters allowed | +| `textAlign` | string | `left`, `center`, or `right` | +| `lineHeight` | number | Spacing between lines (1-10) | +| `letterSpacing` | number | Spacing between characters (0-100) | + +### Number Field + +```json +{ + "type": "NUMBER", + "fieldMeta": { + "type": "number", + "label": "Quantity", + "minValue": 1, + "maxValue": 100, + "value": "10", + "required": true + } +} +``` + +| Option | Type | Description | +| -------------- | ------ | --------------------- | +| `value` | string | Default value | +| `minValue` | number | Minimum allowed value | +| `maxValue` | number | Maximum allowed value | +| `numberFormat` | string | Display format | + +### Date Field + +```json +{ + "type": "DATE", + "fieldMeta": { + "type": "date", + "textAlign": "left", + "required": true + } +} +``` + +### Checkbox Field + +```json +{ + "type": "CHECKBOX", + "fieldMeta": { + "type": "checkbox", + "label": "Agreements", + "values": [ + { "id": 1, "value": "Terms of Service", "checked": false }, + { "id": 2, "value": "Privacy Policy", "checked": false } + ], + "validationRule": "min", + "validationLength": 1, + "direction": "vertical", + "required": true + } +} +``` + +| Option | Type | Description | +| ------------------ | ------ | --------------------------------- | +| `values` | array | List of checkbox options | +| `validationRule` | string | Validation type for selections | +| `validationLength` | number | Number for validation rule | +| `direction` | string | `vertical` or `horizontal` layout | + +### Radio Field + +```json +{ + "type": "RADIO", + "fieldMeta": { + "type": "radio", + "label": "Payment Method", + "values": [ + { "id": 1, "value": "Credit Card", "checked": false }, + { "id": 2, "value": "Bank Transfer", "checked": true }, + { "id": 3, "value": "Check", "checked": false } + ], + "direction": "vertical", + "required": true + } +} +``` + +### Dropdown Field + +```json +{ + "type": "DROPDOWN", + "fieldMeta": { + "type": "dropdown", + "label": "Country", + "values": [{ "value": "United States" }, { "value": "Canada" }, { "value": "United Kingdom" }], + "defaultValue": "United States", + "required": true + } +} +``` + +| Option | Type | Description | +| -------------- | ------ | ------------------------ | +| `values` | array | List of dropdown options | +| `defaultValue` | string | Pre-selected option | + +--- + +## Complete Example + +Create a document with a signature block containing multiple field types: + +```typescript +async function addSignatureBlock(documentId: number, recipientId: number) { + const fields = [ + // Signature + { + type: 'SIGNATURE', + recipientId, + pageNumber: 1, + pageX: 10, + pageY: 80, + width: 30, + height: 8, + fieldMeta: { + type: 'signature', + required: true, + }, + }, + // Printed name + { + type: 'NAME', + recipientId, + pageNumber: 1, + pageX: 10, + pageY: 90, + width: 30, + height: 4, + fieldMeta: { + type: 'name', + label: 'Printed Name', + }, + }, + // Date + { + type: 'DATE', + recipientId, + pageNumber: 1, + pageX: 50, + pageY: 80, + width: 20, + height: 4, + fieldMeta: { + type: 'date', + label: 'Date', + }, + }, + // Job title + { + type: 'TEXT', + recipientId, + pageNumber: 1, + pageX: 50, + pageY: 90, + width: 30, + height: 4, + fieldMeta: { + type: 'text', + label: 'Title', + placeholder: 'Enter your job title', + }, + }, + ]; + + const response = await fetch('https://app.documenso.com/api/v2/envelope/field/create-many', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ documentId, fields }), + }); + + return response.json(); +} +``` + +--- + +## Error Responses + +| Status | Description | +| ------ | ---------------------------------------------------- | +| `400` | Invalid field configuration or document already sent | +| `401` | Invalid or missing API key | +| `404` | Document, recipient, or field not found | +| `500` | Server error | + + + Fields cannot be modified after a document is sent for signing. Make all field changes while the + document is in `DRAFT` status. + + +--- + +## See Also + +- [Documents API](/docs/developers/api/documents) - Create and manage documents +- [Recipients API](/docs/developers/api/recipients) - Add signers to documents +- [Field Types](/docs/concepts/field-types) - Detailed field type reference diff --git a/apps/docs/content/docs/developers/api/index.mdx b/apps/docs/content/docs/developers/api/index.mdx new file mode 100644 index 000000000..7f446c7ad --- /dev/null +++ b/apps/docs/content/docs/developers/api/index.mdx @@ -0,0 +1,72 @@ +--- +title: API Reference +description: Complete reference for the Documenso REST API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + + + The guides below cover common API patterns but may not reflect the latest endpoints or parameters. + For an always up-to-date reference, see the [OpenAPI Reference](https://openapi.documenso.com). + + +## Base URL + +``` +https://app.documenso.com/api/v2 +``` + +For self-hosted instances, replace with your instance URL. + +--- + +## Authentication + +All requests require an API key in the `Authorization` header: + +``` +Authorization: api_xxxxxxxxxxxxxxxx +``` + + + See [Authentication](/docs/developers/getting-started/authentication) for details. + + +--- + +## Endpoints + + + + + + + + + +--- + +## See Also + +- [First API Call](/docs/developers/getting-started/first-api-call) - Quick start example +- [Webhooks](/docs/developers/webhooks) - Get notified about document events diff --git a/apps/docs/content/docs/developers/api/meta.json b/apps/docs/content/docs/developers/api/meta.json new file mode 100644 index 000000000..ffabac120 --- /dev/null +++ b/apps/docs/content/docs/developers/api/meta.json @@ -0,0 +1,13 @@ +{ + "title": "API Reference", + "pages": [ + "documents", + "recipients", + "fields", + "templates", + "teams", + "rate-limits", + "versioning", + "developer-mode" + ] +} diff --git a/apps/docs/content/docs/developers/api/rate-limits.mdx b/apps/docs/content/docs/developers/api/rate-limits.mdx new file mode 100644 index 000000000..ecd50558e --- /dev/null +++ b/apps/docs/content/docs/developers/api/rate-limits.mdx @@ -0,0 +1,67 @@ +--- +title: Rate Limits +description: Learn about the rate limits for the Documenso Public API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +## Overview + +Documenso enforces rate limits on all API endpoints to ensure service stability. + +## HTTP Rate Limits + +**Limit:** 100 requests per minute per IP address +**Response:** 429 Too Many Requests + +### Rate Limit Response + +```json +{ + "error": "Too many requests, please try again later." +} +``` + + + No rate limit headers are currently provided. When you receive a 429 response, wait at least 60 + seconds before retrying. + + +## Resource Limits + +Beyond HTTP rate limits, your account has usage limits based on your subscription plan. + +### Plan Limits + +| Resource | Free | Paid | Self-hosted | Enterprise | +| ---------------- | ---- | --------- | ----------- | ---------- | +| Documents/month | 5 | Unlimited | Unlimited | Unlimited | +| Total Recipients | 10 | Unlimited | Unlimited | Unlimited | +| Direct Templates | 3 | Unlimited | Unlimited | Unlimited | + +### Error Response + +When you exceed a resource limit: + +```json +{ + "error": "You have reached your document limit for this month. Please upgrade your plan.", + "code": "LIMIT_EXCEEDED", + "statusCode": 400 +} +``` + +## Error Codes + +| Code | Status | Description | +| ------------------- | ------ | ----------------------------- | +| `TOO_MANY_REQUESTS` | 429 | HTTP rate limit exceeded | +| `LIMIT_EXCEEDED` | 400 | Resource usage limit exceeded | + +--- + +## See Also + +- [Authentication](/docs/developers/getting-started/authentication) - API authentication guide +- [API Versioning](/docs/developers/api/versioning) - API version management +- [First API Call](/docs/developers/getting-started/first-api-call) - Getting started with the API diff --git a/apps/docs/content/docs/developers/api/recipients.mdx b/apps/docs/content/docs/developers/api/recipients.mdx new file mode 100644 index 000000000..6751a400a --- /dev/null +++ b/apps/docs/content/docs/developers/api/recipients.mdx @@ -0,0 +1,504 @@ +--- +title: Recipients API +description: Add and manage envelope recipients via API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + + This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, + see the [OpenAPI Reference](https://openapi.documenso.com). + + +## Recipient Object + +```json +{ + "id": 123, + "envelopeId": "clu1abc2def3ghi4jkl", + "email": "signer@example.com", + "name": "John Doe", + "role": "SIGNER", + "signingOrder": 1, + "token": "abc123...", + "signedAt": "2024-01-15T10:30:00Z", + "readStatus": "OPENED", + "signingStatus": "SIGNED", + "sendStatus": "SENT" +} +``` + +| Field | Type | Description | +| --------------- | -------------- | ------------------------------------- | +| `id` | number | Unique recipient identifier | +| `envelopeId` | string | ID of the associated envelope | +| `email` | string | Recipient's email address | +| `name` | string | Recipient's display name | +| `role` | string | Recipient role (see below) | +| `signingOrder` | number \| null | Order in sequential signing | +| `token` | string | Unique token for signing URL | +| `signedAt` | string \| null | ISO timestamp when signed | +| `readStatus` | string | `NOT_OPENED` or `OPENED` | +| `signingStatus` | string | `NOT_SIGNED`, `SIGNED`, or `REJECTED` | +| `sendStatus` | string | `NOT_SENT` or `SENT` | + +--- + +## Recipient Roles + +| Role | Description | +| ----------- | -------------------------------------------------------------- | +| `SIGNER` | Must sign the document. Required fields must be completed. | +| `APPROVER` | Must approve the document before signers can proceed. | +| `VIEWER` | Can view the document but takes no action. | +| `CC` | Receives a copy of the completed document. No action required. | +| `ASSISTANT` | Can fill in fields on behalf of another recipient. | + +--- + +## Get Recipient + +Retrieve a single recipient by ID. + +``` +GET /api/v2/envelope/recipient/{recipientId} +``` + +### Example + + + +```bash +curl "https://app.documenso.com/api/v2/envelope/recipient/789" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" +``` + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/recipient/789', + { + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + }, + }, +); + +const recipient = await response.json(); + +``` + + + +### Response + +Returns the full recipient object including fields. + +--- + +## Create Recipients + +Add one or more recipients to an envelope. + +``` + +POST /api/v2/envelope/recipient/create-many + +```` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | --------------------------------------- | +| `envelopeId` | string | Yes | ID of the envelope to add recipients to | +| `data` | array | Yes | Array of recipient objects | + +Each item in the `data` array: + +| Field | Type | Required | Description | +| -------------- | -------- | -------- | ------------------------------------------ | +| `email` | string | Yes | Recipient's email address | +| `name` | string | Yes | Recipient's display name (max 255 chars) | +| `role` | string | Yes | Recipient role (see Recipient Roles above) | +| `signingOrder` | number | No | Position in sequential signing | +| `accessAuth` | string[] | No | Access authentication types | +| `actionAuth` | string[] | No | Action authentication types | + +### Example + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/create-many" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "clu1abc2def3ghi4jkl", + "data": [ + { + "email": "signer@example.com", + "name": "John Doe", + "role": "SIGNER", + "signingOrder": 1 + }, + { + "email": "approver@example.com", + "name": "Jane Smith", + "role": "APPROVER", + "signingOrder": 0 + } + ] + }' +```` + + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/recipient/create-many', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'clu1abc2def3ghi4jkl', + data: [ + { + email: 'signer@example.com', + name: 'John Doe', + role: 'SIGNER', + signingOrder: 1, + }, + { + email: 'approver@example.com', + name: 'Jane Smith', + role: 'APPROVER', + signingOrder: 0, + }, + ], + }), + }, +); + +const { data: recipients } = await response.json(); + +```` + + + +### Response + +```json +{ + "data": [ + { + "id": 789, + "envelopeId": "clu1abc2def3ghi4jkl", + "email": "signer@example.com", + "name": "John Doe", + "role": "SIGNER", + "signingOrder": 1, + "token": "abc123def456", + "signedAt": null, + "readStatus": "NOT_OPENED", + "signingStatus": "NOT_SIGNED", + "sendStatus": "NOT_SENT" + }, + { + "id": 790, + "envelopeId": "clu1abc2def3ghi4jkl", + "email": "approver@example.com", + "name": "Jane Smith", + "role": "APPROVER", + "signingOrder": 0, + "token": "def456ghi789", + "signedAt": null, + "readStatus": "NOT_OPENED", + "signingStatus": "NOT_SIGNED", + "sendStatus": "NOT_SENT" + } + ] +} +```` + +--- + +## Update Recipients + +Update one or more recipients on an envelope. Only available for envelopes that are not yet completed. + +``` +POST /api/v2/envelope/recipient/update-many +``` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | -------------------------------------------- | +| `envelopeId` | string | Yes | ID of the envelope containing the recipients | +| `data` | array | Yes | Array of recipient update objects | + +Each item in the `data` array: + +| Field | Type | Required | Description | +| -------------- | -------- | -------- | ---------------------------------- | +| `id` | number | Yes | ID of the recipient to update | +| `email` | string | No | New email address | +| `name` | string | No | New display name (max 255 chars) | +| `role` | string | No | New recipient role | +| `signingOrder` | number | No | New position in sequential signing | +| `accessAuth` | string[] | No | Access authentication types | +| `actionAuth` | string[] | No | Action authentication types | + +### Example + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/update-many" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "envelopeId": "clu1abc2def3ghi4jkl", + "data": [ + { + "id": 789, + "name": "Jane Doe", + "signingOrder": 2 + } + ] + }' +``` + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/recipient/update-many', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'clu1abc2def3ghi4jkl', + data: [ + { + id: 789, + name: 'Jane Doe', + signingOrder: 2, + }, + ], + }), + }, +); + +const { data: updatedRecipients } = await response.json(); + +``` + + + +### Response + +Returns the updated recipient objects in a `data` array. + +--- + +## Delete Recipient + +Remove a recipient from an envelope. Only available for envelopes that are not yet completed. + +``` + +POST /api/v2/envelope/recipient/delete + +```` + +### Request Body + +| Field | Type | Required | Description | +| ------------- | ------ | -------- | ------------------------------- | +| `recipientId` | number | Yes | ID of the recipient to remove | + +### Example + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/delete" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "recipientId": 789 + }' +```` + + + +```typescript +const response = await fetch( + 'https://app.documenso.com/api/v2/envelope/recipient/delete', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + recipientId: 789, + }), + }, +); + +const result = await response.json(); +// { "success": true } + +```` + + + +### Response + +```json +{ + "success": true +} +```` + +--- + +## Signing Order + +When an envelope uses sequential signing, recipients sign in a specific order defined by `signingOrder`. + +### Setting Signing Order + +When creating recipients, assign `signingOrder` values to control the sequence: + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope/recipient/create-many', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'clu1abc2def3ghi4jkl', + data: [ + { + email: 'approver@example.com', + name: 'Approver', + role: 'APPROVER', + signingOrder: 0, // Approvers typically go first + }, + { + email: 'first@example.com', + name: 'First Signer', + role: 'SIGNER', + signingOrder: 1, + }, + { + email: 'second@example.com', + name: 'Second Signer', + role: 'SIGNER', + signingOrder: 2, + }, + ], + }), +}); +``` + + + To enable sequential signing, set `signingOrder` to `SEQUENTIAL` in the envelope metadata when + creating or updating the envelope. See the [Documents API](/docs/developers/api/documents) for + details. + + +### Signing Order Behavior + +- Recipients with lower `signingOrder` values sign first +- Recipients with the same `signingOrder` can sign simultaneously +- `CC` recipients receive the document after all signing is complete +- `APPROVER` recipients must approve before signers with higher order values + +--- + +## Authentication Options + +For enhanced security, you can require additional authentication when recipients access or sign a document. + +### Access Authentication + +Controls who can view the document: + +| Type | Description | +| ----------------- | ------------------------------ | +| `ACCOUNT` | Recipient must be logged in | +| `TWO_FACTOR_AUTH` | Recipient must verify with 2FA | + +### Action Authentication + +Controls who can sign the document: + +| Type | Description | +| ----------------- | ---------------------------------------- | +| `ACCOUNT` | Recipient must be logged in | +| `PASSKEY` | Require passkey authentication | +| `TWO_FACTOR_AUTH` | Require 2FA code | +| `PASSWORD` | Require password verification | +| `EXPLICIT_NONE` | Explicitly disable action authentication | + +### Example + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope/recipient/create-many', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: 'clu1abc2def3ghi4jkl', + data: [ + { + email: 'signer@example.com', + name: 'John Doe', + role: 'SIGNER', + accessAuth: ['ACCOUNT'], + actionAuth: ['PASSKEY', 'TWO_FACTOR_AUTH'], + }, + ], + }), +}); +``` + +--- + +## Error Responses + +| Status | Description | +| ------ | ------------------------------------------------ | +| `400` | Invalid request body or recipient already exists | +| `400` | Envelope is already completed | +| `401` | Invalid or missing API key | +| `404` | Envelope or recipient not found | +| `500` | Server error | + +### Example Error Response + +```json +{ + "message": "Recipient already exists" +} +``` + +--- + +## See Also + +- [Documents API](/docs/developers/api/documents) - Create and manage envelopes +- [Fields API](/docs/developers/api/fields) - Add signature fields for recipients diff --git a/apps/docs/content/docs/developers/api/teams.mdx b/apps/docs/content/docs/developers/api/teams.mdx new file mode 100644 index 000000000..99d708b41 --- /dev/null +++ b/apps/docs/content/docs/developers/api/teams.mdx @@ -0,0 +1,373 @@ +--- +title: Teams API +description: Manage team resources, documents, and templates with team-scoped API tokens. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + + This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, + see the [OpenAPI Reference](https://openapi.documenso.com). + + +## Team Object + +A team object contains the following properties: + +| Property | Type | Description | +| ----------------- | -------------- | --------------------------------------------------- | +| `id` | number | Unique team identifier | +| `name` | string | Team display name | +| `url` | string | Unique team URL slug | +| `createdAt` | string | ISO 8601 timestamp | +| `avatarImageId` | string \| null | ID of the team's avatar image | +| `organisationId` | string | ID of the parent organisation | +| `currentTeamRole` | string | Your role in the team: `ADMIN`, `MANAGER`, `MEMBER` | + +### Example Team Object + +```json +{ + "id": 123, + "name": "Engineering", + "url": "engineering", + "createdAt": "2025-01-15T10:30:00.000Z", + "avatarImageId": null, + "organisationId": "org_abc123", + "currentTeamRole": "ADMIN" +} +``` + +## Team-Scoped API Tokens + +API tokens in Documenso are always scoped to a specific team. When you create an API token, it is associated with the team you're currently working in. + +### How Team Scoping Works + +- Each API token belongs to exactly one team +- All API operations using that token automatically access that team's resources +- Documents, templates, and other resources created via the API belong to the token's team +- You cannot access resources from other teams with a single token + +### Creating Team-Scoped Tokens + +{/* prettier-ignore */} + + + Navigate to your team's settings + + + Go to **API Tokens** + + + Click **Create Token** + + + The token will be scoped to the current team + + + + + To work with multiple teams via API, create separate tokens for each team. + + +### Token Permissions + +Your API token inherits permissions based on your role in the team: + +| Role | Permissions | +| --------- | ------------------------------------------------ | +| `ADMIN` | Full access to all team resources and settings | +| `MANAGER` | Create, edit, and delete documents and templates | +| `MEMBER` | Create and manage own documents | + +## Working with Team Documents + +When you use a team-scoped API token, all document operations are automatically scoped to that team. + +### Create a Team Document + +Documents created with a team token belong to that team: + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/create" \ + -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: multipart/form-data" \ + -F 'payload={ + "type": "DOCUMENT", + "title": "Team Contract", + "recipients": [ + { + "email": "signer@example.com", + "name": "John Smith", + "role": "SIGNER" + } + ] + }' \ + -F "files=@./contract.pdf;type=application/pdf" +``` + + +```typescript +const TEAM_API_TOKEN = process.env.DOCUMENSO_TEAM_API_TOKEN; + +const form = new FormData(); + +const payload = { + type: 'DOCUMENT', + title: 'Team Contract', + recipients: [ + { + email: 'signer@example.com', + name: 'John Smith', + role: 'SIGNER', + }, + ], +}; + +form.append('payload', JSON.stringify(payload)); +form.append('files', fs.createReadStream('./contract.pdf'), { + contentType: 'application/pdf', +}); + +const response = await fetch('https://app.documenso.com/api/v2/envelope/create', { + method: 'POST', + headers: { + Authorization: TEAM_API_TOKEN, + }, + body: form, +}); + +const { id } = await response.json(); +console.log('Created team document:', id); +```` + + + +### List Team Documents + +Retrieve all documents belonging to the team: + + + +```bash +# List all team documents +curl -X GET "https://app.documenso.com/api/v2/envelope" \ + -H "Authorization: api_team_xxxxxxxxxxxxxxxx" + +# Filter by status +curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING" \ + -H "Authorization: api_team_xxxxxxxxxxxxxxxx" +```` + + + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/envelope', { + method: 'GET', + headers: { + Authorization: TEAM_API_TOKEN, + }, +}); + +const { data, pagination } = await response.json(); +console.log(`Found ${pagination.totalItems} team documents`); + +```` + + + +## Working with Team Templates + +Templates created with a team token are shared across the team. + +### Create a Team Template + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/create" \ + -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: multipart/form-data" \ + -F 'payload={ + "title": "NDA Template", + "recipients": [ + { + "email": "placeholder@example.com", + "name": "Signer", + "role": "SIGNER", + "fields": [ + { + "identifier": 0, + "type": "SIGNATURE", + "page": 1, + "positionX": 10, + "positionY": 80, + "width": 30, + "height": 5 + } + ] + } + ] + }' \ + -F "files=@./nda-template.pdf;type=application/pdf" +```` + + + +```typescript +const form = new FormData(); + +const payload = { + title: 'NDA Template', + recipients: [ + { + email: 'placeholder@example.com', + name: 'Signer', + role: 'SIGNER', + fields: [ + { + identifier: 0, + type: 'SIGNATURE', + page: 1, + positionX: 10, + positionY: 80, + width: 30, + height: 5, + }, + ], + }, + ], +}; + +form.append('payload', JSON.stringify(payload)); +form.append('files', fs.createReadStream('./nda-template.pdf'), { + contentType: 'application/pdf', +}); + +const response = await fetch('https://app.documenso.com/api/v2/template/create', { + method: 'POST', + headers: { + Authorization: TEAM_API_TOKEN, + }, + body: form, +}); + +const template = await response.json(); +console.log('Created team template:', template.id); +```` + + + +### List Team Templates + + + +```bash +curl -X GET "https://app.documenso.com/api/v2/template" \ + -H "Authorization: api_team_xxxxxxxxxxxxxxxx" +```` + + + +```typescript +const response = await fetch('https://app.documenso.com/api/v2/template', { + method: 'GET', + headers: { + Authorization: TEAM_API_TOKEN, + }, +}); + +const { data } = await response.json(); +console.log('Team templates:', data); + +```` + + + +## Team Member Roles + +| Role | Description | +| --------- | ------------------------------------------------------------------- | +| `ADMIN` | Full control over team settings, members, and all resources | +| `MANAGER` | Can manage documents, templates, and view team resources | +| `MEMBER` | Can create and manage their own documents within the team | + +### Document Visibility + +Team documents have visibility settings that control who can access them: + +| Visibility | Description | +| ------------------ | ------------------------------------------------ | +| `EVERYONE` | All team members can view the document | +| `MANAGER_AND_ABOVE`| Only managers and admins can view | +| `ADMIN` | Only admins can view | + +Set visibility when creating a document: + +```typescript +const payload = { + type: 'DOCUMENT', + title: 'Confidential Agreement', + visibility: 'ADMIN', // Only team admins can view + recipients: [...], +}; +```` + +## Multi-Team Workflow + +To work with multiple teams, create and manage separate API tokens for each team. + +### Example: Sync Documents Across Teams + +```typescript +// Tokens for different teams +const SALES_TEAM_TOKEN = process.env.SALES_TEAM_API_TOKEN; +const LEGAL_TEAM_TOKEN = process.env.LEGAL_TEAM_API_TOKEN; + +// Get pending documents from sales team +const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=PENDING', { + headers: { Authorization: SALES_TEAM_TOKEN }, +}); +const salesDocs = await salesResponse.json(); + +// Get completed documents from legal team +const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=COMPLETED', { + headers: { Authorization: LEGAL_TEAM_TOKEN }, +}); +const legalDocs = await legalResponse.json(); + +console.log(`Sales team: ${salesDocs.pagination.totalItems} pending`); +console.log(`Legal team: ${legalDocs.pagination.totalItems} completed`); +``` + +## Error Responses + +| Status | Description | +| ------ | ------------------------------------------------- | +| `401` | Invalid or expired API token | +| `403` | Token doesn't have permission for this operation | +| `404` | Resource not found or not accessible by this team | + +### Example Error Response + +```json +{ + "message": "You do not have permission to access this resource" +} +``` + + + API tokens can only access resources belonging to their associated team. Attempting to access + resources from another team returns a 403 or 404 error. + + +## See Also + +- [Documents API](/docs/developers/api/documents) - Create and manage documents +- [Templates API](/docs/developers/api/templates) - Work with document templates +- [Authentication](/docs/developers/getting-started/authentication) - Create and manage API tokens diff --git a/apps/docs/content/docs/developers/api/templates.mdx b/apps/docs/content/docs/developers/api/templates.mdx new file mode 100644 index 000000000..91bdf5a07 --- /dev/null +++ b/apps/docs/content/docs/developers/api/templates.mdx @@ -0,0 +1,1026 @@ +--- +title: Templates API +description: Create documents from reusable templates via API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + + This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, + see the [OpenAPI Reference](https://openapi.documenso.com). + + +## Template Object + +A template object contains the following properties: + +| Property | Type | Description | +| ------------------- | -------------- | ------------------------------------------------------ | +| `id` | number | Unique template identifier | +| `envelopeId` | string | Associated envelope ID | +| `type` | string | Template type: `PRIVATE` or `PUBLIC` | +| `visibility` | string | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE` | +| `title` | string | Template title | +| `externalId` | string \| null | Your custom identifier | +| `publicTitle` | string \| null | Public-facing title (for public templates) | +| `publicDescription` | string \| null | Public-facing description (for public templates) | +| `userId` | number | Owner's user ID | +| `teamId` | number \| null | Team ID if team-owned | +| `folderId` | string \| null | Folder containing the template | +| `createdAt` | string | ISO 8601 timestamp | +| `updatedAt` | string | ISO 8601 timestamp | +| `recipients` | array | Predefined recipients with roles and fields | +| `fields` | array | Signature and form fields on the template | +| `templateMeta` | object | Email settings, signing options, redirect URL | +| `directLink` | object \| null | Direct link configuration if enabled | + +### Example Template Object + +```json +{ + "id": 123, + "envelopeId": "envelope_abc123xyz", + "type": "PRIVATE", + "visibility": "EVERYONE", + "title": "Employment Contract", + "externalId": "template-emp-001", + "publicTitle": null, + "publicDescription": null, + "userId": 1, + "teamId": 5, + "folderId": null, + "createdAt": "2025-01-10T08:00:00.000Z", + "updatedAt": "2025-01-10T08:30:00.000Z", + "recipients": [ + { + "id": 1, + "email": "employee@example.com", + "name": "Employee", + "role": "SIGNER", + "signingOrder": 1 + }, + { + "id": 2, + "email": "hr@company.com", + "name": "HR Manager", + "role": "SIGNER", + "signingOrder": 2 + } + ], + "fields": [ + { + "id": 101, + "type": "SIGNATURE", + "page": 1, + "positionX": 10, + "positionY": 80, + "width": 30, + "height": 5, + "recipientId": 1 + } + ], + "templateMeta": { + "subject": "Your Employment Contract", + "message": "Please review and sign your employment contract.", + "redirectUrl": "https://example.com/welcome" + }, + "directLink": null +} +``` + +## List Templates + +Retrieve a paginated list of templates. + +``` +GET /template +``` + +### Query Parameters + +| Parameter | Type | Description | +| ------------------ | ------- | ------------------------------------------------- | +| `page` | integer | Page number (default: 1) | +| `perPage` | integer | Results per page (default: 10, max: 100) | +| `type` | string | Filter by type: `PRIVATE` or `PUBLIC` | +| `folderId` | string | Filter by folder ID | +| `orderByColumn` | string | Sort field (only `createdAt` supported) | +| `orderByDirection` | string | Sort direction: `asc` or `desc` (default: `desc`) | + +### Code Examples + + + +```bash +# List all templates +curl -X GET "https://app.documenso.com/api/v2/template" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" + +# Filter by type and paginate + +curl -X GET "https://app.documenso.com/api/v2/template?type=PRIVATE&page=1&perPage=20" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" + +```` + + +```typescript +const API_TOKEN = process.env.DOCUMENSO_API_TOKEN; +const BASE_URL = 'https://app.documenso.com/api/v2'; + +// List all templates +const response = await fetch(`${BASE_URL}/template`, { + method: 'GET', + headers: { + Authorization: API_TOKEN, + }, +}); + +const { data, pagination } = await response.json(); +console.log(`Found ${pagination.totalItems} templates`); + +// Filter by type +const privateResponse = await fetch( + `${BASE_URL}/template?type=PRIVATE&page=1&perPage=20`, + { + method: 'GET', + headers: { + Authorization: API_TOKEN, + }, + } +); + +const privateTemplates = await privateResponse.json(); +```` + + + + +### Response + +```json +{ + "data": [ + { + "id": 123, + "envelopeId": "envelope_abc123", + "type": "PRIVATE", + "title": "Employment Contract", + "createdAt": "2025-01-10T08:00:00.000Z", + "updatedAt": "2025-01-10T08:30:00.000Z", + "recipients": [ + { + "id": 1, + "email": "employee@example.com", + "name": "Employee", + "role": "SIGNER" + } + ] + } + ], + "pagination": { + "page": 1, + "perPage": 10, + "totalPages": 3, + "totalItems": 25 + } +} +``` + +--- + +## Get Template + +Retrieve a single template by ID. + +``` +GET /template/{templateId} +``` + +### Path Parameters + +| Parameter | Type | Description | +| ------------ | ------ | --------------- | +| `templateId` | number | The template ID | + +### Code Examples + + + +```bash +curl -X GET "https://app.documenso.com/api/v2/template/123" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" +``` + + +```typescript +const templateId = 123; + +const response = await fetch(`https://app.documenso.com/api/v2/template/${templateId}`, { + method: 'GET', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + }, +}); + +const template = await response.json(); +console.log(template.title, template.recipients.length); +``` + + + +### Response + +Returns the full template object including recipients, fields, and metadata. + +--- + +## Create Document from Template + +Create a new document using a template. This is the primary way to use templates programmatically. + +``` + +POST /template/use + +```` + +### Request Body + +| Field | Type | Required | Description | +| ------------------- | ------- | -------- | ---------------------------------------------------------- | +| `templateId` | number | Yes | The template ID to use | +| `recipients` | array | Yes | Recipient details (maps to template recipients) | +| `distributeDocument`| boolean | No | If `true`, immediately send the document to recipients | +| `externalId` | string | No | Your custom identifier for the created document | +| `folderId` | string | No | Folder ID to create the document in | +| `prefillFields` | array | No | Pre-fill field values before sending | +| `override` | object | No | Override template settings for this document | +| `formValues` | object | No | PDF form values to insert | + +### Recipients Array + +Each recipient object must include: + +| Field | Type | Required | Description | +| ------- | ------ | -------- | ---------------------------------------------- | +| `id` | number | Yes | The recipient ID from the template | +| `email` | string | Yes | Recipient's email address | +| `name` | string | No | Recipient's display name | + +### Code Examples + + + +```bash +# Create document from template +curl -X POST "https://app.documenso.com/api/v2/template/use" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123, + "recipients": [ + { + "id": 1, + "email": "john.doe@example.com", + "name": "John Doe" + }, + { + "id": 2, + "email": "jane.smith@company.com", + "name": "Jane Smith" + } + ], + "distributeDocument": true, + "externalId": "contract-2025-001" + }' + +# Create document with field prefilling +curl -X POST "https://app.documenso.com/api/v2/template/use" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123, + "recipients": [ + { + "id": 1, + "email": "john.doe@example.com", + "name": "John Doe" + } + ], + "prefillFields": [ + { + "id": 101, + "type": "text", + "value": "Senior Software Engineer" + }, + { + "id": 102, + "type": "number", + "value": "85000" + }, + { + "id": 103, + "type": "date", + "value": "2025-02-01" + } + ], + "distributeDocument": true + }' +```` + + + +```typescript +const API_TOKEN = process.env.DOCUMENSO_API_TOKEN; +const BASE_URL = 'https://app.documenso.com/api/v2'; + +// Create document from template +const response = await fetch(`${BASE_URL}/template/use`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + recipients: [ + { + id: 1, + email: 'john.doe@example.com', + name: 'John Doe', + }, + { + id: 2, + email: 'jane.smith@company.com', + name: 'Jane Smith', + }, + ], + distributeDocument: true, + externalId: 'contract-2025-001', + }), +}); + +const document = await response.json(); +console.log('Created document:', document.id); + +// Create document with prefilled fields +const prefillResponse = await fetch(`${BASE_URL}/template/use`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + recipients: [ + { + id: 1, + email: 'john.doe@example.com', + name: 'John Doe', + }, + ], + prefillFields: [ + { + id: 101, + type: 'text', + value: 'Senior Software Engineer', + }, + { + id: 102, + type: 'number', + value: '85000', + }, + { + id: 103, + type: 'date', + value: '2025-02-01', + }, + ], + distributeDocument: true, + }), +}); + +const prefilledDocument = await prefillResponse.json(); +```` + + + +### Response + +Returns the created document object with recipients and signing URLs. + +```json +{ + "id": "envelope_xyz789", + "type": "DOCUMENT", + "status": "PENDING", + "title": "Employment Contract", + "source": "TEMPLATE", + "externalId": "contract-2025-001", + "recipients": [ + { + "id": 1, + "email": "john.doe@example.com", + "name": "John Doe", + "role": "SIGNER", + "signingStatus": "NOT_SIGNED", + "signingUrl": "https://app.documenso.com/sign/abc123" + } + ] +} +```` + +--- + +## Override Template Settings + +When creating a document from a template, you can override various settings: + +```typescript +const response = await fetch(`${BASE_URL}/template/use`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + recipients: [{ id: 1, email: 'signer@example.com', name: 'Signer' }], + override: { + title: 'Custom Document Title', + subject: 'Custom email subject', + message: 'Custom email message body', + timezone: 'America/New_York', + dateFormat: 'MM/dd/yyyy', + redirectUrl: 'https://example.com/custom-redirect', + language: 'de', + typedSignatureEnabled: true, + uploadSignatureEnabled: false, + drawSignatureEnabled: true, + }, + distributeDocument: true, + }), +}); +``` + +### Override Options + +| Field | Type | Description | +| ------------------------ | ------- | ------------------------------- | +| `title` | string | Document title | +| `subject` | string | Email subject line | +| `message` | string | Email body message | +| `timezone` | string | Timezone for date fields | +| `dateFormat` | string | Date format string | +| `redirectUrl` | string | URL to redirect after signing | +| `language` | string | Document language code | +| `typedSignatureEnabled` | boolean | Allow typed signatures | +| `uploadSignatureEnabled` | boolean | Allow uploaded signature images | +| `drawSignatureEnabled` | boolean | Allow drawn signatures | + +--- + +## Prefill Fields + +Prefill field values when creating a document from a template. This is useful for populating known data before sending. + +### Supported Field Types + +| Type | Value Format | Description | +| ---------- | ----------------- | ------------------------------ | +| `text` | string | Text field value | +| `number` | string | Numeric value as string | +| `date` | string (ISO 8601) | Date in `YYYY-MM-DD` format | +| `radio` | string | Selected option value | +| `checkbox` | array of strings | Array of checked option values | +| `dropdown` | string | Selected dropdown value | + +### Prefill Field Schema + +```typescript +type PrefillField = { + id: number; // Field ID from template + type: string; // Field type (must match template field) + label?: string; // Optional label override + placeholder?: string; // Optional placeholder (text/number only) + value: string | string[]; // Value to prefill +}; +``` + +### Example: Prefill Multiple Field Types + +```typescript +const response = await fetch(`${BASE_URL}/template/use`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + recipients: [{ id: 1, email: 'signer@example.com', name: 'Signer' }], + prefillFields: [ + // Text field + { + id: 101, + type: 'text', + value: 'John Doe', + }, + // Number field + { + id: 102, + type: 'number', + value: '50000', + }, + // Date field + { + id: 103, + type: 'date', + value: '2025-03-15', + }, + // Radio field (select one option) + { + id: 104, + type: 'radio', + value: 'full-time', + }, + // Checkbox field (select multiple options) + { + id: 105, + type: 'checkbox', + value: ['health', 'dental', '401k'], + }, + // Dropdown field + { + id: 106, + type: 'dropdown', + value: 'engineering', + }, + ], + distributeDocument: true, + }), +}); +``` + + + The field type in `prefillFields` must match the actual field type in the template. A mismatch + will result in an error. + + +--- + +## Update Template + +Update a template's properties. + +``` +POST /template/update +``` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | ------------------------------------ | +| `templateId` | number | Yes | Template ID | +| `data` | object | No | Template properties to update | +| `meta` | object | No | Email and signing settings to update | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/update" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123, + "data": { + "title": "Updated Employment Contract", + "visibility": "ADMIN" + }, + "meta": { + "subject": "Updated: Your Employment Contract", + "redirectUrl": "https://example.com/updated-redirect" + } + }' +``` + + +```typescript +const response = await fetch(`${BASE_URL}/template/update`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + data: { + title: 'Updated Employment Contract', + visibility: 'ADMIN', + }, + meta: { + subject: 'Updated: Your Employment Contract', + redirectUrl: 'https://example.com/updated-redirect', + }, + }), +}); + +const template = await response.json(); + +``` + + + +--- + +## Duplicate Template + +Create a copy of an existing template. + +``` + +POST /template/duplicate + +```` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | --------------- | +| `templateId` | number | Yes | Template ID | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/duplicate" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123 + }' +```` + + + +```typescript +const response = await fetch(`${BASE_URL}/template/duplicate`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + }), +}); + +const duplicatedTemplate = await response.json(); +console.log('New template ID:', duplicatedTemplate.id); + +``` + + + +--- + +## Delete Template + +Delete a template. + +``` + +POST /template/delete + +```` + +### Request Body + +| Field | Type | Required | Description | +| ------------ | ------ | -------- | --------------- | +| `templateId` | number | Yes | Template ID | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/delete" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123 + }' +```` + + + +```typescript +const response = await fetch(`${BASE_URL}/template/delete`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + }), +}); + +const { success } = await response.json(); + +```` + + + +### Response + +```json +{ + "success": true +} +```` + +--- + +## Direct Link Templates + +Direct link templates allow recipients to create and sign documents without requiring you to explicitly create each document. When a recipient visits the direct link, a new document is automatically created from the template. + +### Create Direct Link + +``` +POST /template/direct/create +``` + +| Field | Type | Required | Description | +| ------------------- | ------ | -------- | --------------------------------------------- | +| `templateId` | number | Yes | Template ID | +| `directRecipientId` | number | No | Recipient ID to use as the direct link signer | + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/direct/create" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123, + "directRecipientId": 1 + }' +``` + + +```typescript +const response = await fetch(`${BASE_URL}/template/direct/create`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + directRecipientId: 1, + }), +}); + +const directLink = await response.json(); +console.log('Direct link token:', directLink.token); +// Share: https://app.documenso.com/d/{token} + +```` + + + +### Response + +```json +{ + "id": 456, + "token": "abc123xyz", + "templateId": 123, + "directTemplateRecipientId": 1, + "enabled": true, + "createdAt": "2025-01-15T10:00:00.000Z" +} +```` + +### Toggle Direct Link + +Enable or disable an existing direct link. + +``` +POST /template/direct/toggle +``` + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/direct/toggle" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123, + "enabled": false + }' +``` + + +```typescript +const response = await fetch(`${BASE_URL}/template/direct/toggle`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + enabled: false, + }), +}); + +const directLink = await response.json(); +console.log('Direct link enabled:', directLink.enabled); + +``` + + + +### Delete Direct Link + +``` + +POST /template/direct/delete + +```` + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/template/direct/delete" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123 + }' +```` + + + +```typescript +const response = await fetch(`${BASE_URL}/template/direct/delete`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + }), +}); + +const { success } = await response.json(); + +```` + + + +--- + +## Custom Document Data + +When creating a document from a template, you can replace the template's PDF with a custom PDF by using the `customDocumentData` parameter. This is useful when you need to generate the PDF dynamically while reusing the template's recipient and field configuration. + +To use custom document data: + +1. Retrieve the template to get the `envelopeItemId` of the PDF you want to replace +2. Include `customDocumentData` in your `template/use` request, mapping each `envelopeItemId` to a new file + +The field positions from the template are preserved on the new PDF. Ensure the replacement PDF has the same page layout to maintain accurate field placement. + +See the [OpenAPI Reference](https://openapi.documenso.com) for the full request schema. + +--- + +## Template Types + +| Type | Description | +| --------- | ------------------------------------------------------------------ | +| `PRIVATE` | Only accessible by owner and team members | +| `PUBLIC` | Can be shared publicly with a direct link | + +--- + +## Complete Example: Contract Workflow + +This example demonstrates a complete workflow for using templates to send contracts. + +```typescript +const API_TOKEN = process.env.DOCUMENSO_API_TOKEN; +const BASE_URL = 'https://app.documenso.com/api/v2'; + +async function sendEmploymentContract(employeeData: { + email: string; + name: string; + position: string; + salary: number; + startDate: string; +}) { + // 1. Get the template to find recipient and field IDs + const templateResponse = await fetch(`${BASE_URL}/template/456`, { + headers: { Authorization: API_TOKEN }, + }); + const template = await templateResponse.json(); + + // 2. Find the employee recipient slot + const employeeRecipient = template.recipients.find( + (r) => r.role === 'SIGNER' && r.signingOrder === 1 + ); + + // 3. Find fields to prefill + const positionField = template.fields.find( + (f) => f.fieldMeta?.label === 'Position' + ); + const salaryField = template.fields.find( + (f) => f.fieldMeta?.label === 'Salary' + ); + const startDateField = template.fields.find( + (f) => f.type === 'DATE' + ); + + // 4. Create document from template with prefilled data + const documentResponse = await fetch(`${BASE_URL}/template/use`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 456, + recipients: [ + { + id: employeeRecipient.id, + email: employeeData.email, + name: employeeData.name, + }, + ], + prefillFields: [ + { + id: positionField.id, + type: 'text', + value: employeeData.position, + }, + { + id: salaryField.id, + type: 'number', + value: employeeData.salary.toString(), + }, + { + id: startDateField.id, + type: 'date', + value: employeeData.startDate, + }, + ], + override: { + subject: `Employment Contract for ${employeeData.name}`, + message: `Hi ${employeeData.name},\n\nPlease review and sign your employment contract.`, + }, + distributeDocument: true, + externalId: `emp-contract-${Date.now()}`, + }), + }); + + const document = await documentResponse.json(); + + return { + documentId: document.id, + signingUrl: document.recipients[0].signingUrl, + }; +} + +// Usage +const result = await sendEmploymentContract({ + email: 'john.doe@example.com', + name: 'John Doe', + position: 'Senior Engineer', + salary: 120000, + startDate: '2025-03-01', +}); + +console.log('Document created:', result.documentId); +console.log('Signing URL:', result.signingUrl); +```` + +--- + +## See Also + +- [Documents API](/docs/developers/api/documents) - Work with created documents +- [Recipients API](/docs/developers/api/recipients) - Manage document recipients +- [Fields API](/docs/developers/api/fields) - Work with signature and form fields +- [Webhooks](/docs/developers/webhooks) - Get notified when documents are signed diff --git a/apps/docs/content/docs/developers/api/versioning.mdx b/apps/docs/content/docs/developers/api/versioning.mdx new file mode 100644 index 000000000..c137a869a --- /dev/null +++ b/apps/docs/content/docs/developers/api/versioning.mdx @@ -0,0 +1,25 @@ +--- +title: API Versioning +description: Versioning information for the Documenso public API. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +## Overview + +Documenso uses API versioning to manage changes to the public API. This allows us to introduce new features, fix bugs, and make other changes without breaking existing integrations. + +The current version of the API is `v2`. + +The API version is specified in the URL. For example, the base URL for the `v2` API is `https://app.documenso.com/api/v2`. + +We may make changes to the API without incrementing the version number. We will always try to avoid breaking changes, but in some cases, it may be necessary to make changes that are not backward compatible. In these cases, we will increment the version number and provide information about the changes in the release notes. + +Also, we may deprecate certain features or endpoints in the API. When we deprecate a feature or endpoint, we will provide information about the deprecation in the release notes and give a timeline for when the feature or endpoint will be removed. + +--- + +## See Also + +- [Authentication](/docs/developers/getting-started/authentication) - API authentication guide +- [Rate Limits](/docs/developers/api/rate-limits) - API rate limit details diff --git a/apps/docs/content/docs/developers/contributing/contributing-translations.mdx b/apps/docs/content/docs/developers/contributing/contributing-translations.mdx new file mode 100644 index 000000000..24b069ee0 --- /dev/null +++ b/apps/docs/content/docs/developers/contributing/contributing-translations.mdx @@ -0,0 +1,91 @@ +--- +title: Contributing Translations +description: Learn how to contribute translations to Documenso and become part of our community. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; + +We are always open for help with translations! Currently we utilise AI to generate the initial translations for new languages, which are then improved over time by our awesome community. + +If you are looking for development notes on translations, you can find them [here](/docs/developers/local-development/translations). + + + Contributions are made through GitHub Pull Requests, so you will need a GitHub account to + contribute. + + +## Overview + +We store our translations in PO files, which are located in our GitHub repository [here](https://github.com/documenso/documenso/tree/main/packages/lib/translations). + +The translation files are organized into folders represented by their respective language codes (`en` for English, `de` for German, etc). + +Each PO file contains translations which look like this: + +```po +#: apps/remix/app/(signing)/sign/[token]/no-longer-available.tsx:61 +msgid "Want to send slick signing links like this one? <0>Check out Documenso." +msgstr "Möchten Sie auffällige Signatur-Links wie diesen senden? <0>Überprüfen Sie Documenso." +``` + +- `msgid`: The original text in English (never edit this manually) +- `msgstr`: The translated text in the target language + + + Notice the `<0>` tags? These represent HTML elements and must remain in both the `msgid` and `msgstr`. Make sure to translate the content between these tags while keeping the tags intact. + + +## How to Contribute + +### Updating Existing Translations + +{/* prettier-ignore */} + + + Fork the repository + + + Navigate to the appropriate language folder and open the PO file you want to update + + + Make your changes, ensuring you follow the PO file format + + + Commit your changes with a message such as chore: update German translations + + + Create a Pull Request + + + +### Adding a New Language + +If you want to add translations for a language that doesn't exist yet: + +{/* prettier-ignore */} + + + Create an issue in our GitHub repository requesting the addition of the new language + + + Wait for our team to review and approve the request + + + Once approved, we will set up the necessary files and kickstart the translations with AI to + provide initial coverage + + + +## Need Help? + + + If you have any questions, hop into our [Discord](https://documen.so/discord) and ask us directly! + + +Thank you for helping make Documenso more accessible to users around the world! + +## See Also + +- [Translations (Development)](/docs/developers/local-development/translations) - Technical guide to translations in code +- [Contributing Guide](/docs/developers/contributing) - General contributing guidelines diff --git a/apps/docs/content/docs/developers/contributing/index.mdx b/apps/docs/content/docs/developers/contributing/index.mdx new file mode 100644 index 000000000..51296f50b --- /dev/null +++ b/apps/docs/content/docs/developers/contributing/index.mdx @@ -0,0 +1,152 @@ +--- +title: Contributing to Documenso +description: Learn how to contribute to Documenso and become part of our community. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; + +## Overview + +If you plan to contribute to Documenso, please take a moment to feel awesome. People like you are what open source is about. Any contributions, no matter how big or small, are highly appreciated. + +This guide will help you get started with contributing to Documenso. + +## Before Getting Started + +{/* prettier-ignore */} + + + +### Check the existing issues and pull requests + +Search the existing [issues](https://github.com/documenso/documenso/issues) to see if someone else reported the same issue. Or, check the [existing PRs](https://github.com/documenso/documenso/pulls) to see if someone else is already working on the same thing. + + + + +### Creating a new issue + +If there is no issue or PR for the problem you are facing, feel free to create a new issue. Make sure to provide as much detail as possible, including the steps to reproduce the issue. + + + + +### Picking an existing issue + +If you pick an existing issue, take into consideration the discussion on the issue. + + + + +### Contributor license agreement + +Accept the [Contributor License Agreement](https://documen.so/cla) to ensure we can accept your contributions. + + + + + +## Taking Issues + +Before taking an issue, ensure that: + +- The issue has been assigned the public label. +- The issue is clearly defined and understood. +- No one has been assigned to the issue. +- No one has expressed the intention to work on it. + +After that: + +1. Comment on the issue with your intention to work on it. +2. Start working on the issue. + +Feel free to ask for help, clarification or guidance if needed. We are here to help you. + +## Developing + +The development branch is `main`, and all pull requests should be made against this branch. Here's how you can get started with developing: + +{/* prettier-ignore */} + + + +### Set up Documenso locally + +To set up your local environment, check out the [local development](/docs/developers/local-development) guide. + + + + +### Pick a task + +Find an issue to work on or create a new one. + +> Before working on an issue, ensure that no one else is working on it. If no one is assigned to the issue, you can pick it up by leaving a comment and asking to assign it to you. + +Before creating a new issue, check the existing issues to see if someone else has already reported it. + + + + +### Create a new branch + +After you're assigned an issue, you can start working on it. Create a new branch for your feature or bug fix. + +When creating a branch, make sure that the branch name: + +- starts with the correct prefix: `feat/` for new features, `fix/` for bug fixes, etc. +- includes the issue ID you are working on (if applicable). +- is descriptive. + +```sh +git checkout -b feat/issue-id-your-branch-name + +## Example +git checkout -b feat/1234-add-share-button-to-articles +``` + +In the pull request description, include `references #yyyy` or `fixes #yyyy` to link it to the issue you are working on. + + + + +### Implement your changes + +Start working on the issue you picked up and implement the changes. Make sure to test your changes locally and ensure that they work as expected. + + + + +### Open a pull request + +After implementing your changes, open a pull request against the `main` branch. + + + + + + + If you need help getting started, [join us on Discord](https://documen.so/discord). + + +## Building + +Before pushing code or creating pull requests, please ensure you can successfully create a successful production build. You can build the project by running the following command in your terminal: + +```bash +npm run build +``` + +Once the project builds successfully, you can push your code changes or create a pull request. + + + Remember to run tests and perform any necessary checks before finalizing your changes. As a + result, we can collaborate more effectively and maintain a high standard of code quality in our + project. + + +## See Also + +- [Local Development](/docs/developers/local-development) - Set up your development environment +- [Contributing Translations](/docs/developers/contributing/contributing-translations) - Help translate Documenso diff --git a/apps/docs/content/docs/developers/contributing/meta.json b/apps/docs/content/docs/developers/contributing/meta.json new file mode 100644 index 000000000..85a61090e --- /dev/null +++ b/apps/docs/content/docs/developers/contributing/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Contributing", + "pages": ["contributing-translations"] +} diff --git a/apps/docs/content/docs/developers/demo-environment/index.mdx b/apps/docs/content/docs/developers/demo-environment/index.mdx new file mode 100644 index 000000000..4980fc25b --- /dev/null +++ b/apps/docs/content/docs/developers/demo-environment/index.mdx @@ -0,0 +1,64 @@ +--- +title: Demo Environment +description: Use the demo environment to try out the Documenso platform and its features. +--- + +import { Step, Steps } from 'fumadocs-ui/components/steps'; + +## Overview + +The demo (staging) environment is a sandbox environment that replicates the production environment. It has the same features and capabilities as the production environment, but is intended for development and testing purposes. + +You can use it to try out the Documenso platform and its features before committing to a paid plan. + +## How to Use the Demo Environment + +{/* prettier-ignore */} + + + ### Navigate to the staging environment + + Go to the [staging environment](https://stg-app.documenso.com). + + + + ### Create an account + + You need to create a new account for the demo environment. You can't use your production account. + + + + ### Pick a paid plan + + Choose the appropriate plan for your needs. + + You can also use the free plan but it's limited to 5 documents per month and up to 10 recipients per document. + + Whatever plan you choose, you can upgrade later. + + + + ### Use a test card + + To upgrade to a paid plan, you can use a test card. Example: + + ``` + Card number: 4242 4242 4242 4242 + Expiry date: 02/2030 (or any valid future date) + CVV: 123 + ``` + + + + ### Use the platform + + You can then try out the platform and its features. + + + + ### Issues, questions and feedback + + If you have any issues, questions or feedback, please reach out to us on the [Documenso Discord](https://documen.so/discord) or [GitHub](https://github.com/documenso/documenso/issues). + + + diff --git a/apps/docs/content/docs/developers/embedding/authoring.mdx b/apps/docs/content/docs/developers/embedding/authoring.mdx new file mode 100644 index 000000000..030f9ae93 --- /dev/null +++ b/apps/docs/content/docs/developers/embedding/authoring.mdx @@ -0,0 +1,306 @@ +--- +title: Authoring +description: Embed document and template creation directly in your application. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +In addition to embedding signing, Documenso supports embedded authoring. It allows your users to create and edit documents and templates without leaving your application. + + + Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is + also available as a paid add-on for the [Platform Plan](https://documen.so/platform-cta-pricing). + Contact sales for access. + + +## Components + +The SDK provides four authoring components: + +| Component | Purpose | +| ----------------------- | ----------------------- | +| `EmbedCreateDocumentV1` | Create new documents | +| `EmbedCreateTemplateV1` | Create new templates | +| `EmbedUpdateDocumentV1` | Edit existing documents | +| `EmbedUpdateTemplateV1` | Edit existing templates | + +All authoring components require a **presign token** for authentication instead of a regular token. + +--- + +## Presign Tokens + +Before using any authoring component, obtain a presign token from your backend: + +``` +POST /api/v2/embedding/create-presign-token +``` + +This endpoint requires your Documenso API key. The token has a default expiration of 1 hour. + +See the [API documentation](https://openapi.documenso.com/reference#tag/embedding) for full details. + + + Presign tokens should be created server-side. Never expose your API key in client-side code. + + +--- + +## Creating Documents + +```jsx +import { EmbedCreateDocumentV1 } from '@documenso/embed-react'; + +const DocumentCreator = ({ presignToken }) => { + return ( +

+ { + console.log('Document created:', data.documentId); + console.log('External ID:', data.externalId); + }} + /> +
+ ); +}; +``` + +--- + +## Creating Templates + +```jsx +import { EmbedCreateTemplateV1 } from '@documenso/embed-react'; + +const TemplateCreator = ({ presignToken }) => { + return ( +
+ { + console.log('Template created:', data.templateId); + }} + /> +
+ ); +}; +``` + +--- + +## Editing Documents + +```jsx +import { EmbedUpdateDocumentV1 } from '@documenso/embed-react'; + +const DocumentEditor = ({ presignToken, documentId }) => { + return ( +
+ { + console.log('Document updated:', data.documentId); + }} + /> +
+ ); +}; +``` + +--- + +## Editing Templates + +```jsx +import { EmbedUpdateTemplateV1 } from '@documenso/embed-react'; + +const TemplateEditor = ({ presignToken, templateId }) => { + return ( +
+ { + console.log('Template updated:', data.templateId); + }} + /> +
+ ); +}; +``` + +--- + +## Props + +### All Authoring Components + +| Prop | Type | Required | Description | +| ------------------ | --------- | -------- | -------------------------------------------------------- | +| `presignToken` | `string` | Yes | Authentication token from your backend | +| `externalId` | `string` | No | Your reference ID to link with the document or template | +| `host` | `string` | No | Custom host URL. Defaults to `https://app.documenso.com` | +| `css` | `string` | No | Custom CSS string (Platform Plan) | +| `cssVars` | `object` | No | CSS variable overrides (Platform Plan) | +| `darkModeDisabled` | `boolean` | No | Disable dark mode (Platform Plan) | +| `className` | `string` | No | CSS class for the iframe | +| `features` | `object` | No | Feature toggles for the authoring experience | + +### Update Components Only + +| Prop | Type | Required | Description | +| ---------------- | --------- | -------- | ---------------------------------------------------------- | +| `documentId` | `number` | Yes | The document ID to edit (for document update component) | +| `templateId` | `number` | Yes | The template ID to edit (for template update component) | +| `onlyEditFields` | `boolean` | No | Restrict editing to fields only, skipping recipient config | + +--- + +## Feature Toggles + +Customize what options are available in the authoring experience: + +```jsx + +``` + +--- + +## Event Callbacks + +All creation callbacks receive: + +| Field | Type | Description | +| ---------------------------- | -------- | --------------------------------------- | +| `documentId` or `templateId` | `number` | The ID of the created or updated item | +| `externalId` | `string` | Your external reference ID, if provided | + +--- + +## Field-Only Editing + +Restrict users to editing fields only, skipping recipient configuration: + +```jsx + { + console.log('Fields updated:', data.documentId); + }} +/> +``` + +--- + +## Complete Integration Example + +This example shows a full workflow where users create a document and then edit it: + +```tsx +import { useState } from 'react'; + +import { EmbedCreateDocumentV1, EmbedUpdateDocumentV1 } from '@documenso/embed-react'; + +const DocumentManager = ({ presignToken }) => { + const [documentId, setDocumentId] = useState(null); + const [mode, setMode] = useState('create'); + + if (mode === 'success') { + return ( +
+

Document updated successfully

+ +
+ ); + } + + if (mode === 'edit' && documentId) { + return ( +
+ + { + console.log('Document updated:', data.documentId); + setMode('success'); + }} + /> +
+ ); + } + + return ( +
+ { + console.log('Document created:', data.documentId); + setDocumentId(data.documentId); + setMode('edit'); + }} + /> +
+ ); +}; +``` + +--- + +## Additional Props + +Pass extra props to the iframe for testing experimental features: + +```jsx + +``` + + + Presign tokens expire after 1 hour by default. You can customize this duration based on your + security requirements. Generate fresh tokens for each session and avoid caching them on the client + side. + + +--- + +## See Also + +- [Embedding Overview](/docs/developers/embedding) - Signing embed concepts and props +- [CSS Variables](/docs/developers/embedding/css-variables) - Customize appearance +- [Documents API](/docs/developers/api/documents) - Create documents via API +- [Templates API](/docs/developers/api/templates) - Create templates via API diff --git a/apps/docs/content/docs/developers/embedding/css-variables.mdx b/apps/docs/content/docs/developers/embedding/css-variables.mdx new file mode 100644 index 000000000..e95b0fda4 --- /dev/null +++ b/apps/docs/content/docs/developers/embedding/css-variables.mdx @@ -0,0 +1,215 @@ +--- +title: CSS Variables +description: Customize the appearance of embedded signing experiences with CSS variables and class targets. +--- + +import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; +import { Callout } from 'fumadocs-ui/components/callout'; + + + Custom CSS and CSS variables are available on the [Platform + Plan](https://documen.so/platform-cta-pricing). + + +## CSS Variables + +Use the `cssVars` prop on any embed component to override default colors, spacing, and more. + +```jsx + +``` + +### Colors + +| Variable | Description | +| ----------------------- | --------------------------------- | +| `background` | Base background color | +| `foreground` | Base text color | +| `muted` | Muted/subtle background color | +| `mutedForeground` | Muted/subtle text color | +| `popover` | Popover/dropdown background color | +| `popoverForeground` | Popover/dropdown text color | +| `card` | Card background color | +| `cardBorder` | Card border color | +| `cardBorderTint` | Card border tint/highlight color | +| `cardForeground` | Card text color | +| `fieldCard` | Field card background color | +| `fieldCardBorder` | Field card border color | +| `fieldCardForeground` | Field card text color | +| `widget` | Widget background color | +| `widgetForeground` | Widget text color | +| `border` | Default border color | +| `input` | Input field border color | +| `primary` | Primary action/button color | +| `primaryForeground` | Primary action/button text color | +| `secondary` | Secondary action/button color | +| `secondaryForeground` | Secondary button text color | +| `accent` | Accent/highlight color | +| `accentForeground` | Accent/highlight text color | +| `destructive` | Destructive/danger action color | +| `destructiveForeground` | Destructive/danger text color | +| `ring` | Focus ring color | +| `warning` | Warning/alert color | + +### Spacing + +| Variable | Description | +| -------- | ---------------------------------- | +| `radius` | Border radius size (e.g. `0.5rem`) | + +### Framework Usage + +Pass `cssVars` to any embed component. The syntax varies by framework: + +```jsx +// React / Preact + + +// Vue + + +// Svelte + + +// Solid + +``` + +### Color Formats + +Colors can be specified in any valid CSS format: + +- Hex: `#ff0000` +- RGB: `rgb(255, 0, 0)` +- HSL: `hsl(0, 100%, 50%)` +- Named: `red` + +--- + +## Custom CSS + +Use the `css` prop to inject a CSS string for more targeted control: + +```jsx + +``` + +--- + +## CSS Class Targets + +Specific parts of the embed can be targeted with CSS classes for granular styling. + +### Component Classes + +| Class | Description | +| --------------------------------- | --------------------------------------------- | +| `.embed--Root` | Main container for the embedded experience | +| `.embed--DocumentContainer` | Container for the document and signing widget | +| `.embed--DocumentViewer` | Container for the document viewer | +| `.embed--DocumentWidget` | The signing widget container | +| `.embed--DocumentWidgetContainer` | Outer container for the signing widget | +| `.embed--DocumentWidgetHeader` | Header section of the signing widget | +| `.embed--DocumentWidgetContent` | Main content area of the signing widget | +| `.embed--DocumentWidgetForm` | Form section within the signing widget | +| `.embed--DocumentWidgetFooter` | Footer section of the signing widget | +| `.embed--WaitingForTurn` | Waiting screen when it is not the user's turn | +| `.embed--DocumentCompleted` | Completion screen after signing | +| `.field--FieldRootContainer` | Base container for document fields | + +### Field Data Attributes + +Fields expose data attributes for state-based styling: + +| Attribute | Values | Description | +| ------------------- | ---------------------------------------------- | ------------------------------------ | +| `[data-field-type]` | `SIGNATURE`, `TEXT`, `CHECKBOX`, `RADIO`, etc. | The type of field | +| `[data-inserted]` | `true`, `false` | Whether the field has been filled | +| `[data-validate]` | `true`, `false` | Whether the field is being validated | + +### Example + +```css +/* Style signature fields */ +.field--FieldRootContainer[data-field-type='SIGNATURE'] { + background-color: rgba(0, 0, 0, 0.02); +} + +/* Style filled fields */ +.field--FieldRootContainer[data-inserted='true'] { + background-color: var(--primary); + opacity: 0.2; +} + +/* Custom widget styling */ +.embed--DocumentWidget { + background-color: #ffffff; + box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1); +} +``` + +### Additional Examples + +```css +/* Style all field containers with transitions */ +.field--FieldRootContainer { + transition: all 200ms ease; +} + +/* Custom styles for the waiting screen */ +.embed--WaitingForTurn { + background-color: #f9fafb; + padding: 2rem; +} + +/* Responsive adjustments for the document container */ +@media (min-width: 768px) { + .embed--DocumentContainer { + gap: 2rem; + } +} +``` + +--- + +## Best Practices + + + + Ensure sufficient contrast between background and foreground colors for accessibility. + + + If dark mode is not disabled, verify your variables work in both modes. + + + Align `primary` and `accent` colors with your brand for a cohesive look. + + + Use a border radius that matches your application's design system. + + + +--- + +## See Also + +- [Embedding Overview](/docs/developers/embedding) - Props reference and concepts +- [React](/docs/developers/embedding/sdks/react) - React SDK usage +- [Vue](/docs/developers/embedding/sdks/vue) - Vue SDK usage diff --git a/apps/docs/content/docs/developers/embedding/direct-links.mdx b/apps/docs/content/docs/developers/embedding/direct-links.mdx new file mode 100644 index 000000000..87e1ac75c --- /dev/null +++ b/apps/docs/content/docs/developers/embedding/direct-links.mdx @@ -0,0 +1,514 @@ +--- +title: Direct Links +description: Share a URL or embed an iframe to let users sign documents without email invitations. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + +## What Are Direct Links? + +Direct links are unique URLs tied to a template that allow anyone to: + +{/* prettier-ignore */} + + + View and sign a document without receiving an email invitation + + + Enter their own name and email address + + + Complete signature fields and submit the document + + + +When someone uses a direct link, Documenso creates a new document from the template with that person as the signer. + +### When to Use Direct Links + +- Collecting signatures from unknown recipients (forms, waivers, petitions) +- Embedding signing in your website or application +- Self-service contracts where customers initiate signing +- Public-facing agreements that anyone can sign + +### Limitations + +- Only work with templates, not individual documents +- Each link is tied to one recipient role in the template +- Recipients enter their own information (you cannot prefill recipient details) + +## Creating Direct Link Templates + +Before embedding, you need a template with direct links enabled. + +### Via the Dashboard + +{/* prettier-ignore */} + + +Go to **Templates** and create or select a template + +![Team templates](/embedding/team-templates.png) + + + +Click the three-dot menu and select **Direct link** + + +Click **Enable direct link signing** + + +Choose which recipient in your template will use the direct link + +![Enable direct link](/embedding/enable-direct-link.png) + + + +Copy the generated URL + + + +### Via the API + +Create a direct link for an existing template: + + + +```bash +# Create direct link for template +curl -X POST "https://app.documenso.com/api/v2/template/direct/create" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/json" \ + -d '{ + "templateId": 123, + "directRecipientId": 1 + }' +``` + + +```typescript +const API_TOKEN = process.env.DOCUMENSO_API_TOKEN; +const BASE_URL = 'https://app.documenso.com/api/v2'; + +const response = await fetch(`${BASE_URL}/template/direct/create`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + templateId: 123, + directRecipientId: 1, // Optional: specific recipient to use + }), +}); + +const directLink = await response.json(); +console.log('Direct link token:', directLink.token); +// URL: https://app.documenso.com/d/{token} +```` + + + +### Response + +```json +{ + "id": 456, + "token": "abc123xyz", + "templateId": 123, + "directTemplateRecipientId": 1, + "enabled": true, + "createdAt": "2025-01-15T10:00:00.000Z" +} +```` + +The direct link URL format is: + +``` +https://app.documenso.com/d/{token} +``` + +![Copy recipient token](/embedding/copy-recipient-token.png) + +--- + +## Embedding in an iframe + +Embed the signing experience directly in your application using an iframe. + +### Basic iframe Embedding + +```html + +``` + +### Responsive iframe + +```html +
+ +
+``` + +### React Component Example + +```tsx +function DocumentSigner({ token }: { token: string }) { + return ( +
+