paybridge 0.9.0 → 0.11.0

package/README.md

@@ -61,6 +61,86 @@ Runnable integrations for common Node.js frameworks:
 
 Each example uses `PayBridgeRouter` with Stripe + PayStack and demonstrates webhook signature verification, idempotency, and provider-specific routing.
 
+## Drift Detection
+
+Payment providers change their APIs without notice. A field gets renamed, an endpoint moves, a type changes from `string` to `number`. Your integration silently breaks.
+
+PayBridge includes **drift detection** — capture the shape of every provider's sandbox response, store it as a baseline, and get alerted the moment something changes.
+
+### Quick Start
+
+```bash
+# Capture baselines (one-time setup)
+npx paybridge drift-check --capture
+
+# Check for drift
+npx paybridge drift-check
+
+# Watch continuously (6-hour interval)
+npx paybridge drift-watch --interval 6h --webhook-url https://hooks.slack.com/...
+```
+
+### Example Output
+
+```
+=== Drift Detection ===
+
+[✓] stripe — no drift
+[⚠] mollie — drift detected:
+    + new keys: data.expiresAt, _links.dashboard.href
+    - removed keys: data.metadata.legacy
+    ! type changed: data.amount.value (string → number)
+[⚠] square — drift detected:
+    + new keys: payment_link.created_at_iso
+[ ] paystack — Missing: PAYSTACK_API_KEY
+```
+
+Exit code 1 if drift detected, 0 if clean. Perfect for CI/CD pipelines or cron jobs.
+
+### Why It Matters
+
+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/drift-watch.d.ts

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

package/dist/cli/commands/drift-watch.js

@@ -0,0 +1,118 @@
+"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.runDriftWatch = runDriftWatch;
+const path = __importStar(require("node:path"));
+const runners_1 = require("../runners");
+const drift_store_1 = require("../drift-store");
+const drift_1 = require("./drift");
+const utils_1 = require("../utils");
+const INTERVALS = {
+    '30m': 30 * 60 * 1000,
+    '1h': 60 * 60 * 1000,
+    '6h': 6 * 60 * 60 * 1000,
+    '12h': 12 * 60 * 60 * 1000,
+    '24h': 24 * 60 * 60 * 1000,
+};
+function parseInterval(str) {
+    const interval = INTERVALS[str];
+    if (!interval) {
+        throw new Error(`Invalid interval: ${str}. Supported: ${Object.keys(INTERVALS).join(', ')}`);
+    }
+    return interval;
+}
+async function runDriftWatch(args) {
+    const intervalArg = args.find((a, i) => args[i - 1] === '--interval') || '6h';
+    const interval = parseInterval(intervalArg);
+    const once = args.includes('--once');
+    const webhookUrl = args.find((a, i) => args[i - 1] === '--webhook-url');
+    const baselineDir = args.find((a, i) => args[i - 1] === '--baseline-dir') ||
+        path.join(process.cwd(), '.paybridge', 'drift-baseline');
+    const store = new drift_store_1.FileDriftStore(baselineDir);
+    let running = true;
+    const cleanup = () => {
+        running = false;
+        console.log('\nStopping drift watch...');
+        process.exit(0);
+    };
+    process.on('SIGTERM', cleanup);
+    process.on('SIGINT', cleanup);
+    const runCheck = async () => {
+        const timestamp = new Date().toISOString();
+        console.log(`\n${(0, utils_1.colorize)('[drift-watch]', 'cyan')} Running check at ${timestamp}\n`);
+        try {
+            const results = await (0, drift_1.runDriftCheck)(runners_1.runners, store, { webhookUrl });
+            const driftCount = results.filter((r) => r.status === 'drift').length;
+            const noDriftCount = results.filter((r) => r.status === 'no-drift').length;
+            const skippedCount = results.filter((r) => r.status === 'skipped').length;
+            const errorCount = results.filter((r) => r.status === 'error').length;
+            for (const res of results) {
+                if (res.status === 'drift' && res.report) {
+                    console.log(`${(0, utils_1.colorize)('[⚠]', 'yellow')} ${res.provider} — drift detected`);
+                    if (res.report.addedKeys.length > 0) {
+                        console.log(`    + new keys: ${res.report.addedKeys.join(', ')}`);
+                    }
+                    if (res.report.removedKeys.length > 0) {
+                        console.log(`    - removed keys: ${res.report.removedKeys.join(', ')}`);
+                    }
+                    if (res.report.typeChanges.length > 0) {
+                        for (const change of res.report.typeChanges) {
+                            console.log(`    ! type changed: ${change.key} (${change.oldType} → ${change.newType})`);
+                        }
+                    }
+                }
+                else if (res.status === 'error') {
+                    console.log(`${(0, utils_1.colorize)('[✗]', 'red')} ${res.provider} ERROR: ${res.message}`);
+                }
+            }
+            console.log(`\n${(0, utils_1.colorize)('[summary]', 'cyan')} drift: ${driftCount}, clean: ${noDriftCount}, skipped: ${skippedCount}, errors: ${errorCount}`);
+        }
+        catch (err) {
+            console.error(`${(0, utils_1.colorize)('[!]', 'red')} Check failed: ${err.message}`);
+        }
+    };
+    await runCheck();
+    if (once) {
+        process.exit(0);
+    }
+    console.log(`\n${(0, utils_1.colorize)('[drift-watch]', 'cyan')} Watching every ${intervalArg}. Press Ctrl+C to stop.\n`);
+    const timer = setInterval(() => {
+        if (running) {
+            runCheck();
+        }
+    }, interval);
+    timer.unref();
+    await new Promise(() => { });
+}

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

@@ -0,0 +1,20 @@
+import { ProviderRunner } from '../runners';
+import { DriftStore } from '../drift-store';
+import { DriftReport } from '../../drift-detector';
+interface DriftCheckOptions {
+    capture?: boolean;
+    baselineDir?: string;
+    json?: boolean;
+    webhookUrl?: string;
+    providers?: string[];
+}
+interface DriftCheckResult {
+    provider: string;
+    status: 'captured' | 'no-baseline' | 'no-drift' | 'drift' | 'skipped' | 'error';
+    message?: string;
+    report?: DriftReport;
+    keyCount?: number;
+}
+export declare function runDriftCheck(providedRunners: ProviderRunner[], store: DriftStore, opts: DriftCheckOptions): Promise<DriftCheckResult[]>;
+export declare function runDrift(args: string[]): Promise<void>;
+export {};

package/dist/cli/commands/drift.js

@@ -0,0 +1,212 @@
+"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.runDriftCheck = runDriftCheck;
+exports.runDrift = runDrift;
+const path = __importStar(require("node:path"));
+const runners_1 = require("../runners");
+const drift_store_1 = require("../drift-store");
+const drift_detector_1 = require("../../drift-detector");
+const utils_1 = require("../utils");
+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 runDriftCheck(providedRunners, store, opts) {
+    const libVersion = '0.10.0';
+    const results = [];
+    for (const runner of providedRunners) {
+        const missing = runner.envRequired.filter((key) => !process.env[key]);
+        if (missing.length > 0) {
+            results.push({
+                provider: runner.name,
+                status: 'skipped',
+                message: `Missing: ${missing.join(', ')}`,
+            });
+            continue;
+        }
+        try {
+            const response = await runner.run();
+            const shape = (0, drift_detector_1.captureShape)(response);
+            shape.status = response.status;
+            if (opts.capture) {
+                const baseline = {
+                    providerName: runner.name,
+                    operation: 'createPayment',
+                    shape,
+                    libVersion,
+                };
+                await store.save(baseline);
+                results.push({
+                    provider: runner.name,
+                    status: 'captured',
+                    keyCount: shape.keys.length,
+                });
+            }
+            else {
+                const baseline = await store.load(runner.name);
+                if (!baseline) {
+                    results.push({
+                        provider: runner.name,
+                        status: 'no-baseline',
+                        message: 'No baseline found (run with --capture to create)',
+                    });
+                }
+                else {
+                    const report = (0, drift_detector_1.diffBaseline)(baseline, shape, runner.name);
+                    if (report.driftDetected) {
+                        results.push({
+                            provider: runner.name,
+                            status: 'drift',
+                            report,
+                        });
+                        if (opts.webhookUrl) {
+                            try {
+                                await postWebhook(opts.webhookUrl, { provider: runner.name, drift: report, libVersion });
+                            }
+                            catch (err) {
+                                console.error(`${(0, utils_1.colorize)('[!]', 'yellow')} ${runner.name} webhook failed: ${err.message}`);
+                            }
+                        }
+                    }
+                    else {
+                        results.push({
+                            provider: runner.name,
+                            status: 'no-drift',
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            results.push({
+                provider: runner.name,
+                status: 'error',
+                message: error.message || String(error),
+            });
+        }
+    }
+    return results;
+}
+async function runDrift(args) {
+    const capture = args.includes('--capture');
+    const jsonOutput = args.includes('--json');
+    const baselineDir = args.find((a, i) => args[i - 1] === '--baseline-dir') ||
+        path.join(process.cwd(), '.paybridge', 'drift-baseline');
+    const webhookUrl = args.find((a, i) => args[i - 1] === '--webhook-url');
+    const providerNames = args.filter((a) => !a.startsWith('--') && a !== 'drift-check');
+    let selectedRunners = runners_1.runners;
+    if (providerNames.length > 0) {
+        selectedRunners = runners_1.runners.filter((r) => providerNames.includes(r.name));
+        const unknownProviders = providerNames.filter((p) => !runners_1.runners.find((r) => r.name === p));
+        if (unknownProviders.length > 0) {
+            console.error(`Unknown providers: ${unknownProviders.join(', ')}`);
+            console.error(`Available: ${runners_1.runners.map((r) => r.name).join(', ')}`);
+            process.exit(1);
+        }
+    }
+    const store = new drift_store_1.FileDriftStore(baselineDir);
+    const results = await runDriftCheck(selectedRunners, store, { capture, baselineDir, json: jsonOutput, webhookUrl });
+    if (jsonOutput) {
+        console.log(JSON.stringify(results, null, 2));
+    }
+    else {
+        if (capture) {
+            console.log('\n=== Drift Baseline Capture ===\n');
+            for (const res of results) {
+                if (res.status === 'captured') {
+                    console.log(`${(0, utils_1.colorize)('[saved]', 'green')} ${res.provider} baseline (${res.keyCount} keys)`);
+                }
+                else if (res.status === 'skipped') {
+                    console.log(`${(0, utils_1.colorize)('[ ]', 'dim')} ${res.provider} — ${res.message}`);
+                }
+                else if (res.status === 'error') {
+                    console.log(`${(0, utils_1.colorize)('[✗]', 'red')} ${res.provider} ERROR: ${res.message}`);
+                }
+            }
+        }
+        else {
+            console.log('\n=== Drift Detection ===\n');
+            for (const res of results) {
+                if (res.status === 'no-drift') {
+                    console.log(`${(0, utils_1.colorize)('[✓]', 'green')} ${res.provider} — no drift`);
+                }
+                else if (res.status === 'no-baseline') {
+                    console.log(`${(0, utils_1.colorize)('[ ]', 'dim')} ${res.provider} — ${res.message}`);
+                }
+                else if (res.status === 'skipped') {
+                    console.log(`${(0, utils_1.colorize)('[ ]', 'dim')} ${res.provider} — ${res.message}`);
+                }
+                else if (res.status === 'drift' && res.report) {
+                    console.log(`${(0, utils_1.colorize)('[⚠]', 'yellow')} ${res.provider} — drift detected:`);
+                    if (res.report.addedKeys.length > 0) {
+                        console.log(`    ${(0, utils_1.colorize)('+', 'green')} new keys: ${res.report.addedKeys.join(', ')}`);
+                    }
+                    if (res.report.removedKeys.length > 0) {
+                        console.log(`    ${(0, utils_1.colorize)('-', 'red')} removed keys: ${res.report.removedKeys.join(', ')}`);
+                    }
+                    if (res.report.typeChanges.length > 0) {
+                        for (const change of res.report.typeChanges) {
+                            console.log(`    ${(0, utils_1.colorize)('!', 'yellow')} type changed: ${change.key} (${change.oldType} → ${change.newType})`);
+                        }
+                    }
+                    if (res.report.statusChanged) {
+                        console.log(`    ${(0, utils_1.colorize)('!', 'yellow')} status changed: ${res.report.statusChanged.old} → ${res.report.statusChanged.new}`);
+                    }
+                }
+                else if (res.status === 'error') {
+                    console.log(`${(0, utils_1.colorize)('[✗]', 'red')} ${res.provider} ERROR: ${res.message}`);
+                }
+            }
+        }
+    }
+    const driftCount = results.filter((r) => r.status === 'drift').length;
+    const errorCount = results.filter((r) => r.status === 'error').length;
+    if (errorCount > 0) {
+        process.exit(2);
+    }
+    else if (driftCount > 0) {
+        process.exit(1);
+    }
+    else {
+        process.exit(0);
+    }
+}

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

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