@serve.zone/dcrouter 2.12.4

package/dist_ts/ts/errors/index.js

@@ -0,0 +1,138 @@
+/**
+ * Platform Service Error System
+ *
+ * This module provides a comprehensive error handling system for the Platform Service,
+ * with structured error types, error codes, and consistent patterns for logging and recovery.
+ */
+// Export error codes and types
+export * from './error.codes.js';
+// Export base error classes
+export * from './base.errors.js';
+// Export domain-specific error classes
+export * from './email.errors.js';
+export * from './mta.errors.js';
+export * from './reputation.errors.js';
+// Export error handler
+export * from './error-handler.js';
+// Export utility function to create specific error types based on the error category
+import { getErrorClassForCategory } from './base.errors.js';
+export { getErrorClassForCategory };
+// Import needed classes for utility functions
+import { PlatformError } from './base.errors.js';
+import { ErrorSeverity, ErrorCategory, ErrorRecoverability } from './error.codes.js';
+/**
+ * Create a typed error from a standard Error
+ * Useful for converting errors from external libraries or APIs
+ *
+ * @param error Standard error to convert
+ * @param code Error code to assign
+ * @param contextData Additional context data
+ * @returns Typed PlatformError
+ */
+export function fromError(error, code, contextData = {}) {
+    return new PlatformError(error.message, code, ErrorSeverity.MEDIUM, ErrorCategory.OPERATION, ErrorRecoverability.NON_RECOVERABLE, {
+        data: {
+            ...contextData,
+            originalError: {
+                name: error.name,
+                message: error.message,
+                stack: error.stack
+            }
+        }
+    });
+}
+/**
+ * Determine if an error is retryable
+ *
+ * @param error Error to check
+ * @returns Boolean indicating if the error should be retried
+ */
+export function isRetryable(error) {
+    // If it's our platform error, use its recoverability property
+    if (error && typeof error === 'object' && 'recoverability' in error) {
+        return error.recoverability === ErrorRecoverability.RECOVERABLE ||
+            error.recoverability === ErrorRecoverability.MAYBE_RECOVERABLE ||
+            error.recoverability === ErrorRecoverability.TRANSIENT;
+    }
+    // Check if it's a network error (these are often transient)
+    if (error && typeof error === 'object' && error.code) {
+        const networkErrors = [
+            'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EHOSTUNREACH',
+            'ENETUNREACH', 'ENOTFOUND', 'EPROTO', 'ECONNABORTED'
+        ];
+        return networkErrors.includes(error.code);
+    }
+    // By default, we can't determine if the error is retryable
+    return false;
+}
+/**
+ * Create a wrapped version of a function that catches errors
+ * and converts them to typed PlatformErrors
+ *
+ * @param fn Function to wrap
+ * @param errorCode Default error code to use
+ * @param contextData Additional context data
+ * @returns Wrapped function
+ */
+export function withErrorHandling(fn, errorCode, contextData = {}) {
+    return (async function (...args) {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'code' in error) {
+                // Already a typed error, rethrow
+                throw error;
+            }
+            throw fromError(error instanceof Error ? error : new Error(String(error)), errorCode, {
+                ...contextData,
+                fnName: fn.name,
+                args: args.map(arg => typeof arg === 'object'
+                    ? '[Object]'
+                    : String(arg).substring(0, 100))
+            });
+        }
+    });
+}
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn Function to retry
+ * @param options Retry options
+ * @returns Function result or throws after max retries
+ */
+export async function retry(fn, options = {}) {
+    const { maxRetries = 3, initialDelay = 1000, maxDelay = 30000, backoffFactor = 2, retryableErrors = [] } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error
+                ? error
+                : new Error(String(error));
+            // Check if we should retry
+            const shouldRetry = attempt < maxRetries && (isRetryable(error) ||
+                retryableErrors.some(pattern => {
+                    if (typeof pattern === 'string') {
+                        return lastError.message.includes(pattern);
+                    }
+                    return pattern.test(lastError.message);
+                }));
+            if (!shouldRetry) {
+                throw lastError;
+            }
+            // Calculate delay with exponential backoff
+            const delay = Math.min(initialDelay * Math.pow(backoffFactor, attempt), maxDelay);
+            // Add jitter to prevent thundering herd problem (±20%)
+            const jitter = 0.8 + Math.random() * 0.4;
+            const actualDelay = Math.floor(delay * jitter);
+            // Wait before next retry
+            await new Promise(resolve => setTimeout(resolve, actualDelay));
+        }
+    }
+    // This should never happen, but TypeScript needs it
+    throw lastError;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9lcnJvcnMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7O0dBS0c7QUFFSCwrQkFBK0I7QUFDL0IsY0FBYyxrQkFBa0IsQ0FBQztBQUVqQyw0QkFBNEI7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUVqQyx1Q0FBdUM7QUFDdkMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsd0JBQXdCLENBQUM7QUFFdkMsdUJBQXVCO0FBQ3ZCLGNBQWMsb0JBQW9CLENBQUM7QUFFbkMscUZBQXFGO0FBQ3JGLE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQzVELE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxDQUFDO0FBRXBDLDhDQUE4QztBQUM5QyxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDakQsT0FBTyxFQUFFLGFBQWEsRUFBRSxhQUFhLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUVyRjs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sVUFBVSxTQUFTLENBQ3ZCLEtBQVksRUFDWixJQUFZLEVBQ1osY0FBbUMsRUFBRTtJQUVyQyxPQUFPLElBQUksYUFBYSxDQUN0QixLQUFLLENBQUMsT0FBTyxFQUNiLElBQUksRUFDSixhQUFhLENBQUMsTUFBTSxFQUNwQixhQUFhLENBQUMsU0FBUyxFQUN2QixtQkFBbUIsQ0FBQyxlQUFlLEVBQ25DO1FBQ0UsSUFBSSxFQUFFO1lBQ0osR0FBRyxXQUFXO1lBQ2QsYUFBYSxFQUFFO2dCQUNiLElBQUksRUFBRSxLQUFLLENBQUMsSUFBSTtnQkFDaEIsT0FBTyxFQUFFLEtBQUssQ0FBQyxPQUFPO2dCQUN0QixLQUFLLEVBQUUsS0FBSyxDQUFDLEtBQUs7YUFDbkI7U0FDRjtLQUNGLENBQ0YsQ0FBQztBQUNKLENBQUM7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

package/dist_ts/ts/errors/mta.errors.d.ts

@@ -0,0 +1,259 @@
+import { PlatformError, NetworkError, AuthenticationError, OperationError, ConfigurationError } from './base.errors.js';
+import type { IErrorContext } from './base.errors.js';
+/**
+ * Base class for MTA connection errors
+ */
+export declare class MtaConnectionError extends NetworkError {
+    /**
+     * Creates a new MTA connection error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for a DNS resolution error
+     *
+     * @param hostname Hostname that failed to resolve
+     * @param originalError Original error
+     * @param context Additional context
+     */
+    static dnsError(hostname: string, originalError?: Error, context?: IErrorContext): MtaConnectionError;
+    /**
+     * Creates an instance for a connection timeout
+     *
+     * @param hostname Hostname that timed out
+     * @param port Port number
+     * @param timeout Timeout in milliseconds
+     * @param context Additional context
+     */
+    static timeout(hostname: string, port: number, timeout: number, context?: IErrorContext): MtaConnectionError;
+    /**
+     * Creates an instance for a connection refused error
+     *
+     * @param hostname Hostname that refused connection
+     * @param port Port number
+     * @param context Additional context
+     */
+    static refused(hostname: string, port: number, context?: IErrorContext): MtaConnectionError;
+}
+/**
+ * Error class for MTA authentication errors
+ */
+export declare class MtaAuthenticationError extends AuthenticationError {
+    /**
+     * Creates a new MTA authentication error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for invalid credentials
+     *
+     * @param hostname Hostname where authentication failed
+     * @param username Username that failed authentication
+     * @param context Additional context
+     */
+    static invalidCredentials(hostname: string, username: string, context?: IErrorContext): MtaAuthenticationError;
+    /**
+     * Creates an instance for unsupported authentication method
+     *
+     * @param hostname Hostname
+     * @param method Authentication method that is not supported
+     * @param supportedMethods List of supported authentication methods
+     * @param context Additional context
+     */
+    static unsupportedMethod(hostname: string, method: string, supportedMethods?: string[], context?: IErrorContext): MtaAuthenticationError;
+}
+/**
+ * Error class for MTA delivery errors
+ */
+export declare class MtaDeliveryError extends OperationError {
+    /**
+     * Creates a new MTA delivery error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for a permanent delivery failure
+     *
+     * @param message Error message
+     * @param recipientAddress Recipient email address
+     * @param statusCode SMTP status code
+     * @param smtpResponse Full SMTP response
+     * @param context Additional context
+     */
+    static permanent(message: string, recipientAddress: string, statusCode?: string, smtpResponse?: string, context?: IErrorContext): MtaDeliveryError;
+    /**
+     * Creates an instance for a temporary delivery failure
+     *
+     * @param message Error message
+     * @param recipientAddress Recipient email address
+     * @param statusCode SMTP status code
+     * @param smtpResponse Full SMTP response
+     * @param maxRetries Maximum number of retries
+     * @param currentRetry Current retry count
+     * @param retryDelay Delay between retries in ms
+     * @param context Additional context
+     */
+    static temporary(message: string, recipientAddress: string, statusCode?: string, smtpResponse?: string, maxRetries?: number, currentRetry?: number, retryDelay?: number, context?: IErrorContext): MtaDeliveryError;
+    /**
+     * Check if this is a permanent delivery failure
+     */
+    isPermanent(): boolean;
+    /**
+     * Get the recipient address associated with this delivery error
+     */
+    getRecipientAddress(): string | undefined;
+    /**
+     * Get the SMTP status code associated with this delivery error
+     */
+    getStatusCode(): string | undefined;
+}
+/**
+ * Error class for MTA configuration errors
+ */
+export declare class MtaConfigurationError extends ConfigurationError {
+    /**
+     * Creates a new MTA configuration error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for a missing configuration value
+     *
+     * @param propertyPath Path to the missing property
+     * @param context Additional context
+     */
+    static missingConfig(propertyPath: string, context?: IErrorContext): MtaConfigurationError;
+    /**
+     * Creates an instance for an invalid configuration value
+     *
+     * @param propertyPath Path to the invalid property
+     * @param value Current value
+     * @param expectedType Expected type or format
+     * @param context Additional context
+     */
+    static invalidConfig(propertyPath: string, value: any, expectedType: string, context?: IErrorContext): MtaConfigurationError;
+}
+/**
+ * Error class for MTA DNS errors
+ */
+export declare class MtaDnsError extends NetworkError {
+    /**
+     * Creates a new MTA DNS error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for an MX record lookup failure
+     *
+     * @param domain Domain that failed MX lookup
+     * @param originalError Original error
+     * @param context Additional context
+     */
+    static mxLookupFailed(domain: string, originalError?: Error, context?: IErrorContext): MtaDnsError;
+    /**
+     * Creates an instance for a TXT record lookup failure
+     *
+     * @param domain Domain that failed TXT lookup
+     * @param recordPrefix Optional record prefix (e.g., 'spf', 'dkim', 'dmarc')
+     * @param originalError Original error
+     * @param context Additional context
+     */
+    static txtLookupFailed(domain: string, recordPrefix?: string, originalError?: Error, context?: IErrorContext): MtaDnsError;
+}
+/**
+ * Error class for MTA timeout errors
+ */
+export declare class MtaTimeoutError extends NetworkError {
+    /**
+     * Creates a new MTA timeout error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for an SMTP command timeout
+     *
+     * @param command SMTP command that timed out
+     * @param server Server hostname
+     * @param timeout Timeout in milliseconds
+     * @param context Additional context
+     */
+    static commandTimeout(command: string, server: string, timeout: number, context?: IErrorContext): MtaTimeoutError;
+    /**
+     * Creates an instance for an overall transaction timeout
+     *
+     * @param server Server hostname
+     * @param timeout Timeout in milliseconds
+     * @param context Additional context
+     */
+    static transactionTimeout(server: string, timeout: number, context?: IErrorContext): MtaTimeoutError;
+}
+/**
+ * Error class for MTA protocol errors
+ */
+export declare class MtaProtocolError extends OperationError {
+    /**
+     * Creates a new MTA protocol error
+     *
+     * @param message Error message
+     * @param context Additional context
+     */
+    constructor(message: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Creates an instance for an unexpected server response
+     *
+     * @param command SMTP command that received unexpected response
+     * @param response Unexpected response
+     * @param expected Expected response pattern
+     * @param server Server hostname
+     * @param context Additional context
+     */
+    static unexpectedResponse(command: string, response: string, expected: string, server: string, context?: IErrorContext): MtaProtocolError;
+    /**
+     * Creates an instance for a syntax error
+     *
+     * @param details Error details
+     * @param server Server hostname
+     * @param context Additional context
+     */
+    static syntaxError(details: string, server: string, context?: IErrorContext): MtaProtocolError;
+}