@heystack/otel 0.3.4 → 0.4.0

package/README.md

@@ -22,6 +22,7 @@ HEYSTACK_API_KEY=sk_live_…
 | Next.js — **any** deploy target (Vercel/Node **and** Cloudflare/OpenNext) | `@heystack/otel/next` | `registerHeystack` in `instrumentation.ts`. Auto-detects Node vs Cloudflare workerd and picks the right exporter. No-op on Edge. |
 | Standalone Cloudflare Workers (hand-written `export default { fetch }`) | `@heystack/otel/workers` | `instrument()` wraps your handler. Fetch-based exporter, flushes via `ctx.waitUntil`. |
 | Node / Express / Fastify / NestJS (long-running server) | `@heystack/otel/node` | `initHeystack`: auto-instrumentations + graceful shutdown. |
+| Browser (SPA / any web frontend) | `@heystack/otel/web` | `instrumentWeb`: session replay + W3C `traceparent` on outgoing fetch. No-op on the server (SSR-safe). |
 | Anywhere (pure helpers) | `@heystack/otel` | `buildExporterConfig`, types. No Node SDK loaded. |
 
 ## Node / Express / etc.
@@ -141,6 +142,50 @@ export class Counter {
 
 The default export still needs to be wrapped with `instrument()` (or `initHeystackWorkers()` called) so the global provider + ContextManager are registered before the DO runs.
 
+## `@heystack/otel/web` (browser / session replay)
+
+For a browser frontend (any SPA / web app), `instrumentWeb` records **session replay** and injects a W3C `traceparent` header on outgoing `fetch` calls, so replays correlate with the backend traces they triggered. It is a **no-op on the server** (SSR-safe), so it's safe to call from code that also runs during server rendering.
+
+```ts
+import { instrumentWeb } from "@heystack/otel/web";
+
+const stop = await instrumentWeb({
+  apiKey: process.env.HEYSTACK_API_KEY, // same ingest key as the rest of the SDK
+  service: "my-web-app",
+});
+
+// later, e.g. on unmount / sign-out:
+stop();
+```
+
+`instrumentWeb` returns a `stop()` function that ends the recording session.
+
+### Options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `apiKey` | `string` | **Required.** The same Heystack ingest key used by the rest of the SDK. |
+| `service` | `string` | **Required.** The OTel service name (matches the app's service in the console). |
+| `userId` | `string?` | Optional app-supplied identifier stamped on the session. |
+| `endpoint` | `string?` | Optional ingest endpoint override (defaults to the Heystack ingest endpoint). |
+| `sampleRate` | `number?` | Optional **local** override for the recording sample rate (0–1). By default sampling is controlled from the console. |
+| `flushIntervalMs` | `number?` | How often buffered events are flushed (default 5000ms). |
+| `flushEveryEvents` | `number?` | Max buffered events before an early flush (default 200). |
+
+### Sampling & masking come from the console
+
+By default **sampling and masking are controlled from the Heystack console** — enable replay and tune the sample rate / masking mode under **Settings → Session replay** for the app. `sampleRate` is only an optional local override; you don't need to pass it.
+
+### Privacy / masking (rrweb)
+
+Masking is **strict by default**: all text inputs and passwords are masked before anything leaves the browser. For finer control, annotate your DOM:
+
+| Attribute | Effect |
+| --- | --- |
+| `data-hs-mask` | Masks an element's text. |
+| `data-hs-block` | Blocks a region entirely (it's not recorded). |
+| `data-hs-unmask` | Reveals an element you explicitly trust (un-masks it). |
+
 ## Flushing
 
 On Workers/edge the export is a `fetch()` POST, and the isolate can be torn down the instant your handler returns. **You must let that POST complete or the trace is silently dropped** — this is the #1 cause of flaky Workers tracing. `flushHeystack()` and `instrument()`'s built-in flush both await the in-flight fetch (not just the OTel span processor, which does *not* wait for it).
@@ -157,6 +202,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.3.5`** — **type-constraint fix (Workers).** A Worker whose `queue` consumer is typed with a concrete message body — `queue(batch: MessageBatch<MyJob>, …)`, the normal case — failed to compile against `instrument()` in 0.3.4 (`TS2345`: `MessageBatch<unknown>` not assignable to `MessageBatch<MyJob>`). The `WorkerHandler` constraint declared its entrypoints as arrow properties, whose parameters are checked **contravariantly** under `strictFunctionTypes`, so a narrowed handler wasn't assignable. 0.3.5 declares them with **method syntax** (bivariant parameters) and widens the batch to `MessageBatch<any>`, mirroring Cloudflare's own `ExportedHandler` — a typed-queue Worker now type-checks with a bare `instrument(handler, cfg)`. Runtime behaviour unchanged. Also adds a **consumer type-check gate** (`pnpm consumer-typecheck`, run in `check` and `prepublishOnly`) that compiles a fully-typed Worker against the built `dist` through the public `exports` map and asserts `satisfies ExportedHandler<Env>` — the regression that escaped in 0.3.3/0.3.4 now fails the build before publish.
 - **`0.3.4`** — **type-inference fix (Workers).** Restores `instrument()`'s ability to infer the handler's concrete `Env` type. In 0.3.3 the signature was `instrument<E = unknown, H extends WorkerHandler<E>>`, so `E` defaulted to `unknown` and was never recovered from the handler — under `strictFunctionTypes` a Worker typed `fetch(req, env: Env, ctx)` then failed to compile (`TS2345: 'Env' is not assignable to 'unknown'`) unless the caller passed `instrument<Env>(...)` explicitly. 0.3.4 infers `E` from the handler argument (`instrument<H extends WorkerHandler<any>>(...): Instrumented<EnvOf<H>, H>`), so a bare `instrument(handler, cfg)` type-checks again. Runtime behaviour is unchanged; no `0.3.3` consumer needs the explicit type arg after upgrading.
 - **`0.3.3`** — `/next` uses bare, exports-mapped dynamic imports so the OpenNext (Cloudflare Pages) build resolves the workers entry correctly (fixes a build break). Workers/Node paths unchanged.
 - **`0.3.2`** — runtime-correctness fixes:

package/dist/web.d.ts

@@ -0,0 +1,84 @@
+/** The replay chunk metadata sent alongside the events array. Defined locally so
+ *  the published SDK does not depend on the private @heystack/schema package. */
+export interface ReplayChunkMeta {
+    start_url: string;
+    event_count: number;
+    click_count: number;
+    error_count: number;
+    has_snapshot: boolean;
+    user_id?: string;
+    browser?: string;
+    device?: string;
+    trace_ids?: string[];
+    /** Client epoch millis for this chunk's first event; falls back to ingest time. */
+    ts?: number;
+}
+export interface RecorderConfig {
+    enabled: boolean;
+    sample_rate: number;
+    masking_mode: "strict" | "relaxed";
+}
+/** Pure: decide once per session whether to record. rng defaults to Math.random. */
+export declare function shouldRecord(cfg: RecorderConfig, rng?: () => number): boolean;
+export interface ChunkCtx {
+    url: string;
+    errorCount: number;
+    userId?: string;
+    browser?: string;
+    device?: string;
+    traceIds?: string[];
+}
+interface RRWebEventish {
+    type?: number;
+    timestamp?: number;
+    data?: {
+        source?: number;
+        type?: number;
+    };
+}
+/** Pure: derive the per-chunk metadata sent alongside the events array. */
+export declare function computeChunkMeta(events: RRWebEventish[], ctx: ChunkCtx): ReplayChunkMeta;
+/** Browser gzip via the platform CompressionStream. */
+export declare function gzipString(text: string): Promise<Uint8Array>;
+export interface TransportOpts {
+    endpoint: string;
+    apiKey: string;
+    sessionId: string;
+    fetchImpl?: typeof fetch;
+    gzipImpl?: (s: string) => Promise<Uint8Array>;
+}
+/** Batches -> gzips -> POSTs replay chunks, tracking the monotonic chunk_seq. */
+export declare class ReplayTransport {
+    private seq;
+    private readonly o;
+    constructor(opts: TransportOpts);
+    send(events: unknown[], ctx: ChunkCtx, keepalive?: boolean): Promise<void>;
+}
+export interface InstrumentWebOptions {
+    apiKey: string;
+    service: string;
+    endpoint?: string;
+    /** Optional app-supplied user identifier stamped on the session. */
+    userId?: string;
+    /** Local overrides; by default sampling + masking come from server config. */
+    sampleRate?: number;
+    flushIntervalMs?: number;
+    /** Max buffered events before an early flush. */
+    flushEveryEvents?: number;
+}
+/** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
+ *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
+export declare function instrumentWeb(opts: InstrumentWebOptions): Promise<() => void>;
+export declare function makeTraceparent(traceId: string, spanId: string): string;
+/** Collects trace ids observed during a session (deduped, capped). */
+export declare class TraceIdCollector {
+    private readonly cap;
+    private readonly ids;
+    constructor(cap?: number);
+    add(id: string): void;
+    drain(): string[];
+}
+/** Patch window.fetch to inject traceparent on outgoing calls and record the
+ *  trace id for correlation. Returns an unpatch function. */
+export declare function patchFetchForCorrelation(collector: TraceIdCollector): () => void;
+export {};

package/dist/web.js

@@ -0,0 +1,211 @@
+import { DEFAULT_ENDPOINT } from "./core.js";
+/** Pure: decide once per session whether to record. rng defaults to Math.random. */
+export function shouldRecord(cfg, rng = Math.random) {
+    if (!cfg.enabled)
+        return false;
+    return rng() < cfg.sample_rate;
+}
+// rrweb event-shape constants (kept local so we don't import rrweb types into the pure layer).
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+const SOURCE_MOUSE_INTERACTION = 2;
+const MOUSE_CLICK = 2;
+/** Pure: derive the per-chunk metadata sent alongside the events array. */
+export function computeChunkMeta(events, ctx) {
+    let clicks = 0;
+    let hasSnapshot = false;
+    let earliest = Number.POSITIVE_INFINITY;
+    for (const e of events) {
+        if (e.type === FULL_SNAPSHOT)
+            hasSnapshot = true;
+        if (e.type === INCREMENTAL && e.data?.source === SOURCE_MOUSE_INTERACTION && e.data?.type === MOUSE_CLICK) {
+            clicks++;
+        }
+        if (typeof e.timestamp === "number" && e.timestamp < earliest)
+            earliest = e.timestamp;
+    }
+    return {
+        start_url: ctx.url,
+        event_count: events.length,
+        click_count: clicks,
+        error_count: ctx.errorCount,
+        has_snapshot: hasSnapshot,
+        user_id: ctx.userId,
+        browser: ctx.browser,
+        device: ctx.device,
+        trace_ids: ctx.traceIds ?? [],
+        ts: Number.isFinite(earliest) ? earliest : Date.now(),
+    };
+}
+/** Browser gzip via the platform CompressionStream. */
+export async function gzipString(text) {
+    const stream = new Response(text).body.pipeThrough(new CompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+/** Batches -> gzips -> POSTs replay chunks, tracking the monotonic chunk_seq. */
+export class ReplayTransport {
+    seq = 0;
+    o;
+    constructor(opts) {
+        this.o = {
+            fetchImpl: opts.fetchImpl ?? fetch.bind(globalThis),
+            gzipImpl: opts.gzipImpl ?? gzipString,
+            ...opts,
+        };
+    }
+    async send(events, ctx, keepalive = false) {
+        if (events.length === 0)
+            return;
+        const meta = computeChunkMeta(events, ctx);
+        const body = JSON.stringify({ session_id: this.o.sessionId, chunk_seq: this.seq++, events, meta });
+        const bytes = await this.o.gzipImpl(body);
+        await this.o.fetchImpl(`${this.o.endpoint}/v1/replay`, {
+            method: "POST",
+            keepalive,
+            headers: {
+                authorization: `Bearer ${this.o.apiKey}`,
+                "content-type": "application/json",
+                "content-encoding": "gzip",
+            },
+            // `Uint8Array` is a valid fetch body at runtime in every browser/edge
+            // runtime; the cast bridges the DOM vs @cloudflare/workers-types BodyInit
+            // typings (the latter is pulled in globally by workers.ts's triple-slash
+            // reference and narrows BodyInit to exclude Uint8Array).
+            body: bytes,
+        }).catch(() => { });
+    }
+}
+const DEFAULT_FLUSH_MS = 5000;
+const DEFAULT_FLUSH_EVENTS = 200;
+/** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
+ *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
+export async function instrumentWeb(opts) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return () => { };
+    const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    // 1. Fetch per-app config.
+    let cfg = { enabled: false, sample_rate: opts.sampleRate ?? 0, masking_mode: "strict" };
+    try {
+        const res = await fetch(`${endpoint}/v1/replay/config`, { headers: { authorization: `Bearer ${opts.apiKey}` } });
+        if (res.ok)
+            cfg = await res.json();
+    }
+    catch { /* offline / blocked - fall back to disabled */ }
+    if (opts.sampleRate !== undefined)
+        cfg = { ...cfg, sample_rate: opts.sampleRate };
+    // 2. Session-level sampling decision.
+    if (!shouldRecord(cfg))
+        return () => { };
+    // 3. Start the recorder.
+    const { record } = await import("rrweb");
+    // An element marked `data-hs-unmask` (or any descendant of one) is recorded in
+    // cleartext; everything else is masked. rrweb 2.0.1's real opt-out hooks are
+    // `maskInputFn`/`maskTextFn` — there is no `unmaskTextSelector` option.
+    // Signatures (from rrweb-snapshot 2.0.1):
+    //   MaskInputFn = (text: string, element: HTMLElement) => string
+    //   MaskTextFn  = (text: string, element: HTMLElement | null) => string
+    // `maskTextFn`'s element can be null, so the `?.closest?.` chain is guarded.
+    const reveal = (text, element) => !!element?.closest?.("[data-hs-unmask]");
+    const maskInputFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
+    const maskTextFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
+    const sessionId = crypto.randomUUID();
+    const transport = new ReplayTransport({ endpoint, apiKey: opts.apiKey, sessionId });
+    // Install the fetch patch AFTER the transport is constructed so the recorder's
+    // own upload POSTs (which captured the original fetch at construction time via
+    // fetch.bind(globalThis)) are not self-traced.
+    const traces = new TraceIdCollector();
+    const unpatch = patchFetchForCorrelation(traces);
+    let buffer = [];
+    let errorCount = 0;
+    const browser = navigator.userAgent;
+    const device = matchMediaDevice();
+    const onError = () => { errorCount++; };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onError);
+    const flush = (keepalive = false) => {
+        if (buffer.length === 0)
+            return;
+        const events = buffer;
+        buffer = [];
+        const errs = errorCount;
+        errorCount = 0;
+        void transport.send(events, {
+            url: location.href, errorCount: errs, userId: opts.userId, browser, device,
+            traceIds: traces.drain(),
+        }, keepalive);
+    };
+    const stopRecord = record({
+        emit(event) {
+            buffer.push(event);
+            if (buffer.length >= (opts.flushEveryEvents ?? DEFAULT_FLUSH_EVENTS))
+                flush();
+        },
+        maskAllInputs: cfg.masking_mode === "strict",
+        maskTextSelector: "[data-hs-mask]",
+        blockSelector: "[data-hs-block]",
+        maskInputFn,
+        maskTextFn,
+    });
+    const interval = setInterval(() => flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
+    const onHide = () => { if (document.visibilityState === "hidden")
+        flush(true); };
+    document.addEventListener("visibilitychange", onHide);
+    window.addEventListener("pagehide", () => flush(true));
+    return () => {
+        clearInterval(interval);
+        document.removeEventListener("visibilitychange", onHide);
+        window.removeEventListener("error", onError);
+        window.removeEventListener("unhandledrejection", onError);
+        stopRecord?.();
+        unpatch();
+        flush(true);
+    };
+}
+function matchMediaDevice() {
+    if (typeof matchMedia === "undefined")
+        return "unknown";
+    return matchMedia("(max-width: 768px)").matches ? "mobile" : "desktop";
+}
+function randHex(bytes) {
+    const a = new Uint8Array(bytes);
+    crypto.getRandomValues(a);
+    return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+export function makeTraceparent(traceId, spanId) {
+    return `00-${traceId}-${spanId}-01`;
+}
+/** Collects trace ids observed during a session (deduped, capped). */
+export class TraceIdCollector {
+    cap;
+    ids = new Set();
+    constructor(cap = 50) {
+        this.cap = cap;
+    }
+    add(id) {
+        if (this.ids.size >= this.cap || this.ids.has(id))
+            return;
+        this.ids.add(id);
+    }
+    drain() {
+        const out = [...this.ids];
+        this.ids.clear();
+        return out;
+    }
+}
+/** Patch window.fetch to inject traceparent on outgoing calls and record the
+ *  trace id for correlation. Returns an unpatch function. */
+export function patchFetchForCorrelation(collector) {
+    if (typeof window === "undefined" || !window.fetch)
+        return () => { };
+    const orig = window.fetch.bind(window);
+    window.fetch = ((input, init) => {
+        const traceId = randHex(16);
+        const spanId = randHex(8);
+        collector.add(traceId);
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        if (!headers.has("traceparent"))
+            headers.set("traceparent", makeTraceparent(traceId, spanId));
+        return orig(input, { ...init, headers });
+    });
+    return () => { window.fetch = orig; };
+}

package/dist/workers.d.ts

@@ -197,9 +197,9 @@ export declare function __resetWarnings(): void;
  * a Worker never drops a handler Cloudflare requires for deploy.
  */
 interface WorkerHandler<E> {
-    fetch?: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response> | Response;
-    queue?: (batch: MessageBatch, env: E, ctx: ExecutionContext) => Promise<void> | void;
-    scheduled?: (controller: ScheduledController, env: E, ctx: ExecutionContext) => Promise<void> | void;
+    fetch?(req: Request, env: E, ctx: ExecutionContext): Promise<Response> | Response;
+    queue?(batch: MessageBatch<any>, env: E, ctx: ExecutionContext): Promise<void> | void;
+    scheduled?(controller: ScheduledController, env: E, ctx: ExecutionContext): Promise<void> | void;
     [key: string]: unknown;
 }
 /**

package/package.json

@@ -1,26 +1,48 @@
 {
   "name": "@heystack/otel",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
   "main": "./dist/core.js",
   "types": "./dist/core.d.ts",
   "exports": {
-    ".": { "types": "./dist/core.d.ts", "import": "./dist/core.js" },
-    "./node": { "types": "./dist/node.d.ts", "import": "./dist/node.js" },
-    "./next": { "types": "./dist/next.d.ts", "import": "./dist/next.js" },
-    "./workers": { "types": "./dist/workers.d.ts", "import": "./dist/workers.js" }
+    ".": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./workers": {
+      "types": "./dist/workers.d.ts",
+      "import": "./dist/workers.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
-  "files": ["dist", "README.md"],
-  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "validate": "node scripts/validate-entries.mjs",
-    "check": "pnpm typecheck && pnpm build && pnpm validate && pnpm test",
-    "prepublishOnly": "pnpm build && pnpm validate"
+    "consumer-typecheck": "node scripts/consumer-typecheck.mjs",
+    "check": "pnpm typecheck && pnpm build && pnpm validate && pnpm consumer-typecheck && pnpm test",
+    "prepublishOnly": "pnpm build && pnpm validate && pnpm consumer-typecheck"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
@@ -30,7 +52,8 @@
     "@opentelemetry/auto-instrumentations-node": "^0.55.0",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/resources": "^1.30.0",
-    "@opentelemetry/semantic-conventions": "^1.30.0"
+    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "rrweb": "^2.0.0-alpha.18"
   },
   "devDependencies": {
     "vitest": "^2.1.0",