@serve.zone/dcrouter 13.17.0 → 13.17.2

package/dist_ts/errors/base.errors.d.ts

@@ -0,0 +1,224 @@
+import { ErrorSeverity, ErrorCategory, ErrorRecoverability } from './error.codes.js';
+/**
+ * Context information added to structured errors
+ */
+export interface IErrorContext {
+    /** Component or service where the error occurred */
+    component?: string;
+    /** Operation that was being performed */
+    operation?: string;
+    /** Unique request ID if available */
+    requestId?: string;
+    /** Error occurred at timestamp */
+    timestamp?: number;
+    /** User-visible message (safe to display to end-users) */
+    userMessage?: string;
+    /** Additional structured data for debugging */
+    data?: Record<string, any>;
+    /** Related entity IDs if applicable */
+    entity?: {
+        type: string;
+        id: string | number;
+    };
+    /** Stack trace (if enabled in configuration) */
+    stack?: string;
+    /** Retry information if applicable */
+    retry?: {
+        /** Maximum number of retries allowed */
+        maxRetries?: number;
+        /** Current retry count */
+        currentRetry?: number;
+        /** Next retry timestamp */
+        nextRetryAt?: number;
+        /** Delay between retries (in ms) */
+        retryDelay?: number;
+    };
+}
+/**
+ * Base class for all errors in the Platform Service
+ * Adds structured error information, logging, and error tracking
+ */
+export declare class PlatformError extends Error {
+    /** Error code identifying the specific error type */
+    readonly code: string;
+    /** Error severity level */
+    readonly severity: ErrorSeverity;
+    /** Error category for grouping related errors */
+    readonly category: ErrorCategory;
+    /** Whether the error can be recovered from automatically */
+    readonly recoverability: ErrorRecoverability;
+    /** Additional context information */
+    readonly context: IErrorContext;
+    /**
+     * Creates a new PlatformError
+     *
+     * @param message Error message
+     * @param code Error code from error.codes.ts
+     * @param severity Error severity level
+     * @param category Error category
+     * @param recoverability Error recoverability indication
+     * @param context Additional context information
+     */
+    constructor(message: string, code: string, severity?: ErrorSeverity, category?: ErrorCategory, recoverability?: ErrorRecoverability, context?: IErrorContext);
+    /**
+     * Logs the error using the platform logger
+     */
+    private logError;
+    /**
+     * Maps severity levels to log levels
+     */
+    private getLogLevelFromSeverity;
+    /**
+     * Returns a JSON representation of the error
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Creates an instance with retry information
+     *
+     * @param maxRetries Maximum number of retries
+     * @param currentRetry Current retry count
+     * @param retryDelay Delay between retries in ms
+     */
+    withRetry(maxRetries: number, currentRetry?: number, retryDelay?: number): PlatformError;
+    /**
+     * Protected method to create a new instance with updated context
+     * Subclasses can override this to handle their own constructor signatures
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Checks if the error should be retried based on retry information
+     */
+    shouldRetry(): boolean;
+    /**
+     * Returns a user-friendly message that is safe to display to end users
+     */
+    getUserMessage(): string;
+}
+/**
+ * Error class for validation errors
+ */
+export declare class ValidationError extends PlatformError {
+    /**
+     * Creates a new validation error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ValidationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for configuration errors
+ */
+export declare class ConfigurationError extends PlatformError {
+    /**
+     * Creates a new configuration error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ConfigurationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for network-related errors
+ */
+export declare class NetworkError extends PlatformError {
+    /**
+     * Creates a new network error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle NetworkError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for resource availability errors (rate limits, quotas)
+ */
+export declare class ResourceError extends PlatformError {
+    /**
+     * Creates a new resource error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ResourceError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for authentication/authorization errors
+ */
+export declare class AuthenticationError extends PlatformError {
+    /**
+     * Creates a new authentication error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle AuthenticationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for operation errors (API calls, processing)
+ */
+export declare class OperationError extends PlatformError {
+    /**
+     * Creates a new operation error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle OperationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for critical system errors
+ */
+export declare class SystemError extends PlatformError {
+    /**
+     * Creates a new system error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+}
+/**
+ * Helper to get the appropriate error class based on error category
+ *
+ * @param category Error category
+ * @returns The appropriate error class
+ */
+export declare function getErrorClassForCategory(category: ErrorCategory): any;

package/dist_ts/errors/base.errors.js

@@ -0,0 +1,320 @@
+import { ErrorSeverity, ErrorCategory, ErrorRecoverability } from './error.codes.js';
+import { logger } from '../logger.js';
+/**
+ * Base class for all errors in the Platform Service
+ * Adds structured error information, logging, and error tracking
+ */
+export class PlatformError extends Error {
+    /** Error code identifying the specific error type */
+    code;
+    /** Error severity level */
+    severity;
+    /** Error category for grouping related errors */
+    category;
+    /** Whether the error can be recovered from automatically */
+    recoverability;
+    /** Additional context information */
+    context;
+    /**
+     * Creates a new PlatformError
+     *
+     * @param message Error message
+     * @param code Error code from error.codes.ts
+     * @param severity Error severity level
+     * @param category Error category
+     * @param recoverability Error recoverability indication
+     * @param context Additional context information
+     */
+    constructor(message, code, severity = ErrorSeverity.MEDIUM, category = ErrorCategory.OTHER, recoverability = ErrorRecoverability.NON_RECOVERABLE, context = {}) {
+        super(message);
+        // Set error metadata
+        this.name = this.constructor.name;
+        this.code = code;
+        this.severity = severity;
+        this.category = category;
+        this.recoverability = recoverability;
+        // Add timestamp if not provided
+        this.context = {
+            ...context,
+            timestamp: context.timestamp || Date.now(),
+        };
+        // Capture stack trace
+        Error.captureStackTrace(this, this.constructor);
+        // Log the error automatically unless explicitly disabled
+        if (!context.data?.skipLogging) {
+            this.logError();
+        }
+    }
+    /**
+     * Logs the error using the platform logger
+     */
+    logError() {
+        const logLevel = this.getLogLevelFromSeverity();
+        // Construct structured log entry
+        const logData = {
+            error_code: this.code,
+            error_name: this.name,
+            severity: this.severity,
+            category: this.category,
+            recoverability: this.recoverability,
+            ...this.context
+        };
+        // Log with appropriate level
+        logger.log(logLevel, this.message, logData);
+    }
+    /**
+     * Maps severity levels to log levels
+     */
+    getLogLevelFromSeverity() {
+        switch (this.severity) {
+            case ErrorSeverity.CRITICAL:
+            case ErrorSeverity.HIGH:
+                return 'error';
+            case ErrorSeverity.MEDIUM:
+                return 'warn';
+            case ErrorSeverity.LOW:
+                return 'info';
+            case ErrorSeverity.INFO:
+                return 'debug';
+            default:
+                return 'error';
+        }
+    }
+    /**
+     * Returns a JSON representation of the error
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            severity: this.severity,
+            category: this.category,
+            recoverability: this.recoverability,
+            context: this.context,
+            stack: process.env.NODE_ENV !== 'production' ? this.stack : undefined
+        };
+    }
+    /**
+     * Creates an instance with retry information
+     *
+     * @param maxRetries Maximum number of retries
+     * @param currentRetry Current retry count
+     * @param retryDelay Delay between retries in ms
+     */
+    withRetry(maxRetries, currentRetry = 0, retryDelay = 1000) {
+        const nextRetryAt = Date.now() + retryDelay;
+        // Clone the error with updated context
+        const newContext = {
+            ...this.context,
+            retry: {
+                maxRetries,
+                currentRetry,
+                nextRetryAt,
+                retryDelay
+            }
+        };
+        // Create a new instance using the protected method that subclasses can override
+        const newError = this.createWithContext(newContext);
+        // Update recoverability if we can retry
+        if (currentRetry < maxRetries && newError.recoverability === ErrorRecoverability.NON_RECOVERABLE) {
+            newError.recoverability = ErrorRecoverability.MAYBE_RECOVERABLE;
+        }
+        return newError;
+    }
+    /**
+     * Protected method to create a new instance with updated context
+     * Subclasses can override this to handle their own constructor signatures
+     */
+    createWithContext(context) {
+        // Default implementation for PlatformError
+        return new this.constructor(this.message, this.code, this.severity, this.category, this.recoverability, context);
+    }
+    /**
+     * Checks if the error should be retried based on retry information
+     */
+    shouldRetry() {
+        const { retry } = this.context;
+        if (!retry)
+            return false;
+        return (retry.currentRetry ?? 0) < (retry.maxRetries ?? 0);
+    }
+    /**
+     * Returns a user-friendly message that is safe to display to end users
+     */
+    getUserMessage() {
+        return this.context.userMessage || 'An unexpected error occurred.';
+    }
+}
+/**
+ * Error class for validation errors
+ */
+export class ValidationError extends PlatformError {
+    /**
+     * Creates a new validation error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.LOW, ErrorCategory.VALIDATION, ErrorRecoverability.NON_RECOVERABLE, context);
+    }
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ValidationError's constructor signature
+     */
+    createWithContext(context) {
+        return new this.constructor(this.message, this.code, context);
+    }
+}
+/**
+ * Error class for configuration errors
+ */
+export class ConfigurationError extends PlatformError {
+    /**
+     * Creates a new configuration error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.MEDIUM, ErrorCategory.CONFIGURATION, ErrorRecoverability.NON_RECOVERABLE, context);
+    }
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ConfigurationError's constructor signature
+     */
+    createWithContext(context) {
+        return new this.constructor(this.message, this.code, context);
+    }
+}
+/**
+ * Error class for network-related errors
+ */
+export class NetworkError extends PlatformError {
+    /**
+     * Creates a new network error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.MEDIUM, ErrorCategory.CONNECTIVITY, ErrorRecoverability.MAYBE_RECOVERABLE, context);
+    }
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle NetworkError's constructor signature
+     */
+    createWithContext(context) {
+        return new this.constructor(this.message, this.code, context);
+    }
+}
+/**
+ * Error class for resource availability errors (rate limits, quotas)
+ */
+export class ResourceError extends PlatformError {
+    /**
+     * Creates a new resource error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.MEDIUM, ErrorCategory.RESOURCE, ErrorRecoverability.MAYBE_RECOVERABLE, context);
+    }
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ResourceError's constructor signature
+     */
+    createWithContext(context) {
+        return new this.constructor(this.message, this.code, context);
+    }
+}
+/**
+ * Error class for authentication/authorization errors
+ */
+export class AuthenticationError extends PlatformError {
+    /**
+     * Creates a new authentication error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.HIGH, ErrorCategory.AUTHENTICATION, ErrorRecoverability.NON_RECOVERABLE, context);
+    }
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle AuthenticationError's constructor signature
+     */
+    createWithContext(context) {
+        return new this.constructor(this.message, this.code, context);
+    }
+}
+/**
+ * Error class for operation errors (API calls, processing)
+ */
+export class OperationError extends PlatformError {
+    /**
+     * Creates a new operation error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.MEDIUM, ErrorCategory.OPERATION, ErrorRecoverability.MAYBE_RECOVERABLE, context);
+    }
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle OperationError's constructor signature
+     */
+    createWithContext(context) {
+        return new this.constructor(this.message, this.code, context);
+    }
+}
+/**
+ * Error class for critical system errors
+ */
+export class SystemError extends PlatformError {
+    /**
+     * Creates a new system error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message, code, context = {}) {
+        super(message, code, ErrorSeverity.CRITICAL, ErrorCategory.OTHER, ErrorRecoverability.NON_RECOVERABLE, context);
+    }
+}
+/**
+ * Helper to get the appropriate error class based on error category
+ *
+ * @param category Error category
+ * @returns The appropriate error class
+ */
+export function getErrorClassForCategory(category) {
+    switch (category) {
+        case ErrorCategory.VALIDATION:
+            return ValidationError;
+        case ErrorCategory.CONFIGURATION:
+            return ConfigurationError;
+        case ErrorCategory.CONNECTIVITY:
+            return NetworkError;
+        case ErrorCategory.RESOURCE:
+            return ResourceError;
+        case ErrorCategory.AUTHENTICATION:
+            return AuthenticationError;
+        case ErrorCategory.OPERATION:
+            return OperationError;
+        default:
+            return PlatformError;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZS5lcnJvcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9lcnJvcnMvYmFzZS5lcnJvcnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGFBQWEsRUFBRSxhQUFhLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUNyRixPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sY0FBYyxDQUFDO0FBb0R0Qzs7O0dBR0c7QUFDSCxNQUFNLE9BQU8sYUFBYyxTQUFRLEtBQUs7SUFDdEMscURBQXFEO0lBQ3JDLElBQUksQ0FBUztJQUU3QiwyQkFBMkI7SUFDWCxRQUFRLENBQWdCO0lBRXhDLGlEQUFpRDtJQUNqQyxRQUFRLENBQWdCO0lBRXhDLDREQUE0RDtJQUM1QyxjQUFjLENBQXNCO0lBRXBELHFDQUFxQztJQUNyQixPQUFPLENBQWdCO0lBRXZDOzs7Ozs7Ozs7T0FTRztJQUNILFlBQ0UsT0FBZSxFQUNmLElBQVksRUFDWixXQUEwQixhQUFhLENBQUMsTUFBTSxFQUM5QyxXQUEwQixhQUFhLENBQUMsS0FBSyxFQUM3QyxpQkFBc0MsbUJBQW1CLENBQUMsZUFBZSxFQUN6RSxVQUF5QixFQUFFO1FBRTNCLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUVmLHFCQUFxQjtRQUNyQixJQUFJLENBQUMsSUFBSSxHQUFHLElBQUksQ0FBQyxXQUFXLENBQUMsSUFBSSxDQUFDO1FBQ2xDLElBQUksQ0FBQyxJQUFJLEdBQUcsSUFBSSxDQUFDO1FBQ2pCLElBQUksQ0FBQyxRQUFRLEdBQUcsUUFBUSxDQUFDO1FBQ3pCLElBQUksQ0FBQyxRQUFRLEdBQUcsUUFBUSxDQUFDO1FBQ3pCLElBQUksQ0FBQyxjQUFjLEdBQUcsY0FBYyxDQUFDO1FBRXJDLGdDQUFnQztRQUNoQyxJQUFJLENBQUMsT0FBTyxHQUFHO1lBQ2IsR0FBRyxPQUFPO1lBQ1YsU0FBUyxFQUFFLE9BQU8sQ0FBQyxTQUFTLElBQUksSUFB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

package/dist_ts/errors/error-handler.d.ts

@@ -0,0 +1,98 @@
+import { PlatformError } from './base.errors.js';
+import type { IErrorContext } from './base.errors.js';
+/**
+ * Error handler configuration
+ */
+export interface IErrorHandlerConfig {
+    /** Whether to log errors automatically */
+    logErrors: boolean;
+    /** Whether to include stack traces in prod environment */
+    includeStacksInProd: boolean;
+    /** Default retry options */
+    retry: {
+        /** Maximum retry attempts */
+        maxAttempts: number;
+        /** Base delay between retries in ms */
+        baseDelay: number;
+        /** Maximum delay between retries in ms */
+        maxDelay: number;
+        /** Backoff factor for exponential backoff */
+        backoffFactor: number;
+    };
+}
+/**
+ * Error handler utility
+ * Provides methods for consistent error handling across the platform
+ */
+export declare class ErrorHandler {
+    /**
+     * Current configuration
+     */
+    static config: IErrorHandlerConfig;
+    /**
+     * Update error handler configuration
+     *
+     * @param newConfig New configuration (partial)
+     */
+    static configure(newConfig: Partial<IErrorHandlerConfig>): void;
+    /**
+     * Convert any error to a PlatformError
+     *
+     * @param error Error to convert
+     * @param defaultCode Default error code if not a PlatformError
+     * @param context Additional context
+     * @returns PlatformError instance
+     */
+    static toPlatformError(error: any, defaultCode: string, context?: IErrorContext): PlatformError;
+    /**
+     * Format an error for API responses
+     * Sanitizes errors for safe external exposure
+     *
+     * @param error Error to format
+     * @param includeDetails Whether to include detailed information
+     * @returns Formatted error object
+     */
+    static formatErrorForResponse(error: any, includeDetails?: boolean): Record<string, any>;
+    /**
+     * Handle an error with consistent logging and formatting
+     *
+     * @param error Error to handle
+     * @param defaultCode Default error code if not a PlatformError
+     * @param context Additional context
+     * @returns Formatted error for response
+     */
+    static handleError(error: any, defaultCode: string, context?: IErrorContext): Record<string, any>;
+    /**
+     * Execute a function with error handling
+     *
+     * @param fn Function to execute
+     * @param defaultCode Default error code if the function throws
+     * @param context Additional context
+     * @returns Function result or error
+     */
+    static execute<T>(fn: () => Promise<T>, defaultCode: string, context?: IErrorContext): Promise<T>;
+    /**
+     * Execute a function with retries and exponential backoff
+     *
+     * @param fn Function to execute
+     * @param defaultCode Default error code if the function throws
+     * @param options Retry options
+     * @param context Additional context
+     * @returns Function result or error after max retries
+     */
+    static executeWithRetry<T>(fn: () => Promise<T>, defaultCode: string, options?: {
+        maxAttempts?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+        backoffFactor?: number;
+        retryableErrorCodes?: string[];
+        retryableErrorPatterns?: RegExp[];
+        onRetry?: (error: PlatformError, attempt: number, delay: number) => void;
+    }, context?: IErrorContext): Promise<T>;
+}
+/**
+ * Create a middleware for handling errors in HTTP requests
+ *
+ * @returns Middleware function
+ */
+export declare function createErrorHandlerMiddleware(): (error: any, req: any, res: any, next: any) => void;