@zendfi/sdk 0.3.1 → 0.4.0

package/dist/index.d.mts

@@ -1,5 +1,61 @@
-import { Z as ZendFiConfig, C as CreatePaymentRequest, P as Payment, L as ListPaymentsRequest, b as PaginatedResponse, c as CreateSubscriptionPlanRequest, S as SubscriptionPlan, d as CreateSubscriptionRequest, e as Subscription, f as CreatePaymentLinkRequest, g as PaymentLink, h as CreateInstallmentPlanRequest, I as InstallmentPlan, i as CreateEscrowRequest, E as Escrow, A as ApproveEscrowRequest, R as RefundEscrowRequest, D as DisputeEscrowRequest, j as CreateInvoiceRequest, k as Invoice, V as VerifyWebhookRequest, l as WebhookPayload } from './webhook-handler-DG-zic8m.mjs';
-export { q as ApiKeyMode, G as AuthenticationError, M as CreateInstallmentPlanResponse, r as Currency, o as Environment, w as EscrowStatus, v as InstallmentPlanStatus, K as InstallmentScheduleItem, Q as InvoiceLineItem, x as InvoiceStatus, N as NetworkError, t as PaymentStatus, s as PaymentToken, J as RateLimitError, O as ReleaseCondition, B as SplitRecipient, y as SplitStatus, u as SubscriptionStatus, H as ValidationError, z as WebhookEvent, n as WebhookEventHandler, W as WebhookHandlerConfig, a as WebhookHandlers, m as WebhookResult, F as ZendFiError, p as processWebhook } from './webhook-handler-DG-zic8m.mjs';
+import { Z as ZendFiConfig, C as CreatePaymentRequest, P as Payment, L as ListPaymentsRequest, b as PaginatedResponse, c as CreateSubscriptionPlanRequest, S as SubscriptionPlan, d as CreateSubscriptionRequest, e as Subscription, f as CreatePaymentLinkRequest, g as PaymentLink, h as CreateInstallmentPlanRequest, I as InstallmentPlan, i as CreateEscrowRequest, E as Escrow, A as ApproveEscrowRequest, R as RefundEscrowRequest, D as DisputeEscrowRequest, j as CreateInvoiceRequest, k as Invoice, V as VerifyWebhookRequest, l as WebhookPayload } from './webhook-handler-B9ZczHQn.mjs';
+export { q as ApiKeyMode, G as CreateInstallmentPlanResponse, r as Currency, o as Environment, w as EscrowStatus, v as InstallmentPlanStatus, F as InstallmentScheduleItem, J as InvoiceLineItem, x as InvoiceStatus, t as PaymentStatus, s as PaymentToken, H as ReleaseCondition, B as SplitRecipient, y as SplitStatus, u as SubscriptionStatus, z as WebhookEvent, n as WebhookEventHandler, W as WebhookHandlerConfig, a as WebhookHandlers, m as WebhookResult, p as processWebhook } from './webhook-handler-B9ZczHQn.mjs';
+
+/**
+ * Request/Response Interceptor System
+ *
+ * Allows modifying requests before they're sent and responses after they're received
+ */
+interface RequestConfig {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: any;
+}
+interface ResponseData {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    data: any;
+    config: RequestConfig;
+}
+type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+type ResponseInterceptor = (response: ResponseData) => ResponseData | Promise<ResponseData>;
+type ErrorInterceptor = (error: Error) => Error | Promise<Error>;
+/**
+ * Interceptor Manager
+ */
+declare class InterceptorManager<T extends (...args: any[]) => any> {
+    private handlers;
+    /**
+     * Add an interceptor
+     */
+    use(handler: T): number;
+    /**
+     * Remove an interceptor
+     */
+    eject(id: number): void;
+    /**
+     * Execute all interceptors in sequence
+     */
+    execute(initialValue: Parameters<T>[0]): Promise<ReturnType<T>>;
+    /**
+     * Check if any interceptors are registered
+     */
+    has(): boolean;
+    /**
+     * Clear all interceptors
+     */
+    clear(): void;
+}
+/**
+ * Interceptors collection
+ */
+interface Interceptors {
+    request: InterceptorManager<RequestInterceptor>;
+    response: InterceptorManager<ResponseInterceptor>;
+    error: InterceptorManager<ErrorInterceptor>;
+}
 
 /**
  * ZendFi SDK Client.
@@ -7,6 +63,7 @@ export { q as ApiKeyMode, G as AuthenticationError, M as CreateInstallmentPlanRe
  */
 declare class ZendFiClient {
     private config;
+    readonly interceptors: Interceptors;
     constructor(options?: Partial<ZendFiConfig>);
     /**
      * Create a new payment
@@ -174,7 +231,7 @@ declare class ZendFiClient {
      */
     private timingSafeEqual;
     /**
-     * Make an HTTP request with retry logic
+     * Make an HTTP request with retry logic, interceptors, and debug logging
      */
     private request;
 }
@@ -295,4 +352,109 @@ declare function verifyExpressWebhook(request: any, secret?: string): Promise<We
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 
-export { ApproveEscrowRequest, ConfigLoader, CreateEscrowRequest, CreateInstallmentPlanRequest, CreateInvoiceRequest, CreatePaymentLinkRequest, CreatePaymentRequest, CreateSubscriptionPlanRequest, CreateSubscriptionRequest, DisputeEscrowRequest, Escrow, InstallmentPlan, Invoice, ListPaymentsRequest, PaginatedResponse, Payment, PaymentLink, RefundEscrowRequest, Subscription, SubscriptionPlan, VerifyWebhookRequest, WebhookPayload, ZendFiClient, ZendFiConfig, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };
+/**
+ * ZendFi SDK Error Classes
+ *
+ * Custom error types with helpful messages, error codes, and documentation links
+ */
+type ZendFiErrorType = 'authentication_error' | 'payment_error' | 'validation_error' | 'network_error' | 'rate_limit_error' | 'api_error' | 'webhook_error' | 'unknown_error';
+interface ZendFiErrorData {
+    code: string;
+    message: string;
+    type: ZendFiErrorType;
+    suggestion?: string;
+    statusCode?: number;
+    response?: unknown;
+}
+/**
+ * Base ZendFi Error class with enhanced developer experience
+ */
+declare class ZendFiError extends Error {
+    readonly code: string;
+    readonly type: ZendFiErrorType;
+    readonly suggestion?: string;
+    readonly docs_url: string;
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    constructor(data: ZendFiErrorData);
+    /**
+     * Format error for display
+     */
+    toString(): string;
+    /**
+     * Convert error to JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication errors
+ */
+declare class AuthenticationError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Payment processing errors
+ */
+declare class PaymentError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Validation errors
+ */
+declare class ValidationError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Network/connection errors
+ */
+declare class NetworkError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Rate limit errors
+ */
+declare class RateLimitError extends ZendFiError {
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Generic API errors
+ */
+declare class ApiError extends ZendFiError {
+    constructor(message: string, code: string, statusCode: number, response?: unknown);
+}
+/**
+ * Webhook verification errors
+ */
+declare class WebhookError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Error factory - creates appropriate error based on response
+ */
+declare function createZendFiError(statusCode: number, responseBody: any, message?: string): ZendFiError;
+/**
+ * Common error codes and their messages
+ */
+declare const ERROR_CODES: {
+    readonly INVALID_API_KEY: "invalid_api_key";
+    readonly API_KEY_EXPIRED: "api_key_expired";
+    readonly API_KEY_REVOKED: "api_key_revoked";
+    readonly INSUFFICIENT_BALANCE: "insufficient_balance";
+    readonly PAYMENT_DECLINED: "payment_declined";
+    readonly PAYMENT_EXPIRED: "payment_expired";
+    readonly INVALID_AMOUNT: "invalid_amount";
+    readonly INVALID_CURRENCY: "invalid_currency";
+    readonly MISSING_REQUIRED_FIELD: "missing_required_field";
+    readonly INVALID_PARAMETER: "invalid_parameter";
+    readonly NETWORK_ERROR: "network_error";
+    readonly TIMEOUT: "timeout";
+    readonly RATE_LIMIT_EXCEEDED: "rate_limit_exceeded";
+    readonly WEBHOOK_SIGNATURE_INVALID: "webhook_signature_invalid";
+    readonly WEBHOOK_TIMESTAMP_TOO_OLD: "webhook_timestamp_too_old";
+};
+/**
+ * Helper to check if error is a ZendFi error
+ */
+declare function isZendFiError(error: unknown): error is ZendFiError;
+
+export { ApiError, ApproveEscrowRequest, AuthenticationError, ConfigLoader, CreateEscrowRequest, CreateInstallmentPlanRequest, CreateInvoiceRequest, CreatePaymentLinkRequest, CreatePaymentRequest, CreateSubscriptionPlanRequest, CreateSubscriptionRequest, DisputeEscrowRequest, ERROR_CODES, type ErrorInterceptor, Escrow, InstallmentPlan, InterceptorManager, type Interceptors, Invoice, ListPaymentsRequest, NetworkError, PaginatedResponse, Payment, PaymentError, PaymentLink, RateLimitError, RefundEscrowRequest, type RequestConfig, type RequestInterceptor, type ResponseData, type ResponseInterceptor, Subscription, SubscriptionPlan, ValidationError, VerifyWebhookRequest, WebhookError, WebhookPayload, ZendFiClient, ZendFiConfig, ZendFiError, type ZendFiErrorData, type ZendFiErrorType, createZendFiError, isZendFiError, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };

package/dist/index.d.ts

@@ -1,5 +1,61 @@
-import { Z as ZendFiConfig, C as CreatePaymentRequest, P as Payment, L as ListPaymentsRequest, b as PaginatedResponse, c as CreateSubscriptionPlanRequest, S as SubscriptionPlan, d as CreateSubscriptionRequest, e as Subscription, f as CreatePaymentLinkRequest, g as PaymentLink, h as CreateInstallmentPlanRequest, I as InstallmentPlan, i as CreateEscrowRequest, E as Escrow, A as ApproveEscrowRequest, R as RefundEscrowRequest, D as DisputeEscrowRequest, j as CreateInvoiceRequest, k as Invoice, V as VerifyWebhookRequest, l as WebhookPayload } from './webhook-handler-DG-zic8m.js';
-export { q as ApiKeyMode, G as AuthenticationError, M as CreateInstallmentPlanResponse, r as Currency, o as Environment, w as EscrowStatus, v as InstallmentPlanStatus, K as InstallmentScheduleItem, Q as InvoiceLineItem, x as InvoiceStatus, N as NetworkError, t as PaymentStatus, s as PaymentToken, J as RateLimitError, O as ReleaseCondition, B as SplitRecipient, y as SplitStatus, u as SubscriptionStatus, H as ValidationError, z as WebhookEvent, n as WebhookEventHandler, W as WebhookHandlerConfig, a as WebhookHandlers, m as WebhookResult, F as ZendFiError, p as processWebhook } from './webhook-handler-DG-zic8m.js';
+import { Z as ZendFiConfig, C as CreatePaymentRequest, P as Payment, L as ListPaymentsRequest, b as PaginatedResponse, c as CreateSubscriptionPlanRequest, S as SubscriptionPlan, d as CreateSubscriptionRequest, e as Subscription, f as CreatePaymentLinkRequest, g as PaymentLink, h as CreateInstallmentPlanRequest, I as InstallmentPlan, i as CreateEscrowRequest, E as Escrow, A as ApproveEscrowRequest, R as RefundEscrowRequest, D as DisputeEscrowRequest, j as CreateInvoiceRequest, k as Invoice, V as VerifyWebhookRequest, l as WebhookPayload } from './webhook-handler-B9ZczHQn.js';
+export { q as ApiKeyMode, G as CreateInstallmentPlanResponse, r as Currency, o as Environment, w as EscrowStatus, v as InstallmentPlanStatus, F as InstallmentScheduleItem, J as InvoiceLineItem, x as InvoiceStatus, t as PaymentStatus, s as PaymentToken, H as ReleaseCondition, B as SplitRecipient, y as SplitStatus, u as SubscriptionStatus, z as WebhookEvent, n as WebhookEventHandler, W as WebhookHandlerConfig, a as WebhookHandlers, m as WebhookResult, p as processWebhook } from './webhook-handler-B9ZczHQn.js';
+
+/**
+ * Request/Response Interceptor System
+ *
+ * Allows modifying requests before they're sent and responses after they're received
+ */
+interface RequestConfig {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: any;
+}
+interface ResponseData {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    data: any;
+    config: RequestConfig;
+}
+type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+type ResponseInterceptor = (response: ResponseData) => ResponseData | Promise<ResponseData>;
+type ErrorInterceptor = (error: Error) => Error | Promise<Error>;
+/**
+ * Interceptor Manager
+ */
+declare class InterceptorManager<T extends (...args: any[]) => any> {
+    private handlers;
+    /**
+     * Add an interceptor
+     */
+    use(handler: T): number;
+    /**
+     * Remove an interceptor
+     */
+    eject(id: number): void;
+    /**
+     * Execute all interceptors in sequence
+     */
+    execute(initialValue: Parameters<T>[0]): Promise<ReturnType<T>>;
+    /**
+     * Check if any interceptors are registered
+     */
+    has(): boolean;
+    /**
+     * Clear all interceptors
+     */
+    clear(): void;
+}
+/**
+ * Interceptors collection
+ */
+interface Interceptors {
+    request: InterceptorManager<RequestInterceptor>;
+    response: InterceptorManager<ResponseInterceptor>;
+    error: InterceptorManager<ErrorInterceptor>;
+}
 
 /**
  * ZendFi SDK Client.
@@ -7,6 +63,7 @@ export { q as ApiKeyMode, G as AuthenticationError, M as CreateInstallmentPlanRe
  */
 declare class ZendFiClient {
     private config;
+    readonly interceptors: Interceptors;
     constructor(options?: Partial<ZendFiConfig>);
     /**
      * Create a new payment
@@ -174,7 +231,7 @@ declare class ZendFiClient {
      */
     private timingSafeEqual;
     /**
-     * Make an HTTP request with retry logic
+     * Make an HTTP request with retry logic, interceptors, and debug logging
      */
     private request;
 }
@@ -295,4 +352,109 @@ declare function verifyExpressWebhook(request: any, secret?: string): Promise<We
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 
-export { ApproveEscrowRequest, ConfigLoader, CreateEscrowRequest, CreateInstallmentPlanRequest, CreateInvoiceRequest, CreatePaymentLinkRequest, CreatePaymentRequest, CreateSubscriptionPlanRequest, CreateSubscriptionRequest, DisputeEscrowRequest, Escrow, InstallmentPlan, Invoice, ListPaymentsRequest, PaginatedResponse, Payment, PaymentLink, RefundEscrowRequest, Subscription, SubscriptionPlan, VerifyWebhookRequest, WebhookPayload, ZendFiClient, ZendFiConfig, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };
+/**
+ * ZendFi SDK Error Classes
+ *
+ * Custom error types with helpful messages, error codes, and documentation links
+ */
+type ZendFiErrorType = 'authentication_error' | 'payment_error' | 'validation_error' | 'network_error' | 'rate_limit_error' | 'api_error' | 'webhook_error' | 'unknown_error';
+interface ZendFiErrorData {
+    code: string;
+    message: string;
+    type: ZendFiErrorType;
+    suggestion?: string;
+    statusCode?: number;
+    response?: unknown;
+}
+/**
+ * Base ZendFi Error class with enhanced developer experience
+ */
+declare class ZendFiError extends Error {
+    readonly code: string;
+    readonly type: ZendFiErrorType;
+    readonly suggestion?: string;
+    readonly docs_url: string;
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    constructor(data: ZendFiErrorData);
+    /**
+     * Format error for display
+     */
+    toString(): string;
+    /**
+     * Convert error to JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication errors
+ */
+declare class AuthenticationError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Payment processing errors
+ */
+declare class PaymentError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Validation errors
+ */
+declare class ValidationError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Network/connection errors
+ */
+declare class NetworkError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Rate limit errors
+ */
+declare class RateLimitError extends ZendFiError {
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Generic API errors
+ */
+declare class ApiError extends ZendFiError {
+    constructor(message: string, code: string, statusCode: number, response?: unknown);
+}
+/**
+ * Webhook verification errors
+ */
+declare class WebhookError extends ZendFiError {
+    constructor(message: string, code?: string, suggestion?: string);
+}
+/**
+ * Error factory - creates appropriate error based on response
+ */
+declare function createZendFiError(statusCode: number, responseBody: any, message?: string): ZendFiError;
+/**
+ * Common error codes and their messages
+ */
+declare const ERROR_CODES: {
+    readonly INVALID_API_KEY: "invalid_api_key";
+    readonly API_KEY_EXPIRED: "api_key_expired";
+    readonly API_KEY_REVOKED: "api_key_revoked";
+    readonly INSUFFICIENT_BALANCE: "insufficient_balance";
+    readonly PAYMENT_DECLINED: "payment_declined";
+    readonly PAYMENT_EXPIRED: "payment_expired";
+    readonly INVALID_AMOUNT: "invalid_amount";
+    readonly INVALID_CURRENCY: "invalid_currency";
+    readonly MISSING_REQUIRED_FIELD: "missing_required_field";
+    readonly INVALID_PARAMETER: "invalid_parameter";
+    readonly NETWORK_ERROR: "network_error";
+    readonly TIMEOUT: "timeout";
+    readonly RATE_LIMIT_EXCEEDED: "rate_limit_exceeded";
+    readonly WEBHOOK_SIGNATURE_INVALID: "webhook_signature_invalid";
+    readonly WEBHOOK_TIMESTAMP_TOO_OLD: "webhook_timestamp_too_old";
+};
+/**
+ * Helper to check if error is a ZendFi error
+ */
+declare function isZendFiError(error: unknown): error is ZendFiError;
+
+export { ApiError, ApproveEscrowRequest, AuthenticationError, ConfigLoader, CreateEscrowRequest, CreateInstallmentPlanRequest, CreateInvoiceRequest, CreatePaymentLinkRequest, CreatePaymentRequest, CreateSubscriptionPlanRequest, CreateSubscriptionRequest, DisputeEscrowRequest, ERROR_CODES, type ErrorInterceptor, Escrow, InstallmentPlan, InterceptorManager, type Interceptors, Invoice, ListPaymentsRequest, NetworkError, PaginatedResponse, Payment, PaymentError, PaymentLink, RateLimitError, RefundEscrowRequest, type RequestConfig, type RequestInterceptor, type ResponseData, type ResponseInterceptor, Subscription, SubscriptionPlan, ValidationError, VerifyWebhookRequest, WebhookError, WebhookPayload, ZendFiClient, ZendFiConfig, ZendFiError, type ZendFiErrorData, type ZendFiErrorType, createZendFiError, isZendFiError, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };