@absolutejs/esign

Provider-neutral electronic signing for Node.js and Bun. Own agreement versions, identities, permissions, persistence, and billing in your application; swap providers through the same signing contract.

The initial adapters are @absolutejs/esign-docusign and @absolutejs/esign-dropbox-sign. Install only the adapters you use. This package has no provider SDK, database, UI framework, or implicit network initialization.

Contract

• createRequest: PDFs, signer identities, signature field placement, and an application reference.
• getRequest: current provider state and individual signer status.
• createSigningSession: short-lived access for a server-authorized signer already on that request.
• downloadCompleted: completed PDF; separate audit certificate when supported.
• cancelRequest: cancel the provider request.
• verifyWebhook: verify the provider's authentication and return a reconciliation hint.
• capabilities: embedded signing, ordered signing, cancellation, and separate audit downloads.

Signature fields use one-based pages and provider document coordinates (72 DPI). Document/signer IDs are local identifiers; persist the provider signer IDs returned by createRequest. Always authorize by your saved participant-to-provider-signer mapping, never a caller-supplied email or signer ID.

Account connections

linkedESignProvider(resolver, { ownerRef, provider, bindingId }, factory) accepts the existing @absolutejs/linked-providers resolver. It resolves the binding for that owner and supplies a fresh token callback to the adapter. The host stores and encrypts grants, refreshes tokens, and handles revocation. Provider OAuth helpers are also exported by each adapter; their caller must generate unpredictable state, bind it to the signed-in account, validate and consume it once, and persist tokens securely.

Durable workflow

1. Save an immutable document revision and SHA-256 digest (documentDigest) before sending.
2. Persist a creation operation before calling the provider. Do not automatically retry an ambiguous POST timeout; reconcile the operation before allowing another send.
3. Save provider request and signer IDs against that revision. Do not change providers after a request is sent; cancel and create a new revision instead.
4. Check ownership and recipient role before issuing a signing session.
5. Verify callback authentication, deduplicate callback IDs, and call reconcileSignatureRequest using the saved request ID and reference. Callback bodies and browser return URLs never establish completion.
6. Retrieve and persist the completed PDF and audit artifact when available. A completed request can precede PDF generation; retry artifact retrieval separately without re-sending.

Dropbox Sign's event hash authenticates event time and type, not every payload field. Re-fetching the saved request is mandatory. Preserve terminal state against out-of-order callbacks; an interrupted refresh must not erase a known completed state.

HTTP errors exclude vendor response bodies and access tokens. Creation POSTs are never automatically retried. All HTTP requests have bounded timeouts. Callback routes should enforce body-size limits and return each adapter's webhookAcknowledgement after durable processing.

Development

bun run build, bun run typecheck; adapter contract tests live in ../esign-adapters/test. Tests inject fetch and make no external requests. Live account and sandbox acceptance tests are required before enabling a provider for real agreements.