@plyaz/api 1.0.2 → 1.1.0

package/dist/api/errors/error-codes.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Domain-specific error codes for @plyaz/api package
+ * Following the error code pattern from Confluence architecture
+ */
+/**
+ * API Error Codes - domain-specific and grouped by category
+ */
+export declare const API_ERROR_CODES: {
+    readonly CLIENT_INITIALIZATION_FAILED: "CLIENT_INITIALIZATION_FAILED";
+    readonly CLIENT_INVALID_CONFIG: "CLIENT_INVALID_CONFIG";
+    readonly CLIENT_MISSING_BASE_URL: "CLIENT_MISSING_BASE_URL";
+    readonly CLIENT_CANCELLED: "CLIENT_CANCELLED";
+    readonly CONFIG_VALIDATION_FAILED: "CONFIG_VALIDATION_FAILED";
+    readonly HEADER_PROCESSING_FAILED: "HEADER_PROCESSING_FAILED";
+    readonly NETWORK_OVERRIDE_FAILED: "NETWORK_OVERRIDE_FAILED";
+    readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
+    readonly REQUEST_ABORTED: "REQUEST_ABORTED";
+    readonly REQUEST_INVALID_PARAMS: "REQUEST_INVALID_PARAMS";
+    readonly REQUEST_PREPARATION_FAILED: "REQUEST_PREPARATION_FAILED";
+    readonly RESPONSE_INVALID_FORMAT: "RESPONSE_INVALID_FORMAT";
+    readonly RESPONSE_PARSING_FAILED: "RESPONSE_PARSING_FAILED";
+    readonly NETWORK_CONNECTION_FAILED: "NETWORK_CONNECTION_FAILED";
+    readonly NETWORK_OFFLINE: "NETWORK_OFFLINE";
+    readonly NETWORK_DNS_FAILED: "NETWORK_DNS_FAILED";
+    readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly NETWORK_PRESET_NOT_FOUND: "NETWORK_PRESET_NOT_FOUND";
+    readonly NETWORK_CONFIGURATION_INVALID: "NETWORK_CONFIGURATION_INVALID";
+    readonly REGIONAL_PRESET_NOT_FOUND: "REGIONAL_PRESET_NOT_FOUND";
+    readonly REGION_DETECTION_FAILED: "REGION_DETECTION_FAILED";
+    readonly HEADERS_ENRICHMENT_FAILED: "HEADERS_ENRICHMENT_FAILED";
+    readonly HEADERS_VALIDATION_FAILED: "HEADERS_VALIDATION_FAILED";
+    readonly HEADERS_MERGE_CONFLICT: "HEADERS_MERGE_CONFLICT";
+    readonly CACHE_STORAGE_FAILED: "CACHE_STORAGE_FAILED";
+    readonly CACHE_RETRIEVAL_FAILED: "CACHE_RETRIEVAL_FAILED";
+    readonly CACHE_INVALIDATION_FAILED: "CACHE_INVALIDATION_FAILED";
+    readonly RETRY_EXHAUSTED: "RETRY_EXHAUSTED";
+    readonly RETRY_STRATEGY_INVALID: "RETRY_STRATEGY_INVALID";
+    readonly STRATEGY_INVALID: "STRATEGY_INVALID";
+    readonly STRATEGY_CONFLICT: "STRATEGY_CONFLICT";
+    readonly STRATEGY_EXECUTION_FAILED: "STRATEGY_EXECUTION_FAILED";
+    readonly POLLING_TIMEOUT: "POLLING_TIMEOUT";
+    readonly POLLING_CANCELLED: "POLLING_CANCELLED";
+    readonly POLLING_INVALID_CONFIG: "POLLING_INVALID_CONFIG";
+    readonly PUBSUB_SUBSCRIPTION_FAILED: "PUBSUB_SUBSCRIPTION_FAILED";
+    readonly PUBSUB_PUBLICATION_FAILED: "PUBSUB_PUBLICATION_FAILED";
+    readonly PUBSUB_INVALID_TOPIC: "PUBSUB_INVALID_TOPIC";
+    readonly PUBSUB_CHANNEL_ERROR: "PUBSUB_CHANNEL_ERROR";
+    readonly REVALIDATION_FAILED: "REVALIDATION_FAILED";
+    readonly REVALIDATION_IN_PROGRESS: "REVALIDATION_IN_PROGRESS";
+    readonly DEBUG_TRACKING_FAILED: "DEBUG_TRACKING_FAILED";
+    readonly DEBUG_OVERRIDE_FAILED: "DEBUG_OVERRIDE_FAILED";
+    readonly DEBUG_CONFLICT_DETECTED: "DEBUG_CONFLICT_DETECTED";
+    readonly ENDPOINT_BUILD_FAILED: "ENDPOINT_BUILD_FAILED";
+    readonly ENDPOINT_NOT_FOUND: "ENDPOINT_NOT_FOUND";
+    readonly ENDPOINT_INVALID_CONFIG: "ENDPOINT_INVALID_CONFIG";
+    readonly EVENT_HANDLER_FAILED: "EVENT_HANDLER_FAILED";
+    readonly EVENT_EMISSION_FAILED: "EVENT_EMISSION_FAILED";
+    readonly MONITORING_FAILED: "MONITORING_FAILED";
+    readonly CONTEXT_OPERATION_FAILED: "CONTEXT_OPERATION_FAILED";
+    readonly AUTH_TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED";
+    readonly AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED";
+    readonly AUTH_FORBIDDEN: "AUTH_FORBIDDEN";
+    readonly AUTH_INVALID_CREDENTIALS: "AUTH_INVALID_CREDENTIALS";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+    readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly REQUIRED_FIELD_MISSING: "REQUIRED_FIELD_MISSING";
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    readonly VALIDATION_INVALID_FORMAT: "INVALID_FORMAT";
+    readonly STRING_TOO_SHORT: "STRING_TOO_SHORT";
+    readonly STRING_TOO_LONG: "STRING_TOO_LONG";
+    readonly CLIENT_ERROR: "CLIENT_ERROR";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+};
+/**
+ * Type for API error codes
+ */
+export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+/**
+ * Internal package status codes (non-HTTP)
+ * Used for internal configuration and validation errors that aren't HTTP-related
+ */
+export declare const PACKAGE_STATUS_CODES: {
+    readonly INVALID_CONFIGURATION: 1001;
+    readonly MISSING_CONFIGURATION: 1002;
+    readonly CONFIGURATION_CONFLICT: 1003;
+    readonly CONFIGURATION_TRACKING_FAILED: 1004;
+    readonly DEBUG_TRACKING_FAILED: 1005;
+    readonly RESOURCE_NOT_FOUND: 1010;
+    readonly RESOURCE_ALREADY_EXISTS: 1011;
+    readonly RESOURCE_UNAVAILABLE: 1012;
+    readonly INVALID_PARAMETER: 1020;
+    readonly MISSING_PARAMETER: 1021;
+    readonly PARAMETER_OUT_OF_RANGE: 1022;
+    readonly STRATEGY_NOT_FOUND: 1030;
+    readonly PRESET_NOT_FOUND: 1031;
+    readonly INVALID_STRATEGY: 1032;
+    readonly REQUEST_FAILED: 1035;
+    readonly INITIALIZATION_FAILED: 1040;
+    readonly OPERATION_FAILED: 1041;
+    readonly STATE_CORRUPTION: 1042;
+    readonly SERIALIZATION_FAILED: 1043;
+    readonly DESERIALIZATION_FAILED: 1044;
+    readonly CONFIGURATION_INVALID: 1045;
+    readonly HEADER_PROCESSING_ERROR: 1046;
+    readonly REGION_DETECTION_ERROR: 1047;
+    readonly NETWORK_OVERRIDE_ERROR: 1048;
+};
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/api/errors/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../src/api/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoHlB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAElF;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;CAoCvB,CAAC"}

package/dist/api/errors/error-events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Error event management for @plyaz/api package
+ * Simplified to use shared event emitter and factories
+ */
+import type { ErrorEventHandlers, ErrorHandlerOptions, ERROR_EVENTS, ApiPackageErrorLike } from '@plyaz/types/api';
+import { HANDLER_SCOPES } from '@plyaz/types/api';
+/**
+ * Register an error handler for any scope
+ * @param eventType - The event type (e.g., ERROR_EVENTS.NETWORK_ERROR, 'network', '*')
+ * @param handler - The handler function
+ * @param options - Registration options (scope defaults to 'GLOBAL' - app-wide handlers that persist across all instances)
+ * @returns Cleanup function to unregister the handler
+ *
+ * @example
+ * // Register a global handler (default)
+ * registerErrorHandler(ERROR_EVENTS.NETWORK_ERROR, handleNetworkError);
+ *
+ * // Register a client-specific handler
+ * registerErrorHandler(ERROR_EVENTS.NETWORK_ERROR, handleNetworkError, { scope: 'CLIENT' });
+ */
+export declare function registerErrorHandler(eventType: string | (typeof ERROR_EVENTS)[keyof typeof ERROR_EVENTS], handler: (error: ApiPackageErrorLike) => void, options?: ErrorHandlerOptions): () => void;
+/**
+ * Set error handlers for a specific scope
+ * @param handlers - The error handlers to register
+ * @param scope - The scope to register handlers at (defaults to GLOBAL - lowest priority, persists across all instances)
+ */
+export declare function setErrorHandlers(handlers: ErrorEventHandlers, scope?: keyof typeof HANDLER_SCOPES): void;
+/**
+ * Get error handlers for a specific scope
+ * @param scope - The scope to retrieve handlers from (defaults to GLOBAL)
+ * @returns The registered error handlers for the specified scope
+ */
+export declare function getErrorHandlers(scope?: keyof typeof HANDLER_SCOPES): ErrorEventHandlers;
+/**
+ * Register multiple error handlers at once
+ * @param handlers - The error handlers to register
+ * @param options - Registration options (scope defaults to 'GLOBAL' - app-wide handlers)
+ */
+export declare function registerErrorHandlers(handlers: ErrorEventHandlers, options?: ErrorHandlerOptions): void;
+/**
+ * Unregister error handlers
+ * @param eventTypes - Optional array of event types to remove (can use ERROR_EVENTS values or plain types)
+ *                     If not provided, all handlers for the scope are removed.
+ * @param options - Options including scope (defaults to 'GLOBAL')
+ */
+export declare function unregisterErrorHandlers(eventTypes?: Array<string | (typeof ERROR_EVENTS)[keyof typeof ERROR_EVENTS]>, options?: Pick<ErrorHandlerOptions, 'scope'>): void;
+/**
+ * Clear error handlers
+ * @param options - Options including scope(s) to clear (defaults to ['GLOBAL'])
+ */
+export declare function clearErrorHandlers(options?: {
+    scopes?: Array<keyof typeof HANDLER_SCOPES>;
+}): void;
+/**
+ * Register a one-time error handler
+ * Handler will be automatically removed after first execution
+ * @param eventType - The event type (e.g., ERROR_EVENTS.NETWORK_ERROR, 'network', '*')
+ * @param handler - The handler function
+ * @param options - Registration options (scope defaults to 'GLOBAL')
+ */
+export declare function onceErrorHandler(eventType: string | (typeof ERROR_EVENTS)[keyof typeof ERROR_EVENTS], handler: (error: ApiPackageErrorLike) => void, options?: Pick<ErrorHandlerOptions, 'scope'>): void;
+export declare function emitErrorEvent(error: ApiPackageErrorLike): Promise<void>;
+//# sourceMappingURL=error-events.d.ts.map

package/dist/api/errors/error-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-events.d.ts","sourceRoot":"","sources":["../../../src/api/errors/error-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EACV,kBAAkB,EAElB,mBAAmB,EAGnB,YAAY,EACZ,mBAAmB,EAEpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAiC,MAAM,kBAAkB,CAAC;AAsGjF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,EACpE,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,EAC7C,OAAO,GAAE,mBAAwB,GAChC,MAAM,IAAI,CA0BZ;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,GAAE,MAAM,OAAO,cAAyB,GAC5C,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAAM,OAAO,cAAyB,GAC5C,kBAAkB,CAEpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC,EAC7E,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAM,GAC/C,IAAI,CAmBN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,OAAO,cAAc,CAAC,CAAA;CAAO,GAC5D,IAAI,CAQN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,EACpE,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,EAC7C,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAM,GAC/C,IAAI,CAaN;AAuID,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ9E"}

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

@@ -0,0 +1,18 @@
+/**
+ * Error handling module for @plyaz/api package
+ *
+ * This module provides a comprehensive error handling system that:
+ * - Enhances fetchff's ResponseError without replacing it
+ * - Provides typed error categories and codes
+ * - Supports global and instance-level error handlers
+ * - Integrates with existing event systems
+ *
+ * @module errors
+ */
+export { ApiPackageError } from './ApiPackageError';
+export { ERROR_CATEGORY } from '@plyaz/types';
+export { ERROR_CATEGORY as ErrorCategory } from '@plyaz/types';
+export { API_ERROR_CODES, PACKAGE_STATUS_CODES, ERROR_DEFINITIONS, OPERATIONS, ERROR_FIELDS, STORAGE_TYPES, } from '@plyaz/types/api';
+export { getErrorDefinition, getErrorCodeByStatus, getErrorCategory } from './definitions';
+export { registerErrorHandler, registerErrorHandlers, unregisterErrorHandlers, clearErrorHandlers, onceErrorHandler, setErrorHandlers, getErrorHandlers, emitErrorEvent, } from './error-events';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,cAAc,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EAEL,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAGhB,cAAc,GACf,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,64 @@
+/**
+ * Typed constants for error handling
+ */
+export declare const OPERATIONS: {
+    readonly STORAGE: "storage";
+    readonly RETRIEVAL: "retrieval";
+    readonly INVALIDATION: "invalidation";
+    readonly ENRICHMENT: "enrichment";
+    readonly VALIDATION: "validation";
+    readonly PRESET_LOOKUP: "preset-lookup";
+    readonly INITIALIZATION: "initialization";
+    readonly CONFIGURATION: "configuration";
+    readonly REQUEST: "request";
+    readonly RESPONSE: "response";
+    readonly RETRY: "retry";
+    readonly REVALIDATION: "revalidation";
+    readonly STRATEGY_EXECUTION: "strategy-execution";
+    readonly POLLING: "polling";
+    readonly SUBSCRIPTION: "subscription";
+    readonly PUBLICATION: "publication";
+    readonly DEBUG: "debug";
+    readonly DEBUG_TRACKING: "debug-tracking";
+    readonly ENDPOINT_BUILD: "endpoint-build";
+    readonly TRACKING: "tracking";
+    readonly NETWORK_CHECK: "network-check";
+    readonly EVENT_HANDLING: "event-handling";
+    readonly SERIALIZATION: "serialization";
+    readonly DESERIALIZATION: "deserialization";
+    readonly REGIONAL_DETECTION: "regional-detection";
+    readonly MONITORING: "monitoring";
+    readonly CONTEXT_SETUP: "context-setup";
+    readonly FALLBACK: "fallback";
+};
+export type Operation = (typeof OPERATIONS)[keyof typeof OPERATIONS];
+export declare const ERROR_FIELDS: {
+    readonly STORAGE: "storage";
+    readonly CACHE: "cache";
+    readonly HEADERS: "headers";
+    readonly PRESET_NAME: "presetName";
+    readonly PRESET_ID: "presetId";
+    readonly CONFIG: "config";
+    readonly URL: "url";
+    readonly METHOD: "method";
+    readonly STRATEGY: "strategy";
+    readonly RETRY_COUNT: "retryCount";
+    readonly MAX_RETRIES: "maxRetries";
+    readonly POLLING_INTERVAL: "pollingInterval";
+    readonly TOPIC: "topic";
+    readonly CHANNEL: "channel";
+    readonly ENDPOINT: "endpoint";
+    readonly CLIENT: "client";
+    readonly NETWORK_TYPE: "networkType";
+    readonly TIME_INTERVAL: "timeInterval";
+};
+export type ErrorField = (typeof ERROR_FIELDS)[keyof typeof ERROR_FIELDS];
+export declare const STORAGE_TYPES: {
+    readonly PRIMARY: "primary";
+    readonly FALLBACK: "fallback";
+    readonly MEMORY: "memory";
+    readonly SESSION: "session";
+    readonly LOCAL: "local";
+};
+export type StorageType = (typeof STORAGE_TYPES)[keyof typeof STORAGE_TYPES];
+//# sourceMappingURL=types-constants.d.ts.map

package/dist/api/errors/types-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-constants.d.ts","sourceRoot":"","sources":["../../../src/api/errors/types-constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6Bb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAGrE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;CAmBf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAG1E,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC"}

package/dist/api/events/EventManager.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Event Manager
+ * Centralized manager for all event factories and event coordination
+ */
+import { BaseEventFactory } from './factories';
+import type { ConfigEventFactory, PerformanceEventFactory, NetworkEventFactory, HeaderEventFactory, ErrorEventFactory, DebugEventFactory, ClientEventFactory, CacheEventFactory } from './factories';
+import { type EventScopeWithTemporary } from '@plyaz/types/api';
+import type { EventEmitter } from '../pubsub';
+/**
+ * Centralized Event Manager
+ * Provides unified access to all event factories and the shared emitter
+ *
+ * ## Event Scope System
+ *
+ * Events are emitted with scope awareness to control which handlers receive them:
+ *
+ * ### Default Behavior
+ * - **ALL scopes are active by default**: ['global', 'config', 'client', 'request']
+ * - Events are emitted to handlers at ALL scope levels unless restricted
+ * - Factories emit events without scope awareness; EventManager adds scopes based on context
+ *
+ * ### Scope Contexts
+ * 1. **Global Config**: `setGlobalConfig()` sets scopes to ['global', 'config']
+ * 2. **Client Instance**: Creates with ALL scopes by default (merged behavior)
+ * 3. **Temporary Override**: Sets scopes to ['request'] only (isolated)
+ * 4. **Custom**: Can explicitly set any combination of scopes
+ *
+ * ### How It Works
+ * ```typescript
+ * // Factory emits simple event (no scope):
+ * headerFactory.emit({ type: 'headers:changed', data: {...} })
+ *
+ * // EventManager adds scopes based on current context:
+ * // If scopes = ['global', 'client'], emits to:
+ * // - 'global:headers:changed'
+ * // - 'global:headers:*'
+ * // - 'client:headers:changed'
+ * // - 'client:headers:*'
+ * // - 'headers:changed' (backwards compat)
+ * // - 'headers:*' (backwards compat)
+ * ```
+ *
+ * ### Priority Order (lowest to highest)
+ * 1. GLOBAL - App-wide handlers
+ * 2. CONFIG - Configuration-level handlers
+ * 3. CLIENT - Instance-specific handlers
+ * 4. REQUEST/TEMPORARY - Request-level handlers
+ */
+export declare class EventManager extends BaseEventFactory<'eventManager'> {
+    private static instance;
+    private readonly headerFactory;
+    private readonly networkFactory;
+    private readonly errorFactory;
+    private readonly debugFactory;
+    private readonly configFactory;
+    private readonly performanceFactory;
+    private readonly cacheFactory;
+    private readonly clientFactory;
+    private eventScopes;
+    private currentEventScopes;
+    private constructor();
+    /**
+     * Track EventManager operations for debugging and analysis
+     * Uses the operation queue to avoid circular dependency with UnifiedDebugger
+     */
+    private trackEventManagerOperation;
+    /**
+     * Wrap a factory to make it use EventManager's scope configuration
+     * This ensures that when factories emit events through EventManager,
+     * they respect the configured scopes (e.g., excluding global when needed)
+     */
+    private createScopeAwareFactory;
+    /**
+     * Set up internal event handlers for cross-cutting concerns
+     */
+    private setupInternalHandlers;
+    /**
+     * Set up header event handlers
+     */
+    private setupHeaderHandlers;
+    /**
+     * Set up network event handlers
+     */
+    private setupNetworkHandlers;
+    /**
+     * Set up error event handlers
+     */
+    private setupErrorHandlers;
+    /**
+     * Set up debug event handlers
+     */
+    private setupDebugHandlers;
+    /**
+     * Set up performance event handlers
+     */
+    private setupPerformanceHandlers;
+    /**
+     * Set up config event handlers
+     */
+    private setupConfigHandlers;
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): EventManager;
+    /**
+     * Set event scopes for this manager instance
+     * Used by clients to configure which scopes receive events
+     */
+    setEventScopes(scopes: EventScopeWithTemporary[]): void;
+    /**
+     * Get current event scopes
+     */
+    getEventScopes(): EventScopeWithTemporary[];
+    /**
+     * Override emitAcrossScopes to use EventManager's configured scopes
+     * This allows EventManager to control which scopes are active
+     *
+     * @param eventType - The type of event (e.g., 'error', 'debug', 'headers', 'network')
+     * @param eventName - The specific event name (e.g., 'onNetworkError', 'conflict', 'changed')
+     * @param data - The event data
+     * @param scopes - Optional scopes to emit to (defaults to configured scopes)
+     */
+    emitAcrossScopes(eventType: string, eventName: string, data: unknown, scopes?: EventScopeWithTemporary[]): void;
+    /**
+     * Determine priority based on event type and name
+     */
+    private determinePriority;
+    /**
+     * Get the shared event emitter
+     */
+    getEmitter(): EventEmitter;
+    /**
+     * Get header event factory
+     */
+    get headers(): HeaderEventFactory;
+    /**
+     * Get network event factory
+     */
+    get network(): NetworkEventFactory;
+    /**
+     * Get error event factory
+     */
+    get errors(): ErrorEventFactory;
+    /**
+     * Get debug event factory
+     */
+    get debug(): DebugEventFactory;
+    /**
+     * Get config event factory
+     */
+    get config(): ConfigEventFactory;
+    /**
+     * Get performance event factory
+     */
+    get performance(): PerformanceEventFactory;
+    /**
+     * Get cache event factory
+     */
+    get cache(): CacheEventFactory;
+    /**
+     * Get client event factory
+     */
+    get client(): ClientEventFactory;
+    /**
+     * Override on to support any event string (not just namespace-prefixed)
+     * @param event - Any event string
+     * @param handler - Event handler
+     */
+    on<T = unknown>(event: string, handler: (data: T) => void): () => void;
+    /**
+     * Override once to support any event string (not just namespace-prefixed)
+     * @param event - Any event string
+     * @param handler - Event handler
+     */
+    once<T = unknown>(event: string, handler: (data: T) => void): () => void;
+    /**
+     * Get the shared event emitter instance
+     * @returns The underlying EventEmitter
+     */
+    getSharedEmitter(): EventEmitter;
+    /**
+     * Get event statistics
+     * @returns Object with totalEvents and totalListeners
+     */
+    getEventStats(): {
+        totalEvents: number;
+        totalListeners: number;
+    };
+    /**
+     * Get active scopes
+     * @returns Array of active event scopes
+     */
+    getActiveScopes(): EventScopeWithTemporary[];
+    /**
+     * Reset the event manager (mainly for testing)
+     */
+    static reset(): void;
+}
+/**
+ * Export singleton getter
+ */
+export declare function getEventManager(): EventManager;
+/**
+ * Convenience exports for direct factory access
+ */
+export declare const eventManager: {
+    readonly headers: HeaderEventFactory;
+    readonly network: NetworkEventFactory;
+    readonly errors: ErrorEventFactory;
+    readonly debug: DebugEventFactory;
+    readonly config: ConfigEventFactory;
+    readonly performance: PerformanceEventFactory;
+    readonly cache: CacheEventFactory;
+    readonly client: ClientEventFactory;
+    readonly emitter: ReturnType<EventManager["getEmitter"]>;
+    on: <T = unknown>(event: string, handler: (data: T) => void) => (() => void);
+    once: <T = unknown>(event: string, handler: (data: T) => void) => (() => void);
+    emit: <T = unknown>(event: string, data?: T) => void;
+    off: (event: string, handler?: Function) => void;
+    removeAllListeners: (event?: string) => void;
+    listeners: (event: string) => Function[];
+    listenerCount: (event: string) => number;
+    emitAcrossScopes: (eventType: string, eventName: string, data: unknown, scopes?: EventScopeWithTemporary[]) => void;
+    setEventScopes: (scopes: EventScopeWithTemporary[]) => void;
+    getEventScopes: () => EventScopeWithTemporary[];
+    getSharedEmitter: () => ReturnType<EventManager["getSharedEmitter"]>;
+    getEventStats: () => ReturnType<EventManager["getEventStats"]>;
+    getActiveScopes: () => EventScopeWithTemporary[];
+};
+//# sourceMappingURL=EventManager.d.ts.map

package/dist/api/events/EventManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventManager.d.ts","sourceRoot":"","sources":["../../../src/api/events/EventManager.ts"],"names":[],"mappings":"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"}