@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/CHANGELOG.md +72 -0
- package/README.md +1008 -53
- package/dist/index.cjs +285 -23
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +142 -13
- package/dist/index.d.ts +142 -13
- package/dist/index.js +281 -24
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -24,9 +24,17 @@ interface Mechanism {
|
|
|
24
24
|
type: string;
|
|
25
25
|
handled: boolean;
|
|
26
26
|
}
|
|
27
|
-
/**
|
|
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
|
|
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
|
-
|
|
54
|
-
|
|
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
|
|
438
|
+
/** The anonymous id, or null when it was never actually used as an identity. */
|
|
368
439
|
getAnonymousId(): string | null;
|
|
369
|
-
|
|
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.
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
|
|
54
|
-
|
|
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
|
|
438
|
+
/** The anonymous id, or null when it was never actually used as an identity. */
|
|
368
439
|
getAnonymousId(): string | null;
|
|
369
|
-
|
|
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.
|
|
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
|
-
/**
|
|
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 };
|