@xenterprises/fastify-xsignwell 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@xenterprises/fastify-xsignwell",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Fastify plugin for SignWell document signing API integration",
   "type": "module",
   "main": "src/xSignwell.js",
@@ -21,7 +21,7 @@
     "api"
   ],
   "author": "X Enterprises",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "dependencies": {
     "fastify-plugin": "^5.0.1"
   },

package/src/apiRequest.js

@@ -0,0 +1,49 @@
+/**
+ * Shared API request helper for SignWell services.
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance (for logging)
+ * @param {Object} config - Plugin configuration
+ * @param {string} endpoint - API endpoint path
+ * @param {Object} [options] - Fetch options
+ * @returns {Promise<Object>} Parsed API response
+ */
+export async function apiRequest(fastify, config, endpoint, options = {}) {
+  const url = `${config.baseUrl}${endpoint}`;
+  const headers = {
+    "X-Api-Key": config.apiKey,
+    "Content-Type": "application/json",
+    ...options.headers,
+  };
+
+  let response;
+  try {
+    response = await fetch(url, { ...options, headers });
+  } catch (err) {
+    throw new Error(`[xSignwell] Network error calling ${endpoint}: ${err.message}`);
+  }
+
+  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 },
+      "[xSignwell] API error"
+    );
+    const err = new Error(
+      `[xSignwell] ${errorData.message || `API error: ${response.status}`}`
+    );
+    err.statusCode = response.status;
+    err.signwellError = errorData;
+    throw err;
+  }
+
+  const text = await response.text();
+  if (!text) return { success: true };
+
+  return JSON.parse(text);
+}

package/src/services/bulkSend.js

@@ -6,100 +6,67 @@
  * @see https://developers.signwell.com/reference/get_api-v1-bulk-sends-id
  */
 
+import { apiRequest } from "../apiRequest.js";
+
 /**
- * Setup bulk send service
- *
- * @param {import('fastify').FastifyInstance} fastify - Fastify instance
- * @param {Object} config - Plugin configuration
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Object} config
  */
 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 };
+  const { testMode } = config;
 
-    return JSON.parse(text);
+  function req(endpoint, options) {
+    return apiRequest(fastify, config, endpoint, options);
   }
 
   /**
    * Get a bulk send by ID
-   * @param {string} bulkSendId - Bulk send ID
-   * @returns {Promise<Object>} Bulk send details
+   * @param {string} bulkSendId
+   * @returns {Promise<Object>}
    */
   async function get(bulkSendId) {
-    return apiRequest(`/bulk_sends/${bulkSendId}`, {
-      method: "GET",
-    });
+    if (!bulkSendId || typeof bulkSendId !== "string") {
+      throw new Error("[xSignwell] bulkSend.get: bulkSendId (string) is required");
+    }
+    return req(`/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
+   * @param {Object} [params]
+   * @param {number} [params.page]
+   * @param {number} [params.limit]
+   * @returns {Promise<Object>}
    */
   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",
-    });
+    const qp = new URLSearchParams();
+    if (params.page) qp.set("page", params.page);
+    if (params.limit) qp.set("limit", params.limit);
+    const qs = qp.toString();
+    return req(`/bulk_sends${qs ? `?${qs}` : ""}`, { 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 {Object} params
+   * @param {string} params.templateId - Template ID
+   * @param {Array<Object>} params.recipients - Recipient data rows
    * @param {string} [params.subject] - Email subject
    * @param {string} [params.message] - Email message
-   * @returns {Promise<Object>} Created bulk send
+   * @returns {Promise<Object>}
    */
   async function create(params) {
-    const {
-      templateId,
-      recipients,
-      subject,
-      message,
-      ...rest
-    } = params;
+    if (!params || typeof params !== "object") {
+      throw new Error("[xSignwell] bulkSend.create: params object is required");
+    }
+    if (!params.templateId || typeof params.templateId !== "string") {
+      throw new Error("[xSignwell] bulkSend.create: templateId (string) is required");
+    }
+    if (!Array.isArray(params.recipients) || params.recipients.length === 0) {
+      throw new Error("[xSignwell] bulkSend.create: recipients (non-empty array) is required");
+    }
+
+    const { templateId, recipients, subject, message, ...rest } = params;
 
     const body = {
       document_template_id: templateId,
@@ -111,31 +78,40 @@ export async function setupBulkSend(fastify, config) {
     if (subject) body.subject = subject;
     if (message) body.message = message;
 
-    return apiRequest("/bulk_sends", {
+    return req("/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
+   * Get CSV template for a bulk send
+   * @param {string} templateId
+   * @returns {Promise<Object>}
    */
   async function getCsvTemplate(templateId) {
-    return apiRequest(`/bulk_sends/csv_template?document_template_id=${templateId}`, {
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] bulkSend.getCsvTemplate: templateId (string) is required");
+    }
+    return req(`/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
+   * @param {string} templateId
+   * @param {string} csvContent
+   * @returns {Promise<Object>}
    */
   async function validateCsv(templateId, csvContent) {
-    return apiRequest("/bulk_sends/validate_csv", {
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] bulkSend.validateCsv: templateId (string) is required");
+    }
+    if (!csvContent || typeof csvContent !== "string") {
+      throw new Error("[xSignwell] bulkSend.validateCsv: csvContent (string) is required");
+    }
+    return req("/bulk_sends/validate_csv", {
       method: "POST",
       body: JSON.stringify({
         document_template_id: templateId,
@@ -146,26 +122,23 @@ export async function setupBulkSend(fastify, config) {
 
   /**
    * 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
+   * @param {string} bulkSendId
+   * @param {Object} [params]
+   * @returns {Promise<Object>}
    */
   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, {
+    if (!bulkSendId || typeof bulkSendId !== "string") {
+      throw new Error("[xSignwell] bulkSend.getDocuments: bulkSendId (string) is required");
+    }
+    const qp = new URLSearchParams();
+    if (params.page) qp.set("page", params.page);
+    if (params.limit) qp.set("limit", params.limit);
+    const qs = qp.toString();
+    return req(`/bulk_sends/${bulkSendId}/documents${qs ? `?${qs}` : ""}`, {
       method: "GET",
     });
   }
 
-  // Add bulk send service to xsignwell namespace
   fastify.xsignwell.bulkSend = {
     get,
     list,
@@ -175,5 +148,5 @@ export async function setupBulkSend(fastify, config) {
     getDocuments,
   };
 
-  console.info("      • Bulk Send Service initialized");
+  fastify.log.info("[xSignwell] Bulk Send service initialized");
 }

package/src/services/documents.js

@@ -6,76 +6,49 @@
  * @see https://developers.signwell.com/reference/post_api-v1-documents
  */
 
+import { apiRequest } from "../apiRequest.js";
+
 /**
- * Setup documents service
- *
- * @param {import('fastify').FastifyInstance} fastify - Fastify instance
- * @param {Object} config - Plugin configuration
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Object} config
  */
 export async function setupDocuments(fastify, config) {
-  const { apiKey, baseUrl, testMode } = config;
+  const { 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);
+  function req(endpoint, options) {
+    return apiRequest(fastify, config, endpoint, options);
   }
 
   /**
    * Create a new document for signing
-   * @param {Object} params - Document parameters
+   * @param {Object} params
    * @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 {Array<Object>} params.recipients - Recipients list
+   * @param {Array<Object>} [params.files] - Files (base64 or URL)
+   * @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
+   * @returns {Promise<Object>}
    */
   async function create(params) {
+    if (!params || typeof params !== "object") {
+      throw new Error("[xSignwell] documents.create: params object is required");
+    }
+    if (!params.name || typeof params.name !== "string") {
+      throw new Error("[xSignwell] documents.create: name (string) is required");
+    }
+    if (!Array.isArray(params.recipients) || params.recipients.length === 0) {
+      throw new Error("[xSignwell] documents.create: recipients (non-empty array) is required");
+    }
+    for (const r of params.recipients) {
+      if (!r.email) {
+        throw new Error("[xSignwell] documents.create: each recipient must have an email");
+      }
+    }
+
     const {
-      name,
-      recipients,
-      files,
-      draft = false,
-      subject,
-      message,
-      metadata,
-      ...rest
+      name, recipients, files, draft = false, subject, message, metadata, ...rest
     } = params;
 
     const body = {
@@ -104,7 +77,7 @@ export async function setupDocuments(fastify, config) {
     if (message) body.message = message;
     if (metadata) body.metadata = metadata;
 
-    return apiRequest("/documents", {
+    return req("/documents", {
       method: "POST",
       body: JSON.stringify(body),
     });
@@ -112,25 +85,23 @@ export async function setupDocuments(fastify, config) {
 
   /**
    * 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
+   * @param {string} templateId
+   * @param {Object} params
+   * @returns {Promise<Object>}
    */
   async function createFromTemplate(templateId, params) {
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] documents.createFromTemplate: templateId (string) is required");
+    }
+    if (!params || typeof params !== "object") {
+      throw new Error("[xSignwell] documents.createFromTemplate: params object is required");
+    }
+    if (!Array.isArray(params.recipients) || params.recipients.length === 0) {
+      throw new Error("[xSignwell] documents.createFromTemplate: recipients (non-empty array) is required");
+    }
+
     const {
-      recipients,
-      fields,
-      draft = false,
-      subject,
-      message,
-      metadata,
-      ...rest
+      recipients, fields, draft = false, subject, message, metadata, ...rest
     } = params;
 
     const body = {
@@ -151,7 +122,7 @@ export async function setupDocuments(fastify, config) {
     if (message) body.message = message;
     if (metadata) body.metadata = metadata;
 
-    return apiRequest(`/document_templates/${templateId}/documents`, {
+    return req(`/document_templates/${templateId}/documents`, {
       method: "POST",
       body: JSON.stringify(body),
     });
@@ -159,23 +130,42 @@ export async function setupDocuments(fastify, config) {
 
   /**
    * Get a document by ID
-   * @param {string} documentId - Document ID
-   * @returns {Promise<Object>} Document details
+   * @param {string} documentId
+   * @returns {Promise<Object>}
    */
   async function get(documentId) {
-    return apiRequest(`/documents/${documentId}`, {
-      method: "GET",
-    });
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.get: documentId (string) is required");
+    }
+    return req(`/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
+   * List documents
+   * @param {Object} [params]
+   * @param {number} [params.page]
+   * @param {number} [params.limit]
+   * @returns {Promise<Object>}
+   */
+  async function list(params = {}) {
+    const qp = new URLSearchParams();
+    if (params.page) qp.set("page", params.page);
+    if (params.limit) qp.set("limit", params.limit);
+    const qs = qp.toString();
+    return req(`/documents${qs ? `?${qs}` : ""}`, { method: "GET" });
+  }
+
+  /**
+   * Send a document
+   * @param {string} documentId
+   * @param {Object} [params]
+   * @returns {Promise<Object>}
    */
   async function send(documentId, params = {}) {
-    return apiRequest(`/documents/${documentId}/send`, {
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.send: documentId (string) is required");
+    }
+    return req(`/documents/${documentId}/send`, {
       method: "POST",
       body: JSON.stringify(params),
     });
@@ -183,49 +173,59 @@ export async function setupDocuments(fastify, config) {
 
   /**
    * Send a reminder to recipients who haven't signed
-   * @param {string} documentId - Document ID
-   * @returns {Promise<Object>} Result
+   * @param {string} documentId
+   * @returns {Promise<Object>}
    */
   async function remind(documentId) {
-    return apiRequest(`/documents/${documentId}/remind`, {
-      method: "POST",
-    });
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.remind: documentId (string) is required");
+    }
+    return req(`/documents/${documentId}/remind`, { method: "POST" });
   }
 
   /**
    * Delete a document
-   * @param {string} documentId - Document ID
-   * @returns {Promise<Object>} Result
+   * @param {string} documentId
+   * @returns {Promise<Object>}
    */
   async function remove(documentId) {
-    return apiRequest(`/documents/${documentId}`, {
-      method: "DELETE",
-    });
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.remove: documentId (string) is required");
+    }
+    return req(`/documents/${documentId}`, { method: "DELETE" });
   }
 
   /**
    * Download the completed PDF
-   * @param {string} documentId - Document ID
-   * @returns {Promise<Object>} PDF URL or base64 data
+   * @param {string} documentId
+   * @returns {Promise<Object>}
    */
   async function getCompletedPdf(documentId) {
-    return apiRequest(`/documents/${documentId}/completed_pdf`, {
-      method: "GET",
-    });
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.getCompletedPdf: documentId (string) is required");
+    }
+    return req(`/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
+   * @param {string} documentId
+   * @param {string} recipientId
+   * @returns {Promise<Object>}
    */
   async function getEmbeddedSigningUrl(documentId, recipientId) {
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.getEmbeddedSigningUrl: documentId (string) is required");
+    }
+    if (!recipientId || typeof recipientId !== "string") {
+      throw new Error("[xSignwell] documents.getEmbeddedSigningUrl: recipientId (string) is required");
+    }
+
     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`);
+      throw new Error(`[xSignwell] Recipient ${recipientId} not found in document ${documentId}`);
     }
 
     return {
@@ -234,18 +234,31 @@ export async function setupDocuments(fastify, config) {
     };
   }
 
-  // Add documents service to xsignwell namespace
+  /**
+   * Get audit trail for a completed document
+   * @param {string} documentId
+   * @returns {Promise<Object>}
+   */
+  async function getAuditTrail(documentId) {
+    if (!documentId || typeof documentId !== "string") {
+      throw new Error("[xSignwell] documents.getAuditTrail: documentId (string) is required");
+    }
+    return req(`/documents/${documentId}/audit_trail`, { method: "GET" });
+  }
+
   fastify.xsignwell.documents = {
     create,
     createFromTemplate,
     get,
+    list,
     send,
     remind,
     remove,
-    delete: remove, // Alias
+    delete: remove,
     getCompletedPdf,
     getEmbeddedSigningUrl,
+    getAuditTrail,
   };
 
-  console.info("      • Documents Service initialized");
+  fastify.log.info("[xSignwell] Documents service initialized");
 }