paybridge 0.1.2 → 0.2.1

package/dist/crypto/yellowcard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Yellow Card crypto on/off-ramp provider
+ * @see https://yellowcard.io
+ *
+ * WARNING: This implementation is NOT verified against official Yellow Card API documentation.
+ * No public documentation, SDK, or API reference could be found (checked 2026-05-03).
+ * All signing logic, header names, and endpoints are SPECULATIVE based on common patterns.
+ *
+ * Known gaps requiring verification:
+ * - Base URLs (sandbox.api.yellowcard.io / api.yellowcard.io)
+ * - Endpoint paths (/v1/quotes/buy, /v1/orders/buy, /v1/orders/sell)
+ * - Header names (X-API-Key, X-Timestamp, X-Signature)
+ * - Signature algorithm (HMAC-SHA256 of method+path+timestamp+body, hex-encoded)
+ * - Webhook signature scheme and header name
+ *
+ * To verify: Contact Yellow Card for partner API documentation or request sandbox credentials
+ * to test against their actual endpoints.
+ */
+import { CryptoRampProvider } from './base';
+import { OnRampParams, OffRampParams, RampQuote, RampResult, CryptoRampCapabilities } from './types';
+interface YellowCardConfig {
+    apiKey: string;
+    secretKey: string;
+    sandbox: boolean;
+    webhookSecret?: string;
+}
+/**
+ * Yellow Card crypto on/off-ramp provider.
+ *
+ * @experimental Yellow Card public API documentation could not be located. Endpoint paths,
+ *   header names, signature algorithm, and webhook scheme are all speculative — based on
+ *   common patterns, not verified against an official spec or SDK. Will not work against
+ *   real Yellow Card sandbox without spec confirmation. Use only with partner-provided
+ *   integration docs.
+ */
+export declare class YellowCardProvider extends CryptoRampProvider {
+    readonly name = "yellowcard";
+    private apiKey;
+    private secretKey;
+    private sandbox;
+    private baseUrl;
+    private webhookSecret?;
+    private static warnedExperimental;
+    constructor(config: YellowCardConfig);
+    getQuote(direction: 'on' | 'off', fiatAmount: number, fiatCurrency: string, cryptoAsset: string, network: string): Promise<RampQuote>;
+    createOnRamp(params: OnRampParams): Promise<RampResult>;
+    createOffRamp(params: OffRampParams): Promise<RampResult>;
+    getRamp(id: string): Promise<RampResult>;
+    parseWebhook(body: any, _headers?: any): any;
+    verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    getCapabilities(): CryptoRampCapabilities;
+    private apiRequest;
+    private generateSignature;
+    private mapYellowCardStatus;
+}
+export {};

package/dist/crypto/yellowcard.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Yellow Card crypto on/off-ramp provider
+ * @see https://yellowcard.io
+ *
+ * WARNING: This implementation is NOT verified against official Yellow Card API documentation.
+ * No public documentation, SDK, or API reference could be found (checked 2026-05-03).
+ * All signing logic, header names, and endpoints are SPECULATIVE based on common patterns.
+ *
+ * Known gaps requiring verification:
+ * - Base URLs (sandbox.api.yellowcard.io / api.yellowcard.io)
+ * - Endpoint paths (/v1/quotes/buy, /v1/orders/buy, /v1/orders/sell)
+ * - Header names (X-API-Key, X-Timestamp, X-Signature)
+ * - Signature algorithm (HMAC-SHA256 of method+path+timestamp+body, hex-encoded)
+ * - Webhook signature scheme and header name
+ *
+ * To verify: Contact Yellow Card for partner API documentation or request sandbox credentials
+ * to test against their actual endpoints.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YellowCardProvider = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const base_1 = require("./base");
+/**
+ * Yellow Card crypto on/off-ramp provider.
+ *
+ * @experimental Yellow Card public API documentation could not be located. Endpoint paths,
+ *   header names, signature algorithm, and webhook scheme are all speculative — based on
+ *   common patterns, not verified against an official spec or SDK. Will not work against
+ *   real Yellow Card sandbox without spec confirmation. Use only with partner-provided
+ *   integration docs.
+ */
+class YellowCardProvider extends base_1.CryptoRampProvider {
+    constructor(config) {
+        super();
+        this.name = 'yellowcard';
+        this.apiKey = config.apiKey;
+        this.secretKey = config.secretKey;
+        this.sandbox = config.sandbox;
+        this.webhookSecret = config.webhookSecret;
+        this.baseUrl = this.sandbox
+            ? 'https://sandbox.api.yellowcard.io'
+            : 'https://api.yellowcard.io';
+        if (!YellowCardProvider.warnedExperimental) {
+            console.warn('[paybridge] YellowCardProvider is experimental — see @experimental notes in source. Do not use in production without verifying spec against partner docs.');
+            YellowCardProvider.warnedExperimental = true;
+        }
+    }
+    async getQuote(direction, fiatAmount, fiatCurrency, cryptoAsset, network) {
+        const endpoint = direction === 'on' ? '/v1/quotes/buy' : '/v1/quotes/sell';
+        const requestBody = {
+            fiatCurrency: fiatCurrency.toUpperCase(),
+            cryptoCurrency: cryptoAsset.toUpperCase(),
+            fiatAmount,
+            network: network.toUpperCase(),
+        };
+        const response = await this.apiRequest('POST', endpoint, requestBody);
+        const rate = response.rate || 0;
+        const cryptoAmount = response.cryptoAmount || 0;
+        const feeTotal = response.fee || 0;
+        return {
+            fiatAmount,
+            cryptoAmount,
+            rate,
+            feeFixed: 0,
+            feePercent: (feeTotal / fiatAmount) * 100,
+            feeTotal,
+            expiresAt: response.expiresAt || new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+        };
+    }
+    async createOnRamp(params) {
+        (0, base_1.validateWalletAddress)(params.destinationWallet, params.network);
+        const quote = await this.getQuote('on', params.fiatAmount, params.fiatCurrency, params.asset, params.network);
+        const requestBody = {
+            cryptoCurrency: params.asset.toUpperCase(),
+            fiatCurrency: params.fiatCurrency.toUpperCase(),
+            fiatAmount: params.fiatAmount,
+            network: params.network.toUpperCase(),
+            walletAddress: params.destinationWallet,
+            customer: {
+                email: params.customer.email,
+                name: params.customer.name,
+                phone: params.customer.phone,
+            },
+            callbackUrl: params.urls.webhook,
+            successUrl: params.urls.success,
+            cancelUrl: params.urls.cancel,
+            externalReference: params.reference,
+        };
+        const response = await this.apiRequest('POST', '/v1/orders/buy', requestBody);
+        const sanitizedRaw = { ...response };
+        if (sanitizedRaw.bankAccount)
+            delete sanitizedRaw.bankAccount;
+        if (sanitizedRaw.bank_account)
+            delete sanitizedRaw.bank_account;
+        return {
+            id: response.id || `yc_on_${params.reference}`,
+            direction: 'on',
+            status: this.mapYellowCardStatus(response.status),
+            quote,
+            checkoutUrl: response.checkoutUrl || response.paymentUrl,
+            createdAt: response.createdAt || new Date().toISOString(),
+            expiresAt: quote.expiresAt,
+            raw: sanitizedRaw,
+        };
+    }
+    async createOffRamp(params) {
+        if (params.sourceWallet) {
+            (0, base_1.validateWalletAddress)(params.sourceWallet, params.network);
+        }
+        // Get real quote instead of synthetic calculation
+        // TODO(verify): Confirm Yellow Card supports off-ramp quotes via /v1/quotes/sell
+        // If the API doesn't support quotes for sell orders, this will fail and we need to handle it
+        const quote = await this.getQuote('off', params.cryptoAmount * 50000, // Estimate fiat for quote
+        params.fiatCurrency, params.asset, params.network);
+        const requestBody = {
+            cryptoCurrency: params.asset.toUpperCase(),
+            fiatCurrency: params.fiatCurrency.toUpperCase(),
+            cryptoAmount: params.cryptoAmount,
+            network: params.network.toUpperCase(),
+            bankAccount: {
+                accountNumber: params.bankAccount.accountNumber,
+                bankCode: params.bankAccount.branchCode,
+                accountName: params.bankAccount.accountHolder,
+                bankName: params.bankAccount.bankName,
+            },
+            customer: {
+                email: params.customer.email,
+                name: params.customer.name,
+                phone: params.customer.phone,
+            },
+            externalReference: params.reference,
+        };
+        const response = await this.apiRequest('POST', '/v1/orders/sell', requestBody);
+        const sanitizedRaw = { ...response };
+        if (sanitizedRaw.bankAccount)
+            delete sanitizedRaw.bankAccount;
+        if (sanitizedRaw.bank_account)
+            delete sanitizedRaw.bank_account;
+        return {
+            id: response.id || `yc_off_${params.reference}`,
+            direction: 'off',
+            status: this.mapYellowCardStatus(response.status),
+            quote,
+            depositAddress: response.depositAddress,
+            depositTag: response.memo || response.tag,
+            createdAt: response.createdAt || new Date().toISOString(),
+            expiresAt: quote.expiresAt,
+            raw: sanitizedRaw,
+        };
+    }
+    async getRamp(id) {
+        const response = await this.apiRequest('GET', `/v1/orders/${id}`);
+        const direction = response.type === 'buy' ? 'on' : 'off';
+        const status = this.mapYellowCardStatus(response.status);
+        const quote = {
+            fiatAmount: response.fiatAmount || 0,
+            cryptoAmount: response.cryptoAmount || 0,
+            rate: response.rate || 0,
+            feeFixed: 0,
+            feePercent: 0,
+            feeTotal: response.fee || 0,
+            expiresAt: response.expiresAt || new Date().toISOString(),
+        };
+        const sanitizedRaw = { ...response };
+        if (sanitizedRaw.bankAccount)
+            delete sanitizedRaw.bankAccount;
+        if (sanitizedRaw.bank_account)
+            delete sanitizedRaw.bank_account;
+        return {
+            id: response.id,
+            direction,
+            status,
+            quote,
+            txHash: response.txHash || response.transactionHash,
+            createdAt: response.createdAt || new Date().toISOString(),
+            raw: sanitizedRaw,
+        };
+    }
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        return {
+            type: event.eventType || event.type,
+            orderId: event.orderId || event.id,
+            status: event.status,
+            data: event,
+            raw: event,
+        };
+    }
+    verifyWebhook(body, headers) {
+        if (!this.webhookSecret)
+            return false;
+        // TODO(verify): Confirm Yellow Card webhook signature scheme and header names
+        // Current implementation: HMAC-SHA256(webhookSecret, body) in hex format
+        // Common alternatives: timestamp-based scheme like HMAC-SHA256(secret, timestamp.body)
+        // Header name might be X-YC-Signature, X-Signature, or x-yellowcard-signature
+        const signature = headers?.['x-yellowcard-signature'] || headers?.['x-signature'] || headers?.signature;
+        if (!signature)
+            return false;
+        // Check if this is a timestamp-based signature (format: "t=timestamp,s=signature")
+        const timestampMatch = signature.match(/^t=(\d+),s=([a-f0-9]+)$/);
+        if (timestampMatch) {
+            const timestamp = parseInt(timestampMatch[1], 10);
+            const sig = timestampMatch[2];
+            // Replay protection: reject timestamps older than 5 minutes
+            const now = Math.floor(Date.now() / 1000);
+            if (Math.abs(now - timestamp) > 300) {
+                return false;
+            }
+            const payload = `${timestamp}.${body}`;
+            const expectedSignature = crypto_1.default
+                .createHmac('sha256', this.webhookSecret)
+                .update(payload)
+                .digest('hex');
+            const sigBuf = Buffer.from(sig);
+            const expBuf = Buffer.from(expectedSignature);
+            if (sigBuf.length !== expBuf.length)
+                return false;
+            return crypto_1.default.timingSafeEqual(sigBuf, expBuf);
+        }
+        // Fallback: simple HMAC-SHA256(body) verification
+        const expectedSignature = crypto_1.default
+            .createHmac('sha256', this.webhookSecret)
+            .update(body)
+            .digest('hex');
+        const sigBuf = Buffer.from(signature);
+        const expBuf = Buffer.from(expectedSignature);
+        if (sigBuf.length !== expBuf.length)
+            return false;
+        return crypto_1.default.timingSafeEqual(sigBuf, expBuf);
+    }
+    getCapabilities() {
+        return {
+            supportedAssets: ['BTC', 'ETH', 'USDT', 'USDC'],
+            supportedNetworks: ['BTC', 'ETH', 'TRON', 'POLYGON'],
+            supportedFiat: ['ZAR', 'NGN', 'KES', 'UGX', 'GHS'],
+            country: 'AFRICA',
+            kycRequired: true,
+            onRampLimits: {
+                min: 10,
+                max: 100000,
+            },
+            offRampLimits: {
+                min: 20,
+                max: 100000,
+            },
+            fees: {
+                onRampPercent: 3.5,
+                offRampPercent: 2.0,
+            },
+            experimental: true,
+        };
+    }
+    async apiRequest(method, path, body) {
+        const timestamp = Date.now().toString();
+        const bodyString = body ? JSON.stringify(body) : '';
+        const signature = this.generateSignature(method, path, timestamp, bodyString);
+        const url = `${this.baseUrl}${path}`;
+        // TODO(verify): Confirm Yellow Card API header names
+        // Current: X-API-Key, X-Timestamp, X-Signature
+        // Common alternatives: X-YC-API-Key, X-YC-Timestamp, X-YC-Signature
+        // Or: Authorization header + separate X-Signature
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.apiKey,
+                'X-Timestamp': timestamp,
+                'X-Signature': signature,
+            },
+            body: body ? bodyString : undefined,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Yellow Card API error (${method} ${path}): ${response.status} - ${errorText}`);
+        }
+        return await response.json();
+    }
+    generateSignature(method, path, timestamp, body) {
+        // TODO(verify): Confirm Yellow Card signature algorithm
+        // Current: HMAC-SHA256(secret, method+path+timestamp+body) -> hex
+        // Common alternative patterns:
+        //   1. HMAC-SHA256(secret, path+base64(SHA256(body))+timestamp+method) -> base64
+        //   2. HMAC-SHA256(secret, timestamp+method+path+body) -> hex
+        //   3. HMAC-SHA256(secret, method+path+timestamp+SHA256(body)) -> base64
+        // Without official docs/SDK, current implementation is speculative
+        const message = `${method}${path}${timestamp}${body}`;
+        return crypto_1.default
+            .createHmac('sha256', this.secretKey)
+            .update(message)
+            .digest('hex');
+    }
+    mapYellowCardStatus(ycStatus) {
+        const statusMap = {
+            pending: 'pending',
+            processing: 'pending',
+            completed: 'completed',
+            success: 'completed',
+            failed: 'failed',
+            cancelled: 'failed',
+            expired: 'expired',
+        };
+        return statusMap[ycStatus?.toLowerCase()] || 'pending';
+    }
+}
+exports.YellowCardProvider = YellowCardProvider;
+YellowCardProvider.warnedExperimental = false;

package/dist/index.d.ts

@@ -4,11 +4,19 @@
  *
  * @see https://github.com/kobie3717/paybridge
  */
+import { PaymentProvider } from './providers/base';
 import { PayBridgeConfig, CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from './types';
 export * from './types';
 export * from './utils/currency';
+export * from './routing-types';
+export * from './circuit-breaker';
+export * from './circuit-breaker-store';
+export * from './strategies';
+export * from './router';
+export * from './crypto';
+export { createRedisCircuitBreakerStore, type RedisLike, type RedisStoreOptions } from './stores/redis';
 export declare class PayBridge {
-    private provider;
+    readonly provider: PaymentProvider;
     constructor(config: PayBridgeConfig);
     /**
      * Create provider instance based on config

package/dist/index.js

@@ -20,12 +20,25 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayBridge = void 0;
+exports.PayBridge = exports.createRedisCircuitBreakerStore = void 0;
 const softycomp_1 = require("./providers/softycomp");
 const yoco_1 = require("./providers/yoco");
 const ozow_1 = require("./providers/ozow");
+const peach_1 = require("./providers/peach");
+const stripe_1 = require("./providers/stripe");
+const payfast_1 = require("./providers/payfast");
+const paystack_1 = require("./providers/paystack");
+const flutterwave_1 = require("./providers/flutterwave");
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils/currency"), exports);
+__exportStar(require("./routing-types"), exports);
+__exportStar(require("./circuit-breaker"), exports);
+__exportStar(require("./circuit-breaker-store"), exports);
+__exportStar(require("./strategies"), exports);
+__exportStar(require("./router"), exports);
+__exportStar(require("./crypto"), exports);
+var redis_1 = require("./stores/redis");
+Object.defineProperty(exports, "createRedisCircuitBreakerStore", { enumerable: true, get: function () { return redis_1.createRedisCircuitBreakerStore; } });
 class PayBridge {
     constructor(config) {
         this.provider = this.createProvider(config);
@@ -65,11 +78,54 @@ class PayBridge {
                     privateKey: credentials.privateKey,
                     sandbox,
                 });
+            case 'stripe':
+                if (!credentials.apiKey) {
+                    throw new Error('Stripe requires apiKey (secret key, sk_test_* or sk_live_*)');
+                }
+                return new stripe_1.StripeProvider({
+                    apiKey: credentials.apiKey,
+                    webhookSecret,
+                    sandbox,
+                });
             case 'payfast':
+                if (!credentials.merchantId || !credentials.merchantKey) {
+                    throw new Error('PayFast requires merchantId and merchantKey');
+                }
+                return new payfast_1.PayFastProvider({
+                    merchantId: credentials.merchantId,
+                    merchantKey: credentials.merchantKey,
+                    passphrase: credentials.passphrase,
+                    sandbox,
+                    webhookSecret,
+                });
             case 'paystack':
-            case 'stripe':
+                if (!credentials.apiKey) {
+                    throw new Error('PayStack requires apiKey (secret key, sk_test_* or sk_live_*)');
+                }
+                return new paystack_1.PayStackProvider({
+                    apiKey: credentials.apiKey,
+                    sandbox,
+                    webhookSecret,
+                });
             case 'peach':
-                throw new Error(`Provider ${provider} not yet implemented. Coming soon!`);
+                if (!credentials.apiKey || !credentials.secretKey) {
+                    throw new Error('Peach Payments requires apiKey (access token) and secretKey (entityId)');
+                }
+                return new peach_1.PeachProvider({
+                    accessToken: credentials.apiKey,
+                    entityId: credentials.secretKey,
+                    sandbox,
+                    webhookSecret,
+                });
+            case 'flutterwave':
+                if (!credentials.apiKey) {
+                    throw new Error('Flutterwave requires apiKey (FLWSECK_TEST-* or FLWSECK-*)');
+                }
+                return new flutterwave_1.FlutterwaveProvider({
+                    apiKey: credentials.apiKey,
+                    sandbox,
+                    webhookSecret,
+                });
             default:
                 throw new Error(`Unknown provider: ${provider}`);
         }

package/dist/providers/base.d.ts

@@ -3,6 +3,7 @@
  * All payment providers must extend this class
  */
 import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
 export declare abstract class PaymentProvider {
     /**
      * Provider name (e.g. 'softycomp', 'yoco', 'ozow')
@@ -37,6 +38,10 @@ export declare abstract class PaymentProvider {
      * @returns true if signature is valid, false otherwise
      */
     abstract verifyWebhook(body: any, headers?: any): boolean;
+    /**
+     * Get provider capabilities (fees, limits, etc)
+     */
+    abstract getCapabilities(): ProviderCapabilities;
     /**
      * Validate currency is supported
      */

package/dist/providers/flutterwave.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Flutterwave payment provider
+ * Leading payment gateway for Africa with global reach
+ * @see https://developer.flutterwave.com/docs
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+import { ProviderCapabilities } from '../routing-types';
+interface FlutterwaveConfig {
+    apiKey: string;
+    webhookSecret?: string;
+    sandbox?: boolean;
+}
+export declare class FlutterwaveProvider extends PaymentProvider {
+    readonly name = "flutterwave";
+    readonly supportedCurrencies: string[];
+    private apiKey;
+    private webhookSecret?;
+    private sandbox;
+    private baseUrl;
+    constructor(config: FlutterwaveConfig);
+    private apiRequest;
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    /**
+     * Verify webhook signature using Flutterwave's scheme.
+     * Flutterwave sends the configured webhook secret hash as the verif-hash header.
+     * This is a simple equality check, not HMAC.
+     */
+    verifyWebhook(body: any, headers?: any): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+export {};