@zendfi/sdk 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -1,328 +1,9 @@
-/**
- * ZendFi SDK Types
- * Complete type definitions for the ZendFi API
- */
-type Environment = 'development' | 'staging' | 'production';
-type Currency = 'USD' | 'EUR' | 'GBP';
-type PaymentToken = 'SOL' | 'USDC' | 'USDT';
-type PaymentStatus = 'pending' | 'confirmed' | 'failed' | 'expired';
-type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'paused';
-type InstallmentPlanStatus = 'active' | 'completed' | 'defaulted' | 'cancelled';
-type EscrowStatus = 'pending' | 'funded' | 'released' | 'refunded' | 'disputed' | 'cancelled';
-type InvoiceStatus = 'draft' | 'sent' | 'paid';
-type SplitStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded';
-type WebhookEvent = 'payment.created' | 'payment.confirmed' | 'payment.failed' | 'payment.expired' | 'subscription.created' | 'subscription.activated' | 'subscription.canceled' | 'subscription.payment_failed' | 'split.completed' | 'split.failed' | 'installment.due' | 'installment.paid' | 'installment.late' | 'escrow.funded' | 'escrow.released' | 'escrow.refunded' | 'escrow.disputed' | 'invoice.sent' | 'invoice.paid';
-interface ZendFiConfig {
-    apiKey?: string;
-    baseURL?: string;
-    environment?: Environment;
-    timeout?: number;
-    retries?: number;
-    idempotencyEnabled?: boolean;
-}
-interface SplitRecipient {
-    recipient_wallet: string;
-    recipient_name?: string;
-    percentage?: number;
-    fixed_amount_usd?: number;
-    split_order?: number;
-}
-interface CreatePaymentRequest {
-    amount: number;
-    currency?: Currency;
-    token?: PaymentToken;
-    description?: string;
-    customer_email?: string;
-    redirect_url?: string;
-    metadata?: Record<string, any>;
-    split_recipients?: SplitRecipient[];
-}
-/**
- * Payment Link - Shareable checkout links
- */
-interface CreatePaymentLinkRequest {
-    amount: number;
-    currency?: string;
-    token?: string;
-    description?: string;
-    max_uses?: number;
-    expires_at?: string;
-    metadata?: Record<string, any>;
-}
-interface PaymentLink {
-    id: string;
-    link_code: string;
-    payment_url: string;
-    hosted_page_url: string;
-    amount: number;
-    currency: string;
-    token: string;
-    max_uses?: number;
-    uses_count: number;
-    expires_at?: string;
-    is_active: boolean;
-    created_at: string;
-    url: string;
-}
-interface Payment {
-    id: string;
-    merchant_id: string;
-    amount_usd?: number;
-    amount?: number;
-    currency?: string;
-    payment_token?: PaymentToken;
-    status: PaymentStatus;
-    customer_wallet?: string;
-    customer_email?: string;
-    description?: string;
-    checkout_url?: string;
-    payment_url?: string;
-    qr_code?: string;
-    expires_at: string;
-    confirmed_at?: string;
-    transaction_signature?: string;
-    metadata?: Record<string, any>;
-    split_ids?: string[];
-    created_at?: string;
-    updated_at?: string;
-}
-interface ListPaymentsRequest {
-    page?: number;
-    limit?: number;
-    status?: PaymentStatus;
-    from_date?: string;
-    to_date?: string;
-}
-interface PaginatedResponse<T> {
-    data: T[];
-    pagination: {
-        page: number;
-        limit: number;
-        total: number;
-        total_pages: number;
-    };
-}
-interface CreateSubscriptionPlanRequest {
-    name: string;
-    description?: string;
-    amount: number;
-    currency?: Currency;
-    interval: 'daily' | 'weekly' | 'monthly' | 'yearly';
-    interval_count?: number;
-    trial_days?: number;
-    metadata?: Record<string, any>;
-}
-interface SubscriptionPlan {
-    id: string;
-    merchant_id: string;
-    name: string;
-    description?: string;
-    amount: number;
-    currency: Currency;
-    interval: string;
-    interval_count: number;
-    trial_days: number;
-    is_active: boolean;
-    metadata?: Record<string, any>;
-    created_at: string;
-    updated_at: string;
-}
-interface CreateSubscriptionRequest {
-    plan_id: string;
-    customer_email: string;
-    customer_wallet?: string;
-    metadata?: Record<string, any>;
-}
-interface Subscription {
-    id: string;
-    plan_id: string;
-    merchant_id: string;
-    customer_email: string;
-    customer_wallet?: string;
-    status: SubscriptionStatus;
-    current_period_start: string;
-    current_period_end: string;
-    trial_end?: string;
-    canceled_at?: string;
-    metadata?: Record<string, any>;
-    created_at: string;
-    updated_at: string;
-}
-interface WebhookPayload {
-    event: WebhookEvent;
-    timestamp: string;
-    merchant_id: string;
-    data: Payment | Subscription;
-}
-interface VerifyWebhookRequest {
-    payload: string | object;
-    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
- */
-interface InstallmentScheduleItem {
-    installment_number: number;
-    due_date: string;
-    amount: string;
-    status: string;
-    payment_id?: string;
-    paid_at?: string;
-}
-interface CreateInstallmentPlanRequest {
-    customer_wallet: string;
-    customer_email?: string;
-    total_amount: number;
-    installment_count: number;
-    first_payment_date?: string;
-    payment_frequency_days: number;
-    description?: string;
-    late_fee_amount?: number;
-    grace_period_days?: number;
-    metadata?: Record<string, any>;
-}
-interface CreateInstallmentPlanResponse {
-    plan_id: string;
-    status: string;
-}
-interface InstallmentPlan {
-    id?: string;
-    plan_id?: string;
-    merchant_id?: string;
-    customer_wallet?: string;
-    customer_email?: string;
-    total_amount?: string;
-    installment_count?: number;
-    amount_per_installment?: string;
-    payment_schedule?: InstallmentScheduleItem[];
-    paid_count?: number;
-    status: InstallmentPlanStatus | string;
-    description?: string;
-    late_fee_amount?: string;
-    grace_period_days?: number;
-    metadata?: Record<string, any>;
-    created_at?: string;
-    updated_at?: string;
-    completed_at?: string;
-    defaulted_at?: string;
-}
-/**
- * Escrow - Secure fund holding
- */
-interface ReleaseCondition {
-    type: 'manual_approval' | 'time_based' | 'confirmation_required' | 'milestone';
-    approver?: string;
-    approved?: boolean;
-    release_after?: string;
-    confirmations_needed?: number;
-    confirmed_by?: string[];
-    description?: string;
-    approved_by?: string;
-}
-interface CreateEscrowRequest {
-    buyer_wallet: string;
-    seller_wallet: string;
-    amount: number;
-    currency?: Currency;
-    token?: PaymentToken;
-    description?: string;
-    release_conditions: ReleaseCondition;
-    metadata?: Record<string, any>;
-}
-interface Escrow {
-    id: string;
-    payment_id: string;
-    merchant_id: string;
-    buyer_wallet: string;
-    seller_wallet: string;
-    escrow_wallet: string;
-    amount: number;
-    currency: Currency;
-    token: PaymentToken;
-    release_conditions: ReleaseCondition;
-    status: EscrowStatus;
-    payment_url?: string;
-    qr_code?: string;
-    funded_at?: string;
-    released_at?: string;
-    refunded_at?: string;
-    disputed_at?: string;
-    dispute_reason?: string;
-    release_transaction_signature?: string;
-    refund_transaction_signature?: string;
-    metadata?: Record<string, any>;
-    created_at: string;
-    updated_at: string;
-}
-interface ApproveEscrowRequest {
-    approver_wallet: string;
-}
-interface RefundEscrowRequest {
-    reason: string;
-}
-interface DisputeEscrowRequest {
-    reason: string;
-}
-/**
- * Invoices - Professional billing
- */
-interface InvoiceLineItem {
-    description: string;
-    quantity: number;
-    unit_price: number;
-}
-interface CreateInvoiceRequest {
-    customer_email: string;
-    customer_name?: string;
-    amount: number;
-    token?: PaymentToken;
-    description: string;
-    line_items?: InvoiceLineItem[];
-    due_date?: string;
-    metadata?: Record<string, any>;
-}
-interface Invoice {
-    id: string;
-    invoice_number: string;
-    merchant_id: string;
-    customer_email: string;
-    customer_name?: string;
-    amount_usd: number;
-    token: PaymentToken;
-    description: string;
-    line_items?: InvoiceLineItem[];
-    status: InvoiceStatus;
-    payment_url?: string;
-    due_date?: string;
-    sent_at?: string;
-    paid_at?: string;
-    metadata?: Record<string, any>;
-    created_at: string;
-    updated_at: string;
-}
+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';
 
 /**
- * ZendFi SDK Client
- * Zero-config TypeScript SDK for crypto payments
+ * ZendFi SDK Client.
+ * AZero-config TypeScript SDK for crypto payments
  */
 declare class ZendFiClient {
     private config;
@@ -368,7 +49,7 @@ declare class ZendFiClient {
      */
     getPaymentLink(linkCode: string): Promise<PaymentLink>;
     /**
-     * List all payment links
+     * List all payment links for the authenticated merchant
      */
     listPaymentLinks(): Promise<PaymentLink[]>;
     /**
@@ -515,6 +196,10 @@ declare class ConfigLoader {
      * Load configuration from various sources
      */
     static load(options?: Partial<ZendFiConfig>): Required<ZendFiConfig>;
+    /**
+     * Detect mode (test/live) from API key prefix
+     */
+    private static detectMode;
     /**
      * Detect environment based on various signals
      */
@@ -525,6 +210,8 @@ declare class ConfigLoader {
     private static loadApiKey;
     /**
      * Get base URL for API
+     * Note: Both test and live modes use the same API endpoint.
+     * The backend routes requests to devnet or mainnet based on API key prefix.
      */
     private static getBaseURL;
     /**
@@ -608,64 +295,4 @@ declare function verifyExpressWebhook(request: any, secret?: string): Promise<We
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 
-/**
- * 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 };
+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 };

package/dist/index.js

@@ -92,16 +92,30 @@ var ConfigLoader = class {
   static load(options) {
     const environment = this.detectEnvironment();
     const apiKey = this.loadApiKey(options?.apiKey);
-    const baseURL = this.getBaseURL(environment, options?.baseURL);
+    const mode = this.detectMode(apiKey);
+    const baseURL = this.getBaseURL(environment, mode, options?.baseURL);
     return {
       apiKey,
       baseURL,
       environment,
+      mode,
       timeout: options?.timeout ?? 3e4,
       retries: options?.retries ?? 3,
       idempotencyEnabled: options?.idempotencyEnabled ?? true
     };
   }
+  /**
+   * Detect mode (test/live) from API key prefix
+   */
+  static detectMode(apiKey) {
+    if (apiKey.startsWith("zfi_test_")) {
+      return "test";
+    }
+    if (apiKey.startsWith("zfi_live_")) {
+      return "live";
+    }
+    return "live";
+  }
   /**
    * Detect environment based on various signals
    */
@@ -150,8 +164,10 @@ var ConfigLoader = class {
   }
   /**
    * Get base URL for API
+   * Note: Both test and live modes use the same API endpoint.
+   * The backend routes requests to devnet or mainnet based on API key prefix.
    */
-  static getBaseURL(_environment, explicitURL) {
+  static getBaseURL(_environment, _mode, explicitURL) {
     if (explicitURL) return explicitURL;
     return process.env.ZENDFI_API_URL || "https://api.zendfi.tech";
   }
@@ -183,13 +199,17 @@ var ConfigLoader = class {
         'Invalid API key format. ZendFi API keys should start with "zfi_test_" or "zfi_live_"'
       );
     }
-    if (apiKey.startsWith("zfi_live_")) {
-      const env = this.detectEnvironment();
-      if (env === "development") {
-        console.warn(
-          "\u26A0\uFE0F  Warning: Using a live API key (zfi_live_) in development environment. This will create real transactions. Use a test key (zfi_test_) for development."
-        );
-      }
+    const mode = this.detectMode(apiKey);
+    const env = this.detectEnvironment();
+    if (mode === "live" && env === "development") {
+      console.warn(
+        "\u26A0\uFE0F  Warning: Using a live API key (zfi_live_) in development environment. This will create real mainnet transactions. Use a test key (zfi_test_) for devnet testing."
+      );
+    }
+    if (mode === "test" && env === "production") {
+      console.warn(
+        "\u26A0\uFE0F  Warning: Using a test API key (zfi_test_) in production environment. This will create devnet transactions only. Use a live key (zfi_live_) for mainnet."
+      );
     }
   }
 };
@@ -230,6 +250,11 @@ var ZendFiClient = class {
   constructor(options) {
     this.config = ConfigLoader.load(options);
     ConfigLoader.validateApiKey(this.config.apiKey);
+    if (this.config.environment === "development") {
+      console.log(
+        `\u2713 ZendFi SDK initialized in ${this.config.mode} mode (${this.config.mode === "test" ? "devnet" : "mainnet"})`
+      );
+    }
   }
   /**
    * Create a new payment
@@ -323,10 +348,14 @@ var ZendFiClient = class {
     };
   }
   /**
-   * List all payment links
+   * List all payment links for the authenticated merchant
    */
   async listPaymentLinks() {
-    return [];
+    const response = await this.request("GET", "/api/v1/payment-links");
+    return response.map((link) => ({
+      ...link,
+      url: link.hosted_page_url
+    }));
   }
   /**
    * Create an installment plan
@@ -677,6 +706,7 @@ function verifyWebhookSignature(payload, signature, secret) {
 }
 
 // src/webhook-handler.ts
+var import_crypto2 = require("crypto");
 var processedWebhooks = /* @__PURE__ */ new Set();
 var defaultIsProcessed = async (webhookId) => {
   return processedWebhooks.has(webhookId);
@@ -694,16 +724,19 @@ var defaultOnProcessed = async (webhookId) => {
 function generateWebhookId(payload) {
   return `${payload.merchant_id}:${payload.event}:${payload.timestamp}`;
 }
-async function processWebhook(payload, handlers, config) {
+async function processPayload(payload, handlers, config) {
   try {
     const webhookId = generateWebhookId(payload);
-    const isProcessed = config.isProcessed || defaultIsProcessed;
-    const onProcessed = config.onProcessed || defaultOnProcessed;
-    if (await isProcessed(webhookId)) {
+    const isProcessed = config.isProcessed || config.checkDuplicate || defaultIsProcessed;
+    const onProcessed = config.onProcessed || config.markProcessed || defaultOnProcessed;
+    const dedupEnabled = !!(config.enableDeduplication || config.isProcessed || config.checkDuplicate);
+    if (dedupEnabled && await isProcessed(webhookId)) {
       return {
-        success: true,
+        success: false,
         processed: false,
-        event: payload.event
+        event: payload.event,
+        error: "Duplicate webhook",
+        statusCode: 409
       };
     }
     const handler = handlers[payload.event];
@@ -711,7 +744,8 @@ async function processWebhook(payload, handlers, config) {
       return {
         success: true,
         processed: false,
-        event: payload.event
+        event: payload.event,
+        statusCode: 200
       };
     }
     await handler(payload.data, payload);
@@ -723,14 +757,91 @@ async function processWebhook(payload, handlers, config) {
     };
   } catch (error) {
     const err = error;
-    if (config.onError) {
-      await config.onError(err, payload?.event);
+    if (config?.onError) {
+      await config.onError(err, error?.event);
+    }
+    return {
+      success: false,
+      processed: false,
+      error: err.message,
+      event: error?.event,
+      statusCode: 500
+    };
+  }
+}
+async function processWebhook(a, b, c) {
+  if (a && typeof a === "object" && a.event && b && c) {
+    return processPayload(a, b, c);
+  }
+  const opts = a;
+  if (!opts || !opts.signature && !opts.body && !opts.handlers) {
+    return {
+      success: false,
+      processed: false,
+      error: "Invalid arguments to processWebhook",
+      statusCode: 400
+    };
+  }
+  const signature = opts.signature;
+  const body = opts.body;
+  const handlers = opts.handlers || {};
+  const cfg = opts.config || {};
+  const secret = cfg.webhookSecret || cfg.secret;
+  if (!secret) {
+    return {
+      success: false,
+      processed: false,
+      error: "Webhook secret not provided",
+      statusCode: 400
+    };
+  }
+  if (!signature || !body) {
+    return {
+      success: false,
+      processed: false,
+      error: "Missing signature or body",
+      statusCode: 400
+    };
+  }
+  try {
+    const sig = typeof signature === "string" && signature.startsWith("sha256=") ? signature.slice("sha256=".length) : String(signature);
+    const hmac = (0, import_crypto2.createHmac)("sha256", secret).update(body, "utf8").digest("hex");
+    let ok = false;
+    try {
+      const sigBuf = Buffer.from(sig, "hex");
+      const hmacBuf = Buffer.from(hmac, "hex");
+      if (sigBuf.length === hmacBuf.length) {
+        ok = (0, import_crypto2.timingSafeEqual)(sigBuf, hmacBuf);
+      }
+    } catch (e) {
+      ok = (0, import_crypto2.timingSafeEqual)(Buffer.from(String(sig), "utf8"), Buffer.from(hmac, "utf8"));
     }
+    if (!ok) {
+      return {
+        success: false,
+        processed: false,
+        error: "Invalid signature",
+        statusCode: 401
+      };
+    }
+    const payload = JSON.parse(body);
+    const fullConfig = {
+      secret,
+      isProcessed: cfg.isProcessed,
+      onProcessed: cfg.onProcessed,
+      onError: cfg.onError,
+      // Forward compatibility for alternate names and flags
+      enableDeduplication: cfg.enableDeduplication,
+      checkDuplicate: cfg.checkDuplicate,
+      markProcessed: cfg.markProcessed
+    };
+    return await processPayload(payload, handlers, fullConfig);
+  } catch (err) {
     return {
       success: false,
       processed: false,
       error: err.message,
-      event: payload?.event
+      statusCode: 500
     };
   }
 }