@plyaz/config 1.5.1 → 1.5.2

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

@@ -0,0 +1,69 @@
+/**
+ * Typed constants for API error handling
+ */
+/**
+ * Operation types for error context
+ */
+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";
+};
+/**
+ * Field types for error context
+ */
+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";
+};
+/**
+ * Storage types for API errors
+ */
+export declare const STORAGE_TYPES: {
+    readonly PRIMARY: "primary";
+    readonly FALLBACK: "fallback";
+    readonly MEMORY: "memory";
+    readonly SESSION: "session";
+    readonly LOCAL: "local";
+};

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

@@ -0,0 +1,5 @@
+/**
+ * API Error Constants
+ * Re-exports all API error-related constants
+ */
+export * from './constants';

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

@@ -0,0 +1,285 @@
+/**
+ * Event Namespace Constants
+ * Centralized constants for all event namespaces in the API package
+ */
+/**
+ * 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"];
+/**
+ * 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 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";
+};
+/**
+ * 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";
+};
+/**
+ * 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:*";
+};

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

@@ -0,0 +1,5 @@
+/**
+ * Event Constants
+ * Re-exports all event-related constants
+ */
+export * from './constants';

package/dist/api/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * API Package Constants
+ * Re-exports all API-related constants (events, errors, etc.)
+ */
+export * from './events';
+export * from './errors';
+export * from './network';
+export * from './regional';

package/dist/api/network/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Network Quality Constants
+ */
+/**
+ * Network quality levels
+ */
+export declare const NETWORK_QUALITY: {
+    readonly EXCELLENT: "excellent";
+    readonly GOOD: "good";
+    readonly FAIR: "fair";
+    readonly POOR: "poor";
+    readonly OFFLINE: "offline";
+    readonly UNKNOWN: "unknown";
+};
+/**
+ * Network quality type
+ */
+export type NetworkQuality = (typeof NETWORK_QUALITY)[keyof typeof NETWORK_QUALITY];

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

@@ -0,0 +1,5 @@
+/**
+ * Network Constants
+ * Re-exports all network-related constants
+ */
+export * from './constants';

package/dist/api/regional/constants.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Regional detection constants
+ */
+export declare const REGION_STORAGE_KEY = "@plyaz/api:userRegion";
+/**
+ * Confidence levels for region detection
+ */
+export declare const CONFIDENCE_LEVELS: {
+    readonly CDN_HEADER: 0.95;
+    readonly TIMEZONE_DIRECT: 0.9;
+    readonly TIMEZONE_PREFIX: 0.8;
+    readonly HIGH: 0.8;
+    readonly LOCALE_DIRECT: 0.7;
+    readonly MEDIUM: 0.7;
+    readonly GEOLOCATION: 0.6;
+    readonly LOCALE_LANGUAGE: 0.5;
+    readonly LOW: 0.5;
+    readonly GLOBAL_FALLBACK: 0.3;
+    readonly UNKNOWN_FALLBACK: 0.2;
+    readonly FINAL_FALLBACK: 0.1;
+};
+/**
+ * Geographic coordinates for region detection
+ */
+export declare const COORDINATES: {
+    readonly EU: {
+        readonly MIN_LAT: 35;
+        readonly MAX_LAT: 70;
+        readonly MIN_LON: -10;
+        readonly MAX_LON: 40;
+    };
+    readonly US: {
+        readonly MIN_LAT: 25;
+        readonly MAX_LAT: 50;
+        readonly MIN_LON: -125;
+        readonly MAX_LON: -65;
+    };
+    readonly US_WEST: {
+        readonly MIN_LAT: 32;
+        readonly MAX_LAT: 42;
+        readonly MIN_LON: -125;
+        readonly MAX_LON: -114;
+    };
+    readonly US_EAST: {
+        readonly MIN_LAT: 38;
+        readonly MAX_LAT: 45;
+        readonly MIN_LON: -80;
+        readonly MAX_LON: -70;
+    };
+    readonly ASIA: {
+        readonly MIN_LAT: 18;
+        readonly MAX_LAT: 54;
+        readonly MIN_LON: 73;
+        readonly MAX_LON: 135;
+    };
+    readonly JAPAN: {
+        readonly MIN_LAT: 30;
+        readonly MAX_LAT: 46;
+        readonly MIN_LON: 129;
+        readonly MAX_LON: 146;
+    };
+};
+export declare const CACHE_DURATION_MS: number;
+/**
+ * Map regions to presets
+ */
+export declare const REGION_TO_PRESET: {
+    readonly eu: "gdpr";
+    readonly us: "ccpa";
+    readonly 'us-ca': "ccpa";
+    readonly cn: "pipl";
+    readonly jp: "appi";
+    readonly ca: "global";
+    readonly global: "global";
+};

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

@@ -0,0 +1,5 @@
+/**
+ * Regional Constants
+ * Re-exports all regional-related constants
+ */
+export * from './constants';