@plyaz/types 1.11.4 → 1.12.0

package/dist/payments/gateways/routings/types.d.ts

@@ -0,0 +1,512 @@
+import type { CURRENCY } from '../../currency';
+import type { PAYMENTMETHOD, PAYMENTPROVIDERTYPE, TRANSACTIONTYPE, USERTYPE } from '../../provider';
+import type { VolumeTier } from '../provider/types';
+import type { COSTOPTIMIZATIONSTRATEGY, FAILOVERSTRATEGY, LOADBALANCINGSTRATEGY, PERFORMANCEMETRICTYPE, REGULATORYFRAMEWORK, ROUTINGSTRATEGY } from './enums';
+/**
+ * Comprehensive payment routing configuration for optimizing
+ * payment processing across multiple providers and methods.
+ */
+export interface PaymentRoutingConfiguration {
+    /** Overall routing strategy */
+    strategy: ROUTINGSTRATEGY;
+    /** Provider selection rules */
+    providerSelection: ProviderSelectionRules;
+    /** Cost optimization settings */
+    costOptimization: CostOptimizationConfig;
+    /** Failover and redundancy configuration */
+    failover: FailoverConfiguration;
+    /** Geographic routing preferences */
+    geographic: GeographicRoutingConfig;
+    /** Load balancing configuration */
+    loadBalancing: LoadBalancingConfig;
+    /** Performance monitoring */
+    performance: PerformanceMonitoringConfig;
+    /** A/B testing configuration */
+    abTesting: ABTestingConfig;
+}
+/**
+ * Provider selection rules and criteria.
+ */
+export interface ProviderSelectionRules {
+    /** Default provider preferences */
+    defaultProviders: ProviderPreference[];
+    /** Payment method specific preferences */
+    methodSpecificProviders: Record<PAYMENTMETHOD, ProviderPreference[]>;
+    /** Amount-based provider selection */
+    amountBasedSelection: AmountBasedRule[];
+    /** Currency-specific provider preferences */
+    currencySpecificProviders: Record<CURRENCY, ProviderPreference[]>;
+    /** Region-specific provider preferences */
+    regionSpecificProviders: Record<string, ProviderPreference[]>;
+    /** User type specific preferences */
+    userTypeProviders: Record<USERTYPE, ProviderPreference[]>;
+    /** Time-based provider selection */
+    timeBasedSelection: TimeBasedRule[];
+    /** Custom selection rules */
+    customRules: CustomSelectionRule[];
+}
+/**
+ * Provider preference configuration.
+ */
+export interface ProviderPreference {
+    /** Provider identifier */
+    provider: PAYMENTPROVIDERTYPE;
+    /** Weight/priority (higher = preferred) */
+    weight: number;
+    /** Traffic allocation percentage */
+    trafficPercentage: number;
+    /** Conditions for using this provider */
+    conditions: ProviderCondition[];
+    /** Maximum transaction amount for this provider */
+    maxAmount?: {
+        amount: number;
+        currency: CURRENCY;
+    };
+    /** Minimum transaction amount for this provider */
+    minAmount?: {
+        amount: number;
+        currency: CURRENCY;
+    };
+    /** Health check requirements */
+    healthRequirements: {
+        /** Minimum success rate required */
+        minSuccessRate: number;
+        /** Maximum response time allowed */
+        maxResponseTime: number;
+        /** Check interval in minutes */
+        checkInterval: number;
+    };
+}
+/**
+ * Provider selection condition.
+ */
+export interface ProviderCondition<T = string | number | boolean | string[] | number[]> {
+    /** Condition type */
+    type: 'currency' | 'amount' | 'region' | 'time' | 'user_type' | 'payment_method' | 'custom';
+    /** Condition operator */
+    operator: 'equals' | 'not_equals' | 'in' | 'not_in' | 'greater_than' | 'less_than' | 'between';
+    /** Condition value(s) */
+    value: T;
+    /** Whether condition is required */
+    required: boolean;
+}
+/**
+ * Amount-based provider selection rule.
+ */
+export interface AmountBasedRule {
+    /** Rule name */
+    name: string;
+    /** Amount range */
+    amountRange: {
+        min: {
+            amount: number;
+            currency: CURRENCY;
+        };
+        max: {
+            amount: number;
+            currency: CURRENCY;
+        };
+    };
+    /** Preferred providers for this amount range */
+    preferredProviders: ProviderPreference[];
+    /** Special handling rules */
+    specialHandling?: {
+        /** Require additional verification */
+        requireVerification: boolean;
+        /** Apply additional security checks */
+        enhancedSecurity: boolean;
+        /** Manual review required */
+        manualReview: boolean;
+    };
+}
+/**
+ * Time-based provider selection rule.
+ */
+export interface TimeBasedRule {
+    /** Rule name */
+    name: string;
+    /** Time conditions */
+    timeConditions: {
+        /** Days of week (0=Sunday, 6=Saturday) */
+        daysOfWeek: number[];
+        /** Hours of day (0-23) */
+        hoursOfDay: number[];
+        /** Time zones */
+        timeZones: string[];
+    };
+    /** Provider preferences during these times */
+    providerPreferences: ProviderPreference[];
+    /** Reason for time-based routing */
+    reason: string;
+}
+/**
+ * Custom selection rule configuration.
+ */
+export interface CustomSelectionRule {
+    /** Rule identifier */
+    ruleId: string;
+    /** Rule name */
+    name: string;
+    /** Rule description */
+    description: string;
+    /** Rule conditions */
+    conditions: {
+        /** JavaScript condition expression */
+        expression: string;
+        /** Required context variables */
+        requiredContext: string[];
+    };
+    /** Provider selection when rule matches */
+    providerSelection: {
+        /** Providers to prefer */
+        preferred: PAYMENTPROVIDERTYPE[];
+        /** Providers to avoid */
+        excluded: PAYMENTPROVIDERTYPE[];
+        /** Weight adjustments */
+        weightAdjustments: Record<PAYMENTPROVIDERTYPE, number>;
+    };
+    /** Rule priority */
+    priority: number;
+    /** Rule enabled status */
+    enabled: boolean;
+}
+/**
+ * Cost optimization configuration.
+ */
+export interface CostOptimizationConfig {
+    /** Enable cost optimization */
+    enabled: boolean;
+    /** Optimization strategy */
+    strategy: COSTOPTIMIZATIONSTRATEGY;
+    /** Cost calculation settings */
+    calculation: {
+        /** Include network/gas fees */
+        includeNetworkFees: boolean;
+        /** Include currency conversion costs */
+        includeFxCosts: boolean;
+        /** Include opportunity costs */
+        includeOpportunityCosts: boolean;
+        /** Cost update frequency */
+        updateFrequency: number;
+    };
+    /** Fee structure preferences */
+    feePreferences: {
+        /** Prefer percentage vs fixed fees */
+        preferenceType: 'percentage' | 'fixed' | 'hybrid' | 'lowest_total';
+        /** Percentage fee weight */
+        percentageWeight: number;
+        /** Fixed fee weight */
+        fixedWeight: number;
+    };
+    /** Volume-based optimization */
+    volumeOptimization: {
+        /** Enable volume-based routing */
+        enabled: boolean;
+        /** Volume tracking window */
+        trackingWindow: number;
+        /** Volume tiers */
+        volumeTiers: VolumeTier[];
+    };
+    /** Currency conversion optimization */
+    currencyOptimization: {
+        /** Enable FX optimization */
+        enabled: boolean;
+        /** FX rate providers */
+        rateProviders: string[];
+        /** Rate update frequency */
+        updateFrequency: number;
+        /** Spread tolerance */
+        spreadTolerance: number;
+    };
+}
+/**
+ * Failover configuration for handling provider failures.
+ */
+export interface FailoverConfiguration {
+    /** Enable automatic failover */
+    enabled: boolean;
+    /** Failover strategy */
+    strategy: FAILOVERSTRATEGY;
+    /** Provider priority order for failover */
+    providerOrder: PAYMENTPROVIDERTYPE[];
+    /** Failure detection settings */
+    failureDetection: {
+        /** Consecutive failures before failover */
+        consecutiveFailureThreshold: number;
+        /** Error rate threshold (percentage) */
+        errorRateThreshold: number;
+        /** Response time threshold (ms) */
+        responseTimeThreshold: number;
+        /** Health check interval */
+        healthCheckInterval: number;
+    };
+    /** Retry configuration */
+    retry: {
+        /** Enable retries before failover */
+        enabled: boolean;
+        /** Maximum retry attempts */
+        maxAttempts: number;
+        /** Retry delays */
+        delays: number[];
+        /** Exponential backoff */
+        exponentialBackoff: boolean;
+    };
+    /** Recovery configuration */
+    recovery: {
+        /** Automatic recovery enabled */
+        autoRecovery: boolean;
+        /** Recovery check interval */
+        recoveryInterval: number;
+        /** Successful transactions needed for recovery */
+        recoveryThreshold: number;
+        /** Gradual traffic restoration */
+        gradualRestoration: boolean;
+    };
+    /** Circuit breaker configuration */
+    circuitBreaker: {
+        /** Enable circuit breaker */
+        enabled: boolean;
+        /** Failure threshold to open circuit */
+        failureThreshold: number;
+        /** Success threshold to close circuit */
+        successThreshold: number;
+        /** Timeout before retry attempt */
+        timeout: number;
+    };
+}
+/**
+ * Geographic routing configuration.
+ */
+export interface GeographicRoutingConfig {
+    /** Enable geographic routing */
+    enabled: boolean;
+    /** Region-specific provider preferences */
+    regionPreferences: Record<string, RegionRoutingConfig>;
+    /** Cross-border payment handling */
+    crossBorder: {
+        /** Enable cross-border payments */
+        enabled: boolean;
+        /** Preferred providers for cross-border */
+        preferredProviders: PAYMENTPROVIDERTYPE[];
+        /** Additional fees for cross-border */
+        additionalFees: {
+            percentage: number;
+            fixed?: number;
+        };
+    };
+    /** Compliance-based routing */
+    compliance: {
+        /** Enable compliance routing */
+        enabled: boolean;
+        /** Compliance rules per region */
+        rules: Record<string, ComplianceRule[]>;
+    };
+    /** Currency zone optimization */
+    currencyZones: {
+        /** Enable currency zone routing */
+        enabled: boolean;
+        /** Zone definitions */
+        zones: Record<string, {
+            currencies: CURRENCY[];
+            preferredProviders: PAYMENTPROVIDERTYPE[];
+        }>;
+    };
+}
+/**
+ * Region-specific routing configuration.
+ */
+export interface RegionRoutingConfig {
+    /** Region identifier */
+    regionId: string;
+    /** Preferred providers for this region */
+    preferredProviders: ProviderPreference[];
+    /** Local payment methods */
+    localPaymentMethods: PAYMENTMETHOD[];
+    /** Regulatory requirements */
+    regulations: {
+        /** KYC requirements */
+        kycRequired: boolean;
+        /** Transaction limits */
+        transactionLimits: {
+            daily: {
+                amount: number;
+                currency: CURRENCY;
+            };
+            monthly: {
+                amount: number;
+                currency: CURRENCY;
+            };
+        };
+        /** Required licenses */
+        requiredLicenses: string[];
+    };
+    /** Performance optimizations */
+    optimizations: {
+        /** Preferred data centers */
+        preferredDataCenters: string[];
+        /** CDN endpoints */
+        cdnEndpoints: string[];
+        /** Caching strategy */
+        cachingStrategy: 'aggressive' | 'standard' | 'minimal';
+    };
+}
+/**
+ * Compliance rule configuration.
+ */
+export interface ComplianceRule {
+    /** Rule identifier */
+    ruleId: string;
+    /** Rule description */
+    description: string;
+    /** Regulatory framework */
+    framework: REGULATORYFRAMEWORK;
+    /** Rule conditions */
+    conditions: {
+        /** Transaction types affected */
+        transactionTypes: TRANSACTIONTYPE[];
+        /** Amount thresholds */
+        amountThresholds?: {
+            min?: {
+                amount: number;
+                currency: CURRENCY;
+            };
+            max?: {
+                amount: number;
+                currency: CURRENCY;
+            };
+        };
+        /** User types affected */
+        userTypes?: USERTYPE[];
+    };
+    /** Required actions */
+    actions: {
+        /** Additional verification required */
+        verification?: string[];
+        /** Documentation required */
+        documentation?: string[];
+        /** Reporting required */
+        reporting?: boolean;
+        /** Approval required */
+        approval?: boolean;
+    };
+    /** Enforcement level */
+    enforcement: 'mandatory' | 'recommended' | 'optional';
+}
+/**
+ * Load balancing configuration.
+ */
+export interface LoadBalancingConfig {
+    /** Enable load balancing */
+    enabled: boolean;
+    /** Load balancing strategy */
+    strategy: LOADBALANCINGSTRATEGY;
+    /** Traffic weights per provider */
+    providerWeights: Record<PAYMENTPROVIDERTYPE, number>;
+    /** Maximum concurrent connections per provider */
+    maxConnections?: Record<PAYMENTPROVIDERTYPE, number>;
+    /** Session stickiness settings */
+    stickiness?: {
+        enabled: boolean;
+        /** Duration to stick to the same provider in seconds */
+        duration: number;
+        /** Key for stickiness (e.g., userId, region, sessionId) */
+        key: 'user' | 'region' | 'session' | 'custom';
+    };
+    /** Auto-rebalance configuration */
+    autoRebalance?: {
+        enabled: boolean;
+        /** Check interval in seconds */
+        interval: number;
+        /** Rebalance based on performance metrics */
+        basedOn: 'latency' | 'success_rate' | 'cost' | 'mixed';
+    };
+}
+/**
+ * Performance monitoring configuration.
+ */
+export interface PerformanceMonitoringConfig {
+    /** Enable performance monitoring */
+    enabled: boolean;
+    /** Metrics to collect */
+    metrics: PERFORMANCEMETRICTYPE[];
+    /** Data retention period in minutes */
+    retentionPeriod: number;
+    /** Sampling rate (0–1) */
+    samplingRate: number;
+    /** Alerting configuration */
+    alerting: {
+        enabled: boolean;
+        /** Error rate threshold to trigger alert (%) */
+        errorRateThreshold: number;
+        /** Latency threshold in ms */
+        latencyThreshold: number;
+        /** Success rate threshold (%) */
+        successRateThreshold: number;
+        /** Minimum sample size for alerts */
+        minSampleSize: number;
+    };
+    /** Integration hooks for monitoring tools */
+    integrations?: {
+        /** Metrics push to observability stack (e.g., Prometheus, Datadog) */
+        metricsSink?: string;
+        /** Log forwarding destination */
+        logSink?: string;
+    };
+}
+/**
+ * A/B testing configuration.
+ */
+export interface ABTestingConfig {
+    /** Enable A/B testing */
+    enabled: boolean;
+    /** Default experiment ID */
+    defaultExperimentId?: string;
+    /** A/B test experiments */
+    experiments: ABTestExperiment[];
+    /** Fallback behavior if test fails */
+    fallback: {
+        /** Use control strategy if experiment fails */
+        useControlOnFailure: boolean;
+        /** Log experiment errors */
+        logErrors: boolean;
+    };
+}
+/**
+ * A/B test experiment definition.
+ */
+export interface ABTestExperiment {
+    /** Unique experiment ID */
+    id: string;
+    /** Description of experiment */
+    description: string;
+    /** Traffic allocation */
+    allocation: {
+        control: number;
+        variant: number;
+    };
+    /** Experiment strategy overrides */
+    overrides: {
+        /** Routing strategy for variant group */
+        strategy?: ROUTINGSTRATEGY;
+        /** Preferred provider list */
+        preferredProviders?: PAYMENTPROVIDERTYPE[];
+        /** Special fee or cost weighting */
+        costOptimization?: Partial<CostOptimizationConfig>;
+    };
+    /** Targeting rules */
+    targeting?: {
+        /** Regions to include */
+        regions?: string[];
+        /** User types to include */
+        userTypes?: USERTYPE[];
+        /** Payment methods to include */
+        paymentMethods?: PAYMENTMETHOD[];
+    };
+    /** Start and end times */
+    schedule?: {
+        start?: Date;
+        end?: Date;
+    };
+    /** Experiment active status */
+    active: boolean;
+}