@xenterprises/fastify-xsignwell 1.1.1 → 1.2.1

package/index.d.ts

@@ -0,0 +1,164 @@
+import { FastifyPluginAsync } from "fastify";
+
+interface XSignwellOptions {
+  /** SignWell API key (required) */
+  apiKey: string;
+  /** API base URL (default: "https://www.signwell.com/api/v1") */
+  baseUrl?: string;
+  /** Enable test mode (default: false) */
+  testMode?: boolean;
+  /** Enable/disable the plugin (default: true) */
+  active?: boolean;
+}
+
+interface Recipient {
+  id?: string;
+  email: string;
+  name?: string;
+  sendEmail?: boolean;
+  [key: string]: unknown;
+}
+
+interface FileAttachment {
+  name: string;
+  base64?: string;
+  file_base64?: string;
+  url?: string;
+  file_url?: string;
+}
+
+interface CreateDocumentParams {
+  name: string;
+  recipients: Recipient[];
+  files?: FileAttachment[];
+  draft?: boolean;
+  testMode?: boolean;
+  subject?: string;
+  message?: string;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface CreateFromTemplateParams {
+  recipients: Recipient[];
+  fields?: Record<string, unknown>;
+  draft?: boolean;
+  testMode?: boolean;
+  subject?: string;
+  message?: string;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface PaginationParams {
+  page?: number;
+  limit?: number;
+}
+
+interface DocumentsService {
+  create(params: CreateDocumentParams): Promise<Record<string, unknown>>;
+  createFromTemplate(templateId: string, params: CreateFromTemplateParams): Promise<Record<string, unknown>>;
+  get(documentId: string): Promise<Record<string, unknown>>;
+  list(params?: PaginationParams): Promise<Record<string, unknown>>;
+  send(documentId: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  remind(documentId: string): Promise<Record<string, unknown>>;
+  remove(documentId: string): Promise<Record<string, unknown>>;
+  delete(documentId: string): Promise<Record<string, unknown>>;
+  getCompletedPdf(documentId: string): Promise<Record<string, unknown>>;
+  getEmbeddedSigningUrl(documentId: string, recipientId: string): Promise<{ url: string; recipient: Record<string, unknown> }>;
+  getAuditTrail(documentId: string): Promise<Record<string, unknown>>;
+}
+
+interface CreateTemplateParams {
+  name: string;
+  files?: FileAttachment[];
+  recipients?: Array<{ id?: string; name?: string; placeholder_name?: string; [key: string]: unknown }>;
+  fields?: unknown[];
+  subject?: string;
+  message?: string;
+  [key: string]: unknown;
+}
+
+interface TemplatesService {
+  get(templateId: string): Promise<Record<string, unknown>>;
+  create(params: CreateTemplateParams): Promise<Record<string, unknown>>;
+  update(templateId: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+  remove(templateId: string): Promise<Record<string, unknown>>;
+  delete(templateId: string): Promise<Record<string, unknown>>;
+  list(params?: PaginationParams): Promise<Record<string, unknown>>;
+  getFields(templateId: string): Promise<unknown[]>;
+  getRecipients(templateId: string): Promise<unknown[]>;
+}
+
+interface WebhookEvents {
+  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";
+}
+
+interface ParsedEvent {
+  event: string;
+  documentId: string;
+  document: Record<string, unknown>;
+  recipient: Record<string, unknown> | undefined;
+  timestamp: string;
+  raw: Record<string, unknown>;
+}
+
+interface WebhooksService {
+  list(): Promise<Record<string, unknown>>;
+  create(params: { callbackUrl: string; event?: string; [key: string]: unknown }): Promise<Record<string, unknown>>;
+  remove(webhookId: string): Promise<Record<string, unknown>>;
+  delete(webhookId: string): Promise<Record<string, unknown>>;
+  events: WebhookEvents;
+  verifySignature(payload: string, signature: string, secret: string): boolean;
+  parseEvent(payload: Record<string, unknown>): ParsedEvent;
+}
+
+interface CreateBulkSendParams {
+  templateId: string;
+  recipients: Record<string, unknown>[];
+  testMode?: boolean;
+  subject?: string;
+  message?: string;
+  [key: string]: unknown;
+}
+
+interface BulkSendService {
+  get(bulkSendId: string): Promise<Record<string, unknown>>;
+  list(params?: PaginationParams): Promise<Record<string, unknown>>;
+  create(params: CreateBulkSendParams): Promise<Record<string, unknown>>;
+  getCsvTemplate(templateId: string): Promise<Record<string, unknown>>;
+  validateCsv(templateId: string, csvContent: string): Promise<Record<string, unknown>>;
+  getDocuments(bulkSendId: string, params?: PaginationParams): Promise<Record<string, unknown>>;
+}
+
+interface XSignwellDecorator {
+  config: {
+    apiKey: string;
+    baseUrl: string;
+    testMode: boolean;
+  };
+  documents: DocumentsService;
+  templates: TemplatesService;
+  webhooks: WebhooksService;
+  bulkSend: BulkSendService;
+  me(): Promise<Record<string, unknown>>;
+}
+
+declare module "fastify" {
+  interface FastifyInstance {
+    xsignwell: XSignwellDecorator;
+  }
+}
+
+declare const xSignwell: FastifyPluginAsync<XSignwellOptions>;
+export default xSignwell;

package/package.json

@@ -1,35 +1,38 @@
 {
  "name": "@xenterprises/fastify-xsignwell",
-  "version": "1.1.1",
-  "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"
-  }
+ "version": "1.2.1",
+ "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": "SEE LICENSE IN LICENSE",
+ "dependencies": {
+  "fastify-plugin": "^5.0.1"
+ },
+ "peerDependencies": {
+  "fastify": "^5.0.0"
+ },
+ "devDependencies": {
+  "eslint": "^9.0.0",
+  "fastify": "^5.0.0"
+ },
+ "publishConfig": {
+  "access": "public"
+ }
 }

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");
 }