@heystack/otel 0.16.0 → 0.18.0

package/README.md

@@ -659,3 +659,57 @@ claude mcp add --transport http heystack https://mcp.heystack.dev/mcp
 ```
 
 One-click links for Cursor and VS Code, commands for Codex/Gemini CLI, personal access tokens for CI, and the full tool reference are in the docs: **https://heystack.dev/docs/mcp**.
+
+
+## Product activity (0.17.0)
+
+Use `createProductAnalytics` from `@heystack/otel/product` alongside the runtime
+instrumentation. `track({ name, feature?, surface?, action?, outcome?, userId?,
+sessionId?, traceId?, spanId?, properties? })` queues an explicit event.
+`withContext(context)` returns an immutable request/session tracker;
+`feature(name, options?)` and `screen(name, options?)` are convenience methods.
+There is no mutable global user identity. Read the [full guide](https://heystack.dev/docs/product-activity).
+
+```ts
+import { createProductAnalytics } from "@heystack/otel/product";
+const activity = createProductAnalytics({ apiKey, service: "api", version: "2.4.0", allowedProperties: ["plan"] });
+activity.withContext({ userId, sessionId, feature: "signup" }).track({
+  name: "signup.completed", outcome: "succeeded", properties: { plan: "starter" },
+});
+await activity.flush(); // Workers: ctx.waitUntil(activity.flush())
+```
+
+Only allowlisted metadata is exported. Queue: 200 events; batches: 50;
+properties: 20 keys, 256-character strings. `track` reports queued, `flush`
+reports HTTP acceptance, not durable query visibility. Failed batches remain
+bounded for retry; counts may include duplicates. No automatic click/form/text
+capture. The browser-only `flushIntervalMs` timer is opt-in (minimum 5s);
+servers have no background timer. Call `shutdown()` to stop and flush.
+
+`instrumentWeb` now accepts `sessionId`, a UUID shared with product activity.
+Capture product collection's original fetch before calling `instrumentWeb`,
+or supply an original `fetch`. Rotate session UUID and discard bound user
+trackers on logout; restart replay to avoid linking different people. Replay
+sampling remains independent. Use a dedicated browser ingest configuration,
+never expose the backend secret. Native clients may emit the documented event
+attributes through existing log APIs.
+
+
+### Product instrumentation 0.18.0
+
+`createBrowserProductAnalytics` provides a per-browser identity/session facade:
+`identify` rotates on account changes; `reset` clears identity and returns a fresh
+session UUID. Restart replay with that UUID. Servers continue to use immutable
+`createProductAnalytics().withContext()` per request.
+
+Events accept `eventId` (stable on retries) and `attemptId` (shared by started and
+terminal outcomes). Optional `eventDefinitions` validates declared names and
+required context. `allowUserProfiles` enables explicitly supplied
+`userProfile: { displayName, source: "clerk" | "app" }`; `allowNetworkContext`
+enables original-client IP/geography supplied via `network`. Both are off by
+default. Heystack does not resolve monitored users through its own Clerk directory.
+
+Emit `screen.viewed` for actual navigation, with stable `surface` and `sessionId`.
+Emit feature attempts with `feature`, `attemptId` and `outcome`. Keep the same
+user/session/attempt context across backend calls. See the [exact telemetry
+contract and verification checklist](https://heystack.dev/docs/product-activity).

package/dist/product.d.ts

@@ -0,0 +1,77 @@
+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. */
+    surface?: string;
+    traceId?: string;
+    spanId?: string;
+}
+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. */
+    allowedProperties?: readonly string[];
+    /** Opt-in browser flush timer. Default: no background work; await flush on servers. */
+    flushIntervalMs?: number;
+}
+export interface ActivityTracker {
+    track(event: ProductEvent): boolean;
+    feature(name: string, event?: Omit<ProductEvent, "name" | "feature">): boolean;
+    screen(name: string, event?: Omit<ProductEvent, "name" | "surface">): boolean;
+    /** Immutable binding. Create one per request/session; never store request identity globally. */
+    withContext(context: ActivityContext): ActivityTracker;
+}
+export interface ProductAnalytics extends ActivityTracker {
+    flush(): Promise<boolean>;
+    shutdown(): Promise<boolean>;
+}
+/** Explicit product activity over the existing OTLP logs ingest path.
+ * 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

@@ -0,0 +1,135 @@
+import { suppressTracing } from "@opentelemetry/core";
+import { context, trace, isSpanContextValid } from "@opentelemetry/api";
+import { DEFAULT_ENDPOINT, releaseResourceAttributes } from "./core.js";
+const MAX_QUEUE = 200;
+const MAX_BATCH = 50;
+const NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+const SENSITIVE = /password|secret|token|authorization|cookie|email|phone|credit|card|body|prompt|content/i;
+const text = (v, max = 256) => typeof v === "string" ? v.trim().slice(0, max) : "";
+const id = (v, length) => typeof v === "string" && new RegExp(`^[a-f0-9]{${length}}$`, "i").test(v) && !/^0+$/.test(v) ? v.toLowerCase() : "";
+/** Explicit product activity over the existing OTLP logs ingest path.
+ * Bounded, best-effort collection; never auto-captures UI text or form contents.
+ * The return value means queued, not delivered or verified business success. */
+export function createProductAnalytics(options) {
+    const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const endpoint = `${(options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "")}/v1/logs`;
+    const resource = { "service.name": options.service, ...releaseResourceAttributes(options),
+        ...(options.environment ? { "deployment.environment": text(options.environment) } : {}) };
+    const allowed = new Set((options.allowedProperties ?? []).filter(k => NAME.test(k) && !SENSITIVE.test(k)).slice(0, 20));
+    const kv = (key, value) => ({ key, value: typeof value === "boolean" ? { boolValue: value } : typeof value === "number" ? { doubleValue: value } : { stringValue: value } });
+    let queue = [];
+    let sequence = 0;
+    let stopped = false;
+    let inFlight;
+    let timer;
+    const tracker = (bound) => ({
+        track(event) {
+            if (stopped || queue.length >= MAX_QUEUE || !NAME.test(event.name))
+                return false;
+            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": 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.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")
+                    attrs[`heystack.properties.${key}`] = v.slice(0, 256);
+                else if (typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v)))
+                    attrs[`heystack.properties.${key}`] = v;
+            }
+            const traceId = ctx.traceId !== undefined ? id(ctx.traceId, 32) : (active && isSpanContextValid(active) ? active.traceId : "");
+            const spanId = ctx.traceId ? id(ctx.spanId, 16) : active && isSpanContextValid(active) ? active.spanId : "";
+            queue.push({ sequence: ++sequence, record: { timeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
+                    severityText: event.outcome === "failed" ? "ERROR" : "INFO", severityNumber: event.outcome === "failed" ? 17 : 9,
+                    body: { stringValue: event.name }, attributes: Object.entries(attrs).map(([k, v]) => kv(k, v)),
+                    ...(traceId ? { traceId, ...(spanId ? { spanId } : {}) } : {}) } });
+            return true;
+        },
+        feature(name, event = {}) { return this.track({ ...event, name: "feature.used", feature: name }); },
+        screen(name, event = {}) { return this.track({ ...event, name: "screen.viewed", surface: name }); },
+        withContext(next) { return tracker({ ...bound, ...next }); },
+    });
+    const flushThrough = (target) => {
+        // Every caller waits for its own sequence watermark, including events queued
+        // during an earlier export. New producers cannot extend this caller forever.
+        if (inFlight)
+            return inFlight.then(ok => ok ? flushThrough(target) : false);
+        const run = async () => {
+            while (queue.length && queue[0].sequence <= target) {
+                const size = Math.min(MAX_BATCH, queue.filter(item => item.sequence <= target).length);
+                const batch = queue.splice(0, size);
+                const records = batch.map(item => item.record);
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 5000);
+                try {
+                    const response = await context.with(suppressTracing(context.active()), () => send(endpoint, { method: "POST", signal: controller.signal,
+                        headers: { "content-type": "application/json", authorization: `Bearer ${options.apiKey}` },
+                        body: JSON.stringify({ resourceLogs: [{ resource: { attributes: Object.entries(resource).map(([k, v]) => kv(k, v)) },
+                                    scopeLogs: [{ scope: { name: "@heystack/otel/product", version: "1" }, logRecords: records }] }] }) }));
+                    if (!response.ok)
+                        throw new Error("export failed");
+                }
+                catch {
+                    queue = [...batch, ...queue].slice(0, MAX_QUEUE);
+                    return false;
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            return true;
+        };
+        inFlight = run().finally(() => { inFlight = undefined; });
+        return inFlight;
+    };
+    const flush = () => flushThrough(sequence);
+    if (typeof window !== "undefined" && options.flushIntervalMs !== undefined) {
+        timer = setInterval(() => { void flush(); }, Math.max(5000, Number.isFinite(options.flushIntervalMs) ? options.flushIntervalMs : 5000));
+    }
+    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/web.d.ts

@@ -85,6 +85,8 @@ export interface InstrumentWebOptions {
      * resource of exported browser logs for commit-level attribution.
      */
     build?: string;
+    /** Optional shared UUID for product events, browser errors and replay. Rotate on logout. */
+    sessionId?: string;
     /** Optional app-supplied user identifier stamped on the session. */
     userId?: string;
     /** Local overrides; by default sampling + masking come from server config. */
@@ -144,6 +146,8 @@ 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;
+/** 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.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export declare function instrumentWeb(opts: InstrumentWebOptions): Promise<() => void>;

package/dist/web.js

@@ -100,6 +100,14 @@ export function tracingActive(opts, cfg) {
 export function errorCaptureActive(opts, cfg) {
     return opts.errors !== false && cfg.errors_enabled !== false;
 }
+/** A caller-owned session UUID allows product activity to correlate with replay. */
+export function resolveWebSessionId(candidate) {
+    if (candidate === undefined)
+        return crypto.randomUUID();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(candidate))
+        throw new Error("sessionId must be a UUID");
+    return candidate;
+}
 /** 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) {
@@ -125,7 +133,7 @@ export async function instrumentWeb(opts) {
     // One session id for the whole run — shared by errors, console logs AND replay
     // (created here, before the replay sampling gate, so errors correlate even when
     // replay isn't sampled; when it is, they share this id → error ↔ replay linking).
-    const sessionId = crypto.randomUUID();
+    const sessionId = resolveWebSessionId(opts.sessionId);
     // service.version / service.build for release attribution on exported browser logs.
     const releaseAttrs = releaseResourceAttributes({ version: opts.version, build: opts.build });
     // 2. Browser distributed tracing (opt-in) — INDEPENDENT of replay sampling. Emits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,10 @@
     "./web": {
       "types": "./dist/web.d.ts",
       "import": "./dist/web.js"
+    },
+    "./product": {
+      "types": "./dist/product.d.ts",
+      "import": "./dist/product.js"
     }
   },
   "files": [