@nehorai/payments 0.1.0

package/dist/index.js

@@ -0,0 +1,1260 @@
+// src/services/payment-orchestrator.ts
+import { randomUUID } from "crypto";
+
+// src/config/payment-config.ts
+function createConfigFromEnv(mapping) {
+  if (!mapping) {
+    return createPartialConfig({});
+  }
+  const providers = {};
+  for (const providerMapping of mapping.providers) {
+    const config = {};
+    let hasValue = false;
+    for (const [configKey, envVarName] of Object.entries(providerMapping.keys)) {
+      const value = process.env[envVarName];
+      if (value?.trim()) {
+        config[configKey] = value;
+        hasValue = true;
+      }
+    }
+    if (providerMapping.requiredKeys) {
+      const allRequired = providerMapping.requiredKeys.every(
+        (key) => config[key] && typeof config[key] === "string" && config[key].trim()
+      );
+      if (allRequired) {
+        providers[providerMapping.providerName] = config;
+      }
+    } else if (hasValue) {
+      providers[providerMapping.providerName] = config;
+    }
+  }
+  const environment = process.env[mapping.environmentVar ?? "PAYMENT_ENVIRONMENT"] ?? "sandbox";
+  const defaultCurrency = process.env[mapping.defaultCurrencyVar ?? "DEFAULT_CURRENCY"] ?? "USD";
+  return {
+    providers,
+    environment,
+    defaultCurrency
+  };
+}
+function createConfig(config) {
+  validateConfig(config);
+  return {
+    providers: { ...config.providers },
+    environment: config.environment,
+    defaultCurrency: config.defaultCurrency
+  };
+}
+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;
+}
+function getConfiguredProviderList(config) {
+  const availability = getConfiguredProviders(config);
+  return Object.entries(availability).filter(([, isAvailable]) => isAvailable).map(([name]) => name);
+}
+function isProductionReady(config) {
+  const providers = getConfiguredProviderList(config);
+  return config.environment === "production" && providers.length > 0;
+}
+function validateConfig(config) {
+  const providers = getConfiguredProviderList(config);
+  if (providers.length === 0) {
+    throw new Error(
+      "Payment configuration error: At least one payment provider must be configured"
+    );
+  }
+}
+
+// src/services/circuit-breaker-storage.interface.ts
+function createDefaultState(provider) {
+  return {
+    provider,
+    state: "closed",
+    failureCount: 0,
+    successCount: 0,
+    lastFailure: null,
+    openedAt: null,
+    nextRetryAt: null
+  };
+}
+function isCircuitOpen(state) {
+  return state?.state === "open";
+}
+function shouldAttemptHalfOpen(state) {
+  if (!state || state.state !== "open") return false;
+  if (!state.nextRetryAt) return false;
+  return Date.now() >= state.nextRetryAt.getTime();
+}
+
+// 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;
+  }
+};
+var defaultStorage = null;
+function getInMemoryStorage() {
+  if (!defaultStorage) {
+    defaultStorage = new InMemoryCircuitBreakerStorage();
+  }
+  return defaultStorage;
+}
+function resetInMemoryStorage() {
+  if (defaultStorage) {
+    defaultStorage.clear();
+  }
+  defaultStorage = null;
+}
+async function migrateFromLegacyMap(legacyStates) {
+  const storage = new InMemoryCircuitBreakerStorage();
+  for (const [provider, state] of legacyStates) {
+    const record = {
+      provider: state.provider,
+      state: state.state,
+      failureCount: state.failureCount,
+      successCount: state.successCount,
+      lastFailure: state.lastFailure,
+      openedAt: state.openedAt,
+      nextRetryAt: state.nextRetryAt
+    };
+    await storage.setState(provider, record);
+  }
+  return storage;
+}
+
+// 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 defaultStorage2 = null;
+function getCircuitBreaker(config) {
+  if (!circuitBreakerInstance) {
+    if (!defaultStorage2) {
+      defaultStorage2 = new InMemoryCircuitBreakerStorage();
+    }
+    circuitBreakerInstance = new CircuitBreaker({
+      storage: defaultStorage2,
+      config
+    });
+  }
+  return circuitBreakerInstance;
+}
+function createCircuitBreaker(deps = {}) {
+  return new CircuitBreaker(deps);
+}
+function resetCircuitBreaker() {
+  circuitBreakerInstance = null;
+  if (defaultStorage2) {
+    defaultStorage2.clear();
+  }
+  defaultStorage2 = 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"
+    };
+  }
+};
+function createPaymentOrchestrator(deps) {
+  return new PaymentOrchestrator(deps);
+}
+
+// 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();
+}
+
+// src/types/state-machine.ts
+var TERMINAL_STATES = [
+  "voided",
+  "failed",
+  "expired",
+  "fully_refunded"
+];
+var SUCCESS_STATES = [
+  "captured",
+  "partially_refunded",
+  "fully_refunded"
+];
+var HOLD_STATES = [
+  "authorized"
+];
+var VALID_TRANSITIONS = {
+  created: ["INITIATE", "AUTHORIZE_PENDING", "AUTHORIZE_FAILED"],
+  pending_authorization: ["AUTHORIZE_SUCCESS", "AUTHORIZE_FAILED", "EXPIRED"],
+  authorized: ["CAPTURE_STARTED", "VOID_SUCCESS", "VOID_FAILED", "EXPIRED"],
+  capturing: ["CAPTURE_SUCCESS", "CAPTURE_FAILED"],
+  captured: ["PARTIAL_REFUND", "FULL_REFUND"],
+  voided: [],
+  // Terminal state
+  failed: [],
+  // Terminal state
+  expired: [],
+  // Terminal state
+  partially_refunded: ["PARTIAL_REFUND", "FULL_REFUND"],
+  fully_refunded: []
+  // Terminal state
+};
+var EVENT_TO_STATE = {
+  INITIATE: "pending_authorization",
+  AUTHORIZE_PENDING: "pending_authorization",
+  AUTHORIZE_SUCCESS: "authorized",
+  AUTHORIZE_FAILED: "failed",
+  CAPTURE_STARTED: "capturing",
+  CAPTURE_SUCCESS: "captured",
+  CAPTURE_FAILED: "failed",
+  VOID_SUCCESS: "voided",
+  VOID_FAILED: "authorized",
+  // Remain authorized if void fails
+  EXPIRED: "expired",
+  PARTIAL_REFUND: "partially_refunded",
+  FULL_REFUND: "fully_refunded"
+};
+function canTransition(currentStatus, event) {
+  return VALID_TRANSITIONS[currentStatus].includes(event);
+}
+function getNextStatus(currentStatus, event) {
+  if (!canTransition(currentStatus, event)) {
+    return null;
+  }
+  return EVENT_TO_STATE[event];
+}
+function isTerminalState(status) {
+  return TERMINAL_STATES.includes(status);
+}
+function isSuccessState(status) {
+  return SUCCESS_STATES.includes(status);
+}
+function isHoldState(status) {
+  return HOLD_STATES.includes(status);
+}
+function canRefund(status) {
+  return status === "captured" || status === "partially_refunded";
+}
+function canCapture(status) {
+  return status === "authorized";
+}
+function canVoid(status) {
+  return status === "authorized";
+}
+function attemptTransition(currentStatus, event) {
+  const nextStatus = getNextStatus(currentStatus, event);
+  if (nextStatus === null) {
+    return {
+      success: false,
+      previousStatus: currentStatus,
+      newStatus: currentStatus,
+      event,
+      error: `Invalid transition: ${currentStatus} -> ${event}`
+    };
+  }
+  return {
+    success: true,
+    previousStatus: currentStatus,
+    newStatus: nextStatus,
+    event
+  };
+}
+var DEFAULT_AUTH_HOLD_DAYS = 7;
+function calculateCaptureDeadline(authorizedAt, holdDays = DEFAULT_AUTH_HOLD_DAYS) {
+  const deadline = new Date(authorizedAt);
+  deadline.setDate(deadline.getDate() + holdDays);
+  return deadline;
+}
+function isAuthorizationExpired(captureDeadline) {
+  return /* @__PURE__ */ new Date() > captureDeadline;
+}
+
+// src/utils/idempotency.ts
+import { randomUUID as randomUUID2, createHash } from "crypto";
+function generateInternalPaymentId() {
+  return `pay_${randomUUID2()}`;
+}
+function generateIdempotencyKey() {
+  return `idem_${randomUUID2()}`;
+}
+function generateDeterministicKey(...components) {
+  const data = components.join(":");
+  const hash = createHash("sha256").update(data).digest("hex");
+  return `idem_${hash.substring(0, 32)}`;
+}
+function generateOperationKey(operation, transactionId) {
+  return `${operation}_${transactionId}`;
+}
+function isValidIdempotencyKey(key) {
+  return /^idem_[a-f0-9-]{32,36}$/.test(key);
+}
+function isValidInternalPaymentId(id) {
+  return /^pay_[a-f0-9-]{36}$/.test(id);
+}
+
+// src/utils/signature-verification.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyStripeStyleSignature(payload, signature, secret, tolerance) {
+  try {
+    const elements = signature.split(",");
+    const timestamp = elements.find((e) => e.startsWith("t="))?.slice(2);
+    const sig = elements.find((e) => e.startsWith("v1="))?.slice(3);
+    if (!timestamp || !sig) {
+      return { valid: false, error: "Invalid signature format" };
+    }
+    const timestampNum = parseInt(timestamp, 10);
+    const now = Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - timestampNum) > tolerance) {
+      return { valid: false, error: "Timestamp outside tolerance" };
+    }
+    const signedPayload = `${timestamp}.${payload}`;
+    const expectedSig = createHmac("sha256", secret).update(signedPayload).digest("hex");
+    const valid = timingSafeEqual(
+      Buffer.from(sig),
+      Buffer.from(expectedSig)
+    );
+    return { valid };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : "Verification failed"
+    };
+  }
+}
+function verifySortedFieldsHmacSignature(payload, signature, secret, _tolerance) {
+  try {
+    const data = JSON.parse(payload);
+    const sortedKeys = Object.keys(data).sort();
+    const sortedPayload = sortedKeys.map((k) => `${k}=${data[k]}`).join("&");
+    const expectedSig = createHmac("sha256", secret).update(sortedPayload).digest("hex");
+    const valid = timingSafeEqual(
+      Buffer.from(signature.toLowerCase()),
+      Buffer.from(expectedSig)
+    );
+    return { valid };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : "Verification failed"
+    };
+  }
+}
+function verifyHmacSha256Signature(payload, signature, secret, _tolerance) {
+  try {
+    const expectedSig = createHmac("sha256", secret).update(payload).digest("hex");
+    const valid = timingSafeEqual(
+      Buffer.from(signature.toLowerCase()),
+      Buffer.from(expectedSig.toLowerCase())
+    );
+    return { valid };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : "Verification failed"
+    };
+  }
+}
+var verifierRegistry = /* @__PURE__ */ new Map();
+function registerSignatureVerifier(provider, verifier) {
+  verifierRegistry.set(provider, verifier);
+}
+function getSignatureVerifier(provider) {
+  return verifierRegistry.get(provider);
+}
+function verifyWebhookSignature(params) {
+  const { provider, payload, signature, secret, tolerance = 300 } = params;
+  if (!signature || !secret) {
+    return { valid: false, error: "Missing signature or secret" };
+  }
+  const verifier = verifierRegistry.get(provider);
+  if (verifier) {
+    return verifier(payload, signature, secret, tolerance);
+  }
+  return verifyHmacSha256Signature(payload, signature, secret, tolerance);
+}
+function getSignatureHeaderName(provider) {
+  return `x-${provider}-signature`;
+}
+
+// src/repository/memory/in-memory-transaction.ts
+import { randomUUID as randomUUID3 } from "crypto";
+var InMemoryTransactionRepository = class {
+  transactions = /* @__PURE__ */ new Map();
+  async findById(id) {
+    return this.transactions.get(id) ?? null;
+  }
+  async create(data) {
+    const now = /* @__PURE__ */ new Date();
+    const transaction = {
+      id: randomUUID3(),
+      internalPaymentId: data.internalPaymentId,
+      idempotencyKey: data.idempotencyKey ?? null,
+      userId: data.userId,
+      transactionType: data.transactionType,
+      status: data.status ?? "created",
+      amountMinor: data.amountMinor,
+      currency: data.currency,
+      originalAmountMinor: null,
+      originalCurrency: null,
+      currencyConversionRate: null,
+      provider: data.provider,
+      providerTransactionId: null,
+      providerAuthorizationCode: null,
+      providerMetadata: null,
+      authorizedAt: null,
+      capturedAt: null,
+      voidedAt: null,
+      captureDeadline: null,
+      refundedAmountMinor: 0,
+      lastRefundAt: null,
+      taxInvoiceStatus: "pending",
+      taxInvoiceNumber: null,
+      taxInvoiceUrl: null,
+      failureCode: null,
+      failureMessage: null,
+      failureDetails: null,
+      description: data.description ?? null,
+      metadata: data.metadata ?? null,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.transactions.set(transaction.id, transaction);
+    return transaction;
+  }
+  async update(id, data) {
+    const existing = this.transactions.get(id);
+    if (!existing) return null;
+    const updated = {
+      ...existing,
+      ...data,
+      updatedAt: /* @__PURE__ */ new Date()
+    };
+    this.transactions.set(id, updated);
+    return updated;
+  }
+  async delete(id) {
+    return this.transactions.delete(id);
+  }
+  async findByInternalPaymentId(internalPaymentId) {
+    for (const tx of this.transactions.values()) {
+      if (tx.internalPaymentId === internalPaymentId) return tx;
+    }
+    return null;
+  }
+  async findByIdempotencyKey(idempotencyKey) {
+    for (const tx of this.transactions.values()) {
+      if (tx.idempotencyKey === idempotencyKey) return tx;
+    }
+    return null;
+  }
+  async findByProviderTransactionId(provider, providerTransactionId) {
+    for (const tx of this.transactions.values()) {
+      if (tx.provider === provider && tx.providerTransactionId === providerTransactionId) return tx;
+    }
+    return null;
+  }
+  async findMany(filter, pagination) {
+    let results = Array.from(this.transactions.values());
+    if (filter.userId) results = results.filter((t) => t.userId === filter.userId);
+    if (filter.status) {
+      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+      results = results.filter((t) => statuses.includes(t.status));
+    }
+    if (filter.provider) {
+      const providers = Array.isArray(filter.provider) ? filter.provider : [filter.provider];
+      results = results.filter((t) => providers.includes(t.provider));
+    }
+    const total = results.length;
+    const limit = pagination?.limit ?? 50;
+    const offset = pagination?.offset ?? 0;
+    const data = results.slice(offset, offset + limit);
+    return { data, total, limit, offset, hasMore: offset + limit < total };
+  }
+  async findByUserId(userId, pagination) {
+    return this.findMany({ userId }, pagination);
+  }
+  async updateStatus(id, status, additionalData) {
+    return this.update(id, { ...additionalData, status });
+  }
+  async incrementRefundedAmount(id, amountMinor) {
+    const existing = this.transactions.get(id);
+    if (!existing) return null;
+    return this.update(id, {
+      refundedAmountMinor: existing.refundedAmountMinor + amountMinor,
+      lastRefundAt: /* @__PURE__ */ new Date()
+    });
+  }
+  async findExpiredAuthorizations(beforeDate) {
+    return Array.from(this.transactions.values()).filter(
+      (t) => t.status === "authorized" && t.captureDeadline && t.captureDeadline < beforeDate
+    );
+  }
+  async countByStatus(_filter) {
+    const counts = {};
+    for (const tx of this.transactions.values()) {
+      counts[tx.status] = (counts[tx.status] ?? 0) + 1;
+    }
+    return counts;
+  }
+  /** Clear all stored transactions (useful for testing) */
+  clear() {
+    this.transactions.clear();
+  }
+};
+export {
+  CircuitBreaker,
+  InMemoryCircuitBreakerStorage,
+  InMemoryTransactionRepository,
+  PaymentOrchestrator,
+  RoutingEngine,
+  SUCCESS_STATES,
+  TERMINAL_STATES,
+  attemptTransition,
+  calculateCaptureDeadline,
+  canCapture,
+  canRefund,
+  canTransition,
+  canVoid,
+  createCircuitBreaker,
+  createConfig,
+  createConfigFromEnv,
+  createDefaultState,
+  createPartialConfig,
+  createPaymentOrchestrator,
+  createPaymentServices,
+  createRoutingEngine,
+  generateDeterministicKey,
+  generateIdempotencyKey,
+  generateInternalPaymentId,
+  generateOperationKey,
+  getCircuitBreaker,
+  getConfiguredProviderList,
+  getConfiguredProviders,
+  getInMemoryStorage,
+  getNextStatus,
+  getPaymentServices,
+  getRoutingEngine,
+  getSignatureHeaderName,
+  getSignatureVerifier,
+  isAuthorizationExpired,
+  isCircuitOpen,
+  isHoldState,
+  isProductionReady,
+  isSuccessState,
+  isTerminalState,
+  isValidIdempotencyKey,
+  isValidInternalPaymentId,
+  migrateFromLegacyMap,
+  registerProvider,
+  registerSignatureVerifier,
+  resetCircuitBreaker,
+  resetInMemoryStorage,
+  resetPaymentServices,
+  resetRoutingEngine,
+  shouldAttemptHalfOpen,
+  validateConfig,
+  verifyHmacSha256Signature,
+  verifySortedFieldsHmacSignature,
+  verifyStripeStyleSignature,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=index.js.map