@plyaz/types 1.11.3 → 1.12.0

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

@@ -0,0 +1,435 @@
+import type { CURRENCY } from '../../currency';
+import type { PAYMENTMETHOD, PAYMENTPROVIDERTYPE } from '../../provider';
+/**
+ * Base configuration interface that all payment providers must implement.
+ * This ensures consistent configuration structure across all providers.
+ */
+export interface BaseProviderConfig<TProviderSpecific extends object> {
+    /** Provider identification */
+    provider: PAYMENTPROVIDERTYPE;
+    /** Display name for this provider */
+    displayName: string;
+    /** Whether this provider is currently enabled */
+    enabled: boolean;
+    /** Environment configuration */
+    environment: ProviderEnvironment;
+    /** Provider credentials and API keys */
+    credentials: ProviderCredentials;
+    /** Webhook configuration */
+    webhooks: WebhookConfiguration;
+    /** Feature flags specific to this provider */
+    features: ProviderFeatureFlags;
+    /** Fee structure configuration */
+    fees: ProviderFeeConfiguration;
+    /** Operational limits and constraints */
+    limits: ProviderLimitsConfiguration;
+    /** Performance and reliability settings */
+    performance: ProviderPerformanceConfiguration;
+    /** Regional availability and restrictions */
+    /** Monitoring and alerting configuration */
+    /** Provider-specific custom settings */
+    customSettings: TProviderSpecific;
+}
+/**
+ * Provider environment configuration.
+ */
+export interface ProviderEnvironment {
+    /** Current environment */
+    current: 'sandbox' | 'staging' | 'production';
+    /** API base URLs for different environments */
+    apiUrls: {
+        sandbox: string;
+        staging?: string;
+        production: string;
+    };
+    /** Environment-specific feature overrides */
+    environmentOverrides: {
+        sandbox?: Partial<ProviderFeatureFlags>;
+        staging?: Partial<ProviderFeatureFlags>;
+        production?: Partial<ProviderFeatureFlags>;
+    };
+    /** Debug mode settings */
+    debug: {
+        enabled: boolean;
+        logLevel: 'error' | 'warn' | 'info' | 'debug' | 'trace';
+        logRequests: boolean;
+        logResponses: boolean;
+    };
+}
+/**
+ * Provider credentials interface with encryption support.
+ */
+export interface ProviderCredentials {
+    /** Primary API key or client ID */
+    apiKey: string;
+    /** Secret key or client secret */
+    secretKey: string;
+    /** Additional authentication credentials */
+    additionalCredentials?: {
+        /** Merchant ID for providers that require it */
+        merchantId?: string;
+        /** Partner ID for marketplace integrations */
+        partnerId?: string;
+        /** Application ID for OAuth flows */
+        applicationId?: string;
+        /** Webhook verification key */
+        webhookSecret?: string;
+        /** Additional key-value pairs */
+        [key: string]: string | undefined;
+    };
+    /** Credential rotation configuration */
+    rotation: {
+        /** Whether automatic rotation is enabled */
+        enabled: boolean;
+        /** Rotation interval in days */
+        intervalDays: number;
+        /** Warning period before expiration */
+        warningDays: number;
+        /** Last rotation timestamp */
+        lastRotated?: Date;
+        /** Next scheduled rotation */
+        nextRotation?: Date;
+    };
+    /** Encryption information */
+    encryption: {
+        /** Whether credentials are encrypted */
+        encrypted: boolean;
+        /** Encryption algorithm used */
+        algorithm?: string;
+        /** Key version for rotation */
+        keyVersion?: string;
+    };
+}
+/**
+ * Webhook configuration for provider integrations.
+ */
+export interface WebhookConfiguration {
+    /** Whether webhooks are enabled for this provider */
+    enabled: boolean;
+    /** Webhook endpoint URLs */
+    endpoints: {
+        /** Primary webhook endpoint */
+        primary: string;
+        /** Fallback webhook endpoint */
+        fallback?: string;
+        /** Specific endpoints for different event types */
+        eventSpecific?: Record<string, string>;
+    };
+    /** Webhook security configuration */
+    security: {
+        /** Signature verification method */
+        signatureMethod: 'hmac_sha256' | 'hmac_sha512' | 'rsa' | 'custom';
+        /** Signature header name */
+        signatureHeader: string;
+        /** Timestamp header name for replay protection */
+        timestampHeader?: string;
+        /** Webhook secret for signature verification */
+        secret: string;
+        /** Tolerance for timestamp validation (seconds) */
+        timestampTolerance: number;
+        /** IP whitelist for webhook sources */
+        allowedIPs?: string[];
+    };
+    /** Event subscription configuration */
+    events: {
+        /** Events to subscribe to */
+        subscribed: string[];
+        /** Events to explicitly ignore */
+        ignored?: string[];
+    };
+    /** Retry and reliability configuration */
+    reliability: {
+        /** Enable automatic retries for failed deliveries */
+        retryEnabled: boolean;
+        /** Maximum retry attempts */
+        maxRetries: number;
+        /** Retry delay progression (milliseconds) */
+        retryDelays: number[];
+        /** Timeout for webhook processing */
+        timeout: number;
+        /** Dead letter queue configuration */
+        deadLetterQueue?: {
+            enabled: boolean;
+            retentionDays: number;
+        };
+    };
+}
+/**
+ * Provider-specific feature flags.
+ */
+export interface ProviderFeatureFlags {
+    /** Core payment features */
+    payments: {
+        /** Enable payment processing */
+        enabled: boolean;
+        /** Enable subscription payments */
+        subscriptions: boolean;
+        /** Enable pre-authorization */
+        preauthorization: boolean;
+        /** Enable payment cancellation */
+        cancellation: boolean;
+        /** Enable payment updates */
+        updates: boolean;
+    };
+    /** Refund features */
+    refunds: {
+        /** Enable refund processing */
+        enabled: boolean;
+        /** Enable partial refunds */
+        partial: boolean;
+        /** Enable instant refunds */
+        instant: boolean;
+        /** Enable refund scheduling */
+        scheduled: boolean;
+    };
+    /** Security features */
+    security: {
+        /** Enable 3D Secure verification */
+        threeDS: boolean;
+        /** Enable fraud detection */
+        fraudDetection: boolean;
+        /** Enable velocity checking */
+        velocityChecking: boolean;
+        /** Enable payment tokenization */
+        tokenization: boolean;
+    };
+    /** Customer features */
+    customers: {
+        /** Enable customer profiles */
+        profiles: boolean;
+        /** Enable saved payment methods */
+        savedMethods: boolean;
+        /** Enable customer authentication */
+        authentication: boolean;
+    };
+    /** Marketplace features */
+    marketplace: {
+        /** Enable marketplace payments */
+        enabled: boolean;
+        /** Enable split payments */
+        splitPayments: boolean;
+        /** Enable connected accounts */
+        connectedAccounts: boolean;
+        /** Enable instant payouts */
+        instantPayouts: boolean;
+    };
+    /** Advanced features */
+    advanced: {
+        /** Enable multi-currency support */
+        multiCurrency: boolean;
+        /** Enable currency conversion */
+        currencyConversion: boolean;
+        /** Enable payment routing */
+        smartRouting: boolean;
+        /** Enable cost optimization */
+        costOptimization: boolean;
+        /** Enable A/B testing */
+        abTesting: boolean;
+    };
+}
+/**
+ * Provider fee configuration for cost optimization.
+ */
+export interface ProviderFeeConfiguration {
+    /** Base fee structure */
+    baseFees: {
+        /** Percentage fee (e.g., 2.9 for 2.9%) */
+        percentage: number;
+        /** Fixed fee per transaction (in cents) */
+        fixed: number;
+        /** Currency for fixed fees */
+        currency: CURRENCY;
+    };
+    /** Payment method specific fees */
+    methodFees: Record<PAYMENTMETHOD, {
+        percentage: number;
+        fixed: number;
+        currency: CURRENCY;
+    }>;
+    /** Volume-based fee tiers */
+    volumeTiers: VolumeTier[];
+    /** Regional fee variations */
+    regionalFees: Record<string, {
+        percentage: number;
+        fixed: number;
+        currency: CURRENCY;
+    }>;
+    /** Additional fee types */
+    additionalFees: {
+        /** Cross-border transaction fees */
+        crossBorder?: {
+            percentage: number;
+            fixed?: number;
+        };
+        /** Currency conversion fees */
+        currencyConversion?: {
+            percentage: number;
+            minimumFee?: number;
+        };
+        /** Chargeback fees */
+        chargeback?: {
+            amount: number;
+            currency: CURRENCY;
+        };
+        /** Refund processing fees */
+        refund?: {
+            percentage: number;
+            fixed?: number;
+        };
+    };
+    /** Fee calculation configuration */
+    calculation: {
+        /** Rounding method for calculated fees */
+        rounding: 'up' | 'down' | 'nearest';
+        /** Minimum fee amount */
+        minimumFee?: {
+            amount: number;
+            currency: CURRENCY;
+        };
+        /** Maximum fee amount */
+        maximumFee?: {
+            amount: number;
+            currency: CURRENCY;
+        };
+    };
+}
+/**
+ * Volume tier configuration for fee optimization.
+ */
+export interface VolumeTier {
+    /** Tier name */
+    name: string;
+    /** Minimum monthly volume to qualify */
+    minimumVolume: {
+        amount: number;
+        currency: CURRENCY;
+    };
+    /** Fee rates for this tier */
+    feeRates: {
+        percentage: number;
+        fixed: number;
+        currency: CURRENCY;
+    };
+    /** Tier benefits */
+    benefits?: string[];
+    /** Tier requirements */
+    requirements?: string[];
+}
+/**
+ * Provider limits configuration.
+ */
+export interface ProviderLimitsConfiguration<TProviderSpecific extends object = Record<string, never>> {
+    /** Transaction amount limits */
+    amounts: {
+        /** Minimum transaction amount */
+        minimum: Record<PAYMENTMETHOD, {
+            amount: number;
+            currency: CURRENCY;
+        }>;
+        /** Maximum transaction amount */
+        maximum: Record<PAYMENTMETHOD, {
+            amount: number;
+            currency: CURRENCY;
+        }>;
+    };
+    /** Velocity limits */
+    velocity: {
+        /** Daily transaction limits */
+        daily: {
+            /** Maximum number of transactions */
+            maxTransactions: number;
+            /** Maximum total amount */
+            maxAmount: {
+                amount: number;
+                currency: CURRENCY;
+            };
+        };
+        /** Monthly transaction limits */
+        monthly: {
+            maxTransactions: number;
+            maxAmount: {
+                amount: number;
+                currency: CURRENCY;
+            };
+        };
+    };
+    /** API rate limits */
+    apiLimits: {
+        /** Requests per second */
+        requestsPerSecond: number;
+        /** Requests per minute */
+        requestsPerMinute: number;
+        /** Requests per hour */
+        requestsPerHour: number;
+        /** Burst capacity */
+        burstCapacity?: number;
+    };
+    /** Provider-specific limits */
+    providerSpecific: TProviderSpecific;
+}
+/**
+ * Provider performance configuration.
+ */
+export interface ProviderPerformanceConfiguration {
+    /** Timeout configurations */
+    timeouts: {
+        /** Connection timeout (milliseconds) */
+        connection: number;
+        /** Request timeout (milliseconds) */
+        request: number;
+        /** Total timeout including retries */
+        total: number;
+    };
+    /** Retry configuration */
+    retries: {
+        /** Enable automatic retries */
+        enabled: boolean;
+        /** Maximum retry attempts */
+        maxAttempts: number;
+        /** Retry delay strategy */
+        strategy: 'fixed' | 'exponential' | 'linear';
+        /** Base delay for retry strategy */
+        baseDelay: number;
+        /** Maximum delay between retries */
+        maxDelay: number;
+        /** Jitter to prevent thundering herd */
+        jitter: boolean;
+        /** Status codes that trigger retries */
+        retryableStatusCodes: number[];
+    };
+    /** Circuit breaker configuration */
+    circuitBreaker: {
+        /** Enable circuit breaker */
+        enabled: boolean;
+        /** Failure threshold to open circuit */
+        failureThreshold: number;
+        /** Time window for failure counting */
+        windowSize: number;
+        /** Timeout before attempting to close circuit */
+        timeout: number;
+        /** Minimum requests before circuit can open */
+        minimumRequests: number;
+    };
+    /** Connection pooling */
+    connectionPool: {
+        /** Maximum number of connections */
+        maxConnections: number;
+        /** Minimum number of connections */
+        minConnections: number;
+        /** Connection idle timeout */
+        idleTimeout: number;
+        /** Connection validation interval */
+        validationInterval: number;
+    };
+    /** Caching configuration */
+    caching: {
+        /** Enable response caching */
+        enabled: boolean;
+        /** Cache TTL for different operation types */
+        ttl: Record<string, number>;
+        /** Cache size limits */
+        maxSize: number;
+        /** Cache eviction strategy */
+        evictionStrategy: 'lru' | 'lfu' | 'ttl';
+    };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Cost optimization strategies.
+ */
+export declare enum COSTOPTIMIZATIONSTRATEGY {
+    /** Always use cheapest option */
+    Aggressive = "aggressive",
+    /** Balance cost with reliability */
+    Balanced = "balanced",
+    /** Prefer reliability over cost */
+    Conservative = "conservative",
+    /** Optimize for specific cost components */
+    Targeted = "targeted"
+}
+/**
+ * Failover strategies.
+ */
+export declare enum FAILOVERSTRATEGY {
+    /** Use predefined provider order */
+    PriorityOrder = "priority_order",
+    /** Failover to next available provider */
+    NextAvailable = "next_available",
+    /** Failover based on performance metrics */
+    PerformanceBased = "performance_based",
+    /** Failover to least loaded provider */
+    LoadBalanced = "load_balanced",
+    /** Geographic failover preference */
+    Geographic = "geographic"
+}
+/**
+ * Regulatory frameworks.
+ */
+export declare enum REGULATORYFRAMEWORK {
+    PciDss = "pci_dss",
+    Gdpr = "gdpr",
+    Psd2 = "psd2",
+    Sox = "sox",
+    Aml = "aml",
+    Kyc = "kyc",
+    Ccpa = "ccpa",
+    LocalBanking = "local_banking"
+}
+/**
+ * Load balancing strategies.
+ */
+export declare enum LOADBALANCINGSTRATEGY {
+    /** Rotate through providers evenly */
+    RoundRobin = "round_robin",
+    /** Use weighted distribution */
+    Weighted = "weighted",
+    /** Choose provider with least active traffic */
+    LeastConnections = "least_connections",
+    /** Choose based on best performance metrics */
+    PerformanceBased = "performance_based",
+    /** Custom strategy defined by merchant */
+    Custom = "custom"
+}
+/**
+ * Types of performance metrics.
+ */
+export declare enum PERFORMANCEMETRICTYPE {
+    Latency = "latency",
+    SuccessRate = "success_rate",
+    ErrorRate = "error_rate",
+    Throughput = "throughput",
+    Retries = "retries",
+    Availability = "availability",
+    Cost = "cost"
+}
+/**
+ * Primary routing strategies.
+ */
+export declare enum ROUTINGSTRATEGY {
+    /** Optimize for lowest total cost */
+    CostOptimized = "cost_optimized",
+    /** Optimize for highest reliability */
+    ReliabilityFirst = "reliability_first",
+    /** Optimize for fastest processing */
+    PerformanceFirst = "performance_first",
+    /** Balance cost, reliability, and performance */
+    Balanced = "balanced",
+    /** Use user or region preferences */
+    UserPreference = "user_preference",
+    /** Distribute load evenly */
+    RoundRobin = "round_robin",
+    /** Custom routing logic */
+    Custom = "custom"
+}

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

@@ -0,0 +1,2 @@
+export type * from './types';
+export * from './enums';