@xenterprises/fastify-xsignwell 1.0.0

package/src/services/documents.js

@@ -0,0 +1,251 @@
+/**
+ * SignWell Documents Service
+ *
+ * Handles document creation, retrieval, sending, and management.
+ *
+ * @see https://developers.signwell.com/reference/post_api-v1-documents
+ */
+
+/**
+ * Setup documents service
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} config - Plugin configuration
+ */
+export async function setupDocuments(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}`);
+    }
+
+    // Handle empty responses (like DELETE)
+    const text = await response.text();
+    if (!text) return { success: true };
+
+    return JSON.parse(text);
+  }
+
+  /**
+   * Create a new document for signing
+   * @param {Object} params - Document parameters
+   * @param {string} params.name - Document name
+   * @param {Array<Object>} params.recipients - List of recipients
+   * @param {Array<Object>} [params.files] - Files to include (base64 or URL)
+   * @param {boolean} [params.draft] - Create as draft (default: false)
+   * @param {boolean} [params.testMode] - Use test mode
+   * @param {string} [params.subject] - Email subject
+   * @param {string} [params.message] - Email message
+   * @param {Object} [params.metadata] - Custom metadata
+   * @returns {Promise<Object>} Created document
+   */
+  async function create(params) {
+    const {
+      name,
+      recipients,
+      files,
+      draft = false,
+      subject,
+      message,
+      metadata,
+      ...rest
+    } = params;
+
+    const body = {
+      name,
+      recipients: recipients.map((r) => ({
+        id: r.id || `recipient_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+        email: r.email,
+        name: r.name,
+        send_email: r.sendEmail !== false,
+        ...r,
+      })),
+      test_mode: testMode || params.testMode,
+      draft,
+      ...rest,
+    };
+
+    if (files) {
+      body.files = files.map((f) => ({
+        name: f.name,
+        file_base64: f.base64 || f.file_base64,
+        file_url: f.url || f.file_url,
+      }));
+    }
+
+    if (subject) body.subject = subject;
+    if (message) body.message = message;
+    if (metadata) body.metadata = metadata;
+
+    return apiRequest("/documents", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Create a document from a template
+   * @param {string} templateId - Template ID
+   * @param {Object} params - Document parameters
+   * @param {Array<Object>} params.recipients - List of recipients
+   * @param {Object} [params.fields] - Field values to pre-fill
+   * @param {boolean} [params.draft] - Create as draft
+   * @param {string} [params.subject] - Email subject
+   * @param {string} [params.message] - Email message
+   * @param {Object} [params.metadata] - Custom metadata
+   * @returns {Promise<Object>} Created document
+   */
+  async function createFromTemplate(templateId, params) {
+    const {
+      recipients,
+      fields,
+      draft = false,
+      subject,
+      message,
+      metadata,
+      ...rest
+    } = params;
+
+    const body = {
+      recipients: recipients.map((r) => ({
+        id: r.id,
+        email: r.email,
+        name: r.name,
+        send_email: r.sendEmail !== false,
+        ...r,
+      })),
+      test_mode: testMode || params.testMode,
+      draft,
+      ...rest,
+    };
+
+    if (fields) body.fields = fields;
+    if (subject) body.subject = subject;
+    if (message) body.message = message;
+    if (metadata) body.metadata = metadata;
+
+    return apiRequest(`/document_templates/${templateId}/documents`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Get a document by ID
+   * @param {string} documentId - Document ID
+   * @returns {Promise<Object>} Document details
+   */
+  async function get(documentId) {
+    return apiRequest(`/documents/${documentId}`, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Send a document (or update and send)
+   * @param {string} documentId - Document ID
+   * @param {Object} [params] - Optional updates before sending
+   * @returns {Promise<Object>} Updated document
+   */
+  async function send(documentId, params = {}) {
+    return apiRequest(`/documents/${documentId}/send`, {
+      method: "POST",
+      body: JSON.stringify(params),
+    });
+  }
+
+  /**
+   * Send a reminder to recipients who haven't signed
+   * @param {string} documentId - Document ID
+   * @returns {Promise<Object>} Result
+   */
+  async function remind(documentId) {
+    return apiRequest(`/documents/${documentId}/remind`, {
+      method: "POST",
+    });
+  }
+
+  /**
+   * Delete a document
+   * @param {string} documentId - Document ID
+   * @returns {Promise<Object>} Result
+   */
+  async function remove(documentId) {
+    return apiRequest(`/documents/${documentId}`, {
+      method: "DELETE",
+    });
+  }
+
+  /**
+   * Download the completed PDF
+   * @param {string} documentId - Document ID
+   * @returns {Promise<Object>} PDF URL or base64 data
+   */
+  async function getCompletedPdf(documentId) {
+    return apiRequest(`/documents/${documentId}/completed_pdf`, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Get signing URL for embedded signing
+   * @param {string} documentId - Document ID
+   * @param {string} recipientId - Recipient ID
+   * @returns {Promise<Object>} Embedded signing URL
+   */
+  async function getEmbeddedSigningUrl(documentId, recipientId) {
+    const document = await get(documentId);
+    const recipient = document.recipients?.find((r) => r.id === recipientId);
+
+    if (!recipient) {
+      throw new Error(`Recipient ${recipientId} not found in document`);
+    }
+
+    return {
+      url: recipient.embedded_signing_url,
+      recipient,
+    };
+  }
+
+  // Add documents service to xsignwell namespace
+  fastify.xsignwell.documents = {
+    create,
+    createFromTemplate,
+    get,
+    send,
+    remind,
+    remove,
+    delete: remove, // Alias
+    getCompletedPdf,
+    getEmbeddedSigningUrl,
+  };
+
+  console.info("      • Documents Service initialized");
+}

package/src/services/templates.js

@@ -0,0 +1,196 @@
+/**
+ * SignWell Templates Service
+ *
+ * Handles template creation, retrieval, updating, and management.
+ *
+ * @see https://developers.signwell.com/reference/get_api-v1-document-templates-id
+ */
+
+/**
+ * Setup templates service
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} config - Plugin configuration
+ */
+export async function setupTemplates(fastify, config) {
+  const { apiKey, baseUrl } = 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 template by ID
+   * @param {string} templateId - Template ID
+   * @returns {Promise<Object>} Template details
+   */
+  async function get(templateId) {
+    return apiRequest(`/document_templates/${templateId}`, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Create a new template
+   * @param {Object} params - Template parameters
+   * @param {string} params.name - Template name
+   * @param {Array<Object>} [params.files] - Files to include (base64 or URL)
+   * @param {Array<Object>} [params.recipients] - Recipient placeholders
+   * @param {Array<Object>} [params.fields] - Field definitions
+   * @param {string} [params.subject] - Default email subject
+   * @param {string} [params.message] - Default email message
+   * @returns {Promise<Object>} Created template
+   */
+  async function create(params) {
+    const {
+      name,
+      files,
+      recipients,
+      fields,
+      subject,
+      message,
+      ...rest
+    } = params;
+
+    const body = {
+      name,
+      ...rest,
+    };
+
+    if (files) {
+      body.files = files.map((f) => ({
+        name: f.name,
+        file_base64: f.base64 || f.file_base64,
+        file_url: f.url || f.file_url,
+      }));
+    }
+
+    if (recipients) {
+      body.recipients = recipients.map((r) => ({
+        id: r.id,
+        name: r.name || r.placeholder_name,
+        ...r,
+      }));
+    }
+
+    if (fields) body.fields = fields;
+    if (subject) body.subject = subject;
+    if (message) body.message = message;
+
+    return apiRequest("/document_templates", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Update an existing template
+   * @param {string} templateId - Template ID
+   * @param {Object} params - Update parameters
+   * @returns {Promise<Object>} Updated template
+   */
+  async function update(templateId, params) {
+    return apiRequest(`/document_templates/${templateId}`, {
+      method: "PUT",
+      body: JSON.stringify(params),
+    });
+  }
+
+  /**
+   * Delete a template
+   * @param {string} templateId - Template ID
+   * @returns {Promise<Object>} Result
+   */
+  async function remove(templateId) {
+    return apiRequest(`/document_templates/${templateId}`, {
+      method: "DELETE",
+    });
+  }
+
+  /**
+   * List all templates
+   * @param {Object} [params] - Query parameters
+   * @param {number} [params.page] - Page number
+   * @param {number} [params.limit] - Items per page
+   * @returns {Promise<Object>} List of templates
+   */
+  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 = `/document_templates${queryString ? `?${queryString}` : ""}`;
+
+    return apiRequest(endpoint, {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Get template fields (for pre-filling)
+   * @param {string} templateId - Template ID
+   * @returns {Promise<Array>} List of fields
+   */
+  async function getFields(templateId) {
+    const template = await get(templateId);
+    return template.fields || [];
+  }
+
+  /**
+   * Get template recipients (placeholders)
+   * @param {string} templateId - Template ID
+   * @returns {Promise<Array>} List of recipient placeholders
+   */
+  async function getRecipients(templateId) {
+    const template = await get(templateId);
+    return template.recipients || [];
+  }
+
+  // Add templates service to xsignwell namespace
+  fastify.xsignwell.templates = {
+    get,
+    create,
+    update,
+    remove,
+    delete: remove, // Alias
+    list,
+    getFields,
+    getRecipients,
+  };
+
+  console.info("      • Templates Service initialized");
+}

package/src/services/webhooks.js

@@ -0,0 +1,172 @@
+/**
+ * SignWell Webhooks Service
+ *
+ * Handles webhook registration, management, and event processing.
+ *
+ * @see https://developers.signwell.com/reference/get_api-v1-hooks
+ */
+
+/**
+ * Setup webhooks service
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} config - Plugin configuration
+ */
+export async function setupWebhooks(fastify, config) {
+  const { apiKey, baseUrl } = 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);
+  }
+
+  /**
+   * List all webhooks
+   * @returns {Promise<Array>} List of webhooks
+   */
+  async function list() {
+    return apiRequest("/hooks", {
+      method: "GET",
+    });
+  }
+
+  /**
+   * Create a new webhook
+   * @param {Object} params - Webhook parameters
+   * @param {string} params.callbackUrl - URL to receive webhook events
+   * @param {string} [params.event] - Event type to subscribe to
+   * @returns {Promise<Object>} Created webhook
+   */
+  async function create(params) {
+    const { callbackUrl, event, ...rest } = params;
+
+    const body = {
+      callback_url: callbackUrl,
+      ...rest,
+    };
+
+    if (event) body.event = event;
+
+    return apiRequest("/hooks", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Delete a webhook
+   * @param {string} webhookId - Webhook ID
+   * @returns {Promise<Object>} Result
+   */
+  async function remove(webhookId) {
+    return apiRequest(`/hooks/${webhookId}`, {
+      method: "DELETE",
+    });
+  }
+
+  /**
+   * Webhook event types
+   */
+  const 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",
+  };
+
+  /**
+   * Verify webhook signature (if SignWell provides one)
+   * @param {string} payload - Raw request body
+   * @param {string} signature - Signature header value
+   * @param {string} secret - Webhook secret
+   * @returns {boolean} True if valid
+   */
+  function verifySignature(payload, signature, secret) {
+    // SignWell may use HMAC-SHA256 for webhook signatures
+    // This is a placeholder - implement based on SignWell's actual signature method
+    if (!signature || !secret) return true; // No signature verification if not configured
+
+    try {
+      const crypto = require("crypto");
+      const expectedSignature = crypto
+        .createHmac("sha256", secret)
+        .update(payload)
+        .digest("hex");
+      return crypto.timingSafeEqual(
+        Buffer.from(signature),
+        Buffer.from(expectedSignature)
+      );
+    } catch (error) {
+      fastify.log.error({ error }, "Failed to verify webhook signature");
+      return false;
+    }
+  }
+
+  /**
+   * Parse webhook event payload
+   * @param {Object} payload - Webhook payload
+   * @returns {Object} Parsed event data
+   */
+  function parseEvent(payload) {
+    return {
+      event: payload.event || payload.type,
+      documentId: payload.document?.id || payload.document_id,
+      document: payload.document,
+      recipient: payload.recipient,
+      timestamp: payload.timestamp || new Date().toISOString(),
+      raw: payload,
+    };
+  }
+
+  // Add webhooks service to xsignwell namespace
+  fastify.xsignwell.webhooks = {
+    list,
+    create,
+    remove,
+    delete: remove, // Alias
+    events,
+    verifySignature,
+    parseEvent,
+  };
+
+  console.info("      • Webhooks Service initialized");
+}

package/src/xSignwell.js

@@ -0,0 +1,82 @@
+/**
+ * xSignwell - SignWell Document Signing Integration
+ *
+ * A Fastify plugin for integrating with SignWell's e-signature API.
+ * Provides document creation, template management, and webhook handling.
+ *
+ * @see https://developers.signwell.com/reference/getting-started-with-your-api-1
+ */
+
+import fp from "fastify-plugin";
+import { setupDocuments } from "./services/documents.js";
+import { setupTemplates } from "./services/templates.js";
+import { setupWebhooks } from "./services/webhooks.js";
+import { setupBulkSend } from "./services/bulkSend.js";
+
+/**
+ * xSignwell Plugin
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {string} options.apiKey - SignWell API key (required)
+ * @param {string} [options.baseUrl] - API base URL (default: https://www.signwell.com/api/v1)
+ * @param {boolean} [options.testMode] - Enable test mode (default: false)
+ * @param {boolean} [options.active] - Enable/disable the plugin (default: true)
+ */
+async function xSignwell(fastify, options) {
+  // Check if plugin is disabled
+  if (options.active === false) {
+    console.info("   ⏸️  xSignwell Disabled");
+    return;
+  }
+
+  // Validate required configuration
+  if (!options.apiKey) {
+    throw new Error("xSignwell: apiKey is required");
+  }
+
+  const config = {
+    apiKey: options.apiKey,
+    baseUrl: options.baseUrl || "https://www.signwell.com/api/v1",
+    testMode: options.testMode || false,
+  };
+
+  // Store configuration on fastify instance
+  fastify.decorate("xsignwell", {
+    config,
+  });
+
+  // Setup services
+  await setupDocuments(fastify, config);
+  await setupTemplates(fastify, config);
+  await setupWebhooks(fastify, config);
+  await setupBulkSend(fastify, config);
+
+  // Add utility method to get current user/account info
+  fastify.xsignwell.me = async function () {
+    const response = await fetch(`${config.baseUrl}/me`, {
+      method: "GET",
+      headers: {
+        "X-Api-Key": config.apiKey,
+        "Content-Type": "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      fastify.log.error({ error }, "Failed to get SignWell account info");
+      throw new Error(`SignWell API error: ${response.status}`);
+    }
+
+    return response.json();
+  };
+
+  console.info("   ✅ xSignwell Document Signing Enabled");
+  if (config.testMode) {
+    console.info("      ⚠️  Running in TEST MODE");
+  }
+}
+
+export default fp(xSignwell, {
+  name: "xSignwell",
+});