@hitslop/slurp-sdk 0.0.0-stage → 0.1.1

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,130 @@
-# 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`) 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_…',
+  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_…',
+  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.1"}}}
+```
+
+`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 1 MiB of serialized UTF-8 JSON are dropped and reported; nothing is ever truncated. No server stamp fields are emitted.
+
+Options besides the required `key` and full `endpoint`:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `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 by count; oldest queued events are dropped and reported |
+| `maxQueueBytes` | 4194304 | Most bytes kept offline, counting unbatched events and batches not yet acknowledged; the oldest are dropped and reported (never the batch being sent). Records can be up to 1 MiB, so a count limit alone is not a size limit; 4 MiB also stays under browser localStorage |
+| `requestTimeoutMs` | 30000 | A request with no answer after this long is aborted and retried with the same bytes |
+| `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. Any 2xx acknowledges a batch; 408, 429 and 503 and other 5xx responses, network errors and requests with no answer within `requestTimeoutMs` are retried with the same bytes (429 and 503 honor `Retry-After`, seconds or HTTP date; the rest 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>
+}
+```
+
+Saved state is namespaced by endpoint and key, so two senders sharing a storage (two sites on one origin) never send each other's queued events. Replacing a key starts clean: the new key has its own queue and visitor identity (rotating a key gives each visitor a new anonymous id once, and the old key's unsent events stay behind). Replacing the default client with `init` hands its queue to the new client. Saved state is validated when it is read: lines that are not complete JSON records are dropped and reported through `onError` rather than sent (the gateway refuses a request that has one malformed line). If you replace a refused key, the client starts sending again instead of staying stopped. Use one active client per endpoint, key and adapter. **The default Node adapter is in memory, so a Node process that exits loses unsent events; the browser default is `localStorage`.** For restart recovery in Node, 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_…',
+  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.
+
+## Feedback widget
+
+A drop-in "Feedback" button for web pages. It opens a small form (message, an optional 1 to 5 rating, an optional email) and sends one `feedback` event, so what people tell you lands next to what they did:
+
+```js
+import { init } from '@hitslop/slurp-sdk';
+import { mountFeedback } from '@hitslop/slurp-sdk/feedback';
+
+init({ key: 'slurp_pk_…', endpoint: 'https://slurp.YOUR-SUBDOMAIN.workers.dev/v1/events' });
+mountFeedback({ askEmail: true, data: () => ({ plan: currentPlan() }) });
+```
+
+The event is `{ event: 'feedback', data: { message, rating?, email?, ...data() } }` with the usual page context, so in SQL: `SELECT timestamp, data->>'message', data->>'rating' FROM events WHERE event = 'feedback'`. Options: `client` (default: the client from `init`), `label`, `title`, `placeholder`, `ratings` (default true), `askEmail` (default false), `position` (`bottom-right` or `bottom-left`), `accent`, `theme` (`auto` follows the visitor's dark mode; `light` or `dark` match your page), `event`, `data`, `button: false` (open it from your own button with the returned `open()`), `container`. It returns `{ open, close, destroy }`. Text a person types is only ever set as text, never parsed as HTML, and the styles live in a shadow root so they neither affect nor inherit from your page. Browser only.
+
+## Contributing
+
+From the [repository](https://github.com/hitSlop/slurp) root:
+
+```sh
+pnpm --filter @hitslop/slurp-sdk typecheck
+(cd sdks/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,12 @@
+export declare const version = "0.1.1";
+export declare const encoder: {
+    encode(text: string): Uint8Array;
+};
+/** The page address when there is one. React Native defines `window` but not `window.location`. */
+export declare function pageHref(): string | undefined;
+/** An endpoint resolved against the page when it can be, otherwise as written (URL support is partial in some runtimes). */
+export declare function resolveEndpoint(endpoint: string): string;
+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,107 @@
+export const version = '0.1.1';
+/** UTF-8 for runtimes without TextEncoder (React Native before Hermes shipped it). */
+function utf8Encode(text) {
+    const out = [];
+    for (let i = 0; i < text.length; i++) {
+        let c = text.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < text.length) {
+            const next = text.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                c = 0x10000 + ((c - 0xd800) << 10) + (next - 0xdc00);
+                i++;
+            }
+        }
+        if (c >= 0xd800 && c <= 0xdfff)
+            c = 0xfffd; // a lone surrogate, as TextEncoder does
+        if (c < 0x80)
+            out.push(c);
+        else if (c < 0x800)
+            out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+        else if (c < 0x10000)
+            out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+        else
+            out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    }
+    return Uint8Array.from(out);
+}
+export const encoder = typeof TextEncoder === 'function' ? new TextEncoder() : { encode: utf8Encode };
+/** Cryptographic randomness where the runtime has it; ids only need to be unique, so Math.random is the fallback. */
+function randomBytes(length) {
+    const crypto = globalThis.crypto;
+    if (typeof crypto?.getRandomValues === 'function')
+        return crypto.getRandomValues(new Uint8Array(length));
+    return Uint8Array.from({ length }, () => Math.floor(Math.random() * 256));
+}
+/** The page address when there is one. React Native defines `window` but not `window.location`. */
+export function pageHref() {
+    try {
+        return typeof window !== 'undefined' ? window.location?.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An endpoint resolved against the page when it can be, otherwise as written (URL support is partial in some runtimes). */
+export function resolveEndpoint(endpoint) {
+    try {
+        return new URL(endpoint, pageHref()).toString();
+    }
+    catch {
+        return endpoint;
+    }
+}
+export function uuidv7(now = Date.now()) {
+    const bytes = randomBytes(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/feedback.d.ts

@@ -0,0 +1,41 @@
+/** What the widget needs from a client: just `track`. Pass the result of `createClient`, or omit it to use the client from `init`. */
+export interface FeedbackClient {
+    track(event: string, data?: Record<string, unknown>): string;
+}
+export interface FeedbackOptions {
+    /** Where the feedback event goes. Defaults to the client created by `init`. */
+    client?: FeedbackClient;
+    /** Text of the floating button. */
+    label?: string;
+    title?: string;
+    placeholder?: string;
+    /** Show a 1 to 5 rating. Default true. */
+    ratings?: boolean;
+    /** Ask for an email address (optional for the person). Default false. */
+    askEmail?: boolean;
+    position?: 'bottom-right' | 'bottom-left';
+    /** Accent color for the button and the submit button. */
+    accent?: string;
+    /** `auto` follows the visitor's system dark mode; `light` or `dark` match your own page. Default `auto`. */
+    theme?: 'auto' | 'light' | 'dark';
+    /** Event name. Default `feedback`. */
+    event?: string;
+    /** Extra properties added to every feedback event, evaluated when it is sent (the current screen, plan, release...). */
+    data?: () => Record<string, unknown>;
+    /** Show the floating button. Default true; set false and call `open()` from your own button. */
+    button?: boolean;
+    /** Where to attach the widget. Default `document.body`. */
+    container?: HTMLElement;
+}
+export interface FeedbackHandle {
+    open(): void;
+    close(): void;
+    /** Remove the widget from the page. */
+    destroy(): void;
+}
+/**
+ * A floating "Feedback" button that opens a small form and sends the answer as one event (default name `feedback`) with
+ * `message`, and `rating` and `email` when asked for. Everything is built with DOM methods and `textContent`, so nothing a person types
+ * is ever parsed as HTML, and the styles live in a shadow root so they neither affect nor inherit from your page. Browser only.
+ */
+export declare function mountFeedback(options?: FeedbackOptions): FeedbackHandle;

package/dist/feedback.js

@@ -0,0 +1,170 @@
+import { track as defaultTrack } from "./index.js";
+const MAX_MESSAGE = 5000;
+const HOST_ATTRIBUTE = 'data-slurp-feedback';
+const STYLE = `
+:host { all: initial; }
+* { box-sizing: border-box; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; }
+.fab { position: fixed; bottom: 20px; z-index: 2147483000; border: 0; border-radius: 999px; padding: 11px 18px; background: var(--accent); color: #fff; font-size: 14px; font-weight: 600; cursor: pointer; box-shadow: 0 6px 20px rgba(0,0,0,.22); }
+.fab:hover { filter: brightness(1.06); }
+.right { right: 20px; } .left { left: 20px; }
+.panel { position: fixed; bottom: 70px; z-index: 2147483001; width: min(340px, calc(100vw - 24px)); background: #fff; color: #17191c; border: 1px solid #dfe3e8; border-radius: 14px; box-shadow: 0 18px 50px rgba(0,0,0,.25); padding: 16px; }
+.panel[hidden] { display: none; }
+h2 { margin: 0 0 10px; font-size: 16px; }
+textarea, input[type=email] { width: 100%; border: 1px solid #c9ced6; border-radius: 8px; padding: 9px 10px; font-size: 14px; color: inherit; background: #fff; }
+textarea { min-height: 96px; resize: vertical; }
+input[type=email] { margin-top: 8px; }
+textarea:focus-visible, input:focus-visible, button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.rating { display: flex; gap: 6px; margin: 0 0 10px; padding: 0; border: 0; }
+.rating legend { font-size: 12px; color: #5b616a; padding: 0; margin-bottom: 4px; }
+.rating button { width: 34px; height: 34px; border-radius: 8px; border: 1px solid #c9ced6; background: #fff; color: #17191c; font-size: 14px; font-weight: 600; cursor: pointer; }
+.rating button[aria-pressed=true] { background: var(--accent); border-color: var(--accent); color: #fff; }
+.row { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
+.row button { border-radius: 8px; padding: 8px 14px; font-size: 14px; font-weight: 600; cursor: pointer; border: 1px solid #c9ced6; background: #fff; color: #17191c; }
+.row .send { background: var(--accent); border-color: var(--accent); color: #fff; }
+.error { margin: 8px 0 0; font-size: 13px; color: #b3001f; }
+.thanks { margin: 6px 0 2px; font-size: 15px; }
+@media (prefers-color-scheme: dark) {
+  :host([data-theme=auto]) .panel { background: #1f2327; color: #f2f4f6; border-color: #3a4048; }
+  :host([data-theme=auto]) textarea, :host([data-theme=auto]) input[type=email] { background: #15181b; border-color: #3a4048; }
+  :host([data-theme=auto]) .rating button, :host([data-theme=auto]) .row button { background: #15181b; border-color: #3a4048; color: #f2f4f6; }
+  :host([data-theme=auto]) .rating legend { color: #9aa1aa; }
+}
+:host([data-theme=dark]) .panel { background: #1f2327; color: #f2f4f6; border-color: #3a4048; }
+:host([data-theme=dark]) textarea, :host([data-theme=dark]) input[type=email] { background: #15181b; border-color: #3a4048; }
+:host([data-theme=dark]) .rating button, :host([data-theme=dark]) .row button { background: #15181b; border-color: #3a4048; color: #f2f4f6; }
+:host([data-theme=dark]) .rating legend { color: #9aa1aa; }
+`;
+function element(tag, attributes = {}, text) {
+    const node = document.createElement(tag);
+    for (const [name, value] of Object.entries(attributes))
+        node.setAttribute(name, value);
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+}
+/**
+ * A floating "Feedback" button that opens a small form and sends the answer as one event (default name `feedback`) with
+ * `message`, and `rating` and `email` when asked for. Everything is built with DOM methods and `textContent`, so nothing a person types
+ * is ever parsed as HTML, and the styles live in a shadow root so they neither affect nor inherit from your page. Browser only.
+ */
+export function mountFeedback(options = {}) {
+    if (typeof document === 'undefined')
+        throw new Error('mountFeedback needs a browser document');
+    const { label = 'Feedback', title = 'Send feedback', placeholder = 'What is working, and what is not?', ratings = true, askEmail = false, position = 'bottom-right', accent = '#e8002a', event = 'feedback', button = true, theme = 'auto', } = options;
+    const container = options.container ?? document.body;
+    for (const old of container.querySelectorAll(`[${HOST_ATTRIBUTE}]`))
+        old.remove(); // mounting twice replaces, never stacks
+    const host = element('div', { [HOST_ATTRIBUTE]: '', 'data-theme': theme });
+    const root = host.attachShadow({ mode: 'open' });
+    root.appendChild(element('style', {}, STYLE));
+    host.style.setProperty('--accent', accent);
+    const fab = element('button', { type: 'button', class: `fab ${position === 'bottom-left' ? 'left' : 'right'}`, 'aria-haspopup': 'dialog', 'aria-expanded': 'false' }, label);
+    const panel = element('div', { class: `panel ${position === 'bottom-left' ? 'left' : 'right'}`, role: 'dialog', 'aria-modal': 'false', 'aria-labelledby': 'slurp-feedback-title', hidden: '' });
+    const heading = element('h2', { id: 'slurp-feedback-title' }, title);
+    const form = element('form', { novalidate: '' });
+    const message = element('textarea', { name: 'message', placeholder, 'aria-label': title, maxlength: String(MAX_MESSAGE), required: '' });
+    let rating;
+    const ratingButtons = [];
+    let ratingGroup;
+    if (ratings) {
+        ratingGroup = element('fieldset', { class: 'rating' });
+        ratingGroup.appendChild(element('legend', {}, 'How would you rate it?'));
+        for (let value = 1; value <= 5; value++) {
+            const choice = element('button', { type: 'button', 'aria-pressed': 'false', 'aria-label': `${value} out of 5` }, String(value));
+            choice.addEventListener('click', () => {
+                rating = rating === value ? undefined : value;
+                for (const [index, other] of ratingButtons.entries())
+                    other.setAttribute('aria-pressed', String(rating === index + 1));
+            });
+            ratingButtons.push(choice);
+            ratingGroup.appendChild(choice);
+        }
+    }
+    const email = askEmail ? element('input', { type: 'email', name: 'email', placeholder: 'Email (optional, if you want a reply)', autocomplete: 'email', 'aria-label': 'Email (optional)' }) : undefined;
+    const error = element('p', { class: 'error', role: 'alert', hidden: '' });
+    const cancel = element('button', { type: 'button', class: 'cancel' }, 'Cancel');
+    const send = element('button', { type: 'submit', class: 'send' }, 'Send');
+    const row = element('div', { class: 'row' });
+    row.append(cancel, send);
+    form.append(...[ratingGroup, message, email, error, row].filter((node) => node !== undefined));
+    panel.append(heading, form);
+    root.append(...(button ? [fab, panel] : [panel]));
+    let timer;
+    let thanks;
+    const show = (visible) => {
+        if (visible)
+            panel.removeAttribute('hidden');
+        else
+            panel.setAttribute('hidden', '');
+        fab.setAttribute('aria-expanded', String(visible));
+    };
+    const reset = () => {
+        message.value = '';
+        if (email)
+            email.value = '';
+        rating = undefined;
+        for (const choice of ratingButtons)
+            choice.setAttribute('aria-pressed', 'false');
+        error.setAttribute('hidden', '');
+        thanks?.remove();
+        thanks = undefined;
+        form.removeAttribute('hidden');
+    };
+    const open = () => {
+        clearTimeout(timer);
+        if (thanks)
+            reset();
+        show(true);
+        message.focus();
+    };
+    const close = () => {
+        clearTimeout(timer);
+        show(false);
+        fab.focus?.();
+    };
+    fab.addEventListener('click', () => (panel.hasAttribute('hidden') ? open() : close()));
+    cancel.addEventListener('click', close);
+    panel.addEventListener('keydown', (e) => { if (e.key === 'Escape')
+        close(); });
+    form.addEventListener('submit', (e) => {
+        e.preventDefault();
+        const text = message.value.trim();
+        if (!text) {
+            error.textContent = 'Please write a few words first.';
+            error.removeAttribute('hidden');
+            message.focus();
+            return;
+        }
+        const address = email?.value.trim();
+        if (address && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address)) {
+            error.textContent = 'That email address does not look right.';
+            error.removeAttribute('hidden');
+            email?.focus();
+            return;
+        }
+        const properties = { ...(options.data?.() ?? {}), message: text.slice(0, MAX_MESSAGE) };
+        if (rating !== undefined)
+            properties.rating = rating;
+        if (address)
+            properties.email = address;
+        try {
+            ;
+            (options.client ?? { track: defaultTrack }).track(event, properties);
+        }
+        catch (failure) {
+            error.textContent = failure instanceof Error && /call init/.test(failure.message) ? 'Feedback is not set up on this page yet.' : 'Could not send. Please try again.';
+            error.removeAttribute('hidden');
+            return;
+        }
+        form.setAttribute('hidden', '');
+        thanks = element('p', { class: 'thanks', role: 'status' }, 'Thank you! We read every message.');
+        panel.appendChild(thanks);
+        timer = setTimeout(() => { show(false); reset(); }, 2500);
+    });
+    container.appendChild(host);
+    return {
+        open,
+        close,
+        destroy() { clearTimeout(timer); host.remove(); },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { StorageAdapter } from './storage.ts';
+export type { StorageAdapter } from './storage.ts';
+export { memoryStorage } from './storage.ts';
+export { version } from './event.ts';
+export interface SlurpOptions {
+    key: string;
+    endpoint: string;
+    context?: Record<string, unknown> | (() => Record<string, unknown>);
+    flushAt?: number;
+    flushIntervalMs?: number;
+    maxBatchEvents?: number;
+    maxBatchBytes?: number;
+    maxQueue?: number;
+    /** Most bytes kept while offline, counting events not yet batched and batches not yet acknowledged; the oldest are dropped (and reported) beyond it. Records can be up to 1 MiB each, so a count limit alone is not a size limit. Default 4 MiB, which also stays under the browser's roughly 5 MB localStorage. */
+    maxQueueBytes?: number;
+    /** A request with no answer after this many milliseconds is aborted and retried with the same bytes. Default 30000. */
+    requestTimeoutMs?: 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,481 @@
+import { context, encoder, jsonData, pageHref, resolveEndpoint, uuidv7 } from "./event.js";
+import { defaultStorage } from "./storage.js";
+export { memoryStorage } from "./storage.js";
+export { version } from "./event.js";
+const count = (body) => body.split('\n').length - 1;
+/** Saves still in flight for a closed client, by saved-state key. A replacement client waits for its own key here before it reads. */
+const pendingCloses = new Map();
+const bytes = (body) => encoder.encode(body).byteLength;
+const KEEPALIVE_BYTES = 60 * 1024;
+/** Largest single record the gateway accepts; records are stored whole, never truncated. */
+const MAX_EVENT_BYTES = 1024 * 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;
+}
+/** True for one complete JSON object. The gateway validates a request as a whole, so one damaged line costs every event batched with it. */
+function isRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+    catch {
+        return false;
+    }
+}
+/** Read saved state, keeping only complete records; `damaged` counts the lines that were thrown away. */
+function restore(raw) {
+    const state = JSON.parse(raw);
+    if (state.version !== 1 || 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') ||
+        !Array.isArray(state.batches) || !state.batches.every(body => typeof body === 'string') ||
+        !Number.isFinite(state.retryAt) || !Number.isSafeInteger(state.attempts) || typeof state.stopped !== 'boolean') {
+        throw new Error('invalid stored SDK state');
+    }
+    let damaged = 0;
+    const keep = (lines) => lines.filter(line => { const ok = line !== '' && !line.includes('\n') && isRecord(line); if (!ok && line !== '')
+        damaged++; return ok; });
+    state.queue = keep(state.queue);
+    state.batches = state.batches.map(body => keep(body.split('\n').slice(0, -1)).join('\n')).filter(joined => joined !== '').map(joined => joined + '\n');
+    return { state, damaged };
+}
+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 maxQueueBytes = positive(options.maxQueueBytes, 4 * 1024 * 1024);
+    const requestTimeoutMs = positive(options.requestTimeoutMs, 30_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);
+    // Saved state belongs to one key: two senders sharing a storage (two sites on one origin) never send each other's queued events,
+    // and a replaced key starts clean. Replacing a key therefore starts a new visitor identity.
+    const storageKey = `@hitslop/slurp-sdk:v1:${resolveEndpoint(options.endpoint).replace(/[?#].*$/, "").replace(/\/$/, "")}:${options.key}`;
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    let state = {
+        version: 1, anonymousId: uuidv7(), sessionId: uuidv7(), lastActivity: 0,
+        queue: [], batches: [], retryAt: 0, attempts: 0, stopped: false,
+    };
+    let ready = 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?.();
+    };
+    // Bytes held, kept incrementally (re-measured whenever whole batches change) so a capture never has to re-encode the queue.
+    let queueBytes = 0;
+    let batchBytes = 0;
+    const measure = () => {
+        queueBytes = state.queue.reduce((total, line) => total + bytes(line) + 1, 0);
+        batchBytes = state.batches.reduce((total, body) => total + bytes(body), 0);
+    };
+    const trim = () => {
+        let dropped = 0;
+        const excess = state.queue.length - maxQueue;
+        if (excess > 0) {
+            for (const line of state.queue.splice(0, excess))
+                queueBytes -= bytes(line) + 1;
+            dropped += excess;
+        }
+        while (queueBytes + batchBytes > maxQueueBytes && state.queue.length) {
+            queueBytes -= bytes(state.queue.shift()) + 1;
+            dropped++;
+        }
+        // Still too much: the oldest unsent batches go too, but never the one that is on the wire right now.
+        const protectedBatches = sending ? 1 : 0;
+        while (queueBytes + batchBytes > maxQueueBytes && state.batches.length > protectedBatches) {
+            dropped += count(state.batches.splice(protectedBatches, 1)[0]);
+            measure();
+        }
+        if (dropped > 0)
+            report(new Error('queue full; dropped the oldest queued events'), dropped);
+    };
+    const hydrate = (raw) => {
+        if (raw !== null) {
+            const restored = restore(raw);
+            state = restored.state;
+            if (restored.damaged)
+                report(new Error(`dropped ${restored.damaged} damaged saved event(s)`), restored.damaged);
+        }
+        measure();
+    };
+    // A client that replaces another one (`init` twice) must read what the first one saved, so it waits for that save to finish.
+    const earlier = pendingCloses.get(storageKey);
+    let read = null;
+    try {
+        read = earlier ? earlier.then(() => storage.getItem(storageKey)) : 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;
+                try {
+                    await storage.setItem(storageKey, JSON.stringify(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');
+            queueBytes -= size;
+            batchBytes += size;
+        }
+    };
+    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();
+            let deadlineTimer;
+            try {
+                const endpoint = keepalive ? new URL(options.endpoint, pageHref()) : undefined;
+                endpoint?.searchParams.set('key', options.key);
+                // A request that is never answered must not stall delivery for good: abort it and retry the same bytes.
+                const deadline = new Promise((_, reject) => {
+                    deadlineTimer = setTimeout(() => { controller?.abort(); reject(new Error(`request timed out after ${requestTimeoutMs} ms`)); }, requestTimeoutMs);
+                    deadlineTimer.unref?.();
+                });
+                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),
+                    deadline,
+                ]);
+            }
+            catch (error) {
+                if (closed)
+                    return;
+                report(error);
+                await retry();
+                return;
+            }
+            finally {
+                clearTimeout(deadlineTimer);
+                controller = undefined;
+            }
+            if (closed || !response)
+                return;
+            void response.body?.cancel().catch(() => { });
+            const status = response.status;
+            if (status === 401 || status === 403) {
+                const dropped = pending();
+                state.stopped = true;
+                state.batches = [];
+                state.queue = [];
+                queueBytes = 0;
+                batchBytes = 0;
+                clearTimer();
+                report(new Error(`ingest ${status}; client stopped`), dropped);
+                await persist();
+                return;
+            }
+            if (status === 408 || status === 429 || status >= 500) {
+                report(new Error(`ingest ${status}; retry scheduled`));
+                await retry(response);
+                return;
+            }
+            state.batches.shift();
+            batchBytes -= bytes(body);
+            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');
+                    measure();
+                }
+            }
+            else if (status >= 200 && status < 300)
+                accepted += count(body);
+            else
+                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,
+            });
+            const size = bytes(line);
+            if (size > MAX_EVENT_BYTES) {
+                report(new Error('event exceeds 1 MiB'), 1);
+                return;
+            }
+            state.anonymousId = anonymousId;
+            state.sessionId = sessionId;
+            if (identified !== undefined)
+                state.userId = identified;
+            state.lastActivity = now;
+            state.queue.push(line);
+            queueBytes += size + 1;
+            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);
+            const done = persist().then(() => { });
+            pendingCloses.set(storageKey, done);
+            void done.finally(() => { if (pendingCloses.get(storageKey) === done)
+                pendingCloses.delete(storageKey); });
+            return closing = done;
+        },
+        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,64 @@
 {
   "name": "@hitslop/slurp-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "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": "sdks/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"
+    },
+    "./feedback": {
+      "types": "./dist/feedback.d.ts",
+      "default": "./dist/feedback.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "jsdom": "^31.0.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  }
 }