paybridge 0.2.3 → 0.3.1

package/README.md

@@ -50,6 +50,8 @@ Perfect for demos, learning, and rapid prototyping. See [playground/README.md](p
 
 ## Quick Start
 
+> **Upgrading from 0.1 or 0.2?** See [docs/migration.md](docs/migration.md).
+
 ### One-time Payment
 
 ```typescript
@@ -205,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/crypto/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * CryptoRamp — Unified crypto on/off-ramp SDK
  */
+import { CryptoRampProvider } from './base';
 import { OnRampParams, OffRampParams, RampQuote, RampResult, CryptoRampCapabilities } from './types';
 export * from './types';
 export * from './base';
@@ -21,7 +22,9 @@ export interface CryptoRampConfig {
 }
 export declare class CryptoRamp {
     private provider;
-    constructor(config: CryptoRampConfig);
+    constructor(config: CryptoRampConfig | {
+        provider: CryptoRampProvider;
+    });
     private createProvider;
     getQuote(direction: 'on' | 'off', fiatAmount: number, fiatCurrency: string, cryptoAsset: string, network: string): Promise<RampQuote>;
     createOnRamp(params: OnRampParams): Promise<RampResult>;

package/dist/crypto/index.js

@@ -29,7 +29,12 @@ __exportStar(require("./mock"), exports);
 __exportStar(require("./router"), exports);
 class CryptoRamp {
     constructor(config) {
-        this.provider = this.createProvider(config);
+        if ('provider' in config && typeof config.provider === 'object' && 'name' in config.provider) {
+            this.provider = config.provider;
+        }
+        else {
+            this.provider = this.createProvider(config);
+        }
     }
     createProvider(config) {
         const { provider, credentials, sandbox = true, webhookSecret } = config;

package/dist/crypto/router.d.ts

@@ -8,7 +8,7 @@ export interface CryptoRampRouterConfig {
         provider: CryptoRamp;
         priority?: number;
     }>;
-    strategy?: 'cheapest' | 'priority' | 'round-robin';
+    strategy?: 'cheapest' | 'priority' | 'round-robin' | 'fastest';
     fallback?: {
         enabled: boolean;
         maxAttempts?: number;
@@ -16,6 +16,7 @@ export interface CryptoRampRouterConfig {
     };
     allowExperimental?: boolean;
     circuitBreakerStore?: import('../circuit-breaker-store').CircuitBreakerStore;
+    idempotencyStore?: import('../webhook-idempotency-store').IdempotencyStore;
 }
 export declare class CryptoRampRouter {
     private providers;

package/dist/crypto/router.js

@@ -265,6 +265,14 @@ class CryptoRampRouter {
                     const feeB = direction === 'on' ? capsB.fees.onRampPercent : capsB.fees.offRampPercent;
                     return feeA - feeB;
                 });
+            case 'fastest':
+                return [...providers].sort((a, b) => {
+                    const capsA = a.instance.getCapabilities();
+                    const capsB = b.instance.getCapabilities();
+                    const latencyA = capsA.avgLatencyMs ?? Number.MAX_SAFE_INTEGER;
+                    const latencyB = capsB.avgLatencyMs ?? Number.MAX_SAFE_INTEGER;
+                    return latencyA - latencyB;
+                });
             case 'priority':
                 return [...providers].sort((a, b) => {
                     const priorityA = a.priority ?? 0;

package/dist/crypto/types.d.ts

@@ -85,5 +85,6 @@ export interface CryptoRampCapabilities {
         onRampPercent: number;
         offRampPercent: number;
     };
+    avgLatencyMs?: number;
     experimental?: boolean;
 }

package/dist/index.d.ts

@@ -15,7 +15,9 @@ export * from './circuit-breaker-store';
 export * from './strategies';
 export * from './router';
 export * from './crypto';
+export * from './webhook-idempotency-store';
 export { createRedisCircuitBreakerStore, type RedisLike, type RedisStoreOptions } from './stores/redis';
+export { createRedisIdempotencyStore, type RedisIdempotencyStoreOptions } from './stores/redis-idempotency';
 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.createRedisCircuitBreakerStore = void 0;
+exports.PayBridge = exports.createRedisIdempotencyStore = exports.createRedisCircuitBreakerStore = void 0;
 const softycomp_1 = require("./providers/softycomp");
 const yoco_1 = require("./providers/yoco");
 const ozow_1 = require("./providers/ozow");
@@ -38,8 +38,11 @@ __exportStar(require("./circuit-breaker-store"), exports);
 __exportStar(require("./strategies"), exports);
 __exportStar(require("./router"), exports);
 __exportStar(require("./crypto"), exports);
+__exportStar(require("./webhook-idempotency-store"), 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; } });
 class PayBridge {
     constructor(config) {
         this.provider = this.createProvider(config);

package/dist/router.d.ts

@@ -4,6 +4,13 @@
 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';
+export declare class WebhookDuplicateError extends Error {
+    readonly name = "WebhookDuplicateError";
+    readonly eventId: string;
+    readonly provider: string;
+    constructor(provider: string, eventId: string);
+}
 export interface PayBridgeRouterConfig {
     providers: Array<{
         provider: PayBridge;
@@ -13,12 +20,14 @@ export interface PayBridgeRouterConfig {
     strategy?: RoutingStrategy;
     fallback?: FallbackConfig;
     circuitBreakerStore?: import('./circuit-breaker-store').CircuitBreakerStore;
+    idempotencyStore?: IdempotencyStore;
 }
 export declare class PayBridgeRouter {
     private providers;
     private strategy;
     private fallback;
     private circuitBreakers;
+    private idempotencyStore?;
     private rrIndex;
     private config;
     constructor(config: PayBridgeRouterConfig);
@@ -26,7 +35,7 @@ export declare class PayBridgeRouter {
     createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
     getPayment(id: string, provider?: string): Promise<PaymentResult>;
     refund(params: RefundParams, provider?: string): Promise<RefundResult>;
-    parseWebhook(body: any, headers: any, providerName: Provider): WebhookEvent;
+    parseWebhook(body: any, headers: any, providerName: Provider): Promise<WebhookEvent>;
     verifyWebhook(body: any, headers: any, providerName: Provider): boolean;
     private filterProviders;
     private sleep;

package/dist/router.js

@@ -3,7 +3,7 @@
  * PayBridgeRouter — Multi-provider routing with fallback
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayBridgeRouter = void 0;
+exports.PayBridgeRouter = exports.WebhookDuplicateError = void 0;
 const routing_types_1 = require("./routing-types");
 const strategies_1 = require("./strategies");
 const circuit_breaker_1 = require("./circuit-breaker");
@@ -16,6 +16,15 @@ function sanitizeErrorMessage(msg) {
         .replace(/(api[_-]?key|secret|token|password)["':=\s]+\S+/gi, '$1=[REDACTED]')
         .slice(0, 500);
 }
+class WebhookDuplicateError extends Error {
+    constructor(provider, eventId) {
+        super(`Webhook event already processed: ${provider}:${eventId}`);
+        this.name = 'WebhookDuplicateError';
+        this.eventId = eventId;
+        this.provider = provider;
+    }
+}
+exports.WebhookDuplicateError = WebhookDuplicateError;
 class PayBridgeRouter {
     constructor(config) {
         this.rrIndex = 0;
@@ -31,6 +40,7 @@ class PayBridgeRouter {
             maxAttempts: config.fallback?.maxAttempts ?? 3,
             retryDelayMs: config.fallback?.retryDelayMs ?? 250,
         };
+        this.idempotencyStore = config.idempotencyStore;
         this.circuitBreakers = new Map();
         for (const p of this.providers) {
             const name = p.instance.getProviderName();
@@ -246,12 +256,24 @@ class PayBridgeRouter {
         }
         throw new Error(`Refund for payment ${params.paymentId} failed on all providers: ${lastError?.message || 'Unknown error'}`);
     }
-    parseWebhook(body, headers, providerName) {
+    async parseWebhook(body, headers, providerName) {
         const providerMeta = this.providers.find(p => p.instance.getProviderName() === providerName);
         if (!providerMeta) {
             throw new Error(`Unknown provider for webhook: ${providerName}`);
         }
-        return providerMeta.instance.parseWebhook(body, headers);
+        const event = providerMeta.instance.parseWebhook(body, headers);
+        if (this.idempotencyStore) {
+            const eventId = event.payment?.id || event.subscription?.id || event.refund?.id;
+            if (eventId) {
+                const key = `${providerName}:${eventId}`;
+                const ttlMs = 24 * 60 * 60 * 1000;
+                const isNew = await this.idempotencyStore.recordIfNew(key, ttlMs);
+                if (!isNew) {
+                    throw new WebhookDuplicateError(providerName, eventId);
+                }
+            }
+        }
+        return event;
     }
     verifyWebhook(body, headers, providerName) {
         const providerMeta = this.providers.find(p => p.instance.getProviderName() === providerName);

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

@@ -0,0 +1,10 @@
+/**
+ * Redis-backed idempotency store adapter
+ */
+import type { RedisLike } from './redis';
+import type { IdempotencyStore } from '../webhook-idempotency-store';
+export interface RedisIdempotencyStoreOptions {
+    redis: RedisLike;
+    keyPrefix?: string;
+}
+export declare function createRedisIdempotencyStore(opts: RedisIdempotencyStoreOptions): IdempotencyStore;

package/dist/stores/redis-idempotency.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Redis-backed idempotency store adapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedisIdempotencyStore = createRedisIdempotencyStore;
+function createRedisIdempotencyStore(opts) {
+    const prefix = opts.keyPrefix ?? 'pb:idem:';
+    return {
+        async recordIfNew(key, ttlMs) {
+            const result = await opts.redis.set(`${prefix}${key}`, '1', 'PX', ttlMs, 'NX');
+            return result === 'OK';
+        },
+    };
+}

package/dist/strategies.js

@@ -19,8 +19,8 @@ exports.strategies = {
         return [...providers].sort((a, b) => {
             const capsA = a.instance.provider.getCapabilities();
             const capsB = b.instance.provider.getCapabilities();
-            const latencyA = capsA.avgLatencyMs ?? 1000;
-            const latencyB = capsB.avgLatencyMs ?? 1000;
+            const latencyA = capsA.avgLatencyMs ?? Number.MAX_SAFE_INTEGER;
+            const latencyB = capsB.avgLatencyMs ?? Number.MAX_SAFE_INTEGER;
             return latencyA - latencyB;
         });
     },

package/dist/webhook-idempotency-store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Webhook idempotency storage abstraction
+ */
+export interface IdempotencyStore {
+    recordIfNew(key: string, ttlMs: number): Promise<boolean>;
+}
+export declare class InMemoryIdempotencyStore implements IdempotencyStore {
+    private store;
+    private cleanupInterval?;
+    constructor(opts?: {
+        cleanupIntervalMs?: number;
+    });
+    recordIfNew(key: string, ttlMs: number): Promise<boolean>;
+    private cleanup;
+    destroy(): void;
+}

package/dist/webhook-idempotency-store.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Webhook idempotency storage abstraction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryIdempotencyStore = void 0;
+class InMemoryIdempotencyStore {
+    constructor(opts = {}) {
+        this.store = new Map();
+        if (opts.cleanupIntervalMs) {
+            this.cleanupInterval = setInterval(() => this.cleanup(), opts.cleanupIntervalMs);
+            this.cleanupInterval.unref?.();
+        }
+    }
+    async recordIfNew(key, ttlMs) {
+        const now = Date.now();
+        const existing = this.store.get(key);
+        if (existing !== undefined && existing > now) {
+            return false;
+        }
+        this.store.set(key, now + ttlMs);
+        return true;
+    }
+    cleanup() {
+        const now = Date.now();
+        const keysToDelete = [];
+        this.store.forEach((expiresAt, k) => {
+            if (expiresAt <= now)
+                keysToDelete.push(k);
+        });
+        keysToDelete.forEach(k => this.store.delete(k));
+    }
+    destroy() {
+        if (this.cleanupInterval)
+            clearInterval(this.cleanupInterval);
+        this.store.clear();
+    }
+}
+exports.InMemoryIdempotencyStore = InMemoryIdempotencyStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paybridge",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "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"
   }
 }