@clamp-sh/analytics 0.1.0 → 0.3.0

package/README.md

@@ -61,7 +61,7 @@ Server events require an API key (found in your project settings).
 ## Script tag
 
 ```html
-<script src="https://cdn.clamp.sh/v1.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@clamp-sh/analytics@0.2.0/dist/cdn.global.js"></script>
 <script>
   clamp.init("proj_xxx")
 </script>

package/dist/cdn.global.js

@@ -0,0 +1 @@
+"use strict";var clamp=(()=>{var r=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var l=(i,e)=>{for(var t in e)r(i,t,{get:e[t],enumerable:!0})},c=(i,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of h(e))!p.call(i,a)&&a!==t&&r(i,a,{get:()=>e[a],enumerable:!(n=g(e,a))||n.enumerable});return i};var u=i=>c(r({},"__esModule",{value:!0}),i);var w={};l(w,{getAnonymousId:()=>f,init:()=>m,track:()=>y});var v="https://api.clamp.sh";var o=class{constructor(){this.projectId=null;this.endpoint=v;this.sessionId=null;this.anonymousId=null;this.queue=[];this.preInitQueue=[];this.initialized=!1;this.lastPageviewPath=null;this.lastPageviewTime=0;this.engagementSeconds=0;this.engagementTimer=null;this.pageviewEndSent=!1;this.hiddenAt=null}init(e,t){if(typeof window>"u")return;this.projectId=e,t?.endpoint&&(this.endpoint=t.endpoint),this.initialized=!0,this.sessionId=sessionStorage.getItem("clamp_sid")??this.newId("ses"),sessionStorage.setItem("clamp_sid",this.sessionId),this.anonymousId=localStorage.getItem("clamp_aid")??this.newId("anon"),localStorage.setItem("clamp_aid",this.anonymousId);for(let s of this.preInitQueue)this.track(s.name,s.props);this.preInitQueue=[],this.pageview();let n=history.pushState.bind(history),a=history.replaceState.bind(history);history.pushState=(...s)=>{n(...s),this.pageview()},history.replaceState=(...s)=>{a(...s),this.pageview()},window.addEventListener("popstate",()=>this.pageview()),window.addEventListener("pageshow",s=>{s.persisted&&(this.pageviewEndSent=!1,this.pageview())}),setInterval(()=>this.flush(),5e3),document.addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"?(this.hiddenAt=Date.now(),this.stopEngagement(),this.sendPageviewEnd(),this.flush(!0)):(this.hiddenAt!==null&&Date.now()-this.hiddenAt>=18e5&&(this.sessionId=this.newId("ses"),sessionStorage.setItem("clamp_sid",this.sessionId)),this.hiddenAt=null,this.startEngagement())}),window.addEventListener("pagehide",()=>{this.stopEngagement(),this.sendPageviewEnd(),this.flush(!0)}),this.startEngagement()}track(e,t){if(!this.initialized){this.preInitQueue.push({name:e,props:t});return}let n={name:e,url:location.href,referrer:document.referrer,sessionId:this.sessionId,anonymousId:this.anonymousId,timestamp:new Date().toISOString(),screenWidth:window.innerWidth,screenHeight:window.innerHeight,language:navigator.language,platform:"web",properties:t};this.queue.push(n)}getAnonymousId(){return this.anonymousId}pageview(){let e=location.pathname+location.search,t=Date.now();e===this.lastPageviewPath&&t-this.lastPageviewTime<500||(this.lastPageviewPath!==null&&this.sendPageviewEnd(),this.lastPageviewPath=e,this.lastPageviewTime=t,this.engagementSeconds=0,this.pageviewEndSent=!1,this.track("pageview"))}startEngagement(){this.engagementTimer||(this.engagementTimer=setInterval(()=>{document.visibilityState==="visible"&&(this.engagementSeconds+=1)},1e3))}stopEngagement(){this.engagementTimer&&(clearInterval(this.engagementTimer),this.engagementTimer=null)}sendPageviewEnd(){if(this.pageviewEndSent||this.engagementSeconds<1||!this.lastPageviewPath)return;this.pageviewEndSent=!0;let e={p:this.projectId,events:[{name:"pageview_end",url:location.origin+this.lastPageviewPath,referrer:"",sessionId:this.sessionId,anonymousId:this.anonymousId,timestamp:new Date().toISOString(),platform:"web",properties:{engagement_seconds:String(this.engagementSeconds)}}]},t=`${this.endpoint}/e/batch`,n=JSON.stringify(e);typeof navigator.sendBeacon=="function"?navigator.sendBeacon(t,n):fetch(t,{method:"POST",headers:{"content-type":"application/json"},body:n,keepalive:!0}).catch(()=>{})}flush(e=!1){if(!this.projectId||this.queue.length===0)return;let t=this.queue.splice(0,100),n={p:this.projectId,events:t},a=`${this.endpoint}/e/batch`,s=JSON.stringify(n);e&&typeof navigator.sendBeacon=="function"?navigator.sendBeacon(a,s):fetch(a,{method:"POST",headers:{"content-type":"application/json"},body:s,keepalive:!0}).catch(()=>{}),this.queue.length>0&&this.flush(e)}newId(e){let t=Math.random().toString(36).slice(2,10),n=Date.now().toString(36);return`${e}_${n}${t}`}},d=new o;function m(i,e){d.init(i,e)}function y(i,e){d.track(i,e)}function f(){return d.getAnonymousId()}return u(w);})();

package/dist/index.js

@@ -26,6 +26,7 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var SESSION_IDLE_MS = 30 * 60 * 1e3;
 var BrowserClient = class {
   constructor() {
     this.projectId = null;
@@ -34,8 +35,16 @@ var BrowserClient = class {
     this.anonymousId = null;
     this.queue = [];
     this.preInitQueue = [];
-    this.timer = null;
     this.initialized = false;
+    // Dedup state
+    this.lastPageviewPath = null;
+    this.lastPageviewTime = 0;
+    // Engagement tracking
+    this.engagementSeconds = 0;
+    this.engagementTimer = null;
+    this.pageviewEndSent = false;
+    // Session idle tracking
+    this.hiddenAt = null;
   }
   init(projectId, opts) {
     if (typeof window === "undefined") return;
@@ -62,12 +71,34 @@ var BrowserClient = class {
       this.pageview();
     };
     window.addEventListener("popstate", () => this.pageview());
-    this.timer = setInterval(() => this.flush(), 5e3);
-    const onHide = () => this.flush(true);
+    window.addEventListener("pageshow", (e) => {
+      if (e.persisted) {
+        this.pageviewEndSent = false;
+        this.pageview();
+      }
+    });
+    setInterval(() => this.flush(), 5e3);
     document.addEventListener("visibilitychange", () => {
-      if (document.visibilityState === "hidden") onHide();
+      if (document.visibilityState === "hidden") {
+        this.hiddenAt = Date.now();
+        this.stopEngagement();
+        this.sendPageviewEnd();
+        this.flush(true);
+      } else {
+        if (this.hiddenAt !== null && Date.now() - this.hiddenAt >= SESSION_IDLE_MS) {
+          this.sessionId = this.newId("ses");
+          sessionStorage.setItem("clamp_sid", this.sessionId);
+        }
+        this.hiddenAt = null;
+        this.startEngagement();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      this.stopEngagement();
+      this.sendPageviewEnd();
+      this.flush(true);
     });
-    window.addEventListener("pagehide", onHide);
+    this.startEngagement();
   }
   track(name, properties) {
     if (!this.initialized) {
@@ -94,8 +125,57 @@ var BrowserClient = class {
   }
   // ── Private ─────────────────────────────────────────────────────────
   pageview() {
+    const path = location.pathname + location.search;
+    const now = Date.now();
+    if (path === this.lastPageviewPath && now - this.lastPageviewTime < 500) return;
+    if (this.lastPageviewPath !== null) {
+      this.sendPageviewEnd();
+    }
+    this.lastPageviewPath = path;
+    this.lastPageviewTime = now;
+    this.engagementSeconds = 0;
+    this.pageviewEndSent = false;
     this.track("pageview");
   }
+  startEngagement() {
+    if (this.engagementTimer) return;
+    this.engagementTimer = setInterval(() => {
+      if (document.visibilityState === "visible") {
+        this.engagementSeconds += 1;
+      }
+    }, 1e3);
+  }
+  stopEngagement() {
+    if (this.engagementTimer) {
+      clearInterval(this.engagementTimer);
+      this.engagementTimer = null;
+    }
+  }
+  sendPageviewEnd() {
+    if (this.pageviewEndSent || this.engagementSeconds < 1 || !this.lastPageviewPath) return;
+    this.pageviewEndSent = true;
+    const payload = {
+      p: this.projectId,
+      events: [{
+        name: "pageview_end",
+        url: location.origin + this.lastPageviewPath,
+        referrer: "",
+        sessionId: this.sessionId,
+        anonymousId: this.anonymousId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        platform: "web",
+        properties: { engagement_seconds: String(this.engagementSeconds) }
+      }]
+    };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body, keepalive: true }).catch(() => {
+      });
+    }
+  }
   flush(useBeacon = false) {
     if (!this.projectId || this.queue.length === 0) return;
     const events = this.queue.splice(0, 100);

package/dist/index.mjs

@@ -1,5 +1,6 @@
 // src/index.ts
 var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var SESSION_IDLE_MS = 30 * 60 * 1e3;
 var BrowserClient = class {
   constructor() {
     this.projectId = null;
@@ -8,8 +9,16 @@ var BrowserClient = class {
     this.anonymousId = null;
     this.queue = [];
     this.preInitQueue = [];
-    this.timer = null;
     this.initialized = false;
+    // Dedup state
+    this.lastPageviewPath = null;
+    this.lastPageviewTime = 0;
+    // Engagement tracking
+    this.engagementSeconds = 0;
+    this.engagementTimer = null;
+    this.pageviewEndSent = false;
+    // Session idle tracking
+    this.hiddenAt = null;
   }
   init(projectId, opts) {
     if (typeof window === "undefined") return;
@@ -36,12 +45,34 @@ var BrowserClient = class {
       this.pageview();
     };
     window.addEventListener("popstate", () => this.pageview());
-    this.timer = setInterval(() => this.flush(), 5e3);
-    const onHide = () => this.flush(true);
+    window.addEventListener("pageshow", (e) => {
+      if (e.persisted) {
+        this.pageviewEndSent = false;
+        this.pageview();
+      }
+    });
+    setInterval(() => this.flush(), 5e3);
     document.addEventListener("visibilitychange", () => {
-      if (document.visibilityState === "hidden") onHide();
+      if (document.visibilityState === "hidden") {
+        this.hiddenAt = Date.now();
+        this.stopEngagement();
+        this.sendPageviewEnd();
+        this.flush(true);
+      } else {
+        if (this.hiddenAt !== null && Date.now() - this.hiddenAt >= SESSION_IDLE_MS) {
+          this.sessionId = this.newId("ses");
+          sessionStorage.setItem("clamp_sid", this.sessionId);
+        }
+        this.hiddenAt = null;
+        this.startEngagement();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      this.stopEngagement();
+      this.sendPageviewEnd();
+      this.flush(true);
     });
-    window.addEventListener("pagehide", onHide);
+    this.startEngagement();
   }
   track(name, properties) {
     if (!this.initialized) {
@@ -68,8 +99,57 @@ var BrowserClient = class {
   }
   // ── Private ─────────────────────────────────────────────────────────
   pageview() {
+    const path = location.pathname + location.search;
+    const now = Date.now();
+    if (path === this.lastPageviewPath && now - this.lastPageviewTime < 500) return;
+    if (this.lastPageviewPath !== null) {
+      this.sendPageviewEnd();
+    }
+    this.lastPageviewPath = path;
+    this.lastPageviewTime = now;
+    this.engagementSeconds = 0;
+    this.pageviewEndSent = false;
     this.track("pageview");
   }
+  startEngagement() {
+    if (this.engagementTimer) return;
+    this.engagementTimer = setInterval(() => {
+      if (document.visibilityState === "visible") {
+        this.engagementSeconds += 1;
+      }
+    }, 1e3);
+  }
+  stopEngagement() {
+    if (this.engagementTimer) {
+      clearInterval(this.engagementTimer);
+      this.engagementTimer = null;
+    }
+  }
+  sendPageviewEnd() {
+    if (this.pageviewEndSent || this.engagementSeconds < 1 || !this.lastPageviewPath) return;
+    this.pageviewEndSent = true;
+    const payload = {
+      p: this.projectId,
+      events: [{
+        name: "pageview_end",
+        url: location.origin + this.lastPageviewPath,
+        referrer: "",
+        sessionId: this.sessionId,
+        anonymousId: this.anonymousId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        platform: "web",
+        properties: { engagement_seconds: String(this.engagementSeconds) }
+      }]
+    };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body, keepalive: true }).catch(() => {
+      });
+    }
+  }
   flush(useBeacon = false) {
     if (!this.projectId || this.queue.length === 0) return;
     const events = this.queue.splice(0, 100);

package/dist/react.js

@@ -28,6 +28,7 @@ var import_react = require("react");
 
 // src/index.ts
 var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var SESSION_IDLE_MS = 30 * 60 * 1e3;
 var BrowserClient = class {
   constructor() {
     this.projectId = null;
@@ -36,8 +37,16 @@ var BrowserClient = class {
     this.anonymousId = null;
     this.queue = [];
     this.preInitQueue = [];
-    this.timer = null;
     this.initialized = false;
+    // Dedup state
+    this.lastPageviewPath = null;
+    this.lastPageviewTime = 0;
+    // Engagement tracking
+    this.engagementSeconds = 0;
+    this.engagementTimer = null;
+    this.pageviewEndSent = false;
+    // Session idle tracking
+    this.hiddenAt = null;
   }
   init(projectId, opts) {
     if (typeof window === "undefined") return;
@@ -64,12 +73,34 @@ var BrowserClient = class {
       this.pageview();
     };
     window.addEventListener("popstate", () => this.pageview());
-    this.timer = setInterval(() => this.flush(), 5e3);
-    const onHide = () => this.flush(true);
+    window.addEventListener("pageshow", (e) => {
+      if (e.persisted) {
+        this.pageviewEndSent = false;
+        this.pageview();
+      }
+    });
+    setInterval(() => this.flush(), 5e3);
     document.addEventListener("visibilitychange", () => {
-      if (document.visibilityState === "hidden") onHide();
+      if (document.visibilityState === "hidden") {
+        this.hiddenAt = Date.now();
+        this.stopEngagement();
+        this.sendPageviewEnd();
+        this.flush(true);
+      } else {
+        if (this.hiddenAt !== null && Date.now() - this.hiddenAt >= SESSION_IDLE_MS) {
+          this.sessionId = this.newId("ses");
+          sessionStorage.setItem("clamp_sid", this.sessionId);
+        }
+        this.hiddenAt = null;
+        this.startEngagement();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      this.stopEngagement();
+      this.sendPageviewEnd();
+      this.flush(true);
     });
-    window.addEventListener("pagehide", onHide);
+    this.startEngagement();
   }
   track(name, properties) {
     if (!this.initialized) {
@@ -96,8 +127,57 @@ var BrowserClient = class {
   }
   // ── Private ─────────────────────────────────────────────────────────
   pageview() {
+    const path = location.pathname + location.search;
+    const now = Date.now();
+    if (path === this.lastPageviewPath && now - this.lastPageviewTime < 500) return;
+    if (this.lastPageviewPath !== null) {
+      this.sendPageviewEnd();
+    }
+    this.lastPageviewPath = path;
+    this.lastPageviewTime = now;
+    this.engagementSeconds = 0;
+    this.pageviewEndSent = false;
     this.track("pageview");
   }
+  startEngagement() {
+    if (this.engagementTimer) return;
+    this.engagementTimer = setInterval(() => {
+      if (document.visibilityState === "visible") {
+        this.engagementSeconds += 1;
+      }
+    }, 1e3);
+  }
+  stopEngagement() {
+    if (this.engagementTimer) {
+      clearInterval(this.engagementTimer);
+      this.engagementTimer = null;
+    }
+  }
+  sendPageviewEnd() {
+    if (this.pageviewEndSent || this.engagementSeconds < 1 || !this.lastPageviewPath) return;
+    this.pageviewEndSent = true;
+    const payload = {
+      p: this.projectId,
+      events: [{
+        name: "pageview_end",
+        url: location.origin + this.lastPageviewPath,
+        referrer: "",
+        sessionId: this.sessionId,
+        anonymousId: this.anonymousId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        platform: "web",
+        properties: { engagement_seconds: String(this.engagementSeconds) }
+      }]
+    };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body, keepalive: true }).catch(() => {
+      });
+    }
+  }
   flush(useBeacon = false) {
     if (!this.projectId || this.queue.length === 0) return;
     const events = this.queue.splice(0, 100);

package/dist/react.mjs

@@ -5,6 +5,7 @@ import { useEffect } from "react";
 
 // src/index.ts
 var DEFAULT_ENDPOINT = "https://api.clamp.sh";
+var SESSION_IDLE_MS = 30 * 60 * 1e3;
 var BrowserClient = class {
   constructor() {
     this.projectId = null;
@@ -13,8 +14,16 @@ var BrowserClient = class {
     this.anonymousId = null;
     this.queue = [];
     this.preInitQueue = [];
-    this.timer = null;
     this.initialized = false;
+    // Dedup state
+    this.lastPageviewPath = null;
+    this.lastPageviewTime = 0;
+    // Engagement tracking
+    this.engagementSeconds = 0;
+    this.engagementTimer = null;
+    this.pageviewEndSent = false;
+    // Session idle tracking
+    this.hiddenAt = null;
   }
   init(projectId, opts) {
     if (typeof window === "undefined") return;
@@ -41,12 +50,34 @@ var BrowserClient = class {
       this.pageview();
     };
     window.addEventListener("popstate", () => this.pageview());
-    this.timer = setInterval(() => this.flush(), 5e3);
-    const onHide = () => this.flush(true);
+    window.addEventListener("pageshow", (e) => {
+      if (e.persisted) {
+        this.pageviewEndSent = false;
+        this.pageview();
+      }
+    });
+    setInterval(() => this.flush(), 5e3);
     document.addEventListener("visibilitychange", () => {
-      if (document.visibilityState === "hidden") onHide();
+      if (document.visibilityState === "hidden") {
+        this.hiddenAt = Date.now();
+        this.stopEngagement();
+        this.sendPageviewEnd();
+        this.flush(true);
+      } else {
+        if (this.hiddenAt !== null && Date.now() - this.hiddenAt >= SESSION_IDLE_MS) {
+          this.sessionId = this.newId("ses");
+          sessionStorage.setItem("clamp_sid", this.sessionId);
+        }
+        this.hiddenAt = null;
+        this.startEngagement();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      this.stopEngagement();
+      this.sendPageviewEnd();
+      this.flush(true);
     });
-    window.addEventListener("pagehide", onHide);
+    this.startEngagement();
   }
   track(name, properties) {
     if (!this.initialized) {
@@ -73,8 +104,57 @@ var BrowserClient = class {
   }
   // ── Private ─────────────────────────────────────────────────────────
   pageview() {
+    const path = location.pathname + location.search;
+    const now = Date.now();
+    if (path === this.lastPageviewPath && now - this.lastPageviewTime < 500) return;
+    if (this.lastPageviewPath !== null) {
+      this.sendPageviewEnd();
+    }
+    this.lastPageviewPath = path;
+    this.lastPageviewTime = now;
+    this.engagementSeconds = 0;
+    this.pageviewEndSent = false;
     this.track("pageview");
   }
+  startEngagement() {
+    if (this.engagementTimer) return;
+    this.engagementTimer = setInterval(() => {
+      if (document.visibilityState === "visible") {
+        this.engagementSeconds += 1;
+      }
+    }, 1e3);
+  }
+  stopEngagement() {
+    if (this.engagementTimer) {
+      clearInterval(this.engagementTimer);
+      this.engagementTimer = null;
+    }
+  }
+  sendPageviewEnd() {
+    if (this.pageviewEndSent || this.engagementSeconds < 1 || !this.lastPageviewPath) return;
+    this.pageviewEndSent = true;
+    const payload = {
+      p: this.projectId,
+      events: [{
+        name: "pageview_end",
+        url: location.origin + this.lastPageviewPath,
+        referrer: "",
+        sessionId: this.sessionId,
+        anonymousId: this.anonymousId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        platform: "web",
+        properties: { engagement_seconds: String(this.engagementSeconds) }
+      }]
+    };
+    const url = `${this.endpoint}/e/batch`;
+    const body = JSON.stringify(payload);
+    if (typeof navigator.sendBeacon === "function") {
+      navigator.sendBeacon(url, body);
+    } else {
+      fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body, keepalive: true }).catch(() => {
+      });
+    }
+  }
   flush(useBeacon = false) {
     if (!this.projectId || this.queue.length === 0) return;
     const events = this.queue.splice(0, 100);

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "@clamp-sh/analytics",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Lightweight analytics SDK for Clamp. Auto-pageviews, sessions, batching. Browser, server, and React.",
   "license": "MIT",
   "homepage": "https://clamp.sh",
   "repository": {
     "type": "git",
-    "url": "https://github.com/clamp-sh/analytics"
+    "url": "git+https://github.com/clamp-sh/clamp.git",
+    "directory": "packages/sdk"
   },
-  "keywords": ["analytics", "tracking", "pageviews", "sessions", "react", "nextjs"],
+  "keywords": [
+    "analytics",
+    "tracking",
+    "pageviews",
+    "sessions",
+    "react",
+    "nextjs"
+  ],
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -29,7 +37,9 @@
       "require": "./dist/react.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
@@ -40,7 +50,9 @@
     "react": ">=18"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true }
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "react": "^19",