@soham20/smart-offline-sdk 0.1.1 → 0.1.2

package/PROJECT_ANALYSIS.md

@@ -0,0 +1,94 @@
+# SmartOffline SDK — Project Analysis
+
+Date: 2026-01-22
+
+---
+
+## Project Summary
+
+SmartOffline is a JavaScript SDK that enables offline-first behavior by registering a Service Worker which caches configured pages and API responses. The repository includes a demo, basic tests, and a Node-style test SDK.
+
+Key locations:
+
+- `smart-offline-sw.js` — Service Worker implementing caching, usage tracking, and priority logic.
+- `src/index.js` — Browser SDK entry (`SmartOffline.init`) that registers the SW and sends configuration.
+- `src/usageTracker.js` — IndexedDB-based usage tracker (client-side helper).
+- `src/sdk/index.js` — Small Node test client (`HackvisionClient`) used by tests/examples.
+- `demo/` — Demo page and sample API (`demo/index.html`, `demo/api/profile.json`).
+- `tests/` — `tests/basic.test.js` (Jest) covering the test client.
+
+---
+
+## Features That Work (Implemented)
+
+- Service Worker registration via `SmartOffline.init()` (browser).
+- SW intercepts `GET` requests for configured pages and APIs and caches successful network responses.
+- Offline fallback: SW serves cached responses when fetch fails.
+- Usage tracking in IndexedDB (stores `count` and `lastAccessed` per URL) implemented both in `smart-offline-sw.js` and `src/usageTracker.js`.
+- Priority determination (high/normal) based on frequency and recency thresholds.
+- Demo implementation showing SDK usage and an API example.
+- Node test client (`HackvisionClient.echo`) and unit test (`jest`) pass.
+- CI workflow exists to run tests (.github/workflows/ci.yml).
+- Package published as `@soham20/smart-offline-sdk` (v0.1.1).
+
+---
+
+## Issues & Gaps (Needs Attention)
+
+- README contains unresolved merge markers. Clean and add clear quickstarts for browser and Node.
+- `package.json` declares `"type": "commonjs"` but `src/index.js` uses ESM-style `export` (module mismatch). This may confuse Node consumers and bundlers.
+- No build/bundling step: source files are published directly. This reduces compatibility across consumers (CJS/ESM/browser UMD). No `dist/` artifacts.
+- Service Worker behavior is not covered by automated integration tests (typical but recommended to add Playwright/Puppeteer tests for offline behavior).
+- Inconsistent public API surface: demo uses `SmartOffline.init()` while package `main` points to `src/sdk/index.js` (Node test client). Clarify and add a top-level entry that documents both browser and Node exports.
+- Privacy/consent: usage tracking stores per-URL usage in IndexedDB — document privacy implications and provide opt-out.
+- No cache eviction / quota management — cache can grow without limits.
+
+---
+
+## Short-Term Recommendations (Actionable)
+
+1. Fix `README.md` (remove merge markers) and add clear Quickstart sections for browser and Node usage.
+2. Standardize module format:
+   - Option A: Build ESM + CJS bundles (Rollup) and set `main`/`module`/`exports` in `package.json`.
+   - Option B: Convert `src/index.js` to CommonJS `module.exports` if targeting Node-only.
+3. Add a build step that outputs `dist/` bundles (UMD for browsers, ESM and CJS for Node). Update `package.json` scripts (`build`, `prepublishOnly`).
+4. Add integration tests (Playwright) that:
+   - Serve demo, register SW, fetch a resource online, go offline, and verify cached response is served.
+5. Add cache size management (LRU or simple max-entries) using usage metrics in IndexedDB.
+6. Document the usage tracking behavior and add opt-out configuration (e.g., `trackUsage: false`).
+
+---
+
+## Mid/Large-Term Enhancements (Future)
+
+- Prefetching & background sync for high-priority resources.
+- Configurable stale-while-revalidate and TTL per resource.
+- TypeScript conversion + publishing type definitions.
+- Expose a small diagnostics API so apps can query cache status and usage stats.
+- Publish a UMD browser bundle and host on a CDN for direct `<script>` usage.
+- Telemetry (opt-in) and analytics for adoption + cache effectiveness metrics.
+
+---
+
+## Suggested Next Steps (I can implement)
+
+- Patch `README.md` to a clean quickstart (browser + Node).
+- Add a small build setup (Rollup) to produce `dist/` artifacts and update `package.json`.
+- Add a Playwright integration test for offline cache validation.
+
+If you want, I can: (pick one or more)
+
+- Fix the `README.md` now.
+- Add a minimal Rollup build and update `package.json`.
+- Add a Playwright test and a small local server script to run it.
+
+---
+
+## Notes & Observations
+
+- The published package name changed from `hackvision2026-sdk` (spam-detected) to scoped `@soham20/smart-offline-sdk`, which is preferable.
+- Tests pass (`npm test`). The test target is small (echo), so expand tests to include SDK behavior where feasible.
+
+---
+
+_Generated by repository scan on 2026-01-22._

package/README.md

@@ -1,19 +1,63 @@
-<<<<<<< HEAD
-# Hackvision2026
-    
-=======
 # Hackvision2026 SDK (JavaScript)
 
 This repository contains the JavaScript SDK for Hackvision2026.
 
-Quickstart
+## Quickstart
 
 ```javascript
-const { HackvisionClient } = require('./src');
+import { SmartOffline } from "./src/index.js";
 
-const client = new HackvisionClient({ apiKey: process.env.HACKVISION_API_KEY });
-client.echo('hello').then(console.log);
+SmartOffline.init({
+  pages: ["/dashboard", "/profile"],
+  apis: ["/api/user", "/api/data"],
+  debug: true,
+});
 ```
 
 See `examples/` for a runnable example.
->>>>>>> 061641ebd342b507a49884dd32b30125a6525011
+
+## Priority Tuning Options
+
+You can fine-tune how the SDK decides caching priority:
+
+| Option              | Type                                      | Default       | Description                                                                 |
+|---------------------|-------------------------------------------|---------------|-----------------------------------------------------------------------------|
+| `frequencyThreshold`| `number`                                  | `3`           | Number of accesses before a resource is considered "frequent"               |
+| `recencyThreshold`  | `number` (ms)                             | `86400000` (24h) | Milliseconds within which a resource is considered "recent"              |
+| `maxResourceSize`   | `number` (bytes)                          | `Infinity`    | Max bytes to cache per resource; larger resources are skipped               |
+| `networkQuality`    | `'auto'` \| `'fast'` \| `'slow'`          | `'auto'`      | Affects caching aggressiveness; `'auto'` uses Network Information API       |
+| `significance`      | `{ [urlPattern: string]: 'high' \| 'normal' \| 'low' }` | `{}`   | Manual priority overrides per URL pattern                                   |
+
+### Example with all options
+
+```javascript
+SmartOffline.init({
+  pages: ["/dashboard"],
+  apis: ["/api/"],
+  debug: true,
+
+  // Priority tuning
+  frequencyThreshold: 5,         // require 5 accesses to be "frequent"
+  recencyThreshold: 12 * 60 * 60 * 1000, // 12 hours
+  maxResourceSize: 500 * 1024,   // skip caching resources > 500 KB
+  networkQuality: "auto",        // or 'fast' / 'slow'
+  significance: {
+    "/api/critical": "high",     // always high priority
+    "/api/analytics": "low",     // always low priority
+  },
+});
+```
+
+## Installation
+
+### From npm (after publishing)
+
+```bash
+npm install @soham20/smart-offline-sdk
+```
+
+### Directly from GitHub
+
+```bash
+npm install git+https://github.com/OwaisShaikh1/Hackvision2026.git
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soham20/smart-offline-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Smart offline-first JavaScript SDK with intelligent caching for web applications",
   "main": "src/sdk/index.js",
   "scripts": {

package/smart-offline-sw.js

@@ -2,11 +2,19 @@ const CACHE_NAME = "smart-offline-cache-v1";
 
 /**
  * SDK configuration received from SmartOffline.init()
+ * Includes priority tuning knobs.
  */
 let SDK_CONFIG = {
   pages: [],
   apis: [],
   debug: false,
+
+  // Priority tuning defaults
+  frequencyThreshold: 3,
+  recencyThreshold: 24 * 60 * 60 * 1000, // 24h
+  maxResourceSize: Infinity,
+  networkQuality: "auto", // 'auto' | 'fast' | 'slow'
+  significance: {}, // { urlPattern: 'high' | 'normal' | 'low' }
 };
 
 /**
@@ -78,20 +86,43 @@ function getUsage(url) {
 }
 
 /**
- * Decide priority based on real usage
+ * Decide priority based on real usage and developer-tuned config
  */
-function isHighPriority(usage) {
-  if (!usage) return false;
+function isHighPriority(usage, url) {
+  // Manual significance override
+  for (const pattern in SDK_CONFIG.significance) {
+    if (url.includes(pattern)) {
+      const sig = SDK_CONFIG.significance[pattern];
+      if (sig === "high") return true;
+      if (sig === "low") return false;
+      // 'normal' falls through to dynamic logic
+    }
+  }
 
-  const FREQUENT_THRESHOLD = 3;
-  const RECENT_THRESHOLD = 24 * 60 * 60 * 1000; // 24h
+  if (!usage) return false;
 
-  const frequent = usage.count >= FREQUENT_THRESHOLD;
-  const recent = Date.now() - usage.lastAccessed <= RECENT_THRESHOLD;
+  const frequent = usage.count >= SDK_CONFIG.frequencyThreshold;
+  const recent = Date.now() - usage.lastAccessed <= SDK_CONFIG.recencyThreshold;
 
   return frequent || recent;
 }
 
+/**
+ * Detect effective network quality (uses Navigator.connection if available)
+ */
+function getEffectiveNetworkQuality() {
+  if (SDK_CONFIG.networkQuality !== "auto") {
+    return SDK_CONFIG.networkQuality; // developer override
+  }
+  // Use Network Information API if available
+  const conn = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
+  if (conn) {
+    const dominated = ["slow-2g", "2g", "3g"];
+    if (dominated.includes(conn.effectiveType)) return "slow";
+  }
+  return "fast";
+}
+
 /**
  * Install event
  */
@@ -143,10 +174,36 @@ self.addEventListener("fetch", (event) => {
 
   event.respondWith(
     fetch(request)
-      .then((response) => {
+      .then(async (response) => {
         // Network success
         trackUsage(request.url);
 
+        // Check resource size limit
+        const contentLength = response.headers.get("content-length");
+        const size = contentLength ? parseInt(contentLength, 10) : 0;
+        if (size > SDK_CONFIG.maxResourceSize) {
+          if (SDK_CONFIG.debug) {
+            console.log(
+              `[SmartOffline] Skipped caching (size ${size} > ${SDK_CONFIG.maxResourceSize}):`,
+              request.url
+            );
+          }
+          return response;
+        }
+
+        // Network quality aware caching
+        const netQuality = getEffectiveNetworkQuality();
+        if (netQuality === "slow" && !isHighPriority(null, request.url)) {
+          // On slow network, skip caching low priority resources proactively
+          if (SDK_CONFIG.debug) {
+            console.log(
+              `[SmartOffline] Skipped caching (slow network, not high priority):`,
+              request.url
+            );
+          }
+          return response;
+        }
+
         const clone = response.clone();
         caches.open(CACHE_NAME).then((cache) => {
           cache.put(request.url, clone);
@@ -166,7 +223,7 @@ self.addEventListener("fetch", (event) => {
         trackUsage(request.url);
 
         return getUsage(request.url).then((usage) => {
-          const highPriority = isHighPriority(usage);
+          const highPriority = isHighPriority(usage, request.url);
 
           if (SDK_CONFIG.debug) {
             console.log(

package/src/config.js

@@ -0,0 +1,16 @@
+// Build sdk config object with defaults. Used by tests to validate defaults.
+function buildConfig(input = {}) {
+  return {
+    pages: input.pages || [],
+    apis: input.apis || [],
+    debug: input.debug || false,
+
+    frequencyThreshold: input.frequencyThreshold ?? 3,
+    recencyThreshold: input.recencyThreshold ?? 24 * 60 * 60 * 1000,
+    maxResourceSize: input.maxResourceSize ?? Infinity,
+    networkQuality: input.networkQuality ?? 'auto',
+    significance: input.significance || {},
+  };
+}
+
+module.exports = { buildConfig };

package/src/index.js

@@ -1,3 +1,13 @@
+/**
+ * SmartOffline SDK
+ *
+ * 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
+ */
 function init(config = {}) {
   if (!("serviceWorker" in navigator)) {
     console.warn("Service Workers not supported");
@@ -8,14 +18,14 @@ function init(config = {}) {
     pages: config.pages || [],
     apis: config.apis || [],
     debug: config.debug || false,
+
+    
   };
 
-  navigator.serviceWorker.register("/smart-offline-sw.js").then((registration) => {
+  navigator.serviceWorker.register("/smart-offline-sw.js").then(() => {
     console.log("Smart Offline Service Worker registered");
 
-    // Wait for SW to be ready before sending config
     navigator.serviceWorker.ready.then(() => {
-      // Send config to active service worker
       if (navigator.serviceWorker.controller) {
         navigator.serviceWorker.controller.postMessage({
           type: "INIT_CONFIG",
@@ -28,7 +38,6 @@ function init(config = {}) {
       }
     });
 
-    // Handle new SW taking control (on first install)
     navigator.serviceWorker.addEventListener("controllerchange", () => {
       if (navigator.serviceWorker.controller) {
         navigator.serviceWorker.controller.postMessage({
@@ -37,11 +46,17 @@ function init(config = {}) {
         });
 
         if (sdkConfig.debug) {
-          console.log("[SmartOffline] Config sent after controllerchange:", sdkConfig);
+          console.log(
+            "[SmartOffline] Config sent after controllerchange:",
+            sdkConfig
+          );
         }
       }
     });
   });
 }
 
-export const SmartOffline = { init };
+const SmartOffline = { init };
+
+export { SmartOffline };       // ✅ named export
+export default SmartOffline;  // ✅ default export

package/src/priority.js

@@ -0,0 +1,44 @@
+// Utility functions for priority decisions used by the service worker
+
+function matchesSignificance(url, significance) {
+  for (const pattern in significance) {
+    if (Object.prototype.hasOwnProperty.call(significance, pattern)) {
+      if (url.includes(pattern)) return significance[pattern];
+    }
+  }
+  return null;
+}
+
+function isHighPriority(usage, url, config = {}) {
+  // Manual significance override
+  if (config.significance) {
+    const sig = matchesSignificance(url, config.significance);
+    if (sig === 'high') return true;
+    if (sig === 'low') return false;
+  }
+
+  if (!usage) return false;
+
+  const freqThreshold = config.frequencyThreshold ?? 3;
+  const recencyThreshold = config.recencyThreshold ?? 24 * 60 * 60 * 1000;
+
+  const frequent = usage.count >= freqThreshold;
+  const recent = Date.now() - usage.lastAccessed <= recencyThreshold;
+
+  return frequent || recent;
+}
+
+function getEffectiveNetworkQuality(effectiveType, configNetwork = 'auto') {
+  if (configNetwork !== 'auto') return configNetwork;
+  if (!effectiveType) return 'fast';
+  const slowTypes = ['slow-2g', '2g', '3g'];
+  return slowTypes.includes(effectiveType) ? 'slow' : 'fast';
+}
+
+function shouldSkipBySize(size, config = {}) {
+  const max = config.maxResourceSize ?? Infinity;
+  if (!size) return false; // unknown size -> don't skip
+  return size > max;
+}
+
+module.exports = { isHighPriority, getEffectiveNetworkQuality, shouldSkipBySize };

package/.github/workflows/ci.yml

@@ -1,17 +0,0 @@
-name: CI
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: windows-latest
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm ci
-      - run: npm test

package/CHANGELOG.md

@@ -1,6 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [0.1.0] - Initial scaffold
-- JavaScript SDK scaffold: `src/sdk`, examples, tests, CI

package/demo/api/profile.json

@@ -1,5 +0,0 @@
-{
-  "name": "Atif",
-  "role": "Student",
-  "status": "Cached API working"
-}

package/demo/index.html

@@ -1,32 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Smart Offline SDK Demo</title>
-</head>
-<body>
-  <h1>Smart Offline SDK Demo</h1>
-  <p>If this page reloads offline, the SDK works.</p>
-
-  <script type="module">
-  import { SmartOffline } from "../src/index.js";
-
-  SmartOffline.init({
-    pages: ["/demo/index.html","/demo/api/profile.json"],
-    apis: ["https://jsonplaceholder.typicode.com/posts/2"],
-    debug: true
-  });
-
- fetch("https://jsonplaceholder.typicode.com/posts/2")
-  .then(res => res.json())
-  .then(data => {
-    document.body.innerHTML += `<pre>${JSON.stringify(data, null, 2)}</pre>`;
-  })
-  .catch(err => {
-    document.body.innerHTML += "<p>API failed</p>";
-  });
-
-</script>
-
-
-</body>
-</html>

package/examples/example.js

@@ -1,7 +0,0 @@
-const { HackvisionClient } = require('../src/sdk');
-
-(async () => {
-  const client = new HackvisionClient({ apiKey: 'demo' });
-  const res = await client.echo('hello from SDK');
-  console.log(res);
-})();

package/tests/basic.test.js

@@ -1,7 +0,0 @@
-const { HackvisionClient } = require('../src/sdk');
-
-test('echo returns message', async () => {
-  const c = new HackvisionClient();
-  const res = await c.echo('x');
-  expect(res).toEqual({ ok: true, message: 'x' });
-});