feat(docusign): add DocuSign e-signature integration

[waleedlatif1]

Summary

• Add DocuSign e-signature integration with 8 tools: send envelope, create from template, get envelope, list envelopes, void envelope, download document, list templates, list recipients
• Internal API route handles per-account base URI resolution via DocuSign userinfo endpoint
• OAuth config with Basic auth for token endpoint, signature + extended scopes
• File upload support for sending documents via envelopes
• Docs page with manual intro description

Type of Change

• New feature

Testing

Tested manually

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Mar 19, 2026 5:02am

[cursor]

PR Summary

Medium Risk
Adds a new OAuth provider and internal API route that handles DocuSign access tokens and document downloads/uploads, which introduces new external API and file-handling paths. Risk is mitigated by being mostly additive and scoped to the new docusign integration surface.

Overview
Adds a new DocuSign integration across Sim and Docs, including a DocuSignBlock and eight new docusign_* tools for sending envelopes (including optional uploaded documents), creating from templates, querying/listing envelopes, listing templates/recipients, voiding envelopes, and downloading signed documents as base64.

Introduces a new internal endpoint POST /api/tools/docusign that resolves the user’s DocuSign accountId/baseUri via userinfo and proxies the supported operations to DocuSign’s REST API with basic validation and error handling.

Wires DocuSign into OAuth configuration (new env vars, provider/service registration, scopes, token endpoint settings), adds DocuSignIcon + icon mapping, registers the block/tools in registries, and adds a new docs page tools/docusign.

^{Written by Cursor Bugbot for commit b0fe286. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a full DocuSign e-signature integration with 8 tools (send envelope, create from template, get/list/void envelope, download document, list templates, list recipients), an internal API route that resolves per-account base URIs, OAuth provider registration in BetterAuth, and documentation.

Key findings:

• Critical:getUserInfo in auth.ts constructs the user id as `${data.sub}-${crypto.randomUUID()}`, making it non-deterministic. Every OAuth callback — including re-authorizations and token refreshes — will produce a different ID, causing a new database user record to be created each time instead of matching the existing credential. The ID should be just data.sub (or a deterministic composite).
• Significant:handleSendEnvelope places signature tabs using hardcoded anchor strings /sig1/ and /date1/. Documents that don't contain these strings will be sent without any visible signing location; DocuSign won't raise an error, so users receive a silent, unresolvable failure. This dependency is undocumented in the UI.
• Minor:getUserInfo catches all errors and returns null rather than re-throwing, which masks OAuth flow failures with an opaque silent error instead of surfacing a meaningful message.

Confidence Score: 2/5

• Not safe to merge — the non-deterministic user ID in getUserInfo will create duplicate database records on every DocuSign OAuth connection.
• The overall integration is well-structured and the tool/block/route layers are solid, but the crypto.randomUUID() suffix in auth.ts is a functional correctness bug that will break credential deduplication for every DocuSign user. This needs to be fixed before the PR can ship.
• apps/sim/lib/auth/auth.ts requires immediate attention for the non-deterministic user ID; apps/sim/app/api/tools/docusign/route.ts should address the silent anchor-string failure mode.

Important Files Changed

Filename	Overview
apps/sim/lib/auth/auth.ts	Adds DocuSign OAuth provider config; contains a critical bug where getUserInfo appends crypto.randomUUID() to the user ID, causing a new database record on every OAuth callback, and silently returns null on errors instead of re-throwing.
apps/sim/app/api/tools/docusign/route.ts	New internal API route handling all 8 DocuSign operations; resolves base URI via userinfo endpoint, has proper guards for missing documents and base_uri; signature tab placement relies on undocumented hardcoded anchor strings that silently produce no-tab envelopes when absent from the document.
apps/sim/blocks/blocks/docusign.ts	Well-structured block config with correct operation routing, OAuth credential wiring, and conditional field visibility; parameter mapping logic is correct but complex due to two separate status fields for different operations.
apps/sim/tools/docusign/types.ts	Clean type definitions with shared output property constants; all params and response interfaces are well-typed and consistent.
apps/sim/tools/docusign/send-envelope.ts	Tool config for sending envelopes; correctly routes to internal API, handles file uploads, and surfaces errors from the route layer.
apps/sim/lib/oauth/oauth.ts	Adds DocuSign OAuth provider config with correct signature + extended scopes and useBasicAuth: true for token endpoint; consistent with other providers.
apps/sim/tools/docusign/create-from-template.ts	Clean tool config for template-based envelope creation; correctly handles JSON templateRoles string parsing.
apps/sim/tools/docusign/list-envelopes.ts	Lists envelopes with optional filters; maps DocuSign response correctly and defaults totalSetSize and resultSetSize gracefully.
apps/sim/tools/docusign/download-document.ts	Downloads envelope documents as base64; correctly defaults to "combined" document ID and propagates mime type and file name.

Sequence Diagram

sequenceDiagram
participant Agent as Sim Agent
participant Tool as Tool Layer
participant Route as /api/tools/docusign
participant UserInfo as DocuSign /oauth/userinfo
participant API as DocuSign REST API
Agent->>Tool: invoke docusign_<operation>
Tool->>Route: POST { accessToken, operation, ...params }
Route->>UserInfo: GET /oauth/userinfo (Bearer token)
UserInfo-->>Route: { accounts: [{ account_id, base_uri }] }
Route->>Route: build apiBase from base_uri + account_id
alt operation = send_envelope
Route->>Route: parse file → base64
Route->>API: POST /envelopes (with document + recipient tabs)
else operation = create_from_template
Route->>API: POST /envelopes (templateId + templateRoles)
else operation = get/list/void/download/list_templates/list_recipients
Route->>API: GET or PUT on /envelopes endpoint
end
API-->>Route: response JSON / binary
Route-->>Tool: NextResponse.json(data)
Tool-->>Agent: transformed output

Loading

Comments Outside Diff (3)

1. apps/sim/lib/auth/auth.ts, line 1257 (link)

   Non-deterministic user ID breaks credential deduplication

   crypto.randomUUID() is appended to data.sub to form the user id. Because getUserInfo is called on every OAuth callback (token exchange, re-authorization, token refresh), each connection attempt produces a different ID. BetterAuth uses this id to look up or upsert the user record — a new unique ID on every call means a fresh database row is created on every DocuSign connect, making it impossible to match an existing credential to a returning user.

   Every other provider in this file uses a stable, deterministic identifier (e.g. the provider's own sub / account ID). Use data.sub alone, or a deterministic composite such as ${data.sub}-${defaultAccount?.account_id} if account-scoping is needed:

2. apps/sim/app/api/tools/docusign/route.ts, line 457-474 (link)

   Hardcoded anchor strings silently produce envelopes with no signing tabs

   signHereTabs and dateSignedTabs are placed using the anchor strings /sig1/ and /date1/. If the uploaded document does not contain these exact literal strings, DocuSign will accept the envelope (no API error is raised for missing anchors by default) but the signing tab will simply not appear. The signer receives an envelope with no visible place to sign, which is a confusing dead-end UX.

   Consider either:

   1. Falling back to absolute position-based tabs when anchors are not present, or
   2. Documenting the anchor requirement prominently in the UI placeholder / tooltip, or
   3. Passing explicit page/position coordinates as optional user inputs.

3. apps/sim/lib/auth/auth.ts, line 1265-1268 (link)

   getUserInfo swallows errors and returns null, masking OAuth failures

   The outer catch block logs the error and returns null. In BetterAuth, a null return from getUserInfo causes the OAuth callback to fail without a meaningful user-facing error. Re-throwing the error allows the framework to surface a proper error response instead of producing a silent, opaque failure:

_{Last reviewed commit: "fix(docusign): valid..."}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[waleedlatif1]

@greptile

[waleedlatif1]

@greptile

[waleedlatif1]

Addressing latest review feedback

P0 — Non-deterministic user ID (crypto.randomUUID())
This is a false positive. Every single OAuth provider in this codebase (Google, Microsoft, Slack, HubSpot, Salesforce, GitHub, LinkedIn, Notion, etc. — 40+ providers) uses the exact same ${sub}-${crypto.randomUUID()} pattern in getUserInfo. This is by design — the id returned from getUserInfo is used to create a new account record in the oauth accounts table, not to match existing users. User matching is handled by the auth framework via providerId + token metadata, not this id field. Changing this would deviate from the established codebase convention.

P1 — Empty templateRoles array sent to DocuSign
The block config already marks templateRoles as required for the create_from_template operation, so the executor will reject the request before it reaches the route. Adding a redundant server-side check for a field that can never be empty in practice is unnecessary. DocuSign's API error (INVALID_REQUEST_BODY) is also descriptive enough if the route is somehow called directly.

P2 — envelopeId not validated as UUID format
This is over-engineering. DocuSign will return a clear 400 error with a descriptive message if the envelope ID format is invalid. Adding UUID regex validation on our side adds no real value — it just duplicates validation that the downstream API already performs. The .trim() call handles the only realistic user input issue (trailing whitespace).

@greptile