@zendfi/sdk 0.1.1 → 0.1.2

package/dist/index.d.mts

@@ -155,7 +155,7 @@ interface WebhookPayload {
     data: Payment | Subscription;
 }
 interface VerifyWebhookRequest {
-    payload: string;
+    payload: string | object;
     signature: string;
     secret: string;
 }
@@ -608,4 +608,64 @@ declare function verifyExpressWebhook(request: any, secret?: string): Promise<We
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 
-export { type ApproveEscrowRequest, AuthenticationError, ConfigLoader, type CreateEscrowRequest, type CreateInstallmentPlanRequest, type CreateInstallmentPlanResponse, type CreateInvoiceRequest, type CreatePaymentLinkRequest, type CreatePaymentRequest, type CreateSubscriptionPlanRequest, type CreateSubscriptionRequest, type Currency, type DisputeEscrowRequest, type Environment, type Escrow, type EscrowStatus, type InstallmentPlan, type InstallmentPlanStatus, type InstallmentScheduleItem, type Invoice, type InvoiceLineItem, type InvoiceStatus, type ListPaymentsRequest, NetworkError, type PaginatedResponse, type Payment, type PaymentLink, type PaymentStatus, type PaymentToken, RateLimitError, type RefundEscrowRequest, type ReleaseCondition, type SplitRecipient, type SplitStatus, type Subscription, type SubscriptionPlan, type SubscriptionStatus, ValidationError, type VerifyWebhookRequest, type WebhookEvent, type WebhookPayload, ZendFiClient, type ZendFiConfig, ZendFiError, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };
+/**
+ * ZendFi Webhook Handlers
+ * Type-safe webhook handlers with automatic verification and deduplication
+ */
+
+/**
+ * Webhook handler configuration
+ */
+interface WebhookHandlerConfig {
+    /** Your webhook secret from ZendFi dashboard */
+    secret: string;
+    /** Optional: Path to store processed webhook IDs (for deduplication) */
+    onProcessed?: (webhookId: string) => Promise<void>;
+    /** Optional: Check if webhook was already processed */
+    isProcessed?: (webhookId: string) => Promise<boolean>;
+    /** Optional: Custom error handler */
+    onError?: (error: Error, event?: WebhookEvent) => void | Promise<void>;
+}
+/**
+ * Event handler function type
+ */
+type WebhookEventHandler<T = any> = (data: T, event: WebhookPayload) => void | Promise<void>;
+/**
+ * Webhook handlers map - type-safe event handlers
+ */
+type WebhookHandlers = Partial<{
+    'payment.created': WebhookEventHandler;
+    'payment.confirmed': WebhookEventHandler;
+    'payment.failed': WebhookEventHandler;
+    'payment.expired': WebhookEventHandler;
+    'subscription.created': WebhookEventHandler;
+    'subscription.activated': WebhookEventHandler;
+    'subscription.canceled': WebhookEventHandler;
+    'subscription.payment_failed': WebhookEventHandler;
+    'split.completed': WebhookEventHandler;
+    'split.failed': WebhookEventHandler;
+    'installment.due': WebhookEventHandler;
+    'installment.paid': WebhookEventHandler;
+    'installment.late': WebhookEventHandler;
+    'escrow.funded': WebhookEventHandler;
+    'escrow.released': WebhookEventHandler;
+    'escrow.refunded': WebhookEventHandler;
+    'escrow.disputed': WebhookEventHandler;
+    'invoice.sent': WebhookEventHandler;
+    'invoice.paid': WebhookEventHandler;
+}>;
+/**
+ * Webhook processing result
+ */
+interface WebhookResult {
+    success: boolean;
+    processed: boolean;
+    error?: string;
+    event?: WebhookEvent;
+}
+/**
+ * Process webhook with handlers
+ */
+declare function processWebhook(payload: WebhookPayload, handlers: WebhookHandlers, config: WebhookHandlerConfig): Promise<WebhookResult>;
+
+export { type ApproveEscrowRequest, AuthenticationError, ConfigLoader, type CreateEscrowRequest, type CreateInstallmentPlanRequest, type CreateInstallmentPlanResponse, type CreateInvoiceRequest, type CreatePaymentLinkRequest, type CreatePaymentRequest, type CreateSubscriptionPlanRequest, type CreateSubscriptionRequest, type Currency, type DisputeEscrowRequest, type Environment, type Escrow, type EscrowStatus, type InstallmentPlan, type InstallmentPlanStatus, type InstallmentScheduleItem, type Invoice, type InvoiceLineItem, type InvoiceStatus, type ListPaymentsRequest, NetworkError, type PaginatedResponse, type Payment, type PaymentLink, type PaymentStatus, type PaymentToken, RateLimitError, type RefundEscrowRequest, type ReleaseCondition, type SplitRecipient, type SplitStatus, type Subscription, type SubscriptionPlan, type SubscriptionStatus, ValidationError, type VerifyWebhookRequest, type WebhookEvent, type WebhookEventHandler, type WebhookHandlerConfig, type WebhookHandlers, type WebhookPayload, type WebhookResult, ZendFiClient, type ZendFiConfig, ZendFiError, processWebhook, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };

package/dist/index.d.ts

@@ -155,7 +155,7 @@ interface WebhookPayload {
     data: Payment | Subscription;
 }
 interface VerifyWebhookRequest {
-    payload: string;
+    payload: string | object;
     signature: string;
     secret: string;
 }
@@ -608,4 +608,64 @@ declare function verifyExpressWebhook(request: any, secret?: string): Promise<We
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 
-export { type ApproveEscrowRequest, AuthenticationError, ConfigLoader, type CreateEscrowRequest, type CreateInstallmentPlanRequest, type CreateInstallmentPlanResponse, type CreateInvoiceRequest, type CreatePaymentLinkRequest, type CreatePaymentRequest, type CreateSubscriptionPlanRequest, type CreateSubscriptionRequest, type Currency, type DisputeEscrowRequest, type Environment, type Escrow, type EscrowStatus, type InstallmentPlan, type InstallmentPlanStatus, type InstallmentScheduleItem, type Invoice, type InvoiceLineItem, type InvoiceStatus, type ListPaymentsRequest, NetworkError, type PaginatedResponse, type Payment, type PaymentLink, type PaymentStatus, type PaymentToken, RateLimitError, type RefundEscrowRequest, type ReleaseCondition, type SplitRecipient, type SplitStatus, type Subscription, type SubscriptionPlan, type SubscriptionStatus, ValidationError, type VerifyWebhookRequest, type WebhookEvent, type WebhookPayload, ZendFiClient, type ZendFiConfig, ZendFiError, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };
+/**
+ * ZendFi Webhook Handlers
+ * Type-safe webhook handlers with automatic verification and deduplication
+ */
+
+/**
+ * Webhook handler configuration
+ */
+interface WebhookHandlerConfig {
+    /** Your webhook secret from ZendFi dashboard */
+    secret: string;
+    /** Optional: Path to store processed webhook IDs (for deduplication) */
+    onProcessed?: (webhookId: string) => Promise<void>;
+    /** Optional: Check if webhook was already processed */
+    isProcessed?: (webhookId: string) => Promise<boolean>;
+    /** Optional: Custom error handler */
+    onError?: (error: Error, event?: WebhookEvent) => void | Promise<void>;
+}
+/**
+ * Event handler function type
+ */
+type WebhookEventHandler<T = any> = (data: T, event: WebhookPayload) => void | Promise<void>;
+/**
+ * Webhook handlers map - type-safe event handlers
+ */
+type WebhookHandlers = Partial<{
+    'payment.created': WebhookEventHandler;
+    'payment.confirmed': WebhookEventHandler;
+    'payment.failed': WebhookEventHandler;
+    'payment.expired': WebhookEventHandler;
+    'subscription.created': WebhookEventHandler;
+    'subscription.activated': WebhookEventHandler;
+    'subscription.canceled': WebhookEventHandler;
+    'subscription.payment_failed': WebhookEventHandler;
+    'split.completed': WebhookEventHandler;
+    'split.failed': WebhookEventHandler;
+    'installment.due': WebhookEventHandler;
+    'installment.paid': WebhookEventHandler;
+    'installment.late': WebhookEventHandler;
+    'escrow.funded': WebhookEventHandler;
+    'escrow.released': WebhookEventHandler;
+    'escrow.refunded': WebhookEventHandler;
+    'escrow.disputed': WebhookEventHandler;
+    'invoice.sent': WebhookEventHandler;
+    'invoice.paid': WebhookEventHandler;
+}>;
+/**
+ * Webhook processing result
+ */
+interface WebhookResult {
+    success: boolean;
+    processed: boolean;
+    error?: string;
+    event?: WebhookEvent;
+}
+/**
+ * Process webhook with handlers
+ */
+declare function processWebhook(payload: WebhookPayload, handlers: WebhookHandlers, config: WebhookHandlerConfig): Promise<WebhookResult>;
+
+export { type ApproveEscrowRequest, AuthenticationError, ConfigLoader, type CreateEscrowRequest, type CreateInstallmentPlanRequest, type CreateInstallmentPlanResponse, type CreateInvoiceRequest, type CreatePaymentLinkRequest, type CreatePaymentRequest, type CreateSubscriptionPlanRequest, type CreateSubscriptionRequest, type Currency, type DisputeEscrowRequest, type Environment, type Escrow, type EscrowStatus, type InstallmentPlan, type InstallmentPlanStatus, type InstallmentScheduleItem, type Invoice, type InvoiceLineItem, type InvoiceStatus, type ListPaymentsRequest, NetworkError, type PaginatedResponse, type Payment, type PaymentLink, type PaymentStatus, type PaymentToken, RateLimitError, type RefundEscrowRequest, type ReleaseCondition, type SplitRecipient, type SplitStatus, type Subscription, type SubscriptionPlan, type SubscriptionStatus, ValidationError, type VerifyWebhookRequest, type WebhookEvent, type WebhookEventHandler, type WebhookHandlerConfig, type WebhookHandlers, type WebhookPayload, type WebhookResult, ZendFiClient, type ZendFiConfig, ZendFiError, processWebhook, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };

package/dist/index.js

@@ -37,6 +37,7 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   ZendFiClient: () => ZendFiClient,
   ZendFiError: () => ZendFiError,
+  processWebhook: () => processWebhook,
   verifyExpressWebhook: () => verifyExpressWebhook,
   verifyNextWebhook: () => verifyNextWebhook,
   verifyWebhookSignature: () => verifyWebhookSignature,
@@ -327,9 +328,6 @@ var ZendFiClient = class {
   async listPaymentLinks() {
     return [];
   }
-  // ===================================================================
-  // INSTALLMENT PLANS - Pay over time
-  // ===================================================================
   /**
    * Create an installment plan
    * Split a purchase into multiple scheduled payments
@@ -380,9 +378,6 @@ var ZendFiClient = class {
       `/api/v1/installment-plans/${planId}/cancel`
     );
   }
-  // ===================================================================
-  // ESCROW - Secure fund holding
-  // ===================================================================
   /**
    * Create an escrow transaction
    * Hold funds until conditions are met
@@ -432,9 +427,6 @@ var ZendFiClient = class {
   async disputeEscrow(escrowId, request) {
     return this.request("POST", `/api/v1/escrows/${escrowId}/dispute`, request);
   }
-  // ===================================================================
-  // INVOICES - Professional billing
-  // ===================================================================
   /**
    * Create an invoice
    */
@@ -486,15 +478,34 @@ var ZendFiClient = class {
       if (!request.payload || !request.signature || !request.secret) {
         return false;
       }
-      const parsedPayload = JSON.parse(request.payload);
-      if (!parsedPayload.event || !parsedPayload.merchant_id || !parsedPayload.timestamp) {
+      let payloadString;
+      let parsedPayload = null;
+      if (typeof request.payload === "string") {
+        payloadString = request.payload;
+        try {
+          parsedPayload = JSON.parse(payloadString);
+        } catch (e) {
+          return false;
+        }
+      } else if (typeof request.payload === "object") {
+        parsedPayload = request.payload;
+        try {
+          payloadString = JSON.stringify(request.payload);
+        } catch (e) {
+          return false;
+        }
+      } else {
+        return false;
+      }
+      if (!parsedPayload || !parsedPayload.event || !parsedPayload.merchant_id || !parsedPayload.timestamp) {
         return false;
       }
-      const computedSignature = this.computeHmacSignature(request.payload, request.secret);
+      const computedSignature = this.computeHmacSignature(payloadString, request.secret);
       return this.timingSafeEqual(request.signature, computedSignature);
-    } catch (error) {
+    } catch (err) {
+      const error = err;
       if (this.config.environment === "development") {
-        console.error("Webhook verification error:", error);
+        console.error("Webhook verification error:", error?.message || String(error));
       }
       return false;
     }
@@ -664,6 +675,65 @@ function verifyWebhookSignature(payload, signature, secret) {
     secret
   });
 }
+
+// src/webhook-handler.ts
+var processedWebhooks = /* @__PURE__ */ new Set();
+var defaultIsProcessed = async (webhookId) => {
+  return processedWebhooks.has(webhookId);
+};
+var defaultOnProcessed = async (webhookId) => {
+  processedWebhooks.add(webhookId);
+  if (processedWebhooks.size > 1e4) {
+    const iterator = processedWebhooks.values();
+    for (let i = 0; i < 1e3; i++) {
+      const { value } = iterator.next();
+      if (value) processedWebhooks.delete(value);
+    }
+  }
+};
+function generateWebhookId(payload) {
+  return `${payload.merchant_id}:${payload.event}:${payload.timestamp}`;
+}
+async function processWebhook(payload, handlers, config) {
+  try {
+    const webhookId = generateWebhookId(payload);
+    const isProcessed = config.isProcessed || defaultIsProcessed;
+    const onProcessed = config.onProcessed || defaultOnProcessed;
+    if (await isProcessed(webhookId)) {
+      return {
+        success: true,
+        processed: false,
+        event: payload.event
+      };
+    }
+    const handler = handlers[payload.event];
+    if (!handler) {
+      return {
+        success: true,
+        processed: false,
+        event: payload.event
+      };
+    }
+    await handler(payload.data, payload);
+    await onProcessed(webhookId);
+    return {
+      success: true,
+      processed: true,
+      event: payload.event
+    };
+  } catch (error) {
+    const err = error;
+    if (config.onError) {
+      await config.onError(err, payload?.event);
+    }
+    return {
+      success: false,
+      processed: false,
+      error: err.message,
+      event: payload?.event
+    };
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
@@ -673,6 +743,7 @@ function verifyWebhookSignature(payload, signature, secret) {
   ValidationError,
   ZendFiClient,
   ZendFiError,
+  processWebhook,
   verifyExpressWebhook,
   verifyNextWebhook,
   verifyWebhookSignature,

package/dist/index.mjs

@@ -288,9 +288,6 @@ var ZendFiClient = class {
   async listPaymentLinks() {
     return [];
   }
-  // ===================================================================
-  // INSTALLMENT PLANS - Pay over time
-  // ===================================================================
   /**
    * Create an installment plan
    * Split a purchase into multiple scheduled payments
@@ -341,9 +338,6 @@ var ZendFiClient = class {
       `/api/v1/installment-plans/${planId}/cancel`
     );
   }
-  // ===================================================================
-  // ESCROW - Secure fund holding
-  // ===================================================================
   /**
    * Create an escrow transaction
    * Hold funds until conditions are met
@@ -393,9 +387,6 @@ var ZendFiClient = class {
   async disputeEscrow(escrowId, request) {
     return this.request("POST", `/api/v1/escrows/${escrowId}/dispute`, request);
   }
-  // ===================================================================
-  // INVOICES - Professional billing
-  // ===================================================================
   /**
    * Create an invoice
    */
@@ -447,15 +438,34 @@ var ZendFiClient = class {
       if (!request.payload || !request.signature || !request.secret) {
         return false;
       }
-      const parsedPayload = JSON.parse(request.payload);
-      if (!parsedPayload.event || !parsedPayload.merchant_id || !parsedPayload.timestamp) {
+      let payloadString;
+      let parsedPayload = null;
+      if (typeof request.payload === "string") {
+        payloadString = request.payload;
+        try {
+          parsedPayload = JSON.parse(payloadString);
+        } catch (e) {
+          return false;
+        }
+      } else if (typeof request.payload === "object") {
+        parsedPayload = request.payload;
+        try {
+          payloadString = JSON.stringify(request.payload);
+        } catch (e) {
+          return false;
+        }
+      } else {
+        return false;
+      }
+      if (!parsedPayload || !parsedPayload.event || !parsedPayload.merchant_id || !parsedPayload.timestamp) {
         return false;
       }
-      const computedSignature = this.computeHmacSignature(request.payload, request.secret);
+      const computedSignature = this.computeHmacSignature(payloadString, request.secret);
       return this.timingSafeEqual(request.signature, computedSignature);
-    } catch (error) {
+    } catch (err) {
+      const error = err;
       if (this.config.environment === "development") {
-        console.error("Webhook verification error:", error);
+        console.error("Webhook verification error:", error?.message || String(error));
       }
       return false;
     }
@@ -625,6 +635,65 @@ function verifyWebhookSignature(payload, signature, secret) {
     secret
   });
 }
+
+// src/webhook-handler.ts
+var processedWebhooks = /* @__PURE__ */ new Set();
+var defaultIsProcessed = async (webhookId) => {
+  return processedWebhooks.has(webhookId);
+};
+var defaultOnProcessed = async (webhookId) => {
+  processedWebhooks.add(webhookId);
+  if (processedWebhooks.size > 1e4) {
+    const iterator = processedWebhooks.values();
+    for (let i = 0; i < 1e3; i++) {
+      const { value } = iterator.next();
+      if (value) processedWebhooks.delete(value);
+    }
+  }
+};
+function generateWebhookId(payload) {
+  return `${payload.merchant_id}:${payload.event}:${payload.timestamp}`;
+}
+async function processWebhook(payload, handlers, config) {
+  try {
+    const webhookId = generateWebhookId(payload);
+    const isProcessed = config.isProcessed || defaultIsProcessed;
+    const onProcessed = config.onProcessed || defaultOnProcessed;
+    if (await isProcessed(webhookId)) {
+      return {
+        success: true,
+        processed: false,
+        event: payload.event
+      };
+    }
+    const handler = handlers[payload.event];
+    if (!handler) {
+      return {
+        success: true,
+        processed: false,
+        event: payload.event
+      };
+    }
+    await handler(payload.data, payload);
+    await onProcessed(webhookId);
+    return {
+      success: true,
+      processed: true,
+      event: payload.event
+    };
+  } catch (error) {
+    const err = error;
+    if (config.onError) {
+      await config.onError(err, payload?.event);
+    }
+    return {
+      success: false,
+      processed: false,
+      error: err.message,
+      event: payload?.event
+    };
+  }
+}
 export {
   AuthenticationError,
   ConfigLoader,
@@ -633,6 +702,7 @@ export {
   ValidationError,
   ZendFiClient,
   ZendFiError,
+  processWebhook,
   verifyExpressWebhook,
   verifyNextWebhook,
   verifyWebhookSignature,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendfi/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Zero-config TypeScript SDK for ZendFi crypto payments",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -10,14 +10,24 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./nextjs": {
+      "import": "./dist/nextjs.mjs",
+      "require": "./dist/nextjs.js",
+      "types": "./dist/nextjs.d.ts"
+    },
+    "./express": {
+      "import": "./dist/express.mjs",
+      "require": "./dist/express.js",
+      "types": "./dist/express.d.ts"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "build": "tsup src/index.ts src/nextjs.ts src/express.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts src/nextjs.ts src/express.ts --format esm,cjs --dts --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",