@hitslop/slurp-sdk 0.1.0 → 0.1.1

package/README.md

@@ -6,7 +6,7 @@ Browser and Node event capture for [Slurp](https://slurp.run), with no runtime d
 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).
+`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:
 
@@ -15,7 +15,6 @@ import { init, track } from '@hitslop/slurp-sdk';
 
 init({
   key: 'slurp_pk_…',
-  sourceId: 'src_…',
   endpoint: 'https://slurp.YOUR-SUBDOMAIN.workers.dev/v1/events',
 });
 
@@ -29,7 +28,6 @@ import { init, track, flush } from '@hitslop/slurp-sdk';
 
 init({
   key: 'slurp_pk_…',
-  sourceId: 'src_…',
   endpoint: 'https://slurp.YOUR-SUBDOMAIN.workers.dev/v1/events',
 });
 
@@ -44,22 +42,23 @@ await flush();
 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"}}}
+{"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 32 KiB of serialized UTF-8 JSON are dropped and reported. No server stamp fields are emitted.
+`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 |
 | --- | --- | --- |
-| `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 |
+| `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 |
@@ -68,7 +67,7 @@ Options besides the required `key` and full `endpoint`:
 
 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.
+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.
 
@@ -82,7 +81,7 @@ interface StorageAdapter {
 }
 ```
 
-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:
+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';
@@ -90,7 +89,6 @@ 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'),
 });
@@ -101,13 +99,27 @@ 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 packages/sdk-js && node --test test/*.test.ts)
+(cd sdks/js && node --test test/*.test.ts)
 pnpm --filter @hitslop/slurp-sdk build
 ```
 

package/dist/event.d.ts

@@ -1,5 +1,11 @@
-export declare const version = "0.1.0";
-export declare const encoder: TextEncoder;
+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>;

package/dist/event.js

@@ -1,7 +1,57 @@
-export const version = '0.1.0';
-export const encoder = new TextEncoder();
+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 = crypto.getRandomValues(new Uint8Array(16));
+    const bytes = randomBytes(16);
     for (let i = 5; i >= 0; i--) {
         bytes[i] = now % 256;
         now = Math.floor(now / 256);

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

@@ -2,21 +2,19 @@ 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;
+    /** 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;

package/dist/index.js

@@ -1,18 +1,14 @@
-import { context, encoder, jsonData, uuidv7 } from "./event.js";
+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";
-/** 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;
+/** 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;
@@ -20,16 +16,32 @@ function positive(value, fallback) {
         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 !== 2 || typeof state.anonymousId !== 'string' || typeof state.sessionId !== 'string' ||
+    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' && !line.includes('\n')) ||
-        !Array.isArray(state.batches) || !state.batches.every(body => typeof body === 'string' && body.endsWith('\n')) ||
+        !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');
     }
-    return 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)
@@ -39,6 +51,8 @@ export function createClient(options) {
     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;
@@ -50,16 +64,15 @@ export function createClient(options) {
         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}`;
+    // 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: 2, anonymousId: uuidv7(), sessionId: uuidv7(), lastActivity: 0,
+        version: 1, 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;
@@ -90,20 +103,48 @@ export function createClient(options) {
         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 = () => {
-        const dropped = state.queue.length - maxQueue;
-        if (dropped > 0) {
-            state.queue.splice(0, dropped);
-            report(new Error('queue full; dropped oldest queued events'), dropped);
+        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)
-            state = restore(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 = storage.getItem(storageKey);
+        read = earlier ? earlier.then(() => storage.getItem(storageKey)) : storage.getItem(storageKey);
     }
     catch (error) {
         report(error);
@@ -141,10 +182,8 @@ export function createClient(options) {
                 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));
+                    await storage.setItem(storageKey, JSON.stringify(state));
                 }
                 catch (error) {
                     saved = false;
@@ -173,8 +212,11 @@ export function createClient(options) {
             size += next;
             length++;
         }
-        if (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;
@@ -214,9 +256,15 @@ export function createClient(options) {
                 return true;
             let response;
             controller = new AbortController();
+            let deadlineTimer;
             try {
-                const endpoint = keepalive ? new URL(options.endpoint, typeof window === 'undefined' ? undefined : window.location.href) : undefined;
+                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' } :
@@ -224,6 +272,7 @@ export function createClient(options) {
                         body, keepalive, signal: controller.signal,
                     }),
                     stopped.then(() => undefined),
+                    deadline,
                 ]);
             }
             catch (error) {
@@ -234,29 +283,32 @@ export function createClient(options) {
                 return;
             }
             finally {
+                clearTimeout(deadlineTimer);
                 controller = undefined;
             }
             if (closed || !response)
                 return;
             void response.body?.cancel().catch(() => { });
             const status = response.status;
-            if (status === 401 || status === 402 || status === 403) {
+            if (status === 401 || status === 403) {
                 const dropped = pending();
-                quotaRefused = status === 402;
                 state.stopped = true;
                 state.batches = [];
                 state.queue = [];
+                queueBytes = 0;
+                batchBytes = 0;
                 clearTimer();
-                report(status === 402 ? new SlurpQuotaError() : new Error(`ingest ${status}; client stopped`), dropped);
+                report(new Error(`ingest ${status}; client stopped`), dropped);
                 await persist();
                 return;
             }
-            if (status === 429 || status >= 500) {
+            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) {
@@ -266,11 +318,12 @@ export function createClient(options) {
                 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)
+            else if (status >= 200 && status < 300)
                 accepted += count(body);
-            else if (status !== 200)
+            else
                 report(new Error(`ingest ${status}; batch dropped`), count(body));
             if (!(await persist())) {
                 schedule(interval);
@@ -359,8 +412,9 @@ export function createClient(options) {
                 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);
+            const size = bytes(line);
+            if (size > MAX_EVENT_BYTES) {
+                report(new Error('event exceeds 1 MiB'), 1);
                 return;
             }
             state.anonymousId = anonymousId;
@@ -369,6 +423,7 @@ export function createClient(options) {
                 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();
@@ -400,7 +455,11 @@ export function createClient(options) {
             clearTimer();
             hideWindow?.removeEventListener('pagehide', onPageHide);
             hideDocument?.removeEventListener('visibilitychange', onVisibility);
-            return closing = persist().then(() => { });
+            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(); },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitslop/slurp-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Browser and Node event capture for Slurp: durable queue, byte-identical retries and batching. No runtime dependencies.",
   "keywords": [
     "analytics",
@@ -18,7 +18,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hitSlop/slurp.git",
-    "directory": "packages/sdk-js"
+    "directory": "sdks/js"
   },
   "bugs": {
     "url": "https://github.com/hitSlop/slurp/issues"
@@ -35,6 +35,10 @@
     "./node": {
       "types": "./dist/node.d.ts",
       "default": "./dist/node.js"
+    },
+    "./feedback": {
+      "types": "./dist/feedback.d.ts",
+      "default": "./dist/feedback.js"
     }
   },
   "files": [
@@ -48,12 +52,13 @@
   "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"
-  },
-  "devDependencies": {
-    "typescript": "5.9.3"
   }
-}
+}