@plyaz/types 1.13.2 → 1.13.4

package/dist/api/client/types.d.ts

@@ -9,7 +9,7 @@ import type { EndpointTypes } from '../endpoints';
 import type { UnknownRecord } from 'type-fest';
 import type { NETWORK_QUALITY, NetworkInfo } from '../network';
 import type { ConfigConflict, DebugInfo } from '../debugger';
-import type { ApiPackageErrorLike } from '../errors';
+import type { PackageErrorLike } from '../../errors';
 /**
  * Options for creating an API client
  * Endpoints are automatically included from src/api/endpoints
@@ -66,7 +66,7 @@ export interface EventManagerLike<TEventManager = unknown> {
         eventCountsByType: Record<string, number>;
     };
     getActiveScopes(): EventScopeWithTemporary[];
-    emitError(error: ApiPackageErrorLike): void;
+    emitError(error: PackageErrorLike): void;
     emitRequestStart(config: RequestConfig): void;
     emitResponseReceived<TData = unknown>(response: FetchResponse<TData>): void;
     emitRetryAttempt<TResponse = unknown>(error: ResponseError<TResponse>, attemptNumber: number, config?: RequestConfig): void;
@@ -239,7 +239,7 @@ export interface ClientEventManagerLike<TEventManager> {
         eventCountsByType: Record<string, number>;
     };
     getActiveScopes(): EventScopeWithTemporary[];
-    emitError(error: ApiPackageErrorLike): void;
+    emitError(error: PackageErrorLike): void;
     emitRequestStart(config: RequestConfig): void;
     emitResponseReceived<TData = unknown>(response: FetchResponse<TData>): void;
     emitRetryAttempt<TResponse = unknown>(error: ResponseError<TResponse>, attemptNumber: number, config?: RequestConfig): void;

package/dist/api/config/types.d.ts

@@ -10,13 +10,13 @@ import type { RetryConfig, RetryStrategyName } from '../retry';
 import type { PerformancePresetName } from '../performance';
 import type { RevalidationStrategyName } from '../revalidation';
 import type { ApiHeaders, EnrichedHeadersOptions, HeaderBuilderLike, HeaderPresetName } from '../headers';
-import type { ErrorEventHandlers } from '../errors';
 import type { ConfigUpdateStrategy, HandlerStrategy, EventScopeWithTemporary } from '../events';
 import type { NETWORK_QUALITY } from '../network';
 import type { HeaderEventHandlers, NetworkEventHandlers, ConfigEventHandlers, ClientEventHandlers, CacheEventHandlers, PerformanceEventHandlers } from '../events';
 import type { ApiClientOptions } from '../client';
 import type { DebugEventsConfig } from '../debugger';
 import type { EncryptionConfig } from '../encryption';
+import type { ErrorEventHandlers, ErrorDetailsList, MessageCatalog } from '../../errors';
 /**
  * HTTP Methods - extend from fetchff but uppercase
  */
@@ -640,6 +640,38 @@ export interface ApiConfig extends Partial<Omit<FetchffRequestConfig, 'retry' |
          */
         telemetry?: boolean;
     };
+    /**
+     * Error system configuration
+     * Controls error message localization and custom error catalogs
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   errors: {
+     *     locale: 'es',
+     *     additionalCatalogs: {
+     *       en: {
+     *         errors: {
+     *           custom_error: 'Custom error message'
+     *         }
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    errors?: {
+        /**
+         * Default locale for error messages
+         * @default 'en'
+         */
+        locale?: string;
+        /**
+         * Additional message catalogs for custom errors
+         * Merged with built-in error messages
+         */
+        additionalCatalogs?: Record<string, MessageCatalog>;
+    };
 }
 /**
  * Request-specific configuration
@@ -676,13 +708,38 @@ export interface EndpointConfig extends Omit<RequestConfig, 'params' | 'urlPathP
  * API Response wrapper
  * Extends fetchff's FetchResponse
  */
-export interface ApiResponse<TData = DefaultPayload, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> extends FetchResponse<TData, TBody, TParams, TPathParams> {
-}
+export type ApiResponse<TData = DefaultPayload, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> = FetchResponse<TData, TBody, TParams, TPathParams>;
 /**
  * API Error interface
- * Extends fetchff's ResponseError
+ * Extends fetchff's ResponseError with error response data typed as ErrorDetailsList
+ *
+ * The response data (accessible via response.data or response) contains
+ * the error details array from the API.
+ *
+ * @template TData - Type of response data, defaults to ErrorDetailsList (array of error details)
+ * @template TBody - Type of request body
+ * @template TParams - Type of query parameters
+ * @template TPathParams - Type of URL path parameters
+ *
+ * @example
+ * ```typescript
+ * // Default: response.data will be ErrorDetailsList
+ * const error: ApiError = {
+ *   message: 'Validation failed',
+ *   status: 400,
+ *   response: {
+ *     data: [
+ *       { field: 'email', message: 'Invalid email format', code: 'INVALID_EMAIL' }
+ *     ]
+ *   }
+ * };
+ *
+ * // Custom error response type
+ * interface CustomError { code: string; details: string }
+ * const error: ApiError<CustomError[]> = { ... };
+ * ```
  */
-export interface ApiError<TData = DefaultPayload, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> extends ResponseError<TData, TBody, TParams, TPathParams> {
+export interface ApiError<ValueGiven = string | number | boolean, AllowedValues = Record<string, string>, Constraints = Record<string, string>, TData = ErrorDetailsList<ValueGiven, AllowedValues, Constraints>, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> extends ResponseError<TData, TBody, TParams, TPathParams> {
 }
 /**
  * Configuration state that tracks base config and temporary overrides separately

package/dist/api/debugger/enums.d.ts

@@ -15,6 +15,12 @@ export declare const FACTORY_OPERATIONS: {
     readonly FACTORY_REGISTER: "factory_register";
     readonly HANDLER_REGISTERED: "handler_registered";
     readonly HANDLER_UNREGISTERED: "handler_unregistered";
+    /**
+     * Indicates that a specific handler instance has been removed from a factory or scope.
+     * Use this when removing a particular handler by reference or ID, as opposed to
+     * HANDLER_UNREGISTERED, which refers to unregistering a handler type or all handlers.
+     */
+    readonly SPECIFIC_HANDLER_REMOVED: "specific_handler_removed";
     readonly SCOPE_LISTENERS_CLEARED: "scope_listeners_cleared";
 };
 /**
@@ -200,6 +206,12 @@ export declare const UNIFIED_OPERATIONS: {
     readonly FACTORY_REGISTER: "factory_register";
     readonly HANDLER_REGISTERED: "handler_registered";
     readonly HANDLER_UNREGISTERED: "handler_unregistered";
+    /**
+     * Indicates that a specific handler instance has been removed from a factory or scope.
+     * Use this when removing a particular handler by reference or ID, as opposed to
+     * HANDLER_UNREGISTERED, which refers to unregistering a handler type or all handlers.
+     */
+    readonly SPECIFIC_HANDLER_REMOVED: "specific_handler_removed";
     readonly SCOPE_LISTENERS_CLEARED: "scope_listeners_cleared";
 };
 export type QueueOperationType = (typeof QUEUE_OPERATIONS)[keyof typeof QUEUE_OPERATIONS];

package/dist/api/debugger/types.d.ts

@@ -208,7 +208,7 @@ export interface MonitoringAlert {
 /**
  * Factory operation types for type safety
  */
-export type FactoryOperationType = 'factory_created' | 'factory_accessed' | 'factory_initialized' | 'factories_reset' | 'factory_register' | 'handler_registered' | 'handler_unregistered' | 'scope_listeners_cleared';
+export type FactoryOperationType = 'factory_created' | 'factory_accessed' | 'factory_initialized' | 'factories_reset' | 'factory_register' | 'handler_registered' | 'handler_unregistered' | 'specific_handler_removed' | 'scope_listeners_cleared';
 /**
  * Event operation types for pubsub and event system
  */

package/dist/api/errors/types.d.ts

@@ -6,54 +6,32 @@
  * Import and re-export ResponseError and RequestConfig types from fetchff
  * These are 3rd party types that @plyaz/api wraps
  */
-import type { ResponseError, RequestConfig } from 'fetchff';
-import type { ERROR_CATEGORY, ErrorDetail, ErrorResponse } from '../../errors';
-import type { API_ERROR_CODES, OPERATIONS, ERROR_FIELDS, STORAGE_TYPES, ApiClientInstance } from '..';
-import type { PACKAGE_STATUS_CODES } from './enum';
+import type { ResponseError } from 'fetchff';
+import type { ErrorDetail, BasePackageErrorOptions, INTERNAL_STATUS_CODES, PackageErrorLike } from '../../errors';
+import type { ApiClientInstance } from '..';
 import type { HTTP_STATUS } from '@plyaz/config';
 /**
- * Typed constants as types for convenience
+ * ===== Type Aliases =====
+ * Re-exported from centralized location for backwards compatibility
+ * NEW CODE should import from @plyaz/types/errors instead
  */
-export type ErrorOperation = (typeof OPERATIONS)[keyof typeof OPERATIONS];
-export type ErrorField = (typeof ERROR_FIELDS)[keyof typeof ERROR_FIELDS];
-export type StorageType = (typeof STORAGE_TYPES)[keyof typeof STORAGE_TYPES];
+export type { CommonOperation as ErrorOperation } from '../../errors';
+export type { CommonField as ErrorField } from '../../errors';
+export type { CommonStorageType as StorageType } from '../../errors';
 /**
- * Type for API error codes
+ * ===== Status Code Type Aliases =====
+ * API-specific status code types
  */
-export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
 /**
- * Type alias for error category values
- * Represents a single category value from ERROR_CATEGORY
+ * Type alias for internal package status codes (1xxx range)
+ * Custom internal status codes that don't map to HTTP status codes
  *
  * @example
  * ```typescript
- * const category: ErrorCategoryValue = ERROR_CATEGORY.Network; // 'network'
- * const isValid: ErrorCategoryValue = 'authentication'; // valid
+ * const statusCode: InternalStatusCodeValue = INTERNAL_STATUS_CODES.INVALID_CONFIGURATION; // 1001
  * ```
  */
-export type ErrorCategoryValue = (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
-/**
- * Type alias for API error code values
- * Use this instead of repeating the verbose (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES]
- * Also allows dynamic HTTP error codes in the form HTTP_${number}
- *
- * @example
- * ```typescript
- * const code: ApiErrorCodeValue = API_ERROR_CODES.NETWORK_ERROR;
- * const dynamicCode: ApiErrorCodeValue = `HTTP_${404}`; // Also valid
- * ```
- */
-export type ApiErrorCodeValue = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES] | `HTTP_${number}`;
-/**
- * Type alias for package-specific status code values
- * Custom status codes specific to @plyaz/api package (1xxx range)
- *
- * @example
- * ```typescript
- * const statusCode: PackageStatusCodeValue = PACKAGE_STATUS_CODES.CLIENT_CANCELLED; // 1001
- * ```
- */
-export type PackageStatusCodeValue = (typeof PACKAGE_STATUS_CODES)[keyof typeof PACKAGE_STATUS_CODES];
+export type InternalStatusCodeValue = (typeof INTERNAL_STATUS_CODES)[keyof typeof INTERNAL_STATUS_CODES];
 /**
  * Type alias for HTTP status code values
  * Standard HTTP status codes from @plyaz/config
@@ -65,233 +43,63 @@ export type PackageStatusCodeValue = (typeof PACKAGE_STATUS_CODES)[keyof typeof
  */
 export type HttpStatusCodeValue = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS];
 /**
- * Union type for all valid status codes
- * Combines both HTTP status codes and package-specific status codes
+ * Union type for all valid API status codes
+ * Combines both HTTP status codes and internal package status codes
  *
  * @example
  * ```typescript
- * const httpCode: StatusCodeValue = HTTP_STATUS.BAD_REQUEST; // 400
- * const customCode: StatusCodeValue = PACKAGE_STATUS_CODES.CLIENT_CANCELLED; // 1001
+ * const httpCode: ApiStatusCodeValue = HTTP_STATUS.BAD_REQUEST; // 400
+ * const internalCode: ApiStatusCodeValue = INTERNAL_STATUS_CODES.INVALID_CONFIGURATION; // 1001
  * ```
  */
-export type StatusCodeValue = PackageStatusCodeValue | HttpStatusCodeValue;
+export type ApiStatusCodeValue = InternalStatusCodeValue | HttpStatusCodeValue;
 /**
  * Translation interpolation variables
+ * Used for i18n error message interpolation
  */
 export interface I18nContext {
     [key: string]: string | number | boolean | null | undefined;
 }
-/**
- * Base error context with common fields
- */
-export interface BaseErrorContext {
-    operation?: ErrorOperation;
-    originalError?: string;
-    i18n?: I18nContext;
-    url?: string;
-    method?: string;
-    strategyName?: string;
-    fallback?: string;
-    eventType?: string;
-    reason?: string;
-    debuggerOperation?: string;
-    timeoutMs?: number;
-    timeout?: number;
-    elapsed?: number;
-    routerType?: string;
-    storageType?: string;
-    availableStrategies?: string;
-    requestedStrategy?: string;
-    fallbackUsed?: string;
-    requestedPreset?: string;
-    availablePresets?: string;
-    retryable?: boolean;
-    field?: string;
-    value?: unknown;
-    constraints?: Record<string, string>;
-    realm?: string;
-    scheme?: string;
-    limit?: number;
-    remaining?: number;
-    resetAt?: string;
-    retryAfter?: number;
-    serverMessage?: string;
-    traceId?: string;
-    input?: unknown;
-    errors?: Array<{
-        field: string;
-        message: string;
-        code?: string;
-    }>;
-    headers?: Record<string, string>;
-}
-/**
- * Cache error context
- */
-export interface CacheErrorContext extends BaseErrorContext {
-    operation: ErrorOperation;
-    cacheKey?: string;
-    keyPrefix?: string;
-    exactKey?: string;
-    storageType?: StorageType | string;
-    fallbackAvailable?: boolean;
-}
-/**
- * Headers error context
- */
-export interface HeadersErrorContext extends BaseErrorContext {
-    operation: ErrorOperation;
-    warningCount?: number;
-    warnings?: string;
-}
-/**
- * Regional error context
- */
-export interface RegionalErrorContext extends BaseErrorContext {
-    operation: ErrorOperation;
-    requestedPreset?: string;
-    availablePresets?: string;
-    fallbackUsed?: string;
-}
-/**
- * Network error context
- */
-export interface NetworkErrorContext extends BaseErrorContext {
-    operation: ErrorOperation;
-    requestedPreset?: string;
-    availablePresets?: string;
-}
-/**
- * Error definition structure
- */
-export interface ErrorDefinition {
-    code: string;
-    status: number;
-    category: (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
-    fieldsLeft?: string[];
-}
-/**
- * Map of error codes to their definitions
- */
-export type ErrorDefinitions = {
-    [key: string]: ErrorDefinition;
-};
-/**
- * Union type for all error contexts
- */
-export type ErrorContext = BaseErrorContext | CacheErrorContext | HeadersErrorContext | RegionalErrorContext | NetworkErrorContext;
 /**
  * Options for creating an ApiPackageError
- * Note: ApiPackageError class itself is not migrated as it contains implementation
+ * Extends BasePackageErrorOptions with API-specific properties
  */
-export interface ApiPackageErrorOptionsErrorDetail<ValueGiven, AllowedValues, Constraints> {
+export interface ApiPackageErrorOptionsErrorDetail<ValueGiven, AllowedValues, Constraints> extends BasePackageErrorOptions {
+    /** HTTP response error from fetchff */
     responseError?: unknown;
+    /** HTTP status code */
     statusCode?: number;
+    /** Validation error details */
     errors?: ErrorDetail<ValueGiven, AllowedValues, Constraints>[];
-    correlationId?: string;
-    cause?: Error;
-    context?: ErrorContext;
+    /** API client instance context (avoid circular dependency) */
     clientContext?: unknown;
 }
 /**
- * Interface representing the public API of ApiPackageError
- * Useful for type-checking without requiring the actual class instance
+ * ErrorEventHandlers and ErrorHandlerOptions moved to centralized location
+ * Import from: import { ErrorEventHandlers, ErrorHandlerOptions } from '@plyaz/types/errors';
  *
- * This interface allows for:
- * - Duck typing compatibility
- * - Easier mocking in tests
- * - Type-safe function parameters without importing the class
- * - Clearer documentation of the public API contract
- *
- * @example
- * ```typescript
- * function handleError(error: ApiPackageErrorLike): void {
- *   if (error.isRetryable()) {
- *     // Retry logic
- *   }
- *   console.error(error.getUserMessage());
- * }
- * ```
- */
-export interface ApiPackageErrorLike extends Error {
-    readonly statusCode: StatusCodeValue;
-    readonly errorCode: ApiErrorCodeValue;
-    readonly message: string;
-    readonly errors?: ErrorDetail<unknown, unknown, unknown>[];
-    readonly correlationId?: string;
-    readonly timestamp: string;
-    readonly responseError?: ResponseError;
-    readonly category: ErrorCategoryValue;
-    readonly cause?: Error;
-    readonly context?: ErrorContext;
-    readonly requestConfig?: RequestConfig;
-    readonly responseData?: ResponseError['response'];
-    readonly details?: ErrorDetail<unknown, unknown, unknown>[];
-    readonly originalError?: Error;
-    readonly metadata?: Record<string, string | number | boolean | null>;
-    readonly code: string;
-    isAuthError(): boolean;
-    isValidationError(): boolean;
-    isNetworkError(): boolean;
-    isServerError(): boolean;
-    isClientError(): boolean;
-    isRetryable(): boolean;
-    toJSON(): ErrorResponse;
-    toString(): string;
-    getUserMessage(): string;
-}
-/**
- * Event handler types for API package errors
- * Note: ApiPackageError is not imported here to avoid implementation dependencies
- */
-export interface ErrorEventHandlers {
-    onValidationError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onNetworkError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onAuthenticationError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onAuthorizationError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onRateLimitError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onTimeoutError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onConflictError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onNotFoundError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onServerError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onClientError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onExternalServiceError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onCacheError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onHeadersError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onRetryError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onStrategyError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onRegionalError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onUnknownError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-    onAnyError?: ((error: ApiPackageErrorLike) => void) | Array<(error: ApiPackageErrorLike) => void>;
-}
-/**
- * Options for error handler registration
+ * Re-exported here for backwards compatibility
  */
-export interface ErrorHandlerOptions {
-    /**
-     * The scope level for the handler
-     * @default 'GLOBAL'
-     */
-    scope?: 'GLOBAL' | 'CONFIG' | 'CLIENT' | 'REQUEST' | 'TEMPORARY';
-    /**
-     * 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?: 'merge' | 'replace' | 'prepend' | 'append';
-}
+export type { ErrorEventHandlers, ErrorHandlerOptions } from '../../errors';
 /**
- * Options for creating an ApiPackageError
+ * Options for creating an ApiPackageError with typed client instance
+ * Extends BasePackageErrorOptions with API-specific properties
  */
-export interface ApiPackageErrorOptions<EndpointsList> {
+export interface ApiPackageErrorOptions<EndpointsList> extends BasePackageErrorOptions {
+    /** HTTP response error from fetchff */
     responseError?: ResponseError;
+    /** HTTP status code */
     statusCode?: number;
+    /** Validation error details */
     errors?: ErrorDetail<unknown, unknown, unknown>[];
-    correlationId?: string;
-    cause?: Error;
-    context?: ErrorContext;
+    /** API client instance (typed with endpoints list) */
     clientContext?: ApiClientInstance<EndpointsList>;
 }
+/**
+ * Handler function type for category-based error event emission
+ * Used to map error categories to their corresponding event emission handlers
+ *
+ * @param error - The package error to emit
+ * @param context - Optional context from the error containing additional metadata
+ */
+export type CategoryErrorHandler = (error: PackageErrorLike, context: Record<string, unknown> | undefined) => void;