@plyaz/types 1.13.3 → 1.13.4

package/dist/errors/types.d.ts

@@ -1,18 +1,10 @@
 import type { ReactNode } from 'react';
-import type { WithStatusCode, WithErrorCode, WithMessage, WithCorrelationId, WithTimestamp, WithValidationError } from '../common/types';
+import type { WithValidationError } from '../common/types';
 import type { ERRORS_CODES } from '@plyaz/config';
-import type { ERROR_CATEGORY } from './enums';
+import type { ERROR_CATEGORY, ERROR_SEVERITY, COMMON_OPERATIONS, COMMON_FIELDS, COMMON_STORAGE_TYPES, INTERNAL_STATUS_CODES } from './enums';
 import type { NextFunction } from 'express';
-/**
- * Represents the structure of an error response returned by the application.
- * @template ErrorDetails - The type of the `errors` array, defaults to `ErrorDetailsList`.
- */
-export interface ErrorResponse<ErrorDetails = ErrorDetailsList> extends WithStatusCode, WithErrorCode, WithMessage, Partial<WithCorrelationId>, WithTimestamp {
-    /**
-     * Array of detailed errors, typically used for validation failures.
-     */
-    readonly errors: ErrorDetails;
-}
+import type { ERROR_CODES } from './codes';
+import type { ApiClientInstance } from '../api';
 /**
  * Additional context information about a validation error.
  * @template ValueGiven - Type of the value that caused the error.
@@ -50,9 +42,12 @@ export type ErrorDetail<ValueGiven, AllowedValues, Constraints> = WithValidation
  * Error Details Array.
  * @description A flexible list of error details that can contain string, number, or boolean values along with structured allowed values and constraints.
  */
-export type ErrorDetailsList = readonly ErrorDetail<string | number | boolean, Record<string, string>, Record<string, string>>[];
+export type ErrorDetailsList<ValueGiven = string | number | boolean, AllowedValues = Record<string, string>, Constraints = Record<string, string>> = readonly ErrorDetail<ValueGiven, AllowedValues, Constraints>[];
+/**
+ * Alias for error response structure, which serves for API responses.
+ */
+export type ErrorResponse = ErrorDetailsList;
 export type ErrorCodeKey = keyof typeof ERRORS_CODES;
-export type ErrorCodeValue = (typeof ERRORS_CODES)[ErrorCodeKey];
 export type ErrorCodeMsg = (typeof ERRORS_CODES)[ErrorCodeKey];
 export interface ReturnResponseType<T = unknown> {
     codeStatus: number;
@@ -77,5 +72,626 @@ export interface BaseErrorResponse {
     /** ISO timestamp when the error occurred. */
     timestamp: string;
 }
+/**
+ * Error definition structure
+ * Single source of truth for all error definitions across @plyaz packages
+ * Combines properties from API, notifications, and future packages
+ */
+export interface ErrorDefinition {
+    /** Error code (unique identifier) */
+    code: string;
+    /** HTTP or package-specific status code */
+    status: number;
+    /** Error category (from ERROR_CATEGORY) */
+    category: (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
+    /** Error severity level (from ERROR_SEVERITY) - optional for backwards compat */
+    severity?: (typeof ERROR_SEVERITY)[keyof typeof ERROR_SEVERITY];
+    /** Whether this error is retryable - optional for backwards compat */
+    retryable?: boolean;
+    /** User-friendly error message - optional for backwards compat */
+    userMessage?: string;
+    /** Optional: Fields involved in the error (for validation errors) */
+    fieldsLeft?: string[];
+}
+/**
+ * Map of error codes to their definitions
+ * Indexed by error code values (e.g., 'CLIENT_INITIALIZATION_FAILED')
+ */
+export type ErrorDefinitions = {
+    readonly [K in (typeof ERROR_CODES)[keyof typeof ERROR_CODES]]: ErrorDefinition;
+};
+/**
+ * Base error context
+ * Common fields used across all error contexts in @plyaz packages
+ * Combines context properties from API, notifications, and other packages
+ *
+ * Note: All string fields are freeform - you don't need to use specific const objects.
+ * For example, `operation` can be any string like 'storage', 'retrieval', 'validation', etc.
+ *
+ * Note: For validation errors with field-specific details, use the `errors` array with ErrorDetail objects.
+ */
+export interface BaseErrorContext {
+    operation?: string;
+    originalError?: string;
+    url?: string;
+    method?: string;
+    timeoutMs?: number;
+    timeout?: number;
+    elapsed?: number;
+    channel?: string;
+    provider?: string;
+    recipientId?: string;
+    templateId?: string;
+    strategyName?: string;
+    fallback?: string;
+    eventType?: string;
+    reason?: string;
+    debuggerOperation?: string;
+    routerType?: string;
+    storageType?: string;
+    availableStrategies?: string;
+    requestedStrategy?: string;
+    fallbackUsed?: string;
+    requestedPreset?: string;
+    availablePresets?: string;
+    cacheKey?: string;
+    keyPrefix?: string;
+    exactKey?: string;
+    fallbackAvailable?: boolean;
+    warningCount?: number;
+    warnings?: string;
+    retryable?: boolean;
+    realm?: string;
+    scheme?: string;
+    limit?: number;
+    remaining?: number;
+    resetAt?: string;
+    retryAfter?: number;
+    serverMessage?: string;
+    traceId?: string;
+    correlationId?: string;
+    input?: unknown;
+    /**
+     * Validation error details
+     * Use ErrorDetail objects for field-specific validation errors
+     * Each ErrorDetail contains: field, message, code, and ErrorDetailContext (valueGiven, allowedValues, constraints)
+     */
+    errors?: ErrorDetail<unknown, unknown, unknown>[];
+    headers?: Record<string, string>;
+    i18n?: I18nContext;
+    [key: string]: unknown;
+}
+/**
+ * Cache-specific error context
+ * Extends BaseErrorContext with cache-related properties
+ */
+export type CacheErrorContext = BaseErrorContext;
+/**
+ * Headers-specific error context
+ * Extends BaseErrorContext with headers-related properties
+ */
+export type HeadersErrorContext = BaseErrorContext;
+/**
+ * Network-specific error context
+ * Extends BaseErrorContext with network-related properties
+ */
+export type NetworkErrorContext = BaseErrorContext;
+/**
+ * Regional-specific error context
+ * Extends BaseErrorContext with regional-related properties
+ */
+export type RegionalErrorContext = BaseErrorContext;
+/**
+ * Base options for creating package errors
+ * Common options across all @plyaz package errors
+ */
+export interface BasePackageErrorOptions {
+    cause?: Error;
+    context?: BaseErrorContext;
+    metadata?: Record<string, string | number | boolean | null>;
+    correlationId?: string;
+}
+/**
+ * Extended package error options with additional properties
+ * Generic interface that works for API, notifications, and other packages
+ *
+ * @template TClientContext - Type of client context (e.g., ApiClientInstance<EndpointsList>)
+ * @template TResponseError - Type of response error (e.g., ResponseError from fetchff)
+ * @template TValueGiven - Type of validation error value
+ * @template TAllowedValues - Type of validation allowed values
+ * @template TConstraints - Type of validation constraints
+ *
+ * @example
+ * ```typescript
+ * // For API package:
+ * type ApiErrorOptions = PackageErrorOptions<
+ *   ApiClientInstance<MyEndpoints>,
+ *   ResponseError
+ * >;
+ *
+ * // For notifications package:
+ * type NotificationErrorOptions = PackageErrorOptions<never, never>;
+ * ```
+ */
+export interface PackageErrorOptions<TClientContext = unknown, TResponseError = unknown, TValueGiven = unknown, TAllowedValues = unknown, TConstraints = unknown> extends BasePackageErrorOptions {
+    /** HTTP or package response error */
+    responseError?: TResponseError;
+    /** HTTP or package status code */
+    statusCode?: number;
+    /** Validation error details */
+    errors?: ErrorDetail<TValueGiven, TAllowedValues, TConstraints>[];
+    /** Client or service instance context */
+    clientContext?: TClientContext;
+}
+/**
+ * Unified interface for all @plyaz package errors
+ * THE single source of truth for error interfaces across all packages
+ *
+ * This interface should be implemented by:
+ * - BaseError in @plyaz/errors
+ * - ApiPackageError in @plyaz/api (extends BaseError)
+ * - NotificationPackageError in @plyaz/notifications (extends BaseError)
+ *
+ * Combines properties and methods from all error implementations
+ */
+export interface PackageErrorLike extends Error {
+    /** Error code (unique identifier from ERROR_CODES) */
+    readonly errorCode: string;
+    /** Human-readable error message (for developers) */
+    readonly message: string;
+    /** ISO timestamp when error was created */
+    readonly timestamp: string;
+    /** Error category (from ERROR_CATEGORY) */
+    readonly category: (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
+    /** Error severity level (from ERROR_SEVERITY) */
+    readonly severity?: (typeof ERROR_SEVERITY)[keyof typeof ERROR_SEVERITY];
+    /** Whether this error is retryable */
+    readonly retryable?: boolean;
+    /** Original error that caused this error */
+    readonly cause?: Error;
+    /** Alias for cause (for compatibility) */
+    readonly originalError?: Error;
+    /** Contextual information about the error */
+    readonly context?: BaseErrorContext;
+    /** Additional metadata (JSON-serializable) */
+    readonly metadata?: Record<string, string | number | boolean | null>;
+    /** Correlation ID for request tracking */
+    readonly correlationId?: string;
+    /** Trace ID for distributed tracing */
+    readonly traceId?: string;
+    /** HTTP status code (used by API and base errors) */
+    readonly statusCode?: number;
+    /** Validation error details (used by API errors) */
+    readonly errors?: ErrorDetail<unknown, unknown, unknown>[];
+    /** Alias for errors (for compatibility) */
+    readonly details?: ErrorDetail<unknown, unknown, unknown>[];
+    /** Error type (alternative name for errorCode in BaseError) */
+    readonly type?: string;
+    /** Getter for code property (alias for errorCode) */
+    readonly code: string;
+    /** Check if this is a validation error */
+    isValidationError(): boolean;
+    /** Check if this is a network error */
+    isNetworkError(): boolean;
+    /** Check if this error is retryable */
+    isRetryable(): boolean;
+    /** Check if this is an authentication error */
+    isAuthError?(): boolean;
+    /** Check if this is a server error */
+    isServerError?(): boolean;
+    /** Check if this is a client error */
+    isClientError?(): boolean;
+    /** Check if this is a provider error (notifications) */
+    isProviderError?(): boolean;
+    /** Check if this is a template error (notifications) */
+    isTemplateError?(): boolean;
+    /** Check if this is a rate limit error */
+    isRateLimitError?(): boolean;
+    /** Check if this is a queue error (notifications) */
+    isQueueError?(): boolean;
+    /** Check if this is a webhook error (notifications) */
+    isWebhookError?(): boolean;
+    /** Check if this is a configuration error */
+    isConfigurationError?(): boolean;
+    /** Check if this is a timeout error */
+    isTimeoutError?(): boolean;
+    /** Check if this is a not found error */
+    isNotFoundError?(): boolean;
+    /** Check if this is a conflict error */
+    isConflictError?(): boolean;
+    /** Convert error to ErrorResponse or JSON object for logging/API responses */
+    toJSON(): ErrorDetailsList | Record<string, unknown>;
+    /** Convert error to string representation */
+    toString(): string;
+    /** Get user-friendly message for display to end users */
+    getUserMessage(): string;
+}
 export type AsyncMiddleware<TReturn = void> = (req: Request, res: Response, next: NextFunction) => Promise<TReturn>;
 export type MiddlewareWrapper = <TReturn>(fn: AsyncMiddleware<TReturn>) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * ===== Error Event Handling =====
+ * Unified event handlers for all error categories across all packages
+ */
+/**
+ * Event scope levels (uppercase format for @plyaz/errors)
+ * Each scope has different priority and lifecycle
+ *
+ * Scopes (in priority order):
+ * - GLOBAL: Application-wide handlers, persist across all requests
+ * - CONFIG: Configuration-level handlers, scoped to configuration instances
+ * - CLIENT: Client instance handlers, scoped to client lifecycle
+ * - REQUEST: Request-specific handlers, scoped to individual requests (highest priority)
+ * - TEMPORARY: Alias for REQUEST scope, automatically mapped to REQUEST for emission
+ *
+ * Note: TEMPORARY and REQUEST are functionally equivalent.
+ * TEMPORARY exists for semantic clarity when registering one-time handlers.
+ * When emitting events, TEMPORARY scope is automatically treated as REQUEST scope.
+ */
+export type EventScope = 'GLOBAL' | 'CONFIG' | 'CLIENT' | 'REQUEST' | 'TEMPORARY';
+/**
+ * Handler strategy for managing multiple handlers
+ * - merge: Add to existing handlers without duplicates (default)
+ * - replace: Replace all existing handlers with new ones
+ * - prepend: Add new handlers before existing ones
+ * - append: Add new handlers after existing ones
+ */
+export type HandlerStrategy = 'merge' | 'replace' | 'prepend' | 'append';
+/**
+ * Generic error event handler function
+ * Supports both synchronous and asynchronous handlers
+ * Can be a single function or an array of functions
+ */
+export type ErrorEventHandler<TError = PackageErrorLike> = ((error: TError) => void | Promise<void>) | Array<(error: TError) => void | Promise<void>>;
+/**
+ * Error event handlers interface
+ * Maps error categories to their handler functions (single or arrays)
+ * Used by event emitters in all @plyaz packages (api, notifications, errors, etc.)
+ *
+ * @template TError - The error type (defaults to PackageErrorLike)
+ *
+ * @example
+ * ```typescript
+ * const handlers: ErrorEventHandlers = {
+ *   onValidationError: (error) => console.error('Validation failed:', error),
+ *   onProviderError: [(error) => logger.error('Provider error:', error), (error) => metrics.track(error)],
+ *   onAnyError: (error) => metrics.track('error', error)
+ * };
+ * ```
+ */
+export interface ErrorEventHandlers<TError = PackageErrorLike> {
+    onError?: ErrorEventHandler<TError>;
+    onValidationError?: ErrorEventHandler<TError>;
+    onNetworkError?: ErrorEventHandler<TError>;
+    onAuthenticationError?: ErrorEventHandler<TError>;
+    onAuthorizationError?: ErrorEventHandler<TError>;
+    onRateLimitError?: ErrorEventHandler<TError>;
+    onTimeoutError?: ErrorEventHandler<TError>;
+    onNotFoundError?: ErrorEventHandler<TError>;
+    onConflictError?: ErrorEventHandler<TError>;
+    onServerError?: ErrorEventHandler<TError>;
+    onClientError?: ErrorEventHandler<TError>;
+    onExternalServiceError?: ErrorEventHandler<TError>;
+    onCacheError?: ErrorEventHandler<TError>;
+    onHeadersError?: ErrorEventHandler<TError>;
+    onRetryError?: ErrorEventHandler<TError>;
+    onStrategyError?: ErrorEventHandler<TError>;
+    onRegionalError?: ErrorEventHandler<TError>;
+    onProviderError?: ErrorEventHandler<TError>;
+    onQueueError?: ErrorEventHandler<TError>;
+    onWebhookError?: ErrorEventHandler<TError>;
+    onTemplateError?: ErrorEventHandler<TError>;
+    onConfigurationError?: ErrorEventHandler<TError>;
+    onBlockchainError?: ErrorEventHandler<TError>;
+    onUnknownError?: ErrorEventHandler<TError>;
+    onAnyError?: ErrorEventHandler<TError>;
+}
+/**
+ * Options for error handler registration
+ * Used when registering error handlers with different scopes and strategies
+ *
+ * @template TError - The error type (defaults to PackageErrorLike)
+ *
+ * @example
+ * ```typescript
+ * errorEmitter.on({
+ *   onValidationError: handleValidation,
+ * }, {
+ *   scope: 'REQUEST',
+ *   strategy: 'prepend'
+ * });
+ * ```
+ */
+export interface ErrorHandlerOptions<TError = PackageErrorLike> {
+    /**
+     * The scope level for the handler
+     * - GLOBAL: Applies to all errors across the application
+     * - CONFIG: Applies to errors in a specific configuration
+     * - CLIENT: Applies to errors in a specific client instance
+     * - REQUEST: Applies only to a specific request
+     * - TEMPORARY: Temporary handler that can be removed
+     *
+     * @default 'GLOBAL'
+     */
+    scope?: EventScope;
+    /**
+     * Strategy for handling multiple handlers
+     * - merge: Add to existing handlers (default)
+     * - replace: Replace existing handlers for this event type
+     * - prepend: Add new handlers before existing ones
+     * - append: Add new handlers after existing ones
+     *
+     * @default 'merge'
+     */
+    strategy?: HandlerStrategy;
+    /**
+     * Original unwrapped handler (before any transformations)
+     * Used internally to track the original handler for removal
+     */
+    originalHandler?: (data: TError) => void | Promise<void>;
+}
+/**
+ * Generic event factory interface
+ * Packages must provide an implementation that follows this interface
+ * Used by @plyaz/errors to abstract event handling across different packages
+ */
+export interface ErrorEventFactory {
+    /**
+     * Add a scoped handler for an event
+     * @param scope - Event scope (GLOBAL, CONFIG, CLIENT, REQUEST, TEMPORARY)
+     * @param eventName - Event name (e.g., 'validation', 'network', '*')
+     * @param handler - Event handler function
+     * @param options - Handler options (strategy, originalHandler)
+     */
+    addScopedHandler<T = PackageErrorLike>(scope: EventScope, eventName: string, handler: (data: T) => void, options?: ErrorHandlerOptions<T>): void;
+    /**
+     * Remove a scoped handler
+     * @param scope - Event scope
+     * @param eventName - Event name
+     * @param handler - Optional specific handler to remove (if not provided, removes all handlers)
+     */
+    removeScopedHandler<T = PackageErrorLike>(scope: EventScope, eventName: string, handler?: (data: T) => void): void;
+    /**
+     * Get original handlers for a scope (before wrapping)
+     * @param scope - Event scope
+     * @returns Map of event names to handler arrays
+     */
+    getOriginalScopedHandlers<T = PackageErrorLike>(scope: EventScope): Map<string, Array<(data: T) => void>>;
+    /**
+     * Emit an error event with scoping
+     * @param eventName - Event name
+     * @param data - Event data
+     * @param options - Emission options (scopes to emit to)
+     */
+    emit<T = PackageErrorLike>(eventName: string, data: T, options?: {
+        scopes?: EventScope[];
+    }): void;
+}
+/**
+ * Scoped error emitter options
+ * Extends ErrorHandlerOptions with event factory override
+ */
+export interface ScopedErrorEmitterOptions extends ErrorHandlerOptions {
+    /**
+     * Custom event factory to use
+     * If not provided, will use the global/default factory
+     */
+    eventFactory?: ErrorEventFactory;
+}
+/**
+ * Type for error event emitter function
+ * Packages can implement this to emit events when errors are created
+ */
+export type ErrorEventEmitter = (error: PackageErrorLike) => void | Promise<void>;
+/**
+ * ===== API Package Error Types =====
+ */
+/**
+ * Generic API error detail
+ * Extends base ErrorDetail with required errorCode
+ * @template ValueGiven - Type of the value that caused the error
+ * @template AllowedValues - Type of acceptable values for the field
+ * @template Constraints - Type of validation constraints
+ * @template Context - Type of additional error context (key-value pairs)
+ */
+export interface ApiErrorDetail<ValueGiven = unknown, AllowedValues = unknown, Constraints = unknown, Context extends Record<string, unknown> = Record<string, unknown>> {
+    /** Application-specific error code */
+    errorCode: string;
+    /** Human-readable error message */
+    message: string;
+    /** The field that caused the error (optional) */
+    field?: string;
+    /** The value that was provided (optional) */
+    value?: ValueGiven;
+    /** Allowed values for the field (optional) */
+    allowedValues?: AllowedValues;
+    /** Validation constraints (optional) */
+    constraints?: Constraints;
+    /** Additional error context (optional) */
+    context?: Context;
+}
+/**
+ * Generic API package error options
+ */
+export interface ApiPackageErrorOptions<TEndpoints = unknown, TClient = ApiClientInstance<TEndpoints>> {
+    /** Error details (validation errors, etc.) */
+    errors?: ApiErrorDetail[];
+    /** Correlation ID for tracking */
+    correlationId?: string;
+    /** Original HTTP response error (from fetchff or similar) */
+    responseError?: unknown;
+    /** Cause error */
+    cause?: Error;
+    /** Error context */
+    context?: BaseErrorContext;
+    /** Client context (generic) */
+    clientContext?: TClient;
+    /** Additional metadata */
+    metadata?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Configuration for ApiPackageError class
+ */
+export interface ApiPackageErrorConfig {
+    /** Package namespace for event emission */
+    namespace?: string;
+    /** Event factory for scoped events */
+    eventFactory?: ErrorEventFactory;
+    /** Correlation ID generator */
+    correlationIdGenerator?: () => string;
+}
+/**
+ * ===== Error System Configuration =====
+ */
+/**
+ * Translation message catalog
+ * Nested structure for i18n messages
+ */
+export interface MessageCatalog {
+    [key: string]: string | MessageCatalog;
+}
+/**
+ * Message translator configuration
+ */
+export interface TranslatorConfig {
+    /** Default locale to use */
+    defaultLocale: string;
+    /** Fallback locale if key not found */
+    fallbackLocale?: string;
+    /** Message catalogs by locale */
+    catalogs: Record<string, MessageCatalog>;
+}
+/**
+ * Error system initialization options
+ */
+export interface ErrorSystemConfig {
+    /**
+     * Default locale to use for error messages
+     * @default 'en'
+     */
+    defaultLocale?: string;
+    /**
+     * Fallback locale if translation not found
+     * @default 'en'
+     */
+    fallbackLocale?: string;
+    /**
+     * Additional message catalogs to merge with built-in messages
+     * Useful for adding package-specific or custom error messages
+     */
+    additionalCatalogs?: Record<string, MessageCatalog>;
+    /**
+     * Replace built-in catalogs entirely (use with caution)
+     * If true, only additionalCatalogs will be used
+     * @default false
+     */
+    replaceBuiltIn?: boolean;
+}
+/**
+ * ===== Centralized Type Aliases =====
+ * Single source of truth for commonly used type aliases across all @plyaz packages
+ */
+/**
+ * Type alias for error category values
+ * Represents a single category value from ERROR_CATEGORY
+ *
+ * @example
+ * ```typescript
+ * const category: ErrorCategoryValue = ERROR_CATEGORY.Network; // 'network'
+ * const isValid: ErrorCategoryValue = 'authentication'; // valid
+ * ```
+ */
+export type ErrorCategoryValue = (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
+/**
+ * Type alias for error severity values
+ * Represents a single severity value from ERROR_SEVERITY
+ *
+ * @example
+ * ```typescript
+ * const severity: ErrorSeverityValue = ERROR_SEVERITY.High; // 'high'
+ * ```
+ */
+export type ErrorSeverityValue = (typeof ERROR_SEVERITY)[keyof typeof ERROR_SEVERITY];
+/**
+ * Type alias for common operation values
+ * Can be any string, but COMMON_OPERATIONS provides suggested values
+ *
+ * @example
+ * ```typescript
+ * import { COMMON_OPERATIONS } from '@plyaz/types';
+ *
+ * const op1: CommonOperation = COMMON_OPERATIONS.STORAGE;
+ * const op2: CommonOperation = 'custom-operation'; // Also valid
+ * ```
+ */
+export type CommonOperation = (typeof COMMON_OPERATIONS)[keyof typeof COMMON_OPERATIONS] | string;
+/**
+ * Type alias for common field values
+ * Can be any string, but COMMON_FIELDS provides suggested values
+ *
+ * @example
+ * ```typescript
+ * import { COMMON_FIELDS } from '@plyaz/types';
+ *
+ * const field1: CommonField = COMMON_FIELDS.EMAIL;
+ * const field2: CommonField = 'customField'; // Also valid
+ * ```
+ */
+export type CommonField = (typeof COMMON_FIELDS)[keyof typeof COMMON_FIELDS] | string;
+/**
+ * Type alias for common storage type values
+ * Can be any string, but COMMON_STORAGE_TYPES provides suggested values
+ *
+ * @example
+ * ```typescript
+ * import { COMMON_STORAGE_TYPES } from '@plyaz/types';
+ *
+ * const storage1: CommonStorageType = COMMON_STORAGE_TYPES.REDIS;
+ * const storage2: CommonStorageType = 'custom-storage'; // Also valid
+ * ```
+ */
+export type CommonStorageType = (typeof COMMON_STORAGE_TYPES)[keyof typeof COMMON_STORAGE_TYPES] | string;
+/**
+ * ===== Status Code Type Aliases =====
+ */
+/**
+ * Type alias for internal package status codes (1xxx range)
+ * Custom internal status codes that don't map to HTTP status codes
+ *
+ * @example
+ * ```typescript
+ * import { INTERNAL_STATUS_CODES } from '@plyaz/types/errors';
+ *
+ * const statusCode: InternalStatusCodeValue = INTERNAL_STATUS_CODES.INVALID_CONFIGURATION; // 1001
+ * ```
+ */
+export type InternalStatusCodeValue = (typeof INTERNAL_STATUS_CODES)[keyof typeof INTERNAL_STATUS_CODES];
+/**
+ * Type alias for all status codes (HTTP + internal)
+ * Combines HTTP status codes (200-599) and internal package status codes (1xxx)
+ *
+ * @example
+ * ```typescript
+ * const httpStatus: StatusCodeValue = 404;
+ * const internalStatus: StatusCodeValue = 1001;
+ * ```
+ */
+export type StatusCodeValue = number | InternalStatusCodeValue;
+/**
+ * ===== I18n Support =====
+ */
+/**
+ * Translation interpolation variables
+ * Used for i18n error message interpolation
+ *
+ * @example
+ * ```typescript
+ * const i18n: I18nContext = {
+ *   count: 5,
+ *   max: 10,
+ *   fieldName: 'email'
+ * };
+ * ```
+ */
+export interface I18nContext {
+    [key: string]: string | number | boolean | null | undefined;
+}