@plyaz/types 1.7.16 → 1.7.17

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

@@ -0,0 +1,634 @@
+/**
+ * API Configuration Types
+ * Extends fetchff types while providing abstraction layer
+ */
+import type { RequestConfig as FetchffRequestConfig, FetchResponse, ResponseError, ErrorHandlingStrategy, CacheOptions, CacheKeyFunction, CacheSkipFunction, FetcherLogger, Method, DefaultParams, DefaultPayload, UrlPathParams, BodyPayload } from 'fetchff';
+import type { PollingConfig, PollingStrategyName } from '../polling';
+import type { UnifiedStrategyName } from '../strategies';
+import type { CacheStrategyName } from '../cache';
+import type { RetryConfig, RetryStrategyName } from '../retry';
+import type { PerformancePresetName } from '../performance';
+import type { RevalidationStrategyName } from '../revalidation';
+import type { ApiHeaders } 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';
+type HeaderBuilder = unknown;
+type HeaderPresetName = string;
+type DebugEventsConfig = Record<string, unknown>;
+type EnrichedHeadersOptions = Record<string, unknown>;
+export type { ConfigUpdateStrategy } from '../events';
+/**
+ * HTTP Methods - extend from fetchff but uppercase
+ */
+export type HttpMethod = Uppercase<Method>;
+/**
+ * Error handling strategies - re-export from fetchff
+ */
+export type ErrorStrategy = ErrorHandlingStrategy;
+/**
+ * Cache configuration - extends fetchff's CacheOptions
+ */
+export interface ApiCacheConfig extends Partial<CacheOptions> {
+    /** Time to cache in seconds (maps to cacheTime) */
+    ttl?: number;
+    /** Time before considering cache stale (maps to staleTime) */
+    stale?: number;
+    /** Skip caching entirely (maps to skipCache) */
+    skip?: boolean | CacheSkipFunction;
+    /** Custom cache key generator */
+    keyGenerator?: CacheKeyFunction | string;
+}
+/**
+ * Interceptor type aliases for convenience
+ * These match fetchff's expected signatures
+ */
+export type RequestInterceptor = NonNullable<FetchffRequestConfig['onRequest']>;
+export type ResponseInterceptor = NonNullable<FetchffRequestConfig['onResponse']>;
+export type ErrorInterceptor = NonNullable<FetchffRequestConfig['onError']>;
+export type RetryInterceptor = NonNullable<FetchffRequestConfig['onRetry']>;
+/**
+ * Main API configuration interface
+ * Extends fetchff's RequestConfig with our abstraction layer
+ * Supports ALL fetchff configuration options
+ */
+export interface ApiConfig extends Partial<Omit<FetchffRequestConfig, 'retry' | 'cache' | 'cacheTime' | 'staleTime' | 'skipCache' | 'cacheErrors' | 'cacheKey' | 'cacheBuster' | 'pollingInterval' | 'pollingDelay' | 'maxPollingAttempts' | 'shouldStopPolling' | 'data' | 'headers' | 'onRequest' | 'onResponse' | 'onError' | 'onRetry'>> {
+    /** Base URL for all requests */
+    baseURL?: string;
+    /** Default HTTP method */
+    method?: Method | string;
+    /** Default query parameters added to all requests */
+    params?: DefaultParams;
+    /** Default URL path parameters for dynamic routes */
+    urlPathParams?: UrlPathParams;
+    /** Default request body (alias for 'data' in fetchff) */
+    body?: BodyPayload;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Include credentials (cookies) in requests */
+    withCredentials?: boolean;
+    /** Error handling strategy */
+    strategy?: ErrorHandlingStrategy;
+    /** Flatten nested response data */
+    flattenResponse?: boolean;
+    /** Default response when request fails */
+    defaultResponse?: unknown;
+    /** Cancel previous requests to same endpoint */
+    cancellable?: boolean;
+    /** Reject promise for cancelled requests */
+    rejectCancelled?: boolean;
+    /** Time window for request deduplication (ms) */
+    dedupeTime?: number;
+    /** Disable automatic request on init (React-specific) */
+    immediate?: boolean;
+    /** Retry configuration with better naming */
+    retry?: RetryConfig | false;
+    /** Cache configuration with better naming */
+    cache?: ApiCacheConfig;
+    /**
+     * Polling configuration
+     * Can be:
+     * - A strategy name: 'jobStatus' | 'healthCheck' | 'liveData' | etc.
+     * - A PollingConfig object for custom configuration
+     * - false to disable polling
+     */
+    polling?: PollingStrategyName | PollingConfig | false;
+    /** Custom logger for debugging */
+    logger?: FetcherLogger;
+    /** Request interceptor(s) - can be single or array */
+    onRequest?: RequestInterceptor | RequestInterceptor[];
+    /** Response interceptor(s) - can be single or array */
+    onResponse?: ResponseInterceptor | ResponseInterceptor[];
+    /** Error interceptor(s) - can be single or array */
+    onError?: ErrorInterceptor | ErrorInterceptor[];
+    /** Retry interceptor(s) - can be single or array */
+    onRetry?: RetryInterceptor | RetryInterceptor[];
+    /**
+     * Unified strategy - Simple way to configure all domains at once
+     * Available: 'realtime', 'interactive', 'background', 'static', 'offline'
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({ unifiedStrategy: 'interactive' });
+     * ```
+     */
+    unifiedStrategy?: UnifiedStrategyName;
+    /**
+     * Individual strategy overrides
+     * These override the unified strategy if both are specified
+     */
+    /** Cache strategy name or direct config */
+    cacheStrategy?: CacheStrategyName;
+    /** Retry strategy name or direct config */
+    retryStrategy?: RetryStrategyName;
+    /** Polling strategy name */
+    pollingStrategy?: PollingStrategyName;
+    /** Performance optimization preset name */
+    performanceStrategy?: PerformancePresetName;
+    /** Revalidation strategy name */
+    revalidationStrategy?: RevalidationStrategyName;
+    /**
+     * Advanced header configuration with multiple options
+     * Supports presets, static headers, dynamic headers, and builders
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   headers: {
+     *     presets: ['json', 'cors'],
+     *     static: { 'x-api-key': 'secret' },
+     *     dynamic: async () => ({ 'authorization': await getToken() }),
+     *     autoDetectNetwork: true,
+     *     requestClientHints: true
+     *   }
+     * });
+     * ```
+     */
+    headers?: ApiHeaders | (() => ApiHeaders | Promise<ApiHeaders>) | {
+        /** Header presets to apply (e.g., 'json', 'cors', 'mobile') */
+        presets?: HeaderPresetName[];
+        /** Static headers that never change */
+        static?: ApiHeaders;
+        /** Dynamic headers computed at request time */
+        dynamic?: () => ApiHeaders | Promise<ApiHeaders>;
+        /** Header builder for complex logic */
+        builder?: (builder: HeaderBuilder) => HeaderBuilder;
+        /** Auto-detect network conditions and add Client Hints */
+        autoDetectNetwork?: boolean;
+        /** Request Client Hints from browser */
+        requestClientHints?: boolean;
+    };
+    /**
+     * Network-aware configuration for adaptive behavior
+     * Automatically adjusts client behavior based on network conditions
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   networkAware: {
+     *     enabled: true,
+     *     adaptConfig: true,
+     *     qualityPresets: {
+     *       [NETWORK_QUALITY.POOR]: {
+     *         performance: 'minimal',
+     *         cache: 'aggressive',
+     *         retry: 'exponential'
+     *       }
+     *     },
+     *     temporaryOverride: {
+     *       enabled: true,
+     *       triggers: { quality: [NETWORK_QUALITY.POOR] },
+     *       overrideConfig: { timeout: 60000 }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    networkAware?: {
+        /** Enable network-aware features */
+        enabled?: boolean;
+        /** Automatically adapt configuration based on network */
+        adaptConfig?: boolean;
+        /** Request Client Hints for better detection */
+        requestClientHints?: boolean;
+        /** Custom quality thresholds */
+        thresholds?: {
+            good?: {
+                rtt?: number;
+                downlink?: number;
+            };
+            fair?: {
+                rtt?: number;
+                downlink?: number;
+            };
+            poor?: {
+                rtt?: number;
+                downlink?: number;
+            };
+        };
+        /** Custom quality-to-preset mappings */
+        qualityPresets?: Partial<Record<NETWORK_QUALITY, {
+            performance?: PerformancePresetName;
+            cache?: CacheStrategyName;
+            retry?: RetryStrategyName;
+            revalidation?: RevalidationStrategyName;
+            polling?: PollingStrategyName | null;
+        }>>;
+        /** Temporary override configuration */
+        temporaryOverride?: {
+            enabled?: boolean;
+            triggers?: {
+                quality?: NETWORK_QUALITY[];
+                rtt?: number;
+                downlink?: number;
+                saveData?: boolean;
+            };
+            overrideConfig?: Partial<ApiConfig>;
+            checkInterval?: number;
+            onOverrideChange?: ((active: boolean, reason: string) => void) | Array<(active: boolean, reason: string) => void>;
+        };
+        /** Event listeners for network changes */
+        events?: NetworkEventHandlers;
+    };
+    /**
+     * Enriched context headers configuration for microservices
+     * Automatically collects device, network, platform, and compliance headers
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   enrichedHeaders: {
+     *     preset: 'standard',
+     *     includeDevice: true,
+     *     includeNetwork: true,
+     *     includeCompliance: true,
+     *     autoDetectRegion: true
+     *   }
+     * });
+     * ```
+     */
+    enrichedHeaders?: EnrichedHeadersOptions;
+    /**
+     * Event handlers for header changes, conflicts, and overrides
+     * Track all header modifications throughout the request lifecycle
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   headerEvents: {
+     *     onHeadersChanged: (event) => {
+     *       console.log('Headers changed:', event.data.changes);
+     *     },
+     *     onHeadersEnriched: (event) => {
+     *       console.log('Enriched headers:', event.data.headers);
+     *     },
+     *     onHeadersConflict: (event) => {
+     *       console.warn('Header conflict:', event.data.header);
+     *     },
+     *     onHeadersOverride: (event) => {
+     *       console.log('Headers overridden:', event.data.overridden);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    headerEvents?: HeaderEventHandlers;
+    /** User's original configuration (preserved for restoration) */
+    preservedConfig?: Partial<ApiClientOptions>;
+    /**
+     * Debug event handlers for monitoring configuration conflicts and network changes
+     * These handlers are automatically connected when the client is created
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   debugEvents: {
+     *     onConflict: (conflict) => {
+     *       console.warn('Config conflict:', conflict.property);
+     *     },
+     *     onDebugInfo: (info) => {
+     *       metricsCollector.send('debug.info', info);
+     *     },
+     *     autoCheckInterval: 60000 // Check every minute
+     *   }
+     * });
+     * ```
+     */
+    debugEvents?: DebugEventsConfig;
+    /**
+     * Error event handlers for comprehensive error handling
+     * These handlers are automatically chained with global error handlers
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   errorHandlers: {
+     *     onNetworkError: (error) => {
+     *       console.error('Network error:', error);
+     *       showOfflineNotification();
+     *     },
+     *     onAuthenticationError: (error) => {
+     *       console.error('Auth error:', error);
+     *       redirectToLogin();
+     *     },
+     *     onRateLimitError: (error) => {
+     *       console.warn('Rate limited:', error);
+     *       scheduleRetry(error.retryAfter);
+     *     },
+     *     onAnyError: (error) => {
+     *       // Catch-all for any errors
+     *       logToSentry(error);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    errorHandlers?: ErrorEventHandlers;
+    /**
+     * Configuration event handlers for monitoring config changes and updates
+     * Track when global config is updated, reset, or when presets are applied
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   configEvents: {
+     *     onGlobalUpdated: (event) => {
+     *       console.log('Config updated:', event.data.config);
+     *     },
+     *     onPresetApplied: (event) => {
+     *       console.log('Preset applied:', event.data.preset);
+     *     },
+     *     onEnvironmentConfigured: (event) => {
+     *       console.log('Environment detected:', event.data.environment);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    configEvents?: ConfigEventHandlers;
+    /**
+     * Client lifecycle event handlers for monitoring client operations
+     * Track client creation, requests, responses, and retries
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   clientEvents: {
+     *     onClientCreated: (event) => {
+     *       console.log('Client created:', event.data.clientId);
+     *     },
+     *     onRequestStart: (event) => {
+     *       console.log('Request started:', event.data.url);
+     *     },
+     *     onResponseReceived: (event) => {
+     *       console.log('Response received:', event.data.status);
+     *     },
+     *     onRetryAttempt: (event) => {
+     *       console.warn('Retry attempt:', event.data.attempt);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    clientEvents?: ClientEventHandlers;
+    /**
+     * Cache event handlers for monitoring cache operations
+     * Track cache hits, misses, invalidations, and stale data
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   cacheEvents: {
+     *     onCacheHit: (event) => {
+     *       console.log('Cache hit:', event.data.key);
+     *     },
+     *     onCacheMiss: (event) => {
+     *       console.log('Cache miss:', event.data.key);
+     *     },
+     *     onCacheInvalidate: (event) => {
+     *       console.log('Cache invalidated:', event.data.pattern);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    cacheEvents?: CacheEventHandlers;
+    /**
+     * Performance event handlers for monitoring API performance
+     * Track request timings, cache performance, and optimization events
+     *
+     * @example
+     * ```typescript
+     * const api = createApiClient({
+     *   performanceEvents: {
+     *     onRequestStart: (event) => {
+     *       console.log('Request started:', event.data.requestId);
+     *     },
+     *     onRequestComplete: (event) => {
+     *       console.log('Request completed in', event.data.duration, 'ms');
+     *     },
+     *     onThresholdExceeded: (event) => {
+     *       console.warn('Performance threshold exceeded:', event.data.type);
+     *     },
+     *     onOptimizationApplied: (event) => {
+     *       console.log('Optimization applied:', event.data.type);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    performanceEvents?: PerformanceEventHandlers;
+    /**
+     * Configuration override strategy for controlling how configurations are applied
+     * Determines the scope and behavior when updating configurations
+     *
+     * Strategies:
+     * - 'merge': Merges with existing config at CLIENT scope
+     * - 'replace': Replaces existing config entirely at CLIENT scope
+     * - 'temporary': Applies at REQUEST/TEMPORARY scope (highest priority, default for updateConfig)
+     *
+     * Event scopes behavior:
+     * - Client creation: Default is ALL scopes (global + client handlers merged)
+     * - Global config: Only 'global' scope
+     * - updateConfig with 'temporary': Default is only 'request' scope
+     * - updateConfig with 'merge'/'replace': Uses client's eventScopes
+     * - Can be explicitly set via eventScopes to force specific scopes
+     *
+     * @example
+     * ```typescript
+     * // Use temporary strategy (default) for highest priority
+     * const api = createApiClient({
+     *   timeout: 30000,
+     *   configOverride: {
+     *     strategy: 'temporary', // Apply future updates at REQUEST scope
+     *     eventScopes: ['client', 'request'] // Only emit to these scopes
+     *   }
+     * });
+     *
+     * // Use with updateConfig
+     * api.updateConfig({
+     *   timeout: 60000,
+     *   configOverride: {
+     *     strategy: 'replace', // Replace CLIENT config entirely
+     *     clearOnComplete: true // Auto-clear temporary overrides after request
+     *   }
+     * });
+     *
+     * // Or pass strategy directly to updateConfig
+     * api.updateConfig(
+     *   { timeout: 60000 },
+     *   { strategy: 'temporary' } // Default behavior
+     * );
+     * ```
+     */
+    configOverride?: {
+        /** Override strategy - controls WHERE config updates are applied (scope) */
+        strategy?: ConfigUpdateStrategy;
+        /**
+         * Handler strategy - controls how event handlers are registered and merged
+         * If not provided, falls back to 'strategy' value, then defaults to 'merge'
+         * Supports 'temporary' for handlers even when config strategy is different
+         */
+        handlerStrategy?: HandlerStrategy;
+        /** Event scopes to emit to - defaults to all scopes if not specified */
+        eventScopes?: EventScopeWithTemporary[];
+        /** Auto-clear temporary overrides after request completes */
+        clearOnComplete?: boolean;
+        /**
+         * Use priority mode for handler merging - only use highest priority handler
+         * When true: Only the highest priority handler runs (request > client > global)
+         * When false: All handlers are merged and run in sequence (default behavior)
+         * Note: Works with 'merge', 'replace', 'prepend', 'append' HandlerStrategy
+         * @default false
+         */
+        priority?: boolean;
+    };
+    /**
+     * Tracking and telemetry configuration
+     * Controls operation tracking, event processing, and debugging features
+     *
+     * @example
+     * ```typescript
+     * // Disable all tracking for GDPR compliance
+     * const api = createApiClient({
+     *   tracking: {
+     *     enabled: false,
+     *     operations: false,
+     *     events: false
+     *   }
+     * });
+     *
+     * // Enable only events but not operation tracking
+     * const api = createApiClient({
+     *   tracking: {
+     *     operations: false,
+     *     events: true,
+     *     eventStrategy: 'immediate'
+     *   }
+     * });
+     *
+     * // Custom tracking configuration
+     * const api = createApiClient({
+     *   tracking: {
+     *     enabled: true,
+     *     operations: true,
+     *     events: true,
+     *     queueStrategy: 'batch',
+     *     eventStrategy: 'immediate',
+     *     performanceMode: 'minimal'
+     *   }
+     * });
+     * ```
+     */
+    tracking?: {
+        /**
+         * Master switch for all tracking features
+         * When false, disables operations, events, and debugging
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Enable/disable operation tracking (debugger queue)
+         * Controls whether operations are tracked for debugging
+         * @default true
+         */
+        operations?: boolean;
+        /**
+         * Enable/disable event emission and processing
+         * Controls whether events are emitted and processed
+         * @default true
+         */
+        events?: boolean;
+        /**
+         * Queue processing strategy for operations
+         * - 'immediate': Process immediately (best for tests)
+         * - 'batch': Batch operations for processing
+         * - 'throttle': Throttle processing rate
+         * - 'debounce': Debounce processing
+         * @default 'batch' in production, 'immediate' in tests
+         */
+        queueStrategy?: 'immediate' | 'batch' | 'throttle' | 'debounce';
+        /**
+         * Event processing strategy
+         * - 'immediate': Process events immediately
+         * - 'queued': Queue events for batch processing
+         * @default 'immediate'
+         */
+        eventStrategy?: 'immediate' | 'queued';
+        /**
+         * Performance mode for tracking
+         * - 'full': Track everything with full detail
+         * - 'minimal': Track only essential operations
+         * - 'off': Disable tracking (same as enabled: false)
+         * @default 'full'
+         */
+        performanceMode?: 'full' | 'minimal' | 'off';
+        /**
+         * Maximum number of operations to keep in history
+         * @default 1000
+         */
+        historySize?: number;
+        /**
+         * Maximum number of conflicts to track
+         * @default 100
+         */
+        maxConflicts?: number;
+        /**
+         * Skip adding entries to history for this request/operation
+         * Useful for batch operations to avoid duplicate history entries
+         * @default false
+         */
+        skipHistory?: boolean;
+        /**
+         * Enable telemetry data collection (if configured)
+         * Separate from debugging - for analytics/monitoring
+         * @default false
+         */
+        telemetry?: boolean;
+    };
+}
+/**
+ * Request-specific configuration
+ * Extends ApiConfig with request-specific fields
+ */
+export interface RequestConfig extends ApiConfig {
+    /** HTTP method - can be Method or string for flexibility */
+    method?: Method | string;
+    /** URL path (can be relative to baseURL) */
+    url?: string;
+    /** Query parameters */
+    params?: DefaultParams;
+    /** URL path parameters (for dynamic routes like /users/:id) */
+    urlPathParams?: UrlPathParams;
+    /** Request body */
+    body?: BodyPayload;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Endpoint configuration
+ * Used to define API endpoints with their specific settings
+ * Can override ALL global settings on per-endpoint basis
+ */
+export interface EndpointConfig extends Omit<RequestConfig, 'params' | 'urlPathParams' | 'body'> {
+    /** URL pattern (can include :param placeholders) */
+    url: string;
+    /** HTTP method - typically use Method constants */
+    method?: Method | string;
+    /** Description of the endpoint */
+    description?: string;
+}
+/**
+ * API Response wrapper
+ * Extends fetchff's FetchResponse
+ */
+export interface ApiResponse<TData = DefaultPayload, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> extends FetchResponse<TData, TBody, TParams, TPathParams> {
+}
+/**
+ * API Error interface
+ * Extends fetchff's ResponseError
+ */
+export interface ApiError<TData = DefaultPayload, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> extends ResponseError<TData, TBody, TParams, TPathParams> {
+}

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

@@ -0,0 +1,5 @@
+/**
+ * API Error Types
+ * Re-exports all error-related types for the API package
+ */
+export type * from './types';