@edraj/sauron-browser 1.3.0 → 1.4.1

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;
@@ -360,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;
@@ -392,7 +424,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 +441,55 @@ 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, 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. 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. */
@@ -486,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.3.0";
+declare const SDK_VERSION = "1.4.1";
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -509,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;
@@ -536,8 +620,20 @@ 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 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, 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). */
 declare function setTag(key: string, value: string): void;
 /** Merge a batch of scope tags (last-write-wins per key). */
@@ -561,6 +657,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 +673,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;
@@ -360,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;
@@ -392,7 +424,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 +441,55 @@ 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, 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. 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. */
@@ -486,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.3.0";
+declare const SDK_VERSION = "1.4.1";
 
 /**
  * `@edraj/sauron-browser` — public API surface.
@@ -509,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;
@@ -536,8 +620,20 @@ 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 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, 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). */
 declare function setTag(key: string, value: string): void;
 /** Merge a batch of scope tags (last-write-wins per key). */
@@ -561,6 +657,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 +673,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 };