@soham20/smart-offline-sdk 0.2.1 → 1.0.0

package/src/index.d.ts

@@ -1,77 +1,345 @@
-export interface UsageData {
-  url: string;
-  count: number;
-  lastAccessed: number;
-}
+/**
+ * SmartOffline SDK - TypeScript Definitions
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// CONFIGURATION TYPES
+// ============================================================================
+
+export interface SmartOfflineConfig {
+  /**
+   * URL patterns for pages to cache (supports * wildcard)
+   * @example ['/admin/*', '/dashboard', '/products/*']
+   */
+  pages: string[];
+
+  /**
+   * URL patterns for API endpoints to cache
+   * @example ['/api/v1/*', '/graphql']
+   */
+  apis: string[];
+
+  /**
+   * Enable debug logging in console
+   * @default false in production, true in development
+   */
+  debug: boolean;
+
+  /**
+   * Number of accesses before URL is considered high priority
+   * @default 3
+   */
+  frequencyThreshold: number;
+
+  /**
+   * Time in ms within which access is considered "recent"
+   * @default 86400000 (24 hours)
+   */
+  recencyThreshold: number;
+
+  /**
+   * Maximum resource size in bytes to cache (skip larger files)
+   * @default 10485760 (10MB)
+   */
+  maxResourceSize: number;
+
+  /**
+   * Network quality detection mode
+   * - 'auto': Detect from navigator.connection
+   * - 'slow': Treat as slow network (only cache high priority)
+   * - 'fast': Treat as fast network (cache everything)
+   * @default 'auto'
+   */
+  networkQuality: "auto" | "slow" | "fast";
+
+  /**
+   * Override priority for specific URL patterns
+   * @example { '/critical/*': 'high', '/logs/*': 'low' }
+   */
+  significance: Record<string, "high" | "low">;
+
+  /**
+   * Weights for priority calculation
+   * Higher weight = more influence on final score
+   */
+  weights: {
+    frequency: number;
+    recency: number;
+    size: number;
+  };
 
-export interface CacheWeights {
-  /** Weight for frequency score (default: 1) */
-  frequency?: number;
-  /** Weight for recency score (default: 1) */
-  recency?: number;
-  /** Weight for size consideration (default: 1) */
-  size?: number;
+  /**
+   * Custom function to calculate priority (0-100)
+   * If provided, overrides the default algorithm
+   */
+  customPriorityFn:
+    | ((
+        usage: UsageData | null,
+        url: string,
+        config: SmartOfflineConfig,
+      ) => number)
+    | null;
+
+  /**
+   * Enable detailed event logging (for debugging/visualization)
+   * @default false
+   */
+  enableDetailedLogs: boolean;
+
+  /**
+   * Callback when cache events occur
+   */
+  onCacheEvent?: (event: CacheEvent) => void;
+
+  /**
+   * Path to the service worker file
+   * @default '/smart-offline-sw.js'
+   */
+  serviceWorkerPath: string;
+
+  /**
+   * Service worker scope
+   * @default '/'
+   */
+  serviceWorkerScope: string;
 }
 
+// ============================================================================
+// EVENT TYPES
+// ============================================================================
+
 export interface CacheEvent {
-  type: 'CACHE_CACHE' | 'CACHE_SKIP' | 'CACHE_SERVE' | 'CACHE_CLEAR' | 'CACHE_ERROR';
+  type: "CACHE_CACHE" | "CACHE_SKIP" | "CACHE_SERVE" | "CACHE_ERROR";
   url: string;
   reason: string;
-  metadata?: any;
+  metadata: Record<string, unknown>;
   timestamp: number;
 }
 
-export type CustomPriorityFunction = (
-  usage: UsageData | null, 
-  url: string, 
-  config: SmartOfflineConfig
-) => number; // Return 0-100, >50 is high priority
-
-export interface SmartOfflineConfig {
-  /** Array of page URL patterns to cache */
-  pages?: string[];
-  /** Array of API URL patterns to cache */
-  apis?: string[];
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Number of accesses before resource is considered "frequent" (default: 3) */
-  frequencyThreshold?: number;
-  /** Milliseconds within which resource is considered "recent" (default: 24h) */
-  recencyThreshold?: number;
-  /** Max bytes to cache per resource; larger resources skipped (default: Infinity) */
-  maxResourceSize?: number;
-  /** Network quality setting: 'auto' | 'fast' | 'slow' (default: 'auto') */
-  networkQuality?: "auto" | "fast" | "slow";
-  /** Manual priority overrides by URL pattern */
-  significance?: Record<string, "high" | "normal" | "low">;
-  /** Weights for priority calculation (default: all 1) */
-  weights?: CacheWeights;
-  /** Custom priority function for complete control */
-  customPriorityFn?: CustomPriorityFunction;
-  /** Enable detailed event logging to IndexedDB */
-  enableDetailedLogs?: boolean;
-  /** Callback for all cache events */
-  onCacheEvent?: (event: CacheEvent) => void;
+export interface UsageData {
+  url: string;
+  count: number;
+  lastAccessed: number;
 }
 
 export interface CacheLog {
   type: string;
   url: string;
   reason: string;
-  metadata?: any;
+  metadata?: Record<string, unknown>;
   timestamp: number;
   date: string;
 }
 
+// ============================================================================
+// RESULT TYPES
+// ============================================================================
+
+export interface SetupResult {
+  success: boolean;
+  registration?: ServiceWorkerRegistration;
+  error?: string;
+}
+
+export interface CacheStats {
+  cachedItems: number;
+  trackedUrls: number;
+  cacheSize: number;
+}
+
+// ============================================================================
+// TEST UTILITIES TYPES
+// ============================================================================
+
+export interface TestResult {
+  name: string;
+  passed: boolean;
+  message: string;
+  duration?: number;
+}
+
+export interface CacheInspectorData {
+  cachedItems: Array<{ url: string; size: number; contentType: string }>;
+  usageData: UsageData[];
+  logs: Array<{ type: string; url: string; timestamp: number }>;
+}
+
+// ============================================================================
+// MAIN API
+// ============================================================================
+
+/**
+ * Initialize the SmartOffline SDK with complete setup
+ */
+export declare function setupSmartOffline(
+  config?: Partial<SmartOfflineConfig>,
+): Promise<SetupResult>;
+
+/**
+ * Update configuration at runtime
+ */
+export declare function updateConfig(
+  newConfig: Partial<SmartOfflineConfig>,
+): Promise<void>;
+
+/**
+ * Get current configuration
+ */
+export declare function getConfig(): SmartOfflineConfig;
+
+/**
+ * Check if SDK is initialized
+ */
+export declare function isSmartOfflineReady(): boolean;
+
+/**
+ * Get service worker registration
+ */
+export declare function getServiceWorkerRegistration(): ServiceWorkerRegistration | null;
+
+/**
+ * Add event listener for cache events
+ */
+export declare function on(
+  eventType: "cache" | "skip" | "serve" | "clear" | "error",
+  callback: (event: CacheEvent) => void,
+): void;
+
+/**
+ * Remove event listener for cache events
+ */
+export declare function off(
+  eventType: "cache" | "skip" | "serve" | "clear" | "error",
+  callback: (event: CacheEvent) => void,
+): void;
+
+/**
+ * Get cache logs from IndexedDB
+ */
+export declare function getCacheLogs(): Promise<CacheLog[]>;
+
+/**
+ * Clear cache logs from IndexedDB
+ */
+export declare function clearCacheLogs(): Promise<void>;
+
+/**
+ * Clear all cached data
+ */
+export declare function clearAllCache(): Promise<void>;
+
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(): Promise<CacheStats>;
+
+/**
+ * Force update the service worker
+ */
+export declare function forceUpdate(): Promise<void>;
+
+/**
+ * Unregister the service worker and clean up
+ */
+export declare function uninstall(): Promise<void>;
+
+/**
+ * Initialize the SDK (legacy API)
+ * @deprecated Use setupSmartOffline() instead
+ */
+export declare function init(config?: Partial<SmartOfflineConfig>): void;
+
+// ============================================================================
+// MAIN SDK OBJECT
+// ============================================================================
+
 export interface SmartOfflineSDK {
-  init(config?: SmartOfflineConfig): void;
-  on(eventType: 'cache' | 'skip' | 'serve' | 'clear' | 'error', callback: (event: CacheEvent) => void): void;
-  off(eventType: 'cache' | 'skip' | 'serve' | 'clear' | 'error', callback: (event: CacheEvent) => void): void;
-  getCacheLogs(): Promise<CacheLog[]>;
-  clearCacheLogs(): Promise<void>;
-  clearCache(): Promise<void>;
+  /** Main setup function (recommended) */
+  setup: typeof setupSmartOffline;
+  /** Legacy init function */
+  init: typeof init;
+  /** Update configuration at runtime */
+  updateConfig: typeof updateConfig;
+  /** Get current configuration */
+  getConfig: typeof getConfig;
+  /** Check if SDK is initialized */
+  isReady: typeof isSmartOfflineReady;
+  /** Get service worker registration */
+  getRegistration: typeof getServiceWorkerRegistration;
+  /** Add event listener */
+  on: typeof on;
+  /** Remove event listener */
+  off: typeof off;
+  /** Clear all cache */
+  clearCache: typeof clearAllCache;
+  /** Get cache statistics */
+  getStats: typeof getCacheStats;
+  /** Get cache logs */
+  getCacheLogs: typeof getCacheLogs;
+  /** Clear cache logs */
+  clearCacheLogs: typeof clearCacheLogs;
+  /** Force update service worker */
+  forceUpdate: typeof forceUpdate;
+  /** Uninstall SDK */
+  uninstall: typeof uninstall;
 }
 
 export declare const SmartOffline: SmartOfflineSDK;
 export default SmartOffline;
 
+// ============================================================================
+// TEST UTILITIES
+// ============================================================================
+
+/**
+ * Matches URL against wildcard pattern
+ */
+export declare function matchesPattern(url: string, pattern: string): boolean;
+
+/**
+ * Calculates if a URL should be treated as HIGH priority
+ */
+export declare function isHighPriority(
+  usage: UsageData | null,
+  url: string,
+  config?: Partial<SmartOfflineConfig>,
+): boolean;
+
+/**
+ * Determines if a URL should be cached based on pattern matching
+ */
+export declare function shouldCacheUrl(
+  url: string,
+  config?: Partial<SmartOfflineConfig>,
+): { isPage: boolean; isAPI: boolean };
+
+/**
+ * Test suite class for SmartOffline SDK
+ */
+export declare class SmartOfflineTestSuite {
+  constructor(config?: Partial<SmartOfflineConfig>);
+  runAll(): Promise<TestResult[]>;
+  printResults(): void;
+}
+
+/**
+ * Cache inspector for debugging
+ */
+export declare class CacheInspector {
+  getCachedItems(): Promise<
+    Array<{ url: string; size: number; contentType: string }>
+  >;
+  getUsageData(): Promise<UsageData[]>;
+  getLogs(): Promise<Array<{ type: string; url: string; timestamp: number }>>;
+  showAll(): Promise<void>;
+  getAllData(): Promise<CacheInspectorData>;
+}
+
+/**
+ * Run all SmartOffline tests and print results
+ */
+export declare function runSmartOfflineTests(
+  config?: Partial<SmartOfflineConfig>,
+): Promise<TestResult[]>;