@plyaz/types 1.7.18 → 1.7.19

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

@@ -5,10 +5,80 @@
  * Network quality levels enum
  */
 export declare enum NETWORK_QUALITY {
-    EXCELLENT = "excellent",
-    GOOD = "good",
-    FAIR = "fair",
-    POOR = "poor",
-    OFFLINE = "offline",
+    EXCELLENT = "excellent",// 4G, low latency
+    GOOD = "good",// 3G or good 4G
+    FAIR = "fair",// 2G or poor 3G
+    POOR = "poor",// Slow 2G or worse
+    OFFLINE = "offline",// No connection
     UNKNOWN = "unknown"
 }
+/**
+ * Event priority mapping
+ */
+export declare const EVENT_PRIORITY_MAP: {
+    readonly error: "critical";
+    readonly onNetworkError: "critical";
+    readonly critical: "critical";
+    readonly config: "high";
+    readonly auth: "high";
+    readonly conflict: "high";
+    readonly network: "normal";
+    readonly headers: "normal";
+    readonly performance: "normal";
+    readonly debug: "low";
+    readonly metrics: "low";
+    readonly tracking: "low";
+};
+/**
+ * Export preset names for easy access
+ */
+export declare const NetworkPresetNames: {
+    readonly OFFLINE_FIRST: "offline-first";
+    readonly DATA_SAVER: "data-saver";
+    readonly SLOW_CONNECTION: "slow-connection";
+    readonly FAIR_CONNECTION: "fair-connection";
+    readonly GOOD_CONNECTION: "good-connection";
+    readonly EXCELLENT_CONNECTION: "excellent-connection";
+    readonly AGGRESSIVE_CACHE: "aggressive-cache";
+    readonly REALTIME: "realtime";
+    readonly BACKGROUND_SYNC: "background-sync";
+};
+/**
+ * Confidence levels for quality detection
+ */
+export declare const NETWORK_CONFIDENCE_LEVELS: {
+    /** Excellent confidence (90%) */
+    readonly EXCELLENT: 0.9;
+    /** High confidence (80%) */
+    readonly HIGH: 0.8;
+    /** Medium confidence (70%) */
+    readonly MEDIUM: 0.7;
+    /** Low confidence (50%) */
+    readonly LOW: 0.5;
+    /** Threshold for high confidence classification */
+    readonly HIGH_THRESHOLD: 0.7;
+    /** Threshold for medium confidence classification */
+    readonly MEDIUM_THRESHOLD: 0.4;
+};
+/**
+ * Network quality thresholds
+ */
+export interface QualityThresholds {
+    excellentRTT: number;
+    goodRTT: number;
+    fairRTT: number;
+    excellentSpeed: number;
+    goodSpeed: number;
+    fairSpeed: number;
+}
+export declare const SPEED_THRESHOLDS: {
+    readonly EXCELLENT: 10;
+    readonly GOOD: 2;
+    readonly FAIR: 0.5;
+};
+export declare const RTT_THRESHOLDS: {
+    readonly EXCELLENT: 50;
+    readonly GOOD: 150;
+    readonly FAIR: 400;
+};
+export declare const DEFAULT_THRESHOLDS: QualityThresholds;

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

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

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

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

package/dist/api/network/frameworks/nestjs/types.d.ts

@@ -0,0 +1,47 @@
+import type { Request } from 'express';
+import type { NetworkInfo } from '../..';
+import type { EnrichedHeadersOptions } from '../../../headers';
+/**
+ * Options for the enriched headers guard
+ */
+export interface EnrichedHeadersGuardOptions extends EnrichedHeadersOptions {
+    /**
+     * Debug mode - log header processing
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Store headers in request object
+     * @default true
+     */
+    storeInRequest?: boolean;
+    /**
+     * Require specific headers to be present
+     */
+    requiredHeaders?: string[];
+    /**
+     * Require specific compliance for access
+     */
+    requiredCompliance?: string[];
+}
+/**
+ * Options for the enriched headers interceptor
+ */
+export interface EnrichedHeadersInterceptorOptions extends EnrichedHeadersOptions {
+    /**
+     * Debug mode - log header processing
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Store headers in request object
+     * @default true
+     */
+    storeInRequest?: boolean;
+}
+/**
+ * Extended request with network info for NestJS
+ */
+export interface NestRequestWithNetwork extends Request {
+    networkInfo?: NetworkInfo;
+}

package/dist/api/network/frameworks/types.d.ts

@@ -0,0 +1,76 @@
+import type { NextApiRequest } from 'next';
+import type { NetworkInfo } from '..';
+import type { ApiHeaders, EnrichedHeadersOptions } from '../../headers';
+/**
+ * Extended Express request with network info
+ */
+export interface ExpressRequestWithNetwork extends Request {
+    networkInfo?: NetworkInfo;
+}
+/**
+ * Express middleware factory with options
+ *
+ * @param options - Middleware options
+ * @returns Express middleware
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createNetworkDetectionMiddleware } from '@plyaz/api/utils/network/frameworks/express';
+ *
+ * const app = express();
+ *
+ * app.use(createNetworkDetectionMiddleware({
+ *   requestClientHints: true,
+ *   onNetworkDetected: (networkInfo) => {
+ *     console.log('Network detected:', networkInfo);
+ *   }
+ * }));
+ * ```
+ */
+export interface NetworkDetectionOptions {
+    /**
+     * Whether to request Client Hints from browser
+     * @default true
+     */
+    requestClientHints?: boolean;
+    /**
+     * Callback when network is detected
+     */
+    onNetworkDetected?: (networkInfo: NetworkInfo) => void;
+    /**
+     * Custom header name to store network info (for debugging)
+     */
+    debugHeaderName?: string;
+}
+/**
+ * Express request with enriched headers
+ */
+export interface ExpressRequestWithEnrichedHeaders extends Request {
+    enrichedHeaders?: ApiHeaders;
+}
+/**
+ * Options for enriched headers middleware
+ */
+export interface EnrichedHeadersMiddlewareOptions extends EnrichedHeadersOptions {
+    /**
+     * Store enriched headers in res.locals
+     * @default false
+     */
+    storeInLocals?: boolean;
+    /**
+     * Add specific headers to response
+     */
+    addToResponse?: string[];
+    /**
+     * Debug mode - log header processing
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Extended Next.js request with network info
+ */
+export interface NextApiRequestWithNetwork extends NextApiRequest {
+    networkInfo?: NetworkInfo;
+}

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

@@ -4,3 +4,4 @@
  */
 export type * from './enums';
 export type * from './types';
+export type * from './frameworks';

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

@@ -2,6 +2,8 @@
  * Network Information API types
  * Properly typed definitions for browser and Node.js navigator
  */
+import type { NETWORK_QUALITY } from '.';
+import type { ConfigSource, NetworkEvent } from '../events';
 /**
  * Network Information interface (partial for what we use)
  */
@@ -17,20 +19,43 @@ export interface NetworkInformation {
 }
 /**
  * Navigator-like interface with necessary properties
- * Avoids directly extending Navigator which is experimental in Node
+ * Avoids directly extending Navigator which is experimental in Node.js environments
+ * Provides cross-platform compatibility for browser and server-side code
+ *
+ * @example
+ * ```typescript
+ * const nav: NavigatorLike = {
+ *   userAgent: 'Mozilla/5.0...',
+ *   platform: 'MacIntel',
+ *   onLine: true,
+ *   language: 'en-US'
+ * };
+ * ```
  */
 interface NavigatorLike {
+    /** Browser user agent string */
     userAgent?: string;
+    /** Operating system platform identifier */
     platform?: string;
+    /** Browser engine identifier */
     product?: string;
+    /** Primary language code (e.g., 'en-US') */
     language?: string;
+    /** Array of preferred language codes */
     languages?: readonly string[];
+    /** Whether the browser is online */
     onLine?: boolean;
+    /** Number of logical processor cores */
     hardwareConcurrency?: number;
+    /** Device RAM in gigabytes (from Client Hints) */
     deviceMemory?: number;
+    /** Maximum number of simultaneous touch points */
     maxTouchPoints?: number;
+    /** Do Not Track header value */
     doNotTrack?: string | null;
+    /** Browser vendor identifier */
     vendor?: string;
+    /** Browser application version */
     appVersion?: string;
 }
 /**
@@ -57,65 +82,348 @@ export type ConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | '5g' | 'wifi' | 'e
 /**
  * Effective connection type
  */
-export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
+export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | 'unknown';
 /**
- * Network information details
+ * Network connection information
  */
 export interface NetworkInfo {
-    type?: ConnectionType;
-    effectiveType?: EffectiveConnectionType;
-    downlink?: number;
-    rtt?: number;
+    type: ConnectionType;
+    effectiveType: EffectiveConnectionType;
+    downlink: number | null;
+    downlinkMax: number | null;
+    rtt: number | null;
+    saveData: boolean;
+    online: boolean;
+    deviceMemory?: number | null;
+}
+/**
+ * Network status callback
+ */
+export type NetworkStatusCallback = (online: boolean) => void;
+/**
+ * Network client hints
+ */
+export interface NetworkClientHints {
+    'Save-Data'?: 'on' | null;
+    ECT?: EffectiveConnectionType;
+    RTT?: string;
+    Downlink?: string;
+    'Device-Memory'?: string;
+}
+/**
+ * Network preset names
+ */
+export type NetworkPresetName = 'fast' | 'good' | 'moderate' | 'slow' | 'offline';
+/**
+ * Network event listener
+ */
+export type NetworkEventListener<TEvent extends NetworkEvent = NetworkEvent> = (event: TEvent) => void;
+/**
+ * Adaptive configuration based on network
+ */
+export interface AdaptiveConfig {
+    enableHeavyOperations: boolean;
+    enableAutoRefresh: boolean;
+    enablePreloading: boolean;
+    imageQuality: 'high' | 'medium' | 'low';
+    videoQuality: 'auto' | '1080p' | '720p' | '480p' | '360p';
+    dataFetchStrategy: 'aggressive' | 'balanced' | 'conservative';
+}
+/**
+ * Monitoring configuration for network-based optimization
+ */
+export interface MonitoringConfig {
+    networkBasedOptimization: boolean;
+    adaptiveQuality: boolean;
+    enableMetrics: boolean;
+    deviceId: string;
+    platform: string;
+}
+/**
+ * Network metrics subset
+ */
+export interface NetworkMetrics {
+    downlink: number | null;
+    downlinkMax: number | null;
+    rtt: number | null;
+    saveData: boolean;
+}
+/**
+ * Network event statistics
+ */
+export interface NetworkEventStats {
+    totalEvents: number;
+    listenerCount: number;
+    recentEvents: NetworkEvent[];
+    overrideCount: number;
+}
+/**
+ * Partial network info from headers (with null for missing values)
+ */
+export interface PartialNetworkInfoFromHeaders {
+    effectiveType: EffectiveConnectionType | null;
+    rtt: number | null;
+    downlink: number | null;
+    saveData: boolean;
+    deviceMemory?: number | null;
+}
+/**
+ * HTTP request object with network information
+ * Used for server-side network-aware request handling
+ *
+ * @example
+ * ```typescript
+ * const request: NetworkRequest = {
+ *   headers: new Headers({ 'User-Agent': '...' }),
+ *   networkInfo: {
+ *     effectiveType: '4g',
+ *     rtt: 50,
+ *     downlink: 10,
+ *     saveData: false
+ *   },
+ *   networkQuality: NETWORK_QUALITY.GOOD,
+ *   saveData: false
+ * };
+ * ```
+ */
+export interface NetworkRequest {
+    /** Request headers (Headers object or plain object) */
+    headers?: Headers | Record<string, string | string[] | undefined>;
+    /** Network information extracted from headers */
+    networkInfo?: PartialNetworkInfoFromHeaders;
+    /** Detected network quality level */
+    networkQuality?: NETWORK_QUALITY;
+    /** Whether data saver mode is enabled */
     saveData?: boolean;
-    onLine: boolean;
 }
 /**
- * Quality thresholds for network assessment
+ * HTTP response object for setting network-related headers
+ * Provides methods to add Client Hints and network metadata to responses
+ *
+ * @example
+ * ```typescript
+ * const response: NetworkResponse = {
+ *   setHeader: (key, value) => console.log(`${key}: ${value}`),
+ *   headers: {
+ *     set: (key, value) => console.log(`Setting ${key}: ${value}`)
+ *   }
+ * };
+ * ```
  */
-export interface QualityThresholds {
-    good?: {
-        rtt?: number;
-        downlink?: number;
+export interface NetworkResponse {
+    /** Function to set a single response header */
+    setHeader?: (key: string, value: string) => void;
+    /** Headers object with set method */
+    headers?: {
+        set: (key: string, value: string) => void;
     };
-    fair?: {
-        rtt?: number;
-        downlink?: number;
+}
+/**
+ * Network quality preset configurations
+ * These work alongside existing network utilities without conflicts
+ */
+export interface NetworkQualityPreset {
+    /** Preset identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Network quality this preset optimizes for */
+    targetQuality: NETWORK_QUALITY;
+    /** Preset configuration values */
+    config: {
+        /** Request timeout in milliseconds */
+        timeout?: number;
+        /** Cache time in seconds */
+        cacheTime?: number;
+        /** Stale time in seconds */
+        staleTime?: number;
+        /** Enable request deduplication */
+        dedupe?: boolean;
+        /** Deduplication time window in milliseconds */
+        dedupeTime?: number;
+        /** Maximum concurrent requests */
+        maxConcurrent?: number;
+        /** Request retry configuration */
+        retry?: {
+            attempts: number;
+            delay: number;
+            backoff: number;
+            maxDelay: number;
+        };
+        /** Response compression threshold */
+        compressionThreshold?: number;
+        /** Enable progressive loading */
+        progressive?: boolean;
+        /** Skip cache for new requests */
+        skipCache?: boolean;
+        /** Cache error responses */
+        cacheErrors?: boolean;
     };
-    poor?: {
-        rtt?: number;
-        downlink?: number;
+    /** Conditions when this preset should be automatically applied */
+    autoApply?: {
+        /** Network qualities that trigger this preset */
+        qualities?: NETWORK_QUALITY[];
+        /** Save-data mode requirement */
+        saveData?: boolean;
+        /** Connection types that trigger this preset */
+        connectionTypes?: string[];
+        /** RTT threshold in milliseconds */
+        maxRTT?: number;
+        /** Minimum downlink speed in Mbps */
+        minDownlink?: number;
     };
 }
 /**
- * Network status callback
+ * User configuration preferences that should be preserved
  */
-export type NetworkStatusCallback = (online: boolean) => void;
+export interface UserNetworkPreferences {
+    /** User's preferred quality level (overrides auto-detection) */
+    preferredQuality?: NETWORK_QUALITY;
+    /** User's timeout preferences */
+    timeouts?: {
+        minimum?: number;
+        maximum?: number;
+        default?: number;
+    };
+    /** User's caching preferences */
+    caching?: {
+        enabled?: boolean;
+        maxAge?: number;
+        staleWhileRevalidate?: boolean;
+    };
+    /** User's retry preferences */
+    retry?: {
+        maxAttempts?: number;
+        aggressive?: boolean;
+    };
+    /** Features the user has disabled */
+    disabledFeatures?: string[];
+    /** Custom endpoint-specific overrides */
+    endpointOverrides?: Record<string, Partial<NetworkQualityPreset['config']>>;
+}
 /**
- * Adaptive configuration based on network
+ * Temporary override information for debugging and restoration
  */
-export interface AdaptiveConfig {
-    timeout?: number;
-    retry?: number;
-    prefetch?: boolean;
-    autoRefresh?: boolean;
-    batchSize?: number;
-    pageSize?: number;
+export interface TemporaryOverride {
+    /** Property that was overridden */
+    property: string;
+    /** Original value before override */
+    originalValue: unknown;
+    /** Override value */
+    overrideValue: unknown;
+    /** When the override was applied */
+    appliedAt: number;
+    /** How long the override should last (in milliseconds) */
+    duration?: number;
+    /** Source configuration that requested the override */
+    source: ConfigSource;
+    /** Reason for the override */
+    reason: string;
+    /** Function to restore original value */
+    restore: () => void;
+    /** Whether override is still active */
+    active: boolean;
+    /** Context information for debugging */
+    context: {
+        endpoint?: string;
+        clientName?: string;
+        configPath?: string;
+    };
 }
 /**
- * Network client hints
+ * Extended navigator interface with additional device and platform properties
+ * Combines standard navigator properties with device capabilities
+ *
+ * @example
+ * ```typescript
+ * const navigator: ExtendedNavigator = {
+ *   userAgent: window.navigator.userAgent,
+ *   platform: 'MacIntel',
+ *   hardwareConcurrency: 8,
+ *   deviceMemory: 16,
+ *   onLine: true
+ * };
+ * ```
  */
-export interface NetworkClientHints {
-    downlink?: string;
-    rtt?: string;
-    ect?: string;
-    saveData?: string;
+export interface ExtendedNavigator {
+    /** Browser user agent string */
+    userAgent?: string;
+    /** Operating system platform identifier */
+    platform?: string;
+    /** Browser engine identifier */
+    product?: string;
+    /** Primary language code */
+    language?: string;
+    /** Array of preferred language codes */
+    languages?: readonly string[];
+    /** Whether the browser is online */
+    onLine?: boolean;
+    /** Number of logical processor cores */
+    hardwareConcurrency?: number;
+    /** Device RAM in gigabytes */
+    deviceMemory?: number;
+    /** Maximum number of simultaneous touch points */
+    maxTouchPoints?: number;
+    /** Browser vendor identifier */
+    vendor?: string;
+    /** Browser application version */
+    appVersion?: string;
+    /** Do Not Track preference */
+    doNotTrack?: string | null;
 }
 /**
- * Network preset names
+ * Platform detection results
  */
-export type NetworkPresetName = 'fast' | 'good' | 'moderate' | 'slow' | 'offline';
+export interface PlatformInfo {
+    /** Operating system */
+    os: 'windows' | 'macos' | 'linux' | 'ios' | 'android' | 'unknown';
+    /** Browser/runtime */
+    runtime: 'chrome' | 'firefox' | 'safari' | 'edge' | 'node' | 'electron' | 'unknown';
+    /** Device type */
+    deviceType: 'desktop' | 'mobile' | 'tablet' | 'unknown';
+    /** Is mobile device */
+    isMobile: boolean;
+    /** Is touch device */
+    isTouch: boolean;
+    /** Screen size category */
+    screenSize: 'small' | 'medium' | 'large' | 'xlarge' | 'unknown';
+}
 /**
- * Network event listener
+ * Application version information
  */
-export type NetworkEventListener = (event: Event) => void;
+export interface AppInfo {
+    /** Version number */
+    version: string;
+    /** Environment (development, production, etc.) */
+    environment: string;
+    /** Build number or commit hash */
+    build?: string;
+    /** Feature flags */
+    features: string[];
+}
+/**
+ * Device information
+ */
+export interface DeviceInfo {
+    /** Unique device identifier */
+    id: string;
+    /** Platform information */
+    platform: PlatformInfo;
+    /** Screen information */
+    screen: {
+        width: number;
+        height: number;
+        colorDepth: number;
+        pixelRatio: number;
+    };
+    /** Memory in GB (if available) */
+    memory?: number;
+    /** CPU cores (if available) */
+    cores?: number;
+    /** Timezone information */
+    timezone: {
+        name: string;
+        offset: number;
+    };
+}
 export {};