@nehorai/payments 0.1.0

package/dist/routing-engine.interface-DJzGXor9.d.cts

@@ -0,0 +1,194 @@
+import { k as PaymentProvider, d as CreatePaymentIntentParams, h as PaymentIntentResult, a as AuthorizePaymentParams, A as AuthorizationResult, C as CapturePaymentParams, b as CaptureResult, V as VoidPaymentParams, p as VoidResult, R as RefundParams, n as RefundResult, l as ProviderHealthStatus, P as PaymentAmount } from './payment-types-68W-PlGg.cjs';
+
+/**
+ * @nehorai/payments - Payment Provider Interface
+ *
+ * Defines the contract that all payment provider adapters must implement.
+ * Supports Two-Phase Commit (J5) pattern: Authorize -> Capture/Void
+ */
+
+/**
+ * Parameters for saving a payment method
+ */
+interface SavePaymentMethodParams {
+    userId: string;
+    /** Provider-specific setup data (e.g., SetupIntent confirmation) */
+    setupData: Record<string, unknown>;
+}
+/**
+ * Result of saving a payment method
+ */
+interface SavePaymentMethodResult {
+    success: boolean;
+    paymentMethodId?: string;
+    cardBrand?: string;
+    cardLast4?: string;
+    cardExpMonth?: string;
+    cardExpYear?: string;
+    cardBin?: string;
+    error?: string;
+}
+/**
+ * Result of deleting a payment method
+ */
+interface DeletePaymentMethodResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Parameters for creating a setup intent
+ */
+interface CreateSetupIntentParams {
+    userId: string;
+    /** Customer ID in provider system */
+    customerId?: string;
+}
+/**
+ * Result of creating a setup intent
+ */
+interface SetupIntentResult {
+    success: boolean;
+    setupIntentId?: string;
+    clientSecret?: string;
+    error?: string;
+}
+/**
+ * Parameters for creating a customer
+ */
+interface CreateCustomerParams {
+    userId: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Result of creating a customer
+ */
+interface CreateCustomerResult {
+    success: boolean;
+    customerId?: string;
+    error?: string;
+}
+/**
+ * Payment Provider Interface
+ *
+ * All payment provider adapters must implement this interface.
+ * Enables the adapter pattern for multi-provider support.
+ */
+interface IPaymentProvider {
+    /**
+     * Provider identifier
+     */
+    readonly name: PaymentProvider;
+    /**
+     * Supported currencies (ISO 4217 codes)
+     */
+    readonly supportedCurrencies: readonly string[];
+    /**
+     * Whether provider supports recurring billing
+     */
+    readonly supportsRecurring: boolean;
+    /**
+     * Whether provider supports split payments (marketplace)
+     */
+    readonly supportsSplitPayments: boolean;
+    createPaymentIntent(params: CreatePaymentIntentParams): Promise<PaymentIntentResult>;
+    authorize(params: AuthorizePaymentParams): Promise<AuthorizationResult>;
+    capture(params: CapturePaymentParams): Promise<CaptureResult>;
+    void(params: VoidPaymentParams): Promise<VoidResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    createSetupIntent(params: CreateSetupIntentParams): Promise<SetupIntentResult>;
+    savePaymentMethod(params: SavePaymentMethodParams): Promise<SavePaymentMethodResult>;
+    deletePaymentMethod(paymentMethodId: string): Promise<DeletePaymentMethodResult>;
+    createCustomer(params: CreateCustomerParams): Promise<CreateCustomerResult>;
+    getOrCreateCustomer(userId: string, email: string): Promise<CreateCustomerResult>;
+    getHealth(): Promise<ProviderHealthStatus>;
+    validateWebhookSignature(payload: string, signature: string): boolean;
+    getPaymentIntentStatus(providerIntentId: string): Promise<{
+        status: string;
+        error?: string;
+    }>;
+}
+
+/**
+ * @nehorai/payments - Routing Engine Interface
+ *
+ * Defines the contract for intelligent payment routing.
+ * Routes transactions to optimal providers based on:
+ * - Card BIN rules (configurable per deployment)
+ * - Provider health and availability
+ * - Transaction fees
+ * - Currency support
+ */
+
+/**
+ * Context for making routing decisions
+ */
+interface RoutingContext {
+    /** User making the payment */
+    userId: string;
+    /** Payment amount and currency */
+    amount: PaymentAmount;
+    /** Card BIN (first 6-8 digits) for card type detection */
+    cardBin?: string;
+    /** User's country (ISO 2-letter code) */
+    userCountry?: string;
+    /** User's preferred provider (if any) */
+    preferredProvider?: PaymentProvider;
+    /** Whether this is a recurring payment */
+    isRecurring: boolean;
+    /** Saved payment method ID (if using saved method) */
+    savedPaymentMethodId?: string;
+    /** Provider of saved payment method */
+    savedPaymentMethodProvider?: PaymentProvider;
+}
+/**
+ * Result of routing decision
+ */
+interface RoutingDecision {
+    /** Selected provider */
+    provider: PaymentProvider;
+    /** Reason for selection */
+    reason: string;
+    /** Fallback providers in order of priority */
+    fallbackProviders: PaymentProvider[];
+    /** Estimated transaction fee percentage */
+    estimatedFeePercent: number;
+    /** Additional routing metadata */
+    metadata?: {
+        matchedBinRule?: boolean;
+        cardIssuer?: string;
+        cardCountry?: string;
+        primaryProviderUnavailable?: boolean;
+    };
+}
+/**
+ * Routing Engine Interface
+ *
+ * Implementations of this interface handle intelligent routing
+ * of payments to optimal providers.
+ */
+interface IRoutingEngine {
+    /**
+     * 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 a configured rule
+     */
+    matchCardBin(bin: string): boolean;
+    /**
+     * Get all available (healthy) providers
+     */
+    getAvailableProviders(): Promise<PaymentProvider[]>;
+    /**
+     * Get provider recommendation without full context
+     */
+    getQuickRecommendation(currency: string, isRecurring: boolean): Promise<PaymentProvider | null>;
+}
+
+export type { CreateCustomerParams as C, DeletePaymentMethodResult as D, IPaymentProvider as I, RoutingContext as R, SavePaymentMethodParams as S, CreateCustomerResult as a, CreateSetupIntentParams as b, IRoutingEngine as c, RoutingDecision as d, SavePaymentMethodResult as e, SetupIntentResult as f };

package/dist/routing-engine.interface-h9_GmQ4b.d.ts

@@ -0,0 +1,194 @@
+import { k as PaymentProvider, d as CreatePaymentIntentParams, h as PaymentIntentResult, a as AuthorizePaymentParams, A as AuthorizationResult, C as CapturePaymentParams, b as CaptureResult, V as VoidPaymentParams, p as VoidResult, R as RefundParams, n as RefundResult, l as ProviderHealthStatus, P as PaymentAmount } from './payment-types-68W-PlGg.js';
+
+/**
+ * @nehorai/payments - Payment Provider Interface
+ *
+ * Defines the contract that all payment provider adapters must implement.
+ * Supports Two-Phase Commit (J5) pattern: Authorize -> Capture/Void
+ */
+
+/**
+ * Parameters for saving a payment method
+ */
+interface SavePaymentMethodParams {
+    userId: string;
+    /** Provider-specific setup data (e.g., SetupIntent confirmation) */
+    setupData: Record<string, unknown>;
+}
+/**
+ * Result of saving a payment method
+ */
+interface SavePaymentMethodResult {
+    success: boolean;
+    paymentMethodId?: string;
+    cardBrand?: string;
+    cardLast4?: string;
+    cardExpMonth?: string;
+    cardExpYear?: string;
+    cardBin?: string;
+    error?: string;
+}
+/**
+ * Result of deleting a payment method
+ */
+interface DeletePaymentMethodResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Parameters for creating a setup intent
+ */
+interface CreateSetupIntentParams {
+    userId: string;
+    /** Customer ID in provider system */
+    customerId?: string;
+}
+/**
+ * Result of creating a setup intent
+ */
+interface SetupIntentResult {
+    success: boolean;
+    setupIntentId?: string;
+    clientSecret?: string;
+    error?: string;
+}
+/**
+ * Parameters for creating a customer
+ */
+interface CreateCustomerParams {
+    userId: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Result of creating a customer
+ */
+interface CreateCustomerResult {
+    success: boolean;
+    customerId?: string;
+    error?: string;
+}
+/**
+ * Payment Provider Interface
+ *
+ * All payment provider adapters must implement this interface.
+ * Enables the adapter pattern for multi-provider support.
+ */
+interface IPaymentProvider {
+    /**
+     * Provider identifier
+     */
+    readonly name: PaymentProvider;
+    /**
+     * Supported currencies (ISO 4217 codes)
+     */
+    readonly supportedCurrencies: readonly string[];
+    /**
+     * Whether provider supports recurring billing
+     */
+    readonly supportsRecurring: boolean;
+    /**
+     * Whether provider supports split payments (marketplace)
+     */
+    readonly supportsSplitPayments: boolean;
+    createPaymentIntent(params: CreatePaymentIntentParams): Promise<PaymentIntentResult>;
+    authorize(params: AuthorizePaymentParams): Promise<AuthorizationResult>;
+    capture(params: CapturePaymentParams): Promise<CaptureResult>;
+    void(params: VoidPaymentParams): Promise<VoidResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    createSetupIntent(params: CreateSetupIntentParams): Promise<SetupIntentResult>;
+    savePaymentMethod(params: SavePaymentMethodParams): Promise<SavePaymentMethodResult>;
+    deletePaymentMethod(paymentMethodId: string): Promise<DeletePaymentMethodResult>;
+    createCustomer(params: CreateCustomerParams): Promise<CreateCustomerResult>;
+    getOrCreateCustomer(userId: string, email: string): Promise<CreateCustomerResult>;
+    getHealth(): Promise<ProviderHealthStatus>;
+    validateWebhookSignature(payload: string, signature: string): boolean;
+    getPaymentIntentStatus(providerIntentId: string): Promise<{
+        status: string;
+        error?: string;
+    }>;
+}
+
+/**
+ * @nehorai/payments - Routing Engine Interface
+ *
+ * Defines the contract for intelligent payment routing.
+ * Routes transactions to optimal providers based on:
+ * - Card BIN rules (configurable per deployment)
+ * - Provider health and availability
+ * - Transaction fees
+ * - Currency support
+ */
+
+/**
+ * Context for making routing decisions
+ */
+interface RoutingContext {
+    /** User making the payment */
+    userId: string;
+    /** Payment amount and currency */
+    amount: PaymentAmount;
+    /** Card BIN (first 6-8 digits) for card type detection */
+    cardBin?: string;
+    /** User's country (ISO 2-letter code) */
+    userCountry?: string;
+    /** User's preferred provider (if any) */
+    preferredProvider?: PaymentProvider;
+    /** Whether this is a recurring payment */
+    isRecurring: boolean;
+    /** Saved payment method ID (if using saved method) */
+    savedPaymentMethodId?: string;
+    /** Provider of saved payment method */
+    savedPaymentMethodProvider?: PaymentProvider;
+}
+/**
+ * Result of routing decision
+ */
+interface RoutingDecision {
+    /** Selected provider */
+    provider: PaymentProvider;
+    /** Reason for selection */
+    reason: string;
+    /** Fallback providers in order of priority */
+    fallbackProviders: PaymentProvider[];
+    /** Estimated transaction fee percentage */
+    estimatedFeePercent: number;
+    /** Additional routing metadata */
+    metadata?: {
+        matchedBinRule?: boolean;
+        cardIssuer?: string;
+        cardCountry?: string;
+        primaryProviderUnavailable?: boolean;
+    };
+}
+/**
+ * Routing Engine Interface
+ *
+ * Implementations of this interface handle intelligent routing
+ * of payments to optimal providers.
+ */
+interface IRoutingEngine {
+    /**
+     * 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 a configured rule
+     */
+    matchCardBin(bin: string): boolean;
+    /**
+     * Get all available (healthy) providers
+     */
+    getAvailableProviders(): Promise<PaymentProvider[]>;
+    /**
+     * Get provider recommendation without full context
+     */
+    getQuickRecommendation(currency: string, isRecurring: boolean): Promise<PaymentProvider | null>;
+}
+
+export type { CreateCustomerParams as C, DeletePaymentMethodResult as D, IPaymentProvider as I, RoutingContext as R, SavePaymentMethodParams as S, CreateCustomerResult as a, CreateSetupIntentParams as b, IRoutingEngine as c, RoutingDecision as d, SavePaymentMethodResult as e, SetupIntentResult as f };