@zendfi/sdk 0.1.1 → 0.2.0

package/dist/webhook-handler-BIze3Qop.d.ts

@@ -0,0 +1,388 @@
+/**
+ * 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 {
+    link_code: string;
+    merchant_id: string;
+    title?: string;
+    description?: string;
+    amount: number;
+    currency: string;
+    payment_methods?: string[];
+    redirect_url?: string;
+    expires_at?: string;
+    metadata?: Record<string, any>;
+    payment_url: string;
+    hosted_page_url: string;
+    created_at: string;
+    updated_at: string;
+    url: string;
+    id?: string;
+    token?: string;
+    max_uses?: number;
+    uses_count?: number;
+    is_active?: boolean;
+}
+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;
+}
+
+/**
+ * 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;
+    statusCode?: number;
+}
+declare function processWebhook(a: any, b?: any, c?: any): Promise<WebhookResult>;
+
+export { type ApproveEscrowRequest as A, ZendFiError as B, type CreatePaymentRequest as C, type DisputeEscrowRequest as D, type Escrow as E, AuthenticationError as F, ValidationError as G, RateLimitError as H, type InstallmentPlan as I, type InstallmentScheduleItem as J, type CreateInstallmentPlanResponse as K, type ListPaymentsRequest as L, type ReleaseCondition as M, NetworkError as N, type InvoiceLineItem as O, 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 Currency as q, type PaymentToken as r, type PaymentStatus as s, type SubscriptionStatus as t, type InstallmentPlanStatus as u, type EscrowStatus as v, type InvoiceStatus as w, type SplitStatus as x, type WebhookEvent as y, type SplitRecipient as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendfi/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Zero-config TypeScript SDK for ZendFi crypto payments",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -8,16 +8,23 @@
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
+    },
+    "./nextjs": {
+      "import": "./dist/nextjs.mjs",
+      "require": "./dist/nextjs.js"
+    },
+    "./express": {
+      "import": "./dist/express.mjs",
+      "require": "./dist/express.js"
     }
   },
   "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",