paybridge 0.3.0 → 0.4.0

package/README.md

@@ -207,7 +207,7 @@ app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
 **Notes:**
 - `⛔` marks features the underlying provider's API doesn't support — those methods throw a clear error explaining the limitation. Use a different provider for that capability or use `PayBridgeRouter` to route accordingly.
 - **Yellow Card** is gated behind `@experimental` until partner API documentation is verified — it logs a warning on instantiation. Do not use in production without partner-confirmed spec.
-- **Sandbox testing.** PayFast / PayStack / Stripe / Peach / Flutterwave are wired and unit-tested, but have not yet been validated against live sandbox credentials. Run a sandbox transaction before going live.
+- **Sandbox testing.** PayFast / PayStack / Stripe / Peach / Flutterwave are wired and unit-tested, but have not yet been validated against live sandbox credentials. To validate against real sandboxes, set the relevant `*_API_KEY` env vars and run `npm run test:e2e:sandbox`.
 
 ## Provider Configuration
 

package/dist/circuit-breaker.d.ts

@@ -3,6 +3,7 @@
  * Supports pluggable storage for multi-instance deployments.
  * Not atomic across processes — eventual consistency accepted.
  */
+import { EventEmitter } from 'node:events';
 import { CircuitBreakerStore } from './circuit-breaker-store';
 export declare enum CircuitState {
     CLOSED = "CLOSED",
@@ -15,6 +16,7 @@ export interface CircuitBreakerConfig {
     store?: CircuitBreakerStore;
 }
 export declare class CircuitBreaker {
+    readonly events: EventEmitter<any>;
     private readonly key;
     private readonly failureThreshold;
     private readonly resetTimeoutMs;

package/dist/circuit-breaker.js

@@ -6,6 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CircuitBreaker = exports.CircuitState = void 0;
+const node_events_1 = require("node:events");
 const circuit_breaker_store_1 = require("./circuit-breaker-store");
 var CircuitState;
 (function (CircuitState) {
@@ -15,6 +16,7 @@ var CircuitState;
 })(CircuitState || (exports.CircuitState = CircuitState = {}));
 class CircuitBreaker {
     constructor(key = 'default', config = {}) {
+        this.events = new node_events_1.EventEmitter();
         this.key = key;
         this.failureThreshold = config.failureThreshold ?? 5;
         this.resetTimeoutMs = config.resetTimeoutMs ?? 30000;
@@ -26,6 +28,7 @@ class CircuitBreaker {
             if (Date.now() >= snapshot.nextAttemptTime) {
                 snapshot.state = CircuitState.HALF_OPEN;
                 await this.saveSnapshot(snapshot);
+                this.events.emit('half_opened', this.key);
                 return false;
             }
             return true;
@@ -33,12 +36,16 @@ class CircuitBreaker {
         return false;
     }
     async recordSuccess() {
+        const prevSnapshot = await this.getSnapshot();
         const snapshot = {
             state: CircuitState.CLOSED,
             failureCount: 0,
             nextAttemptTime: 0,
         };
         await this.saveSnapshot(snapshot);
+        if (prevSnapshot.state !== CircuitState.CLOSED) {
+            this.events.emit('closed', this.key);
+        }
     }
     async recordFailure() {
         const snapshot = await this.getSnapshot();
@@ -47,11 +54,13 @@ class CircuitBreaker {
             snapshot.state = CircuitState.OPEN;
             snapshot.nextAttemptTime = Date.now() + this.resetTimeoutMs;
             await this.saveSnapshot(snapshot, this.resetTimeoutMs + 5000);
+            this.events.emit('opened', this.key);
         }
         else if (snapshot.failureCount >= this.failureThreshold) {
             snapshot.state = CircuitState.OPEN;
             snapshot.nextAttemptTime = Date.now() + this.resetTimeoutMs;
             await this.saveSnapshot(snapshot, this.resetTimeoutMs + 5000);
+            this.events.emit('opened', this.key);
         }
         else {
             await this.saveSnapshot(snapshot);

package/dist/crypto/router.d.ts

@@ -3,6 +3,9 @@
  */
 import { CryptoRamp } from './index';
 import { OnRampParams, OffRampParams, RampQuote, RampResult } from './types';
+import { RouterEventEmitter } from '../router-events';
+import type { LedgerStore } from '../ledger';
+import type { TracerLike } from '../tracer';
 export interface CryptoRampRouterConfig {
     providers: Array<{
         provider: CryptoRamp;
@@ -17,13 +20,18 @@ export interface CryptoRampRouterConfig {
     allowExperimental?: boolean;
     circuitBreakerStore?: import('../circuit-breaker-store').CircuitBreakerStore;
     idempotencyStore?: import('../webhook-idempotency-store').IdempotencyStore;
+    ledger?: LedgerStore;
+    tracer?: TracerLike;
 }
 export declare class CryptoRampRouter {
+    readonly events: RouterEventEmitter;
     private providers;
     private strategy;
     private fallback;
     private allowExperimental;
     private circuitBreakers;
+    private ledger?;
+    private tracer;
     private rrIndex;
     private config;
     constructor(config: CryptoRampRouterConfig);
@@ -34,4 +42,5 @@ export declare class CryptoRampRouter {
     private filterProviders;
     private orderProviders;
     private sleep;
+    private recordLedgerEntry;
 }

package/dist/crypto/router.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CryptoRampRouter = void 0;
 const routing_types_1 = require("../routing-types");
 const circuit_breaker_1 = require("../circuit-breaker");
+const router_events_1 = require("../router-events");
+const tracer_1 = require("../tracer");
 function sanitizeErrorMessage(msg) {
     if (!msg)
         return 'unknown error';
@@ -16,6 +18,7 @@ function sanitizeErrorMessage(msg) {
 }
 class CryptoRampRouter {
     constructor(config) {
+        this.events = new router_events_1.RouterEventEmitter();
         this.rrIndex = 0;
         this.config = config;
         this.providers = config.providers.map(p => ({
@@ -29,12 +32,36 @@ class CryptoRampRouter {
             retryDelayMs: config.fallback?.retryDelayMs ?? 250,
         };
         this.allowExperimental = config.allowExperimental ?? false;
+        this.ledger = config.ledger;
+        this.tracer = config.tracer ?? tracer_1.noopTracer;
         this.circuitBreakers = new Map();
         for (const p of this.providers) {
             const name = p.instance.getProviderName();
-            this.circuitBreakers.set(name, new circuit_breaker_1.CircuitBreaker(name, {
+            const breaker = new circuit_breaker_1.CircuitBreaker(name, {
                 store: config.circuitBreakerStore,
-            }));
+            });
+            breaker.events.on('opened', (key) => {
+                this.events.emitEvent({
+                    type: 'circuit.opened',
+                    provider: key,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            breaker.events.on('half_opened', (key) => {
+                this.events.emitEvent({
+                    type: 'circuit.half_opened',
+                    provider: key,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            breaker.events.on('closed', (key) => {
+                this.events.emitEvent({
+                    type: 'circuit.closed',
+                    provider: key,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            this.circuitBreakers.set(name, breaker);
         }
     }
     async getQuote(direction, fiatAmount, fiatCurrency, cryptoAsset, network) {
@@ -114,6 +141,13 @@ class CryptoRampRouter {
                 continue;
             }
             const startTime = Date.now();
+            this.events.emitEvent({
+                type: 'attempt.start',
+                provider: providerName,
+                operation: 'createOnRamp',
+                attempt: attempts.length + 1,
+                timestamp: new Date().toISOString(),
+            });
             try {
                 const result = await providerMeta.instance.createOnRamp(params);
                 const latencyMs = Date.now() - startTime;
@@ -124,6 +158,32 @@ class CryptoRampRouter {
                     status: 'success',
                     latencyMs,
                 });
+                this.events.emitEvent({
+                    type: 'attempt.success',
+                    provider: providerName,
+                    operation: 'createOnRamp',
+                    durationMs: latencyMs,
+                    attempt: attempts.length,
+                    timestamp: new Date().toISOString(),
+                });
+                this.events.emitEvent({
+                    type: 'request.success',
+                    provider: providerName,
+                    operation: 'createOnRamp',
+                    durationMs: latencyMs,
+                    timestamp: new Date().toISOString(),
+                });
+                await this.recordLedgerEntry({
+                    id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                    timestamp: new Date().toISOString(),
+                    operation: 'createOnRamp',
+                    provider: providerName,
+                    providerId: result.id,
+                    status: 'success',
+                    amount: params.fiatAmount,
+                    currency: params.fiatCurrency,
+                    durationMs: latencyMs,
+                });
                 const routingMeta = {
                     attempts,
                     chosenProvider: providerName,
@@ -146,12 +206,28 @@ class CryptoRampRouter {
                     errorMessage: sanitizeErrorMessage(error.message),
                     latencyMs,
                 });
+                this.events.emitEvent({
+                    type: 'attempt.failure',
+                    provider: providerName,
+                    operation: 'createOnRamp',
+                    durationMs: latencyMs,
+                    errorCode: error.code,
+                    errorMessage: sanitizeErrorMessage(error.message),
+                    attempt: attempts.length,
+                    timestamp: new Date().toISOString(),
+                });
                 if (!this.fallback.enabled || attempts.length >= this.fallback.maxAttempts) {
                     break;
                 }
                 await this.sleep(this.fallback.retryDelayMs);
             }
         }
+        this.events.emitEvent({
+            type: 'request.failure',
+            operation: 'createOnRamp',
+            errorMessage: lastError?.message || 'All providers failed',
+            timestamp: new Date().toISOString(),
+        });
         throw new routing_types_1.RoutingError(`All providers failed: ${lastError?.message || 'Unknown error'}`, attempts);
     }
     async createOffRamp(params) {
@@ -178,6 +254,13 @@ class CryptoRampRouter {
                 continue;
             }
             const startTime = Date.now();
+            this.events.emitEvent({
+                type: 'attempt.start',
+                provider: providerName,
+                operation: 'createOffRamp',
+                attempt: attempts.length + 1,
+                timestamp: new Date().toISOString(),
+            });
             try {
                 const result = await providerMeta.instance.createOffRamp(params);
                 const latencyMs = Date.now() - startTime;
@@ -188,6 +271,32 @@ class CryptoRampRouter {
                     status: 'success',
                     latencyMs,
                 });
+                this.events.emitEvent({
+                    type: 'attempt.success',
+                    provider: providerName,
+                    operation: 'createOffRamp',
+                    durationMs: latencyMs,
+                    attempt: attempts.length,
+                    timestamp: new Date().toISOString(),
+                });
+                this.events.emitEvent({
+                    type: 'request.success',
+                    provider: providerName,
+                    operation: 'createOffRamp',
+                    durationMs: latencyMs,
+                    timestamp: new Date().toISOString(),
+                });
+                await this.recordLedgerEntry({
+                    id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                    timestamp: new Date().toISOString(),
+                    operation: 'createOffRamp',
+                    provider: providerName,
+                    providerId: result.id,
+                    status: 'success',
+                    amount: params.cryptoAmount,
+                    currency: params.fiatCurrency,
+                    durationMs: latencyMs,
+                });
                 const routingMeta = {
                     attempts,
                     chosenProvider: providerName,
@@ -210,12 +319,28 @@ class CryptoRampRouter {
                     errorMessage: sanitizeErrorMessage(error.message),
                     latencyMs,
                 });
+                this.events.emitEvent({
+                    type: 'attempt.failure',
+                    provider: providerName,
+                    operation: 'createOffRamp',
+                    durationMs: latencyMs,
+                    errorCode: error.code,
+                    errorMessage: sanitizeErrorMessage(error.message),
+                    attempt: attempts.length,
+                    timestamp: new Date().toISOString(),
+                });
                 if (!this.fallback.enabled || attempts.length >= this.fallback.maxAttempts) {
                     break;
                 }
                 await this.sleep(this.fallback.retryDelayMs);
             }
         }
+        this.events.emitEvent({
+            type: 'request.failure',
+            operation: 'createOffRamp',
+            errorMessage: lastError?.message || 'All providers failed',
+            timestamp: new Date().toISOString(),
+        });
         throw new routing_types_1.RoutingError(`All providers failed: ${lastError?.message || 'Unknown error'}`, attempts);
     }
     async getRamp(id, provider) {
@@ -291,5 +416,21 @@ class CryptoRampRouter {
     sleep(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
+    async recordLedgerEntry(entry) {
+        if (!this.ledger)
+            return;
+        try {
+            await this.ledger.append(entry);
+        }
+        catch (err) {
+            this.events.emitEvent({
+                type: 'attempt.failure',
+                operation: entry.operation,
+                provider: entry.provider,
+                errorMessage: 'Ledger write failed',
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
 }
 exports.CryptoRampRouter = CryptoRampRouter;

package/dist/index.d.ts

@@ -16,8 +16,12 @@ export * from './strategies';
 export * from './router';
 export * from './crypto';
 export * from './webhook-idempotency-store';
+export * from './router-events';
+export * from './ledger';
+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 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.createRedisIdempotencyStore = exports.createRedisCircuitBreakerStore = void 0;
+exports.PayBridge = 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");
@@ -39,10 +39,15 @@ __exportStar(require("./strategies"), exports);
 __exportStar(require("./router"), exports);
 __exportStar(require("./crypto"), exports);
 __exportStar(require("./webhook-idempotency-store"), exports);
+__exportStar(require("./router-events"), exports);
+__exportStar(require("./ledger"), exports);
+__exportStar(require("./tracer"), exports);
 var redis_1 = require("./stores/redis");
 Object.defineProperty(exports, "createRedisCircuitBreakerStore", { enumerable: true, get: function () { return redis_1.createRedisCircuitBreakerStore; } });
 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; } });
 class PayBridge {
     constructor(config) {
         this.provider = this.createProvider(config);

package/dist/ledger.d.ts

@@ -0,0 +1,36 @@
+export interface LedgerEntry {
+    id: string;
+    timestamp: string;
+    operation: 'createPayment' | 'createSubscription' | 'getPayment' | 'refund' | 'createOnRamp' | 'createOffRamp' | 'getRamp' | 'parseWebhook';
+    provider: string;
+    reference?: string;
+    providerId?: string;
+    status: 'attempted' | 'success' | 'failed' | 'rate_limited' | 'timeout';
+    amount?: number;
+    currency?: string;
+    durationMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LedgerQuery {
+    reference?: string;
+    provider?: string;
+    status?: LedgerEntry['status'];
+    fromTimestamp?: string;
+    toTimestamp?: string;
+    limit?: number;
+}
+export interface LedgerStore {
+    append(entry: LedgerEntry): Promise<void>;
+    query(filter: LedgerQuery): Promise<LedgerEntry[]>;
+}
+export declare class InMemoryLedgerStore implements LedgerStore {
+    private entries;
+    private maxSize;
+    constructor(opts?: {
+        maxSize?: number;
+    });
+    append(entry: LedgerEntry): Promise<void>;
+    query(filter: LedgerQuery): Promise<LedgerEntry[]>;
+}

package/dist/ledger.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryLedgerStore = void 0;
+class InMemoryLedgerStore {
+    constructor(opts = {}) {
+        this.entries = [];
+        this.maxSize = opts.maxSize ?? 10000;
+    }
+    async append(entry) {
+        this.entries.push(entry);
+        if (this.entries.length > this.maxSize) {
+            this.entries.splice(0, this.entries.length - this.maxSize);
+        }
+    }
+    async query(filter) {
+        let results = this.entries;
+        if (filter.reference)
+            results = results.filter(e => e.reference === filter.reference);
+        if (filter.provider)
+            results = results.filter(e => e.provider === filter.provider);
+        if (filter.status)
+            results = results.filter(e => e.status === filter.status);
+        if (filter.fromTimestamp)
+            results = results.filter(e => e.timestamp >= filter.fromTimestamp);
+        if (filter.toTimestamp)
+            results = results.filter(e => e.timestamp <= filter.toTimestamp);
+        if (filter.limit)
+            results = results.slice(0, filter.limit);
+        return [...results];
+    }
+}
+exports.InMemoryLedgerStore = InMemoryLedgerStore;

package/dist/router-events.d.ts

@@ -0,0 +1,16 @@
+import { EventEmitter } from 'node:events';
+export type RouterEventType = 'attempt.start' | 'attempt.success' | 'attempt.failure' | 'attempt.rate_limited' | 'attempt.timeout' | 'circuit.opened' | 'circuit.half_opened' | 'circuit.closed' | 'webhook.duplicate' | 'request.success' | 'request.failure';
+export interface RouterEvent {
+    type: RouterEventType;
+    provider?: string;
+    operation?: 'createPayment' | 'createSubscription' | 'getPayment' | 'refund' | 'parseWebhook' | 'createOnRamp' | 'createOffRamp' | 'getQuote' | 'getRamp';
+    reference?: string;
+    durationMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    attempt?: number;
+    timestamp: string;
+}
+export declare class RouterEventEmitter extends EventEmitter {
+    emitEvent(event: RouterEvent): void;
+}

package/dist/router-events.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouterEventEmitter = void 0;
+const node_events_1 = require("node:events");
+class RouterEventEmitter extends node_events_1.EventEmitter {
+    emitEvent(event) {
+        this.emit(event.type, event);
+        this.emit('*', event);
+    }
+}
+exports.RouterEventEmitter = RouterEventEmitter;

package/dist/router.d.ts

@@ -5,6 +5,9 @@ import { PayBridge } from './index';
 import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent, Provider } from './types';
 import { RoutingStrategy, FallbackConfig } from './routing-types';
 import type { IdempotencyStore } from './webhook-idempotency-store';
+import { RouterEventEmitter } from './router-events';
+import type { LedgerStore } from './ledger';
+import type { TracerLike } from './tracer';
 export declare class WebhookDuplicateError extends Error {
     readonly name = "WebhookDuplicateError";
     readonly eventId: string;
@@ -21,13 +24,18 @@ export interface PayBridgeRouterConfig {
     fallback?: FallbackConfig;
     circuitBreakerStore?: import('./circuit-breaker-store').CircuitBreakerStore;
     idempotencyStore?: IdempotencyStore;
+    ledger?: LedgerStore;
+    tracer?: TracerLike;
 }
 export declare class PayBridgeRouter {
+    readonly events: RouterEventEmitter;
     private providers;
     private strategy;
     private fallback;
     private circuitBreakers;
     private idempotencyStore?;
+    private ledger?;
+    private tracer;
     private rrIndex;
     private config;
     constructor(config: PayBridgeRouterConfig);
@@ -39,4 +47,5 @@ export declare class PayBridgeRouter {
     verifyWebhook(body: any, headers: any, providerName: Provider): boolean;
     private filterProviders;
     private sleep;
+    private recordLedgerEntry;
 }

package/dist/router.js

@@ -8,6 +8,8 @@ const routing_types_1 = require("./routing-types");
 const strategies_1 = require("./strategies");
 const circuit_breaker_1 = require("./circuit-breaker");
 const fetch_1 = require("./utils/fetch");
+const router_events_1 = require("./router-events");
+const tracer_1 = require("./tracer");
 function sanitizeErrorMessage(msg) {
     if (!msg)
         return 'unknown error';
@@ -27,6 +29,7 @@ class WebhookDuplicateError extends Error {
 exports.WebhookDuplicateError = WebhookDuplicateError;
 class PayBridgeRouter {
     constructor(config) {
+        this.events = new router_events_1.RouterEventEmitter();
         this.rrIndex = 0;
         this.config = config;
         this.providers = config.providers.map(p => ({
@@ -41,12 +44,36 @@ class PayBridgeRouter {
             retryDelayMs: config.fallback?.retryDelayMs ?? 250,
         };
         this.idempotencyStore = config.idempotencyStore;
+        this.ledger = config.ledger;
+        this.tracer = config.tracer ?? tracer_1.noopTracer;
         this.circuitBreakers = new Map();
         for (const p of this.providers) {
             const name = p.instance.getProviderName();
-            this.circuitBreakers.set(name, new circuit_breaker_1.CircuitBreaker(name, {
+            const breaker = new circuit_breaker_1.CircuitBreaker(name, {
                 store: config.circuitBreakerStore,
-            }));
+            });
+            breaker.events.on('opened', (key) => {
+                this.events.emitEvent({
+                    type: 'circuit.opened',
+                    provider: key,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            breaker.events.on('half_opened', (key) => {
+                this.events.emitEvent({
+                    type: 'circuit.half_opened',
+                    provider: key,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            breaker.events.on('closed', (key) => {
+                this.events.emitEvent({
+                    type: 'circuit.closed',
+                    provider: key,
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            this.circuitBreakers.set(name, breaker);
         }
     }
     async createPayment(params) {
@@ -82,9 +109,24 @@ class PayBridgeRouter {
                 continue;
             }
             const startTime = Date.now();
+            const span = this.tracer.startSpan('paybridge.router.createPayment', {
+                'paybridge.provider': providerName,
+                'paybridge.strategy': this.strategy,
+                'paybridge.attempt': attempts.length + 1,
+            });
+            this.events.emitEvent({
+                type: 'attempt.start',
+                provider: providerName,
+                operation: 'createPayment',
+                reference: params.reference,
+                attempt: attempts.length + 1,
+                timestamp: new Date().toISOString(),
+            });
             try {
                 const result = await providerMeta.instance.createPayment(params);
                 const latencyMs = Date.now() - startTime;
+                span.setAttribute('paybridge.payment.id', result.id);
+                span.setAttribute('paybridge.payment.status', result.status);
                 if (breaker)
                     await breaker.recordSuccess();
                 attempts.push({
@@ -92,21 +134,59 @@ class PayBridgeRouter {
                     status: 'success',
                     latencyMs,
                 });
+                this.events.emitEvent({
+                    type: 'attempt.success',
+                    provider: providerName,
+                    operation: 'createPayment',
+                    reference: params.reference,
+                    durationMs: latencyMs,
+                    attempt: attempts.length,
+                    timestamp: new Date().toISOString(),
+                });
+                this.events.emitEvent({
+                    type: 'request.success',
+                    provider: providerName,
+                    operation: 'createPayment',
+                    reference: params.reference,
+                    durationMs: latencyMs,
+                    timestamp: new Date().toISOString(),
+                });
+                await this.recordLedgerEntry({
+                    id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                    timestamp: new Date().toISOString(),
+                    operation: 'createPayment',
+                    provider: providerName,
+                    reference: params.reference,
+                    providerId: result.id,
+                    status: 'success',
+                    amount: params.amount,
+                    currency: params.currency,
+                    durationMs: latencyMs,
+                });
                 const routingMeta = {
                     attempts,
                     chosenProvider: providerName,
                     strategy: this.strategy,
                 };
+                span.end();
                 return {
                     ...result,
                     routingMeta,
                 };
             }
             catch (error) {
+                span.recordException?.(error instanceof Error ? error : new Error(String(error)));
                 const latencyMs = Date.now() - startTime;
                 lastError = error;
                 const isRateLimited = error instanceof fetch_1.HttpError &&
                     (error.status === 429 || (error.status === 503 && error.retryAfterMs !== undefined));
+                let errorCode = error.code;
+                if (error instanceof fetch_1.FetchTimeoutError) {
+                    errorCode = 'TIMEOUT';
+                }
+                else if (isRateLimited) {
+                    errorCode = 'RATE_LIMITED';
+                }
                 if (isRateLimited) {
                     attempts.push({
                         provider: providerName,
@@ -115,14 +195,34 @@ class PayBridgeRouter {
                         errorMessage: sanitizeErrorMessage(error.message),
                         latencyMs,
                     });
+                    this.events.emitEvent({
+                        type: 'attempt.rate_limited',
+                        provider: providerName,
+                        operation: 'createPayment',
+                        reference: params.reference,
+                        durationMs: latencyMs,
+                        errorCode: 'RATE_LIMITED',
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        attempt: attempts.length,
+                        timestamp: new Date().toISOString(),
+                    });
+                    await this.recordLedgerEntry({
+                        id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                        timestamp: new Date().toISOString(),
+                        operation: 'createPayment',
+                        provider: providerName,
+                        reference: params.reference,
+                        status: 'rate_limited',
+                        amount: params.amount,
+                        currency: params.currency,
+                        durationMs: latencyMs,
+                        errorCode: 'RATE_LIMITED',
+                        errorMessage: sanitizeErrorMessage(error.message),
+                    });
                 }
                 else {
                     if (breaker)
                         await breaker.recordFailure();
-                    let errorCode = error.code;
-                    if (error instanceof fetch_1.FetchTimeoutError) {
-                        errorCode = 'TIMEOUT';
-                    }
                     attempts.push({
                         provider: providerName,
                         status: 'failed',
@@ -130,13 +230,48 @@ class PayBridgeRouter {
                         errorMessage: sanitizeErrorMessage(error.message),
                         latencyMs,
                     });
+                    const eventType = error instanceof fetch_1.FetchTimeoutError ? 'attempt.timeout' : 'attempt.failure';
+                    this.events.emitEvent({
+                        type: eventType,
+                        provider: providerName,
+                        operation: 'createPayment',
+                        reference: params.reference,
+                        durationMs: latencyMs,
+                        errorCode,
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        attempt: attempts.length,
+                        timestamp: new Date().toISOString(),
+                    });
+                    const ledgerStatus = error instanceof fetch_1.FetchTimeoutError ? 'timeout' : 'failed';
+                    await this.recordLedgerEntry({
+                        id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                        timestamp: new Date().toISOString(),
+                        operation: 'createPayment',
+                        provider: providerName,
+                        reference: params.reference,
+                        status: ledgerStatus,
+                        amount: params.amount,
+                        currency: params.currency,
+                        durationMs: latencyMs,
+                        errorCode,
+                        errorMessage: sanitizeErrorMessage(error.message),
+                    });
                 }
+                span.setAttribute('paybridge.error.code', errorCode ?? 'unknown');
+                span.end();
                 if (!this.fallback.enabled || attempts.length >= (this.fallback.maxAttempts ?? 3)) {
                     break;
                 }
                 await this.sleep(this.fallback.retryDelayMs ?? 250);
             }
         }
+        this.events.emitEvent({
+            type: 'request.failure',
+            operation: 'createPayment',
+            reference: params.reference,
+            errorMessage: lastError?.message || 'All providers failed',
+            timestamp: new Date().toISOString(),
+        });
         throw new routing_types_1.RoutingError(`All providers failed: ${lastError?.message || 'Unknown error'}`, attempts);
     }
     async createSubscription(params) {
@@ -169,6 +304,14 @@ class PayBridgeRouter {
                 continue;
             }
             const startTime = Date.now();
+            this.events.emitEvent({
+                type: 'attempt.start',
+                provider: providerName,
+                operation: 'createSubscription',
+                reference: params.reference,
+                attempt: attempts.length + 1,
+                timestamp: new Date().toISOString(),
+            });
             try {
                 const result = await providerMeta.instance.createSubscription(params);
                 const latencyMs = Date.now() - startTime;
@@ -179,6 +322,35 @@ class PayBridgeRouter {
                     status: 'success',
                     latencyMs,
                 });
+                this.events.emitEvent({
+                    type: 'attempt.success',
+                    provider: providerName,
+                    operation: 'createSubscription',
+                    reference: params.reference,
+                    durationMs: latencyMs,
+                    attempt: attempts.length,
+                    timestamp: new Date().toISOString(),
+                });
+                this.events.emitEvent({
+                    type: 'request.success',
+                    provider: providerName,
+                    operation: 'createSubscription',
+                    reference: params.reference,
+                    durationMs: latencyMs,
+                    timestamp: new Date().toISOString(),
+                });
+                await this.recordLedgerEntry({
+                    id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                    timestamp: new Date().toISOString(),
+                    operation: 'createSubscription',
+                    provider: providerName,
+                    reference: params.reference,
+                    providerId: result.id,
+                    status: 'success',
+                    amount: params.amount,
+                    currency: params.currency,
+                    durationMs: latencyMs,
+                });
                 return result;
             }
             catch (error) {
@@ -194,6 +366,30 @@ class PayBridgeRouter {
                         errorMessage: sanitizeErrorMessage(error.message),
                         latencyMs,
                     });
+                    this.events.emitEvent({
+                        type: 'attempt.rate_limited',
+                        provider: providerName,
+                        operation: 'createSubscription',
+                        reference: params.reference,
+                        durationMs: latencyMs,
+                        errorCode: 'RATE_LIMITED',
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        attempt: attempts.length,
+                        timestamp: new Date().toISOString(),
+                    });
+                    await this.recordLedgerEntry({
+                        id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                        timestamp: new Date().toISOString(),
+                        operation: 'createSubscription',
+                        provider: providerName,
+                        reference: params.reference,
+                        status: 'rate_limited',
+                        amount: params.amount,
+                        currency: params.currency,
+                        durationMs: latencyMs,
+                        errorCode: 'RATE_LIMITED',
+                        errorMessage: sanitizeErrorMessage(error.message),
+                    });
                 }
                 else {
                     if (breaker)
@@ -209,6 +405,32 @@ class PayBridgeRouter {
                         errorMessage: sanitizeErrorMessage(error.message),
                         latencyMs,
                     });
+                    const eventType = error instanceof fetch_1.FetchTimeoutError ? 'attempt.timeout' : 'attempt.failure';
+                    this.events.emitEvent({
+                        type: eventType,
+                        provider: providerName,
+                        operation: 'createSubscription',
+                        reference: params.reference,
+                        durationMs: latencyMs,
+                        errorCode,
+                        errorMessage: sanitizeErrorMessage(error.message),
+                        attempt: attempts.length,
+                        timestamp: new Date().toISOString(),
+                    });
+                    const ledgerStatus = error instanceof fetch_1.FetchTimeoutError ? 'timeout' : 'failed';
+                    await this.recordLedgerEntry({
+                        id: `${providerName}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+                        timestamp: new Date().toISOString(),
+                        operation: 'createSubscription',
+                        provider: providerName,
+                        reference: params.reference,
+                        status: ledgerStatus,
+                        amount: params.amount,
+                        currency: params.currency,
+                        durationMs: latencyMs,
+                        errorCode,
+                        errorMessage: sanitizeErrorMessage(error.message),
+                    });
                 }
                 if (!this.fallback.enabled || attempts.length >= (this.fallback.maxAttempts ?? 3)) {
                     break;
@@ -216,6 +438,13 @@ class PayBridgeRouter {
                 await this.sleep(this.fallback.retryDelayMs ?? 250);
             }
         }
+        this.events.emitEvent({
+            type: 'request.failure',
+            operation: 'createSubscription',
+            reference: params.reference,
+            errorMessage: lastError?.message || 'All providers failed',
+            timestamp: new Date().toISOString(),
+        });
         throw new routing_types_1.RoutingError(`All providers failed for subscription: ${lastError?.message || 'Unknown error'}`, attempts);
     }
     async getPayment(id, provider) {
@@ -269,6 +498,13 @@ class PayBridgeRouter {
                 const ttlMs = 24 * 60 * 60 * 1000;
                 const isNew = await this.idempotencyStore.recordIfNew(key, ttlMs);
                 if (!isNew) {
+                    this.events.emitEvent({
+                        type: 'webhook.duplicate',
+                        provider: providerName,
+                        operation: 'parseWebhook',
+                        reference: eventId,
+                        timestamp: new Date().toISOString(),
+                    });
                     throw new WebhookDuplicateError(providerName, eventId);
                 }
             }
@@ -300,5 +536,21 @@ class PayBridgeRouter {
     sleep(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
+    async recordLedgerEntry(entry) {
+        if (!this.ledger)
+            return;
+        try {
+            await this.ledger.append(entry);
+        }
+        catch (err) {
+            this.events.emitEvent({
+                type: 'attempt.failure',
+                operation: entry.operation,
+                provider: entry.provider,
+                errorMessage: 'Ledger write failed',
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
 }
 exports.PayBridgeRouter = PayBridgeRouter;

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

@@ -0,0 +1,8 @@
+import type { RedisLike } from './redis';
+import type { LedgerStore } from '../ledger';
+export interface RedisLedgerStoreOptions {
+    redis: RedisLike;
+    keyPrefix?: string;
+    maxEntries?: number;
+}
+export declare function createRedisLedgerStore(opts: RedisLedgerStoreOptions): LedgerStore;

package/dist/stores/redis-ledger.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedisLedgerStore = createRedisLedgerStore;
+function createRedisLedgerStore(opts) {
+    const prefix = opts.keyPrefix ?? 'pb:ledger:';
+    const maxEntries = opts.maxEntries ?? 100000;
+    const listKey = `${prefix}list`;
+    const refIndexPrefix = `${prefix}ref:`;
+    if (!opts.redis.lpush || !opts.redis.ltrim || !opts.redis.lrange || !opts.redis.sadd || !opts.redis.smembers || !opts.redis.expire) {
+        throw new Error('Redis client does not support required list/set operations for ledger store');
+    }
+    return {
+        async append(entry) {
+            const serialized = JSON.stringify(entry);
+            await opts.redis.lpush(listKey, serialized);
+            await opts.redis.ltrim(listKey, 0, maxEntries - 1);
+            if (entry.reference) {
+                const refKey = `${refIndexPrefix}${entry.reference}`;
+                await opts.redis.sadd(refKey, entry.id);
+                await opts.redis.expire(refKey, 86400 * 30);
+            }
+        },
+        async query(filter) {
+            let entries = [];
+            if (filter.reference) {
+                const refKey = `${refIndexPrefix}${filter.reference}`;
+                const ids = await opts.redis.smembers(refKey);
+                if (!ids || ids.length === 0)
+                    return [];
+                const allEntries = await opts.redis.lrange(listKey, 0, -1);
+                entries = allEntries
+                    .map((s) => JSON.parse(s))
+                    .filter((e) => ids.includes(e.id));
+            }
+            else {
+                const allEntries = await opts.redis.lrange(listKey, 0, -1);
+                entries = allEntries.map((s) => JSON.parse(s));
+            }
+            if (filter.provider)
+                entries = entries.filter(e => e.provider === filter.provider);
+            if (filter.status)
+                entries = entries.filter(e => e.status === filter.status);
+            if (filter.fromTimestamp)
+                entries = entries.filter(e => e.timestamp >= filter.fromTimestamp);
+            if (filter.toTimestamp)
+                entries = entries.filter(e => e.timestamp <= filter.toTimestamp);
+            if (filter.limit)
+                entries = entries.slice(0, filter.limit);
+            return entries;
+        },
+    };
+}

package/dist/stores/redis.d.ts

@@ -10,6 +10,12 @@ export interface RedisLike {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ...args: any[]): Promise<any>;
     del(key: string): Promise<any>;
+    lpush?(key: string, ...values: string[]): Promise<number>;
+    ltrim?(key: string, start: number, stop: number): Promise<string>;
+    lrange?(key: string, start: number, stop: number): Promise<string[]>;
+    sadd?(key: string, ...members: string[]): Promise<number>;
+    smembers?(key: string): Promise<string[]>;
+    expire?(key: string, seconds: number): Promise<number>;
 }
 export interface RedisStoreOptions {
     prefix?: string;

package/dist/tracer.d.ts

@@ -0,0 +1,9 @@
+export interface SpanLike {
+    setAttribute(key: string, value: string | number | boolean): void;
+    recordException?(error: Error): void;
+    end(): void;
+}
+export interface TracerLike {
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanLike;
+}
+export declare const noopTracer: TracerLike;

package/dist/tracer.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopTracer = void 0;
+exports.noopTracer = {
+    startSpan: () => ({
+        setAttribute: () => { },
+        recordException: () => { },
+        end: () => { },
+    }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paybridge",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -11,7 +11,8 @@
     "prepublishOnly": "npm run clean && npm run build",
     "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"
+    "test:e2e:yellowcard": "tsx tests/e2e/yellowcard-sandbox.ts",
+    "test:e2e:sandbox": "tsx tests/e2e/sandbox-validate.ts"
   },
   "keywords": [
     "payments",
@@ -49,6 +50,7 @@
   },
   "devDependencies": {
     "@types/node": "^18.19.130",
+    "tsx": "^4.19.2",
     "typescript": "^5.9.3"
   }
 }