@soham20/smart-offline-sdk 0.2.1 → 1.0.1

package/src/SmartOfflineSetup.ts

@@ -0,0 +1,658 @@
+/**
+ * SmartOffline SDK - Complete Setup & Configuration
+ *
+ * This file provides a complete, reliable implementation of the SmartOffline SDK
+ * for offline-first caching. Import and call `setupSmartOffline()` early in your
+ * application entry point.
+ *
+ * Usage:
+ * ```typescript
+ * import { setupSmartOffline } from '@soham20/smart-offline-sdk'
+ *
+ * // Call this early in your app initialization
+ * await setupSmartOffline()
+ * ```
+ */
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+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 Infinity
+   */
+  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;
+  };
+
+  /**
+   * Custom function to calculate priority (0-100)
+   * If provided, overrides the default algorithm
+   */
+  customPriorityFn:
+    | ((
+        usage: { url: string; count: number; lastAccessed: number } | 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;
+}
+
+export interface CacheEvent {
+  type: "CACHE_CACHE" | "CACHE_SKIP" | "CACHE_SERVE" | "CACHE_ERROR";
+  url: string;
+  reason: string;
+  metadata: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface UsageData {
+  url: string;
+  count: number;
+  lastAccessed: number;
+}
+
+export interface CacheLog {
+  type: string;
+  url: string;
+  reason: string;
+  metadata?: Record<string, unknown>;
+  timestamp: number;
+  date: string;
+}
+
+export interface SetupResult {
+  success: boolean;
+  registration?: ServiceWorkerRegistration;
+  error?: string;
+}
+
+export interface CacheStats {
+  cachedItems: number;
+  trackedUrls: number;
+  cacheSize: number;
+}
+
+// ============================================================================
+// DEFAULT CONFIGURATION
+// ============================================================================
+
+const DEFAULT_CONFIG: SmartOfflineConfig = {
+  pages: [],
+  apis: [],
+  debug:
+    typeof process !== "undefined" && process.env?.NODE_ENV !== "production",
+  frequencyThreshold: 3,
+  recencyThreshold: 24 * 60 * 60 * 1000, // 24 hours
+  maxResourceSize: 10 * 1024 * 1024, // 10MB
+  networkQuality: "auto",
+  significance: {},
+  weights: { frequency: 1, recency: 1, size: 1 },
+  customPriorityFn: null,
+  enableDetailedLogs: false,
+  serviceWorkerPath: "/smart-offline-sw.js",
+  serviceWorkerScope: "/",
+};
+
+// ============================================================================
+// STATE
+// ============================================================================
+
+let isInitialized = false;
+let serviceWorkerRegistration: ServiceWorkerRegistration | null = null;
+let currentConfig: SmartOfflineConfig = { ...DEFAULT_CONFIG };
+
+// Event listener registry
+const eventListeners: Record<string, Array<(event: CacheEvent) => void>> = {
+  cache: [],
+  skip: [],
+  serve: [],
+  clear: [],
+  error: [],
+};
+
+// ============================================================================
+// MAIN SETUP FUNCTION
+// ============================================================================
+
+/**
+ * Initialize the SmartOffline SDK with complete setup
+ *
+ * This function:
+ * 1. Checks browser support
+ * 2. Registers the service worker
+ * 3. Sends configuration to the service worker
+ * 4. Sets up event listeners
+ *
+ * @param config - Partial configuration (merged with defaults)
+ * @returns Promise that resolves when setup is complete
+ */
+export async function setupSmartOffline(
+  config: Partial<SmartOfflineConfig> = {},
+): Promise<SetupResult> {
+  // Merge with defaults
+  currentConfig = { ...DEFAULT_CONFIG, ...config };
+
+  // Check if already initialized
+  if (isInitialized) {
+    if (currentConfig.debug) {
+      console.warn("[SmartOffline] Already initialized, updating config...");
+    }
+    await sendConfigToServiceWorker();
+    return { success: true, registration: serviceWorkerRegistration! };
+  }
+
+  // Check browser support
+  if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
+    console.error(
+      "[SmartOffline] Service Workers not supported in this browser",
+    );
+    return { success: false, error: "Service Workers not supported" };
+  }
+
+  if (typeof window === "undefined" || !("caches" in window)) {
+    console.error("[SmartOffline] Cache API not supported in this browser");
+    return { success: false, error: "Cache API not supported" };
+  }
+
+  try {
+    // Register service worker
+    if (currentConfig.debug) {
+      console.log("[SmartOffline] Registering service worker...");
+    }
+
+    serviceWorkerRegistration = await navigator.serviceWorker.register(
+      currentConfig.serviceWorkerPath,
+      { scope: currentConfig.serviceWorkerScope },
+    );
+
+    if (currentConfig.debug) {
+      console.log(
+        "[SmartOffline] Service worker registered:",
+        serviceWorkerRegistration.scope,
+      );
+    }
+
+    // Wait for the service worker to be ready
+    await navigator.serviceWorker.ready;
+
+    if (currentConfig.debug) {
+      console.log("[SmartOffline] Service worker ready");
+    }
+
+    // Send configuration to service worker
+    await sendConfigToServiceWorker();
+
+    // Set up event listeners
+    setupEventListeners();
+
+    isInitialized = true;
+
+    if (currentConfig.debug) {
+      console.log("[SmartOffline] Setup complete! Configuration:", {
+        pages: currentConfig.pages,
+        apis: currentConfig.apis,
+        frequencyThreshold: currentConfig.frequencyThreshold,
+        recencyThreshold: `${currentConfig.recencyThreshold / (60 * 60 * 1000)}h`,
+      });
+    }
+
+    return { success: true, registration: serviceWorkerRegistration };
+  } catch (error) {
+    console.error("[SmartOffline] Setup failed:", error);
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Send configuration to the active service worker
+ */
+async function sendConfigToServiceWorker(): Promise<void> {
+  const controller = navigator.serviceWorker.controller;
+
+  if (!controller) {
+    // No controller yet, wait a bit and retry
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const reg = await navigator.serviceWorker.ready;
+    const worker = reg.active;
+
+    if (worker) {
+      sendConfigMessage(worker);
+    }
+  } else {
+    sendConfigMessage(controller);
+  }
+}
+
+/**
+ * Send the config message to a service worker
+ */
+function sendConfigMessage(worker: ServiceWorker): void {
+  // Prepare config for transfer (can't send functions directly)
+  const transferableConfig = {
+    ...currentConfig,
+    customPriorityFn: currentConfig.customPriorityFn
+      ? currentConfig.customPriorityFn.toString()
+      : null,
+    // Don't send non-serializable properties
+    onCacheEvent: undefined,
+  };
+
+  worker.postMessage({
+    type: "INIT_CONFIG",
+    payload: transferableConfig,
+  });
+
+  if (currentConfig.debug) {
+    console.log("[SmartOffline] Config sent to service worker");
+  }
+}
+
+/**
+ * Set up event listeners for cache events
+ */
+function setupEventListeners(): void {
+  navigator.serviceWorker.addEventListener("message", (event) => {
+    if (event.data && typeof event.data.type === "string") {
+      if (event.data.type.startsWith("CACHE_")) {
+        const cacheEvent: CacheEvent = {
+          type: event.data.type,
+          url: event.data.url,
+          reason: event.data.reason,
+          metadata: event.data.metadata || {},
+          timestamp: event.data.timestamp || Date.now(),
+        };
+
+        // Call user callback if provided
+        if (currentConfig.onCacheEvent) {
+          currentConfig.onCacheEvent(cacheEvent);
+        }
+
+        // Call registered event listeners
+        const eventType = cacheEvent.type.replace("CACHE_", "").toLowerCase();
+        const listeners = eventListeners[eventType] || [];
+        listeners.forEach((fn) => fn(cacheEvent));
+
+        // Debug logging
+        if (currentConfig.debug) {
+          const icon: Record<string, string> = {
+            CACHE_CACHE: "💾",
+            CACHE_SKIP: "⏭️",
+            CACHE_SERVE: "📤",
+            CACHE_ERROR: "❌",
+          };
+
+          console.log(
+            `[SmartOffline] ${icon[cacheEvent.type] || "📝"} ${cacheEvent.type.replace("CACHE_", "")}:`,
+            cacheEvent.url.replace(
+              typeof window !== "undefined" ? window.location.origin : "",
+              "",
+            ),
+            `(${cacheEvent.reason})`,
+          );
+        }
+      }
+    }
+  });
+}
+
+/**
+ * Open IndexedDB database
+ */
+function openDB(name: string, version: number): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(name, version);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (
+        name === "smart-offline-logs-v2" &&
+        !db.objectStoreNames.contains("logs")
+      ) {
+        db.createObjectStore("logs", { autoIncrement: true });
+      }
+      if (
+        name === "smart-offline-usage-v2" &&
+        !db.objectStoreNames.contains("usage")
+      ) {
+        db.createObjectStore("usage", { keyPath: "url" });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+/**
+ * Update configuration at runtime
+ */
+export async function updateConfig(
+  newConfig: Partial<SmartOfflineConfig>,
+): Promise<void> {
+  currentConfig = { ...currentConfig, ...newConfig };
+  await sendConfigToServiceWorker();
+}
+
+/**
+ * Get current configuration
+ */
+export function getConfig(): SmartOfflineConfig {
+  return { ...currentConfig };
+}
+
+/**
+ * Check if SDK is initialized
+ */
+export function isSmartOfflineReady(): boolean {
+  return isInitialized;
+}
+
+/**
+ * Get service worker registration
+ */
+export function getServiceWorkerRegistration(): ServiceWorkerRegistration | null {
+  return serviceWorkerRegistration;
+}
+
+/**
+ * Add event listener for cache events
+ */
+export function on(
+  eventType: "cache" | "skip" | "serve" | "clear" | "error",
+  callback: (event: CacheEvent) => void,
+): void {
+  if (eventListeners[eventType]) {
+    eventListeners[eventType].push(callback);
+  }
+}
+
+/**
+ * Remove event listener for cache events
+ */
+export function off(
+  eventType: "cache" | "skip" | "serve" | "clear" | "error",
+  callback: (event: CacheEvent) => void,
+): void {
+  if (eventListeners[eventType]) {
+    const index = eventListeners[eventType].indexOf(callback);
+    if (index > -1) {
+      eventListeners[eventType].splice(index, 1);
+    }
+  }
+}
+
+/**
+ * Get cache logs from IndexedDB
+ */
+export async function getCacheLogs(): Promise<CacheLog[]> {
+  try {
+    const db = await openDB("smart-offline-logs-v2", 1);
+    const tx = db.transaction("logs", "readonly");
+    const store = tx.objectStore("logs");
+    return new Promise((resolve) => {
+      const request = store.getAll();
+      request.onsuccess = () => resolve(request.result || []);
+      request.onerror = () => resolve([]);
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Clear cache logs from IndexedDB
+ */
+export async function clearCacheLogs(): Promise<void> {
+  try {
+    const db = await openDB("smart-offline-logs-v2", 1);
+    const tx = db.transaction("logs", "readwrite");
+    const store = tx.objectStore("logs");
+    store.clear();
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Clear all cached data
+ */
+export async function clearAllCache(): Promise<void> {
+  // Clear Cache Storage
+  const cacheNames = await caches.keys();
+  for (const name of cacheNames) {
+    if (name.startsWith("smart-offline")) {
+      await caches.delete(name);
+    }
+  }
+
+  // Clear IndexedDB
+  const dbNames = ["smart-offline-usage-v2", "smart-offline-logs-v2"];
+  for (const dbName of dbNames) {
+    try {
+      indexedDB.deleteDatabase(dbName);
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  if (currentConfig.debug) {
+    console.log("[SmartOffline] All cache data cleared");
+  }
+}
+
+/**
+ * Get cache statistics
+ */
+export async function getCacheStats(): Promise<CacheStats> {
+  let cachedItems = 0;
+  let cacheSize = 0;
+  let trackedUrls = 0;
+
+  try {
+    // Count cached items
+    const cache = await caches.open("smart-offline-cache-v2");
+    const keys = await cache.keys();
+    cachedItems = keys.length;
+
+    // Estimate cache size
+    for (const request of keys) {
+      const response = await cache.match(request);
+      if (response) {
+        const size = parseInt(
+          response.headers.get("content-length") || "0",
+          10,
+        );
+        cacheSize += size;
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  try {
+    // Count tracked URLs from IndexedDB
+    const count = await new Promise<number>((resolve) => {
+      const request = indexedDB.open("smart-offline-usage-v2", 1);
+      request.onsuccess = () => {
+        const db = request.result;
+        try {
+          const tx = db.transaction("usage", "readonly");
+          const store = tx.objectStore("usage");
+          const countReq = store.count();
+          countReq.onsuccess = () => resolve(countReq.result);
+          countReq.onerror = () => resolve(0);
+        } catch {
+          resolve(0);
+        }
+      };
+      request.onerror = () => resolve(0);
+    });
+    trackedUrls = count;
+  } catch {
+    // Ignore errors
+  }
+
+  return { cachedItems, trackedUrls, cacheSize };
+}
+
+/**
+ * Force update the service worker
+ */
+export async function forceUpdate(): Promise<void> {
+  if (serviceWorkerRegistration) {
+    await serviceWorkerRegistration.update();
+    if (currentConfig.debug) {
+      console.log("[SmartOffline] Service worker update triggered");
+    }
+  }
+}
+
+/**
+ * Unregister the service worker and clean up
+ */
+export async function uninstall(): Promise<void> {
+  if (serviceWorkerRegistration) {
+    await serviceWorkerRegistration.unregister();
+  }
+  await clearAllCache();
+  isInitialized = false;
+  serviceWorkerRegistration = null;
+
+  if (currentConfig.debug) {
+    console.log("[SmartOffline] Uninstalled and cleaned up");
+  }
+}
+
+// ============================================================================
+// LEGACY API (for backwards compatibility)
+// ============================================================================
+
+/**
+ * Initialize the SDK (legacy API, use setupSmartOffline instead)
+ * @deprecated Use setupSmartOffline() instead
+ */
+export function init(config: Partial<SmartOfflineConfig> = {}): void {
+  void setupSmartOffline(config);
+}
+
+// ============================================================================
+// EXPORT EVERYTHING
+// ============================================================================
+
+export const SmartOffline = {
+  // Main setup
+  setup: setupSmartOffline,
+  init, // Legacy API
+
+  // Configuration
+  updateConfig,
+  getConfig,
+
+  // Status
+  isReady: isSmartOfflineReady,
+  getRegistration: getServiceWorkerRegistration,
+
+  // Event handling
+  on,
+  off,
+
+  // Cache management
+  clearCache: clearAllCache,
+  getStats: getCacheStats,
+  getCacheLogs,
+  clearCacheLogs,
+
+  // Lifecycle
+  forceUpdate,
+  uninstall,
+};
+
+export default SmartOffline;