@unifeather/tracker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dennis Hendricks
+
+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

@@ -0,0 +1,68 @@
+# @unifeather/tracker
+
+Tiny (~1 KB) privacy-friendly client-side tracker for
+[unifeather](https://github.com/dennishendricks/unifeather). Minimal by default —
+no cookies, no persistent ids — so it's usable without a consent banner. Cookie
+id, session id and custom properties are explicitly opt-in.
+
+```sh
+bun add @unifeather/tracker   # or: npm i @unifeather/tracker
+```
+
+```ts
+import { createTracker } from "@unifeather/tracker";
+
+// Privacy-friendly default: auto pageview with active time, nothing else.
+const tracker = createTracker({ endpoint: "/collect" });
+tracker.track("signup"); // custom event
+```
+
+Prefer no build step? Copy-paste the self-hosted `<script>` snippet
+(`@unifeather/tracker/snippet`) instead — see the
+[main README](https://github.com/dennishendricks/unifeather#readme).
+
+## Parameters
+
+### `createTracker(options)`
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `endpoint` | URL of the collect endpoint (e.g. `"https://analytics.example.com/collect"`). | **required** |
+| `userId` | App-provided stable user id (e.g. a logged-in user). Takes precedence over `cookieId`. | optional |
+| `cookieId` | Anonymous id in a long-lived first-party cookie. `true` for defaults, or a `CookieOptions` object. Ignored if `userId` is set. Opt-in, typically needs user consent. | optional |
+| `session` | Session id in a short-lived, sliding-expiry cookie. `true` for defaults, or a `SessionOptions` object. Opt-in. | optional |
+| `properties` | Custom properties object merged into every event. | optional |
+| `maxActiveMs` | Cap on measured active (foreground) time, in milliseconds. Defaults to `600000` (10 min). | optional |
+| `autoTrack` | Send a pageview automatically when the page is hidden/unloaded. Defaults to `true`. | optional |
+| `includeScreen` | Include screen width/height in events. Defaults to `true`. | optional |
+
+### `CookieOptions` (passed to `cookieId`)
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| `name` | Cookie name. | `"uf_uid"` |
+| `maxAgeDays` | Cookie lifetime in days. | `365` |
+| `sameSite` | `SameSite` policy — `"Lax"` \| `"Strict"` \| `"None"`. | `"Lax"` |
+
+### `SessionOptions` (passed to `session`)
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| `name` | Cookie name. | `"uf_sid"` |
+| `timeoutMinutes` | Inactivity timeout before the session cookie lapses (sliding). | `30` |
+| `sameSite` | `SameSite` policy — `"Lax"` \| `"Strict"` \| `"None"`. | `"Lax"` |
+
+### Snippet `data-*` attributes
+
+The `@unifeather/tracker/snippet` build reads these from the `<script>` tag. Cookie
+and session are booleans only — for nested options use `createTracker`.
+
+| Attribute | Description | Default / required |
+| --- | --- | --- |
+| `data-endpoint` | Collect endpoint URL. | **required** |
+| `data-user-id` | App-provided stable user id. | optional |
+| `data-cookie-id` | Enable the anonymous cookie id (`""` or `"true"` to enable). | optional |
+| `data-session` | Enable the session id (`""` or `"true"` to enable). | optional |
+| `data-props` | Custom properties as a JSON object, e.g. `'{"plan":"pro"}'`. Malformed JSON is ignored. | optional |
+
+MIT © Dennis Hendricks

package/dist/chunk-TH4L6Z4L.js

@@ -0,0 +1,96 @@
+// src/cookie.ts
+var uuid = () => crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+var readCookie = (name) => {
+  const prefix = `${name}=`;
+  for (const part of document.cookie.split("; ")) {
+    if (part.startsWith(prefix)) return decodeURIComponent(part.slice(prefix.length));
+  }
+  return void 0;
+};
+var writeCookie = (name, value, maxAgeSeconds, sameSite = "Lax") => {
+  const secure = location.protocol === "https:" ? "; Secure" : "";
+  document.cookie = `${name}=${encodeURIComponent(value)}; Max-Age=${maxAgeSeconds}; Path=/; SameSite=${sameSite}${secure}`;
+};
+var getOrCreateCookieId = (options = {}) => {
+  const name = options.name ?? "uf_uid";
+  const existing = readCookie(name);
+  if (existing) return existing;
+  const id = uuid();
+  writeCookie(name, id, (options.maxAgeDays ?? 365) * 86400, options.sameSite);
+  return id;
+};
+
+// src/session.ts
+var getSessionId = (options = {}) => {
+  const name = options.name ?? "uf_sid";
+  const timeoutSeconds = (options.timeoutMinutes ?? 30) * 60;
+  const id = readCookie(name) ?? uuid();
+  writeCookie(name, id, timeoutSeconds, options.sameSite);
+  return id;
+};
+
+// src/index.ts
+var uuid2 = () => crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+var post = (endpoint, payload) => {
+  const body = JSON.stringify(payload);
+  if (navigator.sendBeacon?.(endpoint, new Blob([body], { type: "application/json" }))) return;
+  void fetch(endpoint, {
+    method: "POST",
+    body,
+    headers: { "Content-Type": "application/json" },
+    keepalive: true
+  }).catch(() => {
+  });
+};
+var createTracker = (options) => {
+  const { endpoint, maxActiveMs = 10 * 60 * 1e3, autoTrack = true, includeScreen = true } = options;
+  const userId = options.userId ?? (options.cookieId ? getOrCreateCookieId(typeof options.cookieId === "object" ? options.cookieId : {}) : void 0);
+  const sessionId = options.session ? getSessionId(typeof options.session === "object" ? options.session : {}) : void 0;
+  let activeMs = 0;
+  let resumedAt = document.hasFocus() ? performance.now() : null;
+  const accumulate = () => {
+    if (resumedAt !== null) activeMs = Math.min(activeMs + (performance.now() - resumedAt), maxActiveMs);
+  };
+  const resume = () => {
+    if (resumedAt === null && activeMs < maxActiveMs) resumedAt = performance.now();
+  };
+  const pause = () => {
+    accumulate();
+    resumedAt = null;
+  };
+  const track = (name = "pageview", properties) => {
+    accumulate();
+    const merged = options.properties || properties ? { ...options.properties, ...properties } : void 0;
+    post(endpoint, {
+      eventId: uuid2(),
+      name,
+      timestamp: Date.now(),
+      url: location.href,
+      referrer: document.referrer || void 0,
+      language: navigator.language,
+      activeSeconds: Math.round(activeMs / 1e3),
+      screenWidth: includeScreen ? screen.width : void 0,
+      screenHeight: includeScreen ? screen.height : void 0,
+      userId,
+      sessionId,
+      properties: merged
+    });
+  };
+  if (autoTrack) {
+    let sent = false;
+    const flush = () => {
+      if (sent) return;
+      sent = true;
+      pause();
+      track("pageview");
+    };
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") flush();
+      else resume();
+    });
+    addEventListener("pagehide", flush);
+  }
+  return { track, pageview: (properties) => track("pageview", properties) };
+};
+
+export { createTracker };

package/dist/cookie.d.ts

@@ -0,0 +1,21 @@
+export type SameSite = "Lax" | "Strict" | "None";
+/** Options for the opt-in cookie-based anonymous user id. */
+export interface CookieOptions {
+    /** Cookie name. Defaults to "uf_uid". */
+    readonly name?: string;
+    /** Lifetime in days. Defaults to 365. */
+    readonly maxAgeDays?: number;
+    /** SameSite policy. Defaults to "Lax". */
+    readonly sameSite?: SameSite;
+}
+/** Generate a random id (RFC 4122 UUID when available). Shared internal helper. */
+export declare const uuid: () => string;
+/** Read a cookie value by name, or undefined. Shared internal helper. */
+export declare const readCookie: (name: string) => string | undefined;
+/** Write a cookie. Shared internal helper. `Secure` is added on HTTPS. */
+export declare const writeCookie: (name: string, value: string, maxAgeSeconds: number, sameSite?: SameSite) => void;
+/**
+ * Read the anonymous user id from a long-lived first-party cookie, creating and
+ * persisting a new random id on first visit. Opt-in — typically requires consent.
+ */
+export declare const getOrCreateCookieId: (options?: CookieOptions) => string;

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import type { Properties } from "@unifeather/core";
+import { type CookieOptions } from "./cookie.js";
+import { type SessionOptions } from "./session.js";
+export type { CookieOptions } from "./cookie.js";
+export type { SessionOptions } from "./session.js";
+export interface TrackerOptions {
+    /** URL of the collect endpoint (e.g. "https://analytics.example.com/collect"). */
+    readonly endpoint: string;
+    /**
+     * Custom, app-provided user id. Takes precedence over `cookieId`. Use this
+     * when you already have a stable id (e.g. a logged-in user).
+     */
+    readonly userId?: string;
+    /**
+     * Anonymous user id persisted in a long-lived first-party cookie. `true` for
+     * defaults or pass options. Opt-in — typically requires consent. Ignored if
+     * `userId` is set.
+     */
+    readonly cookieId?: boolean | CookieOptions;
+    /** Session id in a short-lived, sliding-expiry cookie. Opt-in. */
+    readonly session?: boolean | SessionOptions;
+    /** Custom properties merged into every event. */
+    readonly properties?: Properties;
+    /** Cap on measured active time, in ms. Defaults to 10 minutes. */
+    readonly maxActiveMs?: number;
+    /** Send a pageview automatically when the page is hidden. Defaults to true. */
+    readonly autoTrack?: boolean;
+    /** Include screen width/height. Defaults to true. */
+    readonly includeScreen?: boolean;
+}
+export interface Tracker {
+    /** Send a custom event. Defaults to a "pageview". */
+    track: (name?: string, properties?: Properties) => void;
+    /** Convenience alias for a pageview (e.g. on SPA route changes). */
+    pageview: (properties?: Properties) => void;
+}
+/**
+ * Create a tracker. Minimal by default (no cookies, no ids). Enable
+ * `cookieId`, `session`, `userId` and `properties` as needed.
+ */
+export declare const createTracker: (options: TrackerOptions) => Tracker;

package/dist/index.js

@@ -0,0 +1 @@
+export { createTracker } from './chunk-TH4L6Z4L.js';

package/dist/session.d.ts

@@ -0,0 +1,16 @@
+import { type SameSite } from "./cookie.js";
+/** Options for the opt-in cookie-based session id. */
+export interface SessionOptions {
+    /** Cookie name. Defaults to "uf_sid". */
+    readonly name?: string;
+    /** Inactivity timeout in minutes before the session cookie expires. Defaults to 30. */
+    readonly timeoutMinutes?: number;
+    /** SameSite policy. Defaults to "Lax". */
+    readonly sameSite?: SameSite;
+}
+/**
+ * Return the current session id from a short-lived first-party cookie. The
+ * cookie is written with a sliding expiry equal to the inactivity timeout, so
+ * it renews on each event and lapses after the visitor is idle. Opt-in.
+ */
+export declare const getSessionId: (options?: SessionOptions) => string;

package/dist/snippet.d.ts

@@ -0,0 +1,11 @@
+import { type Tracker } from "./index.js";
+/**
+ * Initialize a tracker from a `<script>` tag's `data-*` attributes. Reads the
+ * currently executing script (or the last matching one). Returns the tracker,
+ * or undefined if no endpoint is configured.
+ *
+ * Supported attributes:
+ *   data-endpoint (required)  data-user-id  data-cookie-id
+ *   data-session              data-props (JSON object)
+ */
+export declare const initFromScript: (script?: HTMLScriptElement) => Tracker | undefined;

package/dist/snippet.global.js

@@ -0,0 +1 @@
+(function(){'use strict';var p=()=>crypto.randomUUID?.()??`${Date.now()}-${Math.random().toString(36).slice(2)}`,u=e=>{let t=`${e}=`;for(let o of document.cookie.split("; "))if(o.startsWith(t))return decodeURIComponent(o.slice(t.length))},m=(e,t,o,r="Lax")=>{let a=location.protocol==="https:"?"; Secure":"";document.cookie=`${e}=${encodeURIComponent(t)}; Max-Age=${o}; Path=/; SameSite=${r}${a}`;},f=(e={})=>{let t=e.name??"uf_uid",o=u(t);if(o)return o;let r=p();return m(t,r,(e.maxAgeDays??365)*86400,e.sameSite),r};var g=(e={})=>{let t=e.name??"uf_sid",o=(e.timeoutMinutes??30)*60,r=u(t)??p();return m(t,r,o,e.sameSite),r};var O=()=>crypto.randomUUID?.()??`${Date.now()}-${Math.random().toString(36).slice(2)}`,b=(e,t)=>{let o=JSON.stringify(t);navigator.sendBeacon?.(e,new Blob([o],{type:"application/json"}))||fetch(e,{method:"POST",body:o,headers:{"Content-Type":"application/json"},keepalive:true}).catch(()=>{});},S=e=>{let{endpoint:t,maxActiveMs:o=600*1e3,autoTrack:r=true,includeScreen:a=true}=e,v=e.userId??(e.cookieId?f(typeof e.cookieId=="object"?e.cookieId:{}):void 0),h=e.session?g(typeof e.session=="object"?e.session:{}):void 0,c=0,i=document.hasFocus()?performance.now():null,l=()=>{i!==null&&(c=Math.min(c+(performance.now()-i),o));},x=()=>{i===null&&c<o&&(i=performance.now());},I=()=>{l(),i=null;},d=(n="pageview",s)=>{l();let w=e.properties||s?{...e.properties,...s}:void 0;b(t,{eventId:O(),name:n,timestamp:Date.now(),url:location.href,referrer:document.referrer||void 0,language:navigator.language,activeSeconds:Math.round(c/1e3),screenWidth:a?screen.width:void 0,screenHeight:a?screen.height:void 0,userId:v,sessionId:h,properties:w});};if(r){let n=false,s=()=>{n||(n=true,I(),d("pageview"));};document.addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"?s():x();}),addEventListener("pagehide",s);}return {track:d,pageview:n=>d("pageview",n)}};var y=e=>e===""||e==="true",k=e=>{let t=document.currentScript??document.querySelector("script[data-endpoint]");if(!t)return;let o=t.dataset.endpoint;if(!o)return;let r;if(t.dataset.props)try{r=JSON.parse(t.dataset.props);}catch{}return S({endpoint:o,userId:t.dataset.userId,cookieId:y(t.dataset.cookieId),session:y(t.dataset.session),properties:r})};window.unifeather=k();})();

package/dist/snippet.iife.d.ts

@@ -0,0 +1,6 @@
+import { initFromScript } from "./snippet.js";
+declare global {
+    interface Window {
+        unifeather?: ReturnType<typeof initFromScript>;
+    }
+}

package/dist/snippet.js

@@ -0,0 +1,26 @@
+import { createTracker } from './chunk-TH4L6Z4L.js';
+
+// src/snippet.ts
+var bool = (value) => value === "" || value === "true";
+var initFromScript = (script) => {
+  const el = script ?? document.currentScript ?? document.querySelector("script[data-endpoint]");
+  if (!el) return void 0;
+  const endpoint = el.dataset.endpoint;
+  if (!endpoint) return void 0;
+  let properties;
+  if (el.dataset.props) {
+    try {
+      properties = JSON.parse(el.dataset.props);
+    } catch {
+    }
+  }
+  return createTracker({
+    endpoint,
+    userId: el.dataset.userId,
+    cookieId: bool(el.dataset.cookieId),
+    session: bool(el.dataset.session),
+    properties
+  });
+};
+
+export { initFromScript };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@unifeather/tracker",
+  "version": "0.1.0",
+  "description": "Tiny (~1KB) privacy-friendly client-side tracker. Minimal by default; cookie id, session id and custom properties are opt-in.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Dennis Hendricks <dennis@hendricks.rocks>",
+  "keywords": [
+    "analytics",
+    "privacy",
+    "web-analytics",
+    "tracking",
+    "tracker",
+    "browser",
+    "lightweight"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dennishendricks/unifeather.git",
+    "directory": "packages/tracker"
+  },
+  "homepage": "https://github.com/dennishendricks/unifeather#readme",
+  "bugs": "https://github.com/dennishendricks/unifeather/issues",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./snippet": {
+      "types": "./dist/snippet.d.ts",
+      "import": "./dist/snippet.js",
+      "default": "./dist/snippet.global.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepublishOnly": "bun run build",
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@unifeather/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}