@zendfi/sdk 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -7,41 +7,6 @@ import {
 import fetch from "cross-fetch";
 import { createHmac, timingSafeEqual } from "crypto";
 
-// src/types.ts
-var ZendFiError = class extends Error {
-  constructor(message, statusCode, code, details) {
-    super(message);
-    this.statusCode = statusCode;
-    this.code = code;
-    this.details = details;
-    this.name = "ZendFiError";
-  }
-};
-var AuthenticationError = class extends ZendFiError {
-  constructor(message = "Authentication failed") {
-    super(message, 401, "AUTHENTICATION_ERROR");
-    this.name = "AuthenticationError";
-  }
-};
-var ValidationError = class extends ZendFiError {
-  constructor(message, details) {
-    super(message, 400, "VALIDATION_ERROR", details);
-    this.name = "ValidationError";
-  }
-};
-var NetworkError = class extends ZendFiError {
-  constructor(message) {
-    super(message, 0, "NETWORK_ERROR");
-    this.name = "NetworkError";
-  }
-};
-var RateLimitError = class extends ZendFiError {
-  constructor(message = "Rate limit exceeded") {
-    super(message, 429, "RATE_LIMIT_ERROR");
-    this.name = "RateLimitError";
-  }
-};
-
 // src/utils.ts
 var ConfigLoader = class {
   /**
@@ -59,7 +24,8 @@ var ConfigLoader = class {
       mode,
       timeout: options?.timeout ?? 3e4,
       retries: options?.retries ?? 3,
-      idempotencyEnabled: options?.idempotencyEnabled ?? true
+      idempotencyEnabled: options?.idempotencyEnabled ?? true,
+      debug: options?.debug ?? false
     };
   }
   /**
@@ -171,28 +137,6 @@ var ConfigLoader = class {
     }
   }
 };
-function parseError(response, body) {
-  const statusCode = response.status;
-  const errorMessage = body?.error || body?.message || response.statusText || "Unknown error";
-  const errorCode = body?.code;
-  const details = body?.details;
-  switch (statusCode) {
-    case 401:
-    case 403:
-      return new AuthenticationError(errorMessage);
-    case 400:
-      return new ValidationError(errorMessage, details);
-    case 429:
-      return new RateLimitError(errorMessage);
-    case 500:
-    case 502:
-    case 503:
-    case 504:
-      return new NetworkError(errorMessage);
-    default:
-      return new ZendFiError(errorMessage, statusCode, errorCode, details);
-  }
-}
 function generateIdempotencyKey() {
   const timestamp = Date.now();
   const random = Math.random().toString(36).substring(2, 15);
@@ -202,16 +146,261 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/errors.ts
+var ZendFiError2 = class _ZendFiError extends Error {
+  code;
+  type;
+  suggestion;
+  docs_url;
+  statusCode;
+  response;
+  constructor(data) {
+    super(data.message);
+    this.name = "ZendFiError";
+    this.code = data.code;
+    this.type = data.type;
+    this.suggestion = data.suggestion;
+    this.statusCode = data.statusCode;
+    this.response = data.response;
+    this.docs_url = `https://docs.zendfi.com/errors/${data.code}`;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ZendFiError);
+    }
+  }
+  /**
+   * Format error for display
+   */
+  toString() {
+    let message = `[${this.code}] ${this.message}`;
+    if (this.suggestion) {
+      message += `
+\u{1F4A1} Suggestion: ${this.suggestion}`;
+    }
+    message += `
+\u{1F4DA} Docs: ${this.docs_url}`;
+    return message;
+  }
+  /**
+   * Convert error to JSON
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      type: this.type,
+      message: this.message,
+      suggestion: this.suggestion,
+      docs_url: this.docs_url,
+      statusCode: this.statusCode
+    };
+  }
+};
+var AuthenticationError2 = class extends ZendFiError2 {
+  constructor(message, code = "authentication_failed", suggestion) {
+    super({
+      code,
+      message,
+      type: "authentication_error",
+      suggestion: suggestion || "Check your API key in the dashboard at https://app.zendfi.com/settings/api-keys",
+      statusCode: 401
+    });
+    this.name = "AuthenticationError";
+  }
+};
+var PaymentError = class extends ZendFiError2 {
+  constructor(message, code = "payment_failed", suggestion) {
+    super({
+      code,
+      message,
+      type: "payment_error",
+      suggestion,
+      statusCode: 400
+    });
+    this.name = "PaymentError";
+  }
+};
+var ValidationError2 = class extends ZendFiError2 {
+  constructor(message, code = "validation_failed", suggestion) {
+    super({
+      code,
+      message,
+      type: "validation_error",
+      suggestion,
+      statusCode: 400
+    });
+    this.name = "ValidationError";
+  }
+};
+var NetworkError2 = class extends ZendFiError2 {
+  constructor(message, code = "network_error", suggestion) {
+    super({
+      code,
+      message,
+      type: "network_error",
+      suggestion: suggestion || "Check your internet connection and try again",
+      statusCode: 0
+    });
+    this.name = "NetworkError";
+  }
+};
+var RateLimitError2 = class extends ZendFiError2 {
+  constructor(message, retryAfter) {
+    super({
+      code: "rate_limit_exceeded",
+      message,
+      type: "rate_limit_error",
+      suggestion: retryAfter ? `Wait ${retryAfter} seconds before retrying` : "You are making too many requests. Please slow down.",
+      statusCode: 429
+    });
+    this.name = "RateLimitError";
+  }
+};
+var ApiError = class extends ZendFiError2 {
+  constructor(message, code, statusCode, response) {
+    super({
+      code,
+      message,
+      type: "api_error",
+      statusCode,
+      response
+    });
+    this.name = "ApiError";
+  }
+};
+var WebhookError = class extends ZendFiError2 {
+  constructor(message, code = "webhook_verification_failed", suggestion) {
+    super({
+      code,
+      message,
+      type: "webhook_error",
+      suggestion: suggestion || "Check your webhook secret matches the one in your dashboard",
+      statusCode: 400
+    });
+    this.name = "WebhookError";
+  }
+};
+function createZendFiError(statusCode, responseBody, message) {
+  const errorMessage = message || responseBody?.error?.message || responseBody?.message || "An error occurred";
+  const errorCode = responseBody?.error?.code || responseBody?.code || "unknown_error";
+  if (statusCode === 401) {
+    return new AuthenticationError2(
+      errorMessage,
+      errorCode,
+      "Verify your API key is correct and not expired"
+    );
+  }
+  if (statusCode === 429) {
+    const retryAfter = responseBody?.retry_after;
+    return new RateLimitError2(errorMessage, retryAfter);
+  }
+  if (statusCode === 400 || statusCode === 422) {
+    return new ValidationError2(errorMessage, errorCode);
+  }
+  if (statusCode === 402) {
+    return new PaymentError(errorMessage, errorCode);
+  }
+  if (statusCode === 0 || statusCode >= 500) {
+    return new NetworkError2(
+      errorMessage,
+      errorCode,
+      statusCode >= 500 ? "The ZendFi API is experiencing issues. Please try again later." : void 0
+    );
+  }
+  return new ApiError(errorMessage, errorCode, statusCode, responseBody);
+}
+var ERROR_CODES = {
+  // Authentication
+  INVALID_API_KEY: "invalid_api_key",
+  API_KEY_EXPIRED: "api_key_expired",
+  API_KEY_REVOKED: "api_key_revoked",
+  // Payment
+  INSUFFICIENT_BALANCE: "insufficient_balance",
+  PAYMENT_DECLINED: "payment_declined",
+  PAYMENT_EXPIRED: "payment_expired",
+  INVALID_AMOUNT: "invalid_amount",
+  INVALID_CURRENCY: "invalid_currency",
+  // Validation
+  MISSING_REQUIRED_FIELD: "missing_required_field",
+  INVALID_PARAMETER: "invalid_parameter",
+  // Network
+  NETWORK_ERROR: "network_error",
+  TIMEOUT: "timeout",
+  // Rate limiting
+  RATE_LIMIT_EXCEEDED: "rate_limit_exceeded",
+  // Webhook
+  WEBHOOK_SIGNATURE_INVALID: "webhook_signature_invalid",
+  WEBHOOK_TIMESTAMP_TOO_OLD: "webhook_timestamp_too_old"
+};
+function isZendFiError(error) {
+  return error instanceof ZendFiError2;
+}
+
+// src/interceptors.ts
+var InterceptorManager = class {
+  handlers = [];
+  /**
+   * Add an interceptor
+   */
+  use(handler) {
+    this.handlers.push(handler);
+    return this.handlers.length - 1;
+  }
+  /**
+   * Remove an interceptor
+   */
+  eject(id) {
+    if (this.handlers[id]) {
+      this.handlers[id] = null;
+    }
+  }
+  /**
+   * Execute all interceptors in sequence
+   */
+  async execute(initialValue) {
+    let result = initialValue;
+    for (const handler of this.handlers) {
+      if (handler !== null) {
+        result = await handler(result);
+      }
+    }
+    return result;
+  }
+  /**
+   * Check if any interceptors are registered
+   */
+  has() {
+    return this.handlers.some((h) => h !== null);
+  }
+  /**
+   * Clear all interceptors
+   */
+  clear() {
+    this.handlers = [];
+  }
+};
+function createInterceptors() {
+  return {
+    request: new InterceptorManager(),
+    response: new InterceptorManager(),
+    error: new InterceptorManager()
+  };
+}
+
 // src/client.ts
 var ZendFiClient = class {
   config;
+  interceptors;
   constructor(options) {
     this.config = ConfigLoader.load(options);
     ConfigLoader.validateApiKey(this.config.apiKey);
-    if (this.config.environment === "development") {
+    this.interceptors = createInterceptors();
+    if (this.config.environment === "development" || this.config.debug) {
       console.log(
         `\u2713 ZendFi SDK initialized in ${this.config.mode} mode (${this.config.mode === "test" ? "devnet" : "mainnet"})`
       );
+      if (this.config.debug) {
+        console.log("[ZendFi] Debug mode enabled");
+      }
     }
   }
   /**
@@ -531,11 +720,12 @@ var ZendFiClient = class {
     return result === 0;
   }
   /**
-   * Make an HTTP request with retry logic
+   * Make an HTTP request with retry logic, interceptors, and debug logging
    */
   async request(method, endpoint, data, options = {}) {
     const attempt = options.attempt || 1;
     const idempotencyKey = options.idempotencyKey || (this.config.idempotencyEnabled && method !== "GET" ? generateIdempotencyKey() : void 0);
+    const startTime = Date.now();
     try {
       const url = `${this.config.baseURL}${endpoint}`;
       const headers = {
@@ -545,12 +735,27 @@ var ZendFiClient = class {
       if (idempotencyKey) {
         headers["Idempotency-Key"] = idempotencyKey;
       }
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-      const response = await fetch(url, {
+      let requestConfig = {
         method,
+        url,
         headers,
-        body: data ? JSON.stringify(data) : void 0,
+        body: data
+      };
+      if (this.interceptors.request.has()) {
+        requestConfig = await this.interceptors.request.execute(requestConfig);
+      }
+      if (this.config.debug) {
+        console.log(`[ZendFi] ${method} ${endpoint}`);
+        if (data) {
+          console.log("[ZendFi] Request:", JSON.stringify(data, null, 2));
+        }
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const response = await fetch(requestConfig.url, {
+        method: requestConfig.method,
+        headers: requestConfig.headers,
+        body: requestConfig.body ? JSON.stringify(requestConfig.body) : void 0,
         signal: controller.signal
       });
       clearTimeout(timeoutId);
@@ -560,32 +765,78 @@ var ZendFiClient = class {
       } catch {
         body = null;
       }
+      const duration = Date.now() - startTime;
       if (!response.ok) {
-        const error = parseError(response, body);
+        const error = createZendFiError(response.status, body);
+        if (this.config.debug) {
+          console.error(`[ZendFi] \u274C ${response.status} ${response.statusText} (${duration}ms)`);
+          console.error(`[ZendFi] Error:`, error.toString());
+        }
         if (response.status >= 500 && attempt < this.config.retries) {
           const delay = Math.pow(2, attempt) * 1e3;
+          if (this.config.debug) {
+            console.log(`[ZendFi] Retrying in ${delay}ms... (attempt ${attempt + 1}/${this.config.retries})`);
+          }
           await sleep(delay);
           return this.request(method, endpoint, data, {
             idempotencyKey,
             attempt: attempt + 1
           });
         }
+        if (this.interceptors.error.has()) {
+          const interceptedError = await this.interceptors.error.execute(error);
+          throw interceptedError;
+        }
         throw error;
       }
-      return body;
+      if (this.config.debug) {
+        console.log(`[ZendFi] \u2713 ${response.status} ${response.statusText} (${duration}ms)`);
+        if (body) {
+          console.log("[ZendFi] Response:", JSON.stringify(body, null, 2));
+        }
+      }
+      const headersObj = {};
+      response.headers.forEach((value, key) => {
+        headersObj[key] = value;
+      });
+      let responseData = {
+        status: response.status,
+        statusText: response.statusText,
+        headers: headersObj,
+        data: body,
+        config: requestConfig
+      };
+      if (this.interceptors.response.has()) {
+        responseData = await this.interceptors.response.execute(responseData);
+      }
+      return responseData.data;
     } catch (error) {
       if (error.name === "AbortError") {
-        throw new Error(`Request timeout after ${this.config.timeout}ms`);
+        const timeoutError = createZendFiError(0, {}, `Request timeout after ${this.config.timeout}ms`);
+        if (this.config.debug) {
+          console.error(`[ZendFi] \u274C Timeout (${this.config.timeout}ms)`);
+        }
+        throw timeoutError;
       }
-      if (attempt < this.config.retries && error.message?.includes("fetch")) {
+      if (attempt < this.config.retries && (error.message?.includes("fetch") || error.message?.includes("network"))) {
         const delay = Math.pow(2, attempt) * 1e3;
+        if (this.config.debug) {
+          console.log(`[ZendFi] Network error, retrying in ${delay}ms... (attempt ${attempt + 1}/${this.config.retries})`);
+        }
         await sleep(delay);
         return this.request(method, endpoint, data, {
           idempotencyKey,
           attempt: attempt + 1
         });
       }
-      throw error;
+      if (isZendFiError(error)) {
+        throw error;
+      }
+      const wrappedError = createZendFiError(0, {}, error.message || "An unknown error occurred");
+      if (this.config.debug) {
+        console.error(`[ZendFi] \u274C Unexpected error:`, error);
+      }
+      throw wrappedError;
     }
   }
 };
@@ -663,13 +914,20 @@ function verifyWebhookSignature(payload, signature, secret) {
   });
 }
 export {
-  AuthenticationError,
+  ApiError,
+  AuthenticationError2 as AuthenticationError,
   ConfigLoader,
-  NetworkError,
-  RateLimitError,
-  ValidationError,
+  ERROR_CODES,
+  InterceptorManager,
+  NetworkError2 as NetworkError,
+  PaymentError,
+  RateLimitError2 as RateLimitError,
+  ValidationError2 as ValidationError,
+  WebhookError,
   ZendFiClient,
-  ZendFiError,
+  ZendFiError2 as ZendFiError,
+  createZendFiError,
+  isZendFiError,
   processWebhook,
   verifyExpressWebhook,
   verifyNextWebhook,

package/dist/nextjs.d.mts

@@ -1,4 +1,4 @@
-import { W as WebhookHandlerConfig, a as WebhookHandlers } from './webhook-handler-DG-zic8m.mjs';
+import { W as WebhookHandlerConfig, a as WebhookHandlers } from './webhook-handler-B9ZczHQn.mjs';
 
 /**
  * Next.js Webhook Handler for App Router

package/dist/nextjs.d.ts

@@ -1,4 +1,4 @@
-import { W as WebhookHandlerConfig, a as WebhookHandlers } from './webhook-handler-DG-zic8m.js';
+import { W as WebhookHandlerConfig, a as WebhookHandlers } from './webhook-handler-B9ZczHQn.js';
 
 /**
  * Next.js Webhook Handler for App Router

package/dist/{webhook-handler-DG-zic8m.d.mts → webhook-handler-B9ZczHQn.d.mts}

@@ -21,6 +21,7 @@ interface ZendFiConfig {
     timeout?: number;
     retries?: number;
     idempotencyEnabled?: boolean;
+    debug?: boolean;
 }
 interface SplitRecipient {
     recipient_wallet: string;
@@ -168,24 +169,6 @@ interface VerifyWebhookRequest {
     signature: string;
     secret: string;
 }
-declare class ZendFiError extends Error {
-    statusCode?: number | undefined;
-    code?: string | undefined;
-    details?: any | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: any | undefined);
-}
-declare class AuthenticationError extends ZendFiError {
-    constructor(message?: string);
-}
-declare class ValidationError extends ZendFiError {
-    constructor(message: string, details?: any);
-}
-declare class NetworkError extends ZendFiError {
-    constructor(message: string);
-}
-declare class RateLimitError extends ZendFiError {
-    constructor(message?: string);
-}
 /**
  * Installment Plans - Pay over time
  */
@@ -387,4 +370,4 @@ interface WebhookResult {
 }
 declare function processWebhook(a: any, b?: any, c?: any): Promise<WebhookResult>;
 
-export { type ApproveEscrowRequest as A, type SplitRecipient as B, type CreatePaymentRequest as C, type DisputeEscrowRequest as D, type Escrow as E, ZendFiError as F, AuthenticationError as G, ValidationError as H, type InstallmentPlan as I, RateLimitError as J, type InstallmentScheduleItem as K, type ListPaymentsRequest as L, type CreateInstallmentPlanResponse as M, NetworkError as N, type ReleaseCondition as O, type Payment as P, type InvoiceLineItem as Q, type RefundEscrowRequest as R, type SubscriptionPlan as S, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type ZendFiConfig as Z, type WebhookHandlers as a, type PaginatedResponse as b, type CreateSubscriptionPlanRequest as c, type CreateSubscriptionRequest as d, type Subscription as e, type CreatePaymentLinkRequest as f, type PaymentLink as g, type CreateInstallmentPlanRequest as h, type CreateEscrowRequest as i, type CreateInvoiceRequest as j, type Invoice as k, type WebhookPayload as l, type WebhookResult as m, type WebhookEventHandler as n, type Environment as o, processWebhook as p, type ApiKeyMode as q, type Currency as r, type PaymentToken as s, type PaymentStatus as t, type SubscriptionStatus as u, type InstallmentPlanStatus as v, type EscrowStatus as w, type InvoiceStatus as x, type SplitStatus as y, type WebhookEvent as z };
+export { type ApproveEscrowRequest as A, type SplitRecipient as B, type CreatePaymentRequest as C, type DisputeEscrowRequest as D, type Escrow as E, type InstallmentScheduleItem as F, type CreateInstallmentPlanResponse as G, type ReleaseCondition as H, type InstallmentPlan as I, type InvoiceLineItem as J, type ListPaymentsRequest as L, type Payment as P, type RefundEscrowRequest as R, type SubscriptionPlan as S, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type ZendFiConfig as Z, type WebhookHandlers as a, type PaginatedResponse as b, type CreateSubscriptionPlanRequest as c, type CreateSubscriptionRequest as d, type Subscription as e, type CreatePaymentLinkRequest as f, type PaymentLink as g, type CreateInstallmentPlanRequest as h, type CreateEscrowRequest as i, type CreateInvoiceRequest as j, type Invoice as k, type WebhookPayload as l, type WebhookResult as m, type WebhookEventHandler as n, type Environment as o, processWebhook as p, type ApiKeyMode as q, type Currency as r, type PaymentToken as s, type PaymentStatus as t, type SubscriptionStatus as u, type InstallmentPlanStatus as v, type EscrowStatus as w, type InvoiceStatus as x, type SplitStatus as y, type WebhookEvent as z };

package/dist/{webhook-handler-DG-zic8m.d.ts → webhook-handler-B9ZczHQn.d.ts}

@@ -21,6 +21,7 @@ interface ZendFiConfig {
     timeout?: number;
     retries?: number;
     idempotencyEnabled?: boolean;
+    debug?: boolean;
 }
 interface SplitRecipient {
     recipient_wallet: string;
@@ -168,24 +169,6 @@ interface VerifyWebhookRequest {
     signature: string;
     secret: string;
 }
-declare class ZendFiError extends Error {
-    statusCode?: number | undefined;
-    code?: string | undefined;
-    details?: any | undefined;
-    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: any | undefined);
-}
-declare class AuthenticationError extends ZendFiError {
-    constructor(message?: string);
-}
-declare class ValidationError extends ZendFiError {
-    constructor(message: string, details?: any);
-}
-declare class NetworkError extends ZendFiError {
-    constructor(message: string);
-}
-declare class RateLimitError extends ZendFiError {
-    constructor(message?: string);
-}
 /**
  * Installment Plans - Pay over time
  */
@@ -387,4 +370,4 @@ interface WebhookResult {
 }
 declare function processWebhook(a: any, b?: any, c?: any): Promise<WebhookResult>;
 
-export { type ApproveEscrowRequest as A, type SplitRecipient as B, type CreatePaymentRequest as C, type DisputeEscrowRequest as D, type Escrow as E, ZendFiError as F, AuthenticationError as G, ValidationError as H, type InstallmentPlan as I, RateLimitError as J, type InstallmentScheduleItem as K, type ListPaymentsRequest as L, type CreateInstallmentPlanResponse as M, NetworkError as N, type ReleaseCondition as O, type Payment as P, type InvoiceLineItem as Q, type RefundEscrowRequest as R, type SubscriptionPlan as S, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type ZendFiConfig as Z, type WebhookHandlers as a, type PaginatedResponse as b, type CreateSubscriptionPlanRequest as c, type CreateSubscriptionRequest as d, type Subscription as e, type CreatePaymentLinkRequest as f, type PaymentLink as g, type CreateInstallmentPlanRequest as h, type CreateEscrowRequest as i, type CreateInvoiceRequest as j, type Invoice as k, type WebhookPayload as l, type WebhookResult as m, type WebhookEventHandler as n, type Environment as o, processWebhook as p, type ApiKeyMode as q, type Currency as r, type PaymentToken as s, type PaymentStatus as t, type SubscriptionStatus as u, type InstallmentPlanStatus as v, type EscrowStatus as w, type InvoiceStatus as x, type SplitStatus as y, type WebhookEvent as z };
+export { type ApproveEscrowRequest as A, type SplitRecipient as B, type CreatePaymentRequest as C, type DisputeEscrowRequest as D, type Escrow as E, type InstallmentScheduleItem as F, type CreateInstallmentPlanResponse as G, type ReleaseCondition as H, type InstallmentPlan as I, type InvoiceLineItem as J, type ListPaymentsRequest as L, type Payment as P, type RefundEscrowRequest as R, type SubscriptionPlan as S, type VerifyWebhookRequest as V, type WebhookHandlerConfig as W, type ZendFiConfig as Z, type WebhookHandlers as a, type PaginatedResponse as b, type CreateSubscriptionPlanRequest as c, type CreateSubscriptionRequest as d, type Subscription as e, type CreatePaymentLinkRequest as f, type PaymentLink as g, type CreateInstallmentPlanRequest as h, type CreateEscrowRequest as i, type CreateInvoiceRequest as j, type Invoice as k, type WebhookPayload as l, type WebhookResult as m, type WebhookEventHandler as n, type Environment as o, processWebhook as p, type ApiKeyMode as q, type Currency as r, type PaymentToken as s, type PaymentStatus as t, type SubscriptionStatus as u, type InstallmentPlanStatus as v, type EscrowStatus as w, type InvoiceStatus as x, type SplitStatus as y, type WebhookEvent as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendfi/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Zero-config TypeScript SDK for ZendFi crypto payments",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",