@plyaz/api 1.0.2 → 1.1.0

package/dist/api/network/frameworks/nestjs/noDataSaverGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noDataSaverGuard.d.ts","sourceRoot":"","sources":["../../../../../src/api/network/frameworks/nestjs/noDataSaverGuard.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAc,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,qBACa,gBAAiB,SAAQ,YAAY;IAChD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;CAIhD"}

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

@@ -0,0 +1,86 @@
+/**
+ * Next.js middleware for network detection
+ */
+import type { NextApiRequest, NextApiResponse, NextApiHandler } from 'next';
+import type { NetworkInfo, NextApiRequestWithNetwork } from '@plyaz/types/api';
+/**
+ * Next.js middleware for network detection
+ * Adds network information to the request object and requests Client Hints from browser
+ *
+ * @param handler - Next.js API route handler
+ * @returns Wrapped handler with network detection
+ *
+ * @example
+ * ```typescript
+ * // pages/api/data.ts
+ * import { withNetworkDetection } from '@plyaz/api/utils/network/frameworks/nextjs';
+ *
+ * export default withNetworkDetection(async (req, res) => {
+ *   const { networkInfo } = req;
+ *
+ *   if (networkInfo?.saveData) {
+ *     // Return minimal data for users with data saver enabled
+ *     return res.json({ data: getMinimalData() });
+ *   }
+ *
+ *   if (networkInfo?.effectiveType === '2g' || networkInfo?.effectiveType === 'slow-2g') {
+ *     // Return cached or simplified data for slow connections
+ *     return res.json({ data: getCachedData() });
+ *   }
+ *
+ *   // Return full data for good connections
+ *   return res.json({ data: getFullData() });
+ * });
+ * ```
+ */
+export declare function withNetworkDetection<T extends NextApiRequestWithNetwork>(handler: (req: T, res: NextApiResponse) => Promise<void> | void): NextApiHandler;
+/**
+ * Next.js Edge Runtime middleware for network detection
+ * Works with Next.js 13+ Edge API Routes
+ *
+ * @example
+ * ```typescript
+ * // app/api/data/route.ts
+ * import { NextRequest, NextResponse } from 'next/server';
+ * import { getNetworkInfoFromRequest } from '@plyaz/api/utils/network/frameworks/nextjs';
+ *
+ * export async function GET(request: NextRequest) {
+ *   const networkInfo = getNetworkInfoFromRequest(request);
+ *
+ *   if (networkInfo?.saveData) {
+ *     return NextResponse.json({ data: getMinimalData() });
+ *   }
+ *
+ *   return NextResponse.json({ data: getFullData() });
+ * }
+ *
+ * export const runtime = 'edge';
+ * ```
+ */
+export declare function getNetworkInfoFromRequest(request: Request): NetworkInfo;
+/**
+ * Next.js middleware helper to add Client Hints headers to response
+ *
+ * @param response - Next.js response or NextResponse
+ * @returns Response with Client Hints headers added
+ *
+ * @example
+ * ```typescript
+ * import { NextResponse } from 'next/server';
+ * import { addClientHintsToResponse } from '@plyaz/api/utils/network/frameworks/nextjs';
+ *
+ * export function middleware() {
+ *   const response = NextResponse.next();
+ *   return addClientHintsToResponse(response);
+ * }
+ * ```
+ */
+export declare function addClientHintsToResponse<T extends Response | NextApiResponse>(response: T): T;
+/**
+ * Type guard to check if request has network info
+ *
+ * @param req - Request to check
+ * @returns True if request has network info
+ */
+export declare function hasNetworkInfo(req: NextApiRequest | NextApiRequestWithNetwork): req is NextApiRequestWithNetwork;
+//# sourceMappingURL=nextjs.d.ts.map

package/dist/api/network/frameworks/nextjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../../../src/api/network/frameworks/nextjs.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,yBAAyB,EACtE,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAC9D,cAAc,CA4BhB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAoBvE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,QAAQ,GAAG,eAAe,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAgB7F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,GAAG,yBAAyB,GAC9C,GAAG,IAAI,yBAAyB,CAElC"}

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

@@ -0,0 +1,45 @@
+/**
+ * Shared utilities for framework middleware
+ */
+import type { NetworkInfo } from '@plyaz/types/api';
+export declare function createAdaptiveResponse<T>(networkInfo: NetworkInfo | undefined, options: {
+    excellent?: T;
+    good?: T;
+    fair?: T;
+    poor?: T;
+    offline?: T;
+    default: T;
+}): T;
+export declare function shouldServeHighQuality(networkInfo?: NetworkInfo): boolean;
+/**
+ * Helper to determine cache duration based on network conditions
+ *
+ * @param networkInfo - Network information
+ * @param baseTime - Base cache time in seconds
+ * @returns Adjusted cache time in seconds
+ */
+export declare function getAdaptiveCacheDuration(networkInfo?: NetworkInfo, baseTime?: number): number;
+/**
+ * Helper to determine if request should be cached based on network
+ *
+ * @param networkInfo - Network information
+ * @returns True if aggressive caching should be used
+ */
+export declare function shouldUseAggressiveCaching(networkInfo?: NetworkInfo): boolean;
+/**
+ * Get recommended timeout based on network conditions
+ *
+ * @param networkInfo - Network information
+ * @param baseTimeout - Base timeout in milliseconds
+ * @returns Adjusted timeout in milliseconds
+ */
+export declare function getFrameworkAdaptiveTimeout(networkInfo?: NetworkInfo, baseTimeout?: number): number;
+/**
+ * Get recommended batch size based on network conditions
+ *
+ * @param networkInfo - Network information
+ * @param baseBatchSize - Base batch size
+ * @returns Adjusted batch size
+ */
+export declare function getFrameworkAdaptiveBatchSize(networkInfo?: NetworkInfo, baseBatchSize?: number): number;
+//# sourceMappingURL=shared.d.ts.map

package/dist/api/network/frameworks/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../src/api/network/frameworks/shared.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA8EpD,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,OAAO,EAAE;IACP,SAAS,CAAC,EAAE,CAAC,CAAC;IACd,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,CAAC,CAAC;CACZ,GACA,CAAC,CAMH;AA+BD,wBAAgB,sBAAsB,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAazE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,CAAC,EAAE,WAAW,EACzB,QAAQ,GAAE,MAA4D,GACrE,MAAM,CAwBR;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAU7E;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,CAAC,EAAE,WAAW,EACzB,WAAW,GAAE,MAAsC,GAClD,MAAM,CAiBR;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,CAAC,EAAE,WAAW,EACzB,aAAa,GAAE,MAAW,GACzB,MAAM,CAuBR"}

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

@@ -0,0 +1,112 @@
+/**
+ * Network Header Detection Utilities
+ * Parse and utilize HTTP Client Hints headers for network-aware capabilities
+ */
+import type { PartialNetworkInfoFromHeaders, ApiClientOptions, NetworkRequest, NetworkResponse } from '@plyaz/types/api';
+import { NETWORK_QUALITY } from '@plyaz/types/api';
+/**
+ * Network Client Hints headers interface
+ */
+/**
+ * Partial network info from headers (with null for missing values)
+ */
+/**
+ * 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";
+};
+/**
+ * Get network information from HTTP headers
+ *
+ * @param headers - Request headers containing Client Hints
+ * @returns Partial network information
+ *
+ * @example
+ * ```typescript
+ * // In a Next.js API route
+ * const networkInfo = getNetworkInfoFromHeaders(req.headers);
+ * if (networkInfo.saveData) {
+ *   // Serve lighter content
+ * }
+ * ```
+ */
+export declare function getNetworkInfoFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): PartialNetworkInfoFromHeaders;
+/**
+ * Get Client Hint request headers
+ * These headers request the browser to send network information
+ *
+ * @returns Headers to request Client Hints
+ *
+ * @example
+ * ```typescript
+ * // In Next.js middleware
+ * const response = NextResponse.next();
+ * const hintHeaders = getClientHintHeaders();
+ * Object.entries(hintHeaders).forEach(([key, value]) => {
+ *   response.headers.set(key, value);
+ * });
+ * ```
+ */
+export declare function getClientHintHeaders(): Record<string, string>;
+/**
+ * Infer network quality from Client Hints
+ *
+ * @param headers - Request headers
+ * @returns Network quality level
+ */
+export declare function getNetworkQualityFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): NETWORK_QUALITY;
+/**
+ * Check if Save-Data header is enabled
+ *
+ * @param headers - Request headers
+ * @returns True if data saver is enabled
+ */
+export declare function isDataSaverEnabledFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): boolean;
+/**
+ * Create network-aware configuration from headers
+ * Combines existing presets based on detected network quality
+ *
+ * @param headers - Request headers
+ * @returns Configuration adjustments based on network
+ *
+ * @example
+ * ```typescript
+ * import { getEnv } from '@utils/environment';
+ * const config = getNetworkConfigFromHeaders(req.headers);
+ * const apiClient = createApiClient({
+ *   ...config,
+ *   baseURL: getEnv('API_URL')
+ * });
+ * ```
+ */
+export declare function getNetworkConfigFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): Partial<ApiClientOptions>;
+/**
+ * Middleware for Next.js API routes with network detection
+ *
+ * @example
+ * ```typescript
+ * // pages/api/data.ts
+ * import { withNetworkDetection } from '@plyaz/api';
+ *
+ * export default withNetworkDetection(async (req, res) => {
+ *   const { networkQuality, saveData } = req;
+ *
+ *   if (saveData) {
+ *     // Return minimal data
+ *     return res.json({ data: 'minimal' });
+ *   }
+ *
+ *   // Return full data
+ *   return res.json({ data: 'full' });
+ * });
+ * ```
+ */
+export declare function withNetworkDetection<TReq extends NetworkRequest = NetworkRequest, TRes extends NetworkResponse = NetworkResponse>(handler: (req: TReq, res: TRes) => Promise<void> | void): (req: TReq, res: TRes) => Promise<void>;
+//# sourceMappingURL=headers.d.ts.map

package/dist/api/network/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../src/api/network/headers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,6BAA6B,EAM7B,gBAAgB,EAEhB,cAAc,EACd,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,eAAe,EAAoC,MAAM,kBAAkB,CAAC;AAQrF;;GAEG;AACH;;GAEG;AACH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAQtB,CAAC;AA+DX;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,6BAA6B,CAa/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO7D;AA6CD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,eAAe,CAoBjB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,OAAO,CAGT;AA2ID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,OAAO,CAAC,gBAAgB,CAAC,CAgB3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wBAAgB,oBAAoB,CAClC,IAAI,SAAS,cAAc,GAAG,cAAc,EAC5C,IAAI,SAAS,eAAe,GAAG,eAAe,EAE9C,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACtD,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAyBzC"}

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

@@ -0,0 +1,17 @@
+/**
+ * Network utilities for connection detection and adaptive behavior
+ * Provides comprehensive network quality assessment and monitoring
+ */
+export type { NetworkInfo, ConnectionType, EffectiveConnectionType, NetworkClientHints, NetworkPresetName, NetworkQualityPreset, UserNetworkPreferences, NetworkRequest, NetworkResponse, NavigatorWithConnection, NetworkInformation, ExpressRequestWithNetwork, ExpressRequestWithEnrichedHeaders, NextApiRequestWithNetwork, } from '@plyaz/types/api';
+export { NETWORK_QUALITY } from '@plyaz/types/api';
+export { isSlowConnection, isNetworkAPISupported, getConnection } from './core';
+export { getNavigator, hasNavigator, isBrowser } from '../utils/environment';
+export { getNetworkInfo, getConnectionType, getEffectiveConnectionType, isCellularConnection, isWifiConnection, isDataSaverEnabled, getNetworkRTT, getNetworkSpeed, isOnline, isOffline, } from './connection';
+export { getNetworkQuality, getNetworkQualityScore, canPerformHeavyOperation, getAdaptiveTimeout, } from './quality';
+export { networkStatus, waitForOnline, onOnline, onOffline } from './status';
+export { getAdaptiveConfig, getAdaptiveApiConfig, getAdaptiveBatchSize, getAdaptivePageSize, shouldPrefetch, shouldAutoRefresh, } from './adaptive';
+export { getNetworkInfoFromHeaders, getNetworkQualityFromHeaders, getClientHintHeaders, getNetworkConfigFromHeaders, } from './headers';
+export * from './frameworks';
+export { startNetworkEventMonitoring } from './events';
+export { networkPresets, getNetworkPreset, getPresetForQuality, getPresetForNetworkInfo, getMatchingPresets, createCustomPreset, mergePresets, validatePreset, NetworkPresetNames, } from './presets';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/network/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,WAAW,EACX,cAAc,EACd,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,iCAAiC,EACjC,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAGhF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAG7E,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,0BAA0B,EAC1B,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,QAAQ,EACR,SAAS,GACV,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG7E,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AAGnB,cAAc,cAAc,CAAC;AAG7B,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAGvD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,kBAAkB,GACnB,MAAM,WAAW,CAAC"}

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

@@ -0,0 +1,225 @@
+/**
+ * Network Configuration Manager
+ * Dynamic preset system that respects user configuration while providing temporary overrides
+ * Handles conflicts with existing network utilities and provides comprehensive debugging
+ */
+import type { NetworkQualityPreset, UserNetworkPreferences, TemporaryOverride, DebuggerConfigSource, NetworkPresetName } from '@plyaz/types/api';
+/**
+ * Network quality preset configurations
+ * These work alongside existing network utilities without conflicts
+ */
+/**
+ * User configuration preferences that should be preserved
+ */
+/**
+ * Temporary override information for debugging and restoration
+ */
+/**
+ * Network Configuration Manager Class
+ */
+export declare class NetworkConfigurationManager {
+    private userPreferences;
+    private availablePresets;
+    private activeOverrides;
+    private currentPreset?;
+    private monitoringEnabled;
+    private cleanupFunctions;
+    constructor();
+    /**
+     * Set user preferences that should be preserved across preset changes
+     */
+    setUserPreferences(preferences: UserNetworkPreferences): void;
+    /**
+     * Get current user preferences
+     */
+    getUserPreferences(): UserNetworkPreferences;
+    /**
+     * Register a custom network quality preset
+     */
+    registerPreset(preset: NetworkQualityPreset): void;
+    /**
+     * Get all available presets
+     */
+    getAvailablePresets(): NetworkQualityPreset[];
+    /**
+     * Helper to validate and get preset
+     */
+    private validateAndGetPreset;
+    /**
+     * Helper to apply tracking to config
+     */
+    private applyTrackingToConfig;
+    /**
+     * Apply a specific preset with user preference consideration
+     */
+    applyPreset(presetId: string, options?: {
+        temporary?: boolean;
+        duration?: number;
+        context?: {
+            endpoint?: string;
+            clientName?: string;
+            configPath?: string;
+        };
+    }): NetworkQualityPreset['config'];
+    /**
+     * Apply temporary configuration override with automatic restoration
+     */
+    applyTemporaryOverride(property: string, value: unknown, options: {
+        duration?: number;
+        reason: string;
+        source?: DebuggerConfigSource;
+        context?: {
+            endpoint?: string;
+            clientName?: string;
+            configPath?: string;
+        };
+    }): () => void;
+    /**
+     * Get optimal preset for current network conditions
+     */
+    getOptimalPreset(): NetworkQualityPreset | null;
+    /**
+     * Enable automatic preset monitoring and switching
+     */
+    enableAutoPresetSwitching(): void;
+    /**
+     * Disable automatic preset monitoring
+     */
+    disableAutoPresetSwitching(): void;
+    /**
+     * Get current active overrides for debugging
+     */
+    getActiveOverrides(): TemporaryOverride[];
+    /**
+     * Restore all temporary overrides
+     */
+    restoreAllOverrides(): void;
+    /**
+     * Get configuration manager stats for debugging
+     */
+    getStats(): {
+        currentPreset?: string;
+        activeOverrides: number;
+        userPreferences: UserNetworkPreferences;
+        availablePresets: string[];
+        monitoringEnabled: boolean;
+    };
+    /**
+     * Get the currently active preset ID
+     */
+    getActivePreset(): string | undefined;
+    /**
+     * Get all temporary overrides currently active
+     */
+    getTemporaryOverrides(): Record<string, unknown>;
+    /**
+     * Cleanup resources
+     */
+    dispose(): void;
+    /**
+     * Apply a preset by name (convenience method)
+     */
+    applyPresetByName(name: NetworkPresetName, options?: {
+        temporary?: boolean;
+        duration?: number;
+        context?: {
+            endpoint?: string;
+            clientName?: string;
+            configPath?: string;
+        };
+    }): NetworkQualityPreset['config'];
+    /**
+     * Initialize default network quality presets
+     */
+    private initializeDefaultPresets;
+    /**
+     * Setup event handlers for configuration tracking
+     */
+    private setupEventHandlers;
+    /**
+     * Apply timeout preferences to config
+     */
+    private applyTimeoutPreferences;
+    /**
+     * Apply caching preferences to config
+     */
+    private applyCachingPreferences;
+    /**
+     * Apply retry preferences to config
+     */
+    private applyRetryPreferences;
+    /**
+     * Apply endpoint-specific overrides to config
+     */
+    private applyEndpointOverrides;
+    /**
+     * Merge preset config with user preferences
+     */
+    private mergeWithUserPreferences;
+    /**
+     * Find preset for specific quality level
+     */
+    private findPresetForQuality;
+    /**
+     * Find best preset for current network conditions
+     */
+    private findBestPresetForConditions;
+    /**
+     * Check if quality matches preset requirements
+     */
+    private qualityMatchesPreset;
+    /**
+     * Check if save-data setting matches preset requirements
+     */
+    private saveDataMatchesPreset;
+    /**
+     * Check if RTT is within preset threshold
+     */
+    private rttWithinThreshold;
+    /**
+     * Check if downlink meets preset minimum
+     */
+    private downlinkMeetsMinimum;
+    /**
+     * Check if preset matches current network conditions
+     */
+    private presetMatchesConditions;
+    /**
+     * Track user preference overrides for debugging
+     */
+    private trackUserPreferenceOverride;
+    /**
+     * Track preference changes
+     */
+    private trackPreferenceChanges;
+    /**
+     * Schedule automatic restoration of a preset
+     */
+    private schedulePresetRestore;
+    /**
+     * Get current configuration value (placeholder for actual implementation)
+     */
+    private getCurrentConfigValue;
+    /**
+     * Set configuration value (placeholder for actual implementation)
+     */
+    private setConfigValue;
+}
+/**
+ * Global network configuration manager instance
+ */
+export declare const networkConfigManager: NetworkConfigurationManager;
+/**
+ * Convenience function to apply temporary network override
+ */
+export declare function applyTemporaryNetworkOverride(property: string, value: unknown, options: {
+    duration?: number;
+    reason: string;
+    endpoint?: string;
+    clientName?: string;
+}): () => void;
+/**
+ * Get network configuration optimized for current conditions with user preferences
+ */
+export declare function getOptimizedNetworkConfig(): NetworkQualityPreset['config'] | null;
+//# sourceMappingURL=networkConfigurationManager.d.ts.map

package/dist/api/network/networkConfigurationManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"networkConfigurationManager.d.ts","sourceRoot":"","sources":["../../../src/api/network/networkConfigurationManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EAGjB,oBAAoB,EAGpB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAe1B;;;GAGG;AACH;;GAEG;AACH;;GAEG;AACH;;GAEG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,gBAAgB,CAAgD;IACxE,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,gBAAgB,CAAyB;;IAOjD;;OAEG;IACH,kBAAkB,CAAC,WAAW,EAAE,sBAAsB,GAAG,IAAI;IA4C7D;;OAEG;IACH,kBAAkB,IAAI,sBAAsB;IAI5C;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAQlD;;OAEG;IACH,mBAAmB,IAAI,oBAAoB,EAAE;IAI7C;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;OAEG;IACH,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE;YACR,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC;KACE,GACL,oBAAoB,CAAC,QAAQ,CAAC;IA4BjC;;OAEG;IACH,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,oBAAoB,CAAC;QAC9B,OAAO,CAAC,EAAE;YACR,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC;KACH,GACA,MAAM,IAAI;IAgEb;;OAEG;IACH,gBAAgB,IAAI,oBAAoB,GAAG,IAAI;IAiC/C;;OAEG;IACH,yBAAyB,IAAI,IAAI;IAoBjC;;OAEG;IACH,0BAA0B,IAAI,IAAI;IAQlC;;OAEG;IACH,kBAAkB,IAAI,iBAAiB,EAAE;IAIzC;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAO3B;;OAEG;IACH,QAAQ,IAAI;QACV,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,sBAAsB,CAAC;QACxC,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,iBAAiB,EAAE,OAAO,CAAC;KAC5B;IAUD;;OAEG;IACH,eAAe,IAAI,MAAM,GAAG,SAAS;IAIrC;;OAEG;IACH,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUhD;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,iBAAiB,CACf,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE;YACR,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC;KACE,GACL,oBAAoB,CAAC,QAAQ,CAAC;IAMjC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkC/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAchC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAoBnC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgB/B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAkBnC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;OAEG;IACH,OAAO,CAAC,cAAc;CAUvB;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,6BAAoC,CAAC;AAEtE;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,MAAM,IAAI,CASZ;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,oBAAoB,CAAC,QAAQ,CAAC,GAAG,IAAI,CAUjF"}

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

@@ -0,0 +1,171 @@
+/**
+ * Platform Detection Utilities
+ * Comprehensive utilities for detecting platform, device, and browser information
+ * These utilities provide detailed information about the user's environment
+ */
+import type { PlatformInfo, AppInfo, DeviceInfo } from '@plyaz/types/api';
+export declare function detectOS(userAgent?: string): PlatformInfo['os'];
+export declare function detectRuntime(userAgent?: string): PlatformInfo['runtime'];
+/**
+ * Detect device type from user agent
+ *
+ * @param userAgent - User agent string or empty string
+ * @returns Device type identifier
+ */
+export declare function detectDeviceType(userAgent?: string): PlatformInfo['deviceType'];
+/**
+ * Check if device is mobile
+ *
+ * @param userAgent - User agent string or empty string
+ * @returns True if mobile device
+ */
+export declare function detectIsMobile(userAgent?: string): boolean;
+/**
+ * Check if device has touch support
+ *
+ * @returns True if touch is supported
+ */
+export declare function detectIsTouch(): boolean;
+/**
+ * Detect screen size category
+ *
+ * @returns Screen size category
+ */
+export declare function detectScreenSize(): PlatformInfo['screenSize'];
+/**
+ * Generate a browser fingerprint for device identification
+ * Creates a semi-unique identifier based on browser characteristics
+ *
+ * @returns Fingerprint string
+ */
+export declare function generateBrowserFingerprint(): string;
+/**
+ * Get user agent string safely
+ *
+ * @returns User agent string or empty string
+ */
+export declare function getUserAgent(): string;
+/**
+ * Detect current platform information
+ * Works in both browser and Node.js environments
+ *
+ * @returns Platform detection results
+ *
+ * @example
+ * ```typescript
+ * const platform = detectPlatform();
+ * console.log(`Running on ${platform.os} with ${platform.runtime}`);
+ * ```
+ */
+export declare function detectPlatform(): PlatformInfo;
+/**
+ * Get application version information
+ * Detects version from environment variables and package.json
+ *
+ * @returns Application version information
+ *
+ * @example
+ * ```typescript
+ * const app = getAppVersion();
+ * console.log(`Version: ${app.version} (${app.environment})`);
+ * ```
+ */
+export declare function getAppVersion(): AppInfo;
+export declare function getDeviceId(): string;
+/**
+ * Get comprehensive device information
+ * Combines platform, screen, and system information
+ *
+ * @returns Device information object
+ *
+ * @example
+ * ```typescript
+ * const device = getDeviceInfo();
+ * console.log(`Device ${device.id} on ${device.platform.os}`);
+ * ```
+ */
+export declare function getDeviceInfo(): DeviceInfo;
+/**
+ * Get screen resolution
+ *
+ * @returns Screen resolution object or null
+ */
+export declare function getScreenResolution(): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Get color depth
+ *
+ * @returns Color depth in bits or null
+ */
+export declare function getColorDepth(): number | null;
+/**
+ * Get pixel ratio
+ *
+ * @returns Device pixel ratio or 1
+ */
+export declare function getPixelRatio(): number;
+/**
+ * Get browser language
+ *
+ * @returns Browser language code or empty string
+ */
+export declare function getBrowserLanguage(): string;
+/**
+ * Get browser languages
+ *
+ * @returns Array of language codes
+ */
+export declare function getBrowserLanguages(): readonly string[];
+/**
+ * Check if cookies are enabled
+ *
+ * @returns True if cookies are enabled
+ */
+export declare function areCookiesEnabled(): boolean;
+/**
+ * Check if Do Not Track is enabled
+ *
+ * @returns True if DNT is enabled
+ */
+export declare function isDoNotTrackEnabled(): boolean;
+/**
+ * Get timezone offset in minutes
+ *
+ * @returns Timezone offset in minutes
+ */
+export declare function getTimezoneOffset(): number;
+/**
+ * Get timezone name
+ *
+ * @returns Timezone name
+ */
+export declare function getTimezoneName(): string;
+/**
+ * Export all utilities as a namespace for convenience
+ */
+export declare const Platform: {
+    readonly detectOS: typeof detectOS;
+    readonly detectRuntime: typeof detectRuntime;
+    readonly detectDeviceType: typeof detectDeviceType;
+    readonly detectIsMobile: typeof detectIsMobile;
+    readonly detectIsTouch: typeof detectIsTouch;
+    readonly detectScreenSize: typeof detectScreenSize;
+    readonly detectPlatform: typeof detectPlatform;
+    readonly generateBrowserFingerprint: typeof generateBrowserFingerprint;
+    readonly getUserAgent: typeof getUserAgent;
+    readonly getAppVersion: typeof getAppVersion;
+    readonly getDeviceId: typeof getDeviceId;
+    readonly getDeviceInfo: typeof getDeviceInfo;
+    readonly getScreenResolution: typeof getScreenResolution;
+    readonly getColorDepth: typeof getColorDepth;
+    readonly getPixelRatio: typeof getPixelRatio;
+    readonly getBrowserLanguage: typeof getBrowserLanguage;
+    readonly getBrowserLanguages: typeof getBrowserLanguages;
+    readonly areCookiesEnabled: typeof areCookiesEnabled;
+    readonly isDoNotTrackEnabled: typeof isDoNotTrackEnabled;
+    readonly getTimezoneOffset: typeof getTimezoneOffset;
+    readonly getTimezoneName: typeof getTimezoneName;
+};
+//# sourceMappingURL=platform.d.ts.map