@cockpitify/js 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cockpitify
+
+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,43 @@
-# Temporary Holding Version
-
-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.
+# @cockpitify/js
+
+Usage analytics for web apps: page views, events and sessions, sent to the `ops` layer that
+[Cockpitify](https://cockpitify.app) installs in your own Supabase project. You see them in the Cockpitify app.
+
+```sh
+npm install @cockpitify/js
+```
+
+```ts
+import { Ops } from '@cockpitify/js';
+import { supabase } from './supabase';
+
+Ops.init(supabase); // page views are recorded from here on
+
+// When a feature is used:
+Ops.track('report_exported', { rows: 120 });
+```
+
+Page views come from the History API. Id-like path segments become `[id]`, so `/orders/8412` is
+counted as `/orders/[id]`.
+
+## Not on Supabase Auth
+
+Send batches to your own endpoint, which verifies the user and passes the batch on to `ops.ingest_batch`:
+
+```ts
+import { Ops, httpTransport } from '@cockpitify/js';
+
+Ops.init(httpTransport({ endpoint: 'https://api.example.com/ops', getToken: () => auth.currentUser?.getIdToken() }));
+```
+
+## API
+
+| | |
+|---|---|
+| `Ops.init(target, options?)` | `target`: a supabase-js client, an `httpTransport(...)`, or full options. Options: `appVersion`, `pageViews` (default `true`), `screenName(pathname)`, `debug`. Safe to call again. |
+| `Ops.track(name, props?)` | An event. Props are strings, numbers or booleans. |
+| `Ops.screen(name)` | A screen view, when you name screens yourself. |
+| `Ops.flush()` | Sends what is queued now. |
+| `Ops.optOut()` / `Ops.optIn()` | Stops or resumes recording on this device. |
+
+Recording never throws into your code. Events are queued, sent in batches and retried when offline. A new session starts after 30 minutes away.

package/dist/adapters.d.ts

@@ -0,0 +1,29 @@
+import type { Transport } from './types.js';
+/** The parts of a Supabase client (supabase-js v2) the SDK uses. Typed structurally: no dependency. */
+export interface SupabaseLike {
+    rpc(fn: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+    auth?: {
+        onAuthStateChange?: (cb: (event: string) => void) => unknown;
+    };
+}
+export declare const isSupabaseClient: (v: unknown) => v is SupabaseLike;
+/**
+ * Supabase: `rpc('ops_ingest', { batch })` through the app's own client, so the URL, anon key and
+ * the signed-in user's session are the ones the app already uses. No other configuration.
+ */
+export declare function supabaseTransport(client: SupabaseLike): Transport;
+export interface HttpTransportOptions {
+    /** Your endpoint; it verifies the token and passes the batch to ops.ingest_batch(user, batch). */
+    endpoint: string;
+    /** The signed-in user's token (Firebase ID token, your own JWT…), sent as a Bearer token. */
+    getToken?: () => Promise<string | null | undefined> | string | null | undefined;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+/** Any backend: POSTs the batch as JSON. */
+export declare function httpTransport(opts: HttpTransportOptions): Transport;

package/dist/adapters.js

@@ -0,0 +1,39 @@
+// Transports: where batches go. Supabase is the first provider; any HTTP endpoint works too.
+export const isSupabaseClient = (v) => Boolean(v) && typeof v.rpc === 'function';
+/**
+ * Supabase: `rpc('ops_ingest', { batch })` through the app's own client, so the URL, anon key and
+ * the signed-in user's session are the ones the app already uses. No other configuration.
+ */
+export function supabaseTransport(client) {
+    return {
+        async send(batch) {
+            const { data, error } = await client.rpc('ops_ingest', { batch });
+            if (error)
+                throw new Error(error.message ?? 'ops_ingest failed');
+            return (data ?? { accepted: 0 });
+        },
+        onIdentityChange(flush) {
+            // Events recorded before a sign-in / sign-out go out under the session they happened in.
+            client.auth?.onAuthStateChange?.((event) => {
+                if (event === 'SIGNED_IN' || event === 'SIGNED_OUT')
+                    flush();
+            });
+        },
+    };
+}
+/** Any backend: POSTs the batch as JSON. */
+export function httpTransport(opts) {
+    return {
+        async send(batch) {
+            const token = await opts.getToken?.();
+            const res = await (opts.fetch ?? fetch)(opts.endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}), ...opts.headers },
+                body: JSON.stringify(batch),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            return (await res.json());
+        },
+    };
+}

package/dist/core.d.ts

@@ -0,0 +1,54 @@
+import type { OpsOptions, PropValue, WireEvent } from './types.js';
+export declare const SESSION_GAP_MS: number;
+export declare function randomUuid(): string;
+/** Flat, short, scalar props; values that look like an e-mail or phone number never leave. */
+export declare function cleanProps(props: Record<string, unknown> | undefined): Record<string, PropValue> | undefined;
+export declare class OpsClient {
+    private readonly opts;
+    private readonly clock;
+    private readonly uuid;
+    private deviceId;
+    private queue;
+    private session;
+    private screen;
+    private config;
+    private optedOut;
+    private foreground;
+    private sending;
+    private backoffUntil;
+    private failures;
+    private timer;
+    private persistScheduled;
+    private unsubscribe;
+    readonly ready: Promise<void>;
+    constructor(opts: OpsOptions);
+    /** A feature was used. */
+    track(name: string, props?: Record<string, unknown>): void;
+    /** The app moved to a screen (route pattern, e.g. "/quiz/[id]"). The previous one is closed and timed. */
+    setScreen(name: string): void;
+    /** Sends what is queued now (also called on background). Never throws. */
+    flush(): Promise<void>;
+    /** Stops recording and drops the queue (consent withdrawn). */
+    optOut(): void;
+    optIn(): void;
+    /** The app (or tests) can drive foreground / background directly when no lifecycle is given. */
+    handleLifecycle(state: 'foreground' | 'background'): void;
+    shutdown(): void;
+    private boot;
+    private startTimer;
+    private applyConfig;
+    private recording;
+    /** Starts a session, or a new one after 30 minutes away (closing the old one at its last activity). */
+    private ensureSession;
+    private closeScreen;
+    private onBackground;
+    private onForeground;
+    private push;
+    private batch;
+    /** Writes the queue at most once per tick (many events in a row cost one write). */
+    private persist;
+    private saveSession;
+    private log;
+    /** For tests: what is waiting to be sent. */
+    pending(): readonly WireEvent[];
+}

package/dist/core.js

@@ -0,0 +1,308 @@
+// The platform-neutral client: sessions, screen timing, the device queue and sending. Platforms
+// supply a transport, storage and lifecycle; nothing here touches a browser or React Native API.
+export const SESSION_GAP_MS = 30 * 60 * 1000;
+const MAX_QUEUE = 1000;
+const MAX_BATCH = 100;
+const FLUSH_AT = 50;
+const MAX_BACKOFF_MS = 5 * 60 * 1000;
+const KEYS = { device: 'ops.device', queue: 'ops.queue', session: 'ops.session', optOut: 'ops.optOut' };
+const EMAIL = /[^\s@]+@[^\s@]+\.[^\s@]+/;
+const PHONE = /^\+?[\d\s().-]{7,}$/;
+const systemClock = {
+    now: () => Date.now(),
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (h) => clearInterval(h),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+};
+export function randomUuid() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {
+        const r = (Math.random() * 16) | 0;
+        return (ch === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+/** Flat, short, scalar props; values that look like an e-mail or phone number never leave. */
+export function cleanProps(props) {
+    if (!props || typeof props !== 'object')
+        return undefined;
+    const out = {};
+    for (const key of Object.keys(props).sort().slice(0, 40)) {
+        if (Object.keys(out).length >= 20)
+            break;
+        const v = props[key];
+        if (key.length === 0 || key.length > 40)
+            continue;
+        if (typeof v === 'string')
+            out[key] = EMAIL.test(v) || PHONE.test(v) ? '[redacted]' : v.slice(0, 200);
+        else if ((typeof v === 'number' && Number.isFinite(v)) || typeof v === 'boolean')
+            out[key] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** A stable 0–1 number per device: sampling keeps a device always in or always out. */
+function deviceFraction(id) {
+    let h = 2166136261;
+    for (let i = 0; i < id.length; i++)
+        h = Math.imul(h ^ id.charCodeAt(i), 16777619);
+    return (h >>> 0) / 4294967295;
+}
+async function safeGet(storage, key) {
+    try {
+        return (await storage?.getItem(key)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function safeSet(storage, key, value) {
+    try {
+        if (value === null)
+            await storage?.removeItem?.(key);
+        else
+            await storage?.setItem(key, value);
+    }
+    catch {
+        // Storage full or unavailable: the queue still works in memory.
+    }
+}
+export class OpsClient {
+    opts;
+    clock;
+    uuid;
+    deviceId = '';
+    queue = [];
+    session = null;
+    screen = null;
+    config = { enabled: true, sampleRate: 1, flushSec: 30 };
+    optedOut = false;
+    foreground = true;
+    sending = false;
+    backoffUntil = 0;
+    failures = 0;
+    timer = null;
+    persistScheduled = false;
+    unsubscribe = null;
+    ready;
+    constructor(opts) {
+        this.opts = opts;
+        this.clock = opts.clock ?? systemClock;
+        this.uuid = opts.uuid ?? randomUuid;
+        this.ready = this.boot().catch((err) => this.log('boot failed', err));
+    }
+    /** A feature was used. */
+    track(name, props) {
+        void this.ready.then(() => {
+            const clean = cleanProps(props);
+            this.push({ type: 'event', name: name.trim().slice(0, 100), t: this.clock.now(), ...(clean ? { props: clean } : {}) });
+        });
+    }
+    /** The app moved to a screen (route pattern, e.g. "/quiz/[id]"). The previous one is closed and timed. */
+    setScreen(name) {
+        void this.ready.then(() => {
+            const now = this.clock.now();
+            if (this.screen?.name === name)
+                return;
+            this.closeScreen(now);
+            if (name)
+                this.screen = { name: name.slice(0, 100), enteredAt: now };
+        });
+    }
+    /** Sends what is queued now (also called on background). Never throws. */
+    async flush() {
+        await this.ready;
+        if (this.sending || this.queue.length === 0 || this.optedOut)
+            return;
+        if (this.clock.now() < this.backoffUntil)
+            return;
+        this.sending = true;
+        const events = this.queue.slice(0, MAX_BATCH);
+        try {
+            const res = await this.opts.transport.send(this.batch(events));
+            this.applyConfig(res);
+            if (res.retryAfterSec) {
+                this.backoffUntil = this.clock.now() + res.retryAfterSec * 1000;
+            }
+            else {
+                const sent = new Set(events.map((e) => e.id));
+                this.queue = this.queue.filter((e) => !sent.has(e.id));
+                this.failures = 0;
+                this.backoffUntil = 0;
+                this.persist();
+            }
+        }
+        catch (err) {
+            this.failures++;
+            this.backoffUntil = this.clock.now() + Math.min(MAX_BACKOFF_MS, 1000 * 2 ** this.failures);
+            this.log('send failed', err);
+        }
+        finally {
+            this.sending = false;
+        }
+        if (this.queue.length >= FLUSH_AT && this.backoffUntil === 0)
+            void this.flush();
+    }
+    /** Stops recording and drops the queue (consent withdrawn). */
+    optOut() {
+        this.optedOut = true;
+        this.queue = [];
+        void safeSet(this.opts.storage, KEYS.optOut, '1');
+        void safeSet(this.opts.storage, KEYS.queue, null);
+    }
+    optIn() {
+        this.optedOut = false;
+        void safeSet(this.opts.storage, KEYS.optOut, null);
+    }
+    /** The app (or tests) can drive foreground / background directly when no lifecycle is given. */
+    handleLifecycle(state) {
+        void this.ready.then(() => (state === 'background' ? this.onBackground() : this.onForeground()));
+    }
+    shutdown() {
+        this.unsubscribe?.();
+        if (this.timer !== null)
+            this.clock.clearInterval(this.timer);
+        this.timer = null;
+    }
+    // ── internals ──
+    async boot() {
+        const storage = this.opts.storage;
+        this.deviceId = (await safeGet(storage, KEYS.device)) ?? '';
+        if (!this.deviceId) {
+            this.deviceId = this.uuid();
+            await safeSet(storage, KEYS.device, this.deviceId);
+        }
+        this.optedOut = (await safeGet(storage, KEYS.optOut)) === '1';
+        try {
+            const saved = JSON.parse((await safeGet(storage, KEYS.queue)) ?? '[]');
+            if (Array.isArray(saved))
+                this.queue = saved.slice(-MAX_QUEUE);
+        }
+        catch {
+            this.queue = [];
+        }
+        try {
+            const s = JSON.parse((await safeGet(storage, KEYS.session)) ?? 'null');
+            if (s && typeof s.id === 'string')
+                this.session = s;
+        }
+        catch {
+            this.session = null;
+        }
+        this.ensureSession(this.clock.now());
+        this.unsubscribe = this.opts.lifecycle?.subscribe((state) => this.handleLifecycle(state)) ?? null;
+        this.opts.transport.onIdentityChange?.(() => void this.flush());
+        this.startTimer();
+    }
+    startTimer() {
+        if (this.timer !== null)
+            this.clock.clearInterval(this.timer);
+        this.timer = this.clock.setInterval(() => void this.flush(), this.config.flushSec * 1000);
+    }
+    applyConfig(res) {
+        const c = res.config;
+        if (!c)
+            return;
+        const flushSec = typeof c.flushSec === 'number' && c.flushSec >= 5 ? c.flushSec : this.config.flushSec;
+        const changedTimer = flushSec !== this.config.flushSec;
+        this.config = {
+            enabled: c.enabled !== false,
+            sampleRate: typeof c.sampleRate === 'number' ? Math.min(1, Math.max(0, c.sampleRate)) : this.config.sampleRate,
+            flushSec,
+        };
+        if (!this.config.enabled) {
+            this.queue = [];
+            this.persist();
+        }
+        if (changedTimer)
+            this.startTimer();
+    }
+    recording() {
+        return !this.optedOut && this.config.enabled && deviceFraction(this.deviceId) < this.config.sampleRate;
+    }
+    /** Starts a session, or a new one after 30 minutes away (closing the old one at its last activity). */
+    ensureSession(now) {
+        const s = this.session;
+        if (s && now - s.lastActiveAt <= SESSION_GAP_MS) {
+            s.lastActiveAt = now;
+            return;
+        }
+        if (s)
+            this.push({ type: 'session_end', name: '$end', t: s.lastActiveAt, ms: Math.max(0, s.lastActiveAt - s.startedAt) }, s.id);
+        this.session = { id: this.uuid(), startedAt: now, lastActiveAt: now };
+        this.push({ type: 'session_start', name: '$start', t: now });
+        this.saveSession();
+    }
+    closeScreen(now) {
+        if (!this.screen)
+            return;
+        this.push({ type: 'screen', name: this.screen.name, t: this.screen.enteredAt, ms: Math.max(0, now - this.screen.enteredAt) });
+        this.screen = null;
+    }
+    onBackground() {
+        if (!this.foreground)
+            return;
+        this.foreground = false;
+        const now = this.clock.now();
+        const name = this.screen?.name ?? null;
+        this.closeScreen(now);
+        this.screen = name ? { name, enteredAt: now } : null;
+        if (this.session)
+            this.session.lastActiveAt = now;
+        this.saveSession();
+        void this.flush();
+    }
+    onForeground() {
+        if (this.foreground)
+            return;
+        this.foreground = true;
+        const now = this.clock.now();
+        this.ensureSession(now);
+        if (this.screen)
+            this.screen.enteredAt = now;
+    }
+    push(e, sessionId) {
+        if (!this.recording() || !e.name)
+            return;
+        if (this.foreground && this.session && e.type !== 'session_end')
+            this.session.lastActiveAt = Math.max(this.session.lastActiveAt, this.clock.now());
+        const event = { ...e, id: this.uuid(), t: new Date(e.t).toISOString(), session: sessionId ?? this.session?.id ?? this.uuid() };
+        this.queue.push(event);
+        if (this.queue.length > MAX_QUEUE)
+            this.queue.splice(0, this.queue.length - MAX_QUEUE);
+        this.persist();
+        if (this.queue.length >= FLUSH_AT)
+            void this.flush();
+    }
+    batch(events) {
+        const device = { id: this.deviceId, ...this.opts.device };
+        return {
+            v: 1,
+            sdk: this.opts.sdk ?? { name: 'ops-js', version: '0.1.0' },
+            sentAt: new Date(this.clock.now()).toISOString(),
+            device,
+            events,
+        };
+    }
+    /** Writes the queue at most once per tick (many events in a row cost one write). */
+    persist() {
+        if (this.persistScheduled)
+            return;
+        this.persistScheduled = true;
+        this.clock.setTimeout(() => {
+            this.persistScheduled = false;
+            void safeSet(this.opts.storage, KEYS.queue, JSON.stringify(this.queue));
+        }, 0);
+    }
+    saveSession() {
+        void safeSet(this.opts.storage, KEYS.session, JSON.stringify(this.session));
+    }
+    log(what, err) {
+        if (this.opts.debug)
+            console.warn(`[ops] ${what}:`, err);
+    }
+    /** For tests: what is waiting to be sent. */
+    pending() {
+        return this.queue;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { OpsClient } from './core.js';
+import { type InitTarget } from './singleton.js';
+export { OpsClient, cleanProps, randomUuid, SESSION_GAP_MS } from './core.js';
+export { httpTransport, supabaseTransport, isSupabaseClient, type HttpTransportOptions, type SupabaseLike } from './adapters.js';
+export { createSingleton, resolveOptions, type InitTarget, type OpsApi } from './singleton.js';
+export { routePattern, watchHistory } from './web.js';
+export type * from './types.js';
+export declare const VERSION = "0.1.0";
+export interface WebInitOptions {
+    /** Your app's version, shown in the console's version breakdown. */
+    appVersion?: string;
+    /** Record page views automatically (default true). */
+    pageViews?: boolean;
+    /** How a path becomes a screen name; default replaces id-like segments with [id]. */
+    screenName?: (pathname: string) => string;
+    debug?: boolean;
+}
+export declare const Ops: {
+    /** A Supabase client, an `httpTransport(...)`, or full options. Safe to call again (re-initialises). */
+    init(target: InitTarget, options?: WebInitOptions): OpsClient;
+    track(name: string, props?: Record<string, unknown>): void;
+    screen(name: string): void;
+    flush(): Promise<void>;
+    optOut(): void;
+    optIn(): void;
+    client(): OpsClient | null;
+    attach(client: OpsClient): void;
+};

package/dist/index.js

@@ -0,0 +1,33 @@
+// @cockpitify/js: usage analytics for web apps (and the shared core of the other JS SDKs).
+//
+//   import { Ops } from '@cockpitify/js';
+//   Ops.init(supabase);                       // page views are recorded from here on
+//   Ops.track('report_exported', { rows: 120 });
+import { OpsClient } from "./core.js";
+import { createSingleton, resolveOptions } from "./singleton.js";
+import { isBrowser, watchHistory, webDevice, webLifecycle, webStorage } from "./web.js";
+export { OpsClient, cleanProps, randomUuid, SESSION_GAP_MS } from "./core.js";
+export { httpTransport, supabaseTransport, isSupabaseClient } from "./adapters.js";
+export { createSingleton, resolveOptions } from "./singleton.js";
+export { routePattern, watchHistory } from "./web.js";
+export const VERSION = '0.1.0';
+const singleton = createSingleton();
+let stopHistory = null;
+export const Ops = {
+    ...singleton,
+    /** A Supabase client, an `httpTransport(...)`, or full options. Safe to call again (re-initialises). */
+    init(target, options = {}) {
+        const browser = isBrowser();
+        const client = new OpsClient(resolveOptions(target, {
+            storage: browser ? webStorage : undefined,
+            lifecycle: browser ? webLifecycle : undefined,
+            device: browser ? webDevice(options.appVersion) : { app: options.appVersion },
+            sdk: { name: 'ops-js', version: VERSION },
+            debug: options.debug,
+        }));
+        singleton.attach(client);
+        stopHistory?.();
+        stopHistory = browser && options.pageViews !== false ? watchHistory((name) => client.setScreen(name), options.screenName) : null;
+        return client;
+    },
+};

package/dist/singleton.d.ts

@@ -0,0 +1,18 @@
+import { type SupabaseLike } from './adapters.js';
+import { OpsClient } from './core.js';
+import type { OpsOptions, Transport } from './types.js';
+export type InitTarget = SupabaseLike | Transport | OpsOptions;
+/** A Supabase client, a transport, or full options → full options. */
+export declare function resolveOptions(target: InitTarget, defaults: Omit<OpsOptions, 'transport'>): OpsOptions;
+export interface OpsApi {
+    track(name: string, props?: Record<string, unknown>): void;
+    screen(name: string): void;
+    flush(): Promise<void>;
+    optOut(): void;
+    optIn(): void;
+    /** The live client, once initialised. */
+    client(): OpsClient | null;
+}
+export declare function createSingleton(): OpsApi & {
+    attach(client: OpsClient): void;
+};

package/dist/singleton.js

@@ -0,0 +1,36 @@
+// `Ops.track(...)` from anywhere in the app. Calls made before init are kept and replayed.
+import { isSupabaseClient, supabaseTransport } from "./adapters.js";
+import { OpsClient } from "./core.js";
+/** A Supabase client, a transport, or full options → full options. */
+export function resolveOptions(target, defaults) {
+    if (isSupabaseClient(target))
+        return { ...defaults, transport: supabaseTransport(target) };
+    if (typeof target.send === 'function')
+        return { ...defaults, transport: target };
+    const o = target;
+    return { ...defaults, ...o, device: { ...defaults.device, ...o.device } };
+}
+export function createSingleton() {
+    let current = null;
+    const early = [];
+    const run = (fn) => {
+        if (current)
+            fn(current);
+        else if (early.length < 200)
+            early.push(fn);
+    };
+    return {
+        attach(client) {
+            current?.shutdown();
+            current = client;
+            for (const fn of early.splice(0))
+                fn(client);
+        },
+        track: (name, props) => run((c) => c.track(name, props)),
+        screen: (name) => run((c) => c.setScreen(name)),
+        flush: () => current?.flush() ?? Promise.resolve(),
+        optOut: () => run((c) => c.optOut()),
+        optIn: () => run((c) => c.optIn()),
+        client: () => current,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+export type EventType = 'screen' | 'event' | 'session_start' | 'session_end';
+export type PropValue = string | number | boolean;
+export interface WireEvent {
+    id: string;
+    t: string;
+    type: EventType;
+    name: string;
+    session: string;
+    ms?: number;
+    props?: Record<string, PropValue>;
+}
+export interface DeviceInfo {
+    platform?: string;
+    os?: string;
+    app?: string;
+    locale?: string;
+}
+export interface Batch {
+    v: 1;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    sentAt: string;
+    device: DeviceInfo & {
+        id: string;
+    };
+    events: WireEvent[];
+}
+export interface ServerConfig {
+    enabled: boolean;
+    sampleRate: number;
+    flushSec: number;
+}
+export interface IngestResponse {
+    accepted: number;
+    retryAfterSec?: number;
+    config?: Partial<ServerConfig>;
+}
+/** Where batches go (Supabase RPC, any HTTP endpoint, …). Rejects on network or server errors. */
+export interface Transport {
+    send(batch: Batch): Promise<IngestResponse>;
+    /** Called with a flush function so the transport can send queued events before the user changes. */
+    onIdentityChange?(flush: () => void): void;
+}
+/** Device storage (localStorage, AsyncStorage, …). May be slow or fail: every call is guarded. */
+export interface Storage {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem?(key: string): Promise<void> | void;
+}
+/** The app's foreground / background changes, from the platform. */
+export interface Lifecycle {
+    subscribe(listener: (state: 'foreground' | 'background') => void): () => void;
+}
+export interface Clock {
+    now(): number;
+    setInterval(fn: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+    setTimeout(fn: () => void, ms: number): unknown;
+}
+export interface OpsOptions {
+    transport: Transport;
+    storage?: Storage;
+    lifecycle?: Lifecycle;
+    device?: DeviceInfo;
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    clock?: Clock;
+    uuid?: () => string;
+    /** Logs SDK problems (never thrown into the app). Off by default. */
+    debug?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Ingest Protocol v1 (protocol/README.md) and the seams a platform plugs into.
+export {};

package/dist/web.d.ts

@@ -0,0 +1,9 @@
+import type { DeviceInfo, Lifecycle, Storage } from './types.js';
+export declare const isBrowser: () => boolean;
+export declare const webStorage: Storage;
+export declare const webLifecycle: Lifecycle;
+export declare function webDevice(appVersion?: string): DeviceInfo;
+/** "/quiz/8f3c…/result" → "/quiz/[id]/result": screens are counted by route, not by record. */
+export declare function routePattern(pathname: string): string;
+/** Calls `onScreen` with the current route now and after every client-side navigation. */
+export declare function watchHistory(onScreen: (name: string) => void, name?: (pathname: string) => string): () => void;

package/dist/web.js

@@ -0,0 +1,52 @@
+// Browsers: localStorage, tab visibility as foreground/background, and page views from the
+// History API (React Router, Next.js, Vue Router… need nothing extra).
+const w = globalThis;
+export const isBrowser = () => typeof w.document !== 'undefined' && typeof w.location !== 'undefined';
+export const webStorage = {
+    getItem: (k) => w.localStorage?.getItem(k) ?? null,
+    setItem: (k, v) => w.localStorage?.setItem(k, v),
+    removeItem: (k) => w.localStorage?.removeItem(k),
+};
+export const webLifecycle = {
+    subscribe(listener) {
+        const onVis = () => listener(w.document?.visibilityState === 'hidden' ? 'background' : 'foreground');
+        const onHide = () => listener('background');
+        w.document?.addEventListener?.('visibilitychange', onVis);
+        w.addEventListener?.('pagehide', onHide);
+        return () => w.document?.removeEventListener?.('visibilitychange', onVis);
+    },
+};
+export function webDevice(appVersion) {
+    const ua = w.navigator?.userAgent ?? '';
+    const os = /Windows/.test(ua) ? 'windows' : /Mac OS X/.test(ua) ? 'macos' : /Android/.test(ua) ? 'android' : /iPhone|iPad/.test(ua) ? 'ios' : /Linux/.test(ua) ? 'linux' : undefined;
+    return { platform: 'web', os, locale: w.navigator?.language, app: appVersion };
+}
+const ID_SEGMENT = /^(\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{16,}|[A-Za-z0-9_-]{21,})$/i;
+/** "/quiz/8f3c…/result" → "/quiz/[id]/result": screens are counted by route, not by record. */
+export function routePattern(pathname) {
+    const parts = pathname.split('/').filter(Boolean).map((p) => (ID_SEGMENT.test(p) ? '[id]' : p));
+    return '/' + parts.join('/');
+}
+/** Calls `onScreen` with the current route now and after every client-side navigation. */
+export function watchHistory(onScreen, name = routePattern) {
+    if (!isBrowser() || !w.history)
+        return () => { };
+    const report = () => onScreen(name(w.location.pathname));
+    const history = w.history;
+    const push = history.pushState;
+    const replace = history.replaceState;
+    history.pushState = function (...args) {
+        push.apply(this, args);
+        report();
+    };
+    history.replaceState = function (...args) {
+        replace.apply(this, args);
+        report();
+    };
+    w.addEventListener?.('popstate', report);
+    report();
+    return () => {
+        history.pushState = push;
+        history.replaceState = replace;
+    };
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@cockpitify/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Cockpitify usage analytics for web apps: screen views, events and sessions.",
+  "license": "MIT",
+  "author": "Cockpitify",
+  "homepage": "https://cockpitify.app",
+  "keywords": [
+    "cockpitify",
+    "analytics",
+    "supabase"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../build.mjs",
+    "test": "node --experimental-strip-types --no-warnings --test \"test/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }