paybridge 0.10.0 → 0.11.0

package/README.md

@@ -101,6 +101,46 @@ Exit code 1 if drift detected, 0 if clean. Perfect for CI/CD pipelines or cron j
 
 The Square `/checkout/payment-links → /online-checkout/payment-links` endpoint change would have shipped silently to production. With `drift-check` running daily, you get a Slack alert the moment it happens.
 
+## Reconciliation
+
+Webhooks can fail. Networks blip. Your server hiccups. Provider retries don't reach you. Without reconciliation, you discover missed webhooks when a customer complains their account wasn't credited.
+
+PayBridge's **reconcile** command diffs your database against each provider's current state, catching payments where your local status doesn't match reality.
+
+### Quick Start
+
+```bash
+# From JSONL file
+echo '{"provider":"stripe","reference":"pay_001","expectedStatus":"pending"}' > expected.jsonl
+npx paybridge reconcile --input expected.jsonl
+
+# From SQL query (Postgres example)
+psql -t -c "SELECT provider, reference, status AS \"expectedStatus\" FROM payments WHERE status='pending' AND created_at > now() - interval '24 hours'" \
+  | npx paybridge reconcile
+
+# CSV format
+cat payments.csv | npx paybridge reconcile
+```
+
+### Example Output
+
+```
+[✓] stripe:pay_001 — completed (match)
+[!] stripe:pay_002 — expected pending, actual completed (MISSED WEBHOOK)
+[?] paystack:pay_003 — not-found (no provider record)
+[✗] stripe:pay_004 — error (HTTP 503)
+[ ] adyen:pay_005 — skipped (missing ADYEN_API_KEY)
+
+Reconciled: 5
+  Match: 1
+  Mismatch (missed webhook): 1
+  Not found: 1
+  Error: 1
+  Skipped: 1
+```
+
+Exit code 1 if any mismatch, 0 if clean. Add `--webhook-url` to POST mismatch reports to Slack/Discord/your ops channel. Use `--json` for pipeline integration.
+
 ## Quick Start
 
 > **Upgrading from 0.1 or 0.2?** See [docs/migration.md](docs/migration.md).

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

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

package/dist/cli/commands/reconcile.js

@@ -0,0 +1,341 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReconcileCommand = runReconcileCommand;
+const fs = __importStar(require("node:fs"));
+const readline = __importStar(require("node:readline"));
+const index_1 = require("../../index");
+const runners_1 = require("../runners");
+const reconcile_1 = require("../reconcile");
+const utils_1 = require("../utils");
+function parseOptions(args) {
+    const opts = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--input' && args[i + 1]) {
+            opts.input = args[i + 1];
+            i++;
+        }
+        else if (args[i] === '--json') {
+            opts.json = true;
+        }
+        else if (args[i] === '--webhook-url' && args[i + 1]) {
+            opts.webhookUrl = args[i + 1];
+            i++;
+        }
+    }
+    return opts;
+}
+async function parseInput(input) {
+    const lines = [];
+    if (input) {
+        const content = fs.readFileSync(input, 'utf8');
+        lines.push(...content.split('\n').filter((l) => l.trim()));
+    }
+    else {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false,
+        });
+        for await (const line of rl) {
+            if (line.trim()) {
+                lines.push(line.trim());
+            }
+        }
+    }
+    if (lines.length === 0) {
+        return [];
+    }
+    const firstLine = lines[0];
+    const isCsv = /^provider\s*,\s*reference\s*,\s*expectedStatus/i.test(firstLine);
+    const records = [];
+    if (isCsv) {
+        for (let i = 1; i < lines.length; i++) {
+            const parts = lines[i].split(',').map((s) => s.trim());
+            if (parts.length >= 3) {
+                records.push({
+                    provider: parts[0],
+                    reference: parts[1],
+                    expectedStatus: parts[2],
+                });
+            }
+        }
+    }
+    else {
+        for (const line of lines) {
+            try {
+                const obj = JSON.parse(line);
+                if (obj.provider && obj.reference && obj.expectedStatus) {
+                    records.push({
+                        provider: obj.provider,
+                        reference: obj.reference,
+                        expectedStatus: obj.expectedStatus,
+                    });
+                }
+            }
+            catch (e) {
+                console.error(`${(0, utils_1.colorize)('[!]', 'yellow')} Skipping invalid JSON line: ${line}`);
+            }
+        }
+    }
+    return records;
+}
+function buildProvider(providerName) {
+    const runner = runners_1.runners.find((r) => r.name === providerName);
+    if (!runner) {
+        throw new Error(`Unknown provider: ${providerName}`);
+    }
+    const missing = runner.envRequired.filter((key) => !process.env[key]);
+    if (missing.length > 0) {
+        throw new Error(`Missing: ${missing.join(', ')}`);
+    }
+    switch (providerName) {
+        case 'stripe':
+            return new index_1.PayBridge({
+                provider: 'stripe',
+                credentials: { apiKey: process.env.STRIPE_API_KEY },
+                sandbox: true,
+            });
+        case 'paystack':
+            return new index_1.PayBridge({
+                provider: 'paystack',
+                credentials: { apiKey: process.env.PAYSTACK_API_KEY },
+                sandbox: true,
+            });
+        case 'flutterwave':
+            return new index_1.PayBridge({
+                provider: 'flutterwave',
+                credentials: { apiKey: process.env.FLUTTERWAVE_API_KEY },
+                sandbox: true,
+            });
+        case 'adyen':
+            return new index_1.PayBridge({
+                provider: 'adyen',
+                credentials: {
+                    apiKey: process.env.ADYEN_API_KEY,
+                    merchantAccount: process.env.ADYEN_MERCHANT_ACCOUNT,
+                },
+                sandbox: true,
+            });
+        case 'softycomp':
+            return new index_1.PayBridge({
+                provider: 'softycomp',
+                credentials: {
+                    apiKey: process.env.SOFTYCOMP_API_KEY,
+                    secretKey: process.env.SOFTYCOMP_SECRET_KEY,
+                },
+                sandbox: true,
+            });
+        case 'yoco':
+            return new index_1.PayBridge({
+                provider: 'yoco',
+                credentials: { apiKey: process.env.YOCO_API_KEY },
+                sandbox: true,
+            });
+        case 'ozow':
+            return 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,
+            });
+        case 'payfast':
+            return 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,
+            });
+        case 'peach':
+            return new index_1.PayBridge({
+                provider: 'peach',
+                credentials: {
+                    apiKey: process.env.PEACH_ACCESS_TOKEN,
+                    secretKey: process.env.PEACH_ENTITY_ID,
+                },
+                sandbox: true,
+            });
+        case 'mercadopago':
+            return new index_1.PayBridge({
+                provider: 'mercadopago',
+                credentials: { apiKey: process.env.MERCADOPAGO_ACCESS_TOKEN },
+                sandbox: true,
+            });
+        case 'razorpay':
+            return new index_1.PayBridge({
+                provider: 'razorpay',
+                credentials: {
+                    apiKey: process.env.RAZORPAY_KEY_ID,
+                    secretKey: process.env.RAZORPAY_KEY_SECRET,
+                },
+                sandbox: true,
+            });
+        case 'mollie':
+            return new index_1.PayBridge({
+                provider: 'mollie',
+                credentials: { apiKey: process.env.MOLLIE_API_KEY },
+                sandbox: true,
+            });
+        case 'square':
+            return new index_1.PayBridge({
+                provider: 'square',
+                credentials: {
+                    apiKey: process.env.SQUARE_ACCESS_TOKEN,
+                    locationId: process.env.SQUARE_LOCATION_ID,
+                },
+                sandbox: true,
+            });
+        case 'pesapal':
+            return new index_1.PayBridge({
+                provider: 'pesapal',
+                credentials: {
+                    apiKey: process.env.PESAPAL_CONSUMER_KEY,
+                    secretKey: process.env.PESAPAL_CONSUMER_SECRET,
+                    notificationId: process.env.PESAPAL_NOTIFICATION_ID,
+                },
+                sandbox: true,
+            });
+        default:
+            throw new Error(`Provider ${providerName} not implemented in reconcile`);
+    }
+}
+function hasCredsFor(providerName) {
+    const runner = runners_1.runners.find((r) => r.name === providerName);
+    if (!runner) {
+        return false;
+    }
+    return runner.envRequired.every((key) => !!process.env[key]);
+}
+function printResult(result) {
+    const { provider, reference, classification, expectedStatus, actualStatus, errorMessage } = result;
+    let icon;
+    let message;
+    switch (classification) {
+        case 'match':
+            icon = (0, utils_1.colorize)('[✓]', 'green');
+            message = `${provider}:${reference} — ${actualStatus} (match)`;
+            break;
+        case 'mismatch':
+            icon = (0, utils_1.colorize)('[!]', 'yellow');
+            message = `${provider}:${reference} — expected ${expectedStatus}, actual ${actualStatus} (MISSED WEBHOOK)`;
+            break;
+        case 'not-found':
+            icon = (0, utils_1.colorize)('[?]', 'yellow');
+            message = `${provider}:${reference} — not-found (no provider record)`;
+            break;
+        case 'error':
+            icon = (0, utils_1.colorize)('[✗]', 'red');
+            message = `${provider}:${reference} — error (${errorMessage})`;
+            break;
+        case 'skipped':
+            icon = (0, utils_1.colorize)('[ ]', 'dim');
+            message = `${provider}:${reference} — skipped (${errorMessage})`;
+            break;
+    }
+    console.log(`${icon} ${message}`);
+}
+async function postWebhook(url, payload) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+        throw new Error(`Webhook POST failed: ${res.status} ${res.statusText}`);
+    }
+}
+async function runReconcileCommand(args) {
+    const opts = parseOptions(args);
+    const records = await parseInput(opts.input);
+    if (records.length === 0) {
+        console.error('No records to reconcile. Provide input via stdin or --input <file>.');
+        process.exit(1);
+    }
+    const { results, summary } = await (0, reconcile_1.runReconcile)(records, { buildProvider, hasCredsFor }, {
+        onResult: opts.json ? undefined : printResult,
+    });
+    if (opts.json) {
+        for (const result of results) {
+            console.log(JSON.stringify(result));
+        }
+        console.log(JSON.stringify({ summary }));
+    }
+    else {
+        console.log(`\nReconciled: ${summary.total}`);
+        console.log(`  Match: ${summary.match}`);
+        console.log(`  Mismatch (missed webhook): ${summary.mismatch}`);
+        console.log(`  Not found: ${summary.notFound}`);
+        console.log(`  Error: ${summary.error}`);
+        console.log(`  Skipped: ${summary.skipped}`);
+    }
+    if (opts.webhookUrl && summary.mismatch > 0) {
+        const mismatches = results.filter((r) => r.classification === 'mismatch');
+        const payload = {
+            totalReconciled: summary.total,
+            missed: summary.mismatch,
+            mismatches: mismatches.map((r) => ({
+                provider: r.provider,
+                reference: r.reference,
+                expected: r.expectedStatus,
+                actual: r.actualStatus,
+            })),
+            libVersion: '0.11.0',
+        };
+        try {
+            await postWebhook(opts.webhookUrl, payload);
+            if (!opts.json) {
+                console.log(`\n${(0, utils_1.colorize)('[webhook]', 'cyan')} Posted mismatch report to ${opts.webhookUrl}`);
+            }
+        }
+        catch (err) {
+            console.error(`${(0, utils_1.colorize)('[!]', 'yellow')} Webhook POST failed: ${err.message}`);
+        }
+    }
+    if (summary.mismatch > 0) {
+        process.exit(1);
+    }
+    else if (summary.error > 0 && summary.match === 0) {
+        process.exit(2);
+    }
+    else {
+        process.exit(0);
+    }
+}

package/dist/cli/index.js

@@ -7,6 +7,7 @@ const webhook_1 = require("./commands/webhook");
 const quote_1 = require("./commands/quote");
 const drift_1 = require("./commands/drift");
 const drift_watch_1 = require("./commands/drift-watch");
+const reconcile_1 = require("./commands/reconcile");
 const utils_1 = require("./utils");
 async function main() {
     const [, , command, ...args] = process.argv;
@@ -29,6 +30,9 @@ async function main() {
         case 'drift-watch':
             await (0, drift_watch_1.runDriftWatch)(args);
             break;
+        case 'reconcile':
+            await (0, reconcile_1.runReconcileCommand)(args);
+            break;
         case '-h':
         case '--help':
         case 'help':

package/dist/cli/reconcile-types.d.ts

@@ -0,0 +1,22 @@
+export type CanonicalStatus = 'completed' | 'pending' | 'failed' | 'cancelled' | 'refunded' | 'unknown';
+export interface ReconcileRecord {
+    provider: string;
+    reference: string;
+    expectedStatus: CanonicalStatus | string;
+}
+export interface ReconcileResult {
+    provider: string;
+    reference: string;
+    expectedStatus: string;
+    actualStatus?: string;
+    classification: 'match' | 'mismatch' | 'not-found' | 'error' | 'skipped';
+    errorMessage?: string;
+}
+export interface ReconcileSummary {
+    total: number;
+    match: number;
+    mismatch: number;
+    notFound: number;
+    error: number;
+    skipped: number;
+}

package/dist/cli/reconcile-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli/reconcile.d.ts

@@ -0,0 +1,12 @@
+import { PayBridge } from '../index';
+import { ReconcileRecord, ReconcileResult, ReconcileSummary } from './reconcile-types';
+export interface ReconcileDeps {
+    buildProvider: (providerName: string) => PayBridge;
+    hasCredsFor: (providerName: string) => boolean;
+}
+export declare function runReconcile(records: ReconcileRecord[], deps: ReconcileDeps, opts?: {
+    onResult?: (r: ReconcileResult) => void;
+}): Promise<{
+    results: ReconcileResult[];
+    summary: ReconcileSummary;
+}>;

package/dist/cli/reconcile.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReconcile = runReconcile;
+async function runReconcile(records, deps, opts = {}) {
+    const providerCache = new Map();
+    const results = [];
+    const summary = {
+        total: records.length,
+        match: 0,
+        mismatch: 0,
+        notFound: 0,
+        error: 0,
+        skipped: 0,
+    };
+    for (const record of records) {
+        if (!deps.hasCredsFor(record.provider)) {
+            const result = {
+                provider: record.provider,
+                reference: record.reference,
+                expectedStatus: record.expectedStatus,
+                classification: 'skipped',
+                errorMessage: 'missing credentials',
+            };
+            results.push(result);
+            summary.skipped++;
+            opts.onResult?.(result);
+            continue;
+        }
+        let pay;
+        if (providerCache.has(record.provider)) {
+            pay = providerCache.get(record.provider);
+        }
+        else {
+            try {
+                pay = deps.buildProvider(record.provider);
+                providerCache.set(record.provider, pay);
+            }
+            catch (err) {
+                const result = {
+                    provider: record.provider,
+                    reference: record.reference,
+                    expectedStatus: record.expectedStatus,
+                    classification: 'error',
+                    errorMessage: err.message || String(err),
+                };
+                results.push(result);
+                summary.error++;
+                opts.onResult?.(result);
+                continue;
+            }
+        }
+        try {
+            const payment = await pay.getPayment(record.reference);
+            const actualStatus = payment.status;
+            const normalized = normalizeStatus(record.expectedStatus);
+            const match = normalized === actualStatus;
+            const result = {
+                provider: record.provider,
+                reference: record.reference,
+                expectedStatus: record.expectedStatus,
+                actualStatus,
+                classification: match ? 'match' : 'mismatch',
+            };
+            results.push(result);
+            if (match) {
+                summary.match++;
+            }
+            else {
+                summary.mismatch++;
+            }
+            opts.onResult?.(result);
+        }
+        catch (err) {
+            const isNotFound = err.message?.includes('not found') ||
+                err.message?.includes('404') ||
+                err.message?.includes('No payment found');
+            const result = {
+                provider: record.provider,
+                reference: record.reference,
+                expectedStatus: record.expectedStatus,
+                classification: isNotFound ? 'not-found' : 'error',
+                errorMessage: err.message || String(err),
+            };
+            results.push(result);
+            if (isNotFound) {
+                summary.notFound++;
+            }
+            else {
+                summary.error++;
+            }
+            opts.onResult?.(result);
+        }
+    }
+    return { results, summary };
+}
+function normalizeStatus(status) {
+    const lower = status.toLowerCase();
+    if (['completed', 'pending', 'failed', 'cancelled', 'refunded'].includes(lower)) {
+        return lower;
+    }
+    return 'unknown';
+}

package/dist/cli/utils.js

@@ -72,6 +72,7 @@ COMMANDS
   quote <p> [opts]        Get a crypto on/off-ramp quote
   drift-check [opts]      Capture/compare provider response shapes (drift detection)
   drift-watch [opts]      Run drift-check on a loop (long-running monitor)
+  reconcile [opts]        Reconcile your DB against provider state (detects missed webhooks)
   help, -h, --help        Print this help
   version, -v             Print version
 
@@ -96,6 +97,8 @@ EXAMPLES
   paybridge drift-check --capture
   paybridge drift-check stripe
   paybridge drift-watch --interval 1h --webhook-url https://hooks.slack.com/...
+  paybridge reconcile --input expected.jsonl
+  psql -t -c "SELECT provider, reference, status FROM payments" | paybridge reconcile
 
 Docs: https://github.com/kobie3717/paybridge
 `.trim();

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export * from './tracer';
 export { createRedisCircuitBreakerStore, type RedisLike, type RedisStoreOptions } from './stores/redis';
 export { createRedisIdempotencyStore, type RedisIdempotencyStoreOptions } from './stores/redis-idempotency';
 export { createRedisLedgerStore, type RedisLedgerStoreOptions } from './stores/redis-ledger';
+export { runReconcile, type ReconcileDeps } from './cli/reconcile';
+export * from './cli/reconcile-types';
 export declare class PayBridge {
     readonly provider: PaymentProvider;
     constructor(config: PayBridgeConfig);

package/dist/index.js

@@ -20,7 +20,7 @@ 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 = exports.createRedisLedgerStore = exports.createRedisIdempotencyStore = exports.createRedisCircuitBreakerStore = void 0;
+exports.PayBridge = exports.runReconcile = exports.createRedisLedgerStore = exports.createRedisIdempotencyStore = exports.createRedisCircuitBreakerStore = void 0;
 const softycomp_1 = require("./providers/softycomp");
 const yoco_1 = require("./providers/yoco");
 const ozow_1 = require("./providers/ozow");
@@ -54,6 +54,9 @@ var redis_idempotency_1 = require("./stores/redis-idempotency");
 Object.defineProperty(exports, "createRedisIdempotencyStore", { enumerable: true, get: function () { return redis_idempotency_1.createRedisIdempotencyStore; } });
 var redis_ledger_1 = require("./stores/redis-ledger");
 Object.defineProperty(exports, "createRedisLedgerStore", { enumerable: true, get: function () { return redis_ledger_1.createRedisLedgerStore; } });
+var reconcile_1 = require("./cli/reconcile");
+Object.defineProperty(exports, "runReconcile", { enumerable: true, get: function () { return reconcile_1.runReconcile; } });
+__exportStar(require("./cli/reconcile-types"), exports);
 class PayBridge {
     constructor(config) {
         this.provider = this.createProvider(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paybridge",
-  "version": "0.10.0",
+  "version": "0.11.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",