@edraj/sauron-browser 1.4.0 → 1.4.1

package/dist/index.d.cts

@@ -374,6 +374,24 @@ declare class Scope {
     readonly extra: Record<string, unknown>;
     constructor(maxBreadcrumbs?: number);
     setMaxBreadcrumbs(max: number): void;
+    /**
+     * 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: UserInput): void;
     /** The user context for an envelope. Never null — defaults to an empty user. */
     getUser(): UserContext;
@@ -438,14 +456,40 @@ declare class SauronClient {
     /** The anonymous id, or null when it was never actually used as an identity. */
     getAnonymousId(): string | 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(): void;
+    /**
+     * 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: string): string | null;
     /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
     makeEnvelope(items: EnvelopeItem[]): Envelope;
     /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
@@ -517,7 +561,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.4.0";
+declare const SDK_VERSION = "1.4.1";
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -540,7 +584,16 @@ declare function captureException(err: unknown, hint?: Hint): void;
 declare function captureMessage(message: string, level?: Level, hint?: Hint): void;
 /** Record a product-analytics event, optionally with per-call tags/contexts/extra. */
 declare function track(name: string, properties?: Record<string, unknown>, options?: TrackOptions): void;
-/** Associate the session with a known user. */
+/**
+ * Associate the session with a known user.
+ *
+ * The `anonymous_id` sent with the identify item is the current anon id — but
+ * only when it was actually used as a `distinct_id` this session, and never
+ * when it belongs to a different person than the last one who identified on
+ * this device. In that case a fresh anon id is minted first and `null` is
+ * sent instead, since the old one is already permanently bound to the
+ * previous person server-side (see `reset()`).
+ */
 declare function identify(id: string, traits?: Record<string, unknown>): void;
 /** Record a performance transaction (navigation, http, screen load, ...). */
 declare function trackTransaction(input: TransactionInput): void;
@@ -570,14 +623,15 @@ declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
 /**
  * Set (or clear, with `null`) the current user.
  *
- * `setUser(null)` is a logout, so it also rotates the anonymous id — otherwise
+ * `setUser(null)` is a logout, so it also calls `reset()` for you — 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.
+ * Forget the current person: clears the scope user, mints a fresh anonymous
+ * id, forgets the last identified user, and rotates the session id so a
+ * single session can never span two different people. Call this on logout.
  */
 declare function reset(): void;
 /** Set a single scope tag (lifted onto later errors/events). */

package/dist/index.d.ts

@@ -374,6 +374,24 @@ declare class Scope {
     readonly extra: Record<string, unknown>;
     constructor(maxBreadcrumbs?: number);
     setMaxBreadcrumbs(max: number): void;
+    /**
+     * 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: UserInput): void;
     /** The user context for an envelope. Never null — defaults to an empty user. */
     getUser(): UserContext;
@@ -438,14 +456,40 @@ declare class SauronClient {
     /** The anonymous id, or null when it was never actually used as an identity. */
     getAnonymousId(): string | 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(): void;
+    /**
+     * 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: string): string | null;
     /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
     makeEnvelope(items: EnvelopeItem[]): Envelope;
     /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
@@ -517,7 +561,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.4.0";
+declare const SDK_VERSION = "1.4.1";
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -540,7 +584,16 @@ declare function captureException(err: unknown, hint?: Hint): void;
 declare function captureMessage(message: string, level?: Level, hint?: Hint): void;
 /** Record a product-analytics event, optionally with per-call tags/contexts/extra. */
 declare function track(name: string, properties?: Record<string, unknown>, options?: TrackOptions): void;
-/** Associate the session with a known user. */
+/**
+ * Associate the session with a known user.
+ *
+ * The `anonymous_id` sent with the identify item is the current anon id — but
+ * only when it was actually used as a `distinct_id` this session, and never
+ * when it belongs to a different person than the last one who identified on
+ * this device. In that case a fresh anon id is minted first and `null` is
+ * sent instead, since the old one is already permanently bound to the
+ * previous person server-side (see `reset()`).
+ */
 declare function identify(id: string, traits?: Record<string, unknown>): void;
 /** Record a performance transaction (navigation, http, screen load, ...). */
 declare function trackTransaction(input: TransactionInput): void;
@@ -570,14 +623,15 @@ declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
 /**
  * Set (or clear, with `null`) the current user.
  *
- * `setUser(null)` is a logout, so it also rotates the anonymous id — otherwise
+ * `setUser(null)` is a logout, so it also calls `reset()` for you — 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.
+ * Forget the current person: clears the scope user, mints a fresh anonymous
+ * id, forgets the last identified user, and rotates the session id so a
+ * single session can never span two different people. Call this on logout.
  */
 declare function reset(): void;
 /** Set a single scope tag (lifted onto later errors/events). */

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.0";
+var SDK_VERSION = "1.4.1";
 function getGlobal() {
   return globalThis;
 }
@@ -88,6 +88,29 @@ function makeLogger(debug) {
 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];
@@ -121,6 +144,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;
@@ -129,6 +153,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");
@@ -163,6 +198,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() {
@@ -809,13 +875,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 ?? {}
     };
@@ -916,11 +1000,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 ?? {}
   };
@@ -1850,18 +1935,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 = {