@heystack/otel 0.17.0 → 0.18.0

package/README.md

@@ -693,3 +693,23 @@ 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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",