@edraj/sauron-browser 1.4.1 → 1.6.0

package/dist/index.d.cts

@@ -144,6 +144,19 @@ interface TransactionItem {
     workflow_id?: string;
     workflow_name?: string;
     timestamp: string;
+    /**
+     * Developer-supplied flat string tags for THIS transaction.
+     *
+     * Unlike {@link EventItem} and the error item, this is NOT merged with the
+     * scope — see {@link TransactionInput.tags}. Omitted entirely when empty.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Developer-supplied freeform JSON for THIS transaction — the request body,
+     * the response body, a retry count. Capped and replaced with a truncation
+     * marker past {@link MAX_TRANSACTION_EXTRA_BYTES}. Omitted when empty.
+     */
+    extra?: Record<string, unknown>;
 }
 /** An identity association (PostHog-style `identify`). */
 interface IdentifyItem {
@@ -330,6 +343,29 @@ interface TransactionInput {
     httpMethod?: string | null;
     httpStatus?: number | null;
     url?: string | null;
+    /**
+     * Flat string tags for this transaction.
+     *
+     * **Per-call only — the scope is NOT merged in**, which is the one place
+     * transactions differ from `track()` and `captureException()`. Those two
+     * merge `setTag`/`setExtra` defaults; a transaction carries only what its own
+     * call site attached. Transactions are the highest-volume signal (one per
+     * navigation and per HTTP call), so inheriting a global blob would write it
+     * onto every row.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Freeform JSON for this transaction — the request body, the response body,
+     * an order id, a retry count.
+     *
+     * Per-call only, for the reason on {@link TransactionInput.tags}. Serialized
+     * and capped at {@link MAX_TRANSACTION_EXTRA_BYTES}; past that the whole map
+     * is replaced with `{ _truncated: true, _bytes: N }` so one large body cannot
+     * take a batched envelope over the ingest limit and drop every span in it.
+     *
+     * Nothing here is scrubbed. `beforeSend` is the redaction seam.
+     */
+    extra?: Record<string, unknown>;
 }
 
 /**
@@ -561,7 +597,34 @@ declare function parseError(err: unknown): Frame[];
 /** Small dependency-free helpers shared across the SDK. */
 /** SDK identity, embedded in every envelope header. */
 declare const SDK_NAME = "sauron.javascript";
-declare const SDK_VERSION = "1.4.1";
+declare const SDK_VERSION = "1.6.0";
+/**
+ * Largest serialized `extra` a single transaction may carry, in bytes.
+ *
+ * Transactions are the highest-volume signal and they ship in BATCHED
+ * envelopes, so one oversized payload does not fail alone — ingest rejects the
+ * whole envelope past `INGEST_MAX_BODY_BYTES` (1 MiB by default) and every
+ * unrelated span batched with it is lost. Since the motivating use of
+ * transaction `extra` is request and response bodies, that is not a remote
+ * hazard.
+ */
+declare const MAX_TRANSACTION_EXTRA_BYTES: number;
+/**
+ * Cap a transaction's `extra`, substituting a marker when it is too large.
+ *
+ * Replaces the WHOLE map rather than trimming keys: a half-written JSON value
+ * is worse than an honest marker, and per-key trimming would make the result
+ * depend on key iteration order, which differs across the five SDKs. The
+ * marker is deliberately readable on the dashboard — `_truncated` says data
+ * was dropped rather than silently serving a short object that looks complete.
+ *
+ * Returns the input unchanged when it fits. A value that cannot be serialized
+ * at all (a cycle, a BigInt) is replaced by the same marker with `_bytes: -1`,
+ * because the alternative is throwing from inside `trackTransaction` — and an
+ * SDK that crashes the app it is measuring is worse than one that drops a
+ * payload.
+ */
+declare function capTransactionExtra(extra: Record<string, unknown>, maxBytes?: number): Record<string, unknown>;
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -673,4 +736,4 @@ declare const Sauron: {
     getClient: typeof getClient;
 };
 
-export { type ActiveWorkflow, type AppContext, type BeforeBreadcrumb, type BeforeSend, type Breadcrumb, type BreadcrumbBatchItem, type BreadcrumbInput, type CaptureOptions, type Context, type DeviceContext, type Dsn, DsnError, type Envelope, type EnvelopeHeader, type EnvelopeItem, type ErrorItem, type EventItem, type ExceptionValue, type Frame, type Hint, type IdentifyItem, type InitOptions, type ItemType, type Level, type Mechanism, type OsContext, type ResolvedOptions, type RuntimeContext, SDK_NAME, SDK_VERSION, Sauron, SauronClient, type SdkInfo, type TrackOptions, type TransactionInput, type TransactionItem, type TransactionOp, type TransportOptions, type UserContext, type UserInput, type WorkflowResult, type WorkflowStatus, addBreadcrumb, buildEnvelope, cancelWorkflow, captureException, captureMessage, close, Sauron as default, endWorkflow, flush, getClient, getScreen, getWorkflow, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, reset, setContext, setExtra, setScreen, setTag, setTags, setUser, startWorkflow, track, trackTransaction };
+export { type ActiveWorkflow, type AppContext, type BeforeBreadcrumb, type BeforeSend, type Breadcrumb, type BreadcrumbBatchItem, type BreadcrumbInput, type CaptureOptions, type Context, type DeviceContext, type Dsn, DsnError, type Envelope, type EnvelopeHeader, type EnvelopeItem, type ErrorItem, type EventItem, type ExceptionValue, type Frame, type Hint, type IdentifyItem, type InitOptions, type ItemType, type Level, MAX_TRANSACTION_EXTRA_BYTES, type Mechanism, type OsContext, type ResolvedOptions, type RuntimeContext, SDK_NAME, SDK_VERSION, Sauron, SauronClient, type SdkInfo, type TrackOptions, type TransactionInput, type TransactionItem, type TransactionOp, type TransportOptions, type UserContext, type UserInput, type WorkflowResult, type WorkflowStatus, addBreadcrumb, buildEnvelope, cancelWorkflow, capTransactionExtra, captureException, captureMessage, close, Sauron as default, endWorkflow, flush, getClient, getScreen, getWorkflow, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, reset, setContext, setExtra, setScreen, setTag, setTags, setUser, startWorkflow, track, trackTransaction };

package/dist/index.d.ts

@@ -144,6 +144,19 @@ interface TransactionItem {
     workflow_id?: string;
     workflow_name?: string;
     timestamp: string;
+    /**
+     * Developer-supplied flat string tags for THIS transaction.
+     *
+     * Unlike {@link EventItem} and the error item, this is NOT merged with the
+     * scope — see {@link TransactionInput.tags}. Omitted entirely when empty.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Developer-supplied freeform JSON for THIS transaction — the request body,
+     * the response body, a retry count. Capped and replaced with a truncation
+     * marker past {@link MAX_TRANSACTION_EXTRA_BYTES}. Omitted when empty.
+     */
+    extra?: Record<string, unknown>;
 }
 /** An identity association (PostHog-style `identify`). */
 interface IdentifyItem {
@@ -330,6 +343,29 @@ interface TransactionInput {
     httpMethod?: string | null;
     httpStatus?: number | null;
     url?: string | null;
+    /**
+     * Flat string tags for this transaction.
+     *
+     * **Per-call only — the scope is NOT merged in**, which is the one place
+     * transactions differ from `track()` and `captureException()`. Those two
+     * merge `setTag`/`setExtra` defaults; a transaction carries only what its own
+     * call site attached. Transactions are the highest-volume signal (one per
+     * navigation and per HTTP call), so inheriting a global blob would write it
+     * onto every row.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Freeform JSON for this transaction — the request body, the response body,
+     * an order id, a retry count.
+     *
+     * Per-call only, for the reason on {@link TransactionInput.tags}. Serialized
+     * and capped at {@link MAX_TRANSACTION_EXTRA_BYTES}; past that the whole map
+     * is replaced with `{ _truncated: true, _bytes: N }` so one large body cannot
+     * take a batched envelope over the ingest limit and drop every span in it.
+     *
+     * Nothing here is scrubbed. `beforeSend` is the redaction seam.
+     */
+    extra?: Record<string, unknown>;
 }
 
 /**
@@ -561,7 +597,34 @@ declare function parseError(err: unknown): Frame[];
 /** Small dependency-free helpers shared across the SDK. */
 /** SDK identity, embedded in every envelope header. */
 declare const SDK_NAME = "sauron.javascript";
-declare const SDK_VERSION = "1.4.1";
+declare const SDK_VERSION = "1.6.0";
+/**
+ * Largest serialized `extra` a single transaction may carry, in bytes.
+ *
+ * Transactions are the highest-volume signal and they ship in BATCHED
+ * envelopes, so one oversized payload does not fail alone — ingest rejects the
+ * whole envelope past `INGEST_MAX_BODY_BYTES` (1 MiB by default) and every
+ * unrelated span batched with it is lost. Since the motivating use of
+ * transaction `extra` is request and response bodies, that is not a remote
+ * hazard.
+ */
+declare const MAX_TRANSACTION_EXTRA_BYTES: number;
+/**
+ * Cap a transaction's `extra`, substituting a marker when it is too large.
+ *
+ * Replaces the WHOLE map rather than trimming keys: a half-written JSON value
+ * is worse than an honest marker, and per-key trimming would make the result
+ * depend on key iteration order, which differs across the five SDKs. The
+ * marker is deliberately readable on the dashboard — `_truncated` says data
+ * was dropped rather than silently serving a short object that looks complete.
+ *
+ * Returns the input unchanged when it fits. A value that cannot be serialized
+ * at all (a cycle, a BigInt) is replaced by the same marker with `_bytes: -1`,
+ * because the alternative is throwing from inside `trackTransaction` — and an
+ * SDK that crashes the app it is measuring is worse than one that drops a
+ * payload.
+ */
+declare function capTransactionExtra(extra: Record<string, unknown>, maxBytes?: number): Record<string, unknown>;
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -673,4 +736,4 @@ declare const Sauron: {
     getClient: typeof getClient;
 };
 
-export { type ActiveWorkflow, type AppContext, type BeforeBreadcrumb, type BeforeSend, type Breadcrumb, type BreadcrumbBatchItem, type BreadcrumbInput, type CaptureOptions, type Context, type DeviceContext, type Dsn, DsnError, type Envelope, type EnvelopeHeader, type EnvelopeItem, type ErrorItem, type EventItem, type ExceptionValue, type Frame, type Hint, type IdentifyItem, type InitOptions, type ItemType, type Level, type Mechanism, type OsContext, type ResolvedOptions, type RuntimeContext, SDK_NAME, SDK_VERSION, Sauron, SauronClient, type SdkInfo, type TrackOptions, type TransactionInput, type TransactionItem, type TransactionOp, type TransportOptions, type UserContext, type UserInput, type WorkflowResult, type WorkflowStatus, addBreadcrumb, buildEnvelope, cancelWorkflow, captureException, captureMessage, close, Sauron as default, endWorkflow, flush, getClient, getScreen, getWorkflow, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, reset, setContext, setExtra, setScreen, setTag, setTags, setUser, startWorkflow, track, trackTransaction };
+export { type ActiveWorkflow, type AppContext, type BeforeBreadcrumb, type BeforeSend, type Breadcrumb, type BreadcrumbBatchItem, type BreadcrumbInput, type CaptureOptions, type Context, type DeviceContext, type Dsn, DsnError, type Envelope, type EnvelopeHeader, type EnvelopeItem, type ErrorItem, type EventItem, type ExceptionValue, type Frame, type Hint, type IdentifyItem, type InitOptions, type ItemType, type Level, MAX_TRANSACTION_EXTRA_BYTES, type Mechanism, type OsContext, type ResolvedOptions, type RuntimeContext, SDK_NAME, SDK_VERSION, Sauron, SauronClient, type SdkInfo, type TrackOptions, type TransactionInput, type TransactionItem, type TransactionOp, type TransportOptions, type UserContext, type UserInput, type WorkflowResult, type WorkflowStatus, addBreadcrumb, buildEnvelope, cancelWorkflow, capTransactionExtra, captureException, captureMessage, close, Sauron as default, endWorkflow, flush, getClient, getScreen, getWorkflow, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, reset, setContext, setExtra, setScreen, setTag, setTags, setUser, startWorkflow, track, trackTransaction };

package/dist/index.js

@@ -4,7 +4,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;
 }
@@ -83,6 +83,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";
@@ -813,12 +839,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);
@@ -829,11 +855,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;
     });
@@ -845,7 +872,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", () => {
@@ -1022,7 +1049,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),
@@ -1035,6 +1062,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();
@@ -2191,13 +2223,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 }
   });
 }
 
@@ -2297,6 +2329,6 @@ var Sauron = {
 };
 var index_default = Sauron;
 
-export { DsnError, SDK_NAME, SDK_VERSION, Sauron, SauronClient, addBreadcrumb2 as addBreadcrumb, buildEnvelope, cancelWorkflow2 as cancelWorkflow, captureException2 as captureException, captureMessage2 as captureMessage, close, index_default as default, endWorkflow2 as endWorkflow, flush, getClient, getScreen2 as getScreen, getWorkflow2 as getWorkflow, identify2 as identify, init2 as init, isInAppFrame, parseDsn, parseError, parseStackString, reset, setContext, setExtra, setScreen2 as setScreen, setTag, setTags, setUser, startWorkflow2 as startWorkflow, track2 as track, trackTransaction2 as trackTransaction };
+export { DsnError, MAX_TRANSACTION_EXTRA_BYTES, SDK_NAME, SDK_VERSION, Sauron, SauronClient, addBreadcrumb2 as addBreadcrumb, buildEnvelope, cancelWorkflow2 as cancelWorkflow, capTransactionExtra, captureException2 as captureException, captureMessage2 as captureMessage, close, index_default as default, endWorkflow2 as endWorkflow, flush, getClient, getScreen2 as getScreen, getWorkflow2 as getWorkflow, identify2 as identify, init2 as init, isInAppFrame, parseDsn, parseError, parseStackString, reset, setContext, setExtra, setScreen2 as setScreen, setTag, setTags, setUser, startWorkflow2 as startWorkflow, track2 as track, trackTransaction2 as trackTransaction };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map