@xenterprises/fastify-xsignwell 1.0.0

package/.gitlab-ci.yml

@@ -0,0 +1,45 @@
+# ============================================================================
+# GitLab CI/CD Pipeline - xSignwell
+# ============================================================================
+# Runs tests on merge requests and commits to main/master
+
+stages:
+  - test
+
+variables:
+  NODE_ENV: test
+
+# ============================================================================
+# Shared Configuration
+# ============================================================================
+.shared_rules: &shared_rules
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "master"'
+    - if: '$CI_COMMIT_TAG'
+
+# ============================================================================
+# STAGE: TEST
+# ============================================================================
+test:
+  stage: test
+  image: node:20-alpine
+  <<: *shared_rules
+
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+
+  before_script:
+    - npm ci
+
+  script:
+    - echo "Running xSignwell tests..."
+    - npm test
+    - npm audit --audit-level=high || true
+
+  retry:
+    max: 2
+    when: runner_system_failure

package/README.md

@@ -0,0 +1,340 @@
+# xSignwell
+
+A Fastify plugin for integrating with SignWell's e-signature API. Provides document creation, template management, bulk sending, and webhook handling.
+
+## 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
+
+```bash
+npm install xsignwell
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `SIGNWELL_API_KEY` | SignWell API key | Yes |
+| `SIGNWELL_TEST_MODE` | Enable test mode | No |
+
+### Plugin Registration
+
+```javascript
+import Fastify from 'fastify';
+import xSignwell from '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
+});
+```
+
+#### 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 };
+});
+```
+
+#### 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
+
+```javascript
+const account = await fastify.xsignwell.me();
+console.log(account.email);
+```
+
+## API Reference
+
+### Decorators
+
+After registration, the following decorators are available on the Fastify instance:
+
+| Decorator | Description |
+|-----------|-------------|
+| `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
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+ "name": "@xenterprises/fastify-xsignwell",
+  "version": "1.0.0",
+  "description": "Fastify plugin for SignWell document signing API integration",
+  "type": "module",
+  "main": "src/xSignwell.js",
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/xSignwell.test.js",
+    "lint": "eslint src/ test/"
+  },
+  "keywords": [
+    "fastify",
+    "signwell",
+    "esignature",
+    "document-signing",
+    "pdf",
+    "api"
+  ],
+  "author": "X Enterprises",
+  "license": "MIT",
+  "dependencies": {
+    "fastify-plugin": "^5.0.1"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "fastify": "^5.0.0"
+  }
+}

package/src/services/bulkSend.js

@@ -0,0 +1,179 @@
+/**
+ * SignWell Bulk Send Service
+ *
+ * Handles bulk document sending operations.
+ *
+ * @see https://developers.signwell.com/reference/get_api-v1-bulk-sends-id
+ */
+
+/**
+ * Setup bulk send service
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} config - Plugin configuration
+ */
+export async function setupBulkSend(fastify, config) {
+  const { apiKey, baseUrl, testMode } = config;
+
+  /**
+   * Make an API request to SignWell
+   * @param {string} endpoint - API endpoint
+   * @param {Object} options - Fetch options
+   * @returns {Promise<Object>} API response
+   */
+  async function apiRequest(endpoint, options = {}) {
+    const url = `${baseUrl}${endpoint}`;
+    const headers = {
+      "X-Api-Key": apiKey,
+      "Content-Type": "application/json",
+      ...options.headers,
+    };
+
+    const response = await fetch(url, {
+      ...options,
+      headers,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorData;
+      try {
+        errorData = JSON.parse(errorText);
+      } catch {
+        errorData = { message: errorText };
+      }
+      fastify.log.error({ endpoint, status: response.status, error: errorData }, "SignWell API error");
+      throw new Error(errorData.message || `SignWell API error: ${response.status}`);
+    }
+
+    const text = await response.text();
+    if (!text) return { success: true };
+
+    return JSON.parse(text);
+  }
+
+  /**
+   * Get a bulk send by ID
+   * @param {string} bulkSendId - Bulk send ID
+   * @returns {Promise<Object>} Bulk send details
+   */
+  async function get(bulkSendId) {
+    return apiRequest(`/bulk_sends/${bulkSendId}`, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * List all bulk sends
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page] - Page number
+   * @param {number} [params.limit] - Items per page
+   * @returns {Promise<Object>} List of bulk sends
+   */
+  async function list(params = {}) {
+    const queryParams = new URLSearchParams();
+    if (params.page) queryParams.set("page", params.page);
+    if (params.limit) queryParams.set("limit", params.limit);
+
+    const queryString = queryParams.toString();
+    const endpoint = `/bulk_sends${queryString ? `?${queryString}` : ""}`;
+
+    return apiRequest(endpoint, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Create a bulk send
+   * @param {Object} params - Bulk send parameters
+   * @param {string} params.templateId - Template ID to use
+   * @param {Array<Object>} params.recipients - List of recipient data
+   * @param {string} [params.subject] - Email subject
+   * @param {string} [params.message] - Email message
+   * @returns {Promise<Object>} Created bulk send
+   */
+  async function create(params) {
+    const {
+      templateId,
+      recipients,
+      subject,
+      message,
+      ...rest
+    } = params;
+
+    const body = {
+      document_template_id: templateId,
+      bulk_send_rows: recipients,
+      test_mode: testMode || params.testMode,
+      ...rest,
+    };
+
+    if (subject) body.subject = subject;
+    if (message) body.message = message;
+
+    return apiRequest("/bulk_sends", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Get CSV template for bulk send
+   * @param {string} templateId - Template ID
+   * @returns {Promise<Object>} CSV template info
+   */
+  async function getCsvTemplate(templateId) {
+    return apiRequest(`/bulk_sends/csv_template?document_template_id=${templateId}`, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Validate CSV for bulk send
+   * @param {string} templateId - Template ID
+   * @param {string} csvContent - CSV content (base64 or raw)
+   * @returns {Promise<Object>} Validation result
+   */
+  async function validateCsv(templateId, csvContent) {
+    return apiRequest("/bulk_sends/validate_csv", {
+      method: "POST",
+      body: JSON.stringify({
+        document_template_id: templateId,
+        csv: csvContent,
+      }),
+    });
+  }
+
+  /**
+   * Get documents from a bulk send
+   * @param {string} bulkSendId - Bulk send ID
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page] - Page number
+   * @param {number} [params.limit] - Items per page
+   * @returns {Promise<Object>} List of documents
+   */
+  async function getDocuments(bulkSendId, params = {}) {
+    const queryParams = new URLSearchParams();
+    if (params.page) queryParams.set("page", params.page);
+    if (params.limit) queryParams.set("limit", params.limit);
+
+    const queryString = queryParams.toString();
+    const endpoint = `/bulk_sends/${bulkSendId}/documents${queryString ? `?${queryString}` : ""}`;
+
+    return apiRequest(endpoint, {
+      method: "GET",
+    });
+  }
+
+  // Add bulk send service to xsignwell namespace
+  fastify.xsignwell.bulkSend = {
+    get,
+    list,
+    create,
+    getCsvTemplate,
+    validateCsv,
+    getDocuments,
+  };
+
+  console.info("      • Bulk Send Service initialized");
+}