@edraj/sauron-browser 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to `@edraj/sauron-browser` are documented here.
 
+## 1.5.0
+
+### Added
+
+- **`tags` and `extra` on transactions.** `trackTransaction` now accepts two
+  developer-supplied maps: `tags` (flat string→string, indexed) and `extra`
+  (freeform JSON). `extra` is where a request body, a response body, an order
+  id or a retry count goes — the span that times an HTTP call can now carry
+  what the call actually sent and received.
+
+  Both are visible on the new **Transactions** page and in the session
+  timeline, and both are searchable: `@tag.tier:premium`,
+  `extra.order_id:9001`, or `extra.response:~9001` to match a substring
+  *inside* a stored response body.
+
+  **They are per-call only.** Unlike `captureException` and `track`, a
+  transaction does not inherit the scope — `setTag()` / `setExtra()` defaults
+  are not merged in. Transactions are the highest-volume signal an app emits,
+  one per navigation and per request, so inheriting a global blob would write
+  it onto every row. This asymmetry is deliberate and is documented on the
+  method.
+
+  `extra` is serialized and capped at **16 KB**. Past that the whole map is
+  replaced with a `{"_truncated": true, "_bytes": N}` marker, and the
+  dashboard says so on the row rather than showing a short object that looks
+  complete. The cap is not cosmetic: envelopes are batched, and one oversized
+  body would push the whole envelope past the ingest limit and take every
+  unrelated span sent with it — a silent loss of data nobody asked about.
+  Size is measured in UTF-8 bytes, so non-ASCII payloads are counted at what
+  they actually cost on the wire.
+
+  Nothing in `extra` is scrubbed. `beforeSend` remains the redaction seam;
+  think twice before attaching a body that can carry tokens or personal data.
+
+  An app that sets neither field serializes byte-identically to before: both
+  keys are omitted when empty, never sent as `null`.
+
+  Signature: `trackTransaction({ …, tags?: Record<string, string>, extra?: Record<string, unknown> })`. `MAX_TRANSACTION_EXTRA_BYTES` and `capTransactionExtra` are now exported from the package entrypoint, so a caller can size a payload before attaching it.
+
+## 1.4.1
+
+### Added
+
+- **Auto-reset on identity switch.** `identify()` now detects a login by a
+  DIFFERENT user than last time on the same device — the common case of a
+  forgotten `reset()` on logout — and mints a fresh anonymous id (and rotates
+  the session id) before sending, so `anonymous_id` is `null` instead of an
+  alias to the previous person. This can't undo an alias already sent under
+  the old id — still call `reset()` on logout — but it bounds a missed
+  `reset()` to one corrupted guest window instead of every one after it. To
+  detect the switch, `identify()` persists a short one-way digest (never the
+  id itself; see `hashIdentity`) of the last identified user in `localStorage`
+  under `sauron.last_identified`. Like the anonymous id, this is a durable
+  first-party value stored on the user's terminal — a retention and consent
+  consequence, not just an implementation detail.
+
+  The stored value carries a format tag: `v1:<digest>`, byte-identical to what
+  the Flutter SDK writes under the same key. A value with no tag or an
+  unrecognised one reads as "nobody has identified on this device yet" and is
+  rewritten in the current format on the next `identify()`. That matters
+  because the digest's shape is not frozen — if it ever widens again, an
+  untagged store could not tell "a digest I no longer produce" from "a
+  different person", so every returning user's next `identify()` would be read
+  as a switch and would rotate their anonymous id and session, once, silently.
+  The tag turns that into one missed switch per device instead.
+
+### Changed
+
+- `reset()` now also rotates the session id (`sauron.session_id`). The
+  server's `bump_session` is last-write-wins on `distinct_id`, so without
+  this a single `sessions` row could otherwise end up serially representing
+  two different people and recording only whichever wrote last.
+
 ## 1.4.0
 
 ### Fixed

package/README.md

@@ -117,6 +117,42 @@ Sauron.init({
 });
 ```
 
+## Funnels
+
+Funnels track the conversion rate of users progressing through a defined sequence of steps. By tracking a unique event at each step, the Sauron dashboard can visualize where users drop off.
+
+```ts
+// 1. User arrives at the pricing page
+Sauron.track('pricing_viewed');
+
+// 2. User clicks on a plan
+Sauron.track('plan_selected', { plan: 'pro' });
+
+// 3. User successfully checks out
+Sauron.track('checkout_completed', { plan: 'pro', value: 42.5 });
+```
+
+## User Journeys
+
+User journeys track the broader path a user takes through your application. Combine `setScreen` (to track navigation) and `startWorkflow` (to group a multi-step process) to see exactly how a user reached an outcome or encountered an error.
+
+```ts
+// Update the screen when the user navigates
+Sauron.setScreen('/onboarding/step1');
+
+// Start a workflow to group all subsequent events and errors
+Sauron.startWorkflow('user_onboarding');
+
+// Track specific actions within the journey
+Sauron.track('profile_photo_uploaded');
+
+Sauron.setScreen('/onboarding/step2');
+Sauron.track('preferences_saved');
+
+// End the workflow when the journey concludes
+Sauron.endWorkflow();
+```
+
 ## API reference
 
 Everything is exported both as a named function and as a member of the `Sauron`
@@ -322,10 +358,28 @@ function trackTransaction(input: TransactionInput): void
 | `httpMethod` | `string \| null` | `null` | For `http` ops. |
 | `httpStatus` | `number \| null` | `null` | For `http` ops. |
 | `url` | `string \| null` | `null` | For `http` ops. |
+| `tags` | `Record<string, string>` | omitted | Indexed string→string labels. Filter with `@tag.key:value` on the Transactions page. |
+| `extra` | `Record<string, unknown>` | omitted | Freeform JSON — request body, response body, SQL text, row counts. Searchable with `extra.key:value`. |
 
 The item is stamped with the current distinct id, session id and timestamp.
 Never sampled. Returns `void`.
 
+**`tags` and `extra` are per-call only.** Unlike `track()` and
+`captureException()`, a transaction does **not** inherit the scope:
+`setTag()` / `setExtra()` defaults are not merged in. Transactions are the
+highest-volume signal a page emits — one per navigation and per fetch — so
+inheriting a global blob would write it onto every row.
+
+`extra` is serialized and capped at **16 KB** (`MAX_TRANSACTION_EXTRA_BYTES`).
+Past that the whole map is replaced with `{ _truncated: true, _bytes: N }` and
+the dashboard says so on the row. The cap is not cosmetic: envelopes are
+batched, and one oversized body would push the whole envelope past the ingest
+limit and drop every unrelated span sent with it. Size is measured in **UTF-8
+bytes**, so a body of non-ASCII text counts what it will actually cost.
+
+Nothing in `extra` is scrubbed. Use `beforeSend` for redaction, and think twice
+before attaching a body that can carry tokens or personal data.
+
 ```ts
 const started = performance.now();
 const res = await fetch('/api/orders');
@@ -340,6 +394,115 @@ Sauron.trackTransaction({
 });
 ```
 
+#### Example: a `fetch` wrapper that records both bodies
+
+Drop-in replacement for `fetch` on the calls you care about. Note the
+`res.clone()` — reading the body consumes the stream, so the caller would get an
+empty response otherwise.
+
+```ts
+import * as Sauron from '@edraj/sauron-browser';
+
+export async function tracedFetch(
+  input: string,
+  init: RequestInit = {},
+): Promise<Response> {
+  const method = (init.method ?? 'GET').toUpperCase();
+  const path = new URL(input, location.origin).pathname;
+  const started = performance.now();
+
+  try {
+    const res = await fetch(input, init);
+    // Clone BEFORE reading: a Response body is a one-shot stream, and
+    // consuming it here would hand the caller an empty one.
+    const responseBody = await res.clone().text();
+
+    Sauron.trackTransaction({
+      name: `${method} ${path}`,          // grouping key — keep it low cardinality
+      op: 'http',
+      durationMs: performance.now() - started,
+      httpMethod: method,
+      httpStatus: res.status,
+      url: input,
+      status: res.ok ? 'ok' : 'error',
+      tags: { api: path.split('/')[2] ?? 'root' },
+      extra: {
+        request: typeof init.body === 'string' ? init.body : undefined,
+        response: responseBody,
+        response_bytes: responseBody.length,
+      },
+    });
+    return res;
+  } catch (err) {
+    Sauron.trackTransaction({
+      name: `${method} ${path}`,
+      op: 'http',
+      durationMs: performance.now() - started,
+      httpMethod: method,
+      url: input,
+      status: 'error',
+      extra: { request: init.body, error: String(err) },
+    });
+    throw err;
+  }
+}
+```
+
+On the dashboard: **Transactions → the row → expand**. Both bodies render as a
+JSON tree, and every one of these finds it:
+
+```text
+extra.response:~9001        # substring, inside the stored response body
+@tag.api:orders             # indexed tag
+op:http http.status:>=500   # the failures
+duration:>2s                # the slow ones
+```
+
+#### Example: a client-side SQL query (`sql.js` / `wa-sqlite`)
+
+If your app runs SQLite in the browser, spans work the same way. Put the
+**statement** in `extra` and keep `name` a stable label — a query with literals
+baked in would mint a new dashboard row per execution.
+
+```ts
+function tracedQuery(db: Database, sql: string, params: unknown[] = []) {
+  const started = performance.now();
+  try {
+    const rows = db.exec(sql, params);
+    Sauron.trackTransaction({
+      // The LABEL, not the statement. `op` accepts only
+      // navigation|http|resource|screen_load|custom — anything else, `'db'`
+      // included, is coerced to 'custom', so pass 'custom' and say it with a tag.
+      name: 'SELECT orders',
+      op: 'custom',
+      durationMs: performance.now() - started,
+      status: 'ok',
+      tags: { db: 'sqlite', table: 'orders' },
+      extra: {
+        statement: sql,
+        row_count: rows[0]?.values.length ?? 0,
+        // Bind PARAMETERS are user data. Log them only if you have decided
+        // that is acceptable, or log their shape instead.
+        params,
+      },
+    });
+    return rows;
+  } catch (err) {
+    Sauron.trackTransaction({
+      name: 'SELECT orders',
+      op: 'custom',
+      durationMs: performance.now() - started,
+      status: 'error',
+      tags: { db: 'sqlite', table: 'orders' },
+      extra: { statement: sql, error: String(err) },
+    });
+    throw err;
+  }
+}
+```
+
+Then `@tag.table:orders duration:>500ms` is your slow-query list.
+
 ### `setScreen(name)`
 
 ```ts
@@ -822,7 +985,7 @@ const appFrames = frames.filter((f) => isInAppFrame(f.filename));
 
 ```ts
 const SDK_NAME: string  // 'sauron.javascript'
-const SDK_VERSION: string // '1.4.0'
+const SDK_VERSION: string // '1.5.0'
 ```
 
 The SDK identity embedded in `header.sdk` of every envelope.
@@ -922,8 +1085,15 @@ Other scope data:
   `captureException`.
 - **identity** — `device_id` persists in `localStorage` under
   `sauron.device_id`; `session_id` persists in `sessionStorage` under
-  `sauron.session_id`. Both fall back to a per-process in-memory id when Web
-  Storage is unavailable.
+  `sauron.session_id`; `identify()` additionally persists a short one-way
+  digest (never the id itself) of the last identified user in `localStorage`
+  under `sauron.last_identified`, used to detect a login by a different
+  person on a device where `reset()` was never wired — see "Reset on logout"
+  in the wiki. This is not a security boundary (an unkeyed hash over a
+  possibly low-entropy id, e.g. an email, is a confirmation oracle, not a
+  secret) — it exists only so the key isn't a second plaintext copy of the
+  app's user id. All fall back to a per-process in-memory id when Web Storage
+  is unavailable.
 
 ```ts
 Sauron.init({ dsn, tags: { tier: 'free' }, extra: { build: 'ci-42' } });
@@ -946,7 +1116,7 @@ Sauron.track('upgraded', {}, { tags: { tier: 'trial' } });
 
 ```html
 <script type="module">
-  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.4.0';
+  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.5.0';
   Sauron.init({ dsn: 'https://pk_test@ingest.example.com/42' });
 </script>
 ```

package/dist/index.cjs

@@ -8,7 +8,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 
 // src/utils.ts
 var SDK_NAME = "sauron.javascript";
-var SDK_VERSION = "1.4.0";
+var SDK_VERSION = "1.5.0";
 function getGlobal() {
   return globalThis;
 }
@@ -87,11 +87,60 @@ function makeLogger(debug) {
     warn: (...args) => console.warn("[sauron]", ...args)
   };
 }
+var MAX_TRANSACTION_EXTRA_BYTES = 16 * 1024;
+function capTransactionExtra(extra, maxBytes = MAX_TRANSACTION_EXTRA_BYTES) {
+  let bytes;
+  try {
+    const json = JSON.stringify(extra);
+    if (json === void 0) return { _truncated: true, _bytes: -1 };
+    bytes = utf8Length(json);
+  } catch {
+    return { _truncated: true, _bytes: -1 };
+  }
+  if (bytes <= maxBytes) return extra;
+  return { _truncated: true, _bytes: bytes };
+}
+function utf8Length(s) {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 128) n += 1;
+    else if (c < 2048) n += 2;
+    else if (c >= 55296 && c <= 56319) {
+      n += 4;
+      i++;
+    } else n += 3;
+  }
+  return n;
+}
 
 // src/identity.ts
 var DEVICE_ID_KEY = "sauron.device_id";
 var SESSION_ID_KEY = "sauron.session_id";
 var ANON_ID_KEY = "sauron.anon_id";
+var LAST_IDENTIFIED_KEY = "sauron.last_identified";
+var LAST_IDENTIFIED_FORMAT = "v1";
+function encodeLastIdentified(digest) {
+  return `${LAST_IDENTIFIED_FORMAT}:${digest}`;
+}
+function decodeLastIdentified(raw) {
+  if (raw === null) return null;
+  const sep = raw.indexOf(":");
+  if (sep < 0 || raw.slice(0, sep) !== LAST_IDENTIFIED_FORMAT) return null;
+  const digest = raw.slice(sep + 1);
+  return digest === "" ? null : digest;
+}
+function fnv1a32(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function hashIdentity(id) {
+  return fnv1a32(id) + fnv1a32("
" + id);
+}
 function webStorage(name) {
   try {
     const s = globalThis[name];
@@ -125,6 +174,7 @@ function persistentId(cached, storage, key) {
 var deviceId = null;
 var sessionId = null;
 var anonymousId = null;
+var lastIdentified = null;
 function getDeviceId() {
   deviceId = persistentId(deviceId, webStorage("localStorage"), DEVICE_ID_KEY);
   return deviceId;
@@ -133,6 +183,17 @@ function getSessionId() {
   sessionId = persistentId(sessionId, webStorage("sessionStorage"), SESSION_ID_KEY);
   return sessionId;
 }
+function rotateSessionId() {
+  sessionId = null;
+  const storage = webStorage("sessionStorage");
+  if (storage) {
+    try {
+      storage.removeItem(SESSION_ID_KEY);
+    } catch {
+    }
+  }
+  return getSessionId();
+}
 function getAnonymousId() {
   if (anonymousId) return anonymousId;
   const storage = webStorage("localStorage");
@@ -167,6 +228,37 @@ function resetAnonymousId() {
   }
   return getAnonymousId();
 }
+function getLastIdentified() {
+  const storage = webStorage("localStorage");
+  if (!storage) return decodeLastIdentified(lastIdentified);
+  try {
+    const stored = storage.getItem(LAST_IDENTIFIED_KEY);
+    return decodeLastIdentified(stored ?? lastIdentified);
+  } catch {
+    return decodeLastIdentified(lastIdentified);
+  }
+}
+function setLastIdentified(id) {
+  const encoded = encodeLastIdentified(id);
+  lastIdentified = encoded;
+  const storage = webStorage("localStorage");
+  if (storage) {
+    try {
+      storage.setItem(LAST_IDENTIFIED_KEY, encoded);
+    } catch {
+    }
+  }
+}
+function clearLastIdentified() {
+  lastIdentified = null;
+  const storage = webStorage("localStorage");
+  if (storage) {
+    try {
+      storage.removeItem(LAST_IDENTIFIED_KEY);
+    } catch {
+    }
+  }
+}
 
 // src/context.ts
 function getNavigator() {
@@ -813,13 +905,31 @@ var Scope = class {
     this.maxBreadcrumbs = Math.max(0, max);
     this.trim();
   }
+  /**
+   * Replace the scope user.
+   *
+   * `id` is coerced with `String()` for the same reason `SauronClient.
+   * prepareIdentify` coerces its own — a plain-JS caller can (and does) pass
+   * `setUser({ id: user.id })` where `user.id` is a number, and TypeScript
+   * cannot stop them. This path is the one that BYPASSES `identify()`'s
+   * coercion entirely, and the consequence is not cosmetic: the scope user
+   * lands in the envelope context, where the server's `distinct_id` is a
+   * non-`Option` Rust `String`. A JSON number there fails deserialization of
+   * the ENVELOPE, not of the one field — so the whole batch 400s, and a 400
+   * is non-retryable, so every event in it is dropped for good.
+   *
+   * Rebuilding the whole object (rather than merging into the existing one)
+   * is deliberate and is the behaviour the Flutter SDK was fixed to match:
+   * `email` and `traits` come from the input alone, so setting a new user
+   * never inherits the previous person's contact details.
+   */
   setUser(user) {
     if (user === null) {
       this.user = null;
       return;
     }
     this.user = {
-      id: user.id ?? null,
+      id: user.id === null || user.id === void 0 ? null : String(user.id),
       email: user.email ?? null,
       traits: user.traits ?? {}
     };
@@ -920,11 +1030,12 @@ function setScreen(name) {
 function identify(id, traits = {}) {
   const client = getClient();
   if (!client) return;
-  const anonymousId2 = client.getAnonymousId();
-  client.getScope().setUser({ id, traits });
+  const distinctId = String(id);
+  const anonymousId2 = client.prepareIdentify(distinctId);
+  client.getScope().setUser({ id: distinctId, traits });
   const item = {
     type: "identify",
-    distinct_id: id,
+    distinct_id: distinctId,
     anonymous_id: anonymousId2,
     traits: traits ?? {}
   };
@@ -941,7 +1052,7 @@ function normalizeOp(op) {
   return op && TRANSACTION_OPS.includes(op) ? op : "custom";
 }
 function buildTransactionItem(input, distinctId, sessionId2) {
-  return {
+  const item = {
     type: "transaction",
     name: input.name,
     op: normalizeOp(input.op),
@@ -954,6 +1065,11 @@ function buildTransactionItem(input, distinctId, sessionId2) {
     session_id: sessionId2,
     timestamp: nowIso()
   };
+  if (input.tags && Object.keys(input.tags).length > 0) item.tags = { ...input.tags };
+  if (input.extra && Object.keys(input.extra).length > 0) {
+    item.extra = capTransactionExtra({ ...input.extra });
+  }
+  return item;
 }
 function trackTransaction(input) {
   const client = getClient();
@@ -1854,18 +1970,56 @@ var SauronClient = class {
     return this.anonUsed ? getAnonymousId() : null;
   }
   /**
-   * Forget the current person: clear the scope user and mint a fresh anonymous
-   * id.
+   * Forget the current person: clear the scope user, mint a fresh anonymous
+   * id, forget the last identified user, and rotate the session id.
    *
    * MUST BE CALLED ON LOGOUT. Without it, the next anonymous visitor on this
    * browser reuses the persisted anon id, and a later identify() aliases their
-   * activity to the previous account server-side, permanently.
+   * activity to the previous account server-side, permanently. Rotating the
+   * session id matters too: the server's `bump_session` is last-write-wins on
+   * `distinct_id`, so without rotation one `sessions` row could otherwise
+   * serially represent two different people and record only whichever wrote
+   * last.
    */
   reset() {
     this.scope.setUser(null);
     resetAnonymousId();
+    clearLastIdentified();
+    rotateSessionId();
     this.anonUsed = false;
   }
+  /**
+   * Prepare for an `identify()`; returns the `anonymous_id` to send.
+   *
+   * When a DIFFERENT user identifies than last time, the current anon id
+   * belongs to the previous person and is already burned server-side, so it is
+   * replaced before anything else happens and `null` is sent instead of a
+   * cross-user alias. This cannot repair events already sent under the burned
+   * alias — nothing can — but it bounds a forgotten `reset()` to one guest
+   * window instead of every future one.
+   *
+   * `id` is coerced with `String()` before comparing/persisting: a plain-JS
+   * caller can pass a number (`Sauron.identify(user.id)`), and `Storage`
+   * itself applies `ToString` on write — so comparing an un-coerced `id`
+   * against a value that already round-tripped through storage would treat
+   * the SAME numeric user as a switch on every single call. The comparison
+   * against `last` is an explicit `!== null` (not a truthiness check) so an
+   * app that (unusually) identifies with `''` still has a later, different id
+   * correctly detected as a real switch — a falsy string is not "no identity
+   * yet". `last`/the persisted value are digests, not the raw id — see
+   * `hashIdentity`.
+   */
+  prepareIdentify(id) {
+    const digest = hashIdentity(String(id));
+    const last = getLastIdentified();
+    if (last !== null && last !== digest) {
+      resetAnonymousId();
+      rotateSessionId();
+      this.anonUsed = false;
+    }
+    setLastIdentified(digest);
+    return this.getAnonymousId();
+  }
   /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
   makeEnvelope(items) {
     const header = {
@@ -2179,6 +2333,7 @@ var Sauron = {
 var index_default = Sauron;
 
 exports.DsnError = DsnError;
+exports.MAX_TRANSACTION_EXTRA_BYTES = MAX_TRANSACTION_EXTRA_BYTES;
 exports.SDK_NAME = SDK_NAME;
 exports.SDK_VERSION = SDK_VERSION;
 exports.Sauron = Sauron;
@@ -2186,6 +2341,7 @@ exports.SauronClient = SauronClient;
 exports.addBreadcrumb = addBreadcrumb2;
 exports.buildEnvelope = buildEnvelope;
 exports.cancelWorkflow = cancelWorkflow2;
+exports.capTransactionExtra = capTransactionExtra;
 exports.captureException = captureException2;
 exports.captureMessage = captureMessage2;
 exports.close = close;