@nehorai/payments 0.1.0

package/dist/payment-orchestrator-Co_X6T_V.d.cts

@@ -0,0 +1,404 @@
+import { k as PaymentProvider, P as PaymentAmount, i as PaymentMetadata } from './payment-types-68W-PlGg.cjs';
+import { c as TransactionStatus } from './state-machine-Cu6_qKnv.cjs';
+import { c as IRoutingEngine, R as RoutingContext, d as RoutingDecision, I as IPaymentProvider } from './routing-engine.interface-DJzGXor9.cjs';
+import { PaymentConfig } from './config/index.cjs';
+
+/**
+ * @nehorai/payments - Circuit Breaker Storage Interface
+ *
+ * Abstracts storage for circuit breaker state, enabling:
+ * - In-memory storage (default, for single-instance deployments)
+ * - Database storage (for multi-instance/serverless deployments)
+ * - Redis storage (for high-performance distributed systems)
+ */
+
+/**
+ * Circuit breaker states
+ */
+type StoredCircuitState = 'closed' | 'open' | 'half_open';
+/**
+ * Circuit breaker state record
+ *
+ * This is the state that gets persisted by storage implementations.
+ */
+interface CircuitBreakerStateRecord {
+    provider: PaymentProvider;
+    state: StoredCircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailure: Date | null;
+    openedAt: Date | null;
+    nextRetryAt: Date | null;
+}
+/**
+ * Storage interface for circuit breaker state
+ *
+ * Implement this interface to provide custom storage backends:
+ * - InMemoryCircuitBreakerStorage (default)
+ * - Database-backed storage (uses provider_health table)
+ * - Redis-backed storage (for high-performance needs)
+ */
+interface ICircuitBreakerStorage {
+    getState(provider: PaymentProvider): Promise<CircuitBreakerStateRecord | null>;
+    setState(provider: PaymentProvider, state: CircuitBreakerStateRecord): Promise<void>;
+    getAllStates(): Promise<Map<PaymentProvider, CircuitBreakerStateRecord>>;
+    deleteState(provider: PaymentProvider): Promise<void>;
+    getOpenCircuits(): Promise<PaymentProvider[]>;
+    isHealthy(): Promise<boolean>;
+}
+/**
+ * Create default (closed) state for a provider
+ */
+declare function createDefaultState(provider: PaymentProvider): CircuitBreakerStateRecord;
+/**
+ * Check if state indicates circuit is open
+ */
+declare function isCircuitOpen(state: CircuitBreakerStateRecord | null): boolean;
+/**
+ * Check if circuit should attempt half-open transition
+ */
+declare function shouldAttemptHalfOpen(state: CircuitBreakerStateRecord | null): boolean;
+
+/**
+ * @nehorai/payments - Circuit Breaker Service
+ *
+ * Implements the circuit breaker pattern for payment provider resilience.
+ * Prevents cascading failures by temporarily disabling unhealthy providers.
+ *
+ * States:
+ * - CLOSED: Normal operation, all requests pass through
+ * - OPEN: Provider disabled, all requests fail fast
+ * - HALF_OPEN: Testing if provider recovered
+ */
+
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time in ms before attempting to close circuit */
+    resetTimeoutMs: number;
+    /** Max requests allowed in half-open state */
+    halfOpenMaxRequests: number;
+}
+type CircuitState = 'closed' | 'open' | 'half_open';
+interface CircuitBreakerState {
+    provider: PaymentProvider;
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailure: Date | null;
+    openedAt: Date | null;
+    nextRetryAt: Date | null;
+}
+/**
+ * Circuit breaker dependencies (for dependency injection)
+ */
+interface CircuitBreakerDeps {
+    /** Storage implementation (optional, defaults to in-memory) */
+    storage?: ICircuitBreakerStorage;
+    /** Configuration overrides */
+    config?: Partial<CircuitBreakerConfig>;
+}
+declare class CircuitBreaker {
+    private config;
+    private storage;
+    constructor(deps?: CircuitBreakerDeps);
+    /**
+     * Check if a request can be executed for a provider
+     */
+    canExecute(provider: PaymentProvider): Promise<boolean>;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(provider: PaymentProvider): Promise<void>;
+    /**
+     * Record a failed request
+     */
+    recordFailure(provider: PaymentProvider): Promise<void>;
+    /**
+     * Get current state for a provider
+     */
+    getState(provider: PaymentProvider): Promise<CircuitBreakerState>;
+    /**
+     * Check if circuit is open (provider unavailable)
+     */
+    isOpen(provider: PaymentProvider): boolean;
+    /**
+     * Async version of isOpen
+     */
+    isOpenAsync(provider: PaymentProvider): Promise<boolean>;
+    /**
+     * Manually reset a provider's circuit
+     */
+    reset(provider: PaymentProvider): Promise<void>;
+    /**
+     * Get all providers with open circuits
+     */
+    getOpenCircuits(): Promise<PaymentProvider[]>;
+    /**
+     * Get the storage instance (useful for testing)
+     */
+    getStorage(): ICircuitBreakerStorage;
+    /**
+     * Get configuration (useful for testing)
+     */
+    getConfig(): CircuitBreakerConfig;
+    private transitionTo;
+    /**
+     * Synchronous check for backward compatibility
+     * Note: This always returns false for database-backed storage
+     */
+    private isOpenSync;
+}
+/**
+ * Get or create singleton CircuitBreaker instance
+ */
+declare function getCircuitBreaker(config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+/**
+ * Create a new CircuitBreaker with custom dependencies
+ */
+declare function createCircuitBreaker(deps?: CircuitBreakerDeps): CircuitBreaker;
+/**
+ * Reset the singleton instance (useful for testing)
+ */
+declare function resetCircuitBreaker(): void;
+
+/**
+ * @nehorai/payments - Routing Engine Service
+ *
+ * Intelligent payment routing based on configurable rules:
+ * - Card BIN rules (match card ranges to preferred providers)
+ * - Provider health (circuit breaker state)
+ * - Transaction fees / provider priorities
+ * - Currency support
+ *
+ * Unlike the Podcasto-specific version, this accepts generic RoutingRules
+ * config instead of hardcoded Israeli card BIN ranges.
+ */
+
+/**
+ * Rule for matching card BIN ranges to preferred providers
+ */
+interface CardBinRule {
+    ranges: Array<{
+        start: string;
+        end: string;
+        issuer?: string;
+        country?: string;
+    }>;
+    preferredProvider: string;
+    priority?: number;
+}
+/**
+ * Provider priority configuration
+ */
+interface ProviderPriorityRule {
+    provider: string;
+    priority: number;
+    maxFeePercent: number;
+    supportsCurrency: string[];
+    supportsRecurring: boolean;
+    isLocalGateway?: boolean;
+}
+/**
+ * Currency-specific routing rule
+ */
+interface CurrencyRule {
+    currency: string;
+    preferredProvider: string;
+}
+/**
+ * Generic routing rules configuration.
+ * Injected at construction time instead of hardcoded.
+ */
+interface RoutingRules {
+    cardBinRules?: CardBinRule[];
+    providerPriorities?: ProviderPriorityRule[];
+    currencyRules?: CurrencyRule[];
+}
+/**
+ * Routing engine dependencies (for dependency injection)
+ */
+interface RoutingEngineDeps {
+    /** Payment configuration (optional, defaults to empty config) */
+    config?: PaymentConfig;
+    /** Circuit breaker instance (optional, defaults to singleton) */
+    circuitBreaker?: CircuitBreaker;
+    /** Routing rules (optional, no rules means simple round-robin) */
+    routingRules?: RoutingRules;
+}
+/**
+ * Routing Engine Implementation
+ *
+ * Routes payments to optimal providers with automatic failover.
+ * Uses injected RoutingRules instead of hardcoded locale-specific logic.
+ */
+declare class RoutingEngine implements IRoutingEngine {
+    private config;
+    private circuitBreaker;
+    private routingRules;
+    constructor(deps?: RoutingEngineDeps);
+    /**
+     * Determine optimal provider for a transaction
+     */
+    route(context: RoutingContext): Promise<RoutingDecision>;
+    /**
+     * Get next provider after a failure
+     */
+    getFailoverProvider(failedProvider: PaymentProvider, _context: RoutingContext): Promise<PaymentProvider | null>;
+    /**
+     * Check if a card BIN matches any configured rule
+     */
+    matchCardBin(bin: string): boolean;
+    /**
+     * Get all available (healthy) providers
+     */
+    getAvailableProviders(): Promise<PaymentProvider[]>;
+    /**
+     * Quick recommendation without full context
+     */
+    getQuickRecommendation(currency: string, isRecurring: boolean): Promise<PaymentProvider | null>;
+    /**
+     * Get current configuration (for testing/debugging)
+     */
+    getConfig(): PaymentConfig;
+    /**
+     * Get circuit breaker instance (for testing/debugging)
+     */
+    getCircuitBreaker(): CircuitBreaker;
+    /**
+     * Get routing rules (for testing/debugging)
+     */
+    getRoutingRules(): RoutingRules;
+    private getProviderList;
+    private getHealthyProviders;
+    private routeToSavedMethodProvider;
+    private getFallbackProviders;
+    private getProviderFee;
+}
+/**
+ * Get or create singleton RoutingEngine instance
+ */
+declare function getRoutingEngine(): RoutingEngine;
+/**
+ * Create a new RoutingEngine with custom dependencies
+ */
+declare function createRoutingEngine(deps?: RoutingEngineDeps): RoutingEngine;
+/**
+ * Reset the singleton instance (useful for testing)
+ */
+declare function resetRoutingEngine(): void;
+
+/**
+ * @nehorai/payments - Payment Orchestrator Service
+ *
+ * Main entry point for payment operations. Coordinates between:
+ * - Routing Engine (provider selection)
+ * - Payment Providers (actual processing)
+ * - Circuit Breaker (resilience)
+ *
+ * Supports full dependency injection for:
+ * - Provider instances
+ * - Routing engine
+ * - Circuit breaker
+ */
+
+interface InitiatePaymentParams {
+    userId: string;
+    amount: PaymentAmount;
+    transactionType: 'one_time_purchase' | 'subscription_initial' | 'subscription_renewal';
+    description?: string;
+    metadata?: PaymentMetadata;
+    preferredProvider?: PaymentProvider;
+    cardBin?: string;
+    returnUrl: string;
+    /** If true, auto-capture immediately (no J5 hold) */
+    autoCapture?: boolean;
+}
+interface PaymentInitiationResult {
+    success: boolean;
+    transactionId: string;
+    internalPaymentId: string;
+    provider: PaymentProvider;
+    clientSecret?: string;
+    redirectUrl?: string;
+    error?: string;
+}
+interface ConfirmPaymentParams {
+    transactionId: string;
+    internalPaymentId: string;
+    providerIntentId: string;
+    provider: PaymentProvider;
+}
+interface PaymentConfirmationResult {
+    success: boolean;
+    transactionId: string;
+    status: TransactionStatus;
+    error?: string;
+}
+interface CapturePaymentParams {
+    transactionId: string;
+    providerIntentId: string;
+    provider: PaymentProvider;
+    amount?: PaymentAmount;
+}
+interface PaymentCaptureResult {
+    success: boolean;
+    status: TransactionStatus;
+    capturedAmount?: PaymentAmount;
+    error?: string;
+}
+/**
+ * Payment orchestrator dependencies (for dependency injection)
+ */
+interface PaymentOrchestratorDeps {
+    /** Provider instances - required */
+    providers: Map<PaymentProvider, IPaymentProvider>;
+    /** Routing engine (optional, defaults to singleton) */
+    routingEngine?: RoutingEngine;
+    /** Circuit breaker (optional, defaults to singleton) */
+    circuitBreaker?: CircuitBreaker;
+}
+/**
+ * Payment Orchestrator
+ *
+ * Standalone service for payment orchestration.
+ * Supports full dependency injection for testing and customization.
+ */
+declare class PaymentOrchestrator {
+    private providers;
+    private routingEngine;
+    private circuitBreaker;
+    constructor(deps: PaymentOrchestratorDeps);
+    /**
+     * Initiate a new payment
+     */
+    initiatePayment(params: InitiatePaymentParams): Promise<PaymentInitiationResult>;
+    /**
+     * Confirm a payment after user authorization
+     */
+    confirmPayment(params: ConfirmPaymentParams): Promise<PaymentConfirmationResult>;
+    /**
+     * Capture an authorized payment (J5 completion)
+     */
+    capturePayment(params: CapturePaymentParams): Promise<PaymentCaptureResult>;
+    /**
+     * Get the routing engine (for testing/debugging)
+     */
+    getRoutingEngine(): RoutingEngine;
+    /**
+     * Get the circuit breaker (for testing/debugging)
+     */
+    getCircuitBreaker(): CircuitBreaker;
+    /**
+     * Get available providers (for testing/debugging)
+     */
+    getProviders(): Map<PaymentProvider, IPaymentProvider>;
+    private getProvider;
+    private tryFailover;
+}
+/**
+ * Create a payment orchestrator with custom dependencies
+ */
+declare function createPaymentOrchestrator(deps: PaymentOrchestratorDeps): PaymentOrchestrator;
+
+export { shouldAttemptHalfOpen as A, type CardBinRule as C, type ICircuitBreakerStorage as I, type PaymentCaptureResult as P, RoutingEngine as R, type StoredCircuitState as S, CircuitBreaker as a, type CircuitBreakerConfig as b, type CircuitBreakerDeps as c, type CircuitBreakerState as d, type CircuitBreakerStateRecord as e, type CircuitState as f, type ConfirmPaymentParams as g, type CurrencyRule as h, type InitiatePaymentParams as i, type CapturePaymentParams as j, type PaymentConfirmationResult as k, type PaymentInitiationResult as l, PaymentOrchestrator as m, type PaymentOrchestratorDeps as n, type ProviderPriorityRule as o, type RoutingEngineDeps as p, type RoutingRules as q, createCircuitBreaker as r, createDefaultState as s, createPaymentOrchestrator as t, createRoutingEngine as u, getCircuitBreaker as v, getRoutingEngine as w, isCircuitOpen as x, resetCircuitBreaker as y, resetRoutingEngine as z };

package/dist/payment-types-68W-PlGg.d.cts

@@ -0,0 +1,211 @@
+/**
+ * @nehorai/payments - Core Payment Types
+ *
+ * Defines the fundamental types for the payment system.
+ * Follows TypeScript conventions with literal union types.
+ */
+/**
+ * Supported payment providers - extensible string identifier
+ */
+type PaymentProvider = string;
+/**
+ * Types of payment transactions
+ */
+type TransactionType = 'one_time_purchase' | 'subscription_initial' | 'subscription_renewal' | 'refund';
+/**
+ * Tax invoice status
+ */
+type TaxInvoiceStatus = 'pending' | 'generated' | 'sent' | 'failed';
+/**
+ * Payment method types
+ */
+type PaymentMethodType = 'card' | 'bank_account' | 'paypal';
+/**
+ * Card brands supported
+ */
+type CardBrand = 'visa' | 'mastercard' | 'amex' | 'discover' | 'isracard' | 'diners' | 'unknown';
+/**
+ * Monetary amount in smallest currency unit (cents, agorot, etc.)
+ * Zero Trust: All amounts validated server-side, never trust client
+ */
+interface PaymentAmount {
+    /** Amount in smallest currency unit (e.g., 1000 = $10.00) */
+    amountMinor: number;
+    /** ISO 4217 currency code (e.g., 'USD', 'ILS') */
+    currency: string;
+}
+/**
+ * Result of currency conversion
+ */
+interface CurrencyConversion {
+    originalAmount: PaymentAmount;
+    convertedAmount: PaymentAmount;
+    exchangeRate: number;
+    convertedAt: Date;
+}
+/**
+ * Parameters for creating a payment intent
+ */
+interface CreatePaymentIntentParams {
+    amount: PaymentAmount;
+    userId: string;
+    idempotencyKey: string;
+    description?: string;
+    metadata?: PaymentMetadata;
+    returnUrl?: string;
+    paymentMethodId?: string;
+    /** If true, only authorize (J5 hold), don't capture */
+    captureMethod?: 'automatic' | 'manual';
+}
+/**
+ * Result from creating a payment intent
+ */
+interface PaymentIntentResult {
+    success: boolean;
+    /** Provider's payment intent ID */
+    providerIntentId?: string;
+    /** Client secret for frontend SDK (Stripe Elements) */
+    clientSecret?: string;
+    /** Redirect URL for redirect-based flows */
+    redirectUrl?: string;
+    /** Current status of the payment */
+    status?: string;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for authorizing a payment (J5 hold)
+ */
+interface AuthorizePaymentParams {
+    providerIntentId: string;
+    idempotencyKey: string;
+}
+/**
+ * Result from authorization
+ */
+interface AuthorizationResult {
+    success: boolean;
+    /** Authorization code for capture */
+    authorizationCode?: string;
+    status?: string;
+    /** Deadline to capture before auth expires (typically 7 days) */
+    captureDeadline?: Date;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for capturing an authorized payment
+ */
+interface CapturePaymentParams {
+    providerIntentId: string;
+    authorizationCode: string;
+    /** For partial capture */
+    amount?: PaymentAmount;
+    idempotencyKey: string;
+}
+/**
+ * Result from capture
+ */
+interface CaptureResult {
+    success: boolean;
+    providerTransactionId?: string;
+    status?: string;
+    capturedAmount?: PaymentAmount;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * Parameters for voiding an authorization
+ */
+interface VoidPaymentParams {
+    providerIntentId: string;
+    authorizationCode: string;
+    idempotencyKey: string;
+    reason?: string;
+}
+/**
+ * Result from void
+ */
+interface VoidResult {
+    success: boolean;
+    status?: string;
+    error?: string;
+}
+/**
+ * Parameters for refunding a payment
+ */
+interface RefundParams {
+    providerTransactionId: string;
+    /** For partial refund */
+    amount?: PaymentAmount;
+    reason?: string;
+    idempotencyKey: string;
+}
+/**
+ * Result from refund
+ */
+interface RefundResult {
+    success: boolean;
+    providerRefundId?: string;
+    refundedAmount?: PaymentAmount;
+    status?: 'pending' | 'succeeded' | 'failed';
+    error?: string;
+}
+/**
+ * Application-specific metadata attached to payments
+ */
+interface PaymentMetadata {
+    /** Credit package being purchased */
+    creditPackageId?: string;
+    /** Subscription plan being purchased */
+    subscriptionPlanId?: string;
+    /** Number of credits being purchased */
+    creditsAmount?: number;
+    /** Custom fields */
+    [key: string]: unknown;
+}
+/**
+ * Provider-specific metadata (raw response data)
+ */
+interface ProviderMetadata {
+    /** Raw response from provider for debugging */
+    rawResponse?: Record<string, unknown>;
+    /** Provider-specific transaction ID */
+    providerTransactionId?: string;
+    /** Provider-specific authorization code */
+    authorizationCode?: string;
+    /** Additional provider data */
+    [key: string]: unknown;
+}
+/**
+ * Provider health status for circuit breaker
+ */
+interface ProviderHealthStatus {
+    provider: PaymentProvider;
+    healthy: boolean;
+    lastChecked: Date;
+    /** Average response time in milliseconds */
+    avgLatencyMs?: number;
+    /** Error rate (0-1) */
+    errorRate?: number;
+    /** Whether circuit breaker is open */
+    circuitBreakerOpen: boolean;
+    /** When circuit breaker will attempt to close */
+    nextRetryAt?: Date;
+}
+/**
+ * Standardized payment error codes
+ */
+type PaymentErrorCode = 'insufficient_funds' | 'invalid_card' | 'expired_card' | 'card_declined' | 'processing_error' | 'provider_timeout' | 'provider_unavailable' | 'rate_limit' | 'webhook_signature_invalid' | 'idempotency_conflict' | 'invalid_amount' | 'invalid_currency' | 'authentication_required' | 'unknown';
+/**
+ * Payment error with structured information
+ */
+interface PaymentError {
+    code: PaymentErrorCode;
+    message: string;
+    provider?: PaymentProvider;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+
+export type { AuthorizationResult as A, CapturePaymentParams as C, PaymentAmount as P, RefundParams as R, TaxInvoiceStatus as T, VoidPaymentParams as V, AuthorizePaymentParams as a, CaptureResult as b, CardBrand as c, CreatePaymentIntentParams as d, CurrencyConversion as e, PaymentError as f, PaymentErrorCode as g, PaymentIntentResult as h, PaymentMetadata as i, PaymentMethodType as j, PaymentProvider as k, ProviderHealthStatus as l, ProviderMetadata as m, RefundResult as n, TransactionType as o, VoidResult as p };