@pantho075/trackima 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pantho Haque
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @pantho075/trackima
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser tracker for [Trackima](https://trackima.vercel.app): pageviews, custom events and visitor history,
+batched in the browser and sent at most every 10 minutes (or when the tab is hidden). No cookies,
+about 2 KB gzipped, and it never throws into your page.
+
+## Script tag
+
+```html
+<script defer src="https://trackima.pantho-haque-dev.workers.dev/t.js" data-site="YOUR_SITE_ID"></script>
+<!-- optional: data-consent="required" keeps ids in memory until trackima.consent(true) -->
+```
+
+```js
+trackima.event("signup", { plan: "pro" });   // up to 10 props: text, numbers, true/false
+trackima.identify("user_42", { plan: "pro" }); // after your login: links this browser to your user id
+trackima.reset();                              // on logout
+```
+
+No-code events: `<button data-trackima-event="signup" data-trackima-plan="pro">`.
+
+## npm
+
+```sh
+pnpm add @pantho075/trackima
+```
+
+```ts
+import { init, event, identify, reset, consent } from "@pantho075/trackima";
+
+init({ site: "YOUR_SITE_ID", host: "https://trackima.pantho-haque-dev.workers.dev" });
+event("add_to_cart", { item: "mug", price: 12 });
+```
+
+| Option | Default | |
+|---|---|---|
+| `site` | required | 12-character site id from the dashboard (Setup & settings) |
+| `host` | required | the Trackima Worker, `https://trackima.pantho-haque-dev.workers.dev` |
+| `consent` | `"granted"` | `"required"`: nothing in localStorage until `consent(true)` |
+| `flushInterval` | `600000` | ms between timed sends |
+| `maxBatch` | `50` | send as soon as this many events are queued |
+| `spa` | `true` | count `history.pushState` / `popstate` route changes |
+
+Delivery: batches carry ids, so retries never double-count. Failed sends retry after 1, 5 and 15
+minutes; a 429 (daily limit) pauses until midnight UTC. Unsent batches from a closed or crashed tab are
+picked up by the next tab after 15 minutes.

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+export type Props = Record<string, string | number | boolean>;
+export type Options = {
+    /** 12-character site id from the Trackima dashboard */
+    site: string;
+    /** Trackima server origin, e.g. "https://trackima.example.workers.dev" */
+    host: string;
+    /** "required": keep ids in memory only until consent(true). Default "granted". */
+    consent?: "granted" | "required";
+    /** ms between timed sends. Default 10 minutes. */
+    flushInterval?: number;
+    /** send as soon as this many events are queued. Default 50. */
+    maxBatch?: number;
+    /** count history.pushState / replaceState / popstate route changes. Default true. */
+    spa?: boolean;
+};
+export type Batch = {
+    s: string;
+    v: string;
+    x?: string;
+    t?: Props;
+    ss: string;
+    st: number;
+    b: string;
+    pv: [number, string][];
+    ev: ([number, string] | [number, string, Props])[];
+    r?: string;
+    u?: Record<string, string>;
+};
+type Pending = Omit<Batch, "s" | "b">;
+export declare const randomId: (prefix: string, n: number) => string;
+export declare function createTracker(opts: Options): {
+    event: (name: string, props?: Props) => void;
+    identify(id: string, t?: Props): void;
+    reset(): void;
+    consent(granted: boolean): void;
+    flush: () => Promise<void>;
+    /** for tests and hot reloads */
+    destroy(): void;
+    readonly state: {
+        outbox: Batch[];
+        queue: Pending | null;
+        pausedUntil: number;
+        fails: number;
+    };
+};
+export type Tracker = ReturnType<typeof createTracker>;
+export declare function init(opts: Options): {
+    event: (name: string, props?: Props) => void;
+    identify(id: string, t?: Props): void;
+    reset(): void;
+    consent(granted: boolean): void;
+    flush: () => Promise<void>;
+    /** for tests and hot reloads */
+    destroy(): void;
+    readonly state: {
+        outbox: Batch[];
+        queue: Pending | null;
+        pausedUntil: number;
+        fails: number;
+    };
+} | null;
+export declare const event: (name: string, props?: Props) => void | undefined;
+export declare const identify: (id: string, traits?: Props) => void | undefined;
+export declare const reset: () => void | undefined;
+export declare const consent: (granted: boolean) => void | undefined;
+export declare const flush: () => Promise<void> | undefined;
+/** what is queued right now (for the playground and debugging) */
+export declare const state: () => {
+    outbox: Batch[];
+    queue: Pending | null;
+    pausedUntil: number;
+    fails: number;
+} | undefined;
+export {};

package/dist/index.js

@@ -0,0 +1,265 @@
+// src/index.ts
+var SESSION_IDLE_MS = 30 * 6e4;
+var ORPHAN_MS = 15 * 6e4;
+var MAX_EVENTS = 1e3;
+var GIVE_UP = [400, 403, 404, 409, 413];
+var randomId = (prefix, n) => {
+  const a = crypto.getRandomValues(new Uint8Array(n));
+  return prefix + Array.from(a, (x) => "abcdefghijklmnopqrstuvwxyz0123456789"[x % 36]).join("");
+};
+var nextUtcMidnight = () => {
+  const d = /* @__PURE__ */ new Date();
+  d.setUTCHours(24, 0, 0, 0);
+  return d.getTime();
+};
+var parse = (s) => {
+  try {
+    return s ? JSON.parse(s) : null;
+  } catch {
+    return null;
+  }
+};
+function createTracker(opts) {
+  const site = opts.site, endpoint = opts.host.replace(/\/$/, "") + "/e";
+  const maxBatch = opts.maxBatch ?? 50, tab = randomId("", 8), myKey = `tq:${site}:${tab}`;
+  const mem = /* @__PURE__ */ new Map();
+  let persist = opts.consent !== "required";
+  const store = {
+    get: (k) => {
+      if (persist) try {
+        return localStorage.getItem(k);
+      } catch {
+      }
+      return mem.get(k) ?? null;
+    },
+    set: (k, v) => {
+      mem.set(k, v);
+      if (persist) try {
+        localStorage.setItem(k, v);
+      } catch {
+      }
+    },
+    del: (k) => {
+      mem.delete(k);
+      try {
+        localStorage.removeItem(k);
+      } catch {
+      }
+    },
+    keys: () => {
+      try {
+        return Object.keys(localStorage);
+      } catch {
+        return [...mem.keys()];
+      }
+    }
+  };
+  let outbox = [], q = null, traits;
+  let pausedUntil = 0, fails = 0, busy = false, lastPath = "";
+  const cleanups = [];
+  const save = () => store.set(myKey, JSON.stringify({ outbox, q, at: Date.now() }));
+  const visitor = () => {
+    let v = store.get("trackima:v");
+    if (!v) store.set("trackima:v", v = randomId("v_", 16));
+    return v;
+  };
+  function session(now) {
+    let s = parse(store.get("trackima:s"));
+    if (!s || now - s.last > SESSION_IDLE_MS) {
+      const ref = document.referrer ? new URL(document.referrer).hostname : "";
+      const u = {};
+      new URLSearchParams(location.search).forEach((val, key) => {
+        if (key.startsWith("utm_") && val) u[key] = val;
+      });
+      s = { id: randomId("s_", 10), start: Math.floor(now / 1e3), last: now };
+      if (ref && ref !== location.hostname) s.r = ref;
+      if (Object.keys(u).length) s.u = u;
+    }
+    s.last = now;
+    store.set("trackima:s", JSON.stringify(s));
+    return s;
+  }
+  function seal() {
+    if (!q || !q.pv.length && !q.ev.length) return;
+    const b = { s: site, b: randomId("", 10), ...q };
+    if (traits) {
+      b.t = traits;
+      traits = void 0;
+    }
+    outbox.push(b);
+    q = { ...q, pv: [], ev: [], r: void 0, u: void 0 };
+    let total = outbox.reduce((n, x) => n + x.pv.length + x.ev.length, 0);
+    while (total > MAX_EVENTS && outbox.length > 1) {
+      const dropped = outbox.shift();
+      total -= dropped.pv.length + dropped.ev.length;
+    }
+  }
+  function record(kind, name, props) {
+    const now = Date.now(), s = session(now), v = visitor(), x = store.get("trackima:x") ?? void 0;
+    if (!q || q.ss !== s.id || q.v !== v) {
+      seal();
+      q = { v, ss: s.id, st: s.start, pv: [], ev: [], ...x && { x }, ...s.r && { r: s.r }, ...s.u && { u: s.u } };
+    }
+    const off = Math.max(0, Math.floor(now / 1e3) - q.st);
+    if (kind === "pv") q.pv.push([off, name]);
+    else q.ev.push(props && Object.keys(props).length ? [off, name, props] : [off, name]);
+    save();
+    if (q.pv.length + q.ev.length >= maxBatch) void flush2(false);
+  }
+  async function deliver(beacon) {
+    if (busy || Date.now() < pausedUntil) return;
+    while (outbox.length) {
+      const batch = outbox[0], body = JSON.stringify(batch);
+      if (beacon && navigator.sendBeacon) {
+        if (!navigator.sendBeacon(endpoint, new Blob([body], { type: "text/plain" }))) break;
+        outbox.shift();
+        save();
+        continue;
+      }
+      busy = true;
+      let status = 0;
+      try {
+        const res = await fetch(endpoint, { method: "POST", body, keepalive: body.length < 6e4, credentials: "omit", headers: { "Content-Type": "text/plain" } });
+        status = res.status;
+      } catch {
+      } finally {
+        busy = false;
+      }
+      if (status >= 200 && status < 300 || GIVE_UP.includes(status)) {
+        outbox.shift();
+        fails = 0;
+        save();
+        continue;
+      }
+      if (status === 429) {
+        pausedUntil = nextUtcMidnight();
+        break;
+      }
+      fails++;
+      pausedUntil = fails > 3 ? nextUtcMidnight() : Date.now() + [6e4, 3e5, 9e5][fails - 1];
+      break;
+    }
+  }
+  async function flush2(beacon = false) {
+    seal();
+    save();
+    await deliver(beacon);
+  }
+  function pageview() {
+    const path = location.pathname;
+    if (path === lastPath) return;
+    lastPath = path;
+    record("pv", path);
+  }
+  function adoptOrphans() {
+    for (const key of store.keys()) {
+      if (!key.startsWith(`tq:${site}:`) || key === myKey) continue;
+      const saved = parse(store.get(key));
+      if (!saved || Date.now() - saved.at < ORPHAN_MS) continue;
+      outbox.push(...saved.outbox);
+      if (saved.q && (saved.q.pv.length || saved.q.ev.length)) outbox.push({ s: site, b: randomId("", 10), ...saved.q });
+      store.del(key);
+    }
+  }
+  const on = (target, type, fn) => {
+    target.addEventListener(type, fn);
+    cleanups.push(() => target.removeEventListener(type, fn));
+  };
+  adoptOrphans();
+  pageview();
+  const timer = setInterval(() => void flush2(false), opts.flushInterval ?? 6e5);
+  const heartbeat = setInterval(save, 6e4);
+  cleanups.push(() => {
+    clearInterval(timer);
+    clearInterval(heartbeat);
+  });
+  on(document, "visibilitychange", () => {
+    if (document.visibilityState === "hidden") void flush2(true);
+  });
+  on(window, "pagehide", () => void flush2(true));
+  on(document, "click", (e) => {
+    const el = e.target?.closest?.("[data-trackima-event]");
+    if (!el) return;
+    const props = {};
+    for (const [k, v] of Object.entries(el.dataset)) if (k.startsWith("trackima") && k !== "trackimaEvent" && v) props[k.slice(8, 9).toLowerCase() + k.slice(9)] = v;
+    record("ev", el.dataset.trackimaEvent, props);
+  });
+  if (opts.spa !== false) {
+    for (const m of ["pushState", "replaceState"]) {
+      const orig = history[m];
+      history[m] = function(...args) {
+        const r = orig.apply(this, args);
+        pageview();
+        return r;
+      };
+      cleanups.push(() => {
+        history[m] = orig;
+      });
+    }
+    on(window, "popstate", pageview);
+  }
+  if (outbox.length) void deliver(false);
+  return {
+    event: (name, props) => record("ev", name, props),
+    identify(id, t) {
+      store.set("trackima:x", String(id).slice(0, 128));
+      if (q) q.x = String(id).slice(0, 128);
+      if (t) traits = t;
+    },
+    reset() {
+      void flush2(false);
+      for (const k of ["trackima:v", "trackima:s", "trackima:x"]) store.del(k);
+      q = null;
+    },
+    consent(granted) {
+      if (granted && !persist) {
+        persist = true;
+        for (const [k, v] of mem) store.set(k, v);
+      }
+      if (!granted) {
+        persist = false;
+        for (const k of ["trackima:v", "trackima:s", "trackima:x", myKey]) try {
+          localStorage.removeItem(k);
+        } catch {
+        }
+      }
+    },
+    flush: () => flush2(false),
+    /** for tests and hot reloads */
+    destroy() {
+      cleanups.forEach((f) => f());
+    },
+    get state() {
+      return { outbox, queue: q, pausedUntil, fails };
+    }
+  };
+}
+var current = null;
+var safe = (fn) => {
+  try {
+    return fn();
+  } catch {
+    return void 0;
+  }
+};
+var usable = () => typeof window !== "undefined" && !navigator.webdriver;
+function init(opts) {
+  return safe(() => current ?? (current = usable() ? createTracker(opts) : null)) ?? null;
+}
+var event = (name, props) => safe(() => current?.event(name, props));
+var identify = (id, traits) => safe(() => current?.identify(id, traits));
+var reset = () => safe(() => current?.reset());
+var consent = (granted) => safe(() => current?.consent(granted));
+var flush = () => safe(() => current?.flush());
+var state = () => safe(() => current?.state);
+export {
+  consent,
+  createTracker,
+  event,
+  flush,
+  identify,
+  init,
+  randomId,
+  reset,
+  state
+};

package/dist/t.js

@@ -0,0 +1 @@
+"use strict";(()=>{var F=[400,403,404,409,413],y=(s,l)=>{let S=crypto.getRandomValues(new Uint8Array(l));return s+Array.from(S,P=>"abcdefghijklmnopqrstuvwxyz0123456789"[P%36]).join("")},R=()=>{let s=new Date;return s.setUTCHours(24,0,0,0),s.getTime()},D=s=>{try{return s?JSON.parse(s):null}catch{return null}};function Q(s){let l=s.site,S=s.host.replace(/\/$/,"")+"/e",P=s.maxBatch??50,C=y("",8),_=`tq:${l}:${C}`,h=new Map,g=s.consent!=="required",c={get:t=>{if(g)try{return localStorage.getItem(t)}catch{}return h.get(t)??null},set:(t,e)=>{if(h.set(t,e),g)try{localStorage.setItem(t,e)}catch{}},del:t=>{h.delete(t);try{localStorage.removeItem(t)}catch{}},keys:()=>{try{return Object.keys(localStorage)}catch{return[...h.keys()]}}},o=[],i=null,k,x=0,p=0,T=!1,M="",w=[],v=()=>c.set(_,JSON.stringify({outbox:o,q:i,at:Date.now()})),K=()=>{let t=c.get("trackima:v");return t||c.set("trackima:v",t=y("v_",16)),t};function W(t){let e=D(c.get("trackima:s"));if(!e||t-e.last>18e5){let n=document.referrer?new URL(document.referrer).hostname:"",r={};new URLSearchParams(location.search).forEach((a,m)=>{m.startsWith("utm_")&&a&&(r[m]=a)}),e={id:y("s_",10),start:Math.floor(t/1e3),last:t},n&&n!==location.hostname&&(e.r=n),Object.keys(r).length&&(e.u=r)}return e.last=t,c.set("trackima:s",JSON.stringify(e)),e}function B(){if(!i||!i.pv.length&&!i.ev.length)return;let t={s:l,b:y("",10),...i};k&&(t.t=k,k=void 0),o.push(t),i={...i,pv:[],ev:[],r:void 0,u:void 0};let e=o.reduce((n,r)=>n+r.pv.length+r.ev.length,0);for(;e>1e3&&o.length>1;){let n=o.shift();e-=n.pv.length+n.ev.length}}function O(t,e,n){let r=Date.now(),a=W(r),m=K(),N=c.get("trackima:x")??void 0;(!i||i.ss!==a.id||i.v!==m)&&(B(),i={v:m,ss:a.id,st:a.start,pv:[],ev:[],...N&&{x:N},...a.r&&{r:a.r},...a.u&&{u:a.u}});let q=Math.max(0,Math.floor(r/1e3)-i.st);t==="pv"?i.pv.push([q,e]):i.ev.push(n&&Object.keys(n).length?[q,e,n]:[q,e]),v(),i.pv.length+i.ev.length>=P&&d(!1)}async function L(t){if(!(T||Date.now()<x))for(;o.length;){let e=o[0],n=JSON.stringify(e);if(t&&navigator.sendBeacon){if(!navigator.sendBeacon(S,new Blob([n],{type:"text/plain"})))break;o.shift(),v();continue}T=!0;let r=0;try{r=(await fetch(S,{method:"POST",body:n,keepalive:n.length<6e4,credentials:"omit",headers:{"Content-Type":"text/plain"}})).status}catch{}finally{T=!1}if(r>=200&&r<300||F.includes(r)){o.shift(),p=0,v();continue}if(r===429){x=R();break}p++,x=p>3?R():Date.now()+[6e4,3e5,9e5][p-1];break}}async function d(t=!1){B(),v(),await L(t)}function I(){let t=location.pathname;t!==M&&(M=t,O("pv",t))}function X(){for(let t of c.keys()){if(!t.startsWith(`tq:${l}:`)||t===_)continue;let e=D(c.get(t));!e||Date.now()-e.at<9e5||(o.push(...e.outbox),e.q&&(e.q.pv.length||e.q.ev.length)&&o.push({s:l,b:y("",10),...e.q}),c.del(t))}}let E=(t,e,n)=>{t.addEventListener(e,n),w.push(()=>t.removeEventListener(e,n))};X(),I();let z=setInterval(()=>{d(!1)},s.flushInterval??6e5),G=setInterval(v,6e4);if(w.push(()=>{clearInterval(z),clearInterval(G)}),E(document,"visibilitychange",()=>{document.visibilityState==="hidden"&&d(!0)}),E(window,"pagehide",()=>{d(!0)}),E(document,"click",t=>{let e=t.target?.closest?.("[data-trackima-event]");if(!e)return;let n={};for(let[r,a]of Object.entries(e.dataset))r.startsWith("trackima")&&r!=="trackimaEvent"&&a&&(n[r.slice(8,9).toLowerCase()+r.slice(9)]=a);O("ev",e.dataset.trackimaEvent,n)}),s.spa!==!1){for(let t of["pushState","replaceState"]){let e=history[t];history[t]=function(...n){let r=e.apply(this,n);return I(),r},w.push(()=>{history[t]=e})}E(window,"popstate",I)}return o.length&&L(!1),{event:(t,e)=>O("ev",t,e),identify(t,e){c.set("trackima:x",String(t).slice(0,128)),i&&(i.x=String(t).slice(0,128)),e&&(k=e)},reset(){d(!1);for(let t of["trackima:v","trackima:s","trackima:x"])c.del(t);i=null},consent(t){if(t&&!g){g=!0;for(let[e,n]of h)c.set(e,n)}if(!t){g=!1;for(let e of["trackima:v","trackima:s","trackima:x",_])try{localStorage.removeItem(e)}catch{}}},flush:()=>d(!1),destroy(){w.forEach(t=>t())},get state(){return{outbox:o,queue:i,pausedUntil:x,fails:p}}}}var u=null,f=s=>{try{return s()}catch{return}},Y=()=>typeof window<"u"&&!navigator.webdriver;function U(s){return f(()=>u??(u=Y()?Q(s):null))??null}var j=(s,l)=>f(()=>u?.event(s,l)),H=(s,l)=>f(()=>u?.identify(s,l)),A=()=>f(()=>u?.reset()),J=s=>f(()=>u?.consent(s)),V=()=>f(()=>u?.flush()),$=()=>f(()=>u?.state);var b=document.currentScript;b?.dataset.site&&U({site:b.dataset.site,host:b.dataset.host??new URL(b.src).origin,consent:b.dataset.consent==="required"?"required":"granted"});window.trackima={event:j,identify:H,reset:A,consent:J,flush:V,state:$};})();

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@pantho075/trackima",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Browser tracker for Trackima: pageviews, events and visitor history, batched and cookie-free.",
+  "license": "MIT",
+  "author": "Pantho Haque",
+  "homepage": "https://trackima.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pantho-Haque/trackima.git",
+    "directory": "packages/tracker"
+  },
+  "bugs": "https://github.com/Pantho-Haque/trackima/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./t.js": "./dist/t.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "happy-dom": "^21.0.3",
+    "tsup": "^9.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "keywords": [
+    "analytics",
+    "tracker",
+    "pageviews",
+    "events",
+    "cloudflare",
+    "privacy"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }