@plyaz/types 1.11.4 → 1.12.0

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

@@ -0,0 +1,346 @@
+import type { PAYMENTPROVIDERTYPE, PAYMENTSTATUS } from '../../provider';
+import type { PAYMENTEVENTTYPE } from '../enums';
+import type { PaymentEventPayload } from '../types';
+import type { EVENTPROCESSINGSTATUS } from './enums';
+/**
+ * Unified provider event interface that normalizes all provider events
+ * into a consistent format while preserving original provider data.
+ *
+ * This system enables:
+ * - Consistent event processing across all providers
+ * - Provider-specific data preservation for debugging
+ * - Configurable event mapping and normalization
+ * - Quality metrics for normalization accuracy
+ */
+export interface UnifiedProviderEvent<TRawEvent extends object = {}, TNormalizedData extends PaymentEventPayload = PaymentEventPayload, TProcessingMetadata extends EventProcessingMetadata = EventProcessingMetadata> {
+    /** Unique event ID generated by our system */
+    id: string;
+    /** Provider that sent this event */
+    provider: PAYMENTPROVIDERTYPE;
+    /** Provider's original event ID for reference */
+    providerEventId: string;
+    /** Provider's original event type as received */
+    providerEventType: string;
+    /** Our normalized event type */
+    normalizedEventType: PAYMENTEVENTTYPE;
+    /** Normalized event data in our standard format */
+    normalizedData: TNormalizedData;
+    /** Original raw event data from provider (for debugging/audit) */
+    rawEventData: TRawEvent;
+    /** Processing metadata and quality metrics */
+    processingMetadata: TProcessingMetadata;
+    /** Timestamp when we received the event from provider */
+    receivedAt: Date;
+    /** Timestamp when event occurred at provider (if available) */
+    providerTimestamp?: Date;
+    /** Signature verification result */
+    signatureVerified: boolean;
+    /** Event processing status */
+    processingStatus: EVENTPROCESSINGSTATUS;
+}
+/**
+ * Event processing metadata for quality tracking and debugging.
+ */
+export interface EventProcessingMetadata {
+    /** Whether event was successfully normalized */
+    normalized: boolean;
+    /** Confidence level of normalization (0.0 - 1.0) */
+    normalizationConfidence: number;
+    /** Quality score based on data completeness (0.0 - 1.0) */
+    qualityScore: number;
+    /** Issues encountered during normalization */
+    normalizationIssues: EventNormalizationIssue[];
+    /** Whether this event type is fully supported */
+    fullySupported: boolean;
+    /** Mapping rule version used for normalization */
+    mappingRuleVersion: string;
+    /** Processing time in milliseconds */
+    processingTime: number;
+    /** Data extraction results */
+    extractionResults: DataExtractionResult[];
+    /** Additional processing notes and warnings */
+    processingNotes: string[];
+    /** Fallback rules applied during processing */
+    fallbacksApplied: string[];
+}
+/**
+ * Normalization issue types for tracking processing problems.
+ */
+/**
+ * Normalization issue types for tracking processing problems.
+ */
+export interface EventNormalizationIssue<TExpected extends object | string | number | boolean | null = {}, TActual extends object | string | number | boolean | null = {}> {
+    /** Severity level of the issue */
+    severity: 'info' | 'warning' | 'error' | 'critical';
+    /** Issue code for programmatic handling */
+    code: string;
+    /** Human-readable description */
+    description: string;
+    /** Field or data path where issue occurred */
+    fieldPath?: string;
+    /** Expected value or format */
+    expected?: TExpected;
+    /** Actual value received */
+    actual?: TActual;
+    /** Suggested resolution */
+    resolution?: string;
+}
+/**
+ * Data extraction result for tracking field extraction success.
+ */
+export interface DataExtractionResult<TValue extends object | string | number | boolean | null = {}> {
+    /** Field name being extracted */
+    fieldName: string;
+    /** Whether extraction was successful */
+    success: boolean;
+    /** Extracted value */
+    value?: TValue;
+    /** Data path used for extraction */
+    extractionPath: string | string[];
+    /** Confidence level of extraction (0.0 - 1.0) */
+    confidence: number;
+    /** Fallback method used if primary extraction failed */
+    fallbackMethod?: string;
+    /** Error message if extraction failed */
+    error?: string;
+}
+/**
+ * Provider event mapping configuration for dynamic event processing.
+ * This configuration allows updating event processing rules without code changes.
+ */
+export interface ProviderEventMapping {
+    /** Provider this mapping applies to */
+    provider: PAYMENTPROVIDERTYPE;
+    /** Provider API version this mapping supports */
+    providerApiVersion?: string;
+    /** Mapping configuration version */
+    mappingVersion: string;
+    /** Event type mappings from provider to normalized types */
+    eventTypeMappings: EventTypeMapping[];
+    /** Status mappings from provider to normalized statuses */
+    statusMappings: StatusMapping[];
+    /** Data extraction rules for converting provider data */
+    dataExtractionRules: ProviderDataExtractionRules;
+    /** Validation rules for provider events */
+    validationRules: ProviderValidationRules;
+    /** Default values for missing or invalid data */
+    defaultValues: DefaultValueRules;
+    /** Special handling rules for edge cases */
+    specialHandlingRules: SpecialHandlingRule[];
+}
+/**
+ * Event type mapping from provider-specific to normalized events.
+ */
+export interface EventTypeMapping {
+    /** Provider's event type */
+    providerEventType: string;
+    /** Our normalized event type */
+    normalizedEventType: PAYMENTEVENTTYPE;
+    /** Confidence level of this mapping (0.0 - 1.0) */
+    confidence: number;
+    /** Whether this mapping is currently active */
+    active: boolean;
+    /** Additional conditions for this mapping to apply */
+    conditions?: MappingCondition[];
+    /** Priority if multiple mappings match (higher = more priority) */
+    priority: number;
+}
+/**
+ * Status mapping from provider-specific to normalized statuses.
+ */
+export interface StatusMapping<TContext extends object = {}> {
+    /** Provider's status value */
+    providerStatus: string;
+    /** Our normalized status */
+    normalizedStatus: PAYMENTSTATUS;
+    /** Additional context required for this mapping */
+    context?: TContext;
+    /** Whether this is a terminal status */
+    terminal: boolean;
+}
+/**
+ * Comprehensive data extraction rules for provider events.
+ */
+export interface ProviderDataExtractionRules {
+    /** How to extract transaction ID from provider event */
+    transactionId: DataExtractionRule;
+    /** How to extract payment amount */
+    amount?: DataExtractionRule;
+    /** How to extract currency information */
+    currency?: DataExtractionRule;
+    /** How to extract payment status */
+    status?: DataExtractionRule;
+    /** How to extract error information */
+    error?: DataExtractionRule;
+    /** How to extract provider transaction ID */
+    providerTransactionId?: DataExtractionRule;
+    /** How to extract customer/user information */
+    customerId?: DataExtractionRule;
+    /** How to extract payment method information */
+    paymentMethod?: DataExtractionRule;
+    /** How to extract metadata and custom fields */
+    metadata?: DataExtractionRule;
+    /** Custom extraction rules for provider-specific fields */
+    customFields?: Record<string, DataExtractionRule>;
+}
+/**
+ * Individual data extraction rule configuration.
+ */
+export interface DataExtractionRule<T extends string | number | boolean | object | null = string | number | boolean | object | null> {
+    /** Primary extraction path (JSONPath or dot notation) */
+    primaryPath: string | string[];
+    /** Fallback extraction paths if primary fails */
+    fallbackPaths?: Array<string | string[]>;
+    /** Data transformation function to apply */
+    transformation?: DataTransformation;
+    /** Validation rules for extracted data */
+    validation?: DataValidationRule;
+    /** Default value if extraction fails */
+    defaultValue?: T;
+    /** Whether this field is required */
+    required: boolean;
+    /** Data type expected */
+    expectedType: 'string' | 'number' | 'boolean' | 'object' | 'array';
+}
+/**
+ * Data transformation configuration.
+ */
+export interface DataTransformation<TParams extends object = {}> {
+    /** Type of transformation to apply */
+    type: 'map' | 'format' | 'calculate' | 'normalize' | 'custom';
+    /** Transformation parameters */
+    parameters: TParams;
+    /** Custom transformation function reference */
+    customFunction?: string;
+}
+/**
+ * Data validation rule configuration.
+ */
+/**
+ * Data validation rule configuration.
+ */
+export interface DataValidationRule<TParams extends object = Record<string, string | number | boolean>> {
+    /** Validation type */
+    type: 'regex' | 'range' | 'enum' | 'length' | 'custom';
+    /** Validation parameters — strongly typed using generics */
+    parameters: TParams;
+    /** Error message if validation fails */
+    errorMessage?: string;
+}
+/**
+ * Mapping condition for conditional event type mapping.
+ */
+export interface MappingCondition<TValue = string | number | boolean> {
+    /** Field path to check */
+    fieldPath: string;
+    /** Condition operator */
+    operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'exists' | 'not_exists' | 'regex';
+    /** Value to compare against */
+    value?: TValue;
+    /** Whether condition is required or optional */
+    required: boolean;
+}
+/**
+ * Provider validation rules for incoming events.
+ */
+export interface ProviderValidationRules<TSchema extends object = object> {
+    /** Required fields that must be present */
+    requiredFields: string[];
+    /** Field format validations */
+    fieldValidations: Record<string, DataValidationRule>;
+    /** Event structure validation schema */
+    structureValidation?: TSchema;
+    /** Business logic validations */
+    businessValidations?: BusinessValidationRule[];
+}
+/**
+ * Business validation rule for provider events.
+ */
+export interface BusinessValidationRule {
+    /** Rule identifier */
+    ruleId: string;
+    /** Rule description */
+    description: string;
+    /** Validation logic */
+    validation: {
+        /** Field to validate */
+        field: string;
+        /** Validation conditions */
+        conditions: ValidationCondition[];
+    };
+    /** Error details if validation fails */
+    error: {
+        code: string;
+        message: string;
+        severity: 'warning' | 'error' | 'critical';
+    };
+}
+/**
+ * Validation condition for business rules.
+ */
+export interface ValidationCondition<TParams extends object = Record<string, string | number | boolean>> {
+    /** Condition type */
+    type: 'range' | 'enum' | 'pattern' | 'custom';
+    /** Condition parameters */
+    parameters: TParams;
+    /** Whether condition must pass */
+    mustPass: boolean;
+}
+/**
+ * Default value rules for missing or invalid data.
+ */
+export interface DefaultValueRules<TField extends string = string, TValue = string | number | boolean> {
+    fieldDefaults: Record<TField, TValue>;
+    conditionalDefaults: ConditionalDefault<TField, TValue>[];
+    generationRules: DefaultGenerationRule<TField>[];
+}
+/**
+ * Conditional default value configuration.
+ */
+export interface ConditionalDefault<TField extends string = string, TValue = string | number | boolean> {
+    /** Condition that must be met */
+    condition: MappingCondition<TValue>;
+    /** Field to set default value for */
+    targetField: TField;
+    /** Default value to use */
+    defaultValue: TValue;
+}
+/**
+ * Default value generation rule.
+ */
+export interface DefaultGenerationRule<TField extends string = string, TParams extends object = Record<string, string | number | boolean>> {
+    /** Field to generate default for */
+    field: TField;
+    /** Generation method */
+    method: 'uuid' | 'timestamp' | 'calculated' | 'derived' | 'custom';
+    /** Generation parameters */
+    parameters?: TParams;
+}
+/**
+ * Special handling rule for edge cases and provider-specific behavior.
+ */
+export interface SpecialHandlingRule {
+    /** Rule identifier */
+    ruleId: string;
+    /** Rule description */
+    description: string;
+    /** Conditions that trigger this rule */
+    triggers: MappingCondition[];
+    /** Actions to take when rule is triggered */
+    actions: SpecialHandlingAction[];
+    /** Priority of this rule (higher = more priority) */
+    priority: number;
+    /** Whether rule is currently active */
+    active: boolean;
+}
+/**
+ * Special handling action configuration.
+ */
+export interface SpecialHandlingAction<TParams extends object = Record<string, string | number | boolean>> {
+    /** Action type */
+    type: 'modify_data' | 'set_status' | 'add_metadata' | 'trigger_event' | 'log_warning' | 'custom';
+    /** Action parameters — strongly typed using generics */
+    parameters: TParams;
+    /** Whether action is critical */
+    critical: boolean;
+}

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

@@ -0,0 +1,2 @@
+export type * from './provider';
+export * from './routings';

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

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