@plyaz/types 1.7.18 → 1.7.20

package/dist/api/headers/enum.d.ts

@@ -0,0 +1,34 @@
+import type { NetworkPresetConfig } from '..';
+/**
+ * Data saver mode uses offline-optimized presets
+ */
+export declare const DATA_SAVER_PRESETS: NetworkPresetConfig;
+/**
+ * Valid Client Hint header names
+ */
+export declare const CLIENT_HINT_HEADERS: {
+    readonly SAVE_DATA: "save-data";
+    readonly ECT: "ect";
+    readonly RTT: "rtt";
+    readonly DOWNLINK: "downlink";
+    readonly DEVICE_MEMORY: "device-memory";
+    readonly ACCEPT_CH: "Accept-CH";
+    readonly ACCEPT_CH_LIFETIME: "Accept-CH-Lifetime";
+};
+/**
+ * Validation ranges for header values
+ */
+export declare const VALIDATION_RANGES: {
+    readonly RTT: {
+        readonly MIN: 0;
+        readonly MAX: 10000;
+    };
+    readonly DOWNLINK: {
+        readonly MIN: 0;
+        readonly MAX: 10000;
+    };
+    readonly DEVICE_MEMORY: {
+        readonly MIN: 0;
+        readonly MAX: 128;
+    };
+};

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

@@ -3,3 +3,4 @@
  * Re-exports all header-related types for the API package
  */
 export type * from './types';
+export * from './enum';

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

@@ -2,6 +2,7 @@
  * Header Management Type Definitions
  * Comprehensive types for HTTP headers, following TASK-016 specification
  */
+import type { ApiClientInstance, DebuggerConfigSource, PerformancePresetName, RetryStrategyName, CacheStrategyName, RevalidationStrategyName } from '..';
 /**
  * Headers that affect cache key generation (based on fetchff behavior)
  * These headers will be included in cache key computation
@@ -57,3 +58,458 @@ export type AuthType = 'Bearer' | 'Basic' | 'ApiKey' | 'Custom';
  * Platform types for client identification
  */
 export type PlatformType = 'ios' | 'android' | 'web' | 'desktop' | 'mobile' | string;
+/**
+ * Configuration options for enriched context headers
+ * Controls what device, network, platform, and compliance headers are collected
+ *
+ * @example
+ * ```typescript
+ * const options: EnrichedHeadersOptions = {
+ *   preset: 'standard',
+ *   includeDevice: true,
+ *   includeNetwork: true,
+ *   autoDetectRegion: true,
+ *   regionalPreset: 'gdpr',
+ *   respectDoNotTrack: true
+ * };
+ * ```
+ */
+export interface EnrichedHeadersOptions {
+    /** Include device info from navigator */
+    includeDevice?: boolean;
+    /** Include network from Connection API */
+    includeNetwork?: boolean;
+    /** Include calculated recommendations */
+    includeAdaptive?: boolean;
+    /** Include browser/app detection */
+    includePlatform?: boolean;
+    /** Include performance metrics */
+    includePerformance?: boolean;
+    /** Include compliance-related headers */
+    includeCompliance?: boolean;
+    /** Preset configuration for common scenarios */
+    preset?: 'minimal' | 'standard' | 'full' | 'low-data' | 'high-performance' | 'compliance-strict';
+    /** Auto-detect region from timezone/locale/IP */
+    autoDetectRegion?: boolean;
+    /** Force specific compliance preset */
+    regionalPreset?: 'gdpr' | 'ccpa' | 'pipl' | 'appi' | 'global';
+    /** Force specific region code (e.g., 'eu', 'us-ca') */
+    region?: string;
+    /** Show consent UI if needed (placeholder, not implemented) */
+    requestConsent?: boolean;
+    /** Honor DNT (Do Not Track) header */
+    respectDoNotTrack?: boolean;
+    /** Use timezone for region detection */
+    useTimezone?: boolean;
+    /** Use browser locale for region detection */
+    useLocale?: boolean;
+    /** Use CDN headers (server-side only) */
+    useCDNHeaders?: boolean;
+    /** Use IP-based detection (requires server) */
+    useIPDetection?: boolean;
+    /** Use geolocation API (requires permission) */
+    useGeolocation?: boolean;
+    /** Default region if all detection methods fail */
+    fallbackRegion?: string;
+    /** Cache expiration in milliseconds */
+    cacheExpiry?: number;
+    /** Caching configuration for detection results */
+    cache?: {
+        /** Enable caching of detection results */
+        enabled?: boolean;
+        /** Time to live in milliseconds */
+        ttl?: number;
+        /** Storage type for cached data */
+        storage?: 'memory' | 'session' | 'local';
+        /** Custom storage key */
+        key?: string;
+    };
+    /** Master switch for enriched headers feature */
+    enabled?: boolean;
+    /** Store headers in AsyncLocalStorage context */
+    useContext?: boolean;
+    /** Headers to exclude from collection */
+    exclude?: string[];
+    /** Headers to always include even if preset excludes them */
+    include?: string[];
+}
+/**
+ * Result of header validation
+ * Contains validation status with detailed error and warning messages
+ *
+ * @example
+ * ```typescript
+ * const result: HeaderValidationResult = {
+ *   isValid: false,
+ *   errors: ['Missing authorization header', 'Invalid content-type'],
+ *   warnings: ['Deprecated header format used']
+ * };
+ * ```
+ */
+export interface HeaderValidationResult {
+    /** Whether the headers are valid */
+    isValid: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+    /** Array of validation warning messages */
+    warnings: string[];
+}
+/**
+ * Build enriched context headers from request context
+ */
+export interface RequestContext {
+    request?: {
+        headers?: Record<string, string | string[] | undefined>;
+        ip?: string;
+        method?: string;
+        url?: string;
+        [key: string]: unknown;
+    };
+    clientContext?: ApiClientInstance;
+    [key: string]: unknown;
+}
+/**
+ * Header merge strategy
+ */
+export type HeaderMergeStrategy = 'overwrite' | 'combine' | 'preserve';
+/**
+ * Options for header merging
+ */
+export interface HeaderMergeOptions {
+    /** Strategy for handling conflicting headers */
+    strategy?: HeaderMergeStrategy;
+    /** Headers that should never be overwritten */
+    immutableHeaders?: string[];
+    /** Custom conflict resolver function */
+    conflictResolver?: (key: string, existingValue: string, newValue: string) => string;
+    /** Whether to emit events for conflicts and merges */
+    emitEvents?: boolean;
+}
+/**
+ * Header merge result with conflict tracking
+ */
+export interface HeaderMergeResult {
+    /** Merged headers */
+    headers: ApiHeaders;
+    /** Any conflicts that occurred during merging */
+    conflicts: Array<{
+        header: string;
+        sources: Array<{
+            source: DebuggerConfigSource;
+            value: string;
+            priority: number;
+        }>;
+    }>;
+}
+/**
+ * Extracted header categories from request processing
+ * Groups headers by their source type for organized middleware handling
+ *
+ * @example
+ * ```typescript
+ * const extraction: RequestHeaderExtraction = {
+ *   clientHints: { 'ECT': '4g', 'RTT': '50' },
+ *   deviceInfo: { 'x-device-memory': '8' },
+ *   networkInfo: { 'x-network-quality': 'good' }
+ * };
+ * ```
+ */
+export interface RequestHeaderExtraction {
+    /** Client hints headers from browser */
+    clientHints: ApiHeaders;
+    /** Device information headers */
+    deviceInfo: ApiHeaders;
+    /** Network information headers */
+    networkInfo: ApiHeaders;
+}
+/**
+ * Parameters for checking immutable header constraints
+ * Used internally during header merging to protect critical headers
+ *
+ * @example
+ * ```typescript
+ * const params: ImmutableHeaderParams = {
+ *   existingValue: 'Bearer token123',
+ *   newValue: 'Bearer token456',
+ *   key: 'authorization',
+ *   normalizedKey: 'authorization',
+ *   isImmutable: true,
+ *   options: { immutableHeaders: ['authorization'] }
+ * };
+ * ```
+ */
+export interface ImmutableHeaderParams {
+    /** Existing header value (if any) */
+    existingValue: string | undefined;
+    /** New value attempting to be set */
+    newValue: string;
+    /** Original header key */
+    key: string;
+    /** Normalized lowercase header key */
+    normalizedKey: string;
+    /** Whether this header is marked as immutable */
+    isImmutable: boolean;
+    /** Header merge options including immutable list */
+    options: HeaderMergeOptions;
+}
+/**
+ * Parameters for resolving header conflicts during merging
+ * Provides all information needed to decide which value wins
+ *
+ * @example
+ * ```typescript
+ * const params: ConflictResolutionParams = {
+ *   key: 'content-type',
+ *   existingValue: 'application/json',
+ *   newValue: 'application/xml',
+ *   strategy: 'overwrite',
+ *   conflictResolver: (key, existing, newVal) => newVal
+ * };
+ * ```
+ */
+export interface ConflictResolutionParams {
+    /** Header key with conflict */
+    key: string;
+    /** Current header value */
+    existingValue: string;
+    /** New value trying to be set */
+    newValue: string;
+    /** Merge strategy to apply */
+    strategy: HeaderMergeStrategy;
+    /** Optional custom resolver function */
+    conflictResolver?: HeaderMergeOptions['conflictResolver'];
+}
+/**
+ * Parameters for processing a batch of new headers
+ * Used internally during header merge operations
+ *
+ * @example
+ * ```typescript
+ * const params: ProcessNewHeadersParams = {
+ *   newHeaders: { 'content-type': 'application/json' },
+ *   result: { 'authorization': 'Bearer token' },
+ *   immutableSet: new Set(['authorization']),
+ *   options: { strategy: 'overwrite' },
+ *   strategy: 'overwrite',
+ *   conflicts: []
+ * };
+ * ```
+ */
+export interface ProcessNewHeadersParams {
+    /** New headers to be merged */
+    newHeaders: ApiHeaders | undefined;
+    /** Result headers being built */
+    result: ApiHeaders;
+    /** Set of immutable header keys */
+    immutableSet: Set<string>;
+    /** Merge options */
+    options: HeaderMergeOptions;
+    /** Current merge strategy */
+    strategy: HeaderMergeStrategy;
+    /** Array collecting conflicts */
+    conflicts: HeaderMergeResult['conflicts'];
+}
+/**
+ * Parameters for processing a single header entry
+ * Contains all context needed to handle one header during merge
+ *
+ * @example
+ * ```typescript
+ * const params: ProcessSingleHeaderParams = {
+ *   key: 'Content-Type',
+ *   value: 'application/json',
+ *   normalizedKey: 'content-type',
+ *   existingValue: 'text/plain',
+ *   isImmutable: false,
+ *   options: { strategy: 'overwrite' },
+ *   strategy: 'overwrite'
+ * };
+ * ```
+ */
+export interface ProcessSingleHeaderParams {
+    /** Original header key */
+    key: string;
+    /** Header value to set */
+    value: string;
+    /** Normalized lowercase key */
+    normalizedKey: string;
+    /** Existing value (if any) */
+    existingValue: string | undefined;
+    /** Whether header is immutable */
+    isImmutable: boolean;
+    /** Merge options */
+    options: HeaderMergeOptions;
+    /** Merge strategy */
+    strategy: HeaderMergeStrategy;
+}
+/**
+ * Result of processing a single header
+ * Indicates the final value and whether a conflict occurred
+ *
+ * @example
+ * ```typescript
+ * const result: ProcessSingleHeaderResult = {
+ *   value: 'application/json',
+ *   conflict: {
+ *     header: 'content-type',
+ *     sources: [
+ *       { source: 'global', value: 'text/plain', priority: 1 },
+ *       { source: 'request', value: 'application/json', priority: 3 }
+ *     ]
+ *   }
+ * };
+ * ```
+ */
+export interface ProcessSingleHeaderResult {
+    /** Final resolved header value */
+    value: string | undefined;
+    /** Conflict information if one occurred */
+    conflict?: {
+        header: string;
+        sources: Array<{
+            source: DebuggerConfigSource;
+            value: string;
+            priority: number;
+        }>;
+    };
+}
+/**
+ * Parameters for tracking header conflicts
+ * Accumulates conflict information during merge process
+ *
+ * @example
+ * ```typescript
+ * const params: ConflictTrackingParams = {
+ *   conflicts: {},
+ *   normalizedKey: 'content-type',
+ *   value: 'application/json',
+ *   priority: 3,
+ *   originalSource: { source: 'request', value: 'application/json', priority: 3 }
+ * };
+ * ```
+ */
+export interface ConflictTrackingParams {
+    /** Map of conflicts by header key */
+    conflicts: Record<string, {
+        header: string;
+        sources: Array<{
+            source: DebuggerConfigSource;
+            value: string;
+            priority: number;
+        }>;
+    }>;
+    /** Normalized header key */
+    normalizedKey: string;
+    /** Header value */
+    value: string;
+    /** Priority level of this source */
+    priority: number;
+    /** Original source information */
+    originalSource: {
+        source: DebuggerConfigSource;
+        value: string;
+        priority: number;
+    } | null;
+}
+/**
+ * Network preset configuration
+ */
+export interface NetworkPresetConfig {
+    performance: PerformancePresetName;
+    cache: CacheStrategyName;
+    retry: RetryStrategyName;
+    revalidation: RevalidationStrategyName;
+}
+/**
+ * Header preset factory functions for common scenarios
+ * Each preset returns headers configured for specific use cases
+ *
+ * @example
+ * ```typescript
+ * const presets: HeaderPresetName = {
+ *   json: () => ({ 'content-type': 'application/json' }),
+ *   bearerToken: (token) => ({ 'authorization': `Bearer ${token}` }),
+ *   cors: () => ({ 'origin': '*', 'access-control-allow-methods': 'GET,POST' })
+ * };
+ *
+ * // Usage
+ * const headers = presets.json();
+ * const authHeaders = presets.bearerToken('my-token-123');
+ * ```
+ */
+export type HeaderPresetName = {
+    /** JSON content type headers */
+    readonly json: () => ApiHeaders;
+    /** Form data content type headers */
+    readonly form: () => ApiHeaders;
+    /** File upload headers (multipart/form-data) */
+    readonly upload: () => ApiHeaders;
+    /** XML content type headers */
+    readonly xml: () => ApiHeaders;
+    /** GraphQL API headers */
+    readonly graphql: () => ApiHeaders;
+    /** Server-Sent Events headers */
+    readonly sse: () => ApiHeaders;
+    /** AJAX request headers */
+    readonly ajax: () => ApiHeaders;
+    /** WebSocket upgrade headers */
+    readonly websocket: () => ApiHeaders;
+    /** Plain text content type headers */
+    readonly text: () => ApiHeaders;
+    /** HTML content type headers */
+    readonly html: () => ApiHeaders;
+    /** CORS headers */
+    readonly cors: () => ApiHeaders;
+    /** Cache-Control: no-cache headers */
+    readonly noCache: () => ApiHeaders;
+    /** Basic authentication headers */
+    readonly basicAuth: (username: string, password: string) => ApiHeaders;
+    /** Bearer token authentication headers */
+    readonly bearerToken: (token: string) => ApiHeaders;
+    /** API key authentication headers */
+    readonly apiKey: (apiKey: string) => ApiHeaders;
+};
+/**
+ * Interface representing the public API of HeaderBuilder
+ * Useful for type-checking without requiring the actual class instance
+ *
+ * This interface allows for:
+ * - Duck typing compatibility
+ * - Easier mocking in tests
+ * - Type-safe function parameters without importing the class
+ * - Clearer documentation of the public API contract
+ *
+ * @example
+ * ```typescript
+ * function buildHeaders(builder: HeaderBuilderLike): ApiHeaders {
+ *   return builder
+ *     .auth('token123')
+ *     .contentType('json')
+ *     .build();
+ * }
+ * ```
+ */
+export interface HeaderBuilderLike {
+    auth(token: string, type?: AuthType): HeaderBuilderLike;
+    contentType(type: ContentType): HeaderBuilderLike;
+    accept(type: AcceptType): HeaderBuilderLike;
+    locale(locale: string): HeaderBuilderLike;
+    platform(platform: PlatformType): HeaderBuilderLike;
+    tenant(tenantId: string): HeaderBuilderLike;
+    user(userId: string): HeaderBuilderLike;
+    version(version: string): HeaderBuilderLike;
+    features(flags: string[] | string): HeaderBuilderLike;
+    device(deviceId: string): HeaderBuilderLike;
+    session(sessionId: string): HeaderBuilderLike;
+    client(clientId: string): HeaderBuilderLike;
+    correlationId(id?: string): HeaderBuilderLike;
+    requestId(id?: string): HeaderBuilderLike;
+    traceId(traceId?: string): HeaderBuilderLike;
+    spanId(spanId: string): HeaderBuilderLike;
+    ajax(): HeaderBuilderLike;
+    custom(key: string, value: string): HeaderBuilderLike;
+    merge(headers: Record<string, string>): HeaderBuilderLike;
+    build(): ApiHeaders;
+    clear(): HeaderBuilderLike;
+    remove(key: string): HeaderBuilderLike;
+}

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

@@ -0,0 +1 @@
+export type * from './types';

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

@@ -0,0 +1,131 @@
+import type { NETWORK_QUALITY, NetworkInfo } from '..';
+import type { ConfigConflict, DebugInfo, MonitoringAlert } from '../debugger';
+/**
+ * Hook options for conflict monitoring
+ */
+export interface UseApiConfigConflictsOptions {
+    /** Enable automatic conflict checking */
+    autoCheck?: boolean;
+    /** Interval for automatic checks (ms) */
+    interval?: number;
+    /** Handler for individual conflicts */
+    onConflict?: (conflict: ConfigConflict) => void;
+}
+/**
+ * Hook return value
+ */
+export interface UseApiConfigConflictsReturn {
+    /** Current conflicts */
+    conflicts: ConfigConflict[];
+    /** Whether currently checking */
+    isChecking: boolean;
+    /** Last check timestamp */
+    lastCheck: Date | null;
+    /** Manually trigger check */
+    checkNow: () => Promise<void>;
+    /** Clear all conflicts */
+    clearConflicts: () => void;
+    /** Number of conflicts */
+    conflictCount: number;
+    /** Whether there are any conflicts */
+    hasConflicts: boolean;
+}
+/**
+ * Hook options for debug info monitoring
+ */
+export interface UseApiDebugInfoOptions {
+    /** Enable automatic refresh */
+    autoRefresh?: boolean;
+    /** Refresh interval (ms) */
+    interval?: number;
+    /** Handler for debug info updates */
+    onUpdate?: (debugInfo: DebugInfo) => void;
+}
+/**
+ * Hook return value
+ */
+export interface UseApiDebugInfoReturn {
+    /** Current debug information */
+    debugInfo: DebugInfo | null;
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** Last update timestamp */
+    lastUpdate: Date | null;
+    /** Manually refresh debug info */
+    refresh: () => Promise<void>;
+    /** Active configuration overrides */
+    activeOverrides: DebugInfo['activeOverrides'];
+    /** Performance score */
+    performanceScore: number | undefined;
+    /** Network quality */
+    networkQuality: DebugInfo['networkQuality'] | undefined;
+}
+/**
+ * Hook options for complete monitoring
+ */
+export interface UseApiMonitorOptions {
+    /** Enable conflict checking */
+    enableConflictCheck?: boolean;
+    /** Conflict check interval (ms) */
+    conflictCheckInterval?: number;
+    /** Enable debug info generation */
+    enableDebugInfo?: boolean;
+    /** Debug info interval (ms) */
+    debugInfoInterval?: number;
+    /** Handler for monitoring alerts */
+    onAlert?: (alert: MonitoringAlert) => void;
+}
+/**
+ * Hook return value
+ */
+export interface UseApiMonitorReturn {
+    /** Current conflicts */
+    conflicts: UseApiConfigConflictsReturn['conflicts'];
+    /** Whether there are conflicts */
+    hasConflicts: boolean;
+    /** Number of conflicts */
+    conflictCount: number;
+    /** Manually check conflicts */
+    checkConflicts: () => Promise<void>;
+    /** Debug information */
+    debugInfo: UseApiDebugInfoReturn['debugInfo'];
+    /** Active overrides */
+    activeOverrides: UseApiDebugInfoReturn['activeOverrides'];
+    /** Performance score */
+    performanceScore: number | undefined;
+    /** Network quality */
+    networkQuality: UseApiDebugInfoReturn['networkQuality'];
+    /** Refresh debug info */
+    refreshDebugInfo: () => Promise<void>;
+    /** Whether monitoring is active */
+    isMonitoring: boolean;
+    /** Start monitoring */
+    startMonitoring: () => void;
+    /** Stop monitoring */
+    stopMonitoring: () => void;
+    /** Last conflict check */
+    lastConflictCheck: Date | null;
+    /** Last debug update */
+    lastDebugUpdate: Date | null;
+}
+/**
+ * Hook return value
+ */
+export interface UseApiNetworkQualityReturn {
+    /** Current network quality */
+    quality: NETWORK_QUALITY;
+    /** Network information */
+    networkInfo: NetworkInfo;
+    /** Whether online */
+    isOnline: boolean;
+    /** Whether connection is slow */
+    isSlow: boolean;
+    /** Whether data saver is enabled */
+    isDataSaver: boolean;
+    /** Effective connection type */
+    effectiveType: NetworkInfo['effectiveType'];
+    /** Round-trip time */
+    rtt: NetworkInfo['rtt'];
+    /** Downlink speed */
+    downlink: NetworkInfo['downlink'];
+}

package/dist/api/index.d.ts

@@ -7,7 +7,8 @@ export type * from './errors';
 export type * from './queue';
 export type * from './headers';
 export type * from './network';
-export type * from './regional';
+export type * from './endpoints';
+export type * from './debugger';
 export type * from './cache';
 export type * from './retry';
 export type * from './polling';
@@ -15,5 +16,10 @@ export type * from './revalidation';
 export type * from './strategies';
 export type * from './client';
 export type * from './performance';
+export type * from './request';
+export type * from './regional';
+export type * from './retry';
 export type * from './config';
 export type * from './utils';
+export type * from './pubsub';
+export type * from './hooks';