@zendfi/sdk 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,611 @@
+/**
+ * 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;
+    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 SDK Client
+ * Zero-config TypeScript SDK for crypto payments
+ */
+declare class ZendFiClient {
+    private config;
+    constructor(options?: Partial<ZendFiConfig>);
+    /**
+     * Create a new payment
+     */
+    createPayment(request: CreatePaymentRequest): Promise<Payment>;
+    /**
+     * Get payment by ID
+     */
+    getPayment(paymentId: string): Promise<Payment>;
+    /**
+     * List all payments with pagination
+     */
+    listPayments(request?: ListPaymentsRequest): Promise<PaginatedResponse<Payment>>;
+    /**
+     * Create a subscription plan
+     */
+    createSubscriptionPlan(request: CreateSubscriptionPlanRequest): Promise<SubscriptionPlan>;
+    /**
+     * Get subscription plan by ID
+     */
+    getSubscriptionPlan(planId: string): Promise<SubscriptionPlan>;
+    /**
+     * Create a subscription
+     */
+    createSubscription(request: CreateSubscriptionRequest): Promise<Subscription>;
+    /**
+     * Get subscription by ID
+     */
+    getSubscription(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Cancel a subscription
+     */
+    cancelSubscription(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Create a payment link (shareable checkout URL)
+     */
+    createPaymentLink(request: CreatePaymentLinkRequest): Promise<PaymentLink>;
+    /**
+     * Get payment link by link code
+     */
+    getPaymentLink(linkCode: string): Promise<PaymentLink>;
+    /**
+     * List all payment links
+     */
+    listPaymentLinks(): Promise<PaymentLink[]>;
+    /**
+     * Create an installment plan
+     * Split a purchase into multiple scheduled payments
+     */
+    createInstallmentPlan(request: CreateInstallmentPlanRequest): Promise<InstallmentPlan>;
+    /**
+     * Get installment plan by ID
+     */
+    getInstallmentPlan(planId: string): Promise<InstallmentPlan>;
+    /**
+     * List all installment plans for merchant
+     */
+    listInstallmentPlans(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<InstallmentPlan[]>;
+    /**
+     * List installment plans for a specific customer
+     */
+    listCustomerInstallmentPlans(customerWallet: string): Promise<InstallmentPlan[]>;
+    /**
+     * Cancel an installment plan
+     */
+    cancelInstallmentPlan(planId: string): Promise<{
+        message: string;
+        plan_id: string;
+    }>;
+    /**
+     * Create an escrow transaction
+     * Hold funds until conditions are met
+     */
+    createEscrow(request: CreateEscrowRequest): Promise<Escrow>;
+    /**
+     * Get escrow by ID
+     */
+    getEscrow(escrowId: string): Promise<Escrow>;
+    /**
+     * List all escrows for merchant
+     */
+    listEscrows(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Escrow[]>;
+    /**
+     * Approve escrow release to seller
+     */
+    approveEscrow(escrowId: string, request: ApproveEscrowRequest): Promise<{
+        status: string;
+        transaction_signature?: string;
+        message: string;
+    }>;
+    /**
+     * Refund escrow to buyer
+     */
+    refundEscrow(escrowId: string, request: RefundEscrowRequest): Promise<{
+        status: string;
+        transaction_signature: string;
+        message: string;
+        reason: string;
+    }>;
+    /**
+     * Raise a dispute for an escrow
+     */
+    disputeEscrow(escrowId: string, request: DisputeEscrowRequest): Promise<{
+        status: string;
+        message: string;
+        dispute_id: string;
+        created_at: string;
+    }>;
+    /**
+     * Create an invoice
+     */
+    createInvoice(request: CreateInvoiceRequest): Promise<Invoice>;
+    /**
+     * Get invoice by ID
+     */
+    getInvoice(invoiceId: string): Promise<Invoice>;
+    /**
+     * List all invoices for merchant
+     */
+    listInvoices(): Promise<Invoice[]>;
+    /**
+     * Send invoice to customer via email
+     */
+    sendInvoice(invoiceId: string): Promise<{
+        success: boolean;
+        invoice_id: string;
+        invoice_number: string;
+        sent_to: string;
+        payment_url: string;
+        status: string;
+    }>;
+    /**
+     * Verify webhook signature using HMAC-SHA256
+     *
+     * @param request - Webhook verification request containing payload, signature, and secret
+     * @returns true if signature is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isValid = zendfi.verifyWebhook({
+     *   payload: req.body,
+     *   signature: req.headers['x-zendfi-signature'],
+     *   secret: process.env.ZENDFI_WEBHOOK_SECRET
+     * });
+     *
+     * if (!isValid) {
+     *   return res.status(401).json({ error: 'Invalid signature' });
+     * }
+     * ```
+     */
+    verifyWebhook(request: VerifyWebhookRequest): boolean;
+    /**
+     * Compute HMAC-SHA256 signature
+     * Works in both Node.js and browser environments
+     */
+    private computeHmacSignature;
+    /**
+     * Timing-safe string comparison to prevent timing attacks
+     */
+    private timingSafeEqual;
+    /**
+     * Make an HTTP request with retry logic
+     */
+    private request;
+}
+/**
+ * Default singleton instance
+ * Auto-configured from environment
+ *
+ * Note: This will throw if ZENDFI_API_KEY is not set.
+ * For custom configuration, create your own instance:
+ * const client = new ZendFiClient({ apiKey: '...' })
+ */
+declare const zendfi: ZendFiClient;
+
+/**
+ * Configuration loader and environment detector
+ */
+declare class ConfigLoader {
+    /**
+     * Load configuration from various sources
+     */
+    static load(options?: Partial<ZendFiConfig>): Required<ZendFiConfig>;
+    /**
+     * Detect environment based on various signals
+     */
+    private static detectEnvironment;
+    /**
+     * Load API key from various sources
+     */
+    private static loadApiKey;
+    /**
+     * Get base URL for API
+     */
+    private static getBaseURL;
+    /**
+     * Load credentials from CLI config file (~/.zendfi/credentials.json)
+     */
+    private static loadCLICredentials;
+    /**
+     * Validate API key format
+     */
+    static validateApiKey(apiKey: string): void;
+}
+
+/**
+ * Webhook Verification Helpers
+ * Convenience functions for common frameworks
+ */
+
+/**
+ * Verify and parse webhook for Next.js API routes
+ *
+ * @example
+ * ```typescript
+ * // app/api/webhooks/zendfi/route.ts
+ * import { verifyNextWebhook } from '@zendfi/sdk/webhooks';
+ *
+ * export async function POST(request: Request) {
+ *   const webhook = await verifyNextWebhook(request);
+ *
+ *   if (!webhook) {
+ *     return new Response('Invalid signature', { status: 401 });
+ *   }
+ *
+ *   // Process webhook
+ *   switch (webhook.event) {
+ *     case 'payment.confirmed':
+ *       // Handle payment
+ *       break;
+ *   }
+ *
+ *   return new Response('OK');
+ * }
+ * ```
+ */
+declare function verifyNextWebhook(request: Request, secret?: string): Promise<WebhookPayload | null>;
+/**
+ * Verify and parse webhook for Express.js
+ *
+ * @example
+ * ```typescript
+ * import { verifyExpressWebhook } from '@zendfi/sdk/webhooks';
+ *
+ * app.post('/webhooks/zendfi', async (req, res) => {
+ *   const webhook = await verifyExpressWebhook(req);
+ *
+ *   if (!webhook) {
+ *     return res.status(401).json({ error: 'Invalid signature' });
+ *   }
+ *
+ *   // Process webhook
+ *   console.log('Event:', webhook.event);
+ *
+ *   res.json({ received: true });
+ * });
+ * ```
+ */
+declare function verifyExpressWebhook(request: any, secret?: string): Promise<WebhookPayload | null>;
+/**
+ * Verify webhook signature manually
+ * Use this for custom integrations
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@zendfi/sdk/webhooks';
+ *
+ * const isValid = verifyWebhookSignature(
+ *   payloadString,
+ *   signatureHeader,
+ *   process.env.ZENDFI_WEBHOOK_SECRET
+ * );
+ * ```
+ */
+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 };