@boostengine/payments 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,339 @@
+type GatewayName = 'razorpay' | 'cashfree' | 'phonepe' | 'paytm' | 'stripe' | 'cod';
+interface UnifiedCustomer {
+    id?: string;
+    name: string;
+    email: string;
+    phone: string;
+}
+interface UnifiedOrderItem {
+    name: string;
+    quantity: number;
+    price: number;
+    sku?: string;
+}
+interface UnifiedCreateOrderOptions {
+    /** Amount in standard currency units (e.g. 1499.00 for INR, 25.00 for USD) */
+    amount: number;
+    /** 3-letter ISO currency code (e.g. 'INR', 'USD', 'EUR') */
+    currency: string;
+    /** Merchant order or receipt reference ID */
+    receipt: string;
+    /** Customer details */
+    customer: UnifiedCustomer;
+    /** Line items */
+    items?: UnifiedOrderItem[];
+    /** Merchant notes/metadata */
+    notes?: Record<string, any>;
+    /** Customer return/redirect URL after payment */
+    redirectUrl?: string;
+    /** Server-to-server webhook callback URL */
+    callbackUrl?: string;
+    /** Explicitly override gateway for this transaction */
+    gateway?: GatewayName;
+}
+interface UnifiedOrderResult {
+    gateway: GatewayName;
+    orderId: string;
+    gatewayOrderId: string;
+    amount: number;
+    currency: string;
+    status: 'CREATED' | 'PENDING' | 'PAID' | 'FAILED';
+    /** Cashfree payment_session_id for Drop-in UI or SDK */
+    paymentSessionId?: string;
+    /** Redirect or hosted pay URL (PhonePe, Stripe, Cashfree) */
+    redirectUrl?: string;
+    /** Paytm checkout txnToken */
+    txnToken?: string;
+    /** Raw response object from gateway */
+    rawResponse: any;
+}
+interface UnifiedPaymentVerificationOptions {
+    gateway: GatewayName;
+    orderId: string;
+    paymentId?: string;
+    signature?: string;
+    rawPayload?: any;
+}
+interface UnifiedPaymentVerificationResult {
+    gateway: GatewayName;
+    isSuccessful: boolean;
+    paymentId: string;
+    orderId: string;
+    amount: number;
+    currency: string;
+    paymentMethod?: string;
+    rawResponse: any;
+}
+interface UnifiedRefundOptions {
+    gateway: GatewayName;
+    paymentId: string;
+    orderId?: string;
+    /** Partial or full refund amount in currency units */
+    amount?: number;
+    reason?: string;
+}
+interface UnifiedRefundResult {
+    gateway: GatewayName;
+    refundId: string;
+    paymentId: string;
+    amount: number;
+    status: 'SUCCESS' | 'PENDING' | 'FAILED';
+    rawResponse: any;
+}
+interface WebhookVerificationOptions {
+    gateway: GatewayName;
+    rawBody: string | Buffer;
+    headers: Record<string, string | string[] | undefined>;
+    webhookSecret?: string;
+}
+interface WebhookVerificationResult {
+    isValid: boolean;
+    event?: string;
+    gateway: GatewayName;
+    data?: any;
+    error?: string;
+}
+interface RazorpayConfig {
+    keyId: string;
+    keySecret: string;
+    webhookSecret?: string;
+}
+interface CashfreeConfig {
+    appId: string;
+    secretKey: string;
+    env?: 'SANDBOX' | 'PRODUCTION';
+    apiVersion?: string;
+}
+interface PhonePeConfig {
+    merchantId: string;
+    saltKey: string;
+    saltIndex?: string;
+    env?: 'UAT' | 'PRODUCTION';
+}
+interface PaytmConfig {
+    mid: string;
+    merchantKey: string;
+    website?: string;
+    env?: 'STAGE' | 'PRODUCTION';
+}
+interface StripeConfig {
+    secretKey: string;
+    webhookSecret?: string;
+}
+interface CODConfig {
+    minOrderValue?: number;
+    maxOrderValue?: number;
+    extraFee?: number;
+    allowedPincodes?: string[];
+}
+interface GatewayConfigs {
+    razorpay?: RazorpayConfig;
+    cashfree?: CashfreeConfig;
+    phonepe?: PhonePeConfig;
+    paytm?: PaytmConfig;
+    stripe?: StripeConfig;
+    cod?: CODConfig;
+}
+interface SmartRoutingConfig {
+    /** Map currency to default gateway, e.g. { 'USD': 'stripe', 'INR': 'cashfree' } */
+    currencyMap?: Record<string, GatewayName>;
+    /** Automatic fallback order if primary gateway fails, e.g. ['razorpay', 'cashfree', 'phonepe'] */
+    fallbackChain?: GatewayName[];
+}
+interface PaymentManagerOptions {
+    defaultGateway?: GatewayName;
+    gateways: GatewayConfigs;
+    smartRouting?: SmartRoutingConfig;
+}
+
+declare abstract class BasePaymentAdapter {
+    abstract readonly name: GatewayName;
+    /**
+     * Create an order or payment session on the gateway.
+     */
+    abstract createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    /**
+     * Verify checkout completion signature or status query.
+     */
+    abstract verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    /**
+     * Initiate a refund back to the customer.
+     */
+    abstract refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    /**
+     * Verify server-to-server webhook authenticity and parse payload.
+     */
+    abstract verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+    /**
+     * Safe helper to extract single string header value from request headers.
+     */
+    protected getHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+    /**
+     * Helper to perform HTTP JSON requests with standard error extraction.
+     */
+    protected fetchJson<T = any>(url: string, options?: {
+        method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+        headers?: Record<string, string>;
+        body?: any;
+    }): Promise<T>;
+}
+
+declare class PaymentManager {
+    private readonly adapters;
+    private readonly defaultGateway?;
+    private readonly smartRouting?;
+    constructor(options: PaymentManagerOptions);
+    /**
+     * Returns an active adapter instance by gateway name.
+     */
+    getAdapter(gateway: GatewayName): BasePaymentAdapter;
+    /**
+     * Lists all currently registered gateway names.
+     */
+    listConfiguredGateways(): GatewayName[];
+    /**
+     * Resolves the optimal gateway based on currency rules, explicit override, or default.
+     */
+    resolveGateway(options: {
+        gateway?: GatewayName;
+        currency?: string;
+    }): GatewayName;
+    /**
+     * Create an order using the chosen or automatically resolved gateway.
+     */
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    /**
+     * Smart Fallback: Attempts creation on primary gateway. If it throws an error or fails,
+     * it automatically routes through fallback gateways in sequence!
+     */
+    createOrderWithFallback(options: UnifiedCreateOrderOptions & {
+        fallbackChain?: GatewayName[];
+    }): Promise<UnifiedOrderResult>;
+    /**
+     * Verifies payment completion signature or status query.
+     */
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    /**
+     * Initiates a customer refund.
+     */
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    /**
+     * Verifies incoming webhook authenticity and decodes payload.
+     */
+    verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+/**
+ * Factory function to instantiate a PaymentManager.
+ */
+declare function createPaymentManager(options: PaymentManagerOptions): PaymentManager;
+
+/**
+ * Computes HMAC-SHA256 hex digest.
+ */
+declare function hmacSha256(data: string | Buffer, secret: string): string;
+/**
+ * Computes standard SHA-256 hex digest.
+ */
+declare function sha256(data: string | Buffer): string;
+/**
+ * Encodes string into Base64.
+ */
+declare function base64Encode(data: string | object): string;
+/**
+ * Decodes Base64 into utf-8 string.
+ */
+declare function base64Decode(encoded: string): string;
+/**
+ * Constant-time safe string comparison to prevent timing attacks on signatures.
+ */
+declare function safeCompare(a: string, b: string): boolean;
+
+declare class PaymentError extends Error {
+    readonly gateway?: GatewayName;
+    readonly statusCode?: number;
+    readonly rawError?: any;
+    constructor(message: string, options?: {
+        gateway?: GatewayName;
+        statusCode?: number;
+        rawError?: any;
+    });
+}
+declare class GatewayNotConfiguredError extends PaymentError {
+    constructor(gateway: GatewayName);
+}
+declare class SignatureVerificationError extends PaymentError {
+    constructor(gateway: GatewayName, details?: string);
+}
+
+declare class RazorpayAdapter extends BasePaymentAdapter {
+    private readonly config;
+    readonly name: GatewayName;
+    private readonly baseUrl;
+    constructor(config: RazorpayConfig);
+    private getAuthHeader;
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+
+declare class CashfreeAdapter extends BasePaymentAdapter {
+    private readonly config;
+    readonly name: GatewayName;
+    private readonly baseUrl;
+    private readonly apiVersion;
+    constructor(config: CashfreeConfig);
+    private getHeaders;
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+
+declare class PhonePeAdapter extends BasePaymentAdapter {
+    private readonly config;
+    readonly name: GatewayName;
+    private readonly baseUrl;
+    private readonly saltIndex;
+    constructor(config: PhonePeConfig);
+    private calculateXVerify;
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+
+declare class PaytmAdapter extends BasePaymentAdapter {
+    private readonly config;
+    readonly name: GatewayName;
+    private readonly baseUrl;
+    constructor(config: PaytmConfig);
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+
+declare class StripeAdapter extends BasePaymentAdapter {
+    private readonly config;
+    readonly name: GatewayName;
+    private readonly baseUrl;
+    constructor(config: StripeConfig);
+    private getAuthHeader;
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    verifyWebhook(options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+
+declare class CODAdapter extends BasePaymentAdapter {
+    private readonly config;
+    readonly name: GatewayName;
+    constructor(config?: CODConfig);
+    createOrder(options: UnifiedCreateOrderOptions): Promise<UnifiedOrderResult>;
+    verifyPayment(options: UnifiedPaymentVerificationOptions): Promise<UnifiedPaymentVerificationResult>;
+    refund(options: UnifiedRefundOptions): Promise<UnifiedRefundResult>;
+    verifyWebhook(_options: WebhookVerificationOptions): Promise<WebhookVerificationResult>;
+}
+
+export { BasePaymentAdapter, CODAdapter, type CODConfig, CashfreeAdapter, type CashfreeConfig, type GatewayConfigs, type GatewayName, GatewayNotConfiguredError, PaymentError, PaymentManager, type PaymentManagerOptions, PaytmAdapter, type PaytmConfig, PhonePeAdapter, type PhonePeConfig, RazorpayAdapter, type RazorpayConfig, SignatureVerificationError, type SmartRoutingConfig, StripeAdapter, type StripeConfig, type UnifiedCreateOrderOptions, type UnifiedCustomer, type UnifiedOrderItem, type UnifiedOrderResult, type UnifiedPaymentVerificationOptions, type UnifiedPaymentVerificationResult, type UnifiedRefundOptions, type UnifiedRefundResult, type WebhookVerificationOptions, type WebhookVerificationResult, base64Decode, base64Encode, createPaymentManager, hmacSha256, safeCompare, sha256 };