@plyaz/types 1.11.4 → 1.12.0

package/dist/payments/events/emitter/types.d.ts

@@ -0,0 +1,333 @@
+import type { PAYMENTEVENTTYPE } from '../enums';
+import type { EventRetryConfig, PaymentEvent, PaymentEventPayload } from '../types';
+/**
+ * Payment event emitter interface that extends the base event system
+ * with payment-specific functionality and type safety.
+ *
+ * Design Goals:
+ * - Type-safe event emission and subscription
+ * - Support for synchronous and asynchronous event processing
+ * - Comprehensive error handling and retry mechanismss
+ * - Event filtering and routing capabilities
+ * - Performance monitoring and metrics
+ */
+/**
+ * Aggregated result of processing a single emitted event by all handlers.
+ * Returned by `emitAndWait` to give a complete view of what happened.
+ */
+export interface EventProcessingResult<TMetadata extends object = {}> {
+    /** Unique emission ID for tracking this processing */
+    emissionId: string;
+    /** Event type that was processed */
+    eventType: PAYMENTEVENTTYPE;
+    /** Total number of handlers triggered */
+    totalHandlers: number;
+    /** Number of handlers that succeeded */
+    successfulHandlers: number;
+    /** Number of handlers that failed */
+    failedHandlers: number;
+    /** Total time taken for processing all handlers */
+    totalProcessingTime: number;
+    /** Individual handler execution results */
+    handlerResults: EventHandlerResult[];
+    /** Whether all handlers executed successfully */
+    fullySuccessful: boolean;
+    /** Any errors encountered during processing */
+    errors?: EventEmissionError[];
+    /** Additional metadata about the emission */
+    metadata?: TMetadata;
+}
+export interface PaymentEventEmitter {
+    /**
+     * Emit a payment event to all registered handlers.
+     * This method should:
+     * - Validate event data before emission
+     * - Route events to appropriate handlers
+     * - Handle emission errors gracefully
+     * - Provide emission metrics
+     *
+     * @param eventType - Type of payment event to emit
+     * @param payload - Event payload with business data
+     * @param options - Additional emission options
+     * @returns Promise that resolves when emission is complete
+     */
+    emit(eventType: PAYMENTEVENTTYPE, payload: PaymentEventPayload, options?: EventEmissionOptions): Promise<EventEmissionResult>;
+    /**
+     * Emit event and wait for all handlers to complete processing.
+     * Useful for critical events that require synchronous processing.
+     *
+     * @param eventType - Type of payment event to emit
+     * @param payload - Event payload with business data
+     * @param timeout - Maximum wait time in milliseconds
+     * @returns Promise with aggregated handler results
+     */
+    emitAndWait(eventType: PAYMENTEVENTTYPE, payload: PaymentEventPayload, timeout?: number): Promise<EventProcessingResult[]>;
+    /**
+     * Subscribe to specific payment event types with typed handlers.
+     * Handlers will be called for matching events.
+     *
+     * @param eventType - Event type to subscribe to
+     * @param handler - Typed event handler function
+     * @param options - Handler configuration options
+     */
+    on(eventType: PAYMENTEVENTTYPE, handler: PaymentEventHandler, options?: EventHandlerOptions): void;
+    /**
+     * Subscribe to multiple event types with pattern matching.
+     * Supports wildcards and complex filtering patterns.
+     *
+     * @param pattern - Event pattern (e.g., 'payment.*', 'refund.completed')
+     * @param handler - Event handler function
+     * @param options - Handler configuration options
+     */
+    onPattern(pattern: string, handler: PaymentEventHandler, options?: EventHandlerOptions): void;
+    /**
+     * Subscribe to events with advanced filtering capabilities.
+     * Allows complex event filtering based on payload content.
+     *
+     * @param filter - Event filter function
+     * @param handler - Event handler function
+     * @param options - Handler configuration options
+     */
+    onFiltered(filter: PaymentEventFilter, handler: PaymentEventHandler, options?: EventHandlerOptions): void;
+    /**
+     * Subscribe to events only once (auto-unsubscribe after first event).
+     *
+     * @param eventType - Event type to subscribe to
+     * @param handler - Event handler function
+     * @param options - Handler configuration options
+     */
+    once(eventType: PAYMENTEVENTTYPE, handler: PaymentEventHandler, options?: EventHandlerOptions): void;
+    /**
+     * Remove event listener for specific event type and handler.
+     *
+     * @param eventType - Event type to unsubscribe from
+     * @param handler - Handler function to remove
+     */
+    off(eventType: PAYMENTEVENTTYPE, handler: PaymentEventHandler): void;
+    /**
+     * Remove all event listeners for specific event type.
+     *
+     * @param eventType - Event type to clear all handlers for
+     */
+    removeAllListeners(eventType: PAYMENTEVENTTYPE): void;
+    /**
+     * Get current event emission metrics and statistics.
+     *
+     * @returns Current emission metrics
+     */
+    getMetrics(): EventEmissionMetrics;
+    /**
+     * Configure event emitter behavior and settings.
+     *
+     * @param config - Event emitter configuration
+     */
+    configure(config: PaymentEventEmitterConfig): void;
+}
+/**
+ * Payment event handler function interface with comprehensive error handling.
+ */
+export interface PaymentEventHandler {
+    /**
+     * Handle a payment event with proper error handling and metrics.
+     *
+     * @param event - Payment event to handle
+     * @returns Promise that resolves when handling is complete
+     * @throws Should handle errors gracefully and not throw unless critical
+     */
+    (event: PaymentEvent): Promise<EventHandlerResult> | EventHandlerResult;
+}
+/**
+ * Event filter function for advanced event subscription.
+ */
+export interface PaymentEventFilter {
+    /**
+     * Determine if an event should be processed by the handler.
+     *
+     * @param event - Payment event to evaluate
+     * @returns True if event should be processed, false otherwise
+     */
+    (event: PaymentEvent): boolean;
+}
+/**
+ * Options for event emission configuration.
+ */
+export interface EventEmissionOptions<TMetadata extends object = {}> {
+    /** Emission priority (higher number = higher priority) */
+    priority?: number;
+    /** Whether this emission is urgent and should skip queues */
+    urgent?: boolean;
+    /** Maximum time to wait for emission completion */
+    timeout?: number;
+    /** Whether to emit synchronously or asynchronously */
+    synchronous?: boolean;
+    /** Tags to add to the event for filtering */
+    tags?: string[];
+    /** Correlation ID for event tracking */
+    correlationId?: string;
+    /** Whether to persist this event */
+    persist?: boolean;
+    /** Custom metadata for this emission */
+    metadata?: TMetadata;
+}
+/**
+ * Result of event emission operation.
+ */
+export interface EventEmissionResult<TMetadata extends object = {}> {
+    /** Whether emission was successful */
+    success: boolean;
+    /** Unique identifier for this emission */
+    emissionId: string;
+    /** Number of handlers that will process this event */
+    handlerCount: number;
+    /** Time taken for emission in milliseconds */
+    emissionTime: number;
+    /** Any errors that occurred during emission */
+    errors?: EventEmissionError[];
+    /** Additional emission metadata */
+    metadata?: TMetadata;
+}
+/**
+ * Options for configuring event handlers.
+ */
+export interface EventHandlerOptions {
+    /** Handler priority (higher number = higher priority) */
+    priority?: number;
+    /** Maximum execution time for this handler */
+    timeout?: number;
+    /** Whether handler failures should stop other handlers */
+    critical?: boolean;
+    /** Retry configuration for failed handler execution */
+    retryConfig?: EventRetryConfig;
+    /** Whether to run this handler asynchronously */
+    async?: boolean;
+    /** Handler identifier for logging and metrics */
+    handlerId?: string;
+    /** Tags for handler classification */
+    tags?: string[];
+}
+/**
+ * Result of event handler execution.
+ */
+export interface EventHandlerResult<TData extends object = {}, TMetadata extends object = {}> {
+    /** Index of the handler in the execution pipeline */
+    handlerIndex: number;
+    /** Whether handler execution was successful */
+    success: boolean;
+    /** Time taken for handler execution in milliseconds */
+    executionTime: number;
+    /** Data returned by the handler */
+    data?: TData;
+    /** Error information if handler failed */
+    error?: EventHandlerError;
+    /** Additional handler metadata */
+    metadata?: TMetadata;
+}
+/**
+ * Error information for failed event emissions.
+ */
+export interface EventEmissionError<TMetadata extends object = {}> {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Component where error occurred */
+    component: string;
+    /** Error timestamp */
+    timestamp: Date;
+    /** Additional error context */
+    context?: TMetadata;
+}
+/**
+ * Error information for failed event handler execution.
+ */
+export interface EventHandlerError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Handler identifier that failed */
+    handlerId?: string;
+    /** Whether this error is retryable */
+    retryable: boolean;
+    /** Error timestamp */
+    timestamp: Date;
+    /** Stack trace or additional error details */
+    details?: string;
+}
+/**
+ * Event emission metrics and statistics.
+ */
+export interface EventEmissionMetrics {
+    /** Total number of events emitted */
+    totalEmissions: number;
+    /** Number of successful emissions */
+    successfulEmissions: number;
+    /** Number of failed emissions */
+    failedEmissions: number;
+    /** Average emission time in milliseconds */
+    averageEmissionTime: number;
+    /** Events emitted per second (current rate) */
+    emissionRate: number;
+    /** Handler execution statistics */
+    handlerMetrics: {
+        totalExecutions: number;
+        successfulExecutions: number;
+        failedExecutions: number;
+        averageExecutionTime: number;
+    };
+    /** Event type breakdown */
+    eventTypeBreakdown: Record<PAYMENTEVENTTYPE, number>;
+    /** Error statistics */
+    errorStatistics: {
+        totalErrors: number;
+        errorsByType: Record<string, number>;
+        errorRate: number;
+    };
+    /** Performance statistics */
+    performanceStats: {
+        p50EmissionTime: number;
+        p95EmissionTime: number;
+        p99EmissionTime: number;
+        maxEmissionTime: number;
+    };
+}
+/**
+ * Configuration for payment event emitter.
+ */
+export interface PaymentEventEmitterConfig {
+    /** Maximum number of concurrent event handlers */
+    maxConcurrentHandlers: number;
+    /** Default timeout for event handlers in milliseconds */
+    defaultHandlerTimeout: number;
+    /** Default timeout for event emission in milliseconds */
+    defaultEmissionTimeout: number;
+    /** Whether to enable event persistence */
+    enablePersistence: boolean;
+    /** Whether to enable event metrics collection */
+    enableMetrics: boolean;
+    /** Event queue configuration */
+    queueConfig: {
+        /** Maximum queue size */
+        maxSize: number;
+        /** Queue processing batch size */
+        batchSize: number;
+        /** Queue processing interval in milliseconds */
+        processingInterval: number;
+    };
+    /** Error handling configuration */
+    errorHandling: {
+        /** Strategy for handling emission errors */
+        strategy: 'ignore' | 'log' | 'retry' | 'circuit_breaker';
+        /** Maximum error rate before circuit breaker opens */
+        maxErrorRate: number;
+        /** Circuit breaker timeout in milliseconds */
+        circuitBreakerTimeout: number;
+    };
+    /** Event filtering configuration */
+    filtering: {
+        /** Whether to enable event filtering */
+        enabled: boolean;
+        /** Default event filter if none specified */
+        defaultFilter?: PaymentEventFilter;
+    };
+}

package/dist/payments/events/enums.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Comprehensive enumeration of all payment-related events that can occur
+ * in the system. Events are organized by category and follow a hierarchical
+ * naming convention for easy filtering and subscription.
+ *
+ * Naming Convention:
+ * - Category.Action (e.g., payment.completed)
+ * - Use present tense for ongoing events, past tense for completed events
+ * - Include both success and failure events for complete audit trails
+ */
+export declare enum PAYMENTEVENTTYPE {
+    PaymentInitiated = "payment.initiated",
+    PaymentProcessing = "payment.processing",
+    PaymentRequiresAction = "payment.requires_action",
+    PaymentCompleted = "payment.completed",
+    PaymentFailed = "payment.failed",
+    PaymentCancelled = "payment.cancelled",
+    PaymentExpired = "payment.expired",
+    PaymentAuthorized = "payment.authorized",
+    PaymentCaptured = "payment.captured",
+    PaymentHeld = "payment.held",
+    PaymentReleased = "payment.released",
+    RefundRequested = "refund.requested",
+    RefundApproved = "refund.approved",
+    RefundRejected = "refund.rejected",
+    RefundProcessing = "refund.processing",
+    RefundCompleted = "refund.completed",
+    RefundFailed = "refund.failed",
+    RefundCancelled = "refund.cancelled",
+    ProviderWebhookReceived = "provider.webhook.received",
+    ProviderWebhookProcessed = "provider.webhook.processed",
+    ProviderWebhookFailed = "provider.webhook.failed",
+    ProviderApiCalled = "provider.api.called",
+    ProviderApiSucceeded = "provider.api.succeeded",
+    ProviderApiFailed = "provider.api.failed",
+    ProviderTimeout = "provider.timeout",
+    ProviderHealthChanged = "provider.health.changed",
+    SettlementInitiated = "settlement.initiated",
+    SettlementCompleted = "settlement.completed",
+    SettlementFailed = "settlement.failed",
+    PayoutRequested = "payout.requested",
+    PayoutProcessed = "payout.processed",
+    PayoutFailed = "payout.failed",
+    ChargebackReceived = "chargeback.received",
+    ChargebackResponded = "chargeback.responded",
+    ChargebackWon = "chargeback.won",
+    ChargebackLost = "chargeback.lost",
+    DisputeCreated = "dispute.created",
+    DisputeUpdated = "dispute.updated",
+    DisputeResolved = "dispute.resolved",
+    DisputeEscalated = "dispute.escalated",
+    FraudDetected = "fraud.detected",
+    FraudReviewRequired = "fraud.review_required",
+    FraudCleared = "fraud.cleared",
+    SuspiciousActivity = "suspicious.activity",
+    PaymentBlocked = "payment.blocked",
+    SecurityCheckFailed = "security.check_failed",
+    VelocityLimitExceeded = "velocity.limit_exceeded",
+    PaymentMethodAdded = "payment_method.added",
+    PaymentMethodUpdated = "payment_method.updated",
+    PaymentMethodDeleted = "payment_method.deleted",
+    PaymentMethodVerified = "payment_method.verified",
+    PaymentMethodExpired = "payment_method.expired",
+    SubscriptionCreated = "subscription.created",
+    SubscriptionUpdated = "subscription.updated",
+    SubscriptionCancelled = "subscription.cancelled",
+    SubscriptionRenewed = "subscription.renewed",
+    SubscriptionFailed = "subscription.failed",
+    SubscriptionTrialStarted = "subscription.trial_started",
+    SubscriptionTrialEnded = "subscription.trial_ended",
+    PaymentLimitsUpdated = "payment_limits.updated",
+    PaymentLimitsExceeded = "payment_limits.exceeded",
+    ProviderConfigUpdated = "provider.config_updated",
+    ProviderMaintenanceStarted = "provider.maintenance_started",
+    ProviderMaintenanceEnded = "provider.maintenance_ended",
+    ComplianceCheckRequired = "compliance.check_required",
+    ComplianceCheckPassed = "compliance.check_passed",
+    ComplianceCheckFailed = "compliance.check_failed",
+    AuditTrailCreated = "audit.trail_created",
+    RegulatoryReportGenerated = "regulatory.report_generated"
+}
+/**
+ * Payment event categories for organization and routing.
+ */
+export declare enum PAYMENTEVENTCATEGORY {
+    TRANSACTION = "transaction",
+    REFUND = "refund",
+    PROVIDER = "provider",
+    SECURITY = "security",
+    COMPLIANCE = "compliance",
+    FINANCIAL = "financial",
+    SUBSCRIPTION = "subscription",
+    SYSTEM = "system",
+    AUDIT = "audit"
+}
+/**
+ * Error categories for payment events.
+ */
+export declare enum PAYMENTERRORCATEGORY {
+    UserError = "user_error",// User input or action errors
+    ProviderError = "provider_error",// Payment provider errors
+    SystemError = "system_error",// Internal system errors
+    NetworkError = "network_error",// Network connectivity errors
+    FraudError = "fraud_error",// Fraud detection errors
+    ComplianceError = "compliance_error",// Regulatory compliance errors
+    LimitError = "limit_error",// Limit exceeded errors
+    ConfigurationError = "configuration_error",// Configuration errors
+    TimeoutError = "timeout_error",// Timeout errors
+    ValidationError = "validation_error"
+}

package/dist/payments/events/index.d.ts

@@ -0,0 +1,4 @@
+export * from './enums';
+export type * from './types';
+export type * from './emitter';
+export * from './unified-event';

package/dist/payments/events/types.d.ts

@@ -0,0 +1,151 @@
+import type { PAYMENTMETHOD, PAYMENTPROVIDERTYPE, PAYMENTSTATUS, PRODUCTTYPE, USERTYPE } from '../provider';
+import type { FeeBreakdown, Money } from '../transaction';
+import type { PAYMENTERRORCATEGORY, PAYMENTEVENTCATEGORY, PAYMENTEVENTTYPE } from './enums';
+/**
+ * Core payment event interface that extends the base Event interface
+ * from @plyaz/events while adding payment-specific data and context.
+ */
+export interface PaymentEvent extends Event {
+    /** Payment-specific event type */
+    type: PAYMENTEVENTTYPE;
+    /** Payment event payload with business data */
+    payload: PaymentEventPayload;
+    /** Event metadata for processing and routing */
+    metadata: PaymentEventMetadata;
+}
+/**
+ * Comprehensive payment event payload containing all relevant business
+ * data for the event. The payload structure adapts based on event type
+ * while maintaining common fields for consistency.
+ */
+export interface PaymentEventPayload<TProviderMetadata extends Record<string, string | number | boolean | object | null> = Record<string, string | number | boolean | object | null>, TEventSpecificData extends Record<string, string | number | boolean | object | null> = Record<string, string | number | boolean | object | null>> {
+    /** Transaction ID related to this event (always present) */
+    transactionId: string;
+    /** User ID who initiated or is affected by this event */
+    userId: string;
+    /** Type of user for business logic and permissions */
+    userType: USERTYPE;
+    /** Payment amount and currency (for monetary events) */
+    amount?: Money;
+    /** Payment provider involved in this event */
+    provider: PAYMENTPROVIDERTYPE;
+    /** Current payment status after this event */
+    status: PAYMENTSTATUS;
+    /** Previous status before this event (for status changes) */
+    previousStatus?: PAYMENTSTATUS;
+    /** Payment method used or affected */
+    paymentMethod?: PAYMENTMETHOD;
+    /** Product information related to the payment */
+    productInfo?: {
+        productId: string;
+        productType: PRODUCTTYPE;
+        productTitle?: string;
+    };
+    /** Error information for failed events */
+    error?: PaymentEventError;
+    /** Financial information */
+    financialInfo?: {
+        fees?: FeeBreakdown;
+        settlementDate?: Date;
+        exchangeRate?: number;
+        originalAmount?: Money;
+    };
+    /** Provider-specific information */
+    providerInfo?: {
+        providerTransactionId?: string;
+        providerStatus?: string;
+        providerMetadata?: TProviderMetadata;
+    };
+    /** Security and fraud information */
+    securityInfo?: {
+        fraudScore?: number;
+        riskLevel?: 'low' | 'medium' | 'high';
+        securityFlags?: string[];
+        ipAddress?: string;
+        userAgent?: string;
+    };
+    /** Additional event-specific data */
+    eventSpecificData?: TEventSpecificData;
+    /** When the actual business event occurred (may differ from emission time) */
+    occurredAt: Date;
+}
+/**
+ * Payment event metadata for system processing, routing, and monitoring.
+ */
+export interface PaymentEventMetadata {
+    /** Event processing priority (higher number = higher priority) */
+    priority: number;
+    /** Whether this event requires immediate processing */
+    urgent: boolean;
+    /** Event category for filtering and routing */
+    category: PAYMENTEVENTCATEGORY;
+    /** Tags for event classification and filtering */
+    tags: string[];
+    /** Correlation ID for tracking related events */
+    correlationId?: string;
+    /** Request ID that triggered this event */
+    requestId?: string;
+    /** Event processing configuration */
+    processingConfig?: {
+        /** Whether to persist this event */
+        persist: boolean;
+        /** Retention period for this event */
+        retentionDays?: number;
+        /** Whether to emit to external systems */
+        externalEmission: boolean;
+        /** Retry configuration for failed processing */
+        retryConfig?: EventRetryConfig;
+    };
+    /** Event source information */
+    source: {
+        /** Component that generated this event */
+        component: string;
+        /** Version of the component */
+        version?: string;
+        /** Environment where event was generated */
+        environment: string;
+    };
+}
+/**
+ * Error information interface for failed payment events.
+ */
+export interface PaymentEventError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Error category for handling logic */
+    category: PAYMENTERRORCATEGORY;
+    /** Whether this error condition is retryable */
+    retryable: boolean;
+    /** Provider-specific error code if applicable */
+    providerErrorCode?: string;
+    /** Provider-specific error message */
+    providerErrorMessage?: string;
+    /** Additional error context and debugging information */
+    context?: {
+        /** Stack trace or error details */
+        details?: string;
+        /** Related transaction or operation IDs */
+        relatedIds?: string[];
+        /** Timestamp when error occurred */
+        errorTimestamp: Date;
+        /** Suggested resolution steps */
+        resolutionSteps?: string[];
+    };
+}
+/**
+ * Event retry configuration for failed event processing.
+ */
+export interface EventRetryConfig {
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Initial retry delay in milliseconds */
+    initialDelayMs: number;
+    /** Backoff multiplier for exponential backoff */
+    backoffMultiplier: number;
+    /** Maximum retry delay in milliseconds */
+    maxDelayMs: number;
+    /** Whether to use jitter to avoid thundering herd */
+    useJitter: boolean;
+}

package/dist/payments/events/unified-event/enums.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Event processing status enumeration.
+ */
+export declare enum EVENTPROCESSINGSTATUS {
+    Received = "received",// Event received from provider
+    Validating = "validating",// Signature and format validation
+    Normalizing = "normalizing",// Converting to unified format
+    Normalized = "normalized",// Successfully normalized
+    Processing = "processing",// Business logic processing
+    Completed = "completed",// Processing completed successfully
+    Failed = "failed",// Processing failed
+    Retrying = "retrying",// Retrying after failure
+    Skipped = "skipped"
+}

package/dist/payments/events/unified-event/index.d.ts

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