@xenterprises/fastify-xsignwell 1.1.1 → 1.2.1

package/LICENSE

@@ -0,0 +1,100 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 X Enterprises LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of X Enterprises LLC, a Washington limited liability
+company ("X Enterprises"). The Software is distributed through public
+package registries (including npm) for operational convenience only; such
+distribution does not grant any rights beyond those expressly stated below.
+
+TERMS AND CONDITIONS
+
+1. OWNERSHIP
+   All rights, title, and interest in and to the Software, including all
+   intellectual property rights, are and shall remain the exclusive property
+   of X Enterprises. No rights are granted except as expressly set forth in
+   this License.
+
+2. PERMITTED USE
+   Subject to the restrictions in Section 3, you are permitted to download,
+   install, and execute the Software solely as a dependency of:
+
+   (a) software developed, owned, or operated by X Enterprises;
+
+   (b) software that X Enterprises has developed, delivered, or licensed to
+       a third party ("Client") under a written engagement agreement with
+       X Enterprises, when such use is performed by or on behalf of that
+       Client; or
+
+   (c) end-user access to, or consumption of, a product or service described
+       in (a) or (b), provided that such access does not involve
+       redistribution, modification, or separate use of the Software.
+
+   Permitted Use includes automated installation and execution by continuous
+   integration systems, container builds, hosting platforms, and similar
+   infrastructure, to the extent necessary to support (a), (b), or (c).
+
+3. RESTRICTIONS
+   Except as expressly permitted in Section 2, and without the prior written
+   consent of X Enterprises, you may not:
+
+   (a) copy, modify, adapt, translate, or create derivative works of the
+       Software for any purpose outside the scope of Section 2;
+
+   (b) redistribute, republish, sublicense, sell, lease, rent, or otherwise
+       transfer the Software, in whole or in part, whether standalone or
+       bundled with other software;
+
+   (c) reverse engineer, decompile, disassemble, or attempt to derive the
+       source code or underlying ideas, algorithms, structure, or
+       organization of the Software, except to the extent such activity is
+       expressly permitted by applicable law notwithstanding this
+       restriction;
+
+   (d) use the Software, in whole or in part, to develop, operate, or
+       provide any product or service that competes with or substitutes for
+       any X Enterprises product or service;
+
+   (e) remove, obscure, or alter any copyright, trademark, license, or other
+       proprietary notice contained in or on the Software; or
+
+   (f) use the Software in violation of any applicable law or regulation.
+
+4. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   X ENTERPRISES BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT
+   OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+   THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL X ENTERPRISES BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. GOVERNING LAW
+   This License shall be governed by and construed in accordance with the
+   laws of the State of Washington, United States, without regard to its
+   conflict of law provisions. Exclusive jurisdiction for any dispute
+   arising out of this License shall lie in the state or federal courts
+   located in King County, Washington.
+
+7. TERMINATION
+   This License is effective until terminated. Your rights under this
+   License will terminate automatically and without notice if you fail to
+   comply with any term herein. Upon termination, you must cease all use of
+   the Software and destroy all copies in your possession or control.
+   Sections 1, 3, 4, 5, 6, and 7 survive termination.
+
+For licensing inquiries, contact: legal@x.enterprises
+
+---
+X Enterprises LLC
+Bothell, Washington, United States

package/README.md

@@ -1,333 +1,166 @@
-# xSignwell
+# @xenterprises/fastify-xsignwell
 
-A Fastify plugin for integrating with SignWell's e-signature API. Provides document creation, template management, bulk sending, and webhook handling.
+Fastify plugin for [SignWell](https://www.signwell.com/) e-signature API integration — document creation, templates, bulk sending, webhooks, and embedded signing.
 
-## Features
-
-- **Document Management**: Create, send, and track documents for signing
-- **Template Support**: Create and manage reusable document templates
-- **Embedded Signing**: Get URLs for embedded signing experiences
-- **Bulk Send**: Send documents to multiple recipients at once
-- **Webhooks**: Register and manage webhook callbacks for document events
-- **Test Mode**: Built-in support for SignWell's test mode
-
-## Installation
+## Install
 
 ```bash
-npm install xsignwell
+npm install @xenterprises/fastify-xsignwell
 ```
 
-## Configuration
-
-### Environment Variables
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `SIGNWELL_API_KEY` | SignWell API key | Yes |
-| `SIGNWELL_TEST_MODE` | Enable test mode | No |
-
-### Plugin Registration
+## Quick Start
 
 ```javascript
-import Fastify from 'fastify';
-import xSignwell from 'xsignwell';
+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',
-});
-```
-
-## Usage
-
-### Documents
-
-#### Create a Document
-
-```javascript
-const document = await fastify.xsignwell.documents.create({
-  name: 'Employment Agreement',
-  recipients: [
-    {
-      id: 'signer_1',
-      name: 'John Doe',
-      email: 'john@example.com',
-    },
-  ],
-  files: [
-    {
-      name: 'agreement.pdf',
-      url: 'https://example.com/agreement.pdf',
-      // OR use base64:
-      // base64: 'JVBERi0xLjQK...',
-    },
-  ],
-  subject: 'Please sign your employment agreement',
-  message: 'Hi John, please review and sign the attached agreement.',
-});
-```
-
-#### Create from Template
-
-```javascript
-const document = await fastify.xsignwell.documents.createFromTemplate(
-  'template_id_here',
-  {
-    recipients: [
-      {
-        id: 'signer_1', // Must match template recipient ID
-        name: 'John Doe',
-        email: 'john@example.com',
-      },
-    ],
-    fields: {
-      employee_name: 'John Doe',
-      start_date: '2025-02-01',
-      salary: '$75,000',
-    },
-  }
-);
-```
-
-#### Get Document Status
-
-```javascript
-const document = await fastify.xsignwell.documents.get('document_id');
-console.log(document.status); // 'pending', 'completed', etc.
-```
-
-#### Send a Document
-
-```javascript
-await fastify.xsignwell.documents.send('document_id');
-```
-
-#### Send Reminder
-
-```javascript
-await fastify.xsignwell.documents.remind('document_id');
-```
-
-#### Get Completed PDF
-
-```javascript
-const pdf = await fastify.xsignwell.documents.getCompletedPdf('document_id');
-// pdf.file_url contains the download URL
-```
-
-#### Get Embedded Signing URL
-
-```javascript
-const { url, recipient } = await fastify.xsignwell.documents.getEmbeddedSigningUrl(
-  'document_id',
-  'recipient_id'
-);
-// Redirect user to `url` for signing
-```
-
-#### Delete Document
-
-```javascript
-await fastify.xsignwell.documents.remove('document_id');
-```
-
-### Templates
-
-#### Get Template
-
-```javascript
-const template = await fastify.xsignwell.templates.get('template_id');
-```
-
-#### List Templates
-
-```javascript
-const templates = await fastify.xsignwell.templates.list({
-  page: 1,
-  limit: 20,
-});
-```
-
-#### Create Template
-
-```javascript
-const template = await fastify.xsignwell.templates.create({
-  name: 'NDA Template',
-  files: [
-    {
-      name: 'nda.pdf',
-      url: 'https://example.com/nda.pdf',
-    },
-  ],
-  recipients: [
-    { id: 'signer_1', name: 'Signer' },
-    { id: 'signer_2', name: 'Counter-Signer' },
-  ],
-});
-```
-
-#### Update Template
-
-```javascript
-await fastify.xsignwell.templates.update('template_id', {
-  name: 'Updated NDA Template',
-  subject: 'New subject line',
-});
-```
-
-#### Delete Template
-
-```javascript
-await fastify.xsignwell.templates.remove('template_id');
-```
-
-#### Get Template Fields
-
-```javascript
-const fields = await fastify.xsignwell.templates.getFields('template_id');
-```
-
-### Bulk Send
-
-#### Create Bulk Send
-
-```javascript
-const bulkSend = await fastify.xsignwell.bulkSend.create({
-  templateId: 'template_id',
-  recipients: [
-    {
-      email: 'john@example.com',
-      name: 'John Doe',
-      // Field values for this recipient
-      employee_name: 'John Doe',
-      start_date: '2025-02-01',
-    },
-    {
-      email: 'jane@example.com',
-      name: 'Jane Smith',
-      employee_name: 'Jane Smith',
-      start_date: '2025-02-15',
-    },
-  ],
-});
-```
-
-#### List Bulk Sends
-
-```javascript
-const bulkSends = await fastify.xsignwell.bulkSend.list();
-```
-
-#### Get Bulk Send Documents
-
-```javascript
-const documents = await fastify.xsignwell.bulkSend.getDocuments('bulk_send_id');
-```
-
-#### Get CSV Template
-
-```javascript
-const csvTemplate = await fastify.xsignwell.bulkSend.getCsvTemplate('template_id');
-```
-
-### Webhooks
-
-#### List Webhooks
-
-```javascript
-const webhooks = await fastify.xsignwell.webhooks.list();
-```
-
-#### Create Webhook
-
-```javascript
-const webhook = await fastify.xsignwell.webhooks.create({
-  callbackUrl: 'https://your-api.com/webhooks/signwell',
-  event: 'document.completed', // Optional: subscribe to specific event
+  testMode: process.env.NODE_ENV !== "production",
 });
-```
-
-#### Delete Webhook
 
-```javascript
-await fastify.xsignwell.webhooks.remove('webhook_id');
-```
-
-#### Handle Webhook Events
-
-```javascript
-fastify.post('/webhooks/signwell', async (request, reply) => {
-  const event = fastify.xsignwell.webhooks.parseEvent(request.body);
-
-  switch (event.event) {
-    case 'document.completed':
-      console.log(`Document ${event.documentId} completed`);
-      // Download the completed PDF
-      const pdf = await fastify.xsignwell.documents.getCompletedPdf(event.documentId);
-      break;
-
-    case 'document.signed':
-      console.log(`Document ${event.documentId} signed by ${event.recipient?.email}`);
-      break;
-
-    case 'document.declined':
-      console.log(`Document ${event.documentId} was declined`);
-      break;
-  }
-
-  return { received: true };
+// Create and send a document
+const doc = await fastify.xsignwell.documents.create({
+  name: "Employment Agreement",
+  recipients: [{ email: "john@example.com", name: "John Doe" }],
+  files: [{ name: "agreement.pdf", url: "https://example.com/agreement.pdf" }],
 });
 ```
 
-#### Webhook Event Types
-
-```javascript
-const events = fastify.xsignwell.webhooks.events;
-// {
-//   DOCUMENT_COMPLETED: 'document.completed',
-//   DOCUMENT_SENT: 'document.sent',
-//   DOCUMENT_VIEWED: 'document.viewed',
-//   DOCUMENT_SIGNED: 'document.signed',
-//   DOCUMENT_DECLINED: 'document.declined',
-//   DOCUMENT_EXPIRED: 'document.expired',
-//   DOCUMENT_VOIDED: 'document.voided',
-//   RECIPIENT_COMPLETED: 'recipient.completed',
-//   RECIPIENT_VIEWED: 'recipient.viewed',
-//   RECIPIENT_SIGNED: 'recipient.signed',
-//   RECIPIENT_DECLINED: 'recipient.declined',
-// }
-```
-
-### Account Info
+## Options
 
-```javascript
-const account = await fastify.xsignwell.me();
-console.log(account.email);
-```
+| Name | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `apiKey` | `string` | — | Yes | SignWell API key |
+| `baseUrl` | `string` | `https://www.signwell.com/api/v1` | No | API base URL |
+| `testMode` | `boolean` | `false` | No | Enable test mode (documents won't actually send) |
+| `active` | `boolean` | `true` | No | Set `false` to disable the plugin entirely |
 
-## API Reference
+## Environment Variables
 
-### Decorators
+| Name | Required | Description |
+|------|----------|-------------|
+| `SIGNWELL_API_KEY` | Yes | SignWell API key |
+| `SIGNWELL_TEST_MODE` | No | Set `"true"` to enable test mode |
 
-After registration, the following decorators are available on the Fastify instance:
+## Decorated Properties
 
 | Decorator | Description |
 |-----------|-------------|
+| `fastify.xsignwell.config` | Plugin configuration object |
 | `fastify.xsignwell.documents` | Document management methods |
 | `fastify.xsignwell.templates` | Template management methods |
 | `fastify.xsignwell.bulkSend` | Bulk send methods |
 | `fastify.xsignwell.webhooks` | Webhook management methods |
-| `fastify.xsignwell.me` | Get account info |
-| `fastify.xsignwell.config` | Plugin configuration |
-
-### Rate Limits
-
-SignWell API has the following rate limits:
-- Standard requests: 100 requests per 60 seconds
-- Document creation: 30 requests per minute
-- Test mode: 20 requests per minute
+| `fastify.xsignwell.me()` | Get current account info |
+
+### `documents`
+
+| Method | Description |
+|--------|-------------|
+| `create(params)` | Create a new document for signing |
+| `createFromTemplate(templateId, params)` | Create a document from a template |
+| `get(documentId)` | Get document details by ID |
+| `list(params?)` | List documents (page, limit) |
+| `send(documentId, params?)` | Send a draft document |
+| `remind(documentId)` | Send reminder to unsigned recipients |
+| `remove(documentId)` | Delete a document |
+| `getCompletedPdf(documentId)` | Get download URL for completed PDF |
+| `getEmbeddedSigningUrl(documentId, recipientId)` | Get embedded signing URL |
+| `getAuditTrail(documentId)` | Get document audit trail |
+
+### `templates`
+
+| Method | Description |
+|--------|-------------|
+| `get(templateId)` | Get template by ID |
+| `create(params)` | Create a new template |
+| `update(templateId, params)` | Update an existing template |
+| `remove(templateId)` | Delete a template |
+| `list(params?)` | List all templates (page, limit) |
+| `getFields(templateId)` | Get template field definitions |
+| `getRecipients(templateId)` | Get template recipient placeholders |
+
+### `bulkSend`
+
+| Method | Description |
+|--------|-------------|
+| `get(bulkSendId)` | Get bulk send by ID |
+| `list(params?)` | List all bulk sends (page, limit) |
+| `create(params)` | Create a bulk send from a template |
+| `getCsvTemplate(templateId)` | Get CSV template for bulk upload |
+| `validateCsv(templateId, csvContent)` | Validate CSV before sending |
+| `getDocuments(bulkSendId, params?)` | Get documents from a bulk send |
+
+### `webhooks`
+
+| Method | Description |
+|--------|-------------|
+| `list()` | List all webhooks |
+| `create(params)` | Create a new webhook |
+| `remove(webhookId)` | Delete a webhook |
+| `events` | Event type constants (see below) |
+| `verifySignature(payload, signature, secret)` | Verify webhook HMAC-SHA256 signature |
+| `parseEvent(payload)` | Parse webhook payload into structured event |
+
+#### Webhook Event Constants
+
+```javascript
+fastify.xsignwell.webhooks.events.DOCUMENT_COMPLETED  // "document.completed"
+fastify.xsignwell.webhooks.events.DOCUMENT_SENT       // "document.sent"
+fastify.xsignwell.webhooks.events.DOCUMENT_VIEWED     // "document.viewed"
+fastify.xsignwell.webhooks.events.DOCUMENT_SIGNED     // "document.signed"
+fastify.xsignwell.webhooks.events.DOCUMENT_DECLINED   // "document.declined"
+fastify.xsignwell.webhooks.events.DOCUMENT_EXPIRED    // "document.expired"
+fastify.xsignwell.webhooks.events.DOCUMENT_VOIDED     // "document.voided"
+fastify.xsignwell.webhooks.events.RECIPIENT_COMPLETED // "recipient.completed"
+fastify.xsignwell.webhooks.events.RECIPIENT_VIEWED    // "recipient.viewed"
+fastify.xsignwell.webhooks.events.RECIPIENT_SIGNED    // "recipient.signed"
+fastify.xsignwell.webhooks.events.RECIPIENT_DECLINED  // "recipient.declined"
+```
+
+## Error Reference
+
+All errors thrown by the plugin are prefixed with `[xSignwell]`.
+
+| Error | When |
+|-------|------|
+| `[xSignwell] apiKey is required` | Plugin registered without `apiKey` option |
+| `[xSignwell] apiKey must be a string` | `apiKey` is not a string |
+| `[xSignwell] baseUrl must be a string` | `baseUrl` is not a string |
+| `[xSignwell] testMode must be a boolean` | `testMode` is not a boolean |
+| `[xSignwell] documents.create: name (string) is required` | `create()` called without `name` |
+| `[xSignwell] documents.create: recipients (non-empty array) is required` | `create()` missing recipients |
+| `[xSignwell] documents.create: each recipient must have an email` | Recipient without email field |
+| `[xSignwell] <service>.<method>: <param> is required` | Any method called with missing required param |
+| `[xSignwell] Recipient <id> not found in document <id>` | `getEmbeddedSigningUrl` can't find recipient |
+| `[xSignwell] API error: <status>` | SignWell API returned a non-2xx response |
+| `[xSignwell] Network error calling <endpoint>: <message>` | Network/connection failure |
+
+API errors include `statusCode` and `signwellError` properties on the Error object for programmatic handling:
+
+```javascript
+try {
+  await fastify.xsignwell.documents.get("bad_id");
+} catch (err) {
+  console.log(err.statusCode);    // 404
+  console.log(err.signwellError);  // { message: "Document not found" }
+}
+```
+
+## How It Works
+
+The plugin registers a single `xsignwell` decorator on the Fastify instance. On startup it validates options (apiKey type, baseUrl type, testMode type) and builds a config object. Four service modules (documents, templates, webhooks, bulkSend) attach their methods to sub-objects on the decorator.
+
+All API calls go through a shared `apiRequest` helper that:
+1. Adds the `X-Api-Key` header from config
+2. Parses JSON responses (handles empty bodies for DELETE)
+3. On non-2xx responses, attaches `statusCode` and `signwellError` to the thrown Error
+4. On network failures, wraps with `[xSignwell] Network error` message
+
+The plugin uses `fastify-plugin` with `fastify >=5.0.0` constraint so the decorator is visible across all scopes. The `testMode` config flag is passed as `test_mode` in document/bulk-send creation payloads so SignWell won't actually deliver signing emails.
 
 ## Testing
 
@@ -335,6 +168,8 @@ SignWell API has the following rate limits:
 npm test
 ```
 
+82 tests covering plugin registration, startup validation, all document/template/webhook/bulk-send methods (happy path + input validation + error propagation), webhook signature verification, and network error handling.
+
 ## License
 
-MIT
+UNLICENSED