@chaja/sdk-browser 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @chaja/sdk-browser
 
-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.
+Error tracking for browsers, reporting to a self-hosted [Chajá](https://github.com/emiliodominguez/chaja) server.
+
+```sh
+pnpm add @chaja/sdk-browser
+```
+
+```ts
+import { captureException, init } from "@chaja/sdk-browser";
+
+init({ endpoint: "https://chaja.example.com", key: "<project ingest key>", release: "1.4.0", environment: "production" });
+
+try {
+	await checkout();
+} catch (error) {
+	captureException(error, { tags: { step: "payment" } });
+}
+```
+
+Uncaught errors and unhandled rejections are captured automatically, with console, `fetch`, navigation and click breadcrumbs.
+Upload sourcemaps with [`@chaja/cli`](https://www.npmjs.com/package/@chaja/cli) so minified frames show your source. All options:
+[docs/sdk.md](https://github.com/emiliodominguez/chaja/blob/main/docs/sdk.md).

package/dist/index.d.mts

@@ -0,0 +1,130 @@
+import { BreadcrumbInput, CaptureContext, CaptureContext as CaptureContext$1, CaptureOptions, CaptureOptions as CaptureOptions$1, Client, Client as Client$1, ClientOptions, ClientOptions as ClientOptions$1 } from "@chaja/sdk-core";
+//#region src/index.d.ts
+export interface BrowserOptions extends Omit<ClientOptions$1, "service"> {
+  /**
+   * Service name; defaults to the page host.
+   */
+  service?: string;
+  /**
+   * Which breadcrumbs to record automatically. All on by default.
+   */
+  breadcrumbs?: {
+    console?: boolean;
+    fetch?: boolean;
+    navigation?: boolean;
+    clicks?: boolean;
+  };
+  /**
+   * Capture uncaught errors and unhandled promise rejections. Default true.
+   */
+  globalHandlers?: boolean;
+  /**
+   * Send a `$pageview` on load and on every client-side navigation to a new path. Default true.
+   */
+  capturePageviews?: boolean;
+  /**
+   * Load feature flags on start and after `identify` or `reset`. Default false.
+   */
+  flags?: boolean;
+  /**
+   * The window to instrument (tests pass a fake one).
+   */
+  window?: Window & typeof globalThis;
+}
+export type FlagValue = boolean | string;
+export interface BrowserClient extends Client$1 {
+  /**
+   * Remove every listener and wrapper this SDK installed.
+   */
+  close(): void;
+  /**
+   * Whether a flag is on for the current person (a variant counts as on); undefined until flags have loaded once.
+   */
+  isFeatureEnabled(key: string): boolean | undefined;
+  /**
+   * A flag's value: `false`, `true`, or the variant key; undefined until flags have loaded once.
+   */
+  getFeatureFlag(key: string): FlagValue | undefined;
+  /**
+   * Called with every flag whenever they load; right away when they already have. Returns a function that stops it.
+   */
+  onFeatureFlags(listener: (flags: Record<string, FlagValue>) => void): () => void;
+  /**
+   * Fetch the current person's flags again.
+   */
+  reloadFeatureFlags(): Promise<void>;
+}
+/**
+ * Start the browser SDK: capture uncaught errors and rejections, record breadcrumbs and send events to Chajá.
+ *
+ * @param options - SDK options.
+ * @returns The client; calling `init` again replaces it.
+ */
+export declare function init(options: BrowserOptions): BrowserClient;
+/**
+ * Capture an error with the client from `init`.
+ *
+ * @param error - Thrown value.
+ * @param context - Extra context.
+ * @returns Event id, if sent.
+ */
+export declare function captureException(error: unknown, context?: CaptureContext$1): string | undefined;
+/**
+ * Capture a message with the client from `init`.
+ *
+ * @param message - Message.
+ * @param level - Level.
+ * @param context - Extra context.
+ * @returns Event id, if sent.
+ */
+export declare function captureMessage(message: string, level?: Parameters<Client$1["captureMessage"]>[1], context?: CaptureContext$1): string | undefined;
+/**
+ * The client created by `init`, if any.
+ *
+ * @returns Current client.
+ */
+export declare function getClient(): BrowserClient | undefined;
+/**
+ * Record a product analytics event with the client from `init`.
+ *
+ * @param name - Event name, such as `signed_up`.
+ * @param properties - Event properties.
+ * @param options - Person override and person properties.
+ * @returns Event id, if sent.
+ */
+export declare function capture(name: string, properties?: Parameters<Client$1["capture"]>[1], options?: CaptureOptions$1): string | undefined;
+/**
+ * Name the current person with your app's user id (after sign-in).
+ *
+ * @param distinctId - Your user id.
+ * @param set - Person properties, such as `{ email, plan }`.
+ * @param setOnce - Person properties to keep from the first time they are set.
+ */
+export declare function identify(distinctId: string, set?: Parameters<Client$1["identify"]>[1], setOnce?: Parameters<Client$1["identify"]>[2]): void;
+/**
+ * Forget the current person (on sign-out).
+ */
+export declare function reset(): void;
+/**
+ * Whether a flag is on for the current person, with the client from `init` (needs `flags: true`).
+ *
+ * @param key - Flag key.
+ * @returns On, off, or undefined before flags load.
+ */
+export declare function isFeatureEnabled(key: string): boolean | undefined;
+/**
+ * A flag's value for the current person, with the client from `init` (needs `flags: true`).
+ *
+ * @param key - Flag key.
+ * @returns `false`, `true`, the variant key, or undefined before flags load.
+ */
+export declare function getFeatureFlag(key: string): FlagValue | undefined;
+/**
+ * Run a callback whenever flags load, with the client from `init`.
+ *
+ * @param listener - Called with every flag.
+ * @returns A function that stops it.
+ */
+export declare function onFeatureFlags(listener: (flags: Record<string, FlagValue>) => void): () => void;
+//#endregion
+export type { BreadcrumbInput, CaptureContext, CaptureOptions, Client, ClientOptions };

package/dist/index.mjs

@@ -0,0 +1,537 @@
+import { SDK_VERSION, createClient, parseRetryAfter, randomEventId } from "@chaja/sdk-core";
+//#region src/index.ts
+let current;
+/**
+* A session ends after this long without events, or after a day.
+*/
+const SESSION_IDLE_MS = 18e5;
+const SESSION_MAX_MS = 864e5;
+/**
+* JSON state in localStorage that survives private modes and blocked storage by falling back to memory.
+*
+* @param view - Window.
+* @param key - Storage key.
+* @returns Read and write functions.
+*/
+function storedValue(view, key) {
+	let memory;
+	return {
+		read() {
+			try {
+				const raw = view.localStorage.getItem(key);
+				return raw === null ? memory : JSON.parse(raw);
+			} catch {
+				return memory;
+			}
+		},
+		write(value) {
+			memory = value;
+			try {
+				if (value === void 0) view.localStorage.removeItem(key);
+				else view.localStorage.setItem(key, JSON.stringify(value));
+			} catch {}
+		}
+	};
+}
+/**
+* Narrow stored or fetched flags.
+*
+* @param value - Parsed JSON.
+* @returns Flags, or undefined.
+*/
+function flagsOf(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return;
+	const flags = {};
+	for (const [key, flag] of Object.entries(value)) if (typeof flag === "boolean" || typeof flag === "string") flags[key] = flag;
+	return flags;
+}
+/**
+* Narrow stored identity.
+*
+* @param value - Parsed JSON.
+* @returns Identity, or undefined.
+*/
+function identityOf(value) {
+	return typeof value === "object" && value !== null && "distinctId" in value && typeof value.distinctId === "string" && "identified" in value && typeof value.identified === "boolean" ? {
+		distinctId: value.distinctId,
+		identified: value.identified
+	} : void 0;
+}
+/**
+* Narrow a stored session.
+*
+* @param value - Parsed JSON.
+* @returns Session, or undefined.
+*/
+function sessionOf(value) {
+	return typeof value === "object" && value !== null && "id" in value && typeof value.id === "string" && "startedAt" in value && typeof value.startedAt === "number" && "lastActivityAt" in value && typeof value.lastActivityAt === "number" ? {
+		id: value.id,
+		startedAt: value.startedAt,
+		lastActivityAt: value.lastActivityAt
+	} : void 0;
+}
+/**
+* Describe a clicked element compactly: `button#save.primary`.
+*
+* @param target - Event target.
+* @returns Selector-like text.
+*/
+function describeElement(target) {
+	if (!isElement(target)) return;
+	const element = target;
+	const id = element.id ? `#${element.id}` : "";
+	const classes = typeof element.className === "string" && element.className ? `.${element.className.trim().split(/\s+/u).slice(0, 3).join(".")}` : "";
+	const label = element.getAttribute("aria-label") ?? element.getAttribute("name");
+	return `${element.tagName.toLowerCase()}${id}${classes}${label ? `[${label.slice(0, 40)}]` : ""}`;
+}
+/**
+* Whether an event target is a DOM element.
+*
+* @param target - Event target.
+* @returns True for elements.
+*/
+function isElement(target) {
+	return typeof target === "object" && target !== null && "tagName" in target && typeof target.tagName === "string" && "getAttribute" in target;
+}
+/**
+* Start the browser SDK: capture uncaught errors and rejections, record breadcrumbs and send events to Chajá.
+*
+* @param options - SDK options.
+* @returns The client; calling `init` again replaces it.
+*/
+function init(options) {
+	current?.close();
+	const view = options.window ?? window;
+	const envelopeUrl = `${options.endpoint.replace(/\/+$/u, "")}/api/v1/envelope`;
+	const cleanups = [];
+	const nativeFetch = Reflect.get(view, "fetch");
+	const originalFetch = view.fetch.bind(view);
+	const transport = {
+		async send(body) {
+			try {
+				const response = await originalFetch(envelopeUrl, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						"x-chaja-key": options.key
+					},
+					body,
+					keepalive: body.length < 6e4
+				});
+				return {
+					status: response.status,
+					...response.status === 429 || response.status === 503 ? optionalRetry(response.headers.get("retry-after")) : {}
+				};
+			} catch {
+				return { status: 0 };
+			}
+		},
+		sendFinal(body) {
+			const navigatorRef = view.navigator;
+			return typeof navigatorRef.sendBeacon === "function" && navigatorRef.sendBeacon(`${envelopeUrl}?key=${encodeURIComponent(options.key)}`, new Blob([body], { type: "text/plain" }));
+		}
+	};
+	const identityStore = storedValue(view, `chaja_id_${options.key}`);
+	const sessionStore = storedValue(view, `chaja_session_${options.key}`);
+	const flagStore = storedValue(view, `chaja_flags_${options.key}`);
+	const flagsUrl = `${options.endpoint.replace(/\/+$/u, "")}/api/v1/flags`;
+	const flagListeners = /* @__PURE__ */ new Set();
+	const reported = /* @__PURE__ */ new Set();
+	let flags = options.flags ? flagsOf(flagStore.read()) : void 0;
+	const client = createClient({
+		...options,
+		service: options.service ?? view.location.host
+	}, {
+		sdk: {
+			name: "chaja.javascript.browser",
+			version: SDK_VERSION
+		},
+		platform: "javascript",
+		transport,
+		eventId: randomEventId,
+		now: Date.now,
+		random: Math.random,
+		schedule(callback, delayMs) {
+			return view.setTimeout(callback, delayMs);
+		},
+		cancel(handle) {
+			if (typeof handle === "number") view.clearTimeout(handle);
+		},
+		enrich(item) {
+			return {
+				...item,
+				request: {
+					url: view.location.href,
+					headers: { "user-agent": view.navigator.userAgent },
+					...item.request
+				}
+			};
+		},
+		identity: {
+			load() {
+				return identityOf(identityStore.read());
+			},
+			save(state) {
+				identityStore.write(state);
+			}
+		},
+		session: {
+			current() {
+				const now = Date.now();
+				const stored = sessionOf(sessionStore.read());
+				const session = stored && now - stored.lastActivityAt < SESSION_IDLE_MS && now - stored.startedAt < SESSION_MAX_MS ? {
+					...stored,
+					lastActivityAt: now
+				} : {
+					id: randomEventId(),
+					startedAt: now,
+					lastActivityAt: now
+				};
+				sessionStore.write(session);
+				return session.id;
+			},
+			reset() {
+				sessionStore.write(void 0);
+			}
+		},
+		eventProperties() {
+			return {
+				$current_url: view.location.href,
+				$host: view.location.host,
+				$pathname: view.location.pathname,
+				$referrer: view.document.referrer,
+				$screen_width: view.screen.width,
+				$screen_height: view.screen.height,
+				$viewport_width: view.innerWidth,
+				$viewport_height: view.innerHeight,
+				$lib: "chaja.javascript.browser",
+				$lib_version: SDK_VERSION,
+				...flagProperties()
+			};
+		}
+	});
+	let lastPage;
+	/**
+	* The loaded flags as `$feature/<key>` event properties, so Insights can compare people by flag.
+	*
+	* @returns Properties.
+	*/
+	function flagProperties() {
+		const properties = {};
+		for (const [key, value] of Object.entries(flags ?? {})) properties[`$feature/${key}`] = value;
+		return properties;
+	}
+	/**
+	* Fetch the current person's flags, keep them for the next page load and tell listeners.
+	*/
+	async function reloadFeatureFlags() {
+		try {
+			const response = await originalFetch(flagsUrl, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					"x-chaja-key": options.key
+				},
+				body: JSON.stringify({ distinctId: client.getDistinctId() })
+			});
+			const body = response.ok ? await response.json() : void 0;
+			const loaded = typeof body === "object" && body !== null && "flags" in body ? flagsOf(body.flags) : void 0;
+			if (!loaded) return;
+			flags = loaded;
+			flagStore.write(loaded);
+			for (const listener of flagListeners) listener(loaded);
+		} catch {}
+	}
+	/**
+	* Read a flag, recording the first read of each value as `$feature_flag_called`.
+	*
+	* @param key - Flag key.
+	* @returns Value, if loaded.
+	*/
+	function readFlag(key) {
+		const value = flags?.[key];
+		if (value !== void 0 && !reported.has(`${key}:${String(value)}`)) {
+			reported.add(`${key}:${String(value)}`);
+			client.capture("$feature_flag_called", {
+				$feature_flag: key,
+				$feature_flag_response: value
+			});
+		}
+		return value;
+	}
+	/**
+	* Send a page view when the path or query changed since the last one.
+	*/
+	function pageview() {
+		const page = `${view.location.pathname}${view.location.search}`;
+		if (options.capturePageviews !== false && page !== lastPage) {
+			lastPage = page;
+			client.capture("$pageview");
+		}
+	}
+	const crumbs = options.breadcrumbs ?? {};
+	/**
+	* Listen to a window event and remember to remove the listener.
+	*
+	* @param type - Event type.
+	* @param listener - Listener.
+	* @param useCapture - Use the capture phase.
+	*/
+	function listen(type, listener, useCapture = false) {
+		view.addEventListener(type, listener, useCapture);
+		cleanups.push(function remove() {
+			view.removeEventListener(type, listener, useCapture);
+		});
+	}
+	if (options.globalHandlers !== false) {
+		listen("error", function onError(event) {
+			const error = event.error ?? new Error(event.message || "Script error");
+			client.captureException(error, { mechanism: {
+				type: "onerror",
+				handled: false
+			} });
+		});
+		listen("unhandledrejection", function onRejection(event) {
+			client.captureException(event.reason, { mechanism: {
+				type: "onunhandledrejection",
+				handled: false
+			} });
+		});
+	}
+	listen("pagehide", function onPageHide() {
+		client.sendFinal();
+	});
+	if (crumbs.console !== false) for (const method of [
+		"warn",
+		"error",
+		"info",
+		"log"
+	]) {
+		const original = view.console[method];
+		view.console[method] = function patched(...args) {
+			client.addBreadcrumb({
+				category: "console",
+				level: method === "warn" ? "warning" : method === "error" ? "error" : "info",
+				message: args.map(function text(arg) {
+					return typeof arg === "string" ? arg : arg instanceof Error ? `${arg.name}: ${arg.message}` : safeJson(arg);
+				}).join(" ").slice(0, 1e3)
+			});
+			original.apply(view.console, args);
+		};
+		cleanups.push(function restore() {
+			view.console[method] = original;
+		});
+	}
+	if (crumbs.fetch !== false) {
+		view.fetch = async function trackedFetch(input, requestInit) {
+			const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+			const method = (requestInit?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+			const started = Date.now();
+			if (url.startsWith(envelopeUrl)) return originalFetch(input, requestInit);
+			try {
+				const response = await originalFetch(input, requestInit);
+				client.addBreadcrumb({
+					category: "fetch",
+					level: response.status >= 500 ? "error" : response.status >= 400 ? "warning" : "info",
+					message: `${method} ${url}`,
+					data: {
+						status: response.status,
+						durationMs: Date.now() - started
+					}
+				});
+				return response;
+			} catch (error) {
+				client.addBreadcrumb({
+					category: "fetch",
+					level: "error",
+					message: `${method} ${url}`,
+					data: {
+						failed: true,
+						durationMs: Date.now() - started
+					}
+				});
+				throw error;
+			}
+		};
+		cleanups.push(function restore() {
+			Reflect.set(view, "fetch", nativeFetch);
+		});
+	}
+	let last = view.location.href;
+	/**
+	* Record a URL change as a breadcrumb.
+	*/
+	function navigated() {
+		const next = view.location.href;
+		if (crumbs.navigation !== false && next !== last) client.addBreadcrumb({
+			category: "navigation",
+			message: `${last} → ${next}`
+		});
+		last = next;
+	}
+	for (const method of ["pushState", "replaceState"]) {
+		const original = view.history[method];
+		view.history[method] = function patched(...args) {
+			const result = original.apply(this, args);
+			navigated();
+			pageview();
+			return result;
+		};
+		cleanups.push(function restore() {
+			view.history[method] = original;
+		});
+	}
+	listen("popstate", function onPopState() {
+		navigated();
+		pageview();
+	});
+	if (crumbs.clicks !== false) listen("click", function onClick(event) {
+		const target = describeElement(event.target);
+		if (target) client.addBreadcrumb({
+			category: "ui.click",
+			message: target
+		});
+	}, true);
+	const instance = {
+		...client,
+		identify(distinctId, set, setOnce) {
+			const before = client.getDistinctId();
+			client.identify(distinctId, set, setOnce);
+			if (options.flags && client.getDistinctId() !== before) reloadFeatureFlags();
+		},
+		reset() {
+			client.reset();
+			reported.clear();
+			if (options.flags) reloadFeatureFlags();
+		},
+		isFeatureEnabled(key) {
+			const value = readFlag(key);
+			return value === void 0 ? void 0 : value !== false;
+		},
+		getFeatureFlag: readFlag,
+		onFeatureFlags(listener) {
+			flagListeners.add(listener);
+			if (flags) listener(flags);
+			return function stop() {
+				flagListeners.delete(listener);
+			};
+		},
+		reloadFeatureFlags,
+		close() {
+			for (const cleanup of cleanups.splice(0)) cleanup();
+			if (current === instance) current = void 0;
+		}
+	};
+	current = instance;
+	pageview();
+	if (options.flags) reloadFeatureFlags();
+	return instance;
+}
+/**
+* Build the optional retry-after field.
+*
+* @param header - Retry-After header.
+* @returns Field to spread into a transport result.
+*/
+function optionalRetry(header) {
+	const seconds = parseRetryAfter(header);
+	return seconds === void 0 ? {} : { retryAfterSeconds: seconds };
+}
+/**
+* JSON for console breadcrumbs, tolerating cycles.
+*
+* @param value - Any value.
+* @returns Text.
+*/
+function safeJson(value) {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/**
+* Capture an error with the client from `init`.
+*
+* @param error - Thrown value.
+* @param context - Extra context.
+* @returns Event id, if sent.
+*/
+function captureException(error, context) {
+	return current?.captureException(error, context);
+}
+/**
+* Capture a message with the client from `init`.
+*
+* @param message - Message.
+* @param level - Level.
+* @param context - Extra context.
+* @returns Event id, if sent.
+*/
+function captureMessage(message, level, context) {
+	return current?.captureMessage(message, level, context);
+}
+/**
+* The client created by `init`, if any.
+*
+* @returns Current client.
+*/
+function getClient() {
+	return current;
+}
+/**
+* Record a product analytics event with the client from `init`.
+*
+* @param name - Event name, such as `signed_up`.
+* @param properties - Event properties.
+* @param options - Person override and person properties.
+* @returns Event id, if sent.
+*/
+function capture(name, properties, options) {
+	return current?.capture(name, properties, options);
+}
+/**
+* Name the current person with your app's user id (after sign-in).
+*
+* @param distinctId - Your user id.
+* @param set - Person properties, such as `{ email, plan }`.
+* @param setOnce - Person properties to keep from the first time they are set.
+*/
+function identify(distinctId, set, setOnce) {
+	current?.identify(distinctId, set, setOnce);
+}
+/**
+* Forget the current person (on sign-out).
+*/
+function reset() {
+	current?.reset();
+}
+/**
+* Whether a flag is on for the current person, with the client from `init` (needs `flags: true`).
+*
+* @param key - Flag key.
+* @returns On, off, or undefined before flags load.
+*/
+function isFeatureEnabled(key) {
+	return current?.isFeatureEnabled(key);
+}
+/**
+* A flag's value for the current person, with the client from `init` (needs `flags: true`).
+*
+* @param key - Flag key.
+* @returns `false`, `true`, the variant key, or undefined before flags load.
+*/
+function getFeatureFlag(key) {
+	return current?.getFeatureFlag(key);
+}
+/**
+* Run a callback whenever flags load, with the client from `init`.
+*
+* @param listener - Called with every flag.
+* @returns A function that stops it.
+*/
+function onFeatureFlags(listener) {
+	return current?.onFeatureFlags(listener) ?? function nothing() {};
+}
+//#endregion
+export { capture, captureException, captureMessage, getClient, getFeatureFlag, identify, init, isFeatureEnabled, onFeatureFlags, reset };

package/dist/replay.d.mts

@@ -0,0 +1,61 @@
+//#region src/replay.d.ts
+export interface ReplayOptions {
+  /**
+   * Share of sessions recorded, decided once per session. Default 1.
+   */
+  sampleRate?: number;
+  /**
+   * Replace what people type with asterisks. Default true.
+   */
+  maskAllInputs?: boolean;
+  /**
+   * Elements whose text is masked, such as `[data-private]`.
+   */
+  maskTextSelector?: string;
+  /**
+   * Elements left out of the recording entirely. Default `.chaja-block`.
+   */
+  blockSelector?: string;
+  /**
+   * How often recorded events are sent. Default 5 seconds.
+   */
+  flushIntervalMs?: number;
+  /**
+   * The window to record (tests pass a fake one).
+   */
+  window?: Window & typeof globalThis;
+  /**
+   * The recorder (tests pass a fake one).
+   */
+  recorder?: Recorder;
+}
+/**
+ * The part of rrweb's `record` the replay uses.
+ */
+export interface Recorder {
+  (options: {
+    emit: (event: unknown) => void;
+    maskAllInputs?: boolean;
+    maskTextSelector?: string;
+    blockSelector?: string;
+    recordCanvas?: boolean;
+    inlineStylesheet?: boolean;
+  }): (() => void) | undefined;
+  takeFullSnapshot?: (isCheckout?: boolean) => void;
+}
+/**
+ * Record the page as a session replay with the client from `init`: the DOM and what people do with it, sent in chunks to
+ * Chajá under the analytics session, so a replay sits next to that session's events and errors. Inputs are masked by
+ * default; add `chaja-block` to an element to leave it out.
+ *
+ * @param options - Sampling, privacy and timing.
+ * @returns A function that stops recording and sends what is left.
+ * @example
+ * import { init } from "@chaja/sdk-browser";
+ * import { startReplay } from "@chaja/sdk-browser/replay";
+ *
+ * init({ endpoint, key });
+ * startReplay({ sampleRate: 0.5 });
+ */
+export declare function startReplay(options?: ReplayOptions): () => void;
+//#endregion

package/dist/replay.mjs

@@ -0,0 +1,146 @@
+import { getClient } from "./index.mjs";
+import { record } from "@rrweb/record";
+//#region src/replay.ts
+const MAX_BUFFER = 500;
+const KEEPALIVE_LIMIT = 6e4;
+/**
+* Compress a body with gzip where the browser can.
+*
+* @param view - Window.
+* @param body - JSON text.
+* @returns Body and its encoding.
+*/
+async function compress(view, body) {
+	if (typeof view.CompressionStream !== "function") return {
+		body,
+		gzip: false
+	};
+	const stream = new Blob([body]).stream().pipeThrough(new view.CompressionStream("gzip"));
+	return {
+		body: await new Response(stream).arrayBuffer(),
+		gzip: true
+	};
+}
+/**
+* Record the page as a session replay with the client from `init`: the DOM and what people do with it, sent in chunks to
+* Chajá under the analytics session, so a replay sits next to that session's events and errors. Inputs are masked by
+* default; add `chaja-block` to an element to leave it out.
+*
+* @param options - Sampling, privacy and timing.
+* @returns A function that stops recording and sends what is left.
+* @example
+* import { init } from "@chaja/sdk-browser";
+* import { startReplay } from "@chaja/sdk-browser/replay";
+*
+* init({ endpoint, key });
+* startReplay({ sampleRate: 0.5 });
+*/
+function startReplay(options = {}) {
+	const client = getClient();
+	if (!client) return function nothing() {};
+	const view = options.window ?? window;
+	const recorder = options.recorder ?? record;
+	const url = `${client.options.endpoint.replace(/\/+$/u, "")}/api/v1/replay`;
+	const sampleRate = options.sampleRate ?? 1;
+	const state = {
+		session: client.getSessionId() ?? "",
+		seq: 0,
+		sampled: false,
+		buffer: []
+	};
+	/**
+	* Whether this session is recorded, decided once and kept for the tab.
+	*
+	* @param session - Session id.
+	* @returns True when recorded.
+	*/
+	function sampled(session) {
+		const key = `chaja_replay_${session}`;
+		try {
+			const stored = view.sessionStorage.getItem(key);
+			if (stored !== null) return stored === "1";
+			const decision = Math.random() < sampleRate;
+			view.sessionStorage.setItem(key, decision ? "1" : "0");
+			return decision;
+		} catch {
+			return Math.random() < sampleRate;
+		}
+	}
+	state.sampled = sampled(state.session);
+	/**
+	* Send buffered events as the next chunk of their session.
+	*
+	* @param final - The page is going away: keep the request alive.
+	*/
+	async function flush(final = false) {
+		const events = state.buffer.splice(0);
+		if (events.length === 0 || !state.sampled || !client) return;
+		const chunk = JSON.stringify({
+			sessionId: state.session,
+			distinctId: client.getDistinctId(),
+			seq: state.seq,
+			events
+		});
+		state.seq += 1;
+		try {
+			const payload = final ? {
+				body: chunk,
+				gzip: false
+			} : await compress(view, chunk);
+			await view.fetch(url, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					"x-chaja-key": client.options.key,
+					...payload.gzip ? { "content-encoding": "gzip" } : {}
+				},
+				body: payload.body,
+				keepalive: final && chunk.length < KEEPALIVE_LIMIT
+			});
+		} catch {}
+	}
+	/**
+	* Flush, first moving to a new session when the old one expired, with a full snapshot so the new replay starts whole.
+	*/
+	function tick() {
+		if (!client) return;
+		const session = client.getSessionId() ?? state.session;
+		if (session === state.session) {
+			flush();
+			return;
+		}
+		flush();
+		state.session = session;
+		state.seq = 0;
+		state.sampled = sampled(session);
+		recorder.takeFullSnapshot?.(true);
+	}
+	const stopRecording = recorder({
+		emit(event) {
+			if (!state.sampled) return;
+			state.buffer.push(event);
+			if (state.buffer.length >= MAX_BUFFER) flush();
+		},
+		maskAllInputs: options.maskAllInputs ?? true,
+		blockSelector: options.blockSelector ?? ".chaja-block",
+		...options.maskTextSelector ? { maskTextSelector: options.maskTextSelector } : {},
+		recordCanvas: false,
+		inlineStylesheet: true
+	});
+	const timer = view.setInterval(tick, options.flushIntervalMs ?? 5e3);
+	/**
+	* Send what is left when the page is hidden.
+	*/
+	function onHide() {
+		flush(true);
+	}
+	view.addEventListener("pagehide", onHide);
+	return function stop() {
+		stopRecording?.();
+		view.clearInterval(timer);
+		view.removeEventListener("pagehide", onHide);
+		flush(true);
+	};
+}
+//#endregion
+export { startReplay };

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@chaja/sdk-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Chajá error tracking for browsers: global handlers, breadcrumbs and sendBeacon delivery.",
+  "keywords": [
+    "chaja",
+    "error-tracking",
+    "observability",
+    "browser",
+    "sdk"
+  ],
+  "homepage": "https://github.com/emiliodominguez/chaja#readme",
+  "bugs": "https://github.com/emiliodominguez/chaja/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emiliodominguez/chaja.git",
+    "directory": "packages/sdk-browser"
+  },
+  "type": "module",
+  "nx": {
+    "tags": [
+      "scope:sdk",
+      "type:sdk"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./replay": {
+      "types": "./dist/replay.d.mts",
+      "default": "./dist/replay.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@rrweb/record": "^2.1.7"
+  },
+  "peerDependenciesMeta": {
+    "@rrweb/record": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@chaja/protocol": "0.0.0",
+    "@rrweb/record": "2.1.7",
+    "tsdown": "0.23.0"
+  },
+  "dependencies": {
+    "@chaja/sdk-core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/replay.ts --format esm --dts --clean --out-dir dist",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }