@xenterprises/fastify-xsignwell 1.1.0 → 1.2.0

package/src/services/templates.js

@@ -6,89 +6,51 @@
  * @see https://developers.signwell.com/reference/get_api-v1-document-templates-id
  */
 
+import { apiRequest } from "../apiRequest.js";
+
 /**
- * Setup templates service
- *
- * @param {import('fastify').FastifyInstance} fastify - Fastify instance
- * @param {Object} config - Plugin configuration
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Object} config
  */
 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);
+  function req(endpoint, options) {
+    return apiRequest(fastify, config, endpoint, options);
   }
 
   /**
    * Get a template by ID
-   * @param {string} templateId - Template ID
-   * @returns {Promise<Object>} Template details
+   * @param {string} templateId
+   * @returns {Promise<Object>}
    */
   async function get(templateId) {
-    return apiRequest(`/document_templates/${templateId}`, {
-      method: "GET",
-    });
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] templates.get: templateId (string) is required");
+    }
+    return req(`/document_templates/${templateId}`, { method: "GET" });
   }
 
   /**
    * Create a new template
-   * @param {Object} params - Template parameters
+   * @param {Object} params
    * @param {string} params.name - Template name
-   * @param {Array<Object>} [params.files] - Files to include (base64 or URL)
+   * @param {Array<Object>} [params.files] - Files (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
+   * @returns {Promise<Object>}
    */
   async function create(params) {
-    const {
-      name,
-      files,
-      recipients,
-      fields,
-      subject,
-      message,
-      ...rest
-    } = params;
-
-    const body = {
-      name,
-      ...rest,
-    };
+    if (!params || typeof params !== "object") {
+      throw new Error("[xSignwell] templates.create: params object is required");
+    }
+    if (!params.name || typeof params.name !== "string") {
+      throw new Error("[xSignwell] templates.create: name (string) is required");
+    }
+
+    const { name, files, recipients, fields, subject, message, ...rest } = params;
+
+    const body = { name, ...rest };
 
     if (files) {
       body.files = files.map((f) => ({
@@ -110,7 +72,7 @@ export async function setupTemplates(fastify, config) {
     if (subject) body.subject = subject;
     if (message) body.message = message;
 
-    return apiRequest("/document_templates", {
+    return req("/document_templates", {
       method: "POST",
       body: JSON.stringify(body),
     });
@@ -118,12 +80,18 @@ export async function setupTemplates(fastify, config) {
 
   /**
    * Update an existing template
-   * @param {string} templateId - Template ID
-   * @param {Object} params - Update parameters
-   * @returns {Promise<Object>} Updated template
+   * @param {string} templateId
+   * @param {Object} params
+   * @returns {Promise<Object>}
    */
   async function update(templateId, params) {
-    return apiRequest(`/document_templates/${templateId}`, {
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] templates.update: templateId (string) is required");
+    }
+    if (!params || typeof params !== "object") {
+      throw new Error("[xSignwell] templates.update: params object is required");
+    }
+    return req(`/document_templates/${templateId}`, {
       method: "PUT",
       body: JSON.stringify(params),
     });
@@ -131,66 +99,67 @@ export async function setupTemplates(fastify, config) {
 
   /**
    * Delete a template
-   * @param {string} templateId - Template ID
-   * @returns {Promise<Object>} Result
+   * @param {string} templateId
+   * @returns {Promise<Object>}
    */
   async function remove(templateId) {
-    return apiRequest(`/document_templates/${templateId}`, {
-      method: "DELETE",
-    });
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] templates.remove: templateId (string) is required");
+    }
+    return req(`/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
+   * @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 = `/document_templates${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(`/document_templates${qs ? `?${qs}` : ""}`, { method: "GET" });
   }
 
   /**
-   * Get template fields (for pre-filling)
-   * @param {string} templateId - Template ID
-   * @returns {Promise<Array>} List of fields
+   * Get template fields
+   * @param {string} templateId
+   * @returns {Promise<Array>}
    */
   async function getFields(templateId) {
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] templates.getFields: templateId (string) is required");
+    }
     const template = await get(templateId);
     return template.fields || [];
   }
 
   /**
    * Get template recipients (placeholders)
-   * @param {string} templateId - Template ID
-   * @returns {Promise<Array>} List of recipient placeholders
+   * @param {string} templateId
+   * @returns {Promise<Array>}
    */
   async function getRecipients(templateId) {
+    if (!templateId || typeof templateId !== "string") {
+      throw new Error("[xSignwell] templates.getRecipients: templateId (string) is required");
+    }
     const template = await get(templateId);
     return template.recipients || [];
   }
 
-  // Add templates service to xsignwell namespace
   fastify.xsignwell.templates = {
     get,
     create,
     update,
     remove,
-    delete: remove, // Alias
+    delete: remove,
     list,
     getFields,
     getRecipients,
   };
 
-  console.info("      • Templates Service initialized");
+  fastify.log.info("[xSignwell] Templates service initialized");
 }

package/src/services/webhooks.js

@@ -6,80 +6,46 @@
  * @see https://developers.signwell.com/reference/get_api-v1-hooks
  */
 
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { apiRequest } from "../apiRequest.js";
+
 /**
- * Setup webhooks service
- *
- * @param {import('fastify').FastifyInstance} fastify - Fastify instance
- * @param {Object} config - Plugin configuration
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Object} config
  */
 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);
+  function req(endpoint, options) {
+    return apiRequest(fastify, config, endpoint, options);
   }
 
   /**
    * List all webhooks
-   * @returns {Promise<Array>} List of webhooks
+   * @returns {Promise<Array>}
    */
   async function list() {
-    return apiRequest("/hooks", {
-      method: "GET",
-    });
+    return req("/hooks", { method: "GET" });
   }
 
   /**
    * Create a new webhook
-   * @param {Object} params - Webhook parameters
-   * @param {string} params.callbackUrl - URL to receive webhook events
+   * @param {Object} params
+   * @param {string} params.callbackUrl - URL to receive events
    * @param {string} [params.event] - Event type to subscribe to
-   * @returns {Promise<Object>} Created webhook
+   * @returns {Promise<Object>}
    */
   async function create(params) {
-    const { callbackUrl, event, ...rest } = params;
-
-    const body = {
-      callback_url: callbackUrl,
-      ...rest,
-    };
+    if (!params || typeof params !== "object") {
+      throw new Error("[xSignwell] webhooks.create: params object is required");
+    }
+    if (!params.callbackUrl || typeof params.callbackUrl !== "string") {
+      throw new Error("[xSignwell] webhooks.create: callbackUrl (string) is required");
+    }
 
+    const { callbackUrl, event, ...rest } = params;
+    const body = { callback_url: callbackUrl, ...rest };
     if (event) body.event = event;
 
-    return apiRequest("/hooks", {
+    return req("/hooks", {
       method: "POST",
       body: JSON.stringify(body),
     });
@@ -87,18 +53,17 @@ export async function setupWebhooks(fastify, config) {
 
   /**
    * Delete a webhook
-   * @param {string} webhookId - Webhook ID
-   * @returns {Promise<Object>} Result
+   * @param {string} webhookId
+   * @returns {Promise<Object>}
    */
   async function remove(webhookId) {
-    return apiRequest(`/hooks/${webhookId}`, {
-      method: "DELETE",
-    });
+    if (!webhookId || typeof webhookId !== "string") {
+      throw new Error("[xSignwell] webhooks.remove: webhookId (string) is required");
+    }
+    return req(`/hooks/${webhookId}`, { method: "DELETE" });
   }
 
-  /**
-   * Webhook event types
-   */
+  /** Webhook event type constants */
   const events = {
     DOCUMENT_COMPLETED: "document.completed",
     DOCUMENT_SENT: "document.sent",
@@ -114,39 +79,41 @@ export async function setupWebhooks(fastify, config) {
   };
 
   /**
-   * Verify webhook signature (if SignWell provides one)
+   * Verify webhook signature (HMAC-SHA256)
    * @param {string} payload - Raw request body
    * @param {string} signature - Signature header value
    * @param {string} secret - Webhook secret
-   * @returns {boolean} True if valid
+   * @returns {boolean}
    */
   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
+    if (!payload || typeof payload !== "string") {
+      throw new Error("[xSignwell] webhooks.verifySignature: payload (string) is required");
+    }
+    if (!signature || typeof signature !== "string") {
+      throw new Error("[xSignwell] webhooks.verifySignature: signature (string) is required");
+    }
+    if (!secret || typeof secret !== "string") {
+      throw new Error("[xSignwell] webhooks.verifySignature: secret (string) is required");
+    }
 
     try {
-      const crypto = require("crypto");
-      const expectedSignature = crypto
-        .createHmac("sha256", secret)
-        .update(payload)
-        .digest("hex");
-      return crypto.timingSafeEqual(
-        Buffer.from(signature),
-        Buffer.from(expectedSignature)
-      );
+      const expected = createHmac("sha256", secret).update(payload).digest("hex");
+      return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
     } catch (error) {
-      fastify.log.error({ error }, "Failed to verify webhook signature");
+      fastify.log.error({ error: error.message }, "[xSignwell] Signature verification failed");
       return false;
     }
   }
 
   /**
    * Parse webhook event payload
-   * @param {Object} payload - Webhook payload
-   * @returns {Object} Parsed event data
+   * @param {Object} payload
+   * @returns {Object}
    */
   function parseEvent(payload) {
+    if (!payload || typeof payload !== "object") {
+      throw new Error("[xSignwell] webhooks.parseEvent: payload (object) is required");
+    }
     return {
       event: payload.event || payload.type,
       documentId: payload.document?.id || payload.document_id,
@@ -157,16 +124,15 @@ export async function setupWebhooks(fastify, config) {
     };
   }
 
-  // Add webhooks service to xsignwell namespace
   fastify.xsignwell.webhooks = {
     list,
     create,
     remove,
-    delete: remove, // Alias
+    delete: remove,
     events,
     verifySignature,
     parseEvent,
   };
 
-  console.info("      • Webhooks Service initialized");
+  fastify.log.info("[xSignwell] Webhooks service initialized");
 }

package/src/xSignwell.js

@@ -2,12 +2,13 @@
  * xSignwell - SignWell Document Signing Integration
  *
  * A Fastify plugin for integrating with SignWell's e-signature API.
- * Provides document creation, template management, and webhook handling.
+ * Provides document creation, template management, bulk sending, and webhook handling.
  *
  * @see https://developers.signwell.com/reference/getting-started-with-your-api-1
  */
 
 import fp from "fastify-plugin";
+import { apiRequest } from "./apiRequest.js";
 import { setupDocuments } from "./services/documents.js";
 import { setupTemplates } from "./services/templates.js";
 import { setupWebhooks } from "./services/webhooks.js";
@@ -24,15 +25,23 @@ import { setupBulkSend } from "./services/bulkSend.js";
  * @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");
+    fastify.log.info("[xSignwell] Plugin disabled");
     return;
   }
 
-  // Validate required configuration
+  // Validate required options
   if (!options.apiKey) {
-    throw new Error("xSignwell: apiKey is required");
+    throw new Error("[xSignwell] apiKey is required");
+  }
+  if (typeof options.apiKey !== "string") {
+    throw new Error("[xSignwell] apiKey must be a string");
+  }
+  if (options.baseUrl !== undefined && typeof options.baseUrl !== "string") {
+    throw new Error("[xSignwell] baseUrl must be a string");
+  }
+  if (options.testMode !== undefined && typeof options.testMode !== "boolean") {
+    throw new Error("[xSignwell] testMode must be a boolean");
   }
 
   const config = {
@@ -41,10 +50,7 @@ async function xSignwell(fastify, options) {
     testMode: options.testMode || false,
   };
 
-  // Store configuration on fastify instance
-  fastify.decorate("xsignwell", {
-    config,
-  });
+  fastify.decorate("xsignwell", { config });
 
   // Setup services
   await setupDocuments(fastify, config);
@@ -52,31 +58,18 @@ async function xSignwell(fastify, options) {
   await setupWebhooks(fastify, config);
   await setupBulkSend(fastify, config);
 
-  // Add utility method to get current user/account info
+  // Account info helper
   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();
+    return apiRequest(fastify, config, "/me", { method: "GET" });
   };
 
-  console.info("   ✅ xSignwell Document Signing Enabled");
+  fastify.log.info("[xSignwell] Document Signing Enabled");
   if (config.testMode) {
-    console.info("      ⚠️  Running in TEST MODE");
+    fastify.log.info("[xSignwell] Running in TEST MODE");
   }
 }
 
 export default fp(xSignwell, {
   name: "xSignwell",
+  fastify: ">=5.0.0",
 });

package/.gitlab-ci.yml

@@ -1,45 +0,0 @@
-# ============================================================================
-# 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