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 / documents.list — fetch one document or 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

Error Reference

All errors use the [xSignwell] prefix. API errors are thrown with statusCode and signwellError properties attached.

Error	Cause
`[xSignwell] apiKey is required`	`apiKey` option missing at startup.
`[xSignwell] apiKey must be a string`	`apiKey` option is not a string.
`[xSignwell] baseUrl must be a string`	`baseUrl` option is not a string.
`[xSignwell] testMode must be a boolean`	`testMode` option is not a boolean.
`[xSignwell] API error: <status>`	SignWell API returned a non-2xx response.
`[xSignwell] Network error calling <endpoint>: <message>`	Network or connection failure.

Environment Variables

Variable	Required	Description
`SIGNWELL_API_KEY`	Yes	SignWell API key. Pass as `apiKey` option.

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.