@plyaz/api 1.0.2 → 1.1.1

package/dist/api/events/factories/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Event Factory Exports
+ * Centralized export of all event factories (implementations only)
+ *
+ * NOTE: All types are available from @plyaz/types/api, not re-exported here
+ * Import types like: import type { HeaderEvent, NetworkEvent, etc. } from '@plyaz/types/api';
+ */
+export { BaseEventFactory } from './base';
+export { HeaderEventFactory } from './headers';
+export { NetworkEventFactory } from './network';
+export { ErrorEventFactory } from './errors';
+export { DebugEventFactory } from './debug';
+export { ConfigEventFactory, getConfigEventFactory } from './config';
+export { PerformanceEventFactory, getPerformanceEventFactory } from './performance';
+export { CacheEventFactory, getCacheEventFactory } from './cache';
+export { ClientEventFactory, getClientEventFactory } from './client';
+import { HeaderEventFactory } from './headers';
+import { NetworkEventFactory } from './network';
+import { ErrorEventFactory } from './errors';
+import { DebugEventFactory } from './debug';
+import type { EventEmitter } from '../../pubsub';
+/**
+ * Get singleton header event factory
+ * @param emitter - The event emitter to use (optional, defaults to shared emitter)
+ */
+export declare function getHeaderEventFactory(emitter?: EventEmitter): HeaderEventFactory;
+/**
+ * Get singleton network event factory
+ * @param emitter - The event emitter to use (optional, defaults to shared emitter)
+ */
+export declare function getNetworkEventFactory(emitter?: EventEmitter): NetworkEventFactory;
+/**
+ * Get singleton error event factory
+ * @param emitter - The event emitter to use (optional, defaults to shared emitter)
+ */
+export declare function getErrorEventFactory(emitter?: EventEmitter): ErrorEventFactory;
+/**
+ * Get singleton debug event factory
+ * @param emitter - The event emitter to use (optional, defaults to shared emitter)
+ */
+export declare function getDebugEventFactory(emitter?: EventEmitter): DebugEventFactory;
+/**
+ * Reset all factory instances (mainly for testing)
+ */
+export declare function resetFactories(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/events/factories/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/events/factories/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AASjD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,kBAAkB,CAIhF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,mBAAmB,CAIlF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAI9E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAI9E;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAKrC"}

package/dist/api/events/factories/network.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Network Event Factory
+ * Creates and emits network-related events with type safety
+ */
+import type { NetworkQualityEvent, NetworkInfoEvent, NetworkConfigOverrideEvent, NetworkPresetEvent, NetworkClientHintsEvent, NetworkAutoDetectionEvent, NetworkManualUpdateEvent, EmitConfigOverrideOptions, EmitPresetAppliedOptions, EmitQualityChangeOptions, EmitAutoDetectionOptions, EmitConfigRestoredOptions, EventOptions, NetworkInfo, EmitPresetChangedOptions, NetworkClientHints as NetworkHints } from '@plyaz/types/api';
+import { BaseEventFactory } from './base';
+import type { EventEmitter } from '../../pubsub';
+/**
+ * Factory for creating network events
+ */
+export declare class NetworkEventFactory extends BaseEventFactory<'network'> {
+    constructor(emitter: EventEmitter);
+    /**
+     * Create and emit a network quality change event
+     */
+    emitQualityChange(options: EmitQualityChangeOptions): NetworkQualityEvent;
+    /**
+     * Create and emit a network info update event
+     */
+    emitInfoUpdate(current: NetworkInfo, previous?: NetworkInfo, options?: EventOptions): NetworkInfoEvent;
+    /**
+     * Create and emit a network config override event
+     */
+    emitConfigOverride(options: EmitConfigOverrideOptions): NetworkConfigOverrideEvent;
+    /**
+     * Create and emit a network config restored event
+     */
+    emitConfigRestored(options: EmitConfigRestoredOptions): NetworkConfigOverrideEvent;
+    /**
+     * Create and emit a network preset applied event
+     */
+    emitPresetApplied(options: EmitPresetAppliedOptions): NetworkPresetEvent;
+    /**
+     * Create and emit a network preset changed event
+     */
+    emitPresetChanged(options: EmitPresetChangedOptions): NetworkPresetEvent;
+    /**
+     * Create and emit a network client hints updated event
+     */
+    emitHintsUpdated(current: NetworkHints, source: 'auto' | 'headers' | 'manual', previous?: NetworkHints, options?: EventOptions): NetworkClientHintsEvent;
+    /**
+     * Create and emit a network auto detection event
+     */
+    emitAutoDetection(options: EmitAutoDetectionOptions): NetworkAutoDetectionEvent;
+    /**
+     * Create and emit a network manual update event
+     */
+    emitManualUpdate(updates: Partial<NetworkInfo>, source: 'user' | 'api' | 'config', reason?: string, options?: EventOptions): NetworkManualUpdateEvent;
+    /**
+     * Detect changes between network info objects
+     */
+    private detectInfoChanges;
+}
+//# sourceMappingURL=network.d.ts.map

package/dist/api/events/factories/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/api/events/factories/network.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,YAAY,EACZ,WAAW,EACX,wBAAwB,EACxB,kBAAkB,IAAI,YAAY,EACnC,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB,CAAC,SAAS,CAAC;gBACtD,OAAO,EAAE,YAAY;IAIjC;;OAEG;IACI,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,mBAAmB;IAyBhF;;OAEG;IACI,cAAc,CACnB,OAAO,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,WAAW,EACtB,OAAO,GAAE,YAAiB,GACzB,gBAAgB;IAgBnB;;OAEG;IACI,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,0BAA0B;IA4BzF;;OAEG;IACI,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,0BAA0B;IAkBzF;;OAEG;IACI,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,kBAAkB;IAiB/E;;OAEG;IACI,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,kBAAkB;IAiB/E;;OAEG;IACI,gBAAgB,CACrB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,EACrC,QAAQ,CAAC,EAAE,YAAY,EACvB,OAAO,GAAE,YAAiB,GACzB,uBAAuB;IAc1B;;OAEG;IACI,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,yBAAyB;IAgBtF;;OAEG;IACI,gBAAgB,CACrB,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,EAC7B,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,EACjC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,wBAAwB;IAc3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}

package/dist/api/events/factories/performance.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Performance Event Factory
+ * Creates and emits performance-related events with type safety
+ */
+import type { PerformanceRequestStartEvent, PerformanceRequestCompleteEvent, PerformanceRetryEvent, PerformanceThresholdExceededEvent, PerformanceOptimizationAppliedEvent, PerformanceMetricRecordedEvent, EventOptions, EmitThresholdExceededOptions, EmitOptimizationAppliedOptions, EmitMetricRecordedOptions, EmitRetryOptions, EmitRequestCompleteOptions } from '@plyaz/types/api';
+import { BaseEventFactory } from './base';
+import type { EventEmitter } from '../../pubsub';
+/**
+ * Performance Event Factory
+ */
+export declare class PerformanceEventFactory extends BaseEventFactory<'performance'> {
+    constructor(emitter: EventEmitter);
+    /**
+     * Emit request start event
+     */
+    emitRequestStart(requestId: string, url: string, method: string, options?: EventOptions): PerformanceRequestStartEvent;
+    /**
+     * Emit request complete event
+     */
+    emitRequestComplete(options: EmitRequestCompleteOptions): PerformanceRequestCompleteEvent;
+    /**
+     * Emit retry event
+     */
+    emitRetry(options: EmitRetryOptions): PerformanceRetryEvent;
+    /**
+     * Emit threshold exceeded event
+     */
+    emitThresholdExceeded(options: EmitThresholdExceededOptions): PerformanceThresholdExceededEvent;
+    /**
+     * Emit optimization applied event
+     */
+    emitOptimizationApplied(options: EmitOptimizationAppliedOptions): PerformanceOptimizationAppliedEvent;
+    /**
+     * Emit metric recorded event
+     */
+    emitMetricRecorded(options: EmitMetricRecordedOptions): PerformanceMetricRecordedEvent;
+}
+/**
+ * Get singleton performance event factory
+ * @param emitter - The event emitter to use (optional, defaults to shared emitter)
+ */
+export declare function getPerformanceEventFactory(emitter?: EventEmitter): PerformanceEventFactory;
+//# sourceMappingURL=performance.d.ts.map

package/dist/api/events/factories/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../../src/api/events/factories/performance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,4BAA4B,EAC5B,+BAA+B,EAC/B,qBAAqB,EACrB,iCAAiC,EACjC,mCAAmC,EACnC,8BAA8B,EAC9B,YAAY,EACZ,4BAA4B,EAC5B,8BAA8B,EAC9B,yBAAyB,EACzB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,gBAAgB,CAAC,aAAa,CAAC;gBAC9D,OAAO,EAAE,YAAY;IAIjC;;OAEG;IACI,gBAAgB,CACrB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,YAAiB,GACzB,4BAA4B;IAc/B;;OAEG;IACI,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,+BAA+B;IAkBhG;;OAEG;IACI,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,qBAAqB;IAiBlE;;OAEG;IACI,qBAAqB,CAC1B,OAAO,EAAE,4BAA4B,GACpC,iCAAiC;IAgBpC;;OAEG;IACI,uBAAuB,CAC5B,OAAO,EAAE,8BAA8B,GACtC,mCAAmC;IAgBtC;;OAEG;IACI,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,8BAA8B;CAe9F;AAID;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,uBAAuB,CAI1F"}

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

@@ -0,0 +1,34 @@
+/**
+ * Event System Barrel Exports
+ *
+ * Centralized exports for the unified event system.
+ * This provides a single entry point for all event-related functionality.
+ */
+export { getSharedEventEmitter, resetSharedEventEmitter } from './shared-emitter';
+export { EVENT_NAMESPACES, HEADER_EVENTS, NETWORK_EVENTS, ERROR_EVENTS, DEBUG_EVENTS, CONFIG_EVENTS, PERFORMANCE_EVENTS, CLIENT_EVENTS, CACHE_EVENTS, ALL_EVENTS, HANDLER_SCOPES, EVENT_SCOPES, EVENT_SCOPES_WITH_TEMPORARY, HANDLER_NAMESPACES, createEventKey, createHandlerNamespace, createErrorHandlerNamespace, createDebugHandlerNamespace, createRequestHandlerNamespace, createResponseHandlerNamespace, createRetryHandlerNamespace, createHeadersHandlerNamespace, createNetworkHandlerNamespace, createCacheHandlerNamespace, createConfigHandlerNamespace, createPerformanceHandlerNamespace, createClientHandlerNamespace, createPollingHandlerNamespace, createRevalidationHandlerNamespace, } from './namespaces';
+export { getHeaderEventFactory, getNetworkEventFactory, getErrorEventFactory, getDebugEventFactory, getConfigEventFactory, getPerformanceEventFactory, getCacheEventFactory, getClientEventFactory, } from './factories';
+export { EventManager, getEventManager, eventManager } from './EventManager';
+export { createEventEmitter } from '../pubsub';
+export declare const EventHelpers: {
+    /**
+     * Check if an event key matches a wildcard pattern
+     */
+    readonly matchesWildcard: (eventKey: string, pattern: string) => boolean;
+    /**
+     * Extract namespace from event key
+     */
+    readonly getNamespace: (eventKey: string) => string;
+    /**
+     * Extract event name from event key
+     */
+    readonly getEventName: (eventKey: string) => string;
+    /**
+     * Check if event key is a wildcard pattern
+     */
+    readonly isWildcard: (eventKey: string) => boolean;
+    /**
+     * Get all wildcard patterns that would match an event
+     */
+    readonly getMatchingWildcards: (eventKey: string) => string[];
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/events/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAGlF,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,2BAA2B,EAC3B,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EAEtB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,2BAA2B,EAC3B,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,iCAAiC,EACjC,4BAA4B,EAC5B,6BAA6B,EAC7B,kCAAkC,GACnC,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAM/C,eAAO,MAAM,YAAY;IACvB;;OAEG;yCACyB,MAAM,WAAW,MAAM,KAAG,OAAO;IAQ7D;;OAEG;sCACsB,MAAM,KAAG,MAAM;IAKxC;;OAEG;sCACsB,MAAM,KAAG,MAAM;IAKxC;;OAEG;oCACoB,MAAM,KAAG,OAAO;IAIvC;;OAEG;8CAC8B,MAAM,KAAG,MAAM,EAAE;CAI1C,CAAC"}

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

@@ -0,0 +1,464 @@
+/**
+ * Event Namespace Constants
+ * Centralized constants for all event namespaces
+ */
+/**
+ * Main event namespaces for the API package
+ */
+export declare const EVENT_NAMESPACES: {
+    readonly HEADERS: "headers";
+    readonly NETWORK: "network";
+    readonly ERRORS: "errors";
+    readonly DEBUG: "debug";
+    readonly CONFIG: "config";
+    readonly PERFORMANCE: "performance";
+    readonly CLIENT: "client";
+    readonly CACHE: "cache";
+    readonly POLLING: "polling";
+    readonly REQUEST: "request";
+    readonly REVALIDATION: "revalidation";
+    readonly EVENT_MANAGER: "eventManager";
+};
+/**
+ * Header-specific event keys
+ */
+export declare const HEADER_EVENTS: {
+    readonly CHANGED: "headers:changed";
+    readonly ENRICHED: "headers:enriched";
+    readonly CONFLICT: "headers:conflict";
+    readonly OVERRIDE: "headers:override";
+    readonly TRACKED: "headers:tracked";
+    readonly MERGED: "headers:merged";
+    readonly FILTERED: "headers:filtered";
+    readonly VALIDATED: "headers:validated";
+    readonly CACHED: "headers:cached";
+    readonly CACHE_HIT: "headers:cache:hit";
+    readonly CACHE_MISS: "headers:cache:miss";
+    readonly ANY: "headers:*";
+};
+/**
+ * Network-specific event keys
+ */
+export declare const NETWORK_EVENTS: {
+    readonly QUALITY_CHANGE: "network:quality:changed";
+    readonly INFO_UPDATE: "network:info-update";
+    readonly CONFIG_OVERRIDE: "network:config:override";
+    readonly CONFIG_RESTORED: "network:config:restored";
+    readonly OVERRIDE_CHANGE: "network:override-change";
+    readonly PRESET_APPLIED: "network:preset-applied";
+    readonly PRESET_CHANGED: "network:preset:changed";
+    readonly HINTS_UPDATED: "network:hints:updated";
+    readonly AUTO_DETECTION: "network:auto:detection";
+    readonly MANUAL_UPDATE: "network:manual:update";
+    readonly ANY: "network:*";
+};
+/**
+ * Error-specific event keys
+ */
+export declare const ERROR_EVENTS: {
+    readonly NETWORK_ERROR: "errors:network";
+    readonly VALIDATION_ERROR: "errors:validation";
+    readonly AUTHENTICATION_ERROR: "errors:authentication";
+    readonly AUTHORIZATION_ERROR: "errors:authorization";
+    readonly RATE_LIMIT_ERROR: "errors:rate-limit";
+    readonly SERVER_ERROR: "errors:server";
+    readonly CLIENT_ERROR: "errors:client";
+    readonly TIMEOUT_ERROR: "errors:timeout";
+    readonly CONFLICT_ERROR: "errors:conflict";
+    readonly CACHE_ERROR: "errors:cache";
+    readonly HEADERS_ERROR: "errors:headers";
+    readonly RETRY_ERROR: "errors:retry";
+    readonly STRATEGY_ERROR: "errors:strategy";
+    readonly REGIONAL_ERROR: "errors:regional";
+    readonly NOT_FOUND_ERROR: "errors:not-found";
+    readonly EXTERNAL_SERVICE_ERROR: "errors:external-service";
+    readonly UNKNOWN_ERROR: "errors:unknown";
+    readonly GENERIC_ERROR: "errors:generic";
+    readonly ANY: "errors:*";
+};
+/**
+ * Handler scopes for different levels of event handlers
+ * These prefixes are used for registering handlers at different priority levels
+ * Can be used for any type of handler (error, request, response, debug, etc.)
+ *
+ * Priority order (lowest to highest):
+ * 1. GLOBAL - Set via setGlobalErrorHandlers(), persists across all instances
+ * 2. CONFIG - Set via setGlobalConfig({ errorHandlers }), global configuration
+ * 3. CLIENT - Set via createApiClient({ errorHandlers }), instance-specific
+ * 4. REQUEST/TEMPORARY - Set per-request or via updateConfig(), highest priority
+ *
+ * Usage:
+ * - GLOBAL: For app-wide handlers that should always run (e.g., logging)
+ * - CONFIG: For environment-specific handlers (e.g., dev vs prod)
+ * - CLIENT: For instance-specific handlers (e.g., per-service client)
+ * - REQUEST/TEMPORARY: For request-specific or runtime updates
+ *
+ * Note: REQUEST and TEMPORARY are aliases - both use 'request' scope
+ *
+ * Examples of namespaced handlers:
+ * - Error handlers: 'global:error', 'config:error', 'client:error'
+ * - Debug handlers: 'global:debug', 'config:debug', 'client:debug'
+ * - Request handlers: 'global:request', 'config:request', 'client:request'
+ */
+export declare const HANDLER_SCOPES: {
+    readonly GLOBAL: "global";
+    readonly CONFIG: "config";
+    readonly CLIENT: "client";
+    readonly TEMPORARY: "request";
+    readonly REQUEST: "request";
+};
+/**
+ * Core event scopes (excluding aliases)
+ * These are the actual scope values used by the event system
+ */
+export declare const EVENT_SCOPES: readonly ["global", "config", "client", "request"];
+/**
+ * All event scopes including 'temporary' alias
+ * Used in APIs where 'temporary' provides semantic clarity
+ */
+export declare const EVENT_SCOPES_WITH_TEMPORARY: readonly ["global", "config", "client", "request", "temporary"];
+/**
+ * Type for core event scopes
+ */
+export type EventScope = (typeof EVENT_SCOPES)[number];
+/**
+ * Type for event scopes including 'temporary'
+ */
+export type EventScopeWithTemporary = (typeof EVENT_SCOPES)[number] | 'temporary';
+/**
+ * Create handler namespace for a specific event type and scope
+ * Example: createHandlerNamespace('error', 'GLOBAL') => 'global:error'
+ * Example: createHandlerNamespace('debug', 'CLIENT') => 'client:debug'
+ *
+ * @param eventType - The type of event (error, debug, request, response, etc.)
+ * @param scope - The scope level (GLOBAL, CONFIG, CLIENT, REQUEST, TEMPORARY)
+ * @returns The namespaced string for handler registration
+ */
+export declare function createHandlerNamespace(eventType: string, scope: keyof typeof HANDLER_SCOPES): string;
+/**
+ * Debug-specific event keys
+ */
+export declare const DEBUG_EVENTS: {
+    readonly CONFIG_CONFLICT: "debug:config-conflict";
+    readonly CONFIG_CHANGE: "debug:config-change";
+    readonly HEADERS_TRACKED: "debug:headers-tracked";
+    readonly NETWORK_OVERRIDE: "debug:network-override";
+    readonly NETWORK_STATE_CHANGED: "debug:network-state-changed";
+    readonly NETWORK_DATA_CLEARED: "debug:network-data-cleared";
+    readonly DEBUG_INFO: "debug:info";
+    readonly PERFORMANCE_IMPACT: "debug:performance-impact";
+    readonly MONITORING_ALERT: "debug:monitoring-alert";
+    readonly CONFIG_TRACKED: "debug:config-tracked";
+    readonly CONFLICTS_BATCH: "debug:conflicts-batch";
+    readonly EVENT_OPERATION: "debug:event-operation";
+    readonly ANY: "debug:*";
+};
+/**
+ * Configuration sources - where config updates originate from
+ */
+export declare const EVENTS_CONFIG_SOURCES: {
+    readonly GLOBAL: "global";
+    readonly CREATE_API_CLIENT: "createApiClient";
+    readonly UPDATE_CONFIG: "updateConfig";
+    readonly MANUAL: "manual";
+    readonly ENVIRONMENT: "environment";
+    readonly PRESET: "preset";
+    readonly NETWORK_AWARE: "networkAware";
+    readonly ADAPTIVE: "adaptive";
+};
+export type EventsConfigSource = (typeof EVENTS_CONFIG_SOURCES)[keyof typeof EVENTS_CONFIG_SOURCES];
+/**
+ * Configuration-specific event keys
+ */
+export declare const CONFIG_EVENTS: {
+    readonly GLOBAL_UPDATED: "config:global-updated";
+    readonly GLOBAL_RESET: "config:global-reset";
+    readonly ENVIRONMENT_CONFIGURED: "config:environment-configured";
+    readonly PRESET_APPLIED: "config:preset-applied";
+    readonly ANY: "config:*";
+};
+/**
+ * Performance-specific event keys
+ */
+export declare const PERFORMANCE_EVENTS: {
+    readonly REQUEST_START: "performance:request-start";
+    readonly REQUEST_COMPLETE: "performance:request-complete";
+    readonly RETRY: "performance:retry";
+    readonly THRESHOLD_EXCEEDED: "performance:threshold-exceeded";
+    readonly OPTIMIZATION_APPLIED: "performance:optimization-applied";
+    readonly METRIC_RECORDED: "performance:metric-recorded";
+    readonly ANY: "performance:*";
+};
+/**
+ * Client-specific event keys
+ */
+export declare const CLIENT_EVENTS: {
+    readonly CONFLICT: "client:conflict";
+    readonly DEBUG: "client:debug";
+    readonly CREATED: "client:created";
+    readonly ANY: "client:*";
+};
+/**
+ * Cache-specific event keys
+ */
+export declare const CACHE_EVENTS: {
+    readonly HIT: "cache:hit";
+    readonly MISS: "cache:miss";
+    readonly INVALIDATE: "cache:invalidate";
+    readonly ANY: "cache:*";
+};
+/**
+ * All event keys combined for easy access
+ */
+export declare const ALL_EVENTS: {
+    readonly HIT: "cache:hit";
+    readonly MISS: "cache:miss";
+    readonly INVALIDATE: "cache:invalidate";
+    readonly ANY: "cache:*";
+    readonly CONFLICT: "client:conflict";
+    readonly DEBUG: "client:debug";
+    readonly CREATED: "client:created";
+    readonly REQUEST_START: "performance:request-start";
+    readonly REQUEST_COMPLETE: "performance:request-complete";
+    readonly RETRY: "performance:retry";
+    readonly THRESHOLD_EXCEEDED: "performance:threshold-exceeded";
+    readonly OPTIMIZATION_APPLIED: "performance:optimization-applied";
+    readonly METRIC_RECORDED: "performance:metric-recorded";
+    readonly GLOBAL_UPDATED: "config:global-updated";
+    readonly GLOBAL_RESET: "config:global-reset";
+    readonly ENVIRONMENT_CONFIGURED: "config:environment-configured";
+    readonly PRESET_APPLIED: "config:preset-applied";
+    readonly CONFIG_CONFLICT: "debug:config-conflict";
+    readonly CONFIG_CHANGE: "debug:config-change";
+    readonly HEADERS_TRACKED: "debug:headers-tracked";
+    readonly NETWORK_OVERRIDE: "debug:network-override";
+    readonly NETWORK_STATE_CHANGED: "debug:network-state-changed";
+    readonly NETWORK_DATA_CLEARED: "debug:network-data-cleared";
+    readonly DEBUG_INFO: "debug:info";
+    readonly PERFORMANCE_IMPACT: "debug:performance-impact";
+    readonly MONITORING_ALERT: "debug:monitoring-alert";
+    readonly CONFIG_TRACKED: "debug:config-tracked";
+    readonly CONFLICTS_BATCH: "debug:conflicts-batch";
+    readonly EVENT_OPERATION: "debug:event-operation";
+    readonly NETWORK_ERROR: "errors:network";
+    readonly VALIDATION_ERROR: "errors:validation";
+    readonly AUTHENTICATION_ERROR: "errors:authentication";
+    readonly AUTHORIZATION_ERROR: "errors:authorization";
+    readonly RATE_LIMIT_ERROR: "errors:rate-limit";
+    readonly SERVER_ERROR: "errors:server";
+    readonly CLIENT_ERROR: "errors:client";
+    readonly TIMEOUT_ERROR: "errors:timeout";
+    readonly CONFLICT_ERROR: "errors:conflict";
+    readonly CACHE_ERROR: "errors:cache";
+    readonly HEADERS_ERROR: "errors:headers";
+    readonly RETRY_ERROR: "errors:retry";
+    readonly STRATEGY_ERROR: "errors:strategy";
+    readonly REGIONAL_ERROR: "errors:regional";
+    readonly NOT_FOUND_ERROR: "errors:not-found";
+    readonly EXTERNAL_SERVICE_ERROR: "errors:external-service";
+    readonly UNKNOWN_ERROR: "errors:unknown";
+    readonly GENERIC_ERROR: "errors:generic";
+    readonly QUALITY_CHANGE: "network:quality:changed";
+    readonly INFO_UPDATE: "network:info-update";
+    readonly CONFIG_OVERRIDE: "network:config:override";
+    readonly CONFIG_RESTORED: "network:config:restored";
+    readonly OVERRIDE_CHANGE: "network:override-change";
+    readonly PRESET_CHANGED: "network:preset:changed";
+    readonly HINTS_UPDATED: "network:hints:updated";
+    readonly AUTO_DETECTION: "network:auto:detection";
+    readonly MANUAL_UPDATE: "network:manual:update";
+    readonly CHANGED: "headers:changed";
+    readonly ENRICHED: "headers:enriched";
+    readonly OVERRIDE: "headers:override";
+    readonly TRACKED: "headers:tracked";
+    readonly MERGED: "headers:merged";
+    readonly FILTERED: "headers:filtered";
+    readonly VALIDATED: "headers:validated";
+    readonly CACHED: "headers:cached";
+    readonly CACHE_HIT: "headers:cache:hit";
+    readonly CACHE_MISS: "headers:cache:miss";
+};
+/**
+ * Helper function to create namespaced event key
+ */
+export declare function createEventKey(namespace: keyof typeof EVENT_NAMESPACES, event: string): string;
+/**
+ * Alias for ERROR_EVENTS for backwards compatibility
+ */
+export declare const ERROR_EVENT_TYPES: {
+    readonly NETWORK_ERROR: "errors:network";
+    readonly VALIDATION_ERROR: "errors:validation";
+    readonly AUTHENTICATION_ERROR: "errors:authentication";
+    readonly AUTHORIZATION_ERROR: "errors:authorization";
+    readonly RATE_LIMIT_ERROR: "errors:rate-limit";
+    readonly SERVER_ERROR: "errors:server";
+    readonly CLIENT_ERROR: "errors:client";
+    readonly TIMEOUT_ERROR: "errors:timeout";
+    readonly CONFLICT_ERROR: "errors:conflict";
+    readonly CACHE_ERROR: "errors:cache";
+    readonly HEADERS_ERROR: "errors:headers";
+    readonly RETRY_ERROR: "errors:retry";
+    readonly STRATEGY_ERROR: "errors:strategy";
+    readonly REGIONAL_ERROR: "errors:regional";
+    readonly NOT_FOUND_ERROR: "errors:not-found";
+    readonly EXTERNAL_SERVICE_ERROR: "errors:external-service";
+    readonly UNKNOWN_ERROR: "errors:unknown";
+    readonly GENERIC_ERROR: "errors:generic";
+    readonly ANY: "errors:*";
+};
+/**
+ * Handler namespace creators for common event types
+ * These provide convenient functions to create properly namespaced handlers
+ *
+ * @example
+ * ```typescript
+ * // For error handlers at different scopes:
+ * const globalErrorNS = createErrorHandlerNamespace('GLOBAL');  // 'global:error'
+ * const clientErrorNS = createErrorHandlerNamespace('CLIENT');  // 'client:error'
+ *
+ * // For debug handlers at different scopes:
+ * const globalDebugNS = createDebugHandlerNamespace('GLOBAL');  // 'global:debug'
+ * const clientDebugNS = createDebugHandlerNamespace('CLIENT');  // 'client:debug'
+ * ```
+ */
+export declare const createErrorHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createDebugHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createRequestHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createResponseHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createRetryHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createHeadersHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createNetworkHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createCacheHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createConfigHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createPerformanceHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createClientHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createPollingHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+export declare const createRevalidationHandlerNamespace: (scope: keyof typeof HANDLER_SCOPES) => string;
+/**
+ * Pre-created handler namespaces for all event types and scopes
+ * These provide ready-to-use namespaces for handler registration
+ */
+/**
+ * Configuration update strategy - controls WHERE configuration is applied
+ * - 'merge': Merges with existing config at CLIENT scope
+ * - 'replace': Replaces existing config at CLIENT scope
+ * - 'temporary': Applies at REQUEST/TEMPORARY scope (highest priority)
+ */
+export type ConfigUpdateStrategy = 'merge' | 'replace' | 'temporary';
+/**
+ * Handler strategy - controls how handlers are registered and merged
+ * - 'merge': Merge handlers with existing ones (chain them)
+ * - 'replace': Replace existing handlers entirely
+ * - 'prepend': Add new handlers before existing ones
+ * - 'append': Add new handlers after existing ones
+ * - 'temporary': Apply as temporary handlers (highest priority, can be reverted)
+ */
+export type HandlerStrategy = 'merge' | 'replace' | 'append' | 'prepend' | 'temporary';
+export declare const HANDLER_NAMESPACES: {
+    readonly ERROR: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly DEBUG: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly HEADERS: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly NETWORK: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly CACHE: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly CONFIG: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly PERFORMANCE: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly CLIENT: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly REQUEST: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly RESPONSE: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly RETRY: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly POLLING: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+    readonly REVALIDATION: {
+        readonly GLOBAL: string;
+        readonly CONFIG: string;
+        readonly CLIENT: string;
+        readonly REQUEST: string;
+        readonly TEMPORARY: string;
+    };
+};
+/**
+ * Type-safe mapping of event type strings to HANDLER_NAMESPACES keys
+ * This ensures TypeScript will error if a new namespace is added without updating the map
+ *
+ * Used for mapping event types (like 'errors', 'headers') to their corresponding
+ * namespace keys in HANDLER_NAMESPACES (like 'ERROR', 'HEADERS')
+ */
+export declare const EVENT_TYPE_TO_NAMESPACE_MAP: Record<string, keyof typeof HANDLER_NAMESPACES>;
+export type ValidateAllNamespacesAreMapped = typeof EVENT_TYPE_TO_NAMESPACE_MAP extends Record<string, infer T> ? T extends keyof typeof HANDLER_NAMESPACES ? keyof typeof HANDLER_NAMESPACES extends T ? true : 'Error: Not all HANDLER_NAMESPACES keys are mapped in EVENT_TYPE_TO_NAMESPACE_MAP' : never : never;
+/**
+ * Get handler namespace for an event type and scope
+ * Helper function for consistent namespace resolution
+ */
+export declare function getHandlerNamespaceForEvent(eventType: string, scope: keyof typeof HANDLER_SCOPES): string;
+//# sourceMappingURL=namespaces.d.ts.map

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

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