paybridge 0.11.0 → 0.12.0

package/README.md

@@ -141,6 +141,65 @@ Reconciled: 5
 
 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.
 
+## Postgres Ledger
+
+The ledger stores every payment attempt and outcome. In-memory and Redis adapters are ephemeral. For durable transaction history, use the Postgres adapter.
+
+### Schema Setup
+
+Create the table once via your migration tool:
+
+```typescript
+import { getPostgresLedgerTableSql } from 'paybridge';
+
+const sql = getPostgresLedgerTableSql();
+await pool.query(sql);
+```
+
+Or run the SQL manually:
+
+```sql
+CREATE TABLE paybridge_ledger (
+  id TEXT PRIMARY KEY,
+  timestamp TIMESTAMPTZ NOT NULL,
+  operation TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  reference TEXT,
+  provider_id TEXT,
+  status TEXT NOT NULL,
+  amount NUMERIC,
+  currency TEXT,
+  duration_ms INTEGER,
+  error_code TEXT,
+  error_message TEXT,
+  metadata JSONB
+);
+
+CREATE INDEX idx_paybridge_ledger_provider_timestamp
+  ON paybridge_ledger (provider, timestamp DESC);
+CREATE INDEX idx_paybridge_ledger_reference
+  ON paybridge_ledger (reference) WHERE reference IS NOT NULL;
+CREATE INDEX idx_paybridge_ledger_status
+  ON paybridge_ledger (status);
+```
+
+### Usage
+
+```typescript
+import { Pool } from 'pg';
+import { PayBridgeRouter, createPostgresLedgerStore } from 'paybridge';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const ledger = createPostgresLedgerStore({ pool });
+
+const router = new PayBridgeRouter({
+  providers: [...],
+  ledger,
+});
+```
+
+Compatible with `pg` (`Pool`) and `postgres` (porsager) adapter wrappers. No runtime dep on `pg` — bring your own client.
+
 ## Quick Start
 
 > **Upgrading from 0.1 or 0.2?** See [docs/migration.md](docs/migration.md).
@@ -612,6 +671,34 @@ const router = new PayBridgeRouter({
 
 The Redis adapter works with both `ioredis` and `redis` (node-redis v4+) clients. State is eventually consistent across instances — race conditions during state transitions may cause a few extra failures, but correctness is preserved.
 
+### Intelligent routing — successRate strategy
+
+Static fee tables lie. PayBridge routes by actual outcomes when you give it ledger access:
+
+```typescript
+import { PayBridgeRouter, createSuccessRateStrategy, createPostgresLedgerStore } from 'paybridge';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const ledger = createPostgresLedgerStore({ pool });
+
+const strategy = createSuccessRateStrategy({
+  ledger,
+  windowMs: 24 * 60 * 60 * 1000,
+  fallback: 'cheapest',
+});
+
+const router = new PayBridgeRouter({
+  providers: [...],
+  strategy,
+  ledger,
+});
+```
+
+Providers are ranked by their real success rate from your own traffic. Below the minimum sample size, the configured fallback (default `cheapest`) takes over.
+
+**Why this matters**: A provider with 1.4% fee but 92% success rate costs more per successful transaction than a 2.5% / 99.5% provider. `successRate` makes routing decisions based on real outcomes from your traffic, not static fee tables.
+
 ## Currency Handling
 
 PayBridge **always uses major currency units** (rands, dollars) in the API:

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 { createPostgresLedgerStore, type PostgresLedgerStoreOptions, getCreateTableSql as getPostgresLedgerTableSql } from './stores/postgres-ledger';
+export type { PgPoolLike, PgQueryResult } from './stores/postgres';
 export { runReconcile, type ReconcileDeps } from './cli/reconcile';
 export * from './cli/reconcile-types';
 export declare class PayBridge {

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.runReconcile = exports.createRedisLedgerStore = exports.createRedisIdempotencyStore = exports.createRedisCircuitBreakerStore = void 0;
+exports.PayBridge = exports.runReconcile = exports.getPostgresLedgerTableSql = exports.createPostgresLedgerStore = 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 postgres_ledger_1 = require("./stores/postgres-ledger");
+Object.defineProperty(exports, "createPostgresLedgerStore", { enumerable: true, get: function () { return postgres_ledger_1.createPostgresLedgerStore; } });
+Object.defineProperty(exports, "getPostgresLedgerTableSql", { enumerable: true, get: function () { return postgres_ledger_1.getCreateTableSql; } });
 var reconcile_1 = require("./cli/reconcile");
 Object.defineProperty(exports, "runReconcile", { enumerable: true, get: function () { return reconcile_1.runReconcile; } });
 __exportStar(require("./cli/reconcile-types"), exports);

package/dist/router.d.ts

@@ -4,6 +4,7 @@
 import { PayBridge } from './index';
 import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent, Provider } from './types';
 import { RoutingStrategy, FallbackConfig } from './routing-types';
+import { type SuccessRateStrategy } from './strategies';
 import type { IdempotencyStore } from './webhook-idempotency-store';
 import { RouterEventEmitter } from './router-events';
 import type { LedgerStore } from './ledger';
@@ -20,7 +21,7 @@ export interface PayBridgeRouterConfig {
         weight?: number;
         priority?: number;
     }>;
-    strategy?: RoutingStrategy;
+    strategy?: RoutingStrategy | SuccessRateStrategy;
     fallback?: FallbackConfig;
     circuitBreakerStore?: import('./circuit-breaker-store').CircuitBreakerStore;
     idempotencyStore?: IdempotencyStore;

package/dist/router.js

@@ -88,12 +88,18 @@ class PayBridgeRouter {
         if (filtered.length === 0) {
             throw new Error(`No providers support currency ${params.currency} with amount ${params.amount}`);
         }
-        const strategyFn = (0, strategies_1.getStrategy)(this.strategy);
-        const ordered = strategyFn(filtered, context, () => {
-            const idx = this.rrIndex;
-            this.rrIndex = (this.rrIndex + 1) % filtered.length;
-            return idx;
-        });
+        let ordered;
+        if (typeof this.strategy === 'string') {
+            const strategyFn = (0, strategies_1.getStrategy)(this.strategy);
+            ordered = strategyFn(filtered, context, () => {
+                const idx = this.rrIndex;
+                this.rrIndex = (this.rrIndex + 1) % filtered.length;
+                return idx;
+            });
+        }
+        else {
+            ordered = await this.strategy.order(filtered);
+        }
         const attempts = [];
         let lastError = null;
         for (const providerMeta of ordered) {
@@ -111,7 +117,7 @@ class PayBridgeRouter {
             const startTime = Date.now();
             const span = this.tracer.startSpan('paybridge.router.createPayment', {
                 'paybridge.provider': providerName,
-                'paybridge.strategy': this.strategy,
+                'paybridge.strategy': typeof this.strategy === 'string' ? this.strategy : 'successRate',
                 'paybridge.attempt': attempts.length + 1,
             });
             this.events.emitEvent({
@@ -166,7 +172,7 @@ class PayBridgeRouter {
                 const routingMeta = {
                     attempts,
                     chosenProvider: providerName,
-                    strategy: this.strategy,
+                    strategy: typeof this.strategy === 'string' ? this.strategy : 'successRate',
                 };
                 span.end();
                 return {
@@ -283,12 +289,18 @@ class PayBridgeRouter {
         if (filtered.length === 0) {
             throw new Error(`No providers support currency ${params.currency} with amount ${params.amount}`);
         }
-        const strategyFn = (0, strategies_1.getStrategy)(this.strategy);
-        const ordered = strategyFn(filtered, context, () => {
-            const idx = this.rrIndex;
-            this.rrIndex = (this.rrIndex + 1) % filtered.length;
-            return idx;
-        });
+        let ordered;
+        if (typeof this.strategy === 'string') {
+            const strategyFn = (0, strategies_1.getStrategy)(this.strategy);
+            ordered = strategyFn(filtered, context, () => {
+                const idx = this.rrIndex;
+                this.rrIndex = (this.rrIndex + 1) % filtered.length;
+                return idx;
+            });
+        }
+        else {
+            ordered = await this.strategy.order(filtered);
+        }
         const attempts = [];
         let lastError = null;
         for (const providerMeta of ordered) {

package/dist/routing-types.d.ts

@@ -25,7 +25,7 @@ export interface RoutingAttempt {
 export interface RoutingMeta {
     attempts: RoutingAttempt[];
     chosenProvider: string;
-    strategy: RoutingStrategy;
+    strategy: RoutingStrategy | 'successRate';
 }
 export type RoutingStrategy = 'cheapest' | 'fastest' | 'priority' | 'round-robin';
 export interface FallbackConfig {

package/dist/stores/postgres-ledger.d.ts

@@ -0,0 +1,9 @@
+import type { LedgerStore } from '../ledger';
+import type { PgPoolLike } from './postgres';
+export interface PostgresLedgerStoreOptions {
+    pool: PgPoolLike;
+    tableName?: string;
+    schema?: string;
+}
+export declare function getCreateTableSql(tableName?: string, schema?: string): string;
+export declare function createPostgresLedgerStore(opts: PostgresLedgerStoreOptions): LedgerStore;

package/dist/stores/postgres-ledger.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCreateTableSql = getCreateTableSql;
+exports.createPostgresLedgerStore = createPostgresLedgerStore;
+function getCreateTableSql(tableName = 'paybridge_ledger', schema = 'public') {
+    const fullTableName = `${schema}.${tableName}`;
+    return `CREATE TABLE ${fullTableName} (
+  id TEXT PRIMARY KEY,
+  timestamp TIMESTAMPTZ NOT NULL,
+  operation TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  reference TEXT,
+  provider_id TEXT,
+  status TEXT NOT NULL,
+  amount NUMERIC,
+  currency TEXT,
+  duration_ms INTEGER,
+  error_code TEXT,
+  error_message TEXT,
+  metadata JSONB
+);
+
+CREATE INDEX idx_${tableName}_provider_timestamp
+  ON ${fullTableName} (provider, timestamp DESC);
+
+CREATE INDEX idx_${tableName}_reference
+  ON ${fullTableName} (reference) WHERE reference IS NOT NULL;
+
+CREATE INDEX idx_${tableName}_status
+  ON ${fullTableName} (status);`;
+}
+function createPostgresLedgerStore(opts) {
+    const tableName = opts.tableName ?? 'paybridge_ledger';
+    const schema = opts.schema ?? 'public';
+    const fullTableName = `${schema}.${tableName}`;
+    return {
+        async append(entry) {
+            const sql = `INSERT INTO ${fullTableName} (
+        id, timestamp, operation, provider, reference, provider_id,
+        status, amount, currency, duration_ms, error_code, error_message, metadata
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)`;
+            const params = [
+                entry.id,
+                entry.timestamp,
+                entry.operation,
+                entry.provider,
+                entry.reference ?? null,
+                entry.providerId ?? null,
+                entry.status,
+                entry.amount ?? null,
+                entry.currency ?? null,
+                entry.durationMs ?? null,
+                entry.errorCode ?? null,
+                entry.errorMessage ?? null,
+                entry.metadata ? JSON.stringify(entry.metadata) : null,
+            ];
+            await opts.pool.query(sql, params);
+        },
+        async query(filter) {
+            const whereClauses = [];
+            const params = [];
+            let paramIndex = 1;
+            if (filter.reference !== undefined) {
+                whereClauses.push(`reference = $${paramIndex++}`);
+                params.push(filter.reference);
+            }
+            if (filter.provider !== undefined) {
+                whereClauses.push(`provider = $${paramIndex++}`);
+                params.push(filter.provider);
+            }
+            if (filter.status !== undefined) {
+                whereClauses.push(`status = $${paramIndex++}`);
+                params.push(filter.status);
+            }
+            if (filter.fromTimestamp !== undefined) {
+                whereClauses.push(`timestamp >= $${paramIndex++}`);
+                params.push(filter.fromTimestamp);
+            }
+            if (filter.toTimestamp !== undefined) {
+                whereClauses.push(`timestamp <= $${paramIndex++}`);
+                params.push(filter.toTimestamp);
+            }
+            const whereClause = whereClauses.length > 0 ? 'WHERE ' + whereClauses.join(' AND ') : '';
+            const limitClause = filter.limit !== undefined ? `LIMIT $${paramIndex++}` : '';
+            if (filter.limit !== undefined) {
+                params.push(filter.limit);
+            }
+            const sql = `SELECT
+        id, timestamp, operation, provider, reference, provider_id,
+        status, amount, currency, duration_ms, error_code, error_message, metadata
+      FROM ${fullTableName}
+      ${whereClause}
+      ORDER BY timestamp DESC
+      ${limitClause}`.trim();
+            const result = await opts.pool.query(sql, params);
+            return result.rows.map(row => ({
+                id: row.id,
+                timestamp: row.timestamp,
+                operation: row.operation,
+                provider: row.provider,
+                reference: row.reference ?? undefined,
+                providerId: row.provider_id ?? undefined,
+                status: row.status,
+                amount: row.amount !== null ? parseFloat(row.amount) : undefined,
+                currency: row.currency ?? undefined,
+                durationMs: row.duration_ms ?? undefined,
+                errorCode: row.error_code ?? undefined,
+                errorMessage: row.error_message ?? undefined,
+                metadata: row.metadata ?? undefined,
+            }));
+        },
+    };
+}

package/dist/stores/postgres.d.ts

@@ -0,0 +1,7 @@
+export interface PgQueryResult<T = any> {
+    rows: T[];
+    rowCount: number | null;
+}
+export interface PgPoolLike {
+    query<T = any>(sql: string, params?: unknown[]): Promise<PgQueryResult<T>>;
+}

package/dist/stores/postgres.js

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

package/dist/strategies.d.ts

@@ -4,6 +4,7 @@
 import { PayBridge } from './index';
 import { Currency } from './types';
 import { RoutingStrategy } from './routing-types';
+import type { LedgerStore } from './ledger';
 export interface ProviderWithMeta {
     instance: PayBridge;
     weight?: number;
@@ -16,3 +17,19 @@ export interface StrategyContext {
 export type Strategy = (providers: ProviderWithMeta[], context: StrategyContext, getRRIndex?: () => number) => ProviderWithMeta[];
 export declare const strategies: Record<RoutingStrategy, Strategy>;
 export declare function getStrategy(name: RoutingStrategy): Strategy;
+export interface SuccessRateStrategyOptions {
+    ledger: LedgerStore;
+    windowMs?: number;
+    cacheTtlMs?: number;
+    minSampleSize?: number;
+    fallback?: 'cheapest' | 'fastest' | 'priority' | 'round-robin';
+}
+export interface SuccessRateStrategy {
+    order: (providers: ProviderWithMeta[]) => Promise<ProviderWithMeta[]>;
+    refresh: () => Promise<void>;
+    getRates: () => Map<string, {
+        successRate: number;
+        sampleSize: number;
+    }>;
+}
+export declare function createSuccessRateStrategy(opts: SuccessRateStrategyOptions): SuccessRateStrategy;

package/dist/strategies.js

@@ -5,6 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.strategies = void 0;
 exports.getStrategy = getStrategy;
+exports.createSuccessRateStrategy = createSuccessRateStrategy;
 exports.strategies = {
     cheapest: (providers, context) => {
         return [...providers].sort((a, b) => {
@@ -42,3 +43,72 @@ exports.strategies = {
 function getStrategy(name) {
     return exports.strategies[name];
 }
+function createSuccessRateStrategy(opts) {
+    const windowMs = opts.windowMs ?? 24 * 60 * 60 * 1000;
+    const cacheTtlMs = opts.cacheTtlMs ?? 60 * 1000;
+    const minSampleSize = opts.minSampleSize ?? 10;
+    const fallbackName = opts.fallback ?? 'cheapest';
+    const fallbackStrategy = exports.strategies[fallbackName];
+    let cachedRates = new Map();
+    let lastRefreshTime = 0;
+    async function computeRates() {
+        const now = Date.now();
+        const fromTimestamp = new Date(now - windowMs).toISOString();
+        const entries = await opts.ledger.query({
+            fromTimestamp,
+        });
+        const providerStats = new Map();
+        for (const entry of entries) {
+            if (!providerStats.has(entry.provider)) {
+                providerStats.set(entry.provider, { total: 0, success: 0 });
+            }
+            const stats = providerStats.get(entry.provider);
+            stats.total++;
+            if (entry.status === 'success') {
+                stats.success++;
+            }
+        }
+        const rates = new Map();
+        for (const [provider, stats] of providerStats) {
+            rates.set(provider, {
+                successRate: stats.total > 0 ? stats.success / stats.total : 0,
+                sampleSize: stats.total,
+            });
+        }
+        return rates;
+    }
+    async function ensureFreshCache() {
+        const now = Date.now();
+        if (now - lastRefreshTime > cacheTtlMs) {
+            cachedRates = await computeRates();
+            lastRefreshTime = now;
+        }
+    }
+    return {
+        async order(providers) {
+            await ensureFreshCache();
+            const highConfidence = [];
+            const lowConfidence = [];
+            for (const provider of providers) {
+                const providerName = provider.instance.getProviderName();
+                const stats = cachedRates.get(providerName);
+                if (stats && stats.sampleSize >= minSampleSize) {
+                    highConfidence.push({ provider, rate: stats.successRate });
+                }
+                else {
+                    lowConfidence.push(provider);
+                }
+            }
+            highConfidence.sort((a, b) => b.rate - a.rate);
+            const sortedLowConfidence = fallbackStrategy(lowConfidence, { amount: 0, currency: 'USD' });
+            return [...highConfidence.map(h => h.provider), ...sortedLowConfidence];
+        },
+        async refresh() {
+            cachedRates = await computeRates();
+            lastRefreshTime = Date.now();
+        },
+        getRates() {
+            return new Map(cachedRates);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paybridge",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -49,7 +49,10 @@
     "command-line",
     "drift-detection",
     "monitoring",
-    "api-validation"
+    "api-validation",
+    "postgres",
+    "success-rate",
+    "intelligent-routing"
   ],
   "author": "Kobie Wentzel",
   "license": "MIT",