@nehorai/payments 0.1.0

package/dist/factory.js

@@ -0,0 +1,777 @@
+// src/services/payment-orchestrator.ts
+import { randomUUID } from "crypto";
+
+// src/config/payment-config.ts
+function createPartialConfig(partial) {
+  return {
+    providers: partial.providers ?? {},
+    environment: partial.environment ?? "sandbox",
+    defaultCurrency: partial.defaultCurrency ?? "USD"
+  };
+}
+function getConfiguredProviders(config) {
+  const availability = {};
+  for (const [name, providerConfig] of Object.entries(config.providers)) {
+    availability[name] = providerConfig !== void 0 && Object.keys(providerConfig).length > 0;
+  }
+  return availability;
+}
+
+// src/services/circuit-breaker-storage.interface.ts
+function createDefaultState(provider) {
+  return {
+    provider,
+    state: "closed",
+    failureCount: 0,
+    successCount: 0,
+    lastFailure: null,
+    openedAt: null,
+    nextRetryAt: null
+  };
+}
+
+// src/services/in-memory-storage.ts
+var InMemoryCircuitBreakerStorage = class {
+  internalStates;
+  constructor() {
+    this.internalStates = /* @__PURE__ */ new Map();
+  }
+  async getState(provider) {
+    return this.internalStates.get(provider) ?? null;
+  }
+  async setState(provider, state) {
+    this.internalStates.set(provider, { ...state });
+  }
+  async getAllStates() {
+    return new Map(this.internalStates);
+  }
+  async deleteState(provider) {
+    this.internalStates.delete(provider);
+  }
+  async getOpenCircuits() {
+    const open = [];
+    for (const [provider, state] of this.internalStates) {
+      if (state.state === "open") {
+        open.push(provider);
+      }
+    }
+    return open;
+  }
+  async isHealthy() {
+    return true;
+  }
+  /**
+   * Clear all stored states (useful for testing)
+   */
+  clear() {
+    this.internalStates.clear();
+  }
+  /**
+   * Get current state count (useful for testing/debugging)
+   */
+  get size() {
+    return this.internalStates.size;
+  }
+  /**
+   * Synchronous state access (for backward compatibility with CircuitBreaker.isOpen)
+   *
+   * Note: Only available on InMemoryCircuitBreakerStorage.
+   * Database-backed storage cannot provide sync access.
+   */
+  getStateSync(provider) {
+    return this.internalStates.get(provider) ?? null;
+  }
+};
+
+// src/services/circuit-breaker.ts
+var DEFAULT_CONFIG = {
+  failureThreshold: 5,
+  resetTimeoutMs: 6e4,
+  // 1 minute
+  halfOpenMaxRequests: 3
+};
+var CircuitBreaker = class {
+  config;
+  storage;
+  constructor(deps = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...deps.config };
+    this.storage = deps.storage ?? new InMemoryCircuitBreakerStorage();
+  }
+  /**
+   * Check if a request can be executed for a provider
+   */
+  async canExecute(provider) {
+    const state = await this.getState(provider);
+    switch (state.state) {
+      case "closed":
+        return true;
+      case "open":
+        if (state.nextRetryAt && Date.now() >= state.nextRetryAt.getTime()) {
+          await this.transitionTo(provider, "half_open");
+          return true;
+        }
+        return false;
+      case "half_open":
+        return state.failureCount < this.config.halfOpenMaxRequests;
+    }
+  }
+  /**
+   * Record a successful request
+   */
+  async recordSuccess(provider) {
+    const state = await this.getState(provider);
+    if (state.state === "half_open") {
+      state.successCount++;
+      if (state.successCount >= this.config.halfOpenMaxRequests) {
+        await this.transitionTo(provider, "closed");
+        return;
+      }
+    } else if (state.state === "closed") {
+      state.failureCount = 0;
+    }
+    await this.storage.setState(provider, state);
+  }
+  /**
+   * Record a failed request
+   */
+  async recordFailure(provider) {
+    const state = await this.getState(provider);
+    state.failureCount++;
+    state.lastFailure = /* @__PURE__ */ new Date();
+    if (state.state === "half_open") {
+      await this.transitionTo(provider, "open");
+    } else if (state.state === "closed") {
+      if (state.failureCount >= this.config.failureThreshold) {
+        await this.transitionTo(provider, "open");
+      } else {
+        await this.storage.setState(provider, state);
+      }
+    } else {
+      await this.storage.setState(provider, state);
+    }
+  }
+  /**
+   * Get current state for a provider
+   */
+  async getState(provider) {
+    const stored = await this.storage.getState(provider);
+    return stored ?? createDefaultState(provider);
+  }
+  /**
+   * Check if circuit is open (provider unavailable)
+   */
+  isOpen(provider) {
+    return this.isOpenSync(provider);
+  }
+  /**
+   * Async version of isOpen
+   */
+  async isOpenAsync(provider) {
+    const state = await this.getState(provider);
+    return state.state === "open";
+  }
+  /**
+   * Manually reset a provider's circuit
+   */
+  async reset(provider) {
+    await this.storage.setState(provider, createDefaultState(provider));
+  }
+  /**
+   * Get all providers with open circuits
+   */
+  async getOpenCircuits() {
+    return this.storage.getOpenCircuits();
+  }
+  /**
+   * Get the storage instance (useful for testing)
+   */
+  getStorage() {
+    return this.storage;
+  }
+  /**
+   * Get configuration (useful for testing)
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+  async transitionTo(provider, newState) {
+    const state = await this.getState(provider);
+    const now = /* @__PURE__ */ new Date();
+    state.state = newState;
+    if (newState === "open") {
+      state.openedAt = now;
+      state.nextRetryAt = new Date(now.getTime() + this.config.resetTimeoutMs);
+      console.warn(
+        `[CIRCUIT_BREAKER] Circuit OPENED for ${provider}. Retry at: ${state.nextRetryAt.toISOString()}`
+      );
+    } else if (newState === "half_open") {
+      state.failureCount = 0;
+      state.successCount = 0;
+      console.info(`[CIRCUIT_BREAKER] Circuit HALF_OPEN for ${provider}`);
+    } else if (newState === "closed") {
+      state.failureCount = 0;
+      state.successCount = 0;
+      state.openedAt = null;
+      state.nextRetryAt = null;
+      console.info(`[CIRCUIT_BREAKER] Circuit CLOSED for ${provider}`);
+    }
+    await this.storage.setState(provider, state);
+  }
+  /**
+   * Synchronous check for backward compatibility
+   * Note: This always returns false for database-backed storage
+   */
+  isOpenSync(provider) {
+    if (this.storage instanceof InMemoryCircuitBreakerStorage) {
+      const state = this.storage.getStateSync(provider);
+      return state?.state === "open";
+    }
+    return false;
+  }
+};
+var circuitBreakerInstance = null;
+var defaultStorage = null;
+function getCircuitBreaker(config) {
+  if (!circuitBreakerInstance) {
+    if (!defaultStorage) {
+      defaultStorage = new InMemoryCircuitBreakerStorage();
+    }
+    circuitBreakerInstance = new CircuitBreaker({
+      storage: defaultStorage,
+      config
+    });
+  }
+  return circuitBreakerInstance;
+}
+function createCircuitBreaker(deps = {}) {
+  return new CircuitBreaker(deps);
+}
+function resetCircuitBreaker() {
+  circuitBreakerInstance = null;
+  if (defaultStorage) {
+    defaultStorage.clear();
+  }
+  defaultStorage = null;
+}
+
+// src/services/routing-engine.ts
+function matchCardBinToRule(bin, rules) {
+  if (!bin || bin.length < 6) return null;
+  const binPrefix = bin.substring(0, 6);
+  for (const rule of rules) {
+    for (const range of rule.ranges) {
+      if (binPrefix >= range.start && binPrefix <= range.end) {
+        return { rule, issuer: range.issuer, country: range.country };
+      }
+    }
+  }
+  return null;
+}
+function getOptimalProviderFromPriorities(matchedBin, currency, requiresRecurring, availableProviders, priorities) {
+  const candidates = priorities.filter(
+    (p) => availableProviders.includes(p.provider)
+  );
+  if (candidates.length === 0) return availableProviders[0] ?? null;
+  const suitable = candidates.filter((p) => {
+    if (!p.supportsCurrency.includes(currency)) return false;
+    if (requiresRecurring && !p.supportsRecurring) return false;
+    return true;
+  });
+  if (suitable.length === 0) {
+    return candidates.sort((a, b) => a.priority - b.priority)[0]?.provider ?? null;
+  }
+  if (matchedBin) {
+    const localProviders = suitable.filter((p) => p.isLocalGateway);
+    if (localProviders.length > 0) {
+      return localProviders.sort((a, b) => a.priority - b.priority)[0].provider;
+    }
+  }
+  return suitable.sort((a, b) => a.priority - b.priority)[0].provider;
+}
+function getFallbackProvidersFromPriorities(primaryProvider, availableProviders, priorities) {
+  return priorities.filter(
+    (p) => p.provider !== primaryProvider && availableProviders.includes(p.provider)
+  ).sort((a, b) => a.priority - b.priority).map((p) => p.provider);
+}
+function getProviderFeeFromPriorities(provider, priorities) {
+  const config = priorities.find((p) => p.provider === provider);
+  return config?.maxFeePercent ?? 3;
+}
+var RoutingEngine = class {
+  config;
+  circuitBreaker;
+  routingRules;
+  constructor(deps = {}) {
+    this.config = deps.config ?? createPartialConfig({});
+    this.circuitBreaker = deps.circuitBreaker ?? getCircuitBreaker();
+    this.routingRules = deps.routingRules ?? {};
+  }
+  /**
+   * Determine optimal provider for a transaction
+   */
+  async route(context) {
+    const availability = getConfiguredProviders(this.config);
+    const availableProviders = this.getProviderList(availability);
+    if (availableProviders.length === 0) {
+      throw new Error("No payment providers configured");
+    }
+    if (context.savedPaymentMethodId && context.savedPaymentMethodProvider) {
+      return this.routeToSavedMethodProvider(context, availableProviders);
+    }
+    const binMatch = context.cardBin && this.routingRules.cardBinRules ? matchCardBinToRule(context.cardBin, this.routingRules.cardBinRules) : null;
+    const currencyRule = this.routingRules.currencyRules?.find(
+      (r) => r.currency === context.amount.currency
+    );
+    const healthyProviders = await this.getHealthyProviders(availableProviders);
+    const availableHealthy = availableProviders.filter((p) => healthyProviders.includes(p));
+    const effectiveProviders = availableHealthy.length > 0 ? availableHealthy : availableProviders;
+    if (binMatch && effectiveProviders.includes(binMatch.rule.preferredProvider)) {
+      const provider2 = binMatch.rule.preferredProvider;
+      const fallbacks2 = this.getFallbackProviders(provider2, availableProviders);
+      const feePercent = this.getProviderFee(provider2);
+      return {
+        provider: provider2,
+        reason: binMatch.issuer ? `Card (${binMatch.issuer}) matched BIN rule, routed to preferred provider` : "Card matched BIN rule, routed to preferred provider",
+        fallbackProviders: fallbacks2,
+        estimatedFeePercent: feePercent,
+        metadata: {
+          matchedBinRule: true,
+          cardIssuer: binMatch.issuer,
+          cardCountry: binMatch.country
+        }
+      };
+    }
+    if (currencyRule && effectiveProviders.includes(currencyRule.preferredProvider)) {
+      const provider2 = currencyRule.preferredProvider;
+      const fallbacks2 = this.getFallbackProviders(provider2, availableProviders);
+      const feePercent = this.getProviderFee(provider2);
+      return {
+        provider: provider2,
+        reason: `Currency ${context.amount.currency} routed to preferred provider`,
+        fallbackProviders: fallbacks2,
+        estimatedFeePercent: feePercent
+      };
+    }
+    const priorities = this.routingRules.providerPriorities;
+    if (priorities && priorities.length > 0) {
+      const provider2 = getOptimalProviderFromPriorities(
+        !!binMatch,
+        context.amount.currency,
+        context.isRecurring,
+        effectiveProviders,
+        priorities
+      );
+      if (provider2) {
+        const fallbacks2 = getFallbackProvidersFromPriorities(provider2, availableProviders, priorities);
+        const feePercent = getProviderFeeFromPriorities(provider2, priorities);
+        return {
+          provider: provider2,
+          reason: `Selected ${provider2} based on priority rules`,
+          fallbackProviders: fallbacks2,
+          estimatedFeePercent: feePercent,
+          metadata: {
+            matchedBinRule: !!binMatch,
+            cardIssuer: binMatch?.issuer,
+            cardCountry: binMatch?.country
+          }
+        };
+      }
+    }
+    const provider = effectiveProviders[0];
+    const fallbacks = effectiveProviders.slice(1);
+    return {
+      provider,
+      reason: `Default routing to ${provider}`,
+      fallbackProviders: fallbacks,
+      estimatedFeePercent: this.getProviderFee(provider)
+    };
+  }
+  /**
+   * Get next provider after a failure
+   */
+  async getFailoverProvider(failedProvider, _context) {
+    const availability = getConfiguredProviders(this.config);
+    const availableProviders = this.getProviderList(availability);
+    const healthyProviders = await this.getHealthyProviders(availableProviders);
+    const fallbacks = this.getFallbackProviders(failedProvider, availableProviders);
+    for (const provider of fallbacks) {
+      if (healthyProviders.includes(provider)) {
+        return provider;
+      }
+    }
+    return fallbacks[0] ?? null;
+  }
+  /**
+   * Check if a card BIN matches any configured rule
+   */
+  matchCardBin(bin) {
+    if (!this.routingRules.cardBinRules) return false;
+    return matchCardBinToRule(bin, this.routingRules.cardBinRules) !== null;
+  }
+  /**
+   * Get all available (healthy) providers
+   */
+  async getAvailableProviders() {
+    const availability = getConfiguredProviders(this.config);
+    const configured = this.getProviderList(availability);
+    return this.getHealthyProviders(configured);
+  }
+  /**
+   * Quick recommendation without full context
+   */
+  async getQuickRecommendation(currency, isRecurring) {
+    const availability = getConfiguredProviders(this.config);
+    const available = this.getProviderList(availability);
+    if (available.length === 0) return null;
+    const currencyRule = this.routingRules.currencyRules?.find(
+      (r) => r.currency === currency
+    );
+    if (currencyRule && available.includes(currencyRule.preferredProvider)) {
+      return currencyRule.preferredProvider;
+    }
+    const priorities = this.routingRules.providerPriorities;
+    if (priorities && priorities.length > 0) {
+      return getOptimalProviderFromPriorities(false, currency, isRecurring, available, priorities);
+    }
+    return available[0] ?? null;
+  }
+  /**
+   * Get current configuration (for testing/debugging)
+   */
+  getConfig() {
+    return this.config;
+  }
+  /**
+   * Get circuit breaker instance (for testing/debugging)
+   */
+  getCircuitBreaker() {
+    return this.circuitBreaker;
+  }
+  /**
+   * Get routing rules (for testing/debugging)
+   */
+  getRoutingRules() {
+    return this.routingRules;
+  }
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+  getProviderList(availability) {
+    const providers = [];
+    for (const [name, isAvailable] of Object.entries(availability)) {
+      if (isAvailable) providers.push(name);
+    }
+    return providers;
+  }
+  async getHealthyProviders(providers) {
+    const healthy = [];
+    for (const provider of providers) {
+      const isOpen = await this.circuitBreaker.isOpenAsync(provider);
+      if (!isOpen) {
+        healthy.push(provider);
+      }
+    }
+    return healthy;
+  }
+  routeToSavedMethodProvider(context, availableProviders) {
+    const provider = context.savedPaymentMethodProvider;
+    if (!availableProviders.includes(provider)) {
+      throw new Error(`Saved payment method provider '${provider}' is not available`);
+    }
+    return {
+      provider,
+      reason: "Using saved payment method provider",
+      fallbackProviders: [],
+      estimatedFeePercent: this.getProviderFee(provider)
+    };
+  }
+  getFallbackProviders(primaryProvider, availableProviders) {
+    const priorities = this.routingRules.providerPriorities;
+    if (priorities && priorities.length > 0) {
+      return getFallbackProvidersFromPriorities(primaryProvider, availableProviders, priorities);
+    }
+    return availableProviders.filter((p) => p !== primaryProvider);
+  }
+  getProviderFee(provider) {
+    const priorities = this.routingRules.providerPriorities;
+    if (priorities && priorities.length > 0) {
+      return getProviderFeeFromPriorities(provider, priorities);
+    }
+    return 3;
+  }
+};
+var routingEngineInstance = null;
+function getRoutingEngine() {
+  if (!routingEngineInstance) {
+    routingEngineInstance = new RoutingEngine();
+  }
+  return routingEngineInstance;
+}
+function createRoutingEngine(deps = {}) {
+  return new RoutingEngine(deps);
+}
+function resetRoutingEngine() {
+  routingEngineInstance = null;
+}
+
+// src/services/payment-orchestrator.ts
+var PaymentOrchestrator = class {
+  providers;
+  routingEngine;
+  circuitBreaker;
+  constructor(deps) {
+    this.providers = deps.providers;
+    this.routingEngine = deps.routingEngine ?? getRoutingEngine();
+    this.circuitBreaker = deps.circuitBreaker ?? getCircuitBreaker();
+  }
+  /**
+   * Initiate a new payment
+   */
+  async initiatePayment(params) {
+    const internalPaymentId = `pay_${randomUUID()}`;
+    const idempotencyKey = `idem_${randomUUID()}`;
+    try {
+      const routing = await this.routingEngine.route({
+        userId: params.userId,
+        amount: params.amount,
+        cardBin: params.cardBin,
+        preferredProvider: params.preferredProvider,
+        isRecurring: params.transactionType !== "one_time_purchase"
+      });
+      const provider = this.getProvider(routing.provider);
+      if (!provider) {
+        return this.tryFailover(params, routing, internalPaymentId);
+      }
+      if (!await this.circuitBreaker.canExecute(routing.provider)) {
+        return this.tryFailover(params, routing, internalPaymentId);
+      }
+      const result = await provider.createPaymentIntent({
+        amount: params.amount,
+        userId: params.userId,
+        idempotencyKey,
+        description: params.description,
+        metadata: params.metadata,
+        returnUrl: params.returnUrl,
+        captureMethod: params.autoCapture ? "automatic" : "manual"
+      });
+      if (!result.success) {
+        await this.circuitBreaker.recordFailure(routing.provider);
+        return this.tryFailover(params, routing, internalPaymentId);
+      }
+      await this.circuitBreaker.recordSuccess(routing.provider);
+      return {
+        success: true,
+        transactionId: result.providerIntentId,
+        internalPaymentId,
+        provider: routing.provider,
+        clientSecret: result.clientSecret,
+        redirectUrl: result.redirectUrl
+      };
+    } catch (error) {
+      return {
+        success: false,
+        transactionId: "",
+        internalPaymentId,
+        provider: "unknown",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Confirm a payment after user authorization
+   */
+  async confirmPayment(params) {
+    const provider = this.getProvider(params.provider);
+    if (!provider) {
+      return {
+        success: false,
+        transactionId: params.transactionId,
+        status: "failed",
+        error: `Provider ${params.provider} not available`
+      };
+    }
+    const result = await provider.authorize({
+      providerIntentId: params.providerIntentId,
+      idempotencyKey: `auth_${params.internalPaymentId}`
+    });
+    if (!result.success) {
+      return {
+        success: false,
+        transactionId: params.transactionId,
+        status: "failed",
+        error: result.error
+      };
+    }
+    return {
+      success: true,
+      transactionId: params.transactionId,
+      status: result.status ?? "authorized"
+    };
+  }
+  /**
+   * Capture an authorized payment (J5 completion)
+   */
+  async capturePayment(params) {
+    const provider = this.getProvider(params.provider);
+    if (!provider) {
+      return {
+        success: false,
+        status: "failed",
+        error: `Provider ${params.provider} not available`
+      };
+    }
+    const result = await provider.capture({
+      providerIntentId: params.providerIntentId,
+      authorizationCode: params.providerIntentId,
+      amount: params.amount,
+      idempotencyKey: `cap_${params.transactionId}`
+    });
+    if (!result.success) {
+      return {
+        success: false,
+        status: "failed",
+        error: result.error
+      };
+    }
+    return {
+      success: true,
+      status: "captured",
+      capturedAmount: result.capturedAmount
+    };
+  }
+  /**
+   * Get the routing engine (for testing/debugging)
+   */
+  getRoutingEngine() {
+    return this.routingEngine;
+  }
+  /**
+   * Get the circuit breaker (for testing/debugging)
+   */
+  getCircuitBreaker() {
+    return this.circuitBreaker;
+  }
+  /**
+   * Get available providers (for testing/debugging)
+   */
+  getProviders() {
+    return new Map(this.providers);
+  }
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+  getProvider(name) {
+    return this.providers.get(name);
+  }
+  async tryFailover(params, routing, internalPaymentId) {
+    for (const fallback of routing.fallbackProviders) {
+      const provider = this.getProvider(fallback);
+      if (!provider) continue;
+      if (!await this.circuitBreaker.canExecute(fallback)) continue;
+      const result = await provider.createPaymentIntent({
+        amount: params.amount,
+        userId: params.userId,
+        idempotencyKey: `idem_${randomUUID()}`,
+        description: params.description,
+        metadata: params.metadata,
+        returnUrl: params.returnUrl,
+        captureMethod: params.autoCapture ? "automatic" : "manual"
+      });
+      if (result.success) {
+        await this.circuitBreaker.recordSuccess(fallback);
+        return {
+          success: true,
+          transactionId: result.providerIntentId,
+          internalPaymentId,
+          provider: fallback,
+          clientSecret: result.clientSecret
+        };
+      }
+      await this.circuitBreaker.recordFailure(fallback);
+    }
+    return {
+      success: false,
+      transactionId: "",
+      internalPaymentId,
+      provider: routing.provider,
+      error: "All payment providers failed"
+    };
+  }
+};
+
+// src/factory.ts
+function createPaymentServices(options) {
+  const config = options.config ?? createPartialConfig({});
+  const providers = options.providers;
+  const webhookHandlers = options.webhookHandlers ?? /* @__PURE__ */ new Map();
+  if (providers.size === 0) {
+    throw new Error("No payment providers provided. Pass at least one provider instance.");
+  }
+  const circuitBreakerStorage = options.circuitBreakerStorage ?? new InMemoryCircuitBreakerStorage();
+  const circuitBreaker = createCircuitBreaker({
+    storage: circuitBreakerStorage,
+    config: options.circuitBreaker
+  });
+  const routingEngine = createRoutingEngine({
+    config,
+    circuitBreaker,
+    routingRules: options.routingRules
+  });
+  const orchestrator = new PaymentOrchestrator({
+    providers,
+    routingEngine,
+    circuitBreaker
+  });
+  return {
+    orchestrator,
+    routingEngine,
+    circuitBreaker,
+    providers,
+    webhookHandlers,
+    config
+  };
+}
+function registerProvider(services, name, provider, webhookHandler) {
+  const newProviders = new Map(services.providers);
+  newProviders.set(name, provider);
+  const newWebhookHandlers = new Map(services.webhookHandlers);
+  if (webhookHandler) {
+    newWebhookHandlers.set(name, webhookHandler);
+  }
+  const orchestrator = new PaymentOrchestrator({
+    providers: newProviders,
+    routingEngine: services.routingEngine,
+    circuitBreaker: services.circuitBreaker
+  });
+  return {
+    ...services,
+    orchestrator,
+    providers: newProviders,
+    webhookHandlers: newWebhookHandlers
+  };
+}
+var servicesInstance = null;
+function getPaymentServices(config) {
+  if (!servicesInstance) {
+    if (!config) {
+      throw new Error("PaymentServices not initialized. Call with config on first use.");
+    }
+    servicesInstance = createPaymentServices(config);
+  }
+  return servicesInstance;
+}
+function resetPaymentServices() {
+  servicesInstance = null;
+  resetCircuitBreaker();
+  resetRoutingEngine();
+}
+export {
+  createPaymentServices,
+  getPaymentServices,
+  registerProvider,
+  resetPaymentServices
+};
+//# sourceMappingURL=factory.js.map