paybridge 0.1.3 → 0.2.2

package/dist/router.d.ts

@@ -0,0 +1,33 @@
+/**
+ * PayBridgeRouter — Multi-provider routing with fallback
+ */
+import { PayBridge } from './index';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent, Provider } from './types';
+import { RoutingStrategy, FallbackConfig } from './routing-types';
+export interface PayBridgeRouterConfig {
+    providers: Array<{
+        provider: PayBridge;
+        weight?: number;
+        priority?: number;
+    }>;
+    strategy?: RoutingStrategy;
+    fallback?: FallbackConfig;
+    circuitBreakerStore?: import('./circuit-breaker-store').CircuitBreakerStore;
+}
+export declare class PayBridgeRouter {
+    private providers;
+    private strategy;
+    private fallback;
+    private circuitBreakers;
+    private rrIndex;
+    private config;
+    constructor(config: PayBridgeRouterConfig);
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string, provider?: string): Promise<PaymentResult>;
+    refund(params: RefundParams, provider?: string): Promise<RefundResult>;
+    parseWebhook(body: any, headers: any, providerName: Provider): WebhookEvent;
+    verifyWebhook(body: any, headers: any, providerName: Provider): boolean;
+    private filterProviders;
+    private sleep;
+}

package/dist/router.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * PayBridgeRouter — Multi-provider routing with fallback
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayBridgeRouter = void 0;
+const routing_types_1 = require("./routing-types");
+const strategies_1 = require("./strategies");
+const circuit_breaker_1 = require("./circuit-breaker");
+const fetch_1 = require("./utils/fetch");
+function sanitizeErrorMessage(msg) {
+    if (!msg)
+        return 'unknown error';
+    return msg
+        .replace(/\b[A-Za-z0-9_-]{32,}\b/g, '[REDACTED]')
+        .replace(/(api[_-]?key|secret|token|password)["':=\s]+\S+/gi, '$1=[REDACTED]')
+        .slice(0, 500);
+}
+class PayBridgeRouter {
+    constructor(config) {
+        this.rrIndex = 0;
+        this.config = config;
+        this.providers = config.providers.map(p => ({
+            instance: p.provider,
+            weight: p.weight,
+            priority: p.priority,
+        }));
+        this.strategy = config.strategy ?? 'cheapest';
+        this.fallback = {
+            enabled: config.fallback?.enabled ?? true,
+            maxAttempts: config.fallback?.maxAttempts ?? 3,
+            retryDelayMs: config.fallback?.retryDelayMs ?? 250,
+        };
+        this.circuitBreakers = new Map();
+        for (const p of this.providers) {
+            const name = p.instance.getProviderName();
+            this.circuitBreakers.set(name, new circuit_breaker_1.CircuitBreaker(name, {
+                store: config.circuitBreakerStore,
+            }));
+        }
+    }
+    async createPayment(params) {
+        if (!Number.isFinite(params.amount) || params.amount <= 0) {
+            throw new Error('Invalid amount: must be a positive finite number');
+        }
+        const context = {
+            amount: params.amount,
+            currency: params.currency,
+        };
+        const filtered = this.filterProviders(params.currency, params.amount);
+        if (filtered.length === 0) {
+            throw new Error(`No providers support currency ${params.currency} with amount ${params.amount}`);
+        }
+        const strategyFn = (0, strategies_1.getStrategy)(this.strategy);
+        const ordered = strategyFn(filtered, context, () => {
+            const idx = this.rrIndex;
+            this.rrIndex = (this.rrIndex + 1) % filtered.length;
+            return idx;
+        });
+        const attempts = [];
+        let lastError = null;
+        for (const providerMeta of ordered) {
+            const providerName = providerMeta.instance.getProviderName();
+            const breaker = this.circuitBreakers.get(providerName);
+            if (breaker && (await breaker.isOpen())) {
+                attempts.push({
+                    provider: providerName,
+                    status: 'skipped',
+                    errorMessage: 'Circuit breaker open',
+                    latencyMs: 0,
+                });
+                continue;
+            }
+            const startTime = Date.now();
+            try {
+                const result = await providerMeta.instance.createPayment(params);
+                const latencyMs = Date.now() - startTime;
+                if (breaker)
+                    await breaker.recordSuccess();
+                attempts.push({
+                    provider: providerName,
+                    status: 'success',
+                    latencyMs,
+                });
+                const routingMeta = {
+                    attempts,
+                    chosenProvider: providerName,
+                    strategy: this.strategy,
+                };
+                return {
+                    ...result,
+                    routingMeta,
+                };
+            }
+            catch (error) {
+                const latencyMs = Date.now() - startTime;
+                lastError = error;
+                const isRateLimited = error instanceof fetch_1.HttpError &&
+                    (error.status === 429 || (error.status === 503 && error.retryAfterMs !== undefined));
+                if (isRateLimited) {
+                    attempts.push({
+                        provider: providerName,
+                        status: 'failed',
+                        errorCode: 'RATE_LIMITED',
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        latencyMs,
+                    });
+                }
+                else {
+                    if (breaker)
+                        await breaker.recordFailure();
+                    let errorCode = error.code;
+                    if (error instanceof fetch_1.FetchTimeoutError) {
+                        errorCode = 'TIMEOUT';
+                    }
+                    attempts.push({
+                        provider: providerName,
+                        status: 'failed',
+                        errorCode,
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        latencyMs,
+                    });
+                }
+                if (!this.fallback.enabled || attempts.length >= (this.fallback.maxAttempts ?? 3)) {
+                    break;
+                }
+                await this.sleep(this.fallback.retryDelayMs ?? 250);
+            }
+        }
+        throw new routing_types_1.RoutingError(`All providers failed: ${lastError?.message || 'Unknown error'}`, attempts);
+    }
+    async createSubscription(params) {
+        const context = {
+            amount: params.amount,
+            currency: params.currency,
+        };
+        const filtered = this.filterProviders(params.currency, params.amount);
+        if (filtered.length === 0) {
+            throw new Error(`No providers support currency ${params.currency} with amount ${params.amount}`);
+        }
+        const strategyFn = (0, strategies_1.getStrategy)(this.strategy);
+        const ordered = strategyFn(filtered, context, () => {
+            const idx = this.rrIndex;
+            this.rrIndex = (this.rrIndex + 1) % filtered.length;
+            return idx;
+        });
+        const attempts = [];
+        let lastError = null;
+        for (const providerMeta of ordered) {
+            const providerName = providerMeta.instance.getProviderName();
+            const breaker = this.circuitBreakers.get(providerName);
+            if (breaker && (await breaker.isOpen())) {
+                attempts.push({
+                    provider: providerName,
+                    status: 'skipped',
+                    errorMessage: 'Circuit breaker open',
+                    latencyMs: 0,
+                });
+                continue;
+            }
+            const startTime = Date.now();
+            try {
+                const result = await providerMeta.instance.createSubscription(params);
+                const latencyMs = Date.now() - startTime;
+                if (breaker)
+                    await breaker.recordSuccess();
+                attempts.push({
+                    provider: providerName,
+                    status: 'success',
+                    latencyMs,
+                });
+                return result;
+            }
+            catch (error) {
+                const latencyMs = Date.now() - startTime;
+                lastError = error;
+                const isRateLimited = error instanceof fetch_1.HttpError &&
+                    (error.status === 429 || (error.status === 503 && error.retryAfterMs !== undefined));
+                if (isRateLimited) {
+                    attempts.push({
+                        provider: providerName,
+                        status: 'failed',
+                        errorCode: 'RATE_LIMITED',
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        latencyMs,
+                    });
+                }
+                else {
+                    if (breaker)
+                        await breaker.recordFailure();
+                    let errorCode = error.code;
+                    if (error instanceof fetch_1.FetchTimeoutError) {
+                        errorCode = 'TIMEOUT';
+                    }
+                    attempts.push({
+                        provider: providerName,
+                        status: 'failed',
+                        errorCode,
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        latencyMs,
+                    });
+                }
+                if (!this.fallback.enabled || attempts.length >= (this.fallback.maxAttempts ?? 3)) {
+                    break;
+                }
+                await this.sleep(this.fallback.retryDelayMs ?? 250);
+            }
+        }
+        throw new routing_types_1.RoutingError(`All providers failed for subscription: ${lastError?.message || 'Unknown error'}`, attempts);
+    }
+    async getPayment(id, provider) {
+        if (provider) {
+            const providerMeta = this.providers.find(p => p.instance.getProviderName() === provider);
+            if (!providerMeta) {
+                throw new Error(`Provider ${provider} not found in router`);
+            }
+            return providerMeta.instance.getPayment(id);
+        }
+        let lastError = null;
+        for (const providerMeta of this.providers) {
+            try {
+                return await providerMeta.instance.getPayment(id);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw new Error(`Payment ${id} not found in any provider: ${lastError?.message || 'Unknown error'}`);
+    }
+    async refund(params, provider) {
+        if (provider) {
+            const providerMeta = this.providers.find(p => p.instance.getProviderName() === provider);
+            if (!providerMeta) {
+                throw new Error(`Provider ${provider} not found in router`);
+            }
+            return providerMeta.instance.refund(params);
+        }
+        let lastError = null;
+        for (const providerMeta of this.providers) {
+            try {
+                return await providerMeta.instance.refund(params);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw new Error(`Refund for payment ${params.paymentId} failed on all providers: ${lastError?.message || 'Unknown error'}`);
+    }
+    parseWebhook(body, headers, providerName) {
+        const providerMeta = this.providers.find(p => p.instance.getProviderName() === providerName);
+        if (!providerMeta) {
+            throw new Error(`Unknown provider for webhook: ${providerName}`);
+        }
+        return providerMeta.instance.parseWebhook(body, headers);
+    }
+    verifyWebhook(body, headers, providerName) {
+        const providerMeta = this.providers.find(p => p.instance.getProviderName() === providerName);
+        if (!providerMeta) {
+            throw new Error(`Unknown provider for webhook: ${providerName}`);
+        }
+        return providerMeta.instance.verifyWebhook(body, headers);
+    }
+    filterProviders(currency, amount) {
+        return this.providers.filter(p => {
+            const caps = p.instance.provider.getCapabilities();
+            if (!caps.currencies.includes(currency)) {
+                return false;
+            }
+            if (caps.minAmount !== undefined && amount < caps.minAmount) {
+                return false;
+            }
+            if (caps.maxAmount !== undefined && amount > caps.maxAmount) {
+                return false;
+            }
+            return true;
+        });
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.PayBridgeRouter = PayBridgeRouter;

package/dist/routing-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Types for payment routing
+ */
+import { Currency } from './types';
+export interface ProviderFees {
+    fixed: number;
+    percent: number;
+    currency: Currency;
+}
+export interface ProviderCapabilities {
+    fees: ProviderFees;
+    currencies: string[];
+    minAmount?: number;
+    maxAmount?: number;
+    avgLatencyMs?: number;
+    country: string;
+}
+export interface RoutingAttempt {
+    provider: string;
+    status: 'success' | 'failed' | 'skipped';
+    errorCode?: string;
+    errorMessage?: string;
+    latencyMs: number;
+}
+export interface RoutingMeta {
+    attempts: RoutingAttempt[];
+    chosenProvider: string;
+    strategy: RoutingStrategy;
+}
+export type RoutingStrategy = 'cheapest' | 'fastest' | 'priority' | 'round-robin';
+export interface FallbackConfig {
+    enabled: boolean;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+}
+export declare class RoutingError extends Error {
+    readonly attempts: RoutingAttempt[];
+    constructor(message: string, attempts: RoutingAttempt[]);
+}

package/dist/routing-types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Types for payment routing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoutingError = void 0;
+class RoutingError extends Error {
+    constructor(message, attempts) {
+        super(message);
+        this.name = 'RoutingError';
+        this.attempts = attempts;
+    }
+}
+exports.RoutingError = RoutingError;

package/dist/stores/redis.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Redis-backed circuit breaker store adapter
+ */
+import { CircuitBreakerStore } from '../circuit-breaker-store';
+/**
+ * Duck-typed Redis client interface.
+ * Compatible with both ioredis and node-redis v4+.
+ */
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    del(key: string): Promise<any>;
+}
+export interface RedisStoreOptions {
+    prefix?: string;
+}
+/**
+ * Create a Redis-backed circuit breaker store.
+ * Works with ioredis and node-redis v4+ (duck-types get/set/del).
+ *
+ * @example
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { createRedisCircuitBreakerStore } from 'paybridge';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = createRedisCircuitBreakerStore(redis, { prefix: 'app:cb:' });
+ * ```
+ */
+export declare function createRedisCircuitBreakerStore(client: RedisLike, options?: RedisStoreOptions): CircuitBreakerStore;

package/dist/stores/redis.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Redis-backed circuit breaker store adapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedisCircuitBreakerStore = createRedisCircuitBreakerStore;
+/**
+ * Create a Redis-backed circuit breaker store.
+ * Works with ioredis and node-redis v4+ (duck-types get/set/del).
+ *
+ * @example
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { createRedisCircuitBreakerStore } from 'paybridge';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = createRedisCircuitBreakerStore(redis, { prefix: 'app:cb:' });
+ * ```
+ */
+function createRedisCircuitBreakerStore(client, options = {}) {
+    const prefix = options.prefix ?? 'paybridge:cb:';
+    return {
+        async get(key) {
+            const raw = await client.get(prefix + key);
+            if (!raw)
+                return null;
+            return JSON.parse(raw);
+        },
+        async set(key, snapshot, ttlMs) {
+            const value = JSON.stringify(snapshot);
+            if (ttlMs !== undefined) {
+                await client.set(prefix + key, value, 'PX', ttlMs);
+            }
+            else {
+                await client.set(prefix + key, value);
+            }
+        },
+        async delete(key) {
+            await client.del(prefix + key);
+        },
+    };
+}

package/dist/strategies.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Routing strategies for multi-provider payments
+ */
+import { PayBridge } from './index';
+import { Currency } from './types';
+import { RoutingStrategy } from './routing-types';
+export interface ProviderWithMeta {
+    instance: PayBridge;
+    weight?: number;
+    priority?: number;
+}
+export interface StrategyContext {
+    amount: number;
+    currency: Currency;
+}
+export type Strategy = (providers: ProviderWithMeta[], context: StrategyContext, getRRIndex?: () => number) => ProviderWithMeta[];
+export declare const strategies: Record<RoutingStrategy, Strategy>;
+export declare function getStrategy(name: RoutingStrategy): Strategy;

package/dist/strategies.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Routing strategies for multi-provider payments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.strategies = void 0;
+exports.getStrategy = getStrategy;
+exports.strategies = {
+    cheapest: (providers, context) => {
+        return [...providers].sort((a, b) => {
+            const capsA = a.instance.provider.getCapabilities();
+            const capsB = b.instance.provider.getCapabilities();
+            const feeA = capsA.fees.fixed + (context.amount * capsA.fees.percent) / 100;
+            const feeB = capsB.fees.fixed + (context.amount * capsB.fees.percent) / 100;
+            return feeA - feeB;
+        });
+    },
+    fastest: (providers, _context) => {
+        return [...providers].sort((a, b) => {
+            const capsA = a.instance.provider.getCapabilities();
+            const capsB = b.instance.provider.getCapabilities();
+            const latencyA = capsA.avgLatencyMs ?? 1000;
+            const latencyB = capsB.avgLatencyMs ?? 1000;
+            return latencyA - latencyB;
+        });
+    },
+    priority: (providers, _context) => {
+        return [...providers].sort((a, b) => {
+            const priorityA = a.priority ?? 0;
+            const priorityB = b.priority ?? 0;
+            return priorityB - priorityA;
+        });
+    },
+    'round-robin': (providers, _context, getRRIndex) => {
+        if (!getRRIndex) {
+            return providers;
+        }
+        const idx = getRRIndex();
+        return [...providers.slice(idx), ...providers.slice(0, idx)];
+    },
+};
+function getStrategy(name) {
+    return exports.strategies[name];
+}

package/dist/types.d.ts

@@ -1,10 +1,10 @@
 /**
  * PayBridge — Unified payment SDK types
  */
-export type Provider = 'softycomp' | 'yoco' | 'ozow' | 'payfast' | 'paystack' | 'stripe' | 'peach';
+export type Provider = 'softycomp' | 'yoco' | 'ozow' | 'payfast' | 'paystack' | 'stripe' | 'peach' | 'flutterwave';
 export type PaymentStatus = 'pending' | 'completed' | 'failed' | 'cancelled' | 'refunded';
 export type SubscriptionInterval = 'weekly' | 'monthly' | 'yearly';
-export type Currency = 'ZAR' | 'USD' | 'EUR' | 'GBP' | 'NGN';
+export type Currency = 'ZAR' | 'USD' | 'EUR' | 'GBP' | 'NGN' | 'KES' | 'UGX' | 'GHS' | string;
 export type WebhookEventType = 'payment.pending' | 'payment.completed' | 'payment.failed' | 'payment.cancelled' | 'subscription.created' | 'subscription.cancelled' | 'refund.completed';
 export interface PayBridgeConfig {
     /** Payment provider to use */
@@ -77,6 +77,8 @@ export interface PaymentResult {
     expiresAt?: string;
     /** Raw provider response */
     raw?: any;
+    /** Routing metadata (populated by PayBridgeRouter) */
+    routingMeta?: import('./routing-types').RoutingMeta;
 }
 export interface CreateSubscriptionParams {
     /** Amount in major currency unit (e.g. 299.00 for R299) */

package/dist/utils/fetch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Fetch utilities with timeout and HTTP error handling
+ */
+export interface FetchOptions extends RequestInit {
+    timeoutMs?: number;
+}
+export declare class FetchTimeoutError extends Error {
+    readonly name = "FetchTimeoutError";
+    readonly url: string;
+    readonly timeoutMs: number;
+    constructor(url: string, timeoutMs: number);
+}
+export declare class HttpError extends Error {
+    readonly name = "HttpError";
+    readonly status: number;
+    readonly retryAfterMs?: number;
+    readonly body?: string;
+    constructor(status: number, message: string, opts?: {
+        retryAfterMs?: number;
+        body?: string;
+    });
+}
+export declare function timedFetch(url: string, opts?: FetchOptions): Promise<Response>;
+export declare function timedFetchOrThrow(url: string, opts?: FetchOptions): Promise<Response>;

package/dist/utils/fetch.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Fetch utilities with timeout and HTTP error handling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = exports.FetchTimeoutError = void 0;
+exports.timedFetch = timedFetch;
+exports.timedFetchOrThrow = timedFetchOrThrow;
+class FetchTimeoutError extends Error {
+    constructor(url, timeoutMs) {
+        super(`Request to ${url} timed out after ${timeoutMs}ms`);
+        this.name = 'FetchTimeoutError';
+        this.url = url;
+        this.timeoutMs = timeoutMs;
+    }
+}
+exports.FetchTimeoutError = FetchTimeoutError;
+class HttpError extends Error {
+    constructor(status, message, opts = {}) {
+        super(message);
+        this.name = 'HttpError';
+        this.status = status;
+        this.retryAfterMs = opts.retryAfterMs;
+        this.body = opts.body;
+    }
+}
+exports.HttpError = HttpError;
+const DEFAULT_TIMEOUT_MS = 30000;
+async function timedFetch(url, opts = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: callerSignal, ...rest } = opts;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    if (callerSignal) {
+        if (callerSignal.aborted)
+            controller.abort();
+        else
+            callerSignal.addEventListener('abort', () => controller.abort(), { once: true });
+    }
+    try {
+        return await fetch(url, { ...rest, signal: controller.signal });
+    }
+    catch (err) {
+        if (err?.name === 'AbortError') {
+            throw new FetchTimeoutError(url, timeoutMs);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+async function timedFetchOrThrow(url, opts = {}) {
+    const response = await timedFetch(url, opts);
+    if (!response.ok) {
+        let body = '';
+        try {
+            body = await response.text();
+        }
+        catch { }
+        const retryAfterHeader = response.headers.get('retry-after');
+        const retryAfterMs = retryAfterHeader ? parseRetryAfter(retryAfterHeader) : undefined;
+        throw new HttpError(response.status, `HTTP ${response.status}: ${body.slice(0, 200) || response.statusText}`, { retryAfterMs, body });
+    }
+    return response;
+}
+function parseRetryAfter(value) {
+    const seconds = parseInt(value, 10);
+    if (!isNaN(seconds))
+        return seconds * 1000;
+    const dateMs = Date.parse(value);
+    if (!isNaN(dateMs))
+        return Math.max(0, dateMs - Date.now());
+    return undefined;
+}

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "paybridge",
-  "version": "0.1.3",
-  "description": "One API, every payment provider. Unified payment SDK for Node.js — SoftyComp, Yoco, Ozow, and more.",
+  "version": "0.2.2",
+  "description": "One API for fiat + crypto payments. Multi-provider routing, automatic failover, MoonPay on/off-ramp. SA-first, global-ready.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "tsc && tsc --project tsconfig.test.json && node --test 'dist-test/**/*.test.js'",
+    "test:e2e:moonpay": "tsx tests/e2e/moonpay-sandbox.ts",
+    "test:e2e:yellowcard": "tsx tests/e2e/yellowcard-sandbox.ts"
   },
   "keywords": [
     "payments",