@edraj/sauron-browser 1.0.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -24,9 +24,17 @@ interface Mechanism {
24
24
  type: string;
25
25
  handled: boolean;
26
26
  }
27
- /** The exception payload of an error item. */
27
+ /**
28
+ * The exception payload of an error item.
29
+ *
30
+ * `type` is NOT nullable: the backend's `ExceptionInfo.ty` is a non-`Option`
31
+ * `String` with no serde default, so `null` fails to deserialize and the
32
+ * gateway 400s the ENTIRE envelope — every other item in the batch with it.
33
+ * An item with no exception type omits `exception` altogether and carries its
34
+ * text in {@link ErrorItem.message}.
35
+ */
28
36
  interface ExceptionValue {
29
- type: string | null;
37
+ type: string;
30
38
  value: string | null;
31
39
  mechanism: Mechanism;
32
40
  stacktrace: Frame[];
@@ -50,8 +58,14 @@ interface ErrorItem {
50
58
  event_id?: string;
51
59
  timestamp: string;
52
60
  level: Level;
53
- exception: ExceptionValue;
54
- /** Optional human-readable summary alongside the exception. */
61
+ /**
62
+ * The captured exception. OPTIONAL a message capture omits it entirely and
63
+ * carries its text in {@link message} instead (the backend's `exception` is
64
+ * `Option<ExceptionInfo>`, and with no exception it fingerprints off
65
+ * `message`). Never emit a placeholder here just to fill the field.
66
+ */
67
+ exception?: ExceptionValue;
68
+ /** Human-readable summary; the ONLY text carrier when `exception` is absent. */
55
69
  message?: string;
56
70
  breadcrumbs: Breadcrumb[];
57
71
  fingerprint: string[] | null;
@@ -74,6 +88,13 @@ interface ErrorItem {
74
88
  */
75
89
  user?: UserContext | null;
76
90
  session_id?: string | null;
91
+ /**
92
+ * The active workflow this item was stamped with, if any. A pair —
93
+ * always both present or both absent, never one without the other. See
94
+ * {@link ActiveWorkflow}.
95
+ */
96
+ workflow_id?: string;
97
+ workflow_name?: string;
77
98
  screen?: string | null;
78
99
  }
79
100
  /** A product-analytics event (PostHog-style `track`). */
@@ -82,6 +103,13 @@ interface EventItem {
82
103
  name: string;
83
104
  distinct_id: string | null;
84
105
  session_id?: string | null;
106
+ /**
107
+ * The active workflow this item was stamped with, if any. A pair —
108
+ * always both present or both absent, never one without the other. See
109
+ * {@link ActiveWorkflow}.
110
+ */
111
+ workflow_id?: string;
112
+ workflow_name?: string;
85
113
  screen?: string | null;
86
114
  timestamp: string;
87
115
  properties: Record<string, unknown>;
@@ -108,6 +136,13 @@ interface TransactionItem {
108
136
  url?: string | null;
109
137
  distinct_id?: string | null;
110
138
  session_id?: string | null;
139
+ /**
140
+ * The active workflow this item was stamped with, if any. A pair —
141
+ * always both present or both absent, never one without the other. See
142
+ * {@link ActiveWorkflow}.
143
+ */
144
+ workflow_id?: string;
145
+ workflow_name?: string;
111
146
  timestamp: string;
112
147
  }
113
148
  /** An identity association (PostHog-style `identify`). */
@@ -163,7 +198,6 @@ interface EnvelopeHeader {
163
198
  dsn: string;
164
199
  sdk: SdkInfo;
165
200
  sent_at: string;
166
- environment: string;
167
201
  release: string | null;
168
202
  }
169
203
  /** The complete, serializable envelope posted to the ingest gateway. */
@@ -191,6 +225,25 @@ interface CaptureOptions {
191
225
  interface TrackOptions extends CaptureOptions {
192
226
  screen?: string;
193
227
  }
228
+ /**
229
+ * Outcome of `startWorkflow` / `endWorkflow` / `cancelWorkflow`. Telemetry
230
+ * never throws — every call resolves to one of these instead.
231
+ */
232
+ type WorkflowStatus = 'ok' | 'already_active' | 'not_active' | 'name_mismatch' | 'invalid_name' | 'disabled';
233
+ /** Result of a workflow lifecycle call. */
234
+ interface WorkflowResult {
235
+ status: WorkflowStatus;
236
+ /** The workflow id involved, when `status` is `'ok'`. */
237
+ workflowId?: string;
238
+ }
239
+ /** The currently-active workflow, as returned by `getWorkflow()`. */
240
+ interface ActiveWorkflow {
241
+ /** Client-generated UUID — the server rollup key is `(app_id, workflow_id)`. */
242
+ workflowId: string;
243
+ name: string;
244
+ /** ISO-8601 UTC timestamp of `startWorkflow()`. */
245
+ startedAt: string;
246
+ }
194
247
  /** Value accepted by `setUser` — normalized into a `UserContext`. */
195
248
  type UserInput = (Partial<UserContext> & {
196
249
  id?: string | null;
@@ -211,7 +264,6 @@ interface TransportOptions {
211
264
  interface InitOptions {
212
265
  /** `https://<public_key>@<host>/<project_id>` */
213
266
  dsn: string;
214
- environment?: string;
215
267
  release?: string;
216
268
  /** Error sample rate in [0, 1]. Default 1 (send everything). */
217
269
  sampleRate?: number;
@@ -244,7 +296,6 @@ interface InitOptions {
244
296
  /** Fully-resolved options with all defaults applied. */
245
297
  interface ResolvedOptions {
246
298
  dsn: string;
247
- environment: string;
248
299
  release: string | null;
249
300
  sampleRate: number;
250
301
  maxBreadcrumbs: number;
@@ -355,18 +406,46 @@ declare class SauronClient {
355
406
  private readonly nativeFetch?;
356
407
  private enabled;
357
408
  private installed;
358
- private anonymousId;
359
409
  private beaconCleanup;
360
410
  constructor(options: ResolvedOptions);
361
411
  /** Install global handlers + auto-instrumentation and start the transport. */
362
412
  install(): void;
363
413
  getScope(): Scope;
414
+ /**
415
+ * False once this client was explicitly disabled/closed, OR once the
416
+ * transport has auto-disabled itself on a 401/403 (revoked/invalid DSN
417
+ * key) — computed from the transport's own state on every call, not a
418
+ * separately mirrored flag, so a propagation regression there cannot leave
419
+ * this predicate stale. `this.transport` always exists once a client
420
+ * exists (it is constructed synchronously in the constructor); the
421
+ * "nothing installed yet" case is instead handled one layer up, by every
422
+ * module-level API (`startWorkflow`, `track`, ...) treating `getClient() ===
423
+ * null` as the no-op/disabled case before it ever reaches here.
424
+ */
364
425
  isEnabled(): boolean;
426
+ /**
427
+ * Whether the anonymous id has actually been USED as a `distinct_id` in this
428
+ * browser session.
429
+ *
430
+ * A persisted id that has never been observed anonymously must not create a
431
+ * permanent `identities` alias row on the server: aliasing is a durable
432
+ * server-side binding of this browser profile to a named user, and an
433
+ * identify() on a first-ever page load has no anonymous history to link.
434
+ */
435
+ private anonUsed;
365
436
  /** The current distinct id: the user id when identified, else an anon id. */
366
437
  getDistinctId(): string | null;
367
- /** The anonymous id, or null if one was never needed. */
438
+ /** The anonymous id, or null when it was never actually used as an identity. */
368
439
  getAnonymousId(): string | null;
369
- private ensureAnonymousId;
440
+ /**
441
+ * Forget the current person: clear the scope user and mint a fresh anonymous
442
+ * id.
443
+ *
444
+ * MUST BE CALLED ON LOGOUT. Without it, the next anonymous visitor on this
445
+ * browser reuses the persisted anon id, and a later identify() aliases their
446
+ * activity to the previous account server-side, permanently.
447
+ */
448
+ reset(): void;
370
449
  /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
371
450
  makeEnvelope(items: EnvelopeItem[]): Envelope;
372
451
  /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
@@ -379,6 +458,23 @@ declare class SauronClient {
379
458
  * `event_id` is always minted so callers can correlate the report.
380
459
  */
381
460
  private enrichErrorItem;
461
+ /**
462
+ * Stamp the active workflow (if any) onto a signal item.
463
+ *
464
+ * Done HERE — the single choke point every capture path funnels through —
465
+ * rather than at each item-construction site, so a capture path added later
466
+ * is stamped by construction instead of by remembering to. The keys are
467
+ * ASSIGNED ONLY when a workflow is active: an item with no workflow keeps
468
+ * them absent entirely (not present-as-`undefined`), which is what makes
469
+ * `JSON.stringify` omit them and keeps the no-workflow wire bytes identical
470
+ * to pre-1.3.0.
471
+ *
472
+ * Only error/event/transaction carry `workflow_id`/`workflow_name` columns
473
+ * server-side — identify and breadcrumb_batch items are deliberately left
474
+ * alone. An item that already carries an explicit `workflow_id` is left
475
+ * untouched, matching how `enrichErrorItem` defers to caller-set fields.
476
+ */
477
+ private stampWorkflow;
382
478
  /**
383
479
  * Run an item through sampling (errors only) and `beforeSend`, then hand it to
384
480
  * the transport. Returns silently when dropped.
@@ -421,7 +517,7 @@ declare function parseError(err: unknown): Frame[];
421
517
  /** Small dependency-free helpers shared across the SDK. */
422
518
  /** SDK identity, embedded in every envelope header. */
423
519
  declare const SDK_NAME = "sauron.javascript";
424
- declare const SDK_VERSION = "1.0.0";
520
+ declare const SDK_VERSION = "1.4.0";
425
521
 
426
522
  /**
427
523
  * `@edraj/sauron-browser` — public API surface.
@@ -452,10 +548,38 @@ declare function trackTransaction(input: TransactionInput): void;
452
548
  declare function setScreen(name: string): void;
453
549
  /** The current screen name, or null. */
454
550
  declare function getScreen(): string | null;
551
+ /**
552
+ * Start a named, explicitly-bounded workflow. `workflow_id` is a fresh
553
+ * client-generated UUID; the id + name are then stamped on every subsequent
554
+ * event/error/transaction until the workflow ends or is cancelled. Optional —
555
+ * an app that never calls this behaves exactly as before.
556
+ */
557
+ declare function startWorkflow(name: string, options?: {
558
+ force?: boolean;
559
+ }): WorkflowResult;
560
+ /** End the active workflow (or the one named `name`, if given). */
561
+ declare function endWorkflow(name?: string): WorkflowResult;
562
+ /** Cancel the active workflow (or the one named `name`, if given). */
563
+ declare function cancelWorkflow(name?: string, options?: {
564
+ reason?: string;
565
+ }): WorkflowResult;
566
+ /** The currently active workflow, or `null` when none is active. */
567
+ declare function getWorkflow(): ActiveWorkflow | null;
455
568
  /** Record a breadcrumb. */
456
569
  declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
457
- /** Set (or clear, with `null`) the current user. */
570
+ /**
571
+ * Set (or clear, with `null`) the current user.
572
+ *
573
+ * `setUser(null)` is a logout, so it also rotates the anonymous id — otherwise
574
+ * the next anonymous visitor on this browser inherits the previous person's
575
+ * durable id and a later identify() aliases them together server-side.
576
+ */
458
577
  declare function setUser(user: UserInput): void;
578
+ /**
579
+ * Forget the current person: clears the scope user and mints a fresh anonymous
580
+ * id. Call this on logout.
581
+ */
582
+ declare function reset(): void;
459
583
  /** Set a single scope tag (lifted onto later errors/events). */
460
584
  declare function setTag(key: string, value: string): void;
461
585
  /** Merge a batch of scope tags (last-write-wins per key). */
@@ -479,15 +603,20 @@ declare const Sauron: {
479
603
  identify: typeof identify;
480
604
  addBreadcrumb: typeof addBreadcrumb;
481
605
  setUser: typeof setUser;
606
+ reset: typeof reset;
482
607
  setTag: typeof setTag;
483
608
  setTags: typeof setTags;
484
609
  setContext: typeof setContext;
485
610
  setExtra: typeof setExtra;
486
611
  setScreen: typeof setScreen;
487
612
  getScreen: typeof getScreen;
613
+ startWorkflow: typeof startWorkflow;
614
+ endWorkflow: typeof endWorkflow;
615
+ cancelWorkflow: typeof cancelWorkflow;
616
+ getWorkflow: typeof getWorkflow;
488
617
  flush: typeof flush;
489
618
  close: typeof close;
490
619
  getClient: typeof getClient;
491
620
  };
492
621
 
493
- export { 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, addBreadcrumb, buildEnvelope, captureException, captureMessage, close, Sauron as default, flush, getClient, getScreen, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, setContext, setExtra, setScreen, setTag, setTags, setUser, track, trackTransaction };
622
+ 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 CHANGED
@@ -24,9 +24,17 @@ interface Mechanism {
24
24
  type: string;
25
25
  handled: boolean;
26
26
  }
27
- /** The exception payload of an error item. */
27
+ /**
28
+ * The exception payload of an error item.
29
+ *
30
+ * `type` is NOT nullable: the backend's `ExceptionInfo.ty` is a non-`Option`
31
+ * `String` with no serde default, so `null` fails to deserialize and the
32
+ * gateway 400s the ENTIRE envelope — every other item in the batch with it.
33
+ * An item with no exception type omits `exception` altogether and carries its
34
+ * text in {@link ErrorItem.message}.
35
+ */
28
36
  interface ExceptionValue {
29
- type: string | null;
37
+ type: string;
30
38
  value: string | null;
31
39
  mechanism: Mechanism;
32
40
  stacktrace: Frame[];
@@ -50,8 +58,14 @@ interface ErrorItem {
50
58
  event_id?: string;
51
59
  timestamp: string;
52
60
  level: Level;
53
- exception: ExceptionValue;
54
- /** Optional human-readable summary alongside the exception. */
61
+ /**
62
+ * The captured exception. OPTIONAL a message capture omits it entirely and
63
+ * carries its text in {@link message} instead (the backend's `exception` is
64
+ * `Option<ExceptionInfo>`, and with no exception it fingerprints off
65
+ * `message`). Never emit a placeholder here just to fill the field.
66
+ */
67
+ exception?: ExceptionValue;
68
+ /** Human-readable summary; the ONLY text carrier when `exception` is absent. */
55
69
  message?: string;
56
70
  breadcrumbs: Breadcrumb[];
57
71
  fingerprint: string[] | null;
@@ -74,6 +88,13 @@ interface ErrorItem {
74
88
  */
75
89
  user?: UserContext | null;
76
90
  session_id?: string | null;
91
+ /**
92
+ * The active workflow this item was stamped with, if any. A pair —
93
+ * always both present or both absent, never one without the other. See
94
+ * {@link ActiveWorkflow}.
95
+ */
96
+ workflow_id?: string;
97
+ workflow_name?: string;
77
98
  screen?: string | null;
78
99
  }
79
100
  /** A product-analytics event (PostHog-style `track`). */
@@ -82,6 +103,13 @@ interface EventItem {
82
103
  name: string;
83
104
  distinct_id: string | null;
84
105
  session_id?: string | null;
106
+ /**
107
+ * The active workflow this item was stamped with, if any. A pair —
108
+ * always both present or both absent, never one without the other. See
109
+ * {@link ActiveWorkflow}.
110
+ */
111
+ workflow_id?: string;
112
+ workflow_name?: string;
85
113
  screen?: string | null;
86
114
  timestamp: string;
87
115
  properties: Record<string, unknown>;
@@ -108,6 +136,13 @@ interface TransactionItem {
108
136
  url?: string | null;
109
137
  distinct_id?: string | null;
110
138
  session_id?: string | null;
139
+ /**
140
+ * The active workflow this item was stamped with, if any. A pair —
141
+ * always both present or both absent, never one without the other. See
142
+ * {@link ActiveWorkflow}.
143
+ */
144
+ workflow_id?: string;
145
+ workflow_name?: string;
111
146
  timestamp: string;
112
147
  }
113
148
  /** An identity association (PostHog-style `identify`). */
@@ -163,7 +198,6 @@ interface EnvelopeHeader {
163
198
  dsn: string;
164
199
  sdk: SdkInfo;
165
200
  sent_at: string;
166
- environment: string;
167
201
  release: string | null;
168
202
  }
169
203
  /** The complete, serializable envelope posted to the ingest gateway. */
@@ -191,6 +225,25 @@ interface CaptureOptions {
191
225
  interface TrackOptions extends CaptureOptions {
192
226
  screen?: string;
193
227
  }
228
+ /**
229
+ * Outcome of `startWorkflow` / `endWorkflow` / `cancelWorkflow`. Telemetry
230
+ * never throws — every call resolves to one of these instead.
231
+ */
232
+ type WorkflowStatus = 'ok' | 'already_active' | 'not_active' | 'name_mismatch' | 'invalid_name' | 'disabled';
233
+ /** Result of a workflow lifecycle call. */
234
+ interface WorkflowResult {
235
+ status: WorkflowStatus;
236
+ /** The workflow id involved, when `status` is `'ok'`. */
237
+ workflowId?: string;
238
+ }
239
+ /** The currently-active workflow, as returned by `getWorkflow()`. */
240
+ interface ActiveWorkflow {
241
+ /** Client-generated UUID — the server rollup key is `(app_id, workflow_id)`. */
242
+ workflowId: string;
243
+ name: string;
244
+ /** ISO-8601 UTC timestamp of `startWorkflow()`. */
245
+ startedAt: string;
246
+ }
194
247
  /** Value accepted by `setUser` — normalized into a `UserContext`. */
195
248
  type UserInput = (Partial<UserContext> & {
196
249
  id?: string | null;
@@ -211,7 +264,6 @@ interface TransportOptions {
211
264
  interface InitOptions {
212
265
  /** `https://<public_key>@<host>/<project_id>` */
213
266
  dsn: string;
214
- environment?: string;
215
267
  release?: string;
216
268
  /** Error sample rate in [0, 1]. Default 1 (send everything). */
217
269
  sampleRate?: number;
@@ -244,7 +296,6 @@ interface InitOptions {
244
296
  /** Fully-resolved options with all defaults applied. */
245
297
  interface ResolvedOptions {
246
298
  dsn: string;
247
- environment: string;
248
299
  release: string | null;
249
300
  sampleRate: number;
250
301
  maxBreadcrumbs: number;
@@ -355,18 +406,46 @@ declare class SauronClient {
355
406
  private readonly nativeFetch?;
356
407
  private enabled;
357
408
  private installed;
358
- private anonymousId;
359
409
  private beaconCleanup;
360
410
  constructor(options: ResolvedOptions);
361
411
  /** Install global handlers + auto-instrumentation and start the transport. */
362
412
  install(): void;
363
413
  getScope(): Scope;
414
+ /**
415
+ * False once this client was explicitly disabled/closed, OR once the
416
+ * transport has auto-disabled itself on a 401/403 (revoked/invalid DSN
417
+ * key) — computed from the transport's own state on every call, not a
418
+ * separately mirrored flag, so a propagation regression there cannot leave
419
+ * this predicate stale. `this.transport` always exists once a client
420
+ * exists (it is constructed synchronously in the constructor); the
421
+ * "nothing installed yet" case is instead handled one layer up, by every
422
+ * module-level API (`startWorkflow`, `track`, ...) treating `getClient() ===
423
+ * null` as the no-op/disabled case before it ever reaches here.
424
+ */
364
425
  isEnabled(): boolean;
426
+ /**
427
+ * Whether the anonymous id has actually been USED as a `distinct_id` in this
428
+ * browser session.
429
+ *
430
+ * A persisted id that has never been observed anonymously must not create a
431
+ * permanent `identities` alias row on the server: aliasing is a durable
432
+ * server-side binding of this browser profile to a named user, and an
433
+ * identify() on a first-ever page load has no anonymous history to link.
434
+ */
435
+ private anonUsed;
365
436
  /** The current distinct id: the user id when identified, else an anon id. */
366
437
  getDistinctId(): string | null;
367
- /** The anonymous id, or null if one was never needed. */
438
+ /** The anonymous id, or null when it was never actually used as an identity. */
368
439
  getAnonymousId(): string | null;
369
- private ensureAnonymousId;
440
+ /**
441
+ * Forget the current person: clear the scope user and mint a fresh anonymous
442
+ * id.
443
+ *
444
+ * MUST BE CALLED ON LOGOUT. Without it, the next anonymous visitor on this
445
+ * browser reuses the persisted anon id, and a later identify() aliases their
446
+ * activity to the previous account server-side, permanently.
447
+ */
448
+ reset(): void;
370
449
  /** Stamp a fresh envelope (new `sent_at`, current context) around `items`. */
371
450
  makeEnvelope(items: EnvelopeItem[]): Envelope;
372
451
  /** Add a breadcrumb, running it through `beforeBreadcrumb` first. */
@@ -379,6 +458,23 @@ declare class SauronClient {
379
458
  * `event_id` is always minted so callers can correlate the report.
380
459
  */
381
460
  private enrichErrorItem;
461
+ /**
462
+ * Stamp the active workflow (if any) onto a signal item.
463
+ *
464
+ * Done HERE — the single choke point every capture path funnels through —
465
+ * rather than at each item-construction site, so a capture path added later
466
+ * is stamped by construction instead of by remembering to. The keys are
467
+ * ASSIGNED ONLY when a workflow is active: an item with no workflow keeps
468
+ * them absent entirely (not present-as-`undefined`), which is what makes
469
+ * `JSON.stringify` omit them and keeps the no-workflow wire bytes identical
470
+ * to pre-1.3.0.
471
+ *
472
+ * Only error/event/transaction carry `workflow_id`/`workflow_name` columns
473
+ * server-side — identify and breadcrumb_batch items are deliberately left
474
+ * alone. An item that already carries an explicit `workflow_id` is left
475
+ * untouched, matching how `enrichErrorItem` defers to caller-set fields.
476
+ */
477
+ private stampWorkflow;
382
478
  /**
383
479
  * Run an item through sampling (errors only) and `beforeSend`, then hand it to
384
480
  * the transport. Returns silently when dropped.
@@ -421,7 +517,7 @@ declare function parseError(err: unknown): Frame[];
421
517
  /** Small dependency-free helpers shared across the SDK. */
422
518
  /** SDK identity, embedded in every envelope header. */
423
519
  declare const SDK_NAME = "sauron.javascript";
424
- declare const SDK_VERSION = "1.0.0";
520
+ declare const SDK_VERSION = "1.4.0";
425
521
 
426
522
  /**
427
523
  * `@edraj/sauron-browser` — public API surface.
@@ -452,10 +548,38 @@ declare function trackTransaction(input: TransactionInput): void;
452
548
  declare function setScreen(name: string): void;
453
549
  /** The current screen name, or null. */
454
550
  declare function getScreen(): string | null;
551
+ /**
552
+ * Start a named, explicitly-bounded workflow. `workflow_id` is a fresh
553
+ * client-generated UUID; the id + name are then stamped on every subsequent
554
+ * event/error/transaction until the workflow ends or is cancelled. Optional —
555
+ * an app that never calls this behaves exactly as before.
556
+ */
557
+ declare function startWorkflow(name: string, options?: {
558
+ force?: boolean;
559
+ }): WorkflowResult;
560
+ /** End the active workflow (or the one named `name`, if given). */
561
+ declare function endWorkflow(name?: string): WorkflowResult;
562
+ /** Cancel the active workflow (or the one named `name`, if given). */
563
+ declare function cancelWorkflow(name?: string, options?: {
564
+ reason?: string;
565
+ }): WorkflowResult;
566
+ /** The currently active workflow, or `null` when none is active. */
567
+ declare function getWorkflow(): ActiveWorkflow | null;
455
568
  /** Record a breadcrumb. */
456
569
  declare function addBreadcrumb(breadcrumb: BreadcrumbInput, hint?: Hint): void;
457
- /** Set (or clear, with `null`) the current user. */
570
+ /**
571
+ * Set (or clear, with `null`) the current user.
572
+ *
573
+ * `setUser(null)` is a logout, so it also rotates the anonymous id — otherwise
574
+ * the next anonymous visitor on this browser inherits the previous person's
575
+ * durable id and a later identify() aliases them together server-side.
576
+ */
458
577
  declare function setUser(user: UserInput): void;
578
+ /**
579
+ * Forget the current person: clears the scope user and mints a fresh anonymous
580
+ * id. Call this on logout.
581
+ */
582
+ declare function reset(): void;
459
583
  /** Set a single scope tag (lifted onto later errors/events). */
460
584
  declare function setTag(key: string, value: string): void;
461
585
  /** Merge a batch of scope tags (last-write-wins per key). */
@@ -479,15 +603,20 @@ declare const Sauron: {
479
603
  identify: typeof identify;
480
604
  addBreadcrumb: typeof addBreadcrumb;
481
605
  setUser: typeof setUser;
606
+ reset: typeof reset;
482
607
  setTag: typeof setTag;
483
608
  setTags: typeof setTags;
484
609
  setContext: typeof setContext;
485
610
  setExtra: typeof setExtra;
486
611
  setScreen: typeof setScreen;
487
612
  getScreen: typeof getScreen;
613
+ startWorkflow: typeof startWorkflow;
614
+ endWorkflow: typeof endWorkflow;
615
+ cancelWorkflow: typeof cancelWorkflow;
616
+ getWorkflow: typeof getWorkflow;
488
617
  flush: typeof flush;
489
618
  close: typeof close;
490
619
  getClient: typeof getClient;
491
620
  };
492
621
 
493
- export { 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, addBreadcrumb, buildEnvelope, captureException, captureMessage, close, Sauron as default, flush, getClient, getScreen, identify, init, isInAppFrame, parseDsn, parseError, parseStackString, setContext, setExtra, setScreen, setTag, setTags, setUser, track, trackTransaction };
622
+ 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 };