paybridge 0.6.0 → 0.8.0

package/README.md

@@ -48,6 +48,17 @@ The playground lets you:
 
 Perfect for demos, learning, and rapid prototyping. See [playground/README.md](playground/README.md) for details.
 
+## Framework Examples
+
+Runnable integrations for common Node.js frameworks:
+
+- [Express](examples/frameworks/express/) — classic, raw body parsing for webhooks
+- [Fastify](examples/frameworks/fastify/) — Fastify plugin pattern, custom content type parser
+- [Next.js](examples/frameworks/nextjs/) — App Router API routes, multi-provider router
+- [Hono](examples/frameworks/hono/) — edge-runtime ready (Cloudflare Workers, Bun, Deno, Node)
+
+Each example uses `PayBridgeRouter` with Stripe + PayStack and demonstrates webhook signature verification, idempotency, and provider-specific routing.
+
 ## Quick Start
 
 > **Upgrading from 0.1 or 0.2?** See [docs/migration.md](docs/migration.md).

package/dist/cli/commands/providers.d.ts

@@ -0,0 +1 @@
+export declare function runProviders(args: string[]): Promise<void>;

package/dist/cli/commands/providers.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProviders = runProviders;
+const index_1 = require("../../index");
+const crypto_1 = require("../../crypto");
+const utils_1 = require("../utils");
+const FIAT_PROVIDERS = [
+    'softycomp',
+    'yoco',
+    'ozow',
+    'payfast',
+    'paystack',
+    'stripe',
+    'peach',
+    'flutterwave',
+    'adyen',
+    'mercadopago',
+    'razorpay',
+    'mollie',
+    'square',
+    'pesapal',
+];
+const CRYPTO_PROVIDERS = ['moonpay', 'yellowcard', 'transak', 'ramp'];
+function createDummyProvider(name) {
+    const dummyCreds = {
+        softycomp: { apiKey: 'dummy', secretKey: 'dummy' },
+        yoco: { apiKey: 'dummy' },
+        ozow: { apiKey: 'dummy', siteCode: 'dummy', privateKey: 'dummy' },
+        payfast: { merchantId: 'dummy', merchantKey: 'dummy' },
+        paystack: { apiKey: 'dummy' },
+        stripe: { apiKey: 'dummy' },
+        peach: { apiKey: 'dummy', secretKey: 'dummy' },
+        flutterwave: { apiKey: 'dummy' },
+        adyen: { apiKey: 'dummy', merchantAccount: 'dummy' },
+        mercadopago: { apiKey: 'dummy' },
+        razorpay: { apiKey: 'dummy', secretKey: 'dummy' },
+        mollie: { apiKey: 'dummy' },
+        square: { apiKey: 'dummy', locationId: 'dummy' },
+        pesapal: { apiKey: 'dummy', secretKey: 'dummy' },
+    };
+    return new index_1.PayBridge({
+        provider: name,
+        credentials: dummyCreds[name],
+        sandbox: true,
+    });
+}
+function createDummyCryptoProvider(name) {
+    const dummyCreds = {
+        moonpay: { apiKey: 'dummy', secretKey: 'dummy' },
+        yellowcard: { apiKey: 'dummy', secretKey: 'dummy' },
+        transak: { apiKey: 'dummy', secretKey: 'dummy' },
+        ramp: { apiKey: 'dummy' },
+        mock: { apiKey: 'dummy' },
+    };
+    return new crypto_1.CryptoRamp({
+        provider: name,
+        credentials: dummyCreds[name],
+        sandbox: true,
+    });
+}
+async function runProviders(args) {
+    const isJson = args.includes('--json');
+    if (isJson) {
+        const fiat = FIAT_PROVIDERS.map((name) => {
+            const provider = createDummyProvider(name);
+            const caps = provider.provider.getCapabilities();
+            return {
+                provider: name,
+                type: 'fiat',
+                region: caps.country || 'N/A',
+                currencies: caps.currencies,
+                fee: `${caps.fees.percent ?? 0}% + ${caps.fees.fixed ?? 0}`,
+                minAmount: caps.minAmount,
+                maxAmount: caps.maxAmount,
+                avgLatencyMs: caps.avgLatencyMs,
+            };
+        });
+        const crypto = CRYPTO_PROVIDERS.map((name) => {
+            const ramp = createDummyCryptoProvider(name);
+            const caps = ramp.getCapabilities();
+            return {
+                provider: name,
+                type: 'crypto',
+                onRampSupported: !!caps.onRampLimits,
+                offRampSupported: !!caps.offRampLimits,
+                assets: caps.supportedAssets,
+                onRampFeePercent: caps.fees.onRampPercent,
+                offRampFeePercent: caps.fees.offRampPercent,
+                experimental: caps.experimental,
+                avgLatencyMs: caps.avgLatencyMs,
+            };
+        });
+        console.log(JSON.stringify({ fiat, crypto }, null, 2));
+        return;
+    }
+    console.log((0, utils_1.colorize)('\nFIAT PROVIDERS', 'bright'));
+    console.log('==============\n');
+    const fiatRows = [
+        ['PROVIDER', 'REGION', 'CURRENCIES', 'FEE'],
+    ];
+    for (const name of FIAT_PROVIDERS) {
+        const provider = createDummyProvider(name);
+        const caps = provider.provider.getCapabilities();
+        fiatRows.push([
+            name,
+            caps.country || 'N/A',
+            caps.currencies.join('/'),
+            `${caps.fees.percent ?? 0}% + ${caps.fees.fixed ?? 0}`,
+        ]);
+    }
+    console.log((0, utils_1.formatTable)(fiatRows));
+    console.log((0, utils_1.colorize)('\n\nCRYPTO PROVIDERS', 'bright'));
+    console.log('================\n');
+    const cryptoRows = [
+        ['PROVIDER', 'ON-RAMP', 'OFF-RAMP', 'ASSETS', 'FEE (ON/OFF)'],
+    ];
+    for (const name of CRYPTO_PROVIDERS) {
+        const ramp = createDummyCryptoProvider(name);
+        const caps = ramp.getCapabilities();
+        const onRampIcon = caps.experimental ? '⚠' : caps.onRampLimits ? '✓' : '✗';
+        const offRampIcon = caps.experimental ? '⚠' : caps.offRampLimits ? '✓' : '✗';
+        const feeText = caps.experimental
+            ? '⚠ experimental'
+            : `${caps.fees.onRampPercent ?? 0}% / ${caps.fees.offRampPercent ?? 0}%`;
+        cryptoRows.push([
+            name,
+            onRampIcon,
+            offRampIcon,
+            caps.supportedAssets.slice(0, 4).join('/'),
+            feeText,
+        ]);
+    }
+    console.log((0, utils_1.formatTable)(cryptoRows));
+    console.log('');
+}

package/dist/cli/commands/quote.d.ts

@@ -0,0 +1 @@
+export declare function runQuote(args: string[]): Promise<void>;

package/dist/cli/commands/quote.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runQuote = runQuote;
+const crypto_1 = require("../../crypto");
+const utils_1 = require("../utils");
+const CRYPTO_PROVIDERS = ['moonpay', 'yellowcard', 'transak', 'ramp'];
+function createCryptoProviderFromEnv(providerName) {
+    const envMap = {
+        moonpay: {
+            keys: ['MOONPAY_API_KEY', 'MOONPAY_SECRET_KEY'],
+            mapper: (env) => ({ apiKey: env.MOONPAY_API_KEY, secretKey: env.MOONPAY_SECRET_KEY }),
+        },
+        yellowcard: {
+            keys: ['YELLOWCARD_API_KEY', 'YELLOWCARD_SECRET_KEY'],
+            mapper: (env) => ({ apiKey: env.YELLOWCARD_API_KEY, secretKey: env.YELLOWCARD_SECRET_KEY }),
+        },
+        transak: {
+            keys: ['TRANSAK_API_KEY', 'TRANSAK_SECRET_KEY'],
+            mapper: (env) => ({ apiKey: env.TRANSAK_API_KEY, secretKey: env.TRANSAK_SECRET_KEY }),
+        },
+        ramp: {
+            keys: ['RAMP_API_KEY'],
+            mapper: (env) => ({ apiKey: env.RAMP_API_KEY }),
+        },
+        mock: {
+            keys: [],
+            mapper: () => ({ apiKey: 'mock' }),
+        },
+    };
+    const config = envMap[providerName];
+    if (!config) {
+        throw new Error(`Unknown crypto provider: ${providerName}`);
+    }
+    const missing = config.keys.filter((k) => !process.env[k]);
+    if (missing.length > 0) {
+        throw new Error(`Missing required env vars: ${missing.join(', ')}`);
+    }
+    const credentials = config.mapper(process.env);
+    return new crypto_1.CryptoRamp({
+        provider: providerName,
+        credentials,
+        sandbox: true,
+    });
+}
+async function runQuote(args) {
+    const providerName = args[0];
+    if (!providerName) {
+        console.error('Usage: paybridge quote <provider> --direction on|off --fiat-amount N --fiat-currency CUR --asset ASSET --network NET');
+        process.exit(1);
+    }
+    if (!CRYPTO_PROVIDERS.includes(providerName)) {
+        console.error(`Unknown crypto provider: ${providerName}`);
+        console.error(`Available: ${CRYPTO_PROVIDERS.join(', ')}`);
+        process.exit(1);
+    }
+    const getArg = (flag) => {
+        const idx = args.indexOf(flag);
+        return idx >= 0 && args[idx + 1] ? args[idx + 1] : undefined;
+    };
+    const direction = getArg('--direction');
+    const fiatAmountStr = getArg('--fiat-amount');
+    const fiatCurrency = getArg('--fiat-currency');
+    const asset = getArg('--asset');
+    const network = getArg('--network');
+    if (!direction || !fiatAmountStr || !fiatCurrency || !asset) {
+        console.error('Missing required flags: --direction, --fiat-amount, --fiat-currency, --asset');
+        process.exit(1);
+    }
+    const fiatAmount = parseFloat(fiatAmountStr);
+    if (!Number.isFinite(fiatAmount) || fiatAmount <= 0) {
+        console.error('Invalid fiat amount (must be positive number)');
+        process.exit(1);
+    }
+    let provider;
+    try {
+        provider = createCryptoProviderFromEnv(providerName);
+    }
+    catch (error) {
+        console.error((0, utils_1.colorize)(error.message, 'red'));
+        process.exit(1);
+    }
+    try {
+        const quote = await provider.getQuote(direction, fiatAmount, fiatCurrency, asset, network || asset);
+        console.log(JSON.stringify(quote, null, 2));
+        process.exit(0);
+    }
+    catch (error) {
+        console.error((0, utils_1.colorize)(`Quote error: ${error.message}`, 'red'));
+        process.exit(1);
+    }
+}

package/dist/cli/commands/test.d.ts

@@ -0,0 +1 @@
+export declare function runTest(args: string[]): Promise<void>;

package/dist/cli/commands/test.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTest = runTest;
+const runners_1 = require("../runners");
+const utils_1 = require("../utils");
+async function runProviderTest(runner) {
+    const missing = runner.envRequired.filter((key) => !process.env[key]);
+    if (missing.length > 0) {
+        return {
+            provider: runner.name,
+            status: 'skipped',
+            message: `Missing: ${missing.join(', ')}`,
+        };
+    }
+    console.log(`${(0, utils_1.colorize)('[…]', 'cyan')} ${runner.name} - validating...`);
+    try {
+        const result = await runner.run();
+        if (!result.id) {
+            throw new Error('No payment ID returned');
+        }
+        console.log(`${(0, utils_1.colorize)('[✓]', 'green')} ${runner.name} → id=${result.id}${result.checkoutUrl ? `, url=${result.checkoutUrl.substring(0, 60)}...` : ''}, status=${result.status}`);
+        return {
+            provider: runner.name,
+            status: 'success',
+            data: {
+                id: result.id,
+                checkoutUrl: result.checkoutUrl,
+                status: result.status,
+            },
+        };
+    }
+    catch (error) {
+        console.log(`${(0, utils_1.colorize)('[✗]', 'red')} ${runner.name} ERROR: ${error.message || String(error)}`);
+        return {
+            provider: runner.name,
+            status: 'failed',
+            message: error.message || String(error),
+        };
+    }
+}
+async function runTest(args) {
+    const isAll = args.includes('--all');
+    const providerName = args.find((a) => !a.startsWith('--'));
+    if (!isAll && !providerName) {
+        console.error('Usage: paybridge test <provider> | paybridge test --all');
+        process.exit(1);
+    }
+    console.log('\n=== PayBridge Test ===\n');
+    const results = [];
+    if (isAll) {
+        for (const runner of runners_1.runners) {
+            const result = await runProviderTest(runner);
+            results.push(result);
+        }
+    }
+    else {
+        const runner = runners_1.runners.find((r) => r.name === providerName);
+        if (!runner) {
+            console.error(`Unknown provider: ${providerName}`);
+            console.error(`Available: ${runners_1.runners.map((r) => r.name).join(', ')}`);
+            process.exit(1);
+        }
+        const result = await runProviderTest(runner);
+        results.push(result);
+    }
+    console.log('\n=== Summary ===\n');
+    const succeeded = results.filter((r) => r.status === 'success').length;
+    const skipped = results.filter((r) => r.status === 'skipped').length;
+    const failed = results.filter((r) => r.status === 'failed').length;
+    results.forEach((r) => {
+        const icon = r.status === 'success'
+            ? (0, utils_1.colorize)('[✓]', 'green')
+            : r.status === 'skipped'
+                ? (0, utils_1.colorize)('[ ]', 'dim')
+                : (0, utils_1.colorize)('[✗]', 'red');
+        const msg = r.message ? ` (${r.message})` : '';
+        console.log(`${icon} ${r.provider}${msg}`);
+    });
+    console.log(`\nSucceeded: ${succeeded}, Skipped: ${skipped}, Failed: ${failed}`);
+    if (failed > 0) {
+        console.log('\nSome providers failed validation.');
+        process.exit(1);
+    }
+    else if (succeeded === 0) {
+        console.log('\nNo providers validated (all skipped). Set env vars to validate.');
+        process.exit(0);
+    }
+    else {
+        console.log('\nAll enabled providers validated successfully!');
+        process.exit(0);
+    }
+}

package/dist/cli/commands/webhook.d.ts

@@ -0,0 +1 @@
+export declare function runWebhook(args: string[]): Promise<void>;

package/dist/cli/commands/webhook.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWebhook = runWebhook;
+const index_1 = require("../../index");
+const utils_1 = require("../utils");
+const PROVIDERS = [
+    'softycomp',
+    'yoco',
+    'ozow',
+    'payfast',
+    'paystack',
+    'stripe',
+    'peach',
+    'flutterwave',
+    'adyen',
+    'mercadopago',
+    'razorpay',
+    'mollie',
+    'square',
+    'pesapal',
+];
+function createProviderFromEnv(providerName) {
+    const envMap = {
+        softycomp: {
+            keys: ['SOFTYCOMP_API_KEY', 'SOFTYCOMP_SECRET_KEY', 'SOFTYCOMP_WEBHOOK_SECRET'],
+            mapper: (env) => ({
+                apiKey: env.SOFTYCOMP_API_KEY,
+                secretKey: env.SOFTYCOMP_SECRET_KEY,
+                webhookSecret: env.SOFTYCOMP_WEBHOOK_SECRET,
+            }),
+        },
+        yoco: {
+            keys: ['YOCO_API_KEY', 'YOCO_WEBHOOK_SECRET'],
+            mapper: (env) => ({ apiKey: env.YOCO_API_KEY, webhookSecret: env.YOCO_WEBHOOK_SECRET }),
+        },
+        ozow: {
+            keys: ['OZOW_API_KEY', 'OZOW_SITE_CODE', 'OZOW_PRIVATE_KEY'],
+            mapper: (env) => ({
+                apiKey: env.OZOW_API_KEY,
+                siteCode: env.OZOW_SITE_CODE,
+                privateKey: env.OZOW_PRIVATE_KEY,
+            }),
+        },
+        payfast: {
+            keys: ['PAYFAST_MERCHANT_ID', 'PAYFAST_MERCHANT_KEY', 'PAYFAST_PASSPHRASE'],
+            mapper: (env) => ({
+                merchantId: env.PAYFAST_MERCHANT_ID,
+                merchantKey: env.PAYFAST_MERCHANT_KEY,
+                passphrase: env.PAYFAST_PASSPHRASE,
+            }),
+        },
+        paystack: {
+            keys: ['PAYSTACK_API_KEY', 'PAYSTACK_WEBHOOK_SECRET'],
+            mapper: (env) => ({ apiKey: env.PAYSTACK_API_KEY, webhookSecret: env.PAYSTACK_WEBHOOK_SECRET }),
+        },
+        stripe: {
+            keys: ['STRIPE_API_KEY', 'STRIPE_WEBHOOK_SECRET'],
+            mapper: (env) => ({ apiKey: env.STRIPE_API_KEY, webhookSecret: env.STRIPE_WEBHOOK_SECRET }),
+        },
+        peach: {
+            keys: ['PEACH_ACCESS_TOKEN', 'PEACH_ENTITY_ID', 'PEACH_WEBHOOK_SECRET'],
+            mapper: (env) => ({
+                apiKey: env.PEACH_ACCESS_TOKEN,
+                secretKey: env.PEACH_ENTITY_ID,
+                webhookSecret: env.PEACH_WEBHOOK_SECRET,
+            }),
+        },
+        flutterwave: {
+            keys: ['FLUTTERWAVE_API_KEY', 'FLUTTERWAVE_WEBHOOK_SECRET'],
+            mapper: (env) => ({ apiKey: env.FLUTTERWAVE_API_KEY, webhookSecret: env.FLUTTERWAVE_WEBHOOK_SECRET }),
+        },
+        adyen: {
+            keys: ['ADYEN_API_KEY', 'ADYEN_MERCHANT_ACCOUNT', 'ADYEN_WEBHOOK_SECRET'],
+            mapper: (env) => ({
+                apiKey: env.ADYEN_API_KEY,
+                merchantAccount: env.ADYEN_MERCHANT_ACCOUNT,
+                webhookSecret: env.ADYEN_WEBHOOK_SECRET,
+            }),
+        },
+        mercadopago: {
+            keys: ['MERCADOPAGO_ACCESS_TOKEN', 'MERCADOPAGO_WEBHOOK_SECRET'],
+            mapper: (env) => ({ apiKey: env.MERCADOPAGO_ACCESS_TOKEN, webhookSecret: env.MERCADOPAGO_WEBHOOK_SECRET }),
+        },
+        razorpay: {
+            keys: ['RAZORPAY_KEY_ID', 'RAZORPAY_KEY_SECRET', 'RAZORPAY_WEBHOOK_SECRET'],
+            mapper: (env) => ({
+                apiKey: env.RAZORPAY_KEY_ID,
+                secretKey: env.RAZORPAY_KEY_SECRET,
+                webhookSecret: env.RAZORPAY_WEBHOOK_SECRET,
+            }),
+        },
+        mollie: {
+            keys: ['MOLLIE_API_KEY'],
+            mapper: (env) => ({ apiKey: env.MOLLIE_API_KEY }),
+        },
+        square: {
+            keys: ['SQUARE_ACCESS_TOKEN', 'SQUARE_LOCATION_ID', 'SQUARE_WEBHOOK_SECRET'],
+            mapper: (env) => ({
+                apiKey: env.SQUARE_ACCESS_TOKEN,
+                locationId: env.SQUARE_LOCATION_ID,
+                webhookSecret: env.SQUARE_WEBHOOK_SECRET,
+            }),
+        },
+        pesapal: {
+            keys: ['PESAPAL_CONSUMER_KEY', 'PESAPAL_CONSUMER_SECRET'],
+            mapper: (env) => ({ apiKey: env.PESAPAL_CONSUMER_KEY, secretKey: env.PESAPAL_CONSUMER_SECRET }),
+        },
+    };
+    const config = envMap[providerName];
+    if (!config) {
+        throw new Error(`Unknown provider: ${providerName}`);
+    }
+    const required = config.keys.filter((k) => !k.includes('WEBHOOK_SECRET'));
+    const missing = required.filter((k) => !process.env[k]);
+    if (missing.length > 0) {
+        throw new Error(`Missing required env vars: ${missing.join(', ')}`);
+    }
+    const credentials = config.mapper(process.env);
+    return new index_1.PayBridge({
+        provider: providerName,
+        credentials,
+        sandbox: true,
+        webhookSecret: credentials.webhookSecret,
+    });
+}
+async function runWebhook(args) {
+    const subcommand = args[0];
+    const providerName = args[1];
+    if (!subcommand || !providerName) {
+        console.error('Usage: paybridge webhook verify|parse <provider> [--header key=value]');
+        process.exit(1);
+    }
+    if (!PROVIDERS.includes(providerName)) {
+        console.error(`Unknown provider: ${providerName}`);
+        console.error(`Available: ${PROVIDERS.join(', ')}`);
+        process.exit(1);
+    }
+    const headerFlags = args.slice(2).filter((a) => a.startsWith('--header')).map((a) => a.replace('--header', '').trim());
+    const headersJsonFlag = args.find((a) => a.startsWith('--headers-json='));
+    let headers = {};
+    if (headersJsonFlag) {
+        const json = headersJsonFlag.replace('--headers-json=', '');
+        try {
+            headers = JSON.parse(json);
+        }
+        catch {
+            console.error('Invalid JSON in --headers-json');
+            process.exit(1);
+        }
+    }
+    else {
+        headers = (0, utils_1.parseHeaders)(headerFlags);
+    }
+    const rawBody = await (0, utils_1.readStdin)();
+    let body;
+    try {
+        body = JSON.parse(rawBody);
+    }
+    catch {
+        body = rawBody;
+    }
+    let provider;
+    try {
+        provider = createProviderFromEnv(providerName);
+    }
+    catch (error) {
+        console.error((0, utils_1.colorize)(error.message, 'red'));
+        process.exit(1);
+    }
+    if (subcommand === 'verify') {
+        const valid = provider.verifyWebhook(body, headers);
+        if (valid) {
+            console.log((0, utils_1.colorize)('OK', 'green'));
+            process.exit(0);
+        }
+        else {
+            console.log((0, utils_1.colorize)('INVALID', 'red'));
+            process.exit(1);
+        }
+    }
+    else if (subcommand === 'parse') {
+        try {
+            const event = provider.parseWebhook(body, headers);
+            console.log(JSON.stringify(event, null, 2));
+            process.exit(0);
+        }
+        catch (error) {
+            console.error((0, utils_1.colorize)(`Parse error: ${error.message}`, 'red'));
+            process.exit(1);
+        }
+    }
+    else {
+        console.error(`Unknown webhook subcommand: ${subcommand}`);
+        console.error('Use "verify" or "parse"');
+        process.exit(1);
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("./commands/test");
+const providers_1 = require("./commands/providers");
+const webhook_1 = require("./commands/webhook");
+const quote_1 = require("./commands/quote");
+const utils_1 = require("./utils");
+async function main() {
+    const [, , command, ...args] = process.argv;
+    switch (command) {
+        case 'test':
+            await (0, test_1.runTest)(args);
+            break;
+        case 'providers':
+            await (0, providers_1.runProviders)(args);
+            break;
+        case 'webhook':
+            await (0, webhook_1.runWebhook)(args);
+            break;
+        case 'quote':
+            await (0, quote_1.runQuote)(args);
+            break;
+        case '-h':
+        case '--help':
+        case 'help':
+        case undefined:
+            (0, utils_1.printHelp)();
+            process.exit(0);
+            break;
+        case '-v':
+        case '--version':
+            (0, utils_1.printVersion)();
+            process.exit(0);
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            (0, utils_1.printHelp)(true);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});

package/dist/cli/runners.d.ts

@@ -0,0 +1,10 @@
+export interface ProviderRunner {
+    name: string;
+    envRequired: string[];
+    run: () => Promise<{
+        id: string;
+        checkoutUrl?: string;
+        status: string;
+    }>;
+}
+export declare const runners: ProviderRunner[];

package/dist/cli/runners.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runners = void 0;
+const index_1 = require("../index");
+const crypto_1 = require("../crypto");
+const timestamp = Date.now();
+const testCustomer = {
+    name: 'Test User',
+    email: 'test@example.com',
+    phone: '0825551234',
+};
+const testUrls = {
+    success: 'https://example.com/success',
+    cancel: 'https://example.com/cancel',
+    webhook: 'https://example.com/webhook',
+};
+exports.runners = [
+    {
+        name: 'softycomp',
+        envRequired: ['SOFTYCOMP_API_KEY', 'SOFTYCOMP_SECRET_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'softycomp',
+                credentials: {
+                    apiKey: process.env.SOFTYCOMP_API_KEY,
+                    secretKey: process.env.SOFTYCOMP_SECRET_KEY,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'ZAR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'yoco',
+        envRequired: ['YOCO_API_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'yoco',
+                credentials: { apiKey: process.env.YOCO_API_KEY },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'ZAR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'ozow',
+        envRequired: ['OZOW_API_KEY', 'OZOW_SITE_CODE', 'OZOW_PRIVATE_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'ozow',
+                credentials: {
+                    apiKey: process.env.OZOW_API_KEY,
+                    siteCode: process.env.OZOW_SITE_CODE,
+                    privateKey: process.env.OZOW_PRIVATE_KEY,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'ZAR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'payfast',
+        envRequired: ['PAYFAST_MERCHANT_ID', 'PAYFAST_MERCHANT_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'payfast',
+                credentials: {
+                    merchantId: process.env.PAYFAST_MERCHANT_ID,
+                    merchantKey: process.env.PAYFAST_MERCHANT_KEY,
+                    passphrase: process.env.PAYFAST_PASSPHRASE,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'ZAR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'paystack',
+        envRequired: ['PAYSTACK_API_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'paystack',
+                credentials: { apiKey: process.env.PAYSTACK_API_KEY },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'NGN',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'stripe',
+        envRequired: ['STRIPE_API_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'stripe',
+                credentials: { apiKey: process.env.STRIPE_API_KEY },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'USD',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'peach',
+        envRequired: ['PEACH_ACCESS_TOKEN', 'PEACH_ENTITY_ID'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'peach',
+                credentials: {
+                    apiKey: process.env.PEACH_ACCESS_TOKEN,
+                    secretKey: process.env.PEACH_ENTITY_ID,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'ZAR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'flutterwave',
+        envRequired: ['FLUTTERWAVE_API_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'flutterwave',
+                credentials: { apiKey: process.env.FLUTTERWAVE_API_KEY },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'NGN',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'adyen',
+        envRequired: ['ADYEN_API_KEY', 'ADYEN_MERCHANT_ACCOUNT'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'adyen',
+                credentials: {
+                    apiKey: process.env.ADYEN_API_KEY,
+                    merchantAccount: process.env.ADYEN_MERCHANT_ACCOUNT,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'EUR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'mercadopago',
+        envRequired: ['MERCADOPAGO_ACCESS_TOKEN'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'mercadopago',
+                credentials: { apiKey: process.env.MERCADOPAGO_ACCESS_TOKEN },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'BRL',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'razorpay',
+        envRequired: ['RAZORPAY_KEY_ID', 'RAZORPAY_KEY_SECRET'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'razorpay',
+                credentials: {
+                    apiKey: process.env.RAZORPAY_KEY_ID,
+                    secretKey: process.env.RAZORPAY_KEY_SECRET,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'INR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'mollie',
+        envRequired: ['MOLLIE_API_KEY'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'mollie',
+                credentials: { apiKey: process.env.MOLLIE_API_KEY },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'EUR',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'square',
+        envRequired: ['SQUARE_ACCESS_TOKEN', 'SQUARE_LOCATION_ID'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'square',
+                credentials: {
+                    apiKey: process.env.SQUARE_ACCESS_TOKEN,
+                    locationId: process.env.SQUARE_LOCATION_ID,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'USD',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'pesapal',
+        envRequired: ['PESAPAL_CONSUMER_KEY', 'PESAPAL_CONSUMER_SECRET'],
+        run: async () => {
+            const pay = new index_1.PayBridge({
+                provider: 'pesapal',
+                credentials: {
+                    apiKey: process.env.PESAPAL_CONSUMER_KEY,
+                    secretKey: process.env.PESAPAL_CONSUMER_SECRET,
+                },
+                sandbox: true,
+            });
+            const payment = await pay.createPayment({
+                amount: 1.0,
+                currency: 'KES',
+                reference: `cli-test-${timestamp}`,
+                customer: testCustomer,
+                urls: testUrls,
+            });
+            return { id: payment.id, checkoutUrl: payment.checkoutUrl, status: payment.status };
+        },
+    },
+    {
+        name: 'moonpay',
+        envRequired: ['MOONPAY_API_KEY', 'MOONPAY_SECRET_KEY'],
+        run: async () => {
+            const ramp = new crypto_1.CryptoRamp({
+                provider: 'moonpay',
+                credentials: {
+                    apiKey: process.env.MOONPAY_API_KEY,
+                    secretKey: process.env.MOONPAY_SECRET_KEY,
+                },
+                sandbox: true,
+            });
+            const result = await ramp.createOnRamp({
+                fiatAmount: 1.0,
+                fiatCurrency: 'USD',
+                asset: 'BTC',
+                network: 'BTC',
+                destinationWallet: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
+                customer: testCustomer,
+                urls: testUrls,
+                reference: `cli-test-${timestamp}`,
+            });
+            return { id: result.id, checkoutUrl: result.checkoutUrl, status: result.status };
+        },
+    },
+];

package/dist/cli/utils.d.ts

@@ -0,0 +1,16 @@
+export declare const colors: {
+    reset: string;
+    bright: string;
+    dim: string;
+    green: string;
+    yellow: string;
+    red: string;
+    cyan: string;
+};
+export declare function colorize(text: string, color: keyof typeof colors): string;
+export declare function padEnd(str: string, length: number): string;
+export declare function formatTable(rows: string[][], padding?: number): string;
+export declare function readStdin(): Promise<string>;
+export declare function parseHeaders(headerFlags: string[]): Record<string, string>;
+export declare function printHelp(toStderr?: boolean): void;
+export declare function printVersion(): void;

package/dist/cli/utils.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colors = void 0;
+exports.colorize = colorize;
+exports.padEnd = padEnd;
+exports.formatTable = formatTable;
+exports.readStdin = readStdin;
+exports.parseHeaders = parseHeaders;
+exports.printHelp = printHelp;
+exports.printVersion = printVersion;
+exports.colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    cyan: '\x1b[36m',
+};
+function colorize(text, color) {
+    return `${exports.colors[color]}${text}${exports.colors.reset}`;
+}
+function padEnd(str, length) {
+    while (str.length < length) {
+        str += ' ';
+    }
+    return str;
+}
+function formatTable(rows, padding = 2) {
+    if (rows.length === 0)
+        return '';
+    const colWidths = [];
+    for (const row of rows) {
+        row.forEach((cell, i) => {
+            colWidths[i] = Math.max(colWidths[i] || 0, cell.length);
+        });
+    }
+    return rows
+        .map((row) => row.map((cell, i) => padEnd(cell, colWidths[i])).join(' '.repeat(padding)))
+        .join('\n');
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseHeaders(headerFlags) {
+    const headers = {};
+    for (const flag of headerFlags) {
+        const [key, ...valueParts] = flag.split('=');
+        if (key && valueParts.length > 0) {
+            headers[key.trim()] = valueParts.join('=').trim();
+        }
+    }
+    return headers;
+}
+function printHelp(toStderr = false) {
+    const output = `
+paybridge — unified payment SDK CLI
+
+USAGE
+  paybridge <command> [options]
+
+COMMANDS
+  test <provider>         Run sandbox createPayment validation for a provider
+  test --all              Run validation for every provider with env vars set
+  providers [--json]      List all providers with capabilities (table or JSON)
+  webhook verify <p>      Verify webhook signature (raw body from stdin)
+  webhook parse <p>       Parse webhook event (raw body from stdin)
+  quote <p> [opts]        Get a crypto on/off-ramp quote
+  help, -h, --help        Print this help
+  version, -v             Print version
+
+PROVIDER ENV VARS
+  See SETUP.md or run 'paybridge test --all' for the full list.
+
+EXAMPLES
+  paybridge providers
+  paybridge test stripe
+  STRIPE_API_KEY=sk_test_... paybridge test stripe
+  echo '{"id":"evt_x"}' | paybridge webhook parse paystack \\
+    --header x-paystack-signature=abc
+
+Docs: https://github.com/kobie3717/paybridge
+`.trim();
+    if (toStderr) {
+        console.error(output);
+    }
+    else {
+        console.log(output);
+    }
+}
+function printVersion() {
+    const pkg = require('../../package.json');
+    console.log(`paybridge v${pkg.version}`);
+}

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "paybridge",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "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",
+  "bin": {
+    "paybridge": "dist/cli/index.js"
+  },
   "scripts": {
     "build": "tsc",
+    "build:cli": "npm run build && node scripts/post-build.js",
     "clean": "rm -rf dist",
-    "prepack": "npm run clean && npm run build",
-    "prepublishOnly": "npm run clean && npm run build",
+    "cli": "node dist/cli/index.js",
+    "prepack": "npm run clean && npm run build:cli",
+    "prepublishOnly": "npm run clean && npm run build:cli",
     "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",
@@ -39,7 +44,9 @@
     "pesapal",
     "transak",
     "ramp",
-    "east-africa"
+    "east-africa",
+    "cli",
+    "command-line"
   ],
   "author": "Kobie Wentzel",
   "license": "MIT",