@edraj/sauron-browser 1.4.1 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes to `@edraj/sauron-browser` are documented here.
 
+## 1.6.0
+
+### Added
+
+- **Navigation direction on history breadcrumbs.** SPA navigation breadcrumbs
+  now carry `operation` alongside `from` and `to`: `push` for
+  `history.pushState`, `replace` for `history.replaceState`, and `pop` for
+  `popstate`. A breadcrumb trail no longer reads the same whether the user
+  advanced through a flow or backed out of it.
+
+  The vocabulary is shared with the Flutter SDK's `SauronNavigatorObserver`
+  (`push` / `pop` / `replace` / `remove`), so a trail reads the same whichever
+  SDK sent it. `remove` has no web equivalent and is never emitted here.
+
+  **A forward navigation is recorded as `pop`.** `history.forward()` fires the
+  same `popstate` event as `history.back()` and carries nothing to separate
+  them, so `pop` means "moved through history" rather than specifically "went
+  back". Telling them apart would mean writing a counter into `history.state`,
+  which the host app's router also owns — not a trade this SDK makes to
+  improve a breadcrumb.
+
+  No API change: `operation` is added to `data` on breadcrumbs the SDK already
+  emitted, and the same-path guard still suppresses a `replaceState` to the
+  current URL before any direction is recorded.
+
+## 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

package/README.md

@@ -358,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');
@@ -376,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
@@ -858,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.6.0'
 ```
 
 The SDK identity embedded in `header.sdk` of every envelope.
@@ -900,7 +1027,7 @@ On by default:
 | `window.onunhandledrejection` | Error item from `event.reason`, mechanism `{ type: 'onunhandledrejection', handled: false }`, level `error`. |
 | `console.log/info/warn/error/debug` | Breadcrumb, category `console`, level mapped (`warn`→`warning`, `error`→`error`, `debug`→`debug`, else `info`), message = arguments joined and truncated to 512 chars, `data: { arguments: n }`. Output is untouched. |
 | `document` click listener (capture, passive) | Breadcrumb, category `ui.click`, message = a `tag#id.class` selector (up to 3 classes). Element text and attribute values are never serialized. |
-| `history.pushState` / `replaceState` / `popstate` | Breadcrumb, type `navigation`, category `history`, `data: { from, to }` as paths. Same-path transitions are skipped. |
+| `history.pushState` / `replaceState` / `popstate` | Breadcrumb, type `navigation`, category `history`, `data: { from, to, operation }` — paths plus the direction: `push`, `replace` or `pop`. Same-path transitions are skipped. |
 | `fetch` | Breadcrumb, category `fetch`, message `METHOD url`, `data: { method, url, status_code }`, level `warning` for status >= 400. |
 | `XMLHttpRequest.prototype.open` / `send` | Breadcrumb, category `xhr`, same shape as `fetch`. |
 | `document` `visibilitychange` + window `pagehide` | Beacon flush of the pending batch on unload. |
@@ -913,6 +1040,16 @@ Opt-in:
 | `performance: true` | A `navigation` transaction for the initial page load (Navigation Timing, captured on `load`), an `http` transaction per instrumented `fetch` (`name` = `METHOD /path`, `status` `ok`/`error`), and a `navigation` transaction per SPA route change measured over one animation frame. No-op when `document` is undefined. |
 | `screenTracking: true` | Sets the screen to the new path on each SPA History navigation, which emits a `$screen` event on change. |
 
+`operation` uses the same vocabulary as the Flutter SDK's
+`SauronNavigatorObserver` (`push` / `pop` / `replace` / `remove`), so a trail
+reads the same whichever SDK sent it. `remove` has no web equivalent and is
+never emitted here. One limit worth knowing: **a forward navigation is recorded
+as `pop`.** `history.forward()` fires the same `popstate` event as
+`history.back()` and carries nothing to separate them, so `pop` means "moved
+through history", not specifically "went back". Distinguishing them would mean
+writing to `history.state`, which the host app's router also owns — not a
+trade the SDK makes.
+
 Two guards keep the SDK from observing itself: a reentrancy flag held while SDK
 code runs, and a denylist on the DSN host. Requests the transport makes are
 therefore never turned into breadcrumbs or transactions. Wrappers are tagged, so
@@ -989,7 +1126,7 @@ Sauron.track('upgraded', {}, { tags: { tier: 'trial' } });
 
 ```html
 <script type="module">
-  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.4.1';
+  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.6.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.1";
+var SDK_VERSION = "1.6.0";
 function getGlobal() {
   return globalThis;
 }
@@ -87,6 +87,32 @@ 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";
@@ -817,12 +843,12 @@ function installHistory() {
   const loc = g2.location;
   if (!hist) return;
   let lastPath = toPath(loc?.href ?? null, loc?.href);
-  const emit = (toHref) => {
+  const emit = (toHref, operation) => {
     const to = toPath(toHref, loc?.href);
     const from = lastPath;
     lastPath = to;
     if (from === to) return;
-    withInternal(() => addNavigationBreadcrumb(from, to));
+    withInternal(() => addNavigationBreadcrumb(from, to, operation));
     if (to && navHandler) {
       try {
         navHandler(to);
@@ -833,11 +859,12 @@ function installHistory() {
   const wrap = (name) => {
     const original = hist[name];
     if (typeof original !== "function" || isWrapped(original)) return;
+    const operation = name === "pushState" ? "push" : "replace";
     hist[name] = markWrapped(function sauronHistory(...args) {
       const result = original.apply(this, args);
       if (!isInternal()) {
         const urlArg = args[2];
-        emit(urlArg != null ? String(urlArg) : loc?.href ?? null);
+        emit(urlArg != null ? String(urlArg) : loc?.href ?? null, operation);
       }
       return result;
     });
@@ -849,7 +876,7 @@ function installHistory() {
   wrap("replaceState");
   if (typeof g2.addEventListener === "function") {
     const onPopState = () => {
-      if (!isInternal()) emit(loc?.href ?? null);
+      if (!isInternal()) emit(loc?.href ?? null, "pop");
     };
     g2.addEventListener("popstate", onPopState);
     registerPatch("popstate", () => {
@@ -1026,7 +1053,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),
@@ -1039,6 +1066,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();
@@ -2195,13 +2227,13 @@ function addBreadcrumb(input, hint) {
   if (!client) return;
   client.addBreadcrumb(normalizeBreadcrumb(input), hint);
 }
-function addNavigationBreadcrumb(from, to) {
+function addNavigationBreadcrumb(from, to, operation = "push") {
   addBreadcrumb({
     type: "navigation",
     category: "history",
     level: "info",
     message: null,
-    data: { from, to }
+    data: { from, to, operation }
   });
 }
 
@@ -2302,6 +2334,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;
@@ -2309,6 +2342,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;