@edraj/sauron-browser 1.5.0 → 1.7.0

package/README.md

@@ -199,12 +199,17 @@ offline queue. Returns the live `SauronClient`.
 
 Idempotent: a second `init()` tears the previous client down first (restoring
 every patched global, clearing the current screen) before installing a fresh
-one. Throws `Error` when `dsn` is missing or not a string, and `DsnError` when
-the DSN itself is malformed.
+one. Throws `Error` when `dsn` is missing or not a string, when `release` is
+missing or blank, and `DsnError` when the DSN itself is malformed.
+
+`release` is required as of v1.7.0 — `init()` throws without one.
 
 ```ts
-const client = Sauron.init({ dsn: 'https://pk_test@localhost:8081/1' });
-client.options.release;     // null
+const client = Sauron.init({
+  dsn: 'https://pk_test@localhost:8081/1',
+  release: 'web@1.4.2',
+});
+client.options.release;     // 'web@1.4.2'
 client.dsn.projectId;       // '1'
 ```
 
@@ -985,7 +990,7 @@ const appFrames = frames.filter((f) => isInAppFrame(f.filename));
 
 ```ts
 const SDK_NAME: string  // 'sauron.javascript'
-const SDK_VERSION: string // '1.5.0'
+const SDK_VERSION: string // '1.7.0'
 ```
 
 The SDK identity embedded in `header.sdk` of every envelope.
@@ -1027,7 +1032,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. |
@@ -1040,6 +1045,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
@@ -1096,7 +1111,7 @@ Other scope data:
   is unavailable.
 
 ```ts
-Sauron.init({ dsn, tags: { tier: 'free' }, extra: { build: 'ci-42' } });
+Sauron.init({ dsn, release: 'web@1.4.2', tags: { tier: 'free' }, extra: { build: 'ci-42' } });
 Sauron.setTag('tier', 'pro');                       // scope beats init default
 Sauron.track('upgraded', {}, { tags: { tier: 'trial' } });
 // -> event tags: { tier: 'trial' }, extra: { build: 'ci-42' }
@@ -1116,8 +1131,8 @@ Sauron.track('upgraded', {}, { tags: { tier: 'trial' } });
 
 ```html
 <script type="module">
-  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.5.0';
-  Sauron.init({ dsn: 'https://pk_test@ingest.example.com/42' });
+  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.7.0';
+  Sauron.init({ dsn: 'https://pk_test@ingest.example.com/42', release: 'web@1.4.2' });
 </script>
 ```
 
@@ -1228,7 +1243,8 @@ npm run dev          # tsup --watch
 
 ## License
 
-AGPL-3.0-only — GNU Affero General Public License v3.0.
+LGPL-3.0-only — GNU Lesser General Public License v3.0. LGPLv3 applies on top of
+the GNU GPL v3, whose text ships alongside it in `COPYING`.
 
 Repo: <https://github.com/edraj/sauron> — wiki:
 <https://github.com/edraj/sauron/wiki>

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.5.0";
+var SDK_VERSION = "1.7.0";
 function getGlobal() {
   return globalThis;
 }
@@ -843,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);
@@ -859,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;
     });
@@ -875,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", () => {
@@ -2174,10 +2175,13 @@ function resolveOptions(options) {
   if (!options || typeof options.dsn !== "string" || options.dsn.length === 0) {
     throw new Error("[sauron] init() requires a `dsn`");
   }
+  if (typeof options.release !== "string" || options.release.trim().length === 0) {
+    throw new Error("[sauron] init() requires a `release` (the app version this build reports as)");
+  }
   const t = options.transport ?? {};
   return {
     dsn: options.dsn,
-    release: options.release ?? null,
+    release: options.release.trim(),
     sampleRate: clamp(options.sampleRate ?? 1, 0, 1),
     maxBreadcrumbs: options.maxBreadcrumbs ?? 50,
     tags: options.tags ?? {},
@@ -2226,13 +2230,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 }
   });
 }