fastify-x-signwell

Fastify plugin for SignWell e-signature API — document creation, template management, bulk sending, and webhook handling.

fastify-x-signwell

Fastify plugin for SignWell e-signature integration. Provides four namespaced service objects on fastify.xSignwell covering document creation and management, template management, bulk sending, and webhook subscription and verification.

Installation

npm install @xenterprises/fastify-xsignwell

Quick Start

import Fastify from "fastify";
import xSignwell from "@xenterprises/fastify-xsignwell";

const fastify = Fastify();

await fastify.register(xSignwell, {
  apiKey: process.env.SIGNWELL_API_KEY,
  testMode: process.env.NODE_ENV !== "production",
});

fastify.post("/sign-nda", async (request, reply) => {
  const doc = await fastify.xSignwell.documents.create({
    name: "NDA",
    recipients: [{ email: "client@example.com", name: "Client" }],
    files: [{ name: "nda.pdf", url: "https://cdn.example.com/nda.pdf" }],
  });
  return reply.send({ documentId: doc.id });
});

Options

Name	Type	Default	Required	Description
`apiKey`	`string`	—	Yes	SignWell API key.
`baseUrl`	`string`	`"https://www.signwell.com/api/v1"`	No	API base URL override.
`testMode`	`boolean`	`false`	No	Enable test mode — documents won't send real signing emails.
`active`	`boolean`	`true`	No	Set `false` to skip plugin registration entirely.

Decorator

Registers fastify.xSignwell with the following shape:

Property	Type	Description
`config`	`object`	Runtime config: `{ apiKey, baseUrl, testMode }`.
`me()`	`function`	Returns the authenticated SignWell account details.
`documents`	`object`	Document CRUD and workflow methods.
`templates`	`object`	Template management methods.
`bulkSend`	`object`	Bulk-send orchestration methods.
`webhooks`	`object`	Webhook subscription and event utilities.

Methods

Documents

documents.create — create a new document for signing
documents.createFromTemplate — instantiate a document from a saved template
documents.get — fetch one document by ID
documents.list — page through all documents
documents.send / documents.remind / documents.delete — send, remind, or delete a document
documents.getCompletedPdf / documents.getEmbeddedSigningUrl / documents.getAuditTrail — download completed PDF, get embedded signing URL, or read audit trail

Templates

templates.get — fetch a template by ID
templates.list — list all templates
templates.create — create a template
templates.update — update a template
templates.delete — delete a template
templates.getFields — get a template's fields
templates.getRecipients — get a template's recipient roles

Bulk Send

bulkSend.create / bulkSend.get / bulkSend.list / bulkSend.getCsvTemplate / bulkSend.validateCsv / bulkSend.getDocuments — send a template to many recipients at once

Webhooks

webhooks.create — register a webhook subscription
webhooks.list — list webhook subscriptions
webhooks.delete — delete a webhook subscription
webhooks.verifySignature — verify an incoming webhook signature
webhooks.parseEvent / webhooks.events — parse incoming webhook events

Error Reference

Registration fails fast with the suite-standard xsignwell: ... option errors. Method-argument errors use the [xSignwell] <service>.<method>: ... prefix. API errors are thrown with statusCode and signwellError properties attached.

Error	Cause
xsignwell: missing required option `apiKey` (string), e.g. `app.register(xSignwell, { apiKey: 'sw_...' })`	`apiKey` option missing at registration.
xsignwell: option `apiKey` must be a non-empty string, e.g. `app.register(xSignwell, { apiKey: 'sw_...' })`	`apiKey` is not a non-empty string.
xsignwell: option `baseUrl` must be a string, e.g. `app.register(xSignwell, { apiKey: 'sw_...', baseUrl: 'https://www.signwell.com/api/v1' })`	`baseUrl` option is not a string.
xsignwell: option `testMode` must be a boolean, e.g. `app.register(xSignwell, { apiKey: 'sw_...', testMode: true })`	`testMode` option is not a boolean.
xsignwell: option `active` must be a boolean, e.g. `app.register(xSignwell, { apiKey: 'sw_...', active: false })`	`active` option is not a boolean.
`[xSignwell] <service>.<method>: <param> is required`	Missing/invalid method argument (thrown before any network call).
`[xSignwell] <API message>` (with `statusCode` + `signwellError`)	SignWell API returned a non-2xx response.
`[xSignwell] Network error calling <endpoint>: <message>`	Network or connection failure.

Environment Variables

The plugin never reads process.env itself — the consumer owns env access and passes values into app.register(xSignwell, { ... }). By convention, consumers store the API key in an env var:

Variable	Description
`SIGNWELL_API_KEY`	SignWell API key. Pass its value as the `apiKey` option (e.g. `apiKey: process.env.SIGNWELL_API_KEY`).

How It Works

On registration the plugin validates all option types, builds a shared config object, and calls four setup* functions that attach service namespaces to fastify.xSignwell. All API calls go through a shared apiRequest helper that injects the X-Api-Key header, parses JSON responses, and on non-2xx responses throws with statusCode and signwellError attached. When testMode is true, the test_mode: true field is included in document and bulk-send creation payloads. Webhook signature verification uses HMAC-SHA256 with timing-safe comparison.

AI Context

package: "@xenterprises/fastify-xsignwell"
type: fastify-plugin
use-when: SignWell e-signature — document creation, template management, bulk sending, webhook handling
decorator: fastify.xSignwell (config, me, documents, templates, bulkSend, webhooks)
env: SIGNWELL_API_KEY
testMode: set true in non-production environments — documents won't send real signing emails
error-shape: { statusCode, signwellError } on API failures

Edit this pageorReport an issue

validate.carousel

Validate a carousel object against RCS constraints without throwing — returns { valid, errors }.

bulkSend.*

Send a SignWell template to many recipients at once using bulk-send — create, list, validate CSV, and inspect results.