@visitor-analytics-sdk/core 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,93 @@
+# @visitor-analytics-sdk/core
+
+Privacy-preserving, framework-agnostic, zero-dependency analytics SDK for web applications. Drop it in any stack and start collecting anonymous visitor data — browser, device, performance, features, environment, and interaction.
+
+```bash
+npm install @visitor-analytics-sdk/core
+```
+
+```ts
+import { createAnalytics } from "@visitor-analytics-sdk/core";
+
+const analytics = createAnalytics({
+  endpoint: "/api/analytics",
+  storage: "indexeddb",
+  autoStart: true,
+});
+```
+
+## Features
+
+- **Zero runtime dependencies** — no external packages, tiny bundle impact
+- **Privacy-first** — never collects PII; all data anonymous and aggregate-only
+- **Plugin-based** — modular collectors, storage adapters, and plugins
+- **Full TypeScript** — strict types, no `any`, auto-complete ready
+- **Tree-shakable** — ESM-first, import only what you need
+- **Offline-ready** — queues records offline, auto-syncs when online
+- **Framework-agnostic** — works with React, Vue, Svelte, Solid, Astro, vanilla JS
+
+## API
+
+```ts
+createAnalytics({
+  endpoint: string;
+  storage: "memory" | "localstorage" | "indexeddb" | StorageAdapter;
+  autoStart?: boolean;
+  batchSize?: number;        // default: 50
+  flushInterval?: number;    // default: 30000 (30s)
+  maxRetries?: number;       // default: 5
+  compressionEnabled?: boolean;
+  deduplicationEnabled?: boolean;
+  sessionTimeout?: number;   // default: 1800000 (30min)
+  includeUserAgent?: boolean;
+  includeReferrer?: boolean;
+  customData?: Record<string, string | number | boolean>;
+})
+```
+
+### Instance methods
+
+```ts
+analytics.start()
+analytics.stop()
+analytics.flush()
+analytics.sync()
+analytics.retryFailed()
+analytics.use(plugin)
+analytics.addCollector(collector)
+analytics.removeCollector(name)
+analytics.query(filters)
+analytics.getCollectedData()
+analytics.export()
+analytics.on(event, handler)
+analytics.off(event, handler)
+analytics.destroy()
+```
+
+### Events
+
+```ts
+analytics.on("start", () => {});
+analytics.on("stop", () => {});
+analytics.on("flush", () => {});
+analytics.on("record-collected", (record) => {});
+analytics.on("batch-uploaded", (batchId) => {});
+analytics.on("batch-failed", (batchId, error) => {});
+```
+
+## Collectors
+
+Six built-in collectors activate automatically:
+
+| Collector | Data |
+|---|---|
+| Browser | name, version, engine, language |
+| Device | OS, screen, touch, form factor |
+| Performance | CLS, LCP, INP, navigation timing |
+| Environment | timezone, language, color scheme |
+| Features | WebGL, WASM, WebGPU, WebRTC |
+| Interaction | session, clicks, scroll, routes |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,3 +1,16 @@
+type AnalyticsEvent = "start" | "stop" | "flush" | "sync" | "record-collected" | "batch-uploaded" | "batch-failed" | "error" | "collector-registered" | "collector-removed" | "plugin-installed" | "plugin-uninstalled" | "storage-saved" | "storage-loaded" | "config-changed";
+type StorageType = "memory" | "localstorage" | "indexeddb";
+
+type Handler = (...args: readonly unknown[]) => void;
+declare class EventBus {
+    private readonly listeners;
+    on(event: AnalyticsEvent, handler: Handler): void;
+    off(event: AnalyticsEvent, handler: Handler): void;
+    emit(event: AnalyticsEvent, ...args: readonly unknown[]): void;
+    removeAllListeners(event?: AnalyticsEvent): void;
+    listenerCount(event: AnalyticsEvent): number;
+}
+
 interface AnalyticsRecord {
     readonly id: string;
     readonly timestamp: number;
@@ -267,7 +280,6 @@ interface PermissionsLike {
 interface PermissionDesc {
     name: string;
 }
-type StorageType = "memory" | "localstorage" | "indexeddb" | "custom";
 interface StorageAdapter {
     save(record: AnalyticsRecord): Promise<void>;
     saveBatch(records: readonly AnalyticsRecord[]): Promise<void>;
@@ -304,15 +316,35 @@ interface UploadResult {
     readonly retryable: boolean;
 }
 type UploadEventHandler = (event: UploadEvent) => void;
-interface UploadEvent {
-    readonly type: "batch-sent" | "batch-success" | "batch-failed" | "retry-scheduled" | "queue-full";
+type UploadEvent = {
+    readonly type: "batch-sent";
+    readonly batchId: string;
+    readonly recordCount: number;
+    readonly timestamp: number;
+} | {
+    readonly type: "batch-success";
+    readonly batchId: string;
+    readonly recordCount: number;
+    readonly timestamp: number;
+} | {
+    readonly type: "batch-failed";
     readonly batchId: string;
     readonly recordCount: number;
     readonly timestamp: number;
     readonly error?: string;
-    readonly retryCount?: number;
-    readonly nextRetryAt?: number;
-}
+} | {
+    readonly type: "retry-scheduled";
+    readonly batchId: string;
+    readonly recordCount: number;
+    readonly timestamp: number;
+    readonly retryCount: number;
+    readonly nextRetryAt: number;
+} | {
+    readonly type: "queue-full";
+    readonly batchId: string;
+    readonly recordCount: number;
+    readonly timestamp: number;
+};
 interface Plugin {
     readonly name: string;
     readonly version: string;
@@ -327,7 +359,6 @@ interface PluginContext {
     off(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
     getConfig(): AnalyticsConfig;
 }
-type AnalyticsEvent = "start" | "stop" | "flush" | "sync" | "record-collected" | "batch-uploaded" | "batch-failed" | "error" | "collector-registered" | "collector-removed" | "plugin-installed" | "plugin-uninstalled" | "storage-saved" | "storage-loaded" | "config-changed";
 interface AnalyticsConfig {
     readonly endpoint: string;
     readonly storage: StorageType | StorageAdapter;
@@ -366,11 +397,21 @@ interface VisitorAnalyticsInstance {
     addCollector(collector: Collector): void;
     removeCollector(name: string): void;
     getCollectedData(): Promise<readonly AnalyticsRecord[]>;
+    query(query: AnalyticsQuery): Promise<readonly AnalyticsRecord[]>;
     export(): Promise<string>;
     on(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
     off(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
+    trackRouteChange(url: string): void;
     destroy(): Promise<void>;
 }
+interface AnalyticsQuery {
+    readonly since?: number;
+    readonly until?: number;
+    readonly pagePath?: string;
+    readonly sessionId?: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
 
 declare class VisitorAnalytics implements VisitorAnalyticsInstance {
     private config;
@@ -395,7 +436,9 @@ declare class VisitorAnalytics implements VisitorAnalyticsInstance {
     addCollector(collector: Collector): void;
     removeCollector(name: string): void;
     getCollectedData(): Promise<readonly AnalyticsRecord[]>;
+    query(query: AnalyticsQuery): Promise<readonly AnalyticsRecord[]>;
     export(): Promise<string>;
+    trackRouteChange(url: string): void;
     on(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
     off(event: AnalyticsEvent, handler: (...args: readonly unknown[]) => void): void;
     destroy(): Promise<void>;
@@ -405,14 +448,4 @@ declare class VisitorAnalytics implements VisitorAnalyticsInstance {
 }
 declare function createAnalytics(config?: AnalyticsConfigPartial): VisitorAnalyticsInstance;
 
-type Handler = (...args: readonly unknown[]) => void;
-declare class EventBus {
-    private readonly listeners;
-    on(event: AnalyticsEvent, handler: Handler): void;
-    off(event: AnalyticsEvent, handler: Handler): void;
-    emit(event: AnalyticsEvent, ...args: readonly unknown[]): void;
-    removeAllListeners(event?: AnalyticsEvent): void;
-    listenerCount(event: AnalyticsEvent): number;
-}
-
-export { type AnalyticsConfig, type AnalyticsConfigPartial, type AnalyticsEvent, type AnalyticsRecord, type BrowserData, type ClipboardLike, type Collector, type CollectorCategory, type CollectorContext, type DeviceData, type DeviceFormFactor, type DocumentLike, type EnvironmentData, EventBus, type FeatureData, type HistoryLike, type InteractionData, type LocationLike, type MetadataData, type NavigationTiming, type NavigatorLike, type NetworkInformationLike, type PaintTiming, type PerformanceData, type PerformanceLike, type PermissionDesc, type PermissionsLike, type Plugin, type PluginContext, type ScreenLike, type ScreenOrientationLike, type StorageAdapter, type StorageManagerLike, type StorageType, type TouchSupport, type UploadEvent, type UploadEventHandler, type UploadPayload, type UploadResult, type UploaderConfig, VisitorAnalytics, type VisitorAnalyticsFactory, type VisitorAnalyticsInstance, type WindowLike, createAnalytics };
+export { type AnalyticsConfig, type AnalyticsConfigPartial, type AnalyticsEvent, type AnalyticsQuery, type AnalyticsRecord, type BrowserData, type ClipboardLike, type Collector, type CollectorCategory, type CollectorContext, type DeviceData, type DeviceFormFactor, type DocumentLike, type EnvironmentData, EventBus, type FeatureData, type HistoryLike, type InteractionData, type LocationLike, type MetadataData, type NavigationTiming, type NavigatorLike, type NetworkInformationLike, type PaintTiming, type PerformanceData, type PerformanceLike, type PermissionDesc, type PermissionsLike, type Plugin, type PluginContext, type ScreenLike, type ScreenOrientationLike, type StorageAdapter, type StorageManagerLike, type StorageType, type TouchSupport, type UploadEvent, type UploadEventHandler, type UploadPayload, type UploadResult, type UploaderConfig, VisitorAnalytics, type VisitorAnalyticsFactory, type VisitorAnalyticsInstance, type WindowLike, createAnalytics };

package/dist/index.js

@@ -1,4 +1,50 @@
-// src/event-bus.ts
+// ../utils/src/index.ts
+var SDK_VERSION = "1.0.0";
+function generateId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+function generateShortId() {
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  return generateId().replace(/-/g, "").slice(0, 16);
+}
+function safeCall(fn, fallback) {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}
+function requestIdle(callback, timeout = 5e3) {
+  if (typeof window !== "undefined" && "requestIdleCallback" in window) {
+    window.requestIdleCallback(callback, { timeout });
+  } else {
+    setTimeout(callback, 0);
+  }
+}
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  for (const key of Object.keys(obj)) {
+    const val = obj[key];
+    if (val !== null && typeof val === "object" && !Object.isFrozen(val)) {
+      deepFreeze(val);
+    }
+  }
+  return obj;
+}
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined" && typeof navigator !== "undefined";
+}
 var EventBus = class {
   listeners = /* @__PURE__ */ new Map();
   on(event, handler) {
@@ -33,6 +79,23 @@ var EventBus = class {
     return this.listeners.get(event)?.size ?? 0;
   }
 };
+function detectBestStorage() {
+  if (typeof window === "undefined") return "memory";
+  try {
+    if (typeof indexedDB !== "undefined") return "indexeddb";
+  } catch {
+  }
+  try {
+    if (typeof localStorage !== "undefined") {
+      const testKey = "__va_storage_test__";
+      localStorage.setItem(testKey, "1");
+      localStorage.removeItem(testKey);
+      return "localstorage";
+    }
+  } catch {
+  }
+  return "memory";
+}
 
 // ../plugins/src/plugin-manager.ts
 var PluginManager = class {
@@ -99,57 +162,6 @@ function createPluginContext(addCollector, removeCollector, eventBus, getConfig)
   };
 }
 
-// ../utils/src/index.ts
-var SDK_VERSION = "1.0.0";
-function generateId() {
-  if (typeof crypto !== "undefined" && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-    const r = Math.random() * 16 | 0;
-    const v = c === "x" ? r : r & 3 | 8;
-    return v.toString(16);
-  });
-}
-function generateShortId() {
-  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
-    const bytes = new Uint8Array(8);
-    crypto.getRandomValues(bytes);
-    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-  }
-  return generateId().replace(/-/g, "").slice(0, 16);
-}
-function safeCall(fn, fallback) {
-  try {
-    return fn();
-  } catch {
-    return fallback;
-  }
-}
-function requestIdle(callback, timeout = 5e3) {
-  if (typeof window !== "undefined" && "requestIdleCallback" in window) {
-    window.requestIdleCallback(callback, { timeout });
-  } else {
-    setTimeout(callback, 0);
-  }
-}
-function deepFreeze(obj) {
-  Object.freeze(obj);
-  for (const key of Object.keys(obj)) {
-    const val = obj[key];
-    if (val !== null && typeof val === "object" && !Object.isFrozen(val)) {
-      deepFreeze(val);
-    }
-  }
-  return obj;
-}
-function cloneRecord(record) {
-  return JSON.parse(JSON.stringify(record));
-}
-function isBrowser() {
-  return typeof window !== "undefined" && typeof document !== "undefined" && typeof navigator !== "undefined";
-}
-
 // ../uploader/src/uploader.ts
 var DEFAULT_CONFIG = {
   endpoint: "",
@@ -173,6 +185,7 @@ var Uploader = class {
   seenBatchIds = /* @__PURE__ */ new Set();
   isUploading = false;
   isStopped = false;
+  beforeUnloadHandler = null;
   constructor(storage, config) {
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.storage = storage;
@@ -184,6 +197,12 @@ var Uploader = class {
         requestIdle(() => this.flush());
       }, this.config.flushInterval);
     }
+    if (typeof window !== "undefined") {
+      this.beforeUnloadHandler = () => {
+        this.flushViaSendBeacon();
+      };
+      window.addEventListener("beforeunload", this.beforeUnloadHandler);
+    }
   }
   stop() {
     this.isStopped = true;
@@ -195,6 +214,10 @@ var Uploader = class {
       clearTimeout(this.retryTimer);
       this.retryTimer = null;
     }
+    if (this.beforeUnloadHandler && typeof window !== "undefined") {
+      window.removeEventListener("beforeunload", this.beforeUnloadHandler);
+      this.beforeUnloadHandler = null;
+    }
     this.retryQueue.clear();
   }
   onEvent(handler) {
@@ -267,6 +290,28 @@ var Uploader = class {
       this.isUploading = false;
     }
   }
+  // C3: sendBeacon fallback for page unload
+  flushViaSendBeacon() {
+    if (this.isStopped) return;
+    try {
+      const raw = typeof localStorage !== "undefined" ? localStorage.getItem("va_records") : null;
+      if (!raw) return;
+      const records = JSON.parse(raw);
+      if (!Array.isArray(records) || records.length === 0) return;
+      const batchId = generateShortId();
+      const payload = {
+        records,
+        batchId,
+        timestamp: Date.now(),
+        sdkVersion: SDK_VERSION
+      };
+      const blob = new Blob([JSON.stringify(payload)], { type: "application/json" });
+      if (this.config.endpoint && typeof navigator !== "undefined" && "sendBeacon" in navigator) {
+        navigator.sendBeacon(this.config.endpoint, blob);
+      }
+    } catch {
+    }
+  }
   async sendBatch(payload) {
     if (!this.config.endpoint) {
       return { success: false, batchId: payload.batchId, error: "No endpoint configured", retryable: false };
@@ -319,8 +364,7 @@ var Uploader = class {
         batchId: payload.batchId,
         recordCount: payload.records.length,
         timestamp: Date.now(),
-        error: "Max retries exceeded",
-        retryCount
+        error: "Max retries exceeded"
       });
       return;
     }
@@ -381,6 +425,7 @@ var Uploader = class {
   async sync() {
     await this.flush();
   }
+  // M1: Document compression browser support
   async compress(data) {
     if (typeof CompressionStream === "undefined") {
       return data;
@@ -404,15 +449,15 @@ var Uploader = class {
 var MemoryStorage = class {
   records = [];
   async save(record) {
-    this.records.push(cloneRecord(record));
+    this.records.push(record);
   }
   async saveBatch(records) {
     for (const record of records) {
-      this.records.push(cloneRecord(record));
+      this.records.push(record);
     }
   }
   async load() {
-    return this.records.map((r) => cloneRecord(r));
+    return this.records;
   }
   async loadBatch(limit) {
     return this.records.splice(0, limit);
@@ -441,13 +486,13 @@ var LocalStorageAdapter = class {
   }
   async save(record) {
     const records = this.readAll();
-    records.push(cloneRecord(record));
+    records.push(record);
     this.writeAll(records);
   }
   async saveBatch(records) {
     const existing = this.readAll();
     for (const record of records) {
-      existing.push(cloneRecord(record));
+      existing.push(record);
     }
     this.writeAll(existing);
   }
@@ -543,7 +588,7 @@ var IndexedDBAdapter = class {
     return new Promise((resolve, reject) => {
       const tx = db.transaction(this.storeName, "readwrite");
       const store = tx.objectStore(this.storeName);
-      const request = store.put(cloneRecord(record));
+      const request = store.put(record);
       request.onsuccess = () => resolve();
       request.onerror = () => reject(request.error);
     });
@@ -554,7 +599,7 @@ var IndexedDBAdapter = class {
       const tx = db.transaction(this.storeName, "readwrite");
       const store = tx.objectStore(this.storeName);
       for (const record of records) {
-        store.put(cloneRecord(record));
+        store.put(record);
       }
       tx.oncomplete = () => resolve();
       tx.onerror = () => reject(tx.error);
@@ -684,11 +729,13 @@ var BrowserCollector = class {
       }
     };
   }
+  // H1: Improved UA parser with proper detection order
   parseUA(ua) {
     let name = "unknown";
     let version = "0";
     let engine = "unknown";
     let engineVersion = "0";
+    const isHeadless = ua.includes("HeadlessChrome") || ua.includes("Headless");
     if (ua.includes("Firefox/") && !ua.includes("Seamonkey")) {
       name = "Firefox";
       const match = ua.match(/Firefox\/([\d.]+)/);
@@ -704,7 +751,27 @@ var BrowserCollector = class {
       const match = ua.match(/(?:OPR|Opera)\/([\d.]+)/);
       version = match?.[1] ?? "0";
       engine = "Blink";
-    } else if (ua.includes("Chrome/") && !ua.includes("Edg/")) {
+    } else if (ua.includes("SamsungBrowser/")) {
+      name = "Samsung Internet";
+      const match = ua.match(/SamsungBrowser\/([\d.]+)/);
+      version = match?.[1] ?? "0";
+      engine = "Blink";
+    } else if (ua.includes("UCBrowser/") || ua.includes("UCWEB")) {
+      name = "UC Browser";
+      const match = ua.match(/(?:UCBrowser|UCWEB)\/([\d.]+)/);
+      version = match?.[1] ?? "0";
+      engine = "Blink";
+    } else if (ua.includes("Opera Mini/")) {
+      name = "Opera Mini";
+      const match = ua.match(/Opera Mini\/([\d.]+)/);
+      version = match?.[1] ?? "0";
+      engine = "Presto";
+    } else if (ua.includes("CriOS/")) {
+      name = "Chrome";
+      const match = ua.match(/CriOS\/([\d.]+)/);
+      version = match?.[1] ?? "0";
+      engine = "WebKit";
+    } else if (ua.includes("Chrome/") && !ua.includes("Edg/") && !ua.includes("OPR/")) {
       name = "Chrome";
       const match = ua.match(/Chrome\/([\d.]+)/);
       version = match?.[1] ?? "0";
@@ -720,6 +787,9 @@ var BrowserCollector = class {
       version = match?.[1] ?? "0";
       engine = "Trident";
     }
+    if (isHeadless && name !== "unknown") {
+      name += " (headless)";
+    }
     if (engine === "Blink") {
       const match = ua.match(/AppleWebKit\/([\d.]+)/);
       engineVersion = match?.[1] ?? "0";
@@ -1177,6 +1247,8 @@ var InteractionCollector = class {
   cleanupFns = [];
   sessionTimeout = null;
   sessionTimeoutMs;
+  originalPushState = null;
+  originalReplaceState = null;
   constructor(options) {
     this.sessionTimeoutMs = options?.sessionTimeout ?? 30 * 60 * 1e3;
     this.state = this.createInitialState();
@@ -1271,8 +1343,28 @@ var InteractionCollector = class {
     this.cleanupFns.push(() => {
       win.removeEventListener("popstate", onPopState);
     });
+    const histWin = win;
+    this.originalPushState = histWin.history.pushState.bind(histWin.history);
+    this.originalReplaceState = histWin.history.replaceState.bind(histWin.history);
+    const state = this.state;
+    const origPush = this.originalPushState;
+    const origReplace = this.originalReplaceState;
+    histWin.history.pushState = function(data, unused, url) {
+      origPush.call(this, data, unused, url);
+      state.routeChanges++;
+      state.lastPage = location.href;
+    };
+    histWin.history.replaceState = function(data, unused, url) {
+      origReplace.call(this, data, unused, url);
+      state.lastPage = location.href;
+    };
     this.startSessionTimeout();
   }
+  // H3: Public method for framework integrations to manually track route changes
+  trackRouteChange(url) {
+    this.state.routeChanges++;
+    this.state.lastPage = url;
+  }
   startSessionTimeout() {
     this.sessionTimeout = setTimeout(() => {
       this.state.sessionStart = Date.now();
@@ -1316,6 +1408,12 @@ var InteractionCollector = class {
     if (this.sessionTimeout !== null) {
       clearTimeout(this.sessionTimeout);
     }
+    if (this.originalPushState && typeof history !== "undefined") {
+      history.pushState = this.originalPushState;
+    }
+    if (this.originalReplaceState && typeof history !== "undefined") {
+      history.replaceState = this.originalReplaceState;
+    }
     for (const fn of this.cleanupFns) {
       fn();
     }
@@ -1326,7 +1424,8 @@ var InteractionCollector = class {
 // src/visitor-analytics.ts
 var DEFAULT_CONFIG2 = {
   endpoint: "",
-  storage: "memory",
+  // H5: Auto-detect best storage instead of defaulting to memory
+  storage: "indexeddb",
   autoStart: true,
   batchSize: 50,
   flushInterval: 3e4,
@@ -1367,6 +1466,9 @@ var VisitorAnalytics = class {
     if (config.headers) {
       merged.headers = { ...DEFAULT_CONFIG2.headers, ...config.headers };
     }
+    if (!config.storage) {
+      merged.storage = detectBestStorage();
+    }
     this.config = merged;
     this.eventBus = new EventBus();
     this.sessionId = generateId();
@@ -1415,7 +1517,9 @@ var VisitorAnalytics = class {
       );
     }
   }
+  // C1: Guard buildCollectorContext with isBrowser() - returns null on server
   buildCollectorContext() {
+    if (!isBrowser()) return null;
     if (this.collectorContext) return this.collectorContext;
     const ctx = {
       document,
@@ -1431,13 +1535,16 @@ var VisitorAnalytics = class {
   }
   start() {
     if (this.isRunning) return;
+    if (!isBrowser()) return;
     this.isRunning = true;
     this.uploader.start();
     this.eventBus.emit("start");
     for (const collector of this.collectors) {
-      if (collector.init && isBrowser()) {
+      if (collector.init) {
+        const ctx = this.buildCollectorContext();
+        if (!ctx) continue;
         requestIdle(() => {
-          collector.init(this.buildCollectorContext()).catch((err) => {
+          collector.init(ctx).catch((err) => {
             console.debug("[VisitorAnalytics] Collector init failed:", collector.name, err);
           });
         });
@@ -1457,13 +1564,13 @@ var VisitorAnalytics = class {
     }
     this.eventBus.emit("stop");
   }
+  // C2: flush() should only upload what's already stored, not collect again
   async flush() {
-    await this.collectAndStore();
     await this.uploader.flush();
     this.eventBus.emit("flush");
   }
+  // C2: sync() same - only upload, don't re-collect
   async sync() {
-    await this.collectAndStore();
     await this.uploader.sync();
     this.eventBus.emit("sync");
   }
@@ -1497,9 +1604,40 @@ var VisitorAnalytics = class {
   async getCollectedData() {
     return this.storage.load();
   }
+  // M2: Query API for filtering records
+  async query(query) {
+    const allRecords = await this.storage.load();
+    let result = [...allRecords];
+    if (query.since !== void 0) {
+      result = result.filter((r) => r.timestamp >= query.since);
+    }
+    if (query.until !== void 0) {
+      result = result.filter((r) => r.timestamp <= query.until);
+    }
+    if (query.pagePath !== void 0) {
+      result = result.filter((r) => r.pagePath === query.pagePath);
+    }
+    if (query.sessionId !== void 0) {
+      result = result.filter((r) => r.sessionId === query.sessionId);
+    }
+    if (query.offset !== void 0) {
+      result = result.slice(query.offset);
+    }
+    if (query.limit !== void 0) {
+      result = result.slice(0, query.limit);
+    }
+    return result;
+  }
   async export() {
     return this.storage.export();
   }
+  // H3: Expose trackRouteChange for SPA framework integrations
+  trackRouteChange(url) {
+    const interactionCollector = this.collectors.find((c) => c.name === "interaction");
+    if (interactionCollector) {
+      interactionCollector.trackRouteChange(url);
+    }
+  }
   on(event, handler) {
     this.eventBus.on(event, handler);
   }
@@ -1521,6 +1659,7 @@ var VisitorAnalytics = class {
   async collectAndStore() {
     if (!isBrowser()) return;
     const context = this.buildCollectorContext();
+    if (!context) return;
     const record = await this.collectRecord(context);
     if (record) {
       await this.storage.save(record);
@@ -1675,8 +1814,5 @@ var VisitorAnalytics = class {
 function createAnalytics(config) {
   return new VisitorAnalytics(config);
 }
-export {
-  EventBus,
-  VisitorAnalytics,
-  createAnalytics
-};
+
+export { EventBus, VisitorAnalytics, createAnalytics };

package/package.json

@@ -1,10 +1,33 @@
 {
   "name": "@visitor-analytics-sdk/core",
-  "version": "1.0.0",
+  "description": "Privacy-preserving, framework-agnostic, zero-dependency analytics SDK for web applications. Core orchestrator with event bus, type-safe API, and plugin system.",
+  "license": "MIT",
+  "keywords": [
+    "visitor-analytics",
+    "analytics",
+    "privacy",
+    "tracking",
+    "sdk",
+    "typescript",
+    "web-analytics",
+    "zero-deps"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/instax-dutta/visitor-analytics.git"
+  },
+  "homepage": "https://github.com/instax-dutta/visitor-analytics#readme",
+  "bugs": {
+    "url": "https://github.com/instax-dutta/visitor-analytics/issues"
+  },
+  "version": "1.0.1",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -19,7 +42,7 @@
     "tsup": "^8.0.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
+    "build": "tsup src/index.ts --format esm --dts --treeshake",
     "typecheck": "tsc --noEmit"
   }
 }