@soham20/smart-offline-sdk 0.2.1 → 1.0.1

package/src/index.js

@@ -1,112 +1,510 @@
 /**
- * SmartOffline SDK
+ * SmartOffline SDK - v1.0.0
  *
- * Priority config options:
- * - frequencyThreshold: number of accesses before resource is considered "frequent" (default 3)
- * - recencyThreshold: milliseconds within which resource is considered "recent" (default 24h)
- * - maxResourceSize: max bytes to cache per resource; larger resources skipped (default Infinity)
- * - networkQuality: 'auto' | 'fast' | 'slow' — affects caching aggressiveness (default 'auto')
- * - significance: { [urlPattern]: 'high' | 'normal' | 'low' } — manual priority overrides
- * - weights: { frequency: number, recency: number, size: number } — priority weights (default all 1)
- * - customPriorityFn: (usage, url, config) => number — custom priority function (0-100)
- * - onCacheEvent: (event) => void — callback for cache events (cache, skip, serve, clear)
+ * Complete, reliable offline-first caching SDK for web applications.
+ *
+ * Usage:
+ * ```javascript
+ * import { setupSmartOffline, SmartOffline } from '@soham20/smart-offline-sdk'
+ *
+ * // Initialize early in your app
+ * await setupSmartOffline({
+ *   pages: ['/dashboard/*', '/products/*'],
+ *   apis: ['/api/v1/*'],
+ *   debug: true
+ * })
+ * ```
  */
 
+// ============================================================================
+// DEFAULT CONFIGURATION
+// ============================================================================
+
+const DEFAULT_CONFIG = {
+  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 = null;
+let currentConfig = { ...DEFAULT_CONFIG };
+
 // Event listener registry
 const eventListeners = {
   cache: [],
   skip: [],
   serve: [],
   clear: [],
-  error: []
+  error: [],
 };
 
-function init(config = {}) {
-  if (!("serviceWorker" in navigator)) {
-    console.warn("Service Workers not supported");
-    return;
-  }
-
-  const sdkConfig = {
-    pages: config.pages || [],
-    apis: config.apis || [],
-    debug: config.debug || false,
-    frequencyThreshold: config.frequencyThreshold ?? 3,
-    recencyThreshold: config.recencyThreshold ?? 24 * 60 * 60 * 1000,
-    maxResourceSize: config.maxResourceSize ?? Infinity,
-    networkQuality: config.networkQuality ?? "auto",
-    significance: config.significance ?? {},
-    
-    // New features
-    weights: {
-      frequency: config.weights?.frequency ?? 1,
-      recency: config.weights?.recency ?? 1,
-      size: config.weights?.size ?? 1
-    },
-    customPriorityFn: config.customPriorityFn ? config.customPriorityFn.toString() : null,
-    enableDetailedLogs: config.enableDetailedLogs ?? false
-  };
+// ============================================================================
+// MAIN SETUP FUNCTION
+// ============================================================================
 
-  // Register event listener if provided
-  if (config.onCacheEvent) {
-    eventListeners.cache.push(config.onCacheEvent);
-    eventListeners.skip.push(config.onCacheEvent);
-    eventListeners.serve.push(config.onCacheEvent);
-    eventListeners.clear.push(config.onCacheEvent);
-    eventListeners.error.push(config.onCacheEvent);
+/**
+ * Initialize the SmartOffline SDK with complete setup
+ * @param {Partial<SmartOfflineConfig>} config - Configuration options
+ * @returns {Promise<{success: boolean, registration?: ServiceWorkerRegistration, error?: string}>}
+ */
+export async function setupSmartOffline(config = {}) {
+  // 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 };
   }
 
-  navigator.serviceWorker.register("/smart-offline-sw.js").then((registration) => {
-    console.log("Smart Offline Service Worker registered");
+  // 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" };
+  }
 
-    // Listen for messages from SW
-    navigator.serviceWorker.addEventListener('message', (event) => {
-      if (event.data && event.data.type) {
-        const eventType = event.data.type.replace('CACHE_', '').toLowerCase();
-        const listeners = eventListeners[eventType] || [];
-        listeners.forEach(fn => fn(event.data));
-      }
+  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) {
+      printStartupBanner();
+      console.log("%c🔧 Registering service worker...", "color: #94a3b8;");
+    }
+
+    serviceWorkerRegistration = await navigator.serviceWorker.register(
+      currentConfig.serviceWorkerPath,
+      { scope: currentConfig.serviceWorkerScope },
+    );
+
+    if (currentConfig.debug) {
+      console.log(
+        "%c✓ Service worker registered", "color: #22c55e;",
+        `(scope: ${serviceWorkerRegistration.scope})`
+      );
+    }
+
+    // Wait for the service worker to be ready
+    await navigator.serviceWorker.ready;
+
+    if (currentConfig.debug) {
+      console.log("%c✓ Service worker ready", "color: #22c55e;");
+    }
+
+    // Send configuration to service worker
+    await sendConfigToServiceWorker();
+
+    // Set up event listeners
+    setupEventListenersInternal();
+
+    isInitialized = true;
+
+    if (currentConfig.debug) {
+      printConfigSummary();
+    }
+
+    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
+// ============================================================================
+
+/**
+ * Print startup banner
+ */
+function printStartupBanner() {
+  console.log(
+    `%c
+╔═══════════════════════════════════════════════════════════╗
+║                                                           ║
+║   🚀 SmartOffline SDK v1.0.0                              ║
+║   Intelligent offline-first caching                       ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+`,
+    "color: #3b82f6; font-weight: bold;"
+  );
+}
+
+/**
+ * Print configuration summary
+ */
+function printConfigSummary() {
+  console.log(
+    `%c━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+    "color: #475569;"
+  );
+  console.log(
+    `%c📋 Configuration Summary`,
+    "color: #22c55e; font-weight: bold; font-size: 14px;"
+  );
+  console.log(
+    `%c━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+    "color: #475569;"
+  );
+
+  // Pages
+  console.log("%c📄 Pages to cache:", "color: #60a5fa; font-weight: bold;");
+  if (currentConfig.pages.length > 0) {
+    currentConfig.pages.forEach((p) =>
+      console.log(`   %c• ${p}`, "color: #94a3b8;")
+    );
+  } else {
+    console.log("   %c(none)", "color: #64748b; font-style: italic;");
+  }
+
+  // APIs
+  console.log("%c🔌 APIs to cache:", "color: #60a5fa; font-weight: bold;");
+  if (currentConfig.apis.length > 0) {
+    currentConfig.apis.forEach((a) =>
+      console.log(`   %c• ${a}`, "color: #94a3b8;")
+    );
+  } else {
+    console.log("   %c(none)", "color: #64748b; font-style: italic;");
+  }
+
+  // Priority settings
+  console.log("%c⚡ Priority settings:", "color: #60a5fa; font-weight: bold;");
+  console.log(
+    `   %cFrequency threshold: ${currentConfig.frequencyThreshold} accesses`,
+    "color: #94a3b8;"
+  );
+  console.log(
+    `   %cRecency threshold: ${currentConfig.recencyThreshold / (60 * 60 * 1000)}h`,
+    "color: #94a3b8;"
+  );
+  console.log(
+    `   %cMax resource size: ${formatBytes(currentConfig.maxResourceSize)}`,
+    "color: #94a3b8;"
+  );
+  console.log(
+    `   %cNetwork quality: ${currentConfig.networkQuality}`,
+    "color: #94a3b8;"
+  );
+
+  // Significance overrides
+  const sigKeys = Object.keys(currentConfig.significance || {});
+  if (sigKeys.length > 0) {
+    console.log(
+      "%c🎯 Significance overrides:",
+      "color: #60a5fa; font-weight: bold;"
+    );
+    sigKeys.forEach((key) => {
+      const val = currentConfig.significance[key];
+      const icon = val === "high" ? "🔴" : val === "low" ? "🔵" : "⚪";
+      console.log(`   %c${icon} ${key} → ${val}`, "color: #94a3b8;");
     });
+  }
+
+  console.log(
+    `%c━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+    "color: #475569;"
+  );
+  console.log(
+    "%c✅ SmartOffline is now active! Cache events will appear below.",
+    "color: #22c55e; font-weight: bold;"
+  );
+  console.log(
+    `%c━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+    "color: #475569;"
+  );
+  console.log(""); // Empty line for spacing
+}
+
+async function sendConfigToServiceWorker() {
+  const controller = navigator.serviceWorker.controller;
+
+  if (!controller) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const reg = await navigator.serviceWorker.ready;
+    const worker = reg.active;
+
+    if (worker) {
+      sendConfigMessage(worker);
+    }
+  } else {
+    sendConfigMessage(controller);
+  }
+}
+
+function sendConfigMessage(worker) {
+  const transferableConfig = {
+    ...currentConfig,
+    customPriorityFn: currentConfig.customPriorityFn
+      ? currentConfig.customPriorityFn.toString()
+      : null,
+    onCacheEvent: undefined,
+  };
+
+  worker.postMessage({
+    type: "INIT_CONFIG",
+    payload: transferableConfig,
+  });
+
+  if (currentConfig.debug) {
+    console.log("[SmartOffline] Config sent to service worker");
+  }
+}
 
-    navigator.serviceWorker.ready.then(() => {
-      if (navigator.serviceWorker.controller) {
-        navigator.serviceWorker.controller.postMessage({
-          type: "INIT_CONFIG",
-          payload: sdkConfig,
-        });
+function setupEventListenersInternal() {
+  navigator.serviceWorker.addEventListener("message", (event) => {
+    if (event.data && typeof event.data.type === "string") {
+      if (event.data.type.startsWith("CACHE_")) {
+        const cacheEvent = {
+          type: event.data.type,
+          url: event.data.url,
+          reason: event.data.reason,
+          metadata: event.data.metadata || {},
+          timestamp: event.data.timestamp || Date.now(),
+        };
 
-        if (sdkConfig.debug) {
-          console.log("[SmartOffline] Config sent to SW:", sdkConfig);
+        // Call user callback if provided
+        if (currentConfig.onCacheEvent) {
+          currentConfig.onCacheEvent(cacheEvent);
         }
-      }
-    });
 
-    navigator.serviceWorker.addEventListener("controllerchange", () => {
-      if (navigator.serviceWorker.controller) {
-        navigator.serviceWorker.controller.postMessage({
-          type: "INIT_CONFIG",
-          payload: sdkConfig,
-        });
-
-        if (sdkConfig.debug) {
-          console.log(
-            "[SmartOffline] Config sent after controllerchange:",
-            sdkConfig,
-          );
+        // Call registered event listeners
+        const eventType = cacheEvent.type.replace("CACHE_", "").toLowerCase();
+        const listeners = eventListeners[eventType] || [];
+        listeners.forEach((fn) => fn(cacheEvent));
+
+        // Rich debug logging with colors
+        if (currentConfig.debug) {
+          logCacheEventToConsole(cacheEvent);
         }
       }
+    }
+  });
+}
+
+/**
+ * Rich console logging for cache events with colors and formatting
+ */
+function logCacheEventToConsole(cacheEvent) {
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const shortUrl = cacheEvent.url.replace(origin, "") || cacheEvent.url;
+  const time = new Date(cacheEvent.timestamp).toLocaleTimeString();
+  
+  // Style configurations for each event type
+  const styles = {
+    CACHE_INTERCEPT: {
+      icon: "🔍",
+      label: "INTERCEPT",
+      bgColor: "#6366f1",
+      textColor: "#fff",
+    },
+    CACHE_CACHE: {
+      icon: "💾",
+      label: "CACHED",
+      bgColor: "#22c55e",
+      textColor: "#fff",
+    },
+    CACHE_SKIP: {
+      icon: "⏭️",
+      label: "SKIPPED",
+      bgColor: "#f59e0b",
+      textColor: "#000",
+    },
+    CACHE_SERVE: {
+      icon: "📤",
+      label: "SERVED",
+      bgColor: "#3b82f6",
+      textColor: "#fff",
+    },
+    CACHE_ERROR: {
+      icon: "❌",
+      label: "MISS",
+      bgColor: "#ef4444",
+      textColor: "#fff",
+    },
+  };
+
+  const style = styles[cacheEvent.type] || {
+    icon: "📝",
+    label: "EVENT",
+    bgColor: "#64748b",
+    textColor: "#fff",
+  };
+
+  // Build metadata string
+  let metaInfo = "";
+  if (cacheEvent.metadata) {
+    const meta = cacheEvent.metadata;
+    const parts = [];
+    if (meta.type) parts.push(`type: ${meta.type}`);
+    if (meta.priority) parts.push(`priority: ${meta.priority}`);
+    if (meta.size) parts.push(`size: ${formatBytes(meta.size)}`);
+    if (meta.networkQuality) parts.push(`network: ${meta.networkQuality}`);
+    if (meta.isPage !== undefined) parts.push(meta.isPage ? "PAGE" : "API");
+    if (parts.length > 0) metaInfo = ` [${parts.join(", ")}]`;
+  }
+
+  // Reason badge
+  const reasonText = cacheEvent.reason ? ` → ${formatReason(cacheEvent.reason)}` : "";
+
+  // Log with styling
+  console.log(
+    `%c ${style.icon} SmartOffline %c ${style.label} %c ${time} %c ${shortUrl}${reasonText}${metaInfo}`,
+    `background: #1e293b; color: #fff; padding: 2px 6px; border-radius: 3px 0 0 3px; font-weight: bold;`,
+    `background: ${style.bgColor}; color: ${style.textColor}; padding: 2px 8px; font-weight: bold;`,
+    `background: #334155; color: #94a3b8; padding: 2px 6px;`,
+    `background: transparent; color: #e2e8f0; padding: 2px 6px;`
+  );
+
+  // For cached items, show additional details in a group
+  if (cacheEvent.type === "CACHE_CACHE" && cacheEvent.metadata) {
+    console.groupCollapsed(`   ↳ Details for ${shortUrl}`);
+    console.table({
+      URL: shortUrl,
+      Type: cacheEvent.metadata.type || "unknown",
+      Priority: cacheEvent.metadata.priority || "normal",
+      Size: cacheEvent.metadata.size ? formatBytes(cacheEvent.metadata.size) : "unknown",
+      Timestamp: new Date(cacheEvent.timestamp).toISOString(),
+    });
+    console.groupEnd();
+  }
+
+  // For serve events, show usage data if available
+  if (cacheEvent.type === "CACHE_SERVE" && cacheEvent.metadata?.usage) {
+    console.groupCollapsed(`   ↳ Usage data for ${shortUrl}`);
+    console.table({
+      "Access Count": cacheEvent.metadata.usage.count,
+      "Last Accessed": new Date(cacheEvent.metadata.usage.lastAccessed).toISOString(),
+      Priority: cacheEvent.metadata.priority || "normal",
     });
+    console.groupEnd();
+  }
+}
+
+/**
+ * Format bytes to human readable string
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+
+/**
+ * Format reason string to be more readable
+ */
+function formatReason(reason) {
+  return reason
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (l) => l.toUpperCase());
+}
+
+function openDB(name, version) {
+  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);
   });
 }
 
-// API for managing event listeners
-function on(eventType, callback) {
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+/**
+ * Update configuration at runtime
+ * @param {Partial<SmartOfflineConfig>} newConfig
+ */
+export async function updateConfig(newConfig) {
+  currentConfig = { ...currentConfig, ...newConfig };
+  await sendConfigToServiceWorker();
+}
+
+/**
+ * Get current configuration
+ * @returns {SmartOfflineConfig}
+ */
+export function getConfig() {
+  return { ...currentConfig };
+}
+
+/**
+ * Check if SDK is initialized
+ * @returns {boolean}
+ */
+export function isSmartOfflineReady() {
+  return isInitialized;
+}
+
+/**
+ * Get service worker registration
+ * @returns {ServiceWorkerRegistration | null}
+ */
+export function getServiceWorkerRegistration() {
+  return serviceWorkerRegistration;
+}
+
+/**
+ * Add event listener for cache events
+ * @param {'cache' | 'skip' | 'serve' | 'clear' | 'error'} eventType
+ * @param {(event: CacheEvent) => void} callback
+ */
+export function on(eventType, callback) {
   if (eventListeners[eventType]) {
     eventListeners[eventType].push(callback);
   }
 }
 
-function off(eventType, callback) {
+/**
+ * Remove event listener for cache events
+ * @param {'cache' | 'skip' | 'serve' | 'clear' | 'error'} eventType
+ * @param {(event: CacheEvent) => void} callback
+ */
+export function off(eventType, callback) {
   if (eventListeners[eventType]) {
     const index = eventListeners[eventType].indexOf(callback);
     if (index > -1) {
@@ -115,66 +513,528 @@ function off(eventType, callback) {
   }
 }
 
-// API to get cache logs
-async function getCacheLogs() {
-  const db = await openDB('smart-offline-logs', 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([]);
-  });
+/**
+ * Get cache logs from IndexedDB
+ * @returns {Promise<CacheLog[]>}
+ */
+export async function getCacheLogs() {
+  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 [];
+  }
 }
 
-// API to clear cache logs
-async function clearCacheLogs() {
-  const db = await openDB('smart-offline-logs', 1);
-  const tx = db.transaction('logs', 'readwrite');
-  const store = tx.objectStore('logs');
-  store.clear();
+/**
+ * Clear cache logs from IndexedDB
+ */
+export async function clearCacheLogs() {
+  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
+  }
 }
 
-// API to clear all caches
-async function clearCache() {
+/**
+ * Clear all cached data
+ */
+export async function clearAllCache() {
   const cacheNames = await caches.keys();
-  const smartOfflineCaches = cacheNames.filter(name => name.includes('smart-offline'));
-  await Promise.all(smartOfflineCaches.map(name => caches.delete(name)));
-  
-  // Also clear usage tracking database
-  const db = await openDB('smart-offline', 1);
-  const tx = db.transaction('usage', 'readwrite');
-  const store = tx.objectStore('usage');
-  store.clear();
-  
-  console.log('🗑️ All SmartOffline caches and usage data cleared');
+  for (const name of cacheNames) {
+    if (name.startsWith("smart-offline")) {
+      await caches.delete(name);
+    }
+  }
+
+  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");
+  }
 }
 
-function openDB(name, version) {
-  return new Promise((resolve, reject) => {
-    const request = indexedDB.open(name, version);
-    request.onupgradeneeded = () => {
-      const db = request.result;
-      if (name === 'smart-offline-logs' && !db.objectStoreNames.contains('logs')) {
-        db.createObjectStore('logs', { autoIncrement: true });
+/**
+ * Get cache statistics
+ * @returns {Promise<{cachedItems: number, trackedUrls: number, cacheSize: number}>}
+ */
+export async function getCacheStats() {
+  let cachedItems = 0;
+  let cacheSize = 0;
+  let trackedUrls = 0;
+
+  try {
+    const cache = await caches.open("smart-offline-cache-v2");
+    const keys = await cache.keys();
+    cachedItems = keys.length;
+
+    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 {
+    const count = await new Promise((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() {
+  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() {
+  if (serviceWorkerRegistration) {
+    await serviceWorkerRegistration.unregister();
+  }
+  await clearAllCache();
+  isInitialized = false;
+  serviceWorkerRegistration = null;
+
+  if (currentConfig.debug) {
+    console.log("[SmartOffline] Uninstalled and cleaned up");
+  }
+}
+
+/**
+ * Initialize the SDK (legacy API)
+ * @deprecated Use setupSmartOffline() instead
+ * @param {Partial<SmartOfflineConfig>} config
+ */
+export function init(config = {}) {
+  setupSmartOffline(config);
+}
+
+// ============================================================================
+// TEST UTILITIES
+// ============================================================================
+
+/**
+ * Matches URL against wildcard pattern
+ * @param {string} url
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+export function matchesPattern(url, pattern) {
+  if (!pattern.includes("*")) {
+    return url.includes(pattern);
+  }
+  const regexPattern = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*");
+  return new RegExp(regexPattern).test(url);
+}
+
+/**
+ * Calculates if a URL should be treated as HIGH priority
+ * @param {{ url: string; count: number; lastAccessed: number } | null} usage
+ * @param {string} url
+ * @param {Partial<SmartOfflineConfig>} config
+ * @returns {boolean}
+ */
+export function isHighPriority(usage, url, config = {}) {
+  const finalConfig = { ...DEFAULT_CONFIG, ...config };
+
+  if (
+    finalConfig.customPriorityFn &&
+    typeof finalConfig.customPriorityFn === "function"
+  ) {
+    try {
+      return finalConfig.customPriorityFn(usage, url, finalConfig) > 50;
+    } catch (e) {
+      console.error("Custom priority function error:", e);
+    }
+  }
+
+  for (const pattern in finalConfig.significance) {
+    if (url.includes(pattern)) {
+      if (finalConfig.significance[pattern] === "high") return true;
+      if (finalConfig.significance[pattern] === "low") return false;
+    }
+  }
+
+  if (!usage) return false;
+
+  const weights = finalConfig.weights || { frequency: 1, recency: 1, size: 1 };
+  const frequencyScore = Math.min(
+    100,
+    (usage.count / finalConfig.frequencyThreshold) * 100,
+  );
+  const timeSinceAccess = Date.now() - usage.lastAccessed;
+  const recencyScore = Math.max(
+    0,
+    100 - (timeSinceAccess / finalConfig.recencyThreshold) * 100,
+  );
+  const totalWeight = weights.frequency + weights.recency;
+  const weightedScore =
+    (frequencyScore * weights.frequency + recencyScore * weights.recency) /
+    totalWeight;
+
+  return weightedScore > 50;
+}
+
+/**
+ * Determines if a URL should be cached based on pattern matching
+ * @param {string} url
+ * @param {Partial<SmartOfflineConfig>} config
+ * @returns {{ isPage: boolean; isAPI: boolean }}
+ */
+export function shouldCacheUrl(url, config = {}) {
+  const pages = config.pages || [];
+  const apis = config.apis || [];
+  const isPage = pages.some((p) => matchesPattern(url, p));
+  const isAPI = apis.some((a) => matchesPattern(url, a));
+  return { isPage, isAPI };
+}
+
+/**
+ * Test suite class for SmartOffline SDK
+ */
+export class SmartOfflineTestSuite {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.results = [];
+  }
+
+  async runAll() {
+    this.results = [];
+    this.testPatternMatching();
+    this.testFrequencyPriority();
+    this.testRecencyPriority();
+
+    if (typeof navigator !== "undefined" && "serviceWorker" in navigator) {
+      await this.testServiceWorkerActive();
+      await this.testCacheAPIAvailable();
+    }
+
+    return this.results;
+  }
+
+  testPatternMatching() {
+    const tests = [
+      { url: "/admin/charts", pattern: "/admin/charts", expected: true },
+      { url: "/admin/charts/123", pattern: "/admin/charts/*", expected: true },
+      { url: "/grapher/gdp", pattern: "/grapher/*", expected: true },
+      { url: "/random", pattern: "/admin/*", expected: false },
+    ];
+
+    let passed = true;
+    let message = "All patterns matched correctly";
+
+    for (const test of tests) {
+      const result = matchesPattern(test.url, test.pattern);
+      if (result !== test.expected) {
+        passed = false;
+        message = `Pattern ${test.pattern} failed for ${test.url}`;
+        break;
       }
-      if (name === 'smart-offline' && !db.objectStoreNames.contains('usage')) {
-        db.createObjectStore('usage', { keyPath: 'url' });
+    }
+
+    this.results.push({ name: "Pattern Matching", passed, message });
+  }
+
+  testFrequencyPriority() {
+    const highUsage = { url: "/test", count: 5, lastAccessed: Date.now() };
+    const lowUsage = {
+      url: "/test",
+      count: 1,
+      lastAccessed: Date.now() - 25 * 60 * 60 * 1000,
+    };
+
+    const highResult = isHighPriority(highUsage, "/test", this.config);
+    const lowResult = isHighPriority(lowUsage, "/test", this.config);
+
+    this.results.push({
+      name: "Frequency Priority",
+      passed: highResult === true && lowResult === false,
+      message:
+        highResult === true && lowResult === false
+          ? "High frequency URLs correctly prioritized"
+          : `Expected high:true, low:false but got high:${highResult}, low:${lowResult}`,
+    });
+  }
+
+  testRecencyPriority() {
+    const recentUsage = {
+      url: "/test",
+      count: 1,
+      lastAccessed: Date.now() - 1000,
+    };
+    const oldUsage = {
+      url: "/test",
+      count: 1,
+      lastAccessed: Date.now() - 48 * 60 * 60 * 1000,
+    };
+
+    const recentResult = isHighPriority(recentUsage, "/test", this.config);
+    const oldResult = isHighPriority(oldUsage, "/test", this.config);
+
+    this.results.push({
+      name: "Recency Priority",
+      passed: recentResult === true && oldResult === false,
+      message:
+        recentResult === true && oldResult === false
+          ? "Recent URLs correctly prioritized"
+          : `Expected recent:true, old:false but got recent:${recentResult}, old:${oldResult}`,
+    });
+  }
+
+  async testServiceWorkerActive() {
+    try {
+      const registration = await navigator.serviceWorker.getRegistration();
+      const passed = !!registration?.active;
+
+      this.results.push({
+        name: "Service Worker Active",
+        passed,
+        message: passed
+          ? `Service worker active at scope: ${registration?.scope}`
+          : "No active service worker found",
+      });
+    } catch (e) {
+      this.results.push({
+        name: "Service Worker Active",
+        passed: false,
+        message: `Error: ${e}`,
+      });
+    }
+  }
+
+  async testCacheAPIAvailable() {
+    try {
+      const cache = await caches.open("smart-offline-test");
+      await caches.delete("smart-offline-test");
+      this.results.push({
+        name: "Cache API Available",
+        passed: true,
+        message: "Cache API is accessible",
+      });
+    } catch (e) {
+      this.results.push({
+        name: "Cache API Available",
+        passed: false,
+        message: `Error: ${e}`,
+      });
+    }
+  }
+
+  printResults() {
+    console.info("\n========================================");
+    console.info("  SmartOffline SDK Test Results");
+    console.info("========================================\n");
+
+    for (const result of this.results) {
+      console.info(`${result.passed ? "✅" : "❌"} ${result.name}`);
+      console.info(`   ${result.message}\n`);
+    }
+
+    const passed = this.results.filter((r) => r.passed).length;
+    console.info("----------------------------------------");
+    console.info(`Total: ${passed}/${this.results.length} tests passed`);
+    console.info("========================================\n");
+  }
+}
+
+/**
+ * Cache inspector for debugging
+ */
+export class CacheInspector {
+  async getCachedItems() {
+    try {
+      const cache = await caches.open("smart-offline-cache-v2");
+      const keys = await cache.keys();
+      const items = [];
+      for (const request of keys) {
+        const response = await cache.match(request);
+        if (response) {
+          items.push({
+            url: request.url,
+            size: parseInt(response.headers.get("content-length") || "0", 10),
+            contentType: response.headers.get("content-type") || "unknown",
+          });
+        }
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
+
+  async getUsageData() {
+    return new Promise((resolve) => {
+      try {
+        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 getAllReq = store.getAll();
+            getAllReq.onsuccess = () => resolve(getAllReq.result || []);
+            getAllReq.onerror = () => resolve([]);
+          } catch {
+            resolve([]);
+          }
+        };
+        request.onerror = () => resolve([]);
+      } catch {
+        resolve([]);
       }
+    });
+  }
+
+  async getLogs() {
+    return new Promise((resolve) => {
+      try {
+        const request = indexedDB.open("smart-offline-logs-v2", 1);
+        request.onsuccess = () => {
+          const db = request.result;
+          try {
+            const tx = db.transaction("logs", "readonly");
+            const store = tx.objectStore("logs");
+            const getAllReq = store.getAll();
+            getAllReq.onsuccess = () => resolve(getAllReq.result || []);
+            getAllReq.onerror = () => resolve([]);
+          } catch {
+            resolve([]);
+          }
+        };
+        request.onerror = () => resolve([]);
+      } catch {
+        resolve([]);
+      }
+    });
+  }
+
+  async showAll() {
+    console.info("\n🔍 SmartOffline Cache Inspector\n");
+
+    const cachedItems = await this.getCachedItems();
+    console.info(`📦 Cached Items (${cachedItems.length}):`);
+    console.table(cachedItems);
+
+    const usageData = await this.getUsageData();
+    console.info(`\n📊 Usage Tracking (${usageData.length} URLs):`);
+    console.table(
+      usageData.map((u) => ({
+        url: u.url.replace(window.location.origin, ""),
+        count: u.count,
+        lastAccessed: new Date(u.lastAccessed).toLocaleString(),
+      })),
+    );
+
+    const logs = await this.getLogs();
+    console.info(`\n📝 Recent Logs (${logs.length}):`);
+    console.table(logs.slice(-20));
+  }
+
+  async getAllData() {
+    return {
+      cachedItems: await this.getCachedItems(),
+      usageData: await this.getUsageData(),
+      logs: await this.getLogs(),
     };
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () => reject(request.error);
-  });
+  }
 }
 
-const SmartOffline = { 
-  init, 
-  on, 
-  off, 
-  getCacheLogs, 
+/**
+ * Run all SmartOffline tests and print results
+ * @param {Partial<SmartOfflineConfig>} config
+ * @returns {Promise<TestResult[]>}
+ */
+export async function runSmartOfflineTests(config) {
+  const suite = new SmartOfflineTestSuite(config);
+  const results = await suite.runAll();
+  suite.printResults();
+  return results;
+}
+
+// ============================================================================
+// MAIN EXPORT OBJECT
+// ============================================================================
+
+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,
-  clearCache
+
+  // Lifecycle
+  forceUpdate,
+  uninstall,
 };
 
-export { SmartOffline }; // ✅ named export
-export default SmartOffline; // ✅ default export
+export default SmartOffline;