@serve.zone/dcrouter 2.12.4

package/dist_ts/ts/config/index.d.ts

@@ -0,0 +1 @@
+export * from './validator.js';

package/dist_ts/ts/config/index.js

@@ -0,0 +1,3 @@
+// Export validation tools only
+export * from './validator.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9jb25maWcvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsK0JBQStCO0FBQy9CLGNBQWMsZ0JBQWdCLENBQUMifQ==

package/dist_ts/ts/config/validator.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Validation result
+ */
+export interface IValidationResult {
+    /**
+     * Whether the validation passed
+     */
+    valid: boolean;
+    /**
+     * Validation errors if any
+     */
+    errors?: string[];
+    /**
+     * Validated configuration (may include defaults)
+     */
+    config?: any;
+}
+/**
+ * Validation schema types
+ */
+export type ValidationSchema = Record<string, {
+    /**
+     * Type of the value
+     */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /**
+     * Whether the field is required
+     */
+    required?: boolean;
+    /**
+     * Default value if not specified
+     */
+    default?: any;
+    /**
+     * Minimum value (for numbers)
+     */
+    min?: number;
+    /**
+     * Maximum value (for numbers)
+     */
+    max?: number;
+    /**
+     * Minimum length (for strings or arrays)
+     */
+    minLength?: number;
+    /**
+     * Maximum length (for strings or arrays)
+     */
+    maxLength?: number;
+    /**
+     * Pattern to match (for strings)
+     */
+    pattern?: RegExp;
+    /**
+     * Allowed values (for strings, numbers)
+     */
+    enum?: any[];
+    /**
+     * Nested schema (for objects)
+     */
+    schema?: ValidationSchema;
+    /**
+     * Item schema (for arrays)
+     */
+    items?: {
+        type: 'string' | 'number' | 'boolean' | 'object';
+        schema?: ValidationSchema;
+    };
+    /**
+     * Custom validation function
+     */
+    validate?: (value: any) => boolean | string;
+}>;
+/**
+ * Configuration validator
+ * Validates configuration objects against schemas and provides default values
+ */
+export declare class ConfigValidator {
+    /**
+     * Validate a configuration object against a schema
+     *
+     * @param config Configuration object to validate
+     * @param schema Validation schema
+     * @returns Validation result
+     */
+    static validate<T>(config: T, schema: ValidationSchema): IValidationResult;
+    /**
+     * Apply defaults to a configuration object based on a schema
+     *
+     * @param config Configuration object to apply defaults to
+     * @param schema Validation schema with defaults
+     * @returns Configuration with defaults applied
+     */
+    static applyDefaults<T>(config: T, schema: ValidationSchema): T;
+    /**
+     * Throw a validation error if the configuration is invalid
+     *
+     * @param config Configuration to validate
+     * @param schema Validation schema
+     * @returns Validated configuration with defaults
+     * @throws ValidationError if validation fails
+     */
+    static validateOrThrow<T>(config: T, schema: ValidationSchema): T;
+}

package/dist_ts/ts/config/validator.js

@@ -0,0 +1,152 @@
+import * as plugins from '../plugins.js';
+import { ValidationError } from '../errors/base.errors.js';
+/**
+ * Configuration validator
+ * Validates configuration objects against schemas and provides default values
+ */
+export class ConfigValidator {
+    /**
+     * Validate a configuration object against a schema
+     *
+     * @param config Configuration object to validate
+     * @param schema Validation schema
+     * @returns Validation result
+     */
+    static validate(config, schema) {
+        const errors = [];
+        const validatedConfig = { ...config };
+        // Validate each field against the schema
+        for (const [key, rules] of Object.entries(schema)) {
+            const value = config[key];
+            // Check if required
+            if (rules.required && (value === undefined || value === null)) {
+                errors.push(`${key} is required`);
+                continue;
+            }
+            // If not present and not required, apply default if available
+            if ((value === undefined || value === null)) {
+                if (rules.default !== undefined) {
+                    validatedConfig[key] = rules.default;
+                }
+                continue;
+            }
+            // Type validation
+            if (value !== undefined && value !== null) {
+                const valueType = Array.isArray(value) ? 'array' : typeof value;
+                if (valueType !== rules.type) {
+                    errors.push(`${key} must be of type ${rules.type}, got ${valueType}`);
+                    continue;
+                }
+                // Type-specific validations
+                switch (rules.type) {
+                    case 'number':
+                        if (rules.min !== undefined && value < rules.min) {
+                            errors.push(`${key} must be at least ${rules.min}`);
+                        }
+                        if (rules.max !== undefined && value > rules.max) {
+                            errors.push(`${key} must be at most ${rules.max}`);
+                        }
+                        break;
+                    case 'string':
+                        if (rules.minLength !== undefined && value.length < rules.minLength) {
+                            errors.push(`${key} must be at least ${rules.minLength} characters`);
+                        }
+                        if (rules.maxLength !== undefined && value.length > rules.maxLength) {
+                            errors.push(`${key} must be at most ${rules.maxLength} characters`);
+                        }
+                        if (rules.pattern && !rules.pattern.test(value)) {
+                            errors.push(`${key} must match pattern ${rules.pattern}`);
+                        }
+                        break;
+                    case 'array':
+                        if (rules.minLength !== undefined && value.length < rules.minLength) {
+                            errors.push(`${key} must have at least ${rules.minLength} items`);
+                        }
+                        if (rules.maxLength !== undefined && value.length > rules.maxLength) {
+                            errors.push(`${key} must have at most ${rules.maxLength} items`);
+                        }
+                        if (rules.items && value.length > 0) {
+                            for (let i = 0; i < value.length; i++) {
+                                const itemType = Array.isArray(value[i]) ? 'array' : typeof value[i];
+                                if (itemType !== rules.items.type) {
+                                    errors.push(`${key}[${i}] must be of type ${rules.items.type}, got ${itemType}`);
+                                }
+                                else if (rules.items.schema && itemType === 'object') {
+                                    const itemResult = this.validate(value[i], rules.items.schema);
+                                    if (!itemResult.valid) {
+                                        errors.push(...itemResult.errors.map(err => `${key}[${i}].${err}`));
+                                    }
+                                }
+                            }
+                        }
+                        break;
+                    case 'object':
+                        if (rules.schema) {
+                            const nestedResult = this.validate(value, rules.schema);
+                            if (!nestedResult.valid) {
+                                errors.push(...nestedResult.errors.map(err => `${key}.${err}`));
+                            }
+                            validatedConfig[key] = nestedResult.config;
+                        }
+                        break;
+                }
+                // Enum validation
+                if (rules.enum && !rules.enum.includes(value)) {
+                    errors.push(`${key} must be one of [${rules.enum.join(', ')}]`);
+                }
+                // Custom validation
+                if (rules.validate) {
+                    const result = rules.validate(value);
+                    if (result !== true) {
+                        errors.push(typeof result === 'string' ? result : `${key} failed custom validation`);
+                    }
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            config: validatedConfig
+        };
+    }
+    /**
+     * Apply defaults to a configuration object based on a schema
+     *
+     * @param config Configuration object to apply defaults to
+     * @param schema Validation schema with defaults
+     * @returns Configuration with defaults applied
+     */
+    static applyDefaults(config, schema) {
+        const result = { ...config };
+        for (const [key, rules] of Object.entries(schema)) {
+            if (result[key] === undefined && rules.default !== undefined) {
+                result[key] = rules.default;
+            }
+            // Apply defaults to nested objects
+            if (result[key] && rules.type === 'object' && rules.schema) {
+                result[key] = this.applyDefaults(result[key], rules.schema);
+            }
+            // Apply defaults to array items
+            if (result[key] && rules.type === 'array' && rules.items && rules.items.schema) {
+                result[key] = result[key].map(item => typeof item === 'object' ? this.applyDefaults(item, rules.items.schema) : item);
+            }
+        }
+        return result;
+    }
+    /**
+     * Throw a validation error if the configuration is invalid
+     *
+     * @param config Configuration to validate
+     * @param schema Validation schema
+     * @returns Validated configuration with defaults
+     * @throws ValidationError if validation fails
+     */
+    static validateOrThrow(config, schema) {
+        const result = this.validate(config, schema);
+        if (!result.valid) {
+            throw new ValidationError(`Configuration validation failed: ${result.errors.join(', ')}`, 'CONFIG_VALIDATION_ERROR', { data: { errors: result.errors } });
+        }
+        return result.config;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvY29uZmlnL3ZhbGlkYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUN6QyxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUEwRjNEOzs7R0FHRztBQUNILE1BQU0sT0FBTyxlQUFlO0lBRTFCOzs7Ozs7T0FNRztJQUNJLE1BQU0sQ0FBQyxRQUFRLENBQUksTUFBUyxFQUFFLE1BQXdCO1FBQzNELE1BQU0sTUFBTSxHQUFhLEVBQUUsQ0FBQztRQUM1QixNQUFNLGVBQWUsR0FBRyxFQUFFLEdBQUcsTUFBTSxFQUFFLENBQUM7UUFFdEMseUNBQXlDO1FBQ3pDLEtBQUssTUFBTSxDQUFDLEdBQUcsRUFBRSxLQUFLLENBQUMsSUFBSSxNQUFNLENBQUMsT0FBTyxDQUFDLE1BQU0sQ0FBQyxFQUFFLENBQUM7WUFDbEQsTUFBTSxLQUFLLEdBQUcsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDO1lBRTFCLG9CQUFvQjtZQUNwQixJQUFJLEtBQUssQ0FBQyxRQUFRLElBQUksQ0FBQyxLQUFLLEtBQUssU0FBUyxJQUFJLEtBQUssS0FBSyxJQUFJLENBQUMsRUFBRSxDQUFDO2dCQUM5RCxNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsR0FBRyxjQUFjLENBQUMsQ0FBQztnQkFDbEMsU0FBUztZQUNYLENBQUM7WUFFRCw4REFBOEQ7WUFDOUQsSUFBSSxDQUFDLEtBQUssS0FBSyxTQUFTLElBQUksS0FBSyxLQUFLLElBQUksQ0FBQyxFQUFFLENBQUM7Z0JBQzVDLElBQUksS0FBSyxDQUFDLE9BQU8sS0FBSyxTQUFTLEVBQUUsQ0FBQztvQkFDaEMsZUFBZSxDQUFDLEdBQUcsQ0FBQyxHQUFHLEtBQUssQ0FBQyxPQUFPLENBQUM7Z0JBQ3ZDLENBQUM7Z0JBQ0QsU0FBUztZQUNYLENBQUM7WUFFRCxr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

package/dist_ts/ts/deliverability/classes.ipwarmupmanager.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Represents a single stage in the warmup process
+ */
+export interface IWarmupStage {
+    /** Stage number (1-based) */
+    stage: number;
+    /** Maximum daily email volume for this stage */
+    maxDailyVolume: number;
+    /** Duration of this stage in days */
+    durationDays: number;
+    /** Target engagement metrics for this stage */
+    targetMetrics?: {
+        /** Minimum open rate (percentage) */
+        minOpenRate?: number;
+        /** Maximum bounce rate (percentage) */
+        maxBounceRate?: number;
+        /** Maximum spam complaint rate (percentage) */
+        maxComplaintRate?: number;
+    };
+}
+/**
+ * Configuration for IP warmup process
+ */
+export interface IIPWarmupConfig {
+    /** Whether the warmup is enabled */
+    enabled?: boolean;
+    /** List of IP addresses to warm up */
+    ipAddresses?: string[];
+    /** Target domains to warm up (e.g. your sending domains) */
+    targetDomains?: string[];
+    /** Warmup stages defining volume and duration */
+    stages?: IWarmupStage[];
+    /** Date when warmup process started */
+    startDate?: Date;
+    /** Default hourly distribution for sending (percentage of daily volume per hour) */
+    hourlyDistribution?: number[];
+    /** Whether to automatically advance stages based on metrics */
+    autoAdvanceStages?: boolean;
+    /** Whether to suspend warmup if metrics decline */
+    suspendOnMetricDecline?: boolean;
+    /** Percentage of traffic to send through fallback provider during warmup */
+    fallbackPercentage?: number;
+    /** Whether to prioritize engaged subscribers during warmup */
+    prioritizeEngagedSubscribers?: boolean;
+}
+/**
+ * Status for a specific IP's warmup process
+ */
+export interface IIPWarmupStatus {
+    /** IP address being warmed up */
+    ipAddress: string;
+    /** Current warmup stage */
+    currentStage: number;
+    /** Start date of the warmup process */
+    startDate: Date;
+    /** Start date of the current stage */
+    currentStageStartDate: Date;
+    /** Target completion date for entire warmup */
+    targetCompletionDate: Date;
+    /** Daily volume allocation for current stage */
+    currentDailyAllocation: number;
+    /** Emails sent in current stage */
+    sentInCurrentStage: number;
+    /** Total emails sent during warmup process */
+    totalSent: number;
+    /** Whether the warmup is currently active */
+    isActive: boolean;
+    /** Daily statistics for the past week */
+    dailyStats: Array<{
+        /** Date of the statistics */
+        date: string;
+        /** Number of emails sent */
+        sent: number;
+        /** Number of emails opened */
+        opened: number;
+        /** Number of bounces */
+        bounces: number;
+        /** Number of spam complaints */
+        complaints: number;
+    }>;
+    /** Current metrics */
+    metrics: {
+        /** Open rate percentage */
+        openRate: number;
+        /** Bounce rate percentage */
+        bounceRate: number;
+        /** Complaint rate percentage */
+        complaintRate: number;
+    };
+}
+/**
+ * Defines methods for a policy used to allocate emails to different IPs
+ */
+export interface IIPAllocationPolicy {
+    /** Name of the policy */
+    name: string;
+    /**
+     * Allocate an IP address for sending an email
+     * @param availableIPs List of available IP addresses
+     * @param emailInfo Information about the email being sent
+     * @returns The IP to use, or null if no IP is available
+     */
+    allocateIP(availableIPs: Array<{
+        ip: string;
+        priority: number;
+        capacity: number;
+    }>, emailInfo: {
+        from: string;
+        to: string[];
+        domain: string;
+        isTransactional: boolean;
+        isWarmup: boolean;
+    }): string | null;
+}
+/**
+ * Manages the IP warming process for new sending IPs
+ */
+export declare class IPWarmupManager {
+    private static instance;
+    private config;
+    private warmupStatuses;
+    private dailySendCounts;
+    private hourlySendCounts;
+    private isInitialized;
+    private allocationPolicies;
+    private activePolicy;
+    /**
+     * Constructor for IPWarmupManager
+     * @param config Warmup configuration
+     */
+    constructor(config?: IIPWarmupConfig);
+    /**
+     * Get the singleton instance of IPWarmupManager
+     * @param config Warmup configuration
+     * @returns Singleton instance
+     */
+    static getInstance(config?: IIPWarmupConfig): IPWarmupManager;
+    /**
+     * Initialize the warmup manager
+     */
+    private initialize;
+    /**
+     * Initialize warmup status for a new IP address
+     * @param ipAddress IP address to initialize
+     */
+    private initializeIPWarmup;
+    /**
+     * Schedule daily reset of send counters
+     */
+    private scheduleDailyReset;
+    /**
+     * Reset daily send counters
+     */
+    private resetDailyCounts;
+    /**
+     * Schedule daily evaluation of warmup progress
+     */
+    private scheduleDailyEvaluation;
+    /**
+     * Evaluate warmup progress and possibly advance stages
+     */
+    private evaluateWarmupProgress;
+    /**
+     * Check if the current metrics meet the requirements for the stage
+     * @param status Warmup status to check
+     * @param stage Stage to check against
+     * @returns Whether metrics meet requirements
+     */
+    private checkStageMetrics;
+    /**
+     * Advance IP to the next warmup stage
+     * @param ipAddress IP address to advance
+     */
+    private advanceToNextStage;
+    /**
+     * Get warmup status for all IPs or a specific IP
+     * @param ipAddress Optional specific IP to get status for
+     * @returns Warmup status information
+     */
+    getWarmupStatus(ipAddress?: string): IIPWarmupStatus | Map<string, IIPWarmupStatus>;
+    /**
+     * Add a new IP address to the warmup process
+     * @param ipAddress IP address to add
+     */
+    addIPToWarmup(ipAddress: string): void;
+    /**
+     * Remove an IP address from the warmup process
+     * @param ipAddress IP address to remove
+     */
+    removeIPFromWarmup(ipAddress: string): void;
+    /**
+     * Update metrics for an IP address
+     * @param ipAddress IP address to update
+     * @param metrics New metrics
+     */
+    updateMetrics(ipAddress: string, metrics: {
+        openRate?: number;
+        bounceRate?: number;
+        complaintRate?: number;
+    }): void;
+    /**
+     * Record a send event for an IP address
+     * @param ipAddress IP address used for sending
+     */
+    recordSend(ipAddress: string): void;
+    /**
+     * Check if an IP can send more emails today
+     * @param ipAddress IP address to check
+     * @returns Whether the IP can send more emails
+     */
+    canSendMoreToday(ipAddress: string): boolean;
+    /**
+     * Check if an IP can send more emails in the current hour
+     * @param ipAddress IP address to check
+     * @returns Whether the IP can send more emails this hour
+     */
+    canSendMoreThisHour(ipAddress: string): boolean;
+    /**
+     * Get the best IP to use for sending an email
+     * @param emailInfo Information about the email being sent
+     * @returns The best IP to use, or null if no suitable IP is available
+     */
+    getBestIPForSending(emailInfo: {
+        from: string;
+        to: string[];
+        domain: string;
+        isTransactional?: boolean;
+    }): string | null;
+    /**
+     * Register a new IP allocation policy
+     * @param name Policy name
+     * @param policy Policy implementation
+     */
+    registerAllocationPolicy(name: string, policy: IIPAllocationPolicy): void;
+    /**
+     * Set the active IP allocation policy
+     * @param name Policy name
+     */
+    setActiveAllocationPolicy(name: string): void;
+    /**
+     * Get the total number of stages in the warmup process
+     * @returns Number of stages
+     */
+    getStageCount(): number;
+    /**
+     * Load warmup statuses from storage
+     */
+    private loadWarmupStatuses;
+    /**
+     * Save warmup statuses to storage
+     */
+    private saveWarmupStatuses;
+}