@heystack/otel 0.17.0 → 0.19.0

package/dist/product.d.ts

@@ -2,6 +2,19 @@ import { type HeystackOptions } from "./core.js";
 export interface ActivityContext {
     /** Stable pseudonymous identifiers; never email addresses or credentials. */
     userId?: string;
+    /** Optional display context, exported only with allowUserProfiles. */
+    userProfile?: {
+        displayName: string;
+        source: "app" | "clerk";
+    };
+    /** Observed client network context, never inferred from an exporter server. */
+    network?: {
+        ip?: string;
+        country?: string;
+        region?: string;
+        city?: string;
+        source?: string;
+    };
     sessionId?: string;
     feature?: string;
     /** Stable screen/route name, not a URL containing customer data. */
@@ -11,12 +24,20 @@ export interface ActivityContext {
 }
 export interface ProductEvent extends ActivityContext {
     name: string;
+    eventId?: string;
+    attemptId?: string;
     action?: string;
     outcome?: "started" | "succeeded" | "failed" | "cancelled";
     properties?: Record<string, string | number | boolean>;
 }
 export interface ProductAnalyticsOptions extends HeystackOptions {
     environment?: string;
+    allowUserProfiles?: boolean;
+    allowNetworkContext?: boolean;
+    /** Optional versioned event catalogue: rejects unlisted names or missing context. */
+    eventDefinitions?: Readonly<Record<string, {
+        required?: readonly ("feature" | "surface" | "sessionId" | "userId" | "attemptId" | "outcome")[];
+    }>>;
     /** Supply an original, uninstrumented fetch if browser fetch is already patched. */
     fetch?: typeof fetch;
     /** Explicitly allow metadata keys. Unlisted properties are discarded. */
@@ -39,3 +60,18 @@ export interface ProductAnalytics extends ActivityTracker {
  * Bounded, best-effort collection; never auto-captures UI text or form contents.
  * The return value means queued, not delivered or verified business success. */
 export declare function createProductAnalytics(options: ProductAnalyticsOptions): ProductAnalytics;
+/** Per-browser-session facade. Do not share this mutable identity facade on servers. */
+export declare function createBrowserProductAnalytics(options: ProductAnalyticsOptions & {
+    sessionId?: string;
+}): {
+    readonly sessionId: string;
+    /** Starts a fresh session on identity changes. Reconfigure replay with returned ID. */
+    identify(userId: string, profile?: ActivityContext["userProfile"]): string;
+    /** Logout boundary: clear identity and rotate session. Reconfigure replay too. */
+    reset(): string;
+    track(event: ProductEvent): boolean;
+    screen(surface: string, event?: Omit<ProductEvent, "name" | "surface">): boolean;
+    feature(feature: string, event?: Omit<ProductEvent, "name" | "feature">): boolean;
+    flush: () => Promise<boolean>;
+    shutdown: () => Promise<boolean>;
+};

package/dist/product.js

@@ -26,16 +26,30 @@ export function createProductAnalytics(options) {
         track(event) {
             if (stopped || queue.length >= MAX_QUEUE || !NAME.test(event.name))
                 return false;
-            const active = trace.getSpan(context.active())?.spanContext();
             const ctx = { ...bound, ...event };
+            if (options.eventDefinitions && (!Object.hasOwn(options.eventDefinitions, event.name) ||
+                options.eventDefinitions[event.name]?.required?.some(key => !text(ctx[key]))))
+                return false;
+            const active = trace.getSpan(context.active())?.spanContext();
             const attrs = {
-                "event.name": event.name, "event.domain": "product", "event.id": crypto.randomUUID(),
+                "event.name": event.name, "event.domain": "product", "event.id": text(event.eventId) || crypto.randomUUID(), "heystack.schema.version": "1",
             };
             for (const [key, v] of Object.entries({ "enduser.id": ctx.userId, "session.id": ctx.sessionId,
-                "heystack.feature": ctx.feature, "heystack.surface": ctx.surface, "heystack.action": event.action, "heystack.outcome": event.outcome })) {
+                "heystack.attempt.id": event.attemptId, "heystack.feature": ctx.feature, "heystack.surface": ctx.surface, "heystack.action": event.action, "heystack.outcome": event.outcome })) {
                 if (text(v))
                     attrs[key] = text(v);
             }
+            if (options.allowUserProfiles && text(ctx.userId) && ctx.userProfile) {
+                attrs["heystack.user.display_name"] = text(ctx.userProfile.displayName);
+                attrs["heystack.user.source"] = ctx.userProfile.source === "clerk" ? "clerk" : "app";
+            }
+            if (options.allowNetworkContext && ctx.network) {
+                for (const [key, v] of Object.entries({ "client.address": ctx.network.ip, "geo.country.code": ctx.network.country,
+                    "geo.locality.region": ctx.network.region, "geo.locality.name": ctx.network.city, "heystack.geo.source": ctx.network.source })) {
+                    if (text(v))
+                        attrs[key] = text(v);
+                }
+            }
             for (const key of allowed) {
                 const v = event.properties?.[key];
                 if (typeof v === "string")
@@ -95,3 +109,27 @@ export function createProductAnalytics(options) {
     return { ...tracker({}), flush, async shutdown() { stopped = true; if (timer)
             clearInterval(timer); return flush(); } };
 }
+/** Per-browser-session facade. Do not share this mutable identity facade on servers. */
+export function createBrowserProductAnalytics(options) {
+    const client = createProductAnalytics(options);
+    let sessionId = options.sessionId ?? crypto.randomUUID();
+    let user = {};
+    const bound = () => client.withContext({ ...user, sessionId });
+    return {
+        get sessionId() { return sessionId; },
+        /** Starts a fresh session on identity changes. Reconfigure replay with returned ID. */
+        identify(userId, profile) {
+            if (user.userId !== userId)
+                sessionId = crypto.randomUUID();
+            user = { userId, userProfile: profile };
+            return sessionId;
+        },
+        /** Logout boundary: clear identity and rotate session. Reconfigure replay too. */
+        reset() { user = {}; sessionId = crypto.randomUUID(); return sessionId; },
+        track(event) { return bound().track({ ...event, userId: user.userId, userProfile: user.userProfile, sessionId }); },
+        screen(surface, event = {}) { return this.track({ ...event, name: "screen.viewed", surface }); },
+        feature(feature, event = {}) { return this.track({ ...event, name: "feature.used", feature }); },
+        flush: client.flush,
+        shutdown: client.shutdown,
+    };
+}

package/dist/redact.d.ts

@@ -0,0 +1,57 @@
+/** Replacement written in place of a redacted query/fragment parameter value. */
+export declare const REDACTED = "REDACTED";
+/**
+ * Query/fragment parameter names whose VALUES are replaced with `REDACTED`
+ * before a URL is recorded. Compared case-insensitively against the decoded key.
+ * `state` is intentionally NOT listed (OAuth `state` is an anti-CSRF nonce, not a
+ * credential, and it is useful when debugging a broken login redirect).
+ */
+export declare const DEFAULT_REDACTED_QUERY_PARAMS: readonly string[];
+/** Options controlling how URLs are redacted before they are recorded. */
+export interface UrlRedactionOptions {
+    /**
+     * Extra query/fragment parameter names to redact, ADDED to
+     * {@link DEFAULT_REDACTED_QUERY_PARAMS} (case-insensitive). Pass `false` to
+     * turn query/fragment parameter redaction off entirely. Credentials embedded
+     * as URL userinfo (`https://user:pass@host`) are always stripped.
+     */
+    redactQueryParams?: readonly string[] | false;
+}
+/** Privacy options shared by the server entries (`/node`, `/next`, `/workers`). */
+export interface SpanPrivacyOptions extends UrlRedactionOptions {
+    /**
+     * Record the end-user's IP address (`client.address`, plus `http.client_ip` /
+     * peer-address attributes on SERVER spans under `/node`). **Off by default** —
+     * an IP address is personal data in most jurisdictions. Set `true` only if you
+     * have a lawful basis and have told your users.
+     */
+    captureClientIp?: boolean;
+}
+export type UrlRedactor = (url: string) => string;
+/** Build a reusable redactor (pre-computes the key set). */
+export declare function makeUrlRedactor(opts?: UrlRedactionOptions): UrlRedactor;
+/**
+ * Redact secrets from a URL before it is recorded: strips userinfo
+ * (`https://user:pass@host` → `https://host`) and replaces the VALUE of every
+ * sensitive query or fragment parameter (see
+ * {@link DEFAULT_REDACTED_QUERY_PARAMS}) with `REDACTED`. Everything else —
+ * scheme, host, path, non-sensitive parameters, plain `#anchors` — is kept
+ * byte-for-byte. Works on absolute and relative URLs (`/cb?code=…`).
+ */
+export declare function redactUrl(url: string, opts?: UrlRedactionOptions): string;
+/** Span/log attributes that hold a full or relative URL. */
+export declare const URL_ATTRS: readonly ["url.full", "http.url", "http.target", "url.original"];
+/** End-user IP attributes, dropped on every span unless `captureClientIp`. */
+export declare const CLIENT_IP_ATTRS: readonly ["client.address", "http.client_ip"];
+/** Peer-address attributes that equal the end-user (or edge proxy) IP on a SERVER span. */
+export declare const SERVER_PEER_IP_ATTRS: readonly ["net.peer.ip", "network.peer.address", "net.sock.peer.addr"];
+/**
+ * Return `attrs` with every URL-bearing attribute redacted and, unless
+ * `captureClientIp`, end-user IP attributes removed. Returns the SAME object
+ * when nothing changed (cheap common path), otherwise a shallow copy.
+ */
+export declare function applySpanPrivacy(attrs: Record<string, unknown>, o: {
+    redact: UrlRedactor;
+    captureClientIp?: boolean;
+    isServer?: boolean;
+}): Record<string, unknown>;

package/dist/redact.js

@@ -0,0 +1,190 @@
+// ---------------------------------------------------------------------------
+// URL + client-IP privacy helpers (shared by /node, /workers and /web)
+//
+// Pure string logic with NO imports — safe in every entry, including the
+// WinterCG-only `/workers` build and the browser `/web` bundle. Deliberately
+// avoids `new URL(...).href` re-serialisation so a redacted URL keeps the exact
+// spelling of everything that was not redacted (and so relative targets such as
+// `http.target` = `/cb?code=…` work without a base).
+// ---------------------------------------------------------------------------
+/** Replacement written in place of a redacted query/fragment parameter value. */
+export const REDACTED = "REDACTED";
+/**
+ * Query/fragment parameter names whose VALUES are replaced with `REDACTED`
+ * before a URL is recorded. Compared case-insensitively against the decoded key.
+ * `state` is intentionally NOT listed (OAuth `state` is an anti-CSRF nonce, not a
+ * credential, and it is useful when debugging a broken login redirect).
+ */
+export const DEFAULT_REDACTED_QUERY_PARAMS = [
+    "key",
+    "api_key",
+    "apikey",
+    "api-key",
+    "token",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "auth_token",
+    "api_token",
+    "oauth_token",
+    "oauth_signature",
+    "code",
+    "sig",
+    "signature",
+    "password",
+    "passwd",
+    "pass",
+    "secret",
+    "client_secret",
+    "auth",
+    "authorization",
+    "session",
+    "sessionid",
+    "session_id",
+    "jwt",
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    "x-goog-signature",
+    "x-goog-credential",
+];
+function safeDecode(s) {
+    try {
+        return decodeURIComponent(s.replace(/\+/g, " "));
+    }
+    catch {
+        return s;
+    }
+}
+/** Redact sensitive parameter values in a bare `a=1&b=2` string. */
+function redactParams(qs, keys) {
+    if (!qs || keys.size === 0)
+        return qs;
+    let changed = false;
+    const parts = qs.split("&").map((part) => {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            return part; // bare flag, no value to leak
+        const key = part.slice(0, eq);
+        if (!keys.has(safeDecode(key).trim().toLowerCase()))
+            return part;
+        if (part.slice(eq + 1) === REDACTED)
+            return part;
+        changed = true;
+        return `${key}=${REDACTED}`;
+    });
+    return changed ? parts.join("&") : qs;
+}
+/** Strip `user[:password]@` from an absolute (or protocol-relative) URL. */
+const USERINFO_RE = /^((?:[a-zA-Z][a-zA-Z0-9+.-]*:)?\/\/)[^/?#]*@/;
+function redactWith(url, keys) {
+    let out = url.replace(USERINFO_RE, "$1");
+    const hash = out.indexOf("#");
+    let fragment;
+    if (hash >= 0) {
+        fragment = out.slice(hash + 1);
+        out = out.slice(0, hash);
+    }
+    const q = out.indexOf("?");
+    if (q >= 0)
+        out = `${out.slice(0, q)}?${redactParams(out.slice(q + 1), keys)}`;
+    if (fragment !== undefined) {
+        // OAuth implicit flow puts tokens in the fragment (`#access_token=…`); hash
+        // routers put a query after a route (`#/cb?code=…`). Plain anchors pass.
+        const fq = fragment.indexOf("?");
+        if (fq >= 0) {
+            fragment = `${fragment.slice(0, fq)}?${redactParams(fragment.slice(fq + 1), keys)}`;
+        }
+        else if (fragment.includes("=")) {
+            fragment = redactParams(fragment, keys);
+        }
+        out = `${out}#${fragment}`;
+    }
+    return out;
+}
+function keySet(opts) {
+    if (opts?.redactQueryParams === false)
+        return new Set();
+    const extra = Array.isArray(opts?.redactQueryParams) ? opts.redactQueryParams : [];
+    return new Set([...DEFAULT_REDACTED_QUERY_PARAMS, ...extra].map((k) => String(k).trim().toLowerCase()));
+}
+/** Build a reusable redactor (pre-computes the key set). */
+export function makeUrlRedactor(opts) {
+    const keys = keySet(opts);
+    return (url) => (typeof url === "string" && url ? redactWith(url, keys) : url);
+}
+const defaultRedactor = makeUrlRedactor();
+/**
+ * Redact secrets from a URL before it is recorded: strips userinfo
+ * (`https://user:pass@host` → `https://host`) and replaces the VALUE of every
+ * sensitive query or fragment parameter (see
+ * {@link DEFAULT_REDACTED_QUERY_PARAMS}) with `REDACTED`. Everything else —
+ * scheme, host, path, non-sensitive parameters, plain `#anchors` — is kept
+ * byte-for-byte. Works on absolute and relative URLs (`/cb?code=…`).
+ */
+export function redactUrl(url, opts) {
+    return opts ? makeUrlRedactor(opts)(url) : defaultRedactor(url);
+}
+/** Span/log attributes that hold a full or relative URL. */
+export const URL_ATTRS = ["url.full", "http.url", "http.target", "url.original"];
+/** Attributes that hold a bare query string (no leading `?`). */
+const QUERY_ATTRS = ["url.query"];
+/** Attributes that hold a bare fragment (no leading `#`). */
+const FRAGMENT_ATTRS = ["url.fragment"];
+/** End-user IP attributes, dropped on every span unless `captureClientIp`. */
+export const CLIENT_IP_ATTRS = ["client.address", "http.client_ip"];
+/** Peer-address attributes that equal the end-user (or edge proxy) IP on a SERVER span. */
+export const SERVER_PEER_IP_ATTRS = [
+    "net.peer.ip",
+    "network.peer.address",
+    "net.sock.peer.addr",
+];
+/**
+ * Return `attrs` with every URL-bearing attribute redacted and, unless
+ * `captureClientIp`, end-user IP attributes removed. Returns the SAME object
+ * when nothing changed (cheap common path), otherwise a shallow copy.
+ */
+export function applySpanPrivacy(attrs, o) {
+    let out;
+    const set = (k, v) => {
+        out ??= { ...attrs };
+        if (v === undefined)
+            delete out[k];
+        else
+            out[k] = v;
+    };
+    for (const k of URL_ATTRS) {
+        const v = attrs[k];
+        if (typeof v === "string") {
+            const r = o.redact(v);
+            if (r !== v)
+                set(k, r);
+        }
+    }
+    for (const k of QUERY_ATTRS) {
+        const v = attrs[k];
+        if (typeof v === "string" && v) {
+            const r = o.redact(`?${v.replace(/^\?/, "")}`).slice(1);
+            if (r !== v)
+                set(k, r);
+        }
+    }
+    for (const k of FRAGMENT_ATTRS) {
+        const v = attrs[k];
+        if (typeof v === "string" && v) {
+            const r = o.redact(`#${v.replace(/^#/, "")}`).slice(1);
+            if (r !== v)
+                set(k, r);
+        }
+    }
+    if (!o.captureClientIp) {
+        for (const k of CLIENT_IP_ATTRS)
+            if (k in attrs)
+                set(k, undefined);
+        if (o.isServer)
+            for (const k of SERVER_PEER_IP_ATTRS)
+                if (k in attrs)
+                    set(k, undefined);
+    }
+    return out ?? attrs;
+}

package/dist/web.d.ts

@@ -1,3 +1,4 @@
+import { type UrlRedactor } from "./redact.js";
 /** 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 {
@@ -130,6 +131,14 @@ export interface InstrumentWebOptions {
      * Rate-capped and recursion-guarded so it can never feed a self-export loop.
      */
     captureConsole?: "error" | "warn" | false;
+    /**
+     * Extra query/fragment parameter names whose values are replaced with
+     * `REDACTED` in every URL this SDK records (fetch spans, page URL on errors,
+     * console logs, bug reports and replay). Added to the built-in list (`token`,
+     * `code`, `key`, `apikey`, `access_token`, `signature`, …); userinfo is always
+     * stripped. Pass `false` to turn parameter redaction off.
+     */
+    redactQueryParams?: readonly string[] | false;
 }
 /**
  * Pure: is browser distributed tracing active for this run? Requires BOTH the app
@@ -146,6 +155,33 @@ export declare function tracingActive(opts: Pick<InstrumentWebOptions, "tracing"
  * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
  */
 export declare function errorCaptureActive(opts: Pick<InstrumentWebOptions, "errors">, cfg: Pick<RecorderConfig, "errors_enabled">): boolean;
+/** rrweb `record()` privacy options for a masking mode. */
+export interface ReplayPrivacyOptions {
+    maskAllInputs: boolean;
+    maskTextSelector: string;
+    blockSelector: string;
+    maskInputFn: (text: string, element: HTMLElement) => string;
+    maskTextFn: (text: string, element: HTMLElement | null) => string;
+}
+/**
+ * Pure: the rrweb privacy options for a masking mode. Anything other than an
+ * explicit `"relaxed"` is treated as `"strict"` (fail-closed).
+ *
+ * - **strict** (default): ALL text and ALL input values are masked
+ *   (`maskTextSelector: "*"` + `maskAllInputs`). Mark an element with
+ *   `data-hs-unmask` to record it (and its descendants) in cleartext; a nested
+ *   `data-hs-mask` re-masks. Password inputs are ALWAYS masked, even inside a
+ *   `data-hs-unmask` region.
+ * - **relaxed**: text is recorded except inside `data-hs-mask`; input values are
+ *   recorded except passwords (rrweb's default).
+ *
+ * Both modes drop `data-hs-block` elements entirely (recorded as a placeholder
+ * box). Masking applies to text nodes and input values only — element ATTRIBUTES
+ * (`title`, `alt`, `placeholder`, `aria-label`, link `href`s) are not masked by
+ * rrweb, so use `data-hs-block` for regions whose attributes are sensitive.
+ */
+export declare function replayPrivacyOptions(mode: RecorderConfig["masking_mode"] | undefined): ReplayPrivacyOptions;
+export declare function redactReplayEvent(event: unknown, redact?: UrlRedactor): unknown;
 /** A caller-owned session UUID allows product activity to correlate with replay. */
 export declare function resolveWebSessionId(candidate?: string): string;
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
@@ -236,6 +272,8 @@ export interface TracingPatchOpts {
     /** Cross-origin backends allowed to receive trace headers (same-origin always is).
      *  Third-party / non-listed cross-origin calls are passed through untouched. */
     propagateTargets?: ReadonlyArray<string | RegExp>;
+    /** URL redactor for the recorded `url.full` (default: built-in redaction). */
+    redactUrl?: UrlRedactor;
     rng?: () => number;
 }
 /** Patch window.fetch to emit a real CLIENT span per outbound call, inject that
@@ -322,6 +360,8 @@ export interface ErrorCaptureOpts {
     rateCap?: number;
     /** Rate window in ms (default 60_000). */
     rateWindowMs?: number;
+    /** URL redactor for the recorded page URL (default: built-in redaction). */
+    redactUrl?: UrlRedactor;
 }
 /** Wire up `window.onerror` / `unhandledrejection` (+ optional console) capture.
  *  Returns an unpatch function. Recursion-guarded (anything logged on our own
@@ -356,6 +396,8 @@ export interface BugReportSession {
     logsExporter: BrowserLogsExporter;
     version?: string;
     build?: string;
+    /** URL redactor for the attached page URL (default: built-in redaction). */
+    redactUrl?: UrlRedactor;
 }
 /** Internal: instrumentWeb() registers the active session here (and clears it with
  *  `null` on stop) so the module-level reportBug() works after instrumentWeb() is