@desert-ant-labs/desert-ant-web 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @desert-ant-labs/desert-ant-web
+
+Internal shared web/JS code for Desert Ant's on-device SDKs (`shapes`, `emo`, …).
+Currently it provides usage reporting: an active-device `load` event (the MAD
+turnstile) sent to our ingestion API.
+
+> **Not for direct use.** This package is published only so our SDKs can depend
+> on it. It has no stable public API and may change without notice — integrate a
+> Desert Ant SDK, not this.
+
+## API
+
+```ts
+import { initUsage } from "@desert-ant-labs/desert-ant-web";
+
+const usage = initUsage();  // keyless: the browser Origin identifies the site
+usage.recordCall();         // once per inference; rides the session's load event
+```
+
+- One `load` per device per session (30-min idle timeout); the server dedups by
+  device per month and sums `callCount` across events.
+- Zero dependencies, best-effort, never throws into the host.
+- `initUsage({ key?, endpoint?, callCount?, context?, disabled? })` — `endpoint`
+  overrides the default (e.g. staging). `@desert-ant-labs/desert-ant-web/core`
+  exposes the transport/storage-free `createClient`.
+
+## Develop
+
+```bash
+npm run build
+npm test              # offline unit tests
+DAL_LIVE=1 npm test   # also hits staging
+npm run check:pkg     # build + publint + attw
+```

package/dist/core.d.ts

@@ -0,0 +1,66 @@
+export declare const SDK_NAME = "desert-ant-web";
+export declare const SDK_VERSION = "0.1.0";
+export declare const DAY_MS: number;
+export declare const WEB_SESSION_MS: number;
+export type LoadContext = Record<string, unknown>;
+export interface IngestEvent {
+    name: "load";
+    deviceId: string;
+    callCount?: number;
+    timestamp?: string;
+    context?: LoadContext;
+}
+export interface IngestBody {
+    platform: "web";
+    key?: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    sentAt: string;
+    events: IngestEvent[];
+}
+/** Persisted per origin/instance, across sessions. */
+export interface UsageState {
+    /** Epoch ms we last emitted or went inactive (0 = never). Gates the next emit. */
+    lastActiveAt: number;
+    /** Calls accrued during throttled sessions, awaiting the next emitted load. */
+    carryCallCount: number;
+}
+export interface SendOptions {
+    /** Use the unload-safe transport (sendBeacon) where available. */
+    beacon?: boolean;
+}
+export interface ClientDeps {
+    deviceId: string;
+    key?: string;
+    /** Authoritative call count read at emit time; overrides recordCall() when set. */
+    callCount?: () => number;
+    /** Default context attached to auto-emitted loads. */
+    context?: () => LoadContext | undefined;
+    /** Re-emit window (ms): DAY_MS off-browser, WEB_SESSION_MS on web. */
+    windowMs: number;
+    now?: () => number;
+    loadState: () => UsageState;
+    saveState: (s: UsageState) => void;
+    send: (body: IngestBody, opts: SendOptions) => void;
+}
+export interface UsageClient {
+    /** Host calls this once per inference/call to attribute to the turnstile. */
+    recordCall(n?: number): void;
+    /** Force a turnstile now, ignoring the window. */
+    load(opts?: {
+        context?: LoadContext;
+    }): void;
+    /** Flush any pending event. `beacon: true` uses the unload-safe path. */
+    flush(opts?: SendOptions): void;
+    /** Evaluate the window and, if a new session/day is due, queue a turnstile.
+     *  Call on init and again on reactivation (e.g. tab becoming visible). */
+    start(): void;
+    /** Mark the app inactive (stamp the idle clock) and flush. Call on page hide. */
+    suspend(): void;
+}
+/** RFC 4122 v4, via crypto.randomUUID where available. */
+export declare function uuid(): string;
+export declare function buildBody(deviceId: string, key: string | undefined, events: IngestEvent[]): IngestBody;
+export declare function createClient(deps: ClientDeps): UsageClient;

package/dist/core.js

@@ -0,0 +1,112 @@
+// Wire format + client state machine for the usage turnstile.
+//
+// Transport- and storage-free by design: the platform entries (browser / node)
+// inject a stable `deviceId`, persisted-state access, and a `send` transport.
+// Exposed at "@desert-ant-labs/desert-ant-web/core" for hosts that already own
+// identity and transport and just want the semantics.
+//
+// The one billed signal is a `load` event — the MAD turnstile. The server dedups
+// by device (COUNT DISTINCT deviceId per company per month) and SUMS callCount
+// across events, so emitting an extra `load` never over-bills and a session's
+// calls can be split across several events and still add up.
+export const SDK_NAME = "desert-ant-web";
+export const SDK_VERSION = "0.1.0"; // keep in sync with package.json
+// Re-emit windows. A node/mobile install is persistent, so a device re-emits at
+// most once a DAY. Web is session-shaped and its identity is ephemeral, so it
+// re-emits per SESSION — a new session being the first activity after this much
+// inactivity (the ~30-min idle timeout every web-analytics tool uses). Neither
+// affects billing: MAD is COUNT(DISTINCT deviceId) per month regardless of how
+// often a device re-emits within it.
+export const DAY_MS = 24 * 60 * 60 * 1000;
+export const WEB_SESSION_MS = 30 * 60 * 1000;
+const positive = (n) => (n > 0 ? n : undefined);
+/** RFC 4122 v4, via crypto.randomUUID where available. */
+export function uuid() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    const b = new Uint8Array(16);
+    c.getRandomValues(b);
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0"));
+    return `${h[0]}${h[1]}${h[2]}${h[3]}-${h[4]}${h[5]}-${h[6]}${h[7]}-${h[8]}${h[9]}-${h[10]}${h[11]}${h[12]}${h[13]}${h[14]}${h[15]}`;
+}
+export function buildBody(deviceId, key, events) {
+    const body = {
+        platform: "web",
+        sdk: { name: SDK_NAME, version: SDK_VERSION },
+        sentAt: new Date().toISOString(),
+        events,
+    };
+    // Key rides the body (never a header) so the text/plain + sendBeacon path stays
+    // a CORS "simple" request with no preflight.
+    if (key)
+        body.key = key;
+    return body;
+}
+export function createClient(deps) {
+    const now = deps.now ?? Date.now;
+    let sessionCalls = 0; // recordCall() accrued this session, not yet accounted
+    let pending = null; // queued turnstile, awaiting first flush
+    let emitted = false; // did we open a turnstile this session?
+    // Effective count for an emit: provider is authoritative when set, else the
+    // accumulated (carry + session) count.
+    const resolveCount = (accumulated) => positive(deps.callCount ? deps.callCount() : accumulated);
+    function queue(context) {
+        pending = { name: "load", deviceId: deps.deviceId, context: context ?? deps.context?.() };
+        emitted = true;
+    }
+    function start() {
+        const st = deps.loadState();
+        if (now() - st.lastActiveAt < deps.windowMs)
+            return; // still within the same session/day
+        // Reserve the slot up front so a second tab opening now won't double-emit.
+        deps.saveState({ ...st, lastActiveAt: now() });
+        queue();
+    }
+    function suspend() {
+        // Stamp the moment we go inactive so the next session is measured from here,
+        // then flush via the unload-safe path.
+        const st = deps.loadState();
+        deps.saveState({ ...st, lastActiveAt: now() });
+        flush({ beacon: true });
+    }
+    function recordCall(n = 1) {
+        if (n > 0)
+            sessionCalls += n;
+    }
+    function flush(opts = {}) {
+        const st = deps.loadState();
+        if (pending) {
+            // First flush of this session's turnstile: attach carry + session calls.
+            const ev = pending;
+            pending = null;
+            ev.callCount = resolveCount(st.carryCallCount + sessionCalls);
+            if (!deps.callCount)
+                deps.saveState({ ...st, carryCallCount: 0 });
+            sessionCalls = 0;
+            deps.send(buildBody(deps.deviceId, deps.key, [ev]), opts);
+            return;
+        }
+        if (emitted && sessionCalls > 0) {
+            // Turnstile already sent; late calls ride a delta load (server sums them).
+            const ev = { name: "load", deviceId: deps.deviceId, callCount: resolveCount(sessionCalls), context: deps.context?.() };
+            sessionCalls = 0;
+            deps.send(buildBody(deps.deviceId, deps.key, [ev]), opts);
+            return;
+        }
+        if (!emitted && sessionCalls > 0 && !deps.callCount) {
+            // Throttled session: no turnstile today. Carry the calls to the next emit.
+            deps.saveState({ ...st, carryCallCount: st.carryCallCount + sessionCalls });
+            sessionCalls = 0;
+        }
+    }
+    function load(opts = {}) {
+        const st = deps.loadState();
+        deps.saveState({ ...st, lastActiveAt: now() });
+        queue(opts.context);
+        flush();
+    }
+    return { recordCall, load, flush, start, suspend };
+}

package/dist/identity.d.ts

@@ -0,0 +1,4 @@
+import { type UsageState } from "./core.js";
+export declare function getDeviceId(): string;
+export declare function loadState(): UsageState;
+export declare function saveState(state: UsageState): void;

package/dist/identity.js

@@ -0,0 +1,54 @@
+// Browser device identity + throttle state, persisted in localStorage.
+//
+// The deviceId is a random per-origin UUID — opaque, no PII, never a user id.
+// The SDK always owns it; hosts can't supply or override it. Churn is inherent
+// to the web (storage clears, Safari ITP eviction, private mode) and simply
+// inflates device counts slightly; we accept that rather than fingerprint.
+import { uuid } from "./core.js";
+const KEY = "desert-ant-web/usage/v1";
+// Used when localStorage is unavailable (private mode, sandboxed iframe, SSR).
+// Per-session only — a fresh id each load, which is the honest fallback.
+let memory = null;
+function fresh() {
+    return { deviceId: uuid(), lastActiveAt: 0, carryCallCount: 0 };
+}
+function normalize(s) {
+    if (!s || typeof s.deviceId !== "string" || !s.deviceId)
+        return null;
+    return {
+        deviceId: s.deviceId,
+        lastActiveAt: Number(s.lastActiveAt) || 0,
+        carryCallCount: Number(s.carryCallCount) || 0,
+    };
+}
+function read() {
+    try {
+        const existing = normalize(JSON.parse(localStorage.getItem(KEY) ?? "null"));
+        if (existing)
+            return existing;
+        const created = fresh();
+        localStorage.setItem(KEY, JSON.stringify(created));
+        return created;
+    }
+    catch {
+        return (memory ??= fresh());
+    }
+}
+function write(s) {
+    try {
+        localStorage.setItem(KEY, JSON.stringify(s));
+    }
+    catch {
+        memory = s;
+    }
+}
+export function getDeviceId() {
+    return read().deviceId;
+}
+export function loadState() {
+    const { lastActiveAt, carryCallCount } = read();
+    return { lastActiveAt, carryCallCount };
+}
+export function saveState(state) {
+    write({ ...read(), ...state });
+}

package/dist/index.browser.d.ts

@@ -0,0 +1,16 @@
+import { type LoadContext, type UsageClient } from "./core.js";
+export { DAY_MS, WEB_SESSION_MS, createClient, uuid } from "./core.js";
+export type { UsageClient, ClientDeps, IngestBody, IngestEvent, UsageState, LoadContext } from "./core.js";
+export interface UsageConfig {
+    /** Publishable key. Optional: keyless requests are identified by the Origin. */
+    key?: string;
+    /** Override the ingestion endpoint (e.g. staging). */
+    endpoint?: string;
+    /** Authoritative call count, read at emit time. Alternative to recordCall(). */
+    callCount?: () => number;
+    /** Extra context merged onto each load (appVersion, etc.). */
+    context?: LoadContext | (() => LoadContext | undefined);
+    /** Disable entirely (returns an inert client). */
+    disabled?: boolean;
+}
+export declare function initUsage(config?: UsageConfig): UsageClient;

package/dist/index.browser.js

@@ -0,0 +1,57 @@
+// Browser entry. Batteries-included: wires the localStorage identity, the
+// beacon/fetch transport, and the page lifecycle into the core client.
+import { createClient, WEB_SESSION_MS } from "./core.js";
+import { getDeviceId, loadState, saveState } from "./identity.js";
+import { makeSend } from "./transport.js";
+export { DAY_MS, WEB_SESSION_MS, createClient, uuid } from "./core.js";
+// Production ingestion endpoint. Point at staging via `initUsage({ endpoint })`.
+const DEFAULT_ENDPOINT = "https://platform.desertant.ai/api/v1/ingest";
+// Lock in the turnstile shortly after load — capturing calls made early in the
+// session — without waiting for pagehide, which a flaky unload can drop.
+const SETTLE_MS = 3000;
+function inert() {
+    return { recordCall() { }, load() { }, flush() { }, start() { }, suspend() { } };
+}
+export function initUsage(config = {}) {
+    // No-op under SSR or when disabled — never touch DOM/storage that isn't there.
+    if (config.disabled || typeof window === "undefined")
+        return inert();
+    const endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    const client = createClient({
+        deviceId: getDeviceId(),
+        key: config.key,
+        callCount: config.callCount,
+        context: contextProvider(config.context),
+        windowMs: WEB_SESSION_MS,
+        loadState,
+        saveState,
+        send: makeSend(endpoint),
+    });
+    client.start();
+    // Tab hidden → the session may be ending: stamp the idle clock and flush.
+    // Tab visible again → re-evaluate; a return after the idle window is a new
+    // session and emits a fresh turnstile.
+    window.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden")
+            client.suspend();
+        else
+            client.start();
+    });
+    window.addEventListener("pagehide", () => client.suspend());
+    setTimeout(() => client.flush(), SETTLE_MS);
+    return client;
+}
+function contextProvider(c) {
+    const base = {};
+    if (typeof navigator !== "undefined" && navigator.language)
+        base.locale = navigator.language;
+    if (typeof c === "function")
+        return () => merge(base, c());
+    if (c)
+        return () => merge(base, c);
+    return () => (Object.keys(base).length ? { ...base } : undefined);
+}
+function merge(base, extra) {
+    const out = { ...base, ...(extra ?? {}) };
+    return Object.keys(out).length ? out : undefined;
+}

package/dist/index.node.d.ts

@@ -0,0 +1,12 @@
+import { type LoadContext, type UsageClient } from "./core.js";
+export { DAY_MS, WEB_SESSION_MS, createClient, uuid } from "./core.js";
+export type { UsageClient, ClientDeps, IngestBody, IngestEvent, UsageState, LoadContext } from "./core.js";
+export interface UsageConfig {
+    /** Publishable key. Required off-browser: there's no Origin to identify by. */
+    key?: string;
+    endpoint?: string;
+    callCount?: () => number;
+    context?: LoadContext | (() => LoadContext | undefined);
+    disabled?: boolean;
+}
+export declare function initUsage(config?: UsageConfig): UsageClient;

package/dist/index.node.js

@@ -0,0 +1,63 @@
+// Node / headless entry. No Origin off-browser, so a key is required for events
+// to be attributable. No DOM lifecycle — best-effort flush on process exit.
+import { createClient, DAY_MS } from "./core.js";
+import { nodeStore } from "./store-node.js";
+export { DAY_MS, WEB_SESSION_MS, createClient, uuid } from "./core.js";
+// How often a long-running process re-checks the daily window. Servers don't
+// relaunch daily the way a mobile app does, so without this a boot-once process
+// would emit once and never again — missing subsequent days/months.
+const RECHECK_MS = 60 * 60 * 1000;
+const DEFAULT_ENDPOINT = "https://platform.desertant.ai/api/v1/ingest";
+function inert() {
+    return { recordCall() { }, load() { }, flush() { }, start() { }, suspend() { } };
+}
+export function initUsage(config = {}) {
+    if (config.disabled)
+        return inert();
+    if (!config.key) {
+        // Never throw into the host — warn and carry on; the server drops unattributable events.
+        console.warn("[desert-ant-web] no key provided off-browser; events cannot be attributed. Pass { key }.");
+    }
+    const endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    const store = nodeStore();
+    const client = createClient({
+        deviceId: store.deviceId(),
+        key: config.key,
+        callCount: config.callCount,
+        context: contextProvider(config.context),
+        windowMs: DAY_MS,
+        loadState: store.loadState,
+        saveState: store.saveState,
+        send: (body) => {
+            void post(endpoint, JSON.stringify(body));
+        },
+    });
+    client.start();
+    // Daily re-check for long-lived processes; unref'd so it never keeps the
+    // process alive on its own.
+    const timer = setInterval(() => client.start(), RECHECK_MS);
+    if (typeof timer.unref === "function")
+        timer.unref();
+    if (typeof process !== "undefined" && typeof process.once === "function") {
+        process.once("beforeExit", () => client.flush());
+    }
+    return client;
+}
+async function post(endpoint, json) {
+    try {
+        await fetch(endpoint, { method: "POST", body: json, headers: { "Content-Type": "application/json" } });
+    }
+    catch {
+        // best-effort
+    }
+}
+function contextProvider(c) {
+    if (typeof c === "function")
+        return () => normalize(c());
+    if (c)
+        return () => normalize(c);
+    return () => undefined;
+}
+function normalize(ctx) {
+    return ctx && Object.keys(ctx).length ? { ...ctx } : undefined;
+}

package/dist/store-node.d.ts

@@ -0,0 +1,7 @@
+import { type UsageState } from "./core.js";
+export interface NodeStore {
+    deviceId(): string;
+    loadState(): UsageState;
+    saveState(state: UsageState): void;
+}
+export declare function nodeStore(): NodeStore;

package/dist/store-node.js

@@ -0,0 +1,49 @@
+// Node device identity + throttle state, persisted to a per-user cache file so a
+// server instance keeps a stable device id across restarts. Node-only (uses
+// node:fs); on any failure it degrades to an in-memory, process-lifetime id.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { uuid } from "./core.js";
+const FILE = join(homedir(), ".cache", "desert-ant-web", "usage.json");
+export function nodeStore() {
+    let cache = null;
+    function read() {
+        if (cache)
+            return cache;
+        try {
+            const parsed = JSON.parse(readFileSync(FILE, "utf8"));
+            if (parsed && typeof parsed.deviceId === "string" && parsed.deviceId) {
+                return (cache = {
+                    deviceId: parsed.deviceId,
+                    lastActiveAt: Number(parsed.lastActiveAt) || 0,
+                    carryCallCount: Number(parsed.carryCallCount) || 0,
+                });
+            }
+        }
+        catch {
+            // missing / corrupt / unreadable — regenerate below
+        }
+        const created = { deviceId: uuid(), lastActiveAt: 0, carryCallCount: 0 };
+        write(created);
+        return created;
+    }
+    function write(s) {
+        cache = s;
+        try {
+            mkdirSync(dirname(FILE), { recursive: true });
+            writeFileSync(FILE, JSON.stringify(s));
+        }
+        catch {
+            // read-only fs — keep the id in memory for this process
+        }
+    }
+    return {
+        deviceId: () => read().deviceId,
+        loadState: () => {
+            const { lastActiveAt, carryCallCount } = read();
+            return { lastActiveAt, carryCallCount };
+        },
+        saveState: (state) => write({ ...read(), ...state }),
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,2 @@
+import type { IngestBody, SendOptions } from "./core.js";
+export declare function makeSend(endpoint: string): (body: IngestBody, opts: SendOptions) => void;

package/dist/transport.js

@@ -0,0 +1,42 @@
+// Browser transport. Two paths, both preflight-free:
+//   - normal flush: fetch(keepalive), text/plain body (server parses it as JSON)
+//   - unload flush:  navigator.sendBeacon (text/plain Blob)
+// The key travels in the body (see buildBody), so we never set an Authorization
+// header and every request stays a CORS "simple" request — no OPTIONS round-trip.
+const CONTENT_TYPE = "text/plain;charset=UTF-8";
+export function makeSend(endpoint) {
+    return (body, opts) => {
+        const json = JSON.stringify(body);
+        if (opts.beacon && typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+            try {
+                if (navigator.sendBeacon(endpoint, new Blob([json], { type: CONTENT_TYPE })))
+                    return;
+            }
+            catch {
+                // queued send failed (e.g. payload too large) — fall through to fetch
+            }
+        }
+        void post(endpoint, json);
+    };
+}
+async function post(endpoint, json, tries = 2) {
+    for (let attempt = 0; attempt < tries; attempt++) {
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST",
+                body: json,
+                keepalive: true,
+                mode: "cors",
+                credentials: "omit",
+                headers: { "Content-Type": CONTENT_TYPE },
+            });
+            if (res.ok)
+                return;
+        }
+        catch {
+            // network error — retry
+        }
+        await new Promise((r) => setTimeout(r, 200 * 2 ** attempt));
+    }
+    // Best-effort: a dropped turnstile is recovered by the next active session.
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@desert-ant-labs/desert-ant-web",
+  "version": "0.1.0",
+  "description": "Internal shared browser/JS code for Desert Ant on-device SDKs (currently: usage reporting — active-device 'load' events to the ingestion API).",
+  "type": "module",
+  "main": "./dist/index.node.js",
+  "types": "./dist/index.node.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/index.browser.d.ts",
+        "default": "./dist/index.browser.js"
+      },
+      "node": {
+        "types": "./dist/index.node.d.ts",
+        "default": "./dist/index.node.js"
+      },
+      "default": {
+        "types": "./dist/index.node.d.ts",
+        "default": "./dist/index.node.js"
+      }
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test test/*.test.ts",
+    "lint:publint": "publint --strict",
+    "lint:attw": "attw --pack . --profile esm-only",
+    "check:pkg": "npm run build && npm run lint:publint && npm run lint:attw",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "usage",
+    "telemetry",
+    "active-devices",
+    "mad",
+    "desert-ant"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Desert-Ant-Labs/desert-ant-web.git"
+  },
+  "homepage": "https://github.com/Desert-Ant-Labs/desert-ant-web",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18",
+    "@types/node": "^22",
+    "publint": "^0.3",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}