@edraj/sauron-browser 1.3.0 → 1.4.0

package/dist/index.d.cts

@@ -24,9 +24,17 @@ interface Mechanism {
     type: string;
     handled: boolean;
 }
-/** The exception payload of an error item. */
+/**
+ * The exception payload of an error item.
+ *
+ * `type` is NOT nullable: the backend's `ExceptionInfo.ty` is a non-`Option`
+ * `String` with no serde default, so `null` fails to deserialize and the
+ * gateway 400s the ENTIRE envelope — every other item in the batch with it.
+ * An item with no exception type omits `exception` altogether and carries its
+ * text in {@link ErrorItem.message}.
+ */
 interface ExceptionValue {
-    type: string | null;
+    type: string;
     value: string | null;
     mechanism: Mechanism;
     stacktrace: Frame[];
@@ -50,8 +58,14 @@ interface ErrorItem {
     event_id?: string;
     timestamp: string;
     level: Level;
-    exception: ExceptionValue;
-    /** Optional human-readable summary alongside the exception. */
+    /**
+     * The captured exception. OPTIONAL — a message capture omits it entirely and
+     * carries its text in {@link message} instead (the backend's `exception` is
+     * `Option<ExceptionInfo>`, and with no exception it fingerprints off
+     * `message`). Never emit a placeholder here just to fill the field.
+     */
+    exception?: ExceptionValue;
+    /** Human-readable summary; the ONLY text carrier when `exception` is absent. */
     message?: string;
     breadcrumbs: Breadcrumb[];
     fingerprint: string[] | null;
@@ -392,7 +406,6 @@ declare class SauronClient {
     private readonly nativeFetch?;
     private enabled;
     private installed;
-    private anonymousId;
     private beaconCleanup;
     constructor(options: ResolvedOptions);
     /** Install global handlers + auto-instrumentation and start the transport. */
@@ -410,11 +423,29 @@ declare class SauronClient {
      * null` as the no-op/disabled case before it ever reaches here.
      */
     isEnabled(): boolean;
+    /**
+     * Whether the anonymous id has actually been USED as a `distinct_id` in this
+     * browser session.
+     *
+     * A persisted id that has never been observed anonymously must not create a
+     * permanent `identities` alias row on the server: aliasing is a durable
+     * server-side binding of this browser profile to a named user, and an
+     * identify() on a first-ever page load has no anonymous history to link.
+     */
+    private anonUsed;
     /** The current distinct id: the user id when identified, else an anon id. */
     getDistinctId(): string | null;
-    /** The anonymous id, or null if one was never needed. */
+    /** The anonymous id, or null when it was never actually used as an identity. */
     getAnonymousId(): string | null;
-    private ensureAnonymousId;
+    /**
+     * Forget the current person: clear the scope user and mint a fresh anonymous
+     * 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.
+     */
+    reset(): void;
     /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
     makeEnvelope(items: EnvelopeItem[]): Envelope;
     /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
@@ -486,7 +517,7 @@ 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.3.0";
+declare const SDK_VERSION = "1.4.0";
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -536,8 +567,19 @@ declare function cancelWorkflow(name?: string, options?: {
 declare function getWorkflow(): ActiveWorkflow | null;
 /** Record a breadcrumb. */
 declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
-/** Set (or clear, with `null`) the current user. */
+/**
+ * Set (or clear, with `null`) the current user.
+ *
+ * `setUser(null)` is a logout, so it also rotates the anonymous id — otherwise
+ * the next anonymous visitor on this browser inherits the previous person's
+ * durable id and a later identify() aliases them together server-side.
+ */
 declare function setUser(user: UserInput): void;
+/**
+ * Forget the current person: clears the scope user and mints a fresh anonymous
+ * id. Call this on logout.
+ */
+declare function reset(): void;
 /** Set a single scope tag (lifted onto later errors/events). */
 declare function setTag(key: string, value: string): void;
 /** Merge a batch of scope tags (last-write-wins per key). */
@@ -561,6 +603,7 @@ declare const Sauron: {
     identify: typeof identify;
     addBreadcrumb: typeof addBreadcrumb;
     setUser: typeof setUser;
+    reset: typeof reset;
     setTag: typeof setTag;
     setTags: typeof setTags;
     setContext: typeof setContext;
@@ -576,4 +619,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, 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, 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 };

package/dist/index.d.ts

@@ -24,9 +24,17 @@ interface Mechanism {
     type: string;
     handled: boolean;
 }
-/** The exception payload of an error item. */
+/**
+ * The exception payload of an error item.
+ *
+ * `type` is NOT nullable: the backend's `ExceptionInfo.ty` is a non-`Option`
+ * `String` with no serde default, so `null` fails to deserialize and the
+ * gateway 400s the ENTIRE envelope — every other item in the batch with it.
+ * An item with no exception type omits `exception` altogether and carries its
+ * text in {@link ErrorItem.message}.
+ */
 interface ExceptionValue {
-    type: string | null;
+    type: string;
     value: string | null;
     mechanism: Mechanism;
     stacktrace: Frame[];
@@ -50,8 +58,14 @@ interface ErrorItem {
     event_id?: string;
     timestamp: string;
     level: Level;
-    exception: ExceptionValue;
-    /** Optional human-readable summary alongside the exception. */
+    /**
+     * The captured exception. OPTIONAL — a message capture omits it entirely and
+     * carries its text in {@link message} instead (the backend's `exception` is
+     * `Option<ExceptionInfo>`, and with no exception it fingerprints off
+     * `message`). Never emit a placeholder here just to fill the field.
+     */
+    exception?: ExceptionValue;
+    /** Human-readable summary; the ONLY text carrier when `exception` is absent. */
     message?: string;
     breadcrumbs: Breadcrumb[];
     fingerprint: string[] | null;
@@ -392,7 +406,6 @@ declare class SauronClient {
     private readonly nativeFetch?;
     private enabled;
     private installed;
-    private anonymousId;
     private beaconCleanup;
     constructor(options: ResolvedOptions);
     /** Install global handlers + auto-instrumentation and start the transport. */
@@ -410,11 +423,29 @@ declare class SauronClient {
      * null` as the no-op/disabled case before it ever reaches here.
      */
     isEnabled(): boolean;
+    /**
+     * Whether the anonymous id has actually been USED as a `distinct_id` in this
+     * browser session.
+     *
+     * A persisted id that has never been observed anonymously must not create a
+     * permanent `identities` alias row on the server: aliasing is a durable
+     * server-side binding of this browser profile to a named user, and an
+     * identify() on a first-ever page load has no anonymous history to link.
+     */
+    private anonUsed;
     /** The current distinct id: the user id when identified, else an anon id. */
     getDistinctId(): string | null;
-    /** The anonymous id, or null if one was never needed. */
+    /** The anonymous id, or null when it was never actually used as an identity. */
     getAnonymousId(): string | null;
-    private ensureAnonymousId;
+    /**
+     * Forget the current person: clear the scope user and mint a fresh anonymous
+     * 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.
+     */
+    reset(): void;
     /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
     makeEnvelope(items: EnvelopeItem[]): Envelope;
     /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
@@ -486,7 +517,7 @@ 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.3.0";
+declare const SDK_VERSION = "1.4.0";
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -536,8 +567,19 @@ declare function cancelWorkflow(name?: string, options?: {
 declare function getWorkflow(): ActiveWorkflow | null;
 /** Record a breadcrumb. */
 declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
-/** Set (or clear, with `null`) the current user. */
+/**
+ * Set (or clear, with `null`) the current user.
+ *
+ * `setUser(null)` is a logout, so it also rotates the anonymous id — otherwise
+ * the next anonymous visitor on this browser inherits the previous person's
+ * durable id and a later identify() aliases them together server-side.
+ */
 declare function setUser(user: UserInput): void;
+/**
+ * Forget the current person: clears the scope user and mints a fresh anonymous
+ * id. Call this on logout.
+ */
+declare function reset(): void;
 /** Set a single scope tag (lifted onto later errors/events). */
 declare function setTag(key: string, value: string): void;
 /** Merge a batch of scope tags (last-write-wins per key). */
@@ -561,6 +603,7 @@ declare const Sauron: {
     identify: typeof identify;
     addBreadcrumb: typeof addBreadcrumb;
     setUser: typeof setUser;
+    reset: typeof reset;
     setTag: typeof setTag;
     setTags: typeof setTags;
     setContext: typeof setContext;
@@ -576,4 +619,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, 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, 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 };

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.3.0";
+var SDK_VERSION = "1.4.0";
 function getGlobal() {
   return globalThis;
 }
@@ -87,6 +87,7 @@ function makeLogger(debug) {
 // src/identity.ts
 var DEVICE_ID_KEY = "sauron.device_id";
 var SESSION_ID_KEY = "sauron.session_id";
+var ANON_ID_KEY = "sauron.anon_id";
 function webStorage(name) {
   try {
     const s = globalThis[name];
@@ -119,6 +120,7 @@ function persistentId(cached, storage, key) {
 }
 var deviceId = null;
 var sessionId = null;
+var anonymousId = null;
 function getDeviceId() {
   deviceId = persistentId(deviceId, webStorage("localStorage"), DEVICE_ID_KEY);
   return deviceId;
@@ -127,6 +129,40 @@ function getSessionId() {
   sessionId = persistentId(sessionId, webStorage("sessionStorage"), SESSION_ID_KEY);
   return sessionId;
 }
+function getAnonymousId() {
+  if (anonymousId) return anonymousId;
+  const storage = webStorage("localStorage");
+  if (storage) {
+    try {
+      const existing = storage.getItem(ANON_ID_KEY);
+      if (existing) {
+        anonymousId = existing;
+        return anonymousId;
+      }
+    } catch {
+    }
+  }
+  const fresh = `anon_${uuidv4()}`;
+  if (storage) {
+    try {
+      storage.setItem(ANON_ID_KEY, fresh);
+    } catch {
+    }
+  }
+  anonymousId = fresh;
+  return anonymousId;
+}
+function resetAnonymousId() {
+  anonymousId = null;
+  const storage = webStorage("localStorage");
+  if (storage) {
+    try {
+      storage.removeItem(ANON_ID_KEY);
+    } catch {
+    }
+  }
+  return getAnonymousId();
+}
 
 // src/context.ts
 function getNavigator() {
@@ -624,12 +660,7 @@ function captureMessage(message, level = "info", hint) {
     type: "error",
     timestamp: nowIso(),
     level,
-    exception: {
-      type: null,
-      value: message,
-      mechanism: { type: "message", handled: true },
-      stacktrace: []
-    },
+    message,
     breadcrumbs,
     fingerprint: hint?.fingerprint ?? null,
     session_id: getSessionId(),
@@ -885,12 +916,12 @@ function setScreen(name) {
 function identify(id, traits = {}) {
   const client = getClient();
   if (!client) return;
-  const anonymousId = client.getAnonymousId();
+  const anonymousId2 = client.getAnonymousId();
   client.getScope().setUser({ id, traits });
   const item = {
     type: "identify",
     distinct_id: id,
-    anonymous_id: anonymousId,
+    anonymous_id: anonymousId2,
     traits: traits ?? {}
   };
   client.captureItem(item);
@@ -1395,6 +1426,21 @@ var OfflineQueue = class {
     if (entries.length) this.write([]);
     return entries;
   }
+  /**
+   * Put drained payloads BACK at the head, keeping their relative order.
+   *
+   * The counterpart to {@link drain}: a drain empties the store immediately, so
+   * whatever the caller could not deliver only exists in its local array and is
+   * lost the moment the caller returns. Re-parking at the head (rather than via
+   * {@link enqueue}) keeps the queue oldest-first, which is what the byte-cap
+   * eviction policy assumes — the oldest entry must stay the first one evicted.
+   */
+  requeueFront(payloads) {
+    if (!this.storage || payloads.length === 0) return;
+    const entries = [...payloads, ...this.read()];
+    this.evict(entries);
+    this.write(entries);
+  }
   /** Non-destructive read of the current entries, oldest first. */
   peek() {
     return this.read();
@@ -1580,11 +1626,21 @@ var Transport = class {
       }
     }
   }
-  /** Re-attempt any envelopes that were parked while offline. */
+  /**
+   * Re-attempt any envelopes that were parked while offline.
+   *
+   * `drain()` empties `localStorage` in one shot, so from here on the ONLY copy
+   * of the backlog is the local `payloads` array. Every early return therefore
+   * has to re-park the whole untried remainder, not just the payload that
+   * failed: this used to re-park the failing one and return, which silently
+   * deleted every payload behind it — the exact reconnect-then-one-500 case the
+   * queue exists for.
+   */
   async drainOfflineQueue() {
     if (this.disabled || !this.offline.available) return;
     const payloads = this.offline.drain();
-    for (const json of payloads) {
+    for (let i = 0; i < payloads.length; i++) {
+      const json = payloads[i];
       let outcome;
       try {
         outcome = await this.post(json);
@@ -1592,13 +1648,14 @@ var Transport = class {
         outcome = { action: "retry_backoff" };
       }
       if (outcome.action === "disable") {
+        this.logger.warn("server rejected credentials while draining; disabling client");
         this.disable();
         this.onDisable();
-        this.offline.enqueue(json);
+        this.offline.requeueFront(payloads.slice(i));
         return;
       }
       if (outcome.action === "retry_after" || outcome.action === "retry_backoff") {
-        this.offline.enqueue(json);
+        this.offline.requeueFront(payloads.slice(i));
         return;
       }
     }
@@ -1708,8 +1765,17 @@ var SauronClient = class {
     __publicField(this, "nativeFetch");
     __publicField(this, "enabled", true);
     __publicField(this, "installed", false);
-    __publicField(this, "anonymousId", null);
     __publicField(this, "beaconCleanup", null);
+    /**
+     * Whether the anonymous id has actually been USED as a `distinct_id` in this
+     * browser session.
+     *
+     * A persisted id that has never been observed anonymously must not create a
+     * permanent `identities` alias row on the server: aliasing is a durable
+     * server-side binding of this browser profile to a named user, and an
+     * identify() on a first-ever page load has no anonymous history to link.
+     */
+    __publicField(this, "anonUsed", false);
     this.options = options;
     this.dsn = parseDsn(options.dsn);
     this.logger = makeLogger(options.debug);
@@ -1776,15 +1842,25 @@ var SauronClient = class {
   getDistinctId() {
     const user = this.scope.getUser();
     if (user.id) return user.id;
-    return this.ensureAnonymousId();
+    this.anonUsed = true;
+    return getAnonymousId();
   }
-  /** The anonymous id, or null if one was never needed. */
+  /** The anonymous id, or null when it was never actually used as an identity. */
   getAnonymousId() {
-    return this.anonymousId;
+    return this.anonUsed ? getAnonymousId() : null;
   }
-  ensureAnonymousId() {
-    if (!this.anonymousId) this.anonymousId = `anon_${uuidv4()}`;
-    return this.anonymousId;
+  /**
+   * Forget the current person: clear the scope user and mint a fresh anonymous
+   * 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.
+   */
+  reset() {
+    this.scope.setUser(null);
+    resetAnonymousId();
+    this.anonUsed = false;
   }
   /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
   makeEnvelope(items) {
@@ -2043,8 +2119,15 @@ function addBreadcrumb2(breadcrumb, hint) {
   addBreadcrumb(breadcrumb, hint);
 }
 function setUser(user) {
+  if (user === null) {
+    getClient()?.reset();
+    return;
+  }
   getClient()?.getScope().setUser(user);
 }
+function reset() {
+  getClient()?.reset();
+}
 function setTag(key, value) {
   getClient()?.getScope().setTag(key, value);
 }
@@ -2074,6 +2157,7 @@ var Sauron = {
   identify: identify2,
   addBreadcrumb: addBreadcrumb2,
   setUser,
+  reset,
   setTag,
   setTags,
   setContext,
@@ -2090,6 +2174,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, setContext, setExtra, setScreen2 as setScreen, setTag, setTags, setUser, startWorkflow2 as startWorkflow, track2 as track, trackTransaction2 as trackTransaction };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map