@hitslop/slurp-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Longtail Labs
+
+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,118 @@
-# Temporary Holding Version
+# @hitslop/slurp-sdk
 
-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.
+Browser and Node event capture for [Slurp](https://slurp.run), with no runtime dependencies. Events go to the Worker in your own Cloudflare account; `slurp sync` pulls them into DuckDB for your coding agent.
+
+```sh
+npm install @hitslop/slurp-sdk
+```
+
+`slurp init` in your app prints your project's snippet with the real values filled in: your ingest URL (`https://slurp.<your-subdomain>.workers.dev/v1/events`), your source ID and your publishable key (`slurp_pk_…`, ingest-only, safe in a web page).
+
+Browser:
+
+```js
+import { init, track } from '@hitslop/slurp-sdk';
+
+init({
+  key: 'slurp_pk_…',
+  sourceId: 'src_…',
+  endpoint: 'https://slurp.YOUR-SUBDOMAIN.workers.dev/v1/events',
+});
+
+track('signed_up', { plan: 'pro' });
+```
+
+Node:
+
+```js
+import { init, track, flush } from '@hitslop/slurp-sdk';
+
+init({
+  key: 'slurp_pk_…',
+  sourceId: 'src_…',
+  endpoint: 'https://slurp.YOUR-SUBDOMAIN.workers.dev/v1/events',
+});
+
+track('order_completed', { total: 49 });
+
+// Send queued events before the process exits.
+await flush();
+```
+
+`init` creates or replaces the default client. `createClient(options)` creates an independent client with `track`, `identify`, `reset`, `flush`, `close` and a `pending` event count. `track` returns a locally generated UUIDv7, including when an event is rejected; use `onError(error, dropped)` to observe drops. Network failures never throw from `track` or `flush`. Call `identify('user-id', { plan: 'pro' })` to queue an identify record and attach `user_id` to subsequent events. Switching between known users rotates anonymous and session IDs; first identification keeps them so prior anonymous activity can be linked. Queued records retain their original identities. `reset()` clears it and starts a new anonymous identity and session. Thirty minutes without tracking starts a new session. Identity and session survive reloads through storage.
+
+Each record is one JSON line. Identify records omit `event` and put trait updates in `data`:
+
+```json
+{"id":"019a3cb6-bc00-7000-8000-000000000001","type":"track","event":"signed_up","timestamp":"2025-11-01T00:00:00.000Z","user_id":"user-42","anonymous_id":"…","session_id":"…","data":{"plan":"pro"},"context":{"library":{"name":"@hitslop/slurp-sdk","version":"0.1.0"}}}
+```
+
+`user_id` is omitted until identification. Browser context also contains `page: {url, path, referrer, title}`, `user_agent`, `locale`, and `timezone`; Node context adds `runtime: {name: 'node', version: process.version}`. Event names must be non-empty strings of at most 200 characters. Data must be a plain object containing only JSON values: no cycles, dates, bigint, functions, undefined, symbols or nonfinite numbers. Data and context are snapshotted when captured. `context` accepts a plain JSON object or a function called for each record; use it for app, device, OS and screen metadata. `context.geo` is reserved for backend enrichment. `track(event, data, { userId, anonymousId, sessionId, context })` overrides one record without changing the client identity, for server applications handling multiple users. Events larger than 32 KiB of serialized UTF-8 JSON are dropped and reported. No server stamp fields are emitted.
+
+Options besides the required `key` and full `endpoint`:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `sourceId` | None | Public source ID; include it so identity survives publishable-key rotation |
+| `context` | Automatic environment | JSON context or a function producing capture-time context |
+| `flushAt` | 100 | Queue size that triggers a send |
+| `flushIntervalMs` | 5000 | Background flush interval |
+| `maxBatchEvents` | 1000 | Maximum events per request |
+| `maxBatchBytes` | 921600 | UTF-8 body target; an event larger than the target travels alone |
+| `maxQueue` | 10000 | Unbatched queue cap; oldest queued events are dropped and reported; unacknowledged batch bodies remain intact |
+| `sessionTimeoutMs` | 1800000 | Session inactivity timeout |
+| `storage` | Browser localStorage; Node memory | Adapter described below |
+| `fetch` | Global fetch | Fetch implementation |
+| `onError` | None | Error callback; `dropped` is zero when work is retained for retry |
+| `flushOnHide` | true in browsers | Try one head batch using fetch keepalive on page hide |
+
+Limits and intervals must be positive safe integers. Browser page hide sends at most 60 KiB; larger bodies stay persisted. Timers are unref'd in Node. `flush()` resolves when queued work is acknowledged, a retry is scheduled, or the client stops. Its result is `{accepted, rejected, pending, retryAt, stopped}`: accepted/rejected are cumulative record counts for this client instance, pending is current retained work, retryAt is an epoch-millisecond deadline or null, and stopped includes closed clients. Acceptance means durable ingest acknowledgment, not publication or read availability. It respects a pending retry deadline, including across reloads; it does not wait for that deadline. `close()` immediately stops timers, listeners and requests and persists outstanding work; call `flush()` first for a normal shutdown. Subsequent `track` calls are dropped and reported.
+
+Batches are raw NDJSON with a trailing newline, sent to `endpoint` with `Content-Type: application/x-ndjson` and `Authorization: Bearer <key>`. Before the first send, the SDK persists the exact completed body. Retries and restarts resend those bytes so the gateway can dedupe a committed request whose response was lost. A 200 acknowledges a batch; 429/503 honor `Retry-After` (seconds or HTTP date), and other 5xx/network errors back off with jitter from 250–500 ms to 30–60 s. A 413 splits existing lines without reserializing them; a rejected singleton is dropped. A 400 or other permanent rejection drops the batch. A 401/403 drops all pending work and permanently stops that client, including when its state is restored. Storage write failures retain work and prevent sending until a snapshot succeeds.
+
+Delivery depends on retained storage, gateway dedupe retention, and a running client. Queue overflow, invalid/oversized events, permanent rejections, and failed browser persistence can lose events. Browser localStorage access is guarded; if unavailable it falls back to memory and reports the error. A process exiting before storage writes finish can lose newly queued events; awaiting `flush` or `close` finishes those writes. Neither call guarantees a successful network delivery when a retry is scheduled.
+
+The storage adapter has localStorage's shape; methods may be synchronous or return promises:
+
+```ts
+interface StorageAdapter {
+  getItem(key: string): string | null | Promise<string | null>
+  setItem(key: string, value: string): void | Promise<void>
+  removeItem(key: string): void | Promise<void>
+}
+```
+
+Version-2 storage keys are namespaced by endpoint and public source ID when supplied, with publishable-key fallback otherwise. The incompatible version-1 state remains untouched. Supply `sourceId` for identity continuity across key rotation. Use one active client per endpoint/source and adapter; independent clients can use separate adapters. The default Node adapter is in memory. For restart recovery, use the Node-only entry:
+
+```js
+import { createClient } from '@hitslop/slurp-sdk';
+import { fileStorage } from '@hitslop/slurp-sdk/node';
+
+const client = createClient({
+  key: 'slurp_pk_…',
+  sourceId: 'src_…',
+  endpoint: 'https://slurp.YOUR-SUBDOMAIN.workers.dev/v1/events',
+  storage: fileStorage('/tmp/slurp-sdk.json'),
+});
+client.track('order_completed', { total: 49 });
+await client.flush();
+await client.close();
+```
+
+The parent directory must exist. `fileStorage` replaces the JSON file atomically using a sibling temporary file and rename (mode 0600). Reuse a single adapter for a file within one process; concurrent processes must use separate files. Atomic replacement protects process restart recovery, without a power-loss/fsync guarantee. The main entry never imports Node modules.
+
+## Contributing
+
+From the [repository](https://github.com/hitSlop/slurp) root:
+
+```sh
+pnpm --filter @hitslop/slurp-sdk typecheck
+(cd packages/sdk-js && node --test test/*.test.ts)
+pnpm --filter @hitslop/slurp-sdk build
+```
+
+The capture scenarios verify identity transitions, contextual snapshots, key rotation and delivery results. The gateway integration scenario starts the real Worker (`backend/`) under `wrangler dev` with local R2 and Durable Objects, injects proxy faults, checks deduped restart replay, retry timing, 413 splitting and permanent authentication failures, then verifies archive digests and the exact delivered IDs. It needs Node 24+ and `npm install` in `backend/`; it uses no external services or paid APIs. `dist/` is ignored. Source uses erasable TypeScript and `.ts` import specifiers; the build rewrites them to `.js` and emits declarations.
+
+## License
+
+MIT

package/dist/event.d.ts

@@ -0,0 +1,6 @@
+export declare const version = "0.1.0";
+export declare const encoder: TextEncoder;
+export declare function uuidv7(now?: number): string;
+export declare function plainObject(value: unknown): value is Record<string, unknown>;
+export declare function jsonData(data: unknown): Record<string, unknown>;
+export declare function context(): Record<string, unknown>;

package/dist/event.js

@@ -0,0 +1,57 @@
+export const version = '0.1.0';
+export const encoder = new TextEncoder();
+export function uuidv7(now = Date.now()) {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    for (let i = 5; i >= 0; i--) {
+        bytes[i] = now % 256;
+        now = Math.floor(now / 256);
+    }
+    bytes[6] = (bytes[6] & 15) | 0x70;
+    bytes[8] = (bytes[8] & 63) | 0x80;
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+export function plainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function jsonData(data) {
+    if (!plainObject(data))
+        throw new Error('data must be a plain JSON object');
+    const seen = new Set();
+    const check = (value) => {
+        if (value === null || typeof value === 'string' || typeof value === 'boolean')
+            return;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return;
+        if (!Array.isArray(value) && !plainObject(value))
+            throw new Error('data must contain only JSON values');
+        if (seen.has(value))
+            throw new Error('data must not contain cycles');
+        seen.add(value);
+        if (Object.getOwnPropertySymbols(value).length)
+            throw new Error('data must contain only JSON keys');
+        for (const item of Array.isArray(value) ? value : Object.values(value))
+            check(item);
+        seen.delete(value);
+    };
+    check(data);
+    return JSON.parse(JSON.stringify(data));
+}
+export function context() {
+    const value = { library: { name: '@hitslop/slurp-sdk', version } };
+    if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+        value.page = { url: window.location.href, path: window.location.pathname, referrer: document.referrer, title: document.title };
+        value.user_agent = navigator.userAgent;
+        value.locale = navigator.language;
+        value.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    else {
+        const process = globalThis.process;
+        if (process?.versions?.node)
+            value.runtime = { name: 'node', version: process.version };
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import type { StorageAdapter } from './storage.ts';
+export type { StorageAdapter } from './storage.ts';
+export { memoryStorage } from './storage.ts';
+export { version } from './event.ts';
+/** A terminal ingestion refusal; billing changes require the project owner. */
+export declare class SlurpQuotaError extends Error {
+    readonly status = 402;
+    constructor();
+}
+export interface SlurpOptions {
+    key: string;
+    endpoint: string;
+    sourceId?: string;
+    context?: Record<string, unknown> | (() => Record<string, unknown>);
+    flushAt?: number;
+    flushIntervalMs?: number;
+    maxBatchEvents?: number;
+    maxBatchBytes?: number;
+    maxQueue?: number;
+    sessionTimeoutMs?: number;
+    storage?: StorageAdapter;
+    fetch?: typeof globalThis.fetch;
+    onError?: (error: Error, dropped: number) => void;
+    flushOnHide?: boolean;
+}
+export interface CaptureOptions {
+    userId?: string;
+    anonymousId?: string;
+    sessionId?: string;
+    context?: Record<string, unknown>;
+}
+/** Cumulative accepted/rejected counts for this client instance, plus current delivery state. */
+export interface FlushResult {
+    accepted: number;
+    rejected: number;
+    pending: number;
+    retryAt: number | null;
+    stopped: boolean;
+}
+export interface SlurpClient {
+    track(event: string, data?: Record<string, unknown>, options?: CaptureOptions): string;
+    identify(userId: string, data?: Record<string, unknown>): string;
+    reset(): void;
+    flush(): Promise<FlushResult>;
+    close(): Promise<void>;
+    readonly pending: number;
+}
+export declare function createClient(options: SlurpOptions): SlurpClient;
+export declare function init(options: SlurpOptions): SlurpClient;
+export declare const track: (event: string, data?: Record<string, unknown>, options?: CaptureOptions) => string;
+export declare const identify: (userId: string, data?: Record<string, unknown>) => string;
+export declare const reset: () => void;
+export declare const flush: () => Promise<FlushResult>;

package/dist/index.js

@@ -0,0 +1,422 @@
+import { context, encoder, jsonData, uuidv7 } from "./event.js";
+import { defaultStorage } from "./storage.js";
+export { memoryStorage } from "./storage.js";
+export { version } from "./event.js";
+/** A terminal ingestion refusal; billing changes require the project owner. */
+export class SlurpQuotaError extends Error {
+    status = 402;
+    constructor() {
+        super('Slurp ingestion stopped: trial, spending limit, or payment needs attention. Ask the owner to run slurp billing status.');
+        this.name = 'SlurpQuotaError';
+    }
+}
+const count = (body) => body.split('\n').length - 1;
+const bytes = (body) => encoder.encode(body).byteLength;
+const KEEPALIVE_BYTES = 60 * 1024;
+function positive(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error('limits and intervals must be positive safe integers');
+    return value;
+}
+function restore(raw) {
+    const state = JSON.parse(raw);
+    if (state.version !== 2 || typeof state.anonymousId !== 'string' || typeof state.sessionId !== 'string' ||
+        !Number.isFinite(state.lastActivity) || (state.userId !== undefined && typeof state.userId !== 'string') ||
+        !Array.isArray(state.queue) || !state.queue.every(line => typeof line === 'string' && !line.includes('\n')) ||
+        !Array.isArray(state.batches) || !state.batches.every(body => typeof body === 'string' && body.endsWith('\n')) ||
+        !Number.isFinite(state.retryAt) || !Number.isSafeInteger(state.attempts) || typeof state.stopped !== 'boolean') {
+        throw new Error('invalid stored SDK state');
+    }
+    return state;
+}
+export function createClient(options) {
+    if (!options.key || !options.endpoint)
+        throw new Error('key and endpoint are required');
+    const flushAt = positive(options.flushAt, 100);
+    const interval = positive(options.flushIntervalMs, 5000);
+    const maxBatchEvents = positive(options.maxBatchEvents, 1000);
+    const maxBatchBytes = positive(options.maxBatchBytes, 900 * 1024);
+    const maxQueue = positive(options.maxQueue, 10_000);
+    const sessionTimeout = positive(options.sessionTimeoutMs, 30 * 60 * 1000);
+    let accepted = 0;
+    let rejected = 0;
+    const report = (error, dropped = 0) => {
+        rejected += dropped;
+        try {
+            options.onError?.(error instanceof Error ? error : new Error(String(error)), dropped);
+        }
+        catch { /* callbacks cannot break delivery */ }
+    };
+    const storage = options.storage ?? defaultStorage(report);
+    const storageKey = options.sourceId
+        ? `@hitslop/slurp-sdk:v2:${new URL(options.endpoint, typeof window === 'undefined' ? undefined : window.location.href).toString().replace(/[?#].*$/, "").replace(/\/$/, "")}:${options.sourceId}`
+        : `@hitslop/slurp-sdk:v2:${options.key}`;
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    let state = {
+        version: 2, anonymousId: uuidv7(), sessionId: uuidv7(), lastActivity: 0,
+        queue: [], batches: [], retryAt: 0, attempts: 0, stopped: false,
+    };
+    let ready = false;
+    let quotaRefused = false;
+    let closed = false;
+    let closing;
+    let stagedCount = 0;
+    const staged = [];
+    let sending;
+    let controller;
+    let timer;
+    let timerAt = Infinity;
+    let saving = false;
+    let saveWaiters = [];
+    let stop;
+    const stopped = new Promise(resolve => { stop = resolve; });
+    const clearTimer = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        timerAt = Infinity;
+    };
+    const pending = () => stagedCount + state.queue.length + state.batches.reduce((total, body) => total + count(body), 0);
+    const schedule = (delay) => {
+        if (closed || state.stopped)
+            return;
+        const at = Date.now() + delay;
+        if (timerAt <= at)
+            return;
+        clearTimer();
+        timerAt = at;
+        timer = setTimeout(() => { clearTimer(); void flush(); }, Math.min(delay, 2_147_483_647));
+        timer.unref?.();
+    };
+    const trim = () => {
+        const dropped = state.queue.length - maxQueue;
+        if (dropped > 0) {
+            state.queue.splice(0, dropped);
+            report(new Error('queue full; dropped oldest queued events'), dropped);
+        }
+    };
+    const hydrate = (raw) => {
+        if (raw !== null)
+            state = restore(raw);
+    };
+    let read = null;
+    try {
+        read = storage.getItem(storageKey);
+    }
+    catch (error) {
+        report(error);
+    }
+    const finishLoad = () => {
+        ready = true;
+        for (const apply of staged.splice(0))
+            apply();
+        trim();
+        if (pending())
+            schedule(Math.max(0, state.retryAt - Date.now()) || interval);
+    };
+    let loaded;
+    if (typeof read === 'string' || read === null) {
+        try {
+            hydrate(read);
+        }
+        catch (error) {
+            report(error);
+        }
+        finishLoad();
+        loaded = Promise.resolve();
+    }
+    else {
+        loaded = Promise.resolve(read).then(hydrate).catch(report).then(finishLoad);
+    }
+    const persist = () => new Promise(resolve => {
+        saveWaiters.push(resolve);
+        if (saving)
+            return;
+        saving = true;
+        void (async () => {
+            await loaded;
+            while (saveWaiters.length) {
+                const waiters = saveWaiters;
+                saveWaiters = [];
+                let saved = true;
+                // A 402 stops this client, but a fresh client after an owner upgrade
+                // must recover without clearing identities on every user's device.
+                try {
+                    await storage.setItem(storageKey, JSON.stringify(quotaRefused ? { ...state, stopped: false } : state));
+                }
+                catch (error) {
+                    saved = false;
+                    report(error);
+                }
+                for (const done of waiters)
+                    done(saved);
+            }
+            saving = false;
+        })();
+    });
+    const apply = (operation) => {
+        if (ready)
+            operation();
+        else
+            staged.push(operation);
+        void persist();
+    };
+    const cutBatch = (limit) => {
+        let size = 0;
+        let length = 0;
+        for (const line of state.queue) {
+            const next = bytes(line) + 1;
+            if (length >= maxBatchEvents || (length > 0 && size + next > limit))
+                break;
+            size += next;
+            length++;
+        }
+        if (length)
+            state.batches.push(state.queue.splice(0, length).join('\n') + '\n');
+    };
+    const retry = async (response) => {
+        let delay = NaN;
+        const header = response?.headers.get('Retry-After');
+        if ((response?.status === 429 || response?.status === 503) && header) {
+            delay = /^\d+(?:\.\d+)?$/.test(header.trim()) ? Number(header) * 1000 : Date.parse(header) - Date.now();
+        }
+        state.attempts++;
+        if (!Number.isFinite(delay)) {
+            const backoff = Math.min(500 * 2 ** Math.min(state.attempts - 1, 7), 60_000);
+            delay = backoff * (0.5 + Math.random() * 0.5);
+        }
+        state.retryAt = Date.now() + Math.max(0, delay);
+        await persist();
+        schedule(Math.max(0, state.retryAt - Date.now()));
+    };
+    const send = async (keepalive) => {
+        await loaded;
+        while (!closed && !state.stopped) {
+            if (state.retryAt > Date.now()) {
+                schedule(state.retryAt - Date.now());
+                return;
+            }
+            // A page-hide batch must fit a keepalive request; bigger pending batches wait for the next load.
+            if (!state.batches.length)
+                cutBatch(keepalive ? Math.min(maxBatchBytes, KEEPALIVE_BYTES) : maxBatchBytes);
+            const body = state.batches[0];
+            if (!body)
+                return;
+            if (!(await persist())) {
+                schedule(interval);
+                return;
+            }
+            if (closed || state.stopped)
+                return;
+            if (keepalive && bytes(body) > KEEPALIVE_BYTES)
+                return true;
+            let response;
+            controller = new AbortController();
+            try {
+                const endpoint = keepalive ? new URL(options.endpoint, typeof window === 'undefined' ? undefined : window.location.href) : undefined;
+                endpoint?.searchParams.set('key', options.key);
+                response = await Promise.race([
+                    doFetch(endpoint?.toString() ?? options.endpoint, {
+                        method: 'POST', headers: keepalive ? { 'Content-Type': 'text/plain' } :
+                            { 'Content-Type': 'application/x-ndjson', Authorization: `Bearer ${options.key}` },
+                        body, keepalive, signal: controller.signal,
+                    }),
+                    stopped.then(() => undefined),
+                ]);
+            }
+            catch (error) {
+                if (closed)
+                    return;
+                report(error);
+                await retry();
+                return;
+            }
+            finally {
+                controller = undefined;
+            }
+            if (closed || !response)
+                return;
+            void response.body?.cancel().catch(() => { });
+            const status = response.status;
+            if (status === 401 || status === 402 || status === 403) {
+                const dropped = pending();
+                quotaRefused = status === 402;
+                state.stopped = true;
+                state.batches = [];
+                state.queue = [];
+                clearTimer();
+                report(status === 402 ? new SlurpQuotaError() : new Error(`ingest ${status}; client stopped`), dropped);
+                await persist();
+                return;
+            }
+            if (status === 429 || status >= 500) {
+                report(new Error(`ingest ${status}; retry scheduled`));
+                await retry(response);
+                return;
+            }
+            state.batches.shift();
+            state.retryAt = 0;
+            state.attempts = 0;
+            if (status === 413) {
+                const lines = body.slice(0, -1).split('\n');
+                if (lines.length === 1)
+                    report(new Error('ingest 413; single event rejected'), 1);
+                else {
+                    const middle = Math.ceil(lines.length / 2);
+                    state.batches.unshift(lines.slice(0, middle).join('\n') + '\n', lines.slice(middle).join('\n') + '\n');
+                }
+            }
+            else if (status === 200)
+                accepted += count(body);
+            else if (status !== 200)
+                report(new Error(`ingest ${status}; batch dropped`), count(body));
+            if (!(await persist())) {
+                schedule(interval);
+                return;
+            }
+            if (keepalive)
+                return true;
+        }
+    };
+    const start = (keepalive) => {
+        sending ??= send(keepalive).finally(() => {
+            sending = undefined;
+            if (pending())
+                schedule(Math.max(0, state.retryAt - Date.now()) || interval);
+        });
+        return sending;
+    };
+    async function flush() {
+        clearTimer();
+        while (await start(false)) {
+            if (closed || state.stopped || !pending())
+                break;
+            clearTimer();
+        }
+        return { accepted, rejected, pending: pending(), retryAt: state.retryAt > Date.now() ? state.retryAt : null, stopped: closed || state.stopped };
+    }
+    const onPageHide = () => {
+        if (!sending && !closed && !state.stopped) {
+            clearTimer();
+            void start(true);
+        }
+    };
+    const onVisibility = () => { if (document.visibilityState === 'hidden')
+        onPageHide(); };
+    const watchHide = (options.flushOnHide ?? true) && typeof window !== 'undefined' && typeof document !== 'undefined';
+    const hideWindow = watchHide ? window : undefined;
+    const hideDocument = watchHide ? document : undefined;
+    if (watchHide) {
+        hideWindow.addEventListener('pagehide', onPageHide);
+        hideDocument.addEventListener('visibilitychange', onVisibility);
+    }
+    const capture = (type, event, data, overrides = {}, identified) => {
+        const now = Date.now();
+        const id = uuidv7(now);
+        if (closed || state.stopped) {
+            report(new Error('client stopped; event dropped'), 1);
+            return id;
+        }
+        let payload;
+        let eventContext;
+        let identity;
+        try {
+            if (type === 'track' && (typeof event !== 'string' || !event.length || [...event].length > 200))
+                throw new Error('event must be a non-empty string of at most 200 characters');
+            if (type === 'identify' && (typeof identified !== 'string' || !identified.length))
+                throw new Error('userId must be a non-empty string');
+            for (const value of [overrides.userId, overrides.anonymousId, overrides.sessionId]) {
+                if (value !== undefined && (typeof value !== 'string' || !value.length))
+                    throw new Error('identity overrides must be non-empty strings');
+            }
+            payload = jsonData(data);
+            const configured = typeof options.context === 'function' ? options.context() : options.context ?? {};
+            eventContext = jsonData({ ...context(), ...jsonData(configured), ...jsonData(overrides.context ?? {}) });
+            if ('geo' in eventContext)
+                throw new Error('context.geo is reserved for server enrichment');
+            identity = { userId: overrides.userId, anonymousId: overrides.anonymousId, sessionId: overrides.sessionId };
+        }
+        catch (error) {
+            report(error, 1);
+            return id;
+        }
+        stagedCount++;
+        apply(() => {
+            stagedCount--;
+            if (state.stopped) {
+                report(new Error('client stopped; event dropped'), 1);
+                return;
+            }
+            const switching = identified !== undefined && state.userId !== undefined && state.userId !== identified;
+            const anonymousId = switching ? uuidv7(now) : state.anonymousId;
+            const sessionId = switching || now - state.lastActivity >= sessionTimeout ? uuidv7(now) : state.sessionId;
+            const userId = identified ?? identity.userId ?? state.userId;
+            const line = JSON.stringify({
+                id, type, ...(event === undefined ? {} : { event }), timestamp: new Date(now).toISOString(),
+                ...(userId !== undefined ? { user_id: userId } : {}),
+                anonymous_id: identity.anonymousId ?? anonymousId,
+                session_id: identity.sessionId ?? sessionId, data: payload, context: eventContext,
+            });
+            if (bytes(line) > 32 * 1024) {
+                report(new Error('event exceeds 32 KB'), 1);
+                return;
+            }
+            state.anonymousId = anonymousId;
+            state.sessionId = sessionId;
+            if (identified !== undefined)
+                state.userId = identified;
+            state.lastActivity = now;
+            state.queue.push(line);
+            trim();
+            if (state.queue.length >= flushAt && state.retryAt <= Date.now())
+                void flush();
+            else
+                schedule(Math.max(0, state.retryAt - Date.now()) || interval);
+        });
+        return id;
+    };
+    return {
+        track: (event, data = {}, overrides) => capture('track', event, data, overrides),
+        identify: (userId, data = {}) => capture('identify', undefined, data, {}, userId),
+        reset() {
+            if (closed || state.stopped)
+                return;
+            apply(() => {
+                delete state.userId;
+                state.anonymousId = uuidv7();
+                state.sessionId = uuidv7();
+                state.lastActivity = Date.now();
+            });
+        },
+        flush,
+        close() {
+            if (closing)
+                return closing;
+            closed = true;
+            stop();
+            controller?.abort();
+            clearTimer();
+            hideWindow?.removeEventListener('pagehide', onPageHide);
+            hideDocument?.removeEventListener('visibilitychange', onVisibility);
+            return closing = persist().then(() => { });
+        },
+        get pending() { return pending(); },
+    };
+}
+let defaultClient;
+export function init(options) {
+    if (defaultClient)
+        void defaultClient.close();
+    return defaultClient = createClient(options);
+}
+function client() {
+    if (!defaultClient)
+        throw new Error('call init before using the default client');
+    return defaultClient;
+}
+export const track = (event, data, options) => client().track(event, data, options);
+export const identify = (userId, data) => client().identify(userId, data);
+export const reset = () => client().reset();
+export const flush = () => client().flush();

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+import type { StorageAdapter } from './storage.ts';
+export declare function fileStorage(path: string): StorageAdapter;

package/dist/node.js

@@ -0,0 +1,37 @@
+import { promises as fs } from 'node:fs';
+export function fileStorage(path) {
+    let operations = Promise.resolve();
+    const run = (operation) => {
+        const result = operations.then(operation);
+        operations = result.then(() => { }, () => { });
+        return result;
+    };
+    const read = async () => {
+        try {
+            return JSON.parse(await fs.readFile(path, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return Object.create(null);
+            throw error;
+        }
+    };
+    const write = async (values) => {
+        const temporary = `${path}.${crypto.randomUUID()}.tmp`;
+        try {
+            await fs.writeFile(temporary, JSON.stringify(values), { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            await fs.rename(temporary, path);
+        }
+        finally {
+            await fs.unlink(temporary).catch(error => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
+        }
+    };
+    return {
+        getItem: key => run(async () => (await read())[key] ?? null),
+        setItem: (key, value) => run(async () => { const values = await read(); values[key] = value; await write(values); }),
+        removeItem: key => run(async () => { const values = await read(); delete values[key]; await write(values); }),
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,7 @@
+export interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+export declare function memoryStorage(): StorageAdapter;
+export declare function defaultStorage(report: (error: unknown) => void): StorageAdapter;

package/dist/storage.js

@@ -0,0 +1,52 @@
+export function memoryStorage() {
+    const values = new Map();
+    return {
+        getItem: key => values.get(key) ?? null,
+        setItem: (key, value) => { values.set(key, value); },
+        removeItem: key => { values.delete(key); },
+    };
+}
+export function defaultStorage(report) {
+    const memory = memoryStorage();
+    if (typeof window === 'undefined')
+        return memory;
+    let failed = false;
+    return {
+        getItem(key) {
+            if (!failed) {
+                try {
+                    return window.localStorage.getItem(key);
+                }
+                catch (error) {
+                    failed = true;
+                    report(error);
+                }
+            }
+            return memory.getItem(key);
+        },
+        setItem(key, value) {
+            memory.setItem(key, value);
+            if (!failed) {
+                try {
+                    window.localStorage.setItem(key, value);
+                }
+                catch (error) {
+                    failed = true;
+                    report(error);
+                }
+            }
+        },
+        removeItem(key) {
+            memory.removeItem(key);
+            if (!failed) {
+                try {
+                    window.localStorage.removeItem(key);
+                }
+                catch (error) {
+                    failed = true;
+                    report(error);
+                }
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@hitslop/slurp-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Browser and Node event capture for Slurp: durable queue, byte-identical retries and batching. No runtime dependencies.",
+  "keywords": [
+    "analytics",
+    "product-analytics",
+    "events",
+    "tracking",
+    "slurp",
+    "cloudflare",
+    "duckdb",
+    "coding-agents"
+  ],
+  "license": "MIT",
+  "author": "Longtail Labs",
+  "homepage": "https://slurp.run/docs/#capture",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hitSlop/slurp.git",
+    "directory": "packages/sdk-js"
+  },
+  "bugs": {
+    "url": "https://github.com/hitSlop/slurp/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}