@starko-one/sdk 0.0.0-stage → 0.1.0-beta.1
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 +248 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-BAFm4Lxj.d.ts +558 -0
- package/dist/api-DNrctwJu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-2PM4FRM5.cjs +431 -0
- package/dist/chunk-335HNCOJ.js +249 -0
- package/dist/chunk-3AW5B2WW.js +115 -0
- package/dist/chunk-3R5TQAWD.js +216 -0
- package/dist/chunk-6H5MOPTQ.cjs +1230 -0
- package/dist/chunk-7TKNT3QJ.cjs +2487 -0
- package/dist/chunk-A4WLNFMU.cjs +220 -0
- package/dist/chunk-ALYFFOPR.cjs +134 -0
- package/dist/chunk-BVVFVRMO.js +1113 -0
- package/dist/chunk-CIHNKN62.cjs +15 -0
- package/dist/chunk-CMGCH6HD.js +1212 -0
- package/dist/chunk-D6QAPQ7L.cjs +56 -0
- package/dist/chunk-DUO5V6WZ.js +213 -0
- package/dist/chunk-EC2WZ6PG.js +90 -0
- package/dist/chunk-EFURLFJT.cjs +187 -0
- package/dist/chunk-EROUORMY.js +53 -0
- package/dist/chunk-LXBXFOAP.cjs +96 -0
- package/dist/chunk-MF6SA6DB.js +563 -0
- package/dist/chunk-N5R6ORIB.js +413 -0
- package/dist/chunk-N6R6BWHK.cjs +142 -0
- package/dist/chunk-QAGGN2T7.cjs +225 -0
- package/dist/chunk-QV4HRIDD.cjs +659 -0
- package/dist/chunk-TKNDYQB3.cjs +583 -0
- package/dist/chunk-UI5YC4TH.js +131 -0
- package/dist/chunk-VEHZYLK6.cjs +1151 -0
- package/dist/chunk-VNCWOGTI.js +12 -0
- package/dist/chunk-VWNIOGE6.js +180 -0
- package/dist/chunk-WDKRKGYF.js +608 -0
- package/dist/chunk-XOZIXBUK.js +2462 -0
- package/dist/chunk-ZS3K3SDR.cjs +258 -0
- package/dist/cli/index.cjs +2780 -0
- package/dist/common-DLFAqL2d.d.cts +36 -0
- package/dist/common-DbSXkaw6.d.ts +36 -0
- package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
- package/dist/dedupe-DoYiSx-9.d.ts +13 -0
- package/dist/handler-BcnsnvhF.d.cts +82 -0
- package/dist/handler-qHzilC9T.d.ts +82 -0
- package/dist/index.cjs +309 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +277 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +263 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-BUhWuWJX.d.cts +79 -0
- package/dist/options-BUhWuWJX.d.ts +79 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-D1ouJm2h.d.cts +628 -0
- package/dist/scope-D1ouJm2h.d.ts +628 -0
- package/dist/server-edge-7624N3WF.cjs +51 -0
- package/dist/server-edge-BEEXWL7T.js +48 -0
- package/dist/server-node-ET4LIPEC.cjs +27 -0
- package/dist/server-node-TQUVMZUC.js +24 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
- package/dist/session-propagation-RM5py1bp.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +386 -0
- package/docs/configuration.md +310 -0
- package/docs/nextjs.md +488 -0
- package/docs/node.md +427 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +482 -0
- package/docs/troubleshooting.md +263 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +547 -0
- package/package.json +191 -4
|
@@ -0,0 +1,558 @@
|
|
|
1
|
+
import { W as WireEvent, M as Mechanism, L as Level, B as Breadcrumb, k as Platform, F as FramePlatform, $ as WireEnvelope, R as RemoteConfig, a as WireUser, S as Scope } from './scope-D1ouJm2h.cjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Core types shared by every platform. Environment-free: nothing here
|
|
5
|
+
* references the DOM or Node.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** A parsed stack frame before the platform fields are added. */
|
|
9
|
+
interface ParsedFrame {
|
|
10
|
+
filename?: string;
|
|
11
|
+
function?: string;
|
|
12
|
+
lineno?: number;
|
|
13
|
+
colno?: number;
|
|
14
|
+
}
|
|
15
|
+
/** Turns one line of a stack into a frame, or undefined when the line is not a frame. */
|
|
16
|
+
type StackLineParser = (line: string) => ParsedFrame | undefined;
|
|
17
|
+
/** Turns a whole `error.stack` into frames, MOST RECENT CALL FIRST (the order the string already has). */
|
|
18
|
+
type StackParser = (stack: string, skipFirst?: number) => ParsedFrame[];
|
|
19
|
+
/** Extra information about a captured value. Everything is optional. */
|
|
20
|
+
interface EventHint {
|
|
21
|
+
/** How the error was caught. Defaults to `{ type: "generic", handled: true }`. */
|
|
22
|
+
mechanism?: Partial<Mechanism>;
|
|
23
|
+
/** The value that was thrown (filled by the client). */
|
|
24
|
+
originalException?: unknown;
|
|
25
|
+
/** An `Error` created at the capture site; its stack is used when the thrown value has none. */
|
|
26
|
+
syntheticException?: Error;
|
|
27
|
+
/** Frames to drop from the top of `syntheticException.stack` (the SDK's own frames). */
|
|
28
|
+
syntheticSkip?: number;
|
|
29
|
+
/** Event level; defaults to "error" (captureException) or the message level. */
|
|
30
|
+
level?: Level;
|
|
31
|
+
/** Merged into the event's tags / extra / contexts. */
|
|
32
|
+
tags?: Record<string, string>;
|
|
33
|
+
extra?: Record<string, unknown>;
|
|
34
|
+
contexts?: Record<string, Record<string, unknown>>;
|
|
35
|
+
fingerprint?: string;
|
|
36
|
+
/** Free-form data an integration may read (e.g. the DOM event). */
|
|
37
|
+
data?: Record<string, unknown>;
|
|
38
|
+
}
|
|
39
|
+
interface Integration {
|
|
40
|
+
name: string;
|
|
41
|
+
/** Called once per client, after options are resolved. Install hooks here. */
|
|
42
|
+
setup?(client: Client): void;
|
|
43
|
+
/** Runs for every event before `beforeSend`; return null to drop it. */
|
|
44
|
+
processEvent?(event: WireEvent, hint: EventHint, client: Client): WireEvent | null;
|
|
45
|
+
/** Undo `setup` (tests, `close()`, remote config disabled). */
|
|
46
|
+
teardown?(): void;
|
|
47
|
+
}
|
|
48
|
+
/** What a transport reports back. `status` 0 means the request never got an HTTP answer. */
|
|
49
|
+
interface TransportResult {
|
|
50
|
+
status: number;
|
|
51
|
+
/** Seconds from a `Retry-After` header. */
|
|
52
|
+
retryAfter?: number;
|
|
53
|
+
/** `data.reason` of a JSON ingest response (`IngestRejectReason`), when the body had one. */
|
|
54
|
+
reason?: string;
|
|
55
|
+
/** A 3xx answer's `Location` (never followed), for the warning that names it. */
|
|
56
|
+
location?: string;
|
|
57
|
+
}
|
|
58
|
+
interface TransportSendOptions {
|
|
59
|
+
/** The page is going away: use `fetch({ keepalive })` and respect its body budget. */
|
|
60
|
+
keepalive?: boolean;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Sends one envelope; never rejects (failures resolve to `{ status: 0 }`).
|
|
64
|
+
* Batching, retries and back-off live in the client's queue (core/queue.ts),
|
|
65
|
+
* so a transport is a single HTTP call.
|
|
66
|
+
*/
|
|
67
|
+
interface Transport {
|
|
68
|
+
send(envelope: WireEnvelope, opts?: TransportSendOptions): Promise<TransportResult>;
|
|
69
|
+
/** GET the remote config (`data` of the response), or null when it could not be read. */
|
|
70
|
+
fetchConfig?(): Promise<Partial<RemoteConfig> | null>;
|
|
71
|
+
/**
|
|
72
|
+
* Abort every request in flight (they resolve as network failures). The
|
|
73
|
+
* shutdown paths call it when their deadline passes: a connection attempt
|
|
74
|
+
* still pending would otherwise keep the process alive until it times out.
|
|
75
|
+
*/
|
|
76
|
+
abort?(): void;
|
|
77
|
+
}
|
|
78
|
+
interface TransportOptions {
|
|
79
|
+
host: string;
|
|
80
|
+
workspaceKey: string;
|
|
81
|
+
/** Deadline per request, ms (`requestTimeoutMs`); the transport's default when undefined. */
|
|
82
|
+
timeoutMs?: number;
|
|
83
|
+
}
|
|
84
|
+
/** Options common to every platform's `init()`. */
|
|
85
|
+
interface Options {
|
|
86
|
+
/** Workspace key (public): the workspace id shown in Starko under Settings. Required. */
|
|
87
|
+
workspaceKey: string;
|
|
88
|
+
/** Starko host. Default https://v2.starko.one. */
|
|
89
|
+
host?: string;
|
|
90
|
+
/** App version; must match the release the source maps were uploaded for. Default: the build-injected `globalThis._starkoRelease`. */
|
|
91
|
+
release?: string;
|
|
92
|
+
environment?: string;
|
|
93
|
+
/** False: capture nothing. Default true. */
|
|
94
|
+
enabled?: boolean;
|
|
95
|
+
/** Log SDK internals (and internal failures) to the console. */
|
|
96
|
+
debug?: boolean;
|
|
97
|
+
/** 0..1 share of events to send. Default 1. */
|
|
98
|
+
sampleRate?: number;
|
|
99
|
+
/** Breadcrumbs kept (max 50). Default 50. */
|
|
100
|
+
maxBreadcrumbs?: number;
|
|
101
|
+
/** Last step before an event is queued; return null to drop it. May return a promise. */
|
|
102
|
+
beforeSend?: (event: WireEvent, hint: EventHint) => WireEvent | null | PromiseLike<WireEvent | null>;
|
|
103
|
+
/** Edit or drop (null) a breadcrumb before it is stored. */
|
|
104
|
+
beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: Record<string, unknown>) => Breadcrumb | null;
|
|
105
|
+
/** Drop events whose message (`Type: value` or `value`) contains a string or matches a RegExp. */
|
|
106
|
+
ignoreErrors?: Array<string | RegExp>;
|
|
107
|
+
/** Only send events whose most recent frame's file matches one of these. */
|
|
108
|
+
allowUrls?: Array<string | RegExp>;
|
|
109
|
+
/** Drop events whose most recent frame's file matches one of these. */
|
|
110
|
+
denyUrls?: Array<string | RegExp>;
|
|
111
|
+
/** Added to (array) or replacing (function receiving the defaults) the default integrations. */
|
|
112
|
+
integrations?: Integration[] | ((defaults: Integration[]) => Integration[]);
|
|
113
|
+
/** `false`: no default integrations. */
|
|
114
|
+
defaultIntegrations?: false | Integration[];
|
|
115
|
+
/** Custom transport factory (tests, proxies). */
|
|
116
|
+
transport?: (options: TransportOptions) => Transport;
|
|
117
|
+
/** Read the workspace's remote config at start. Default true. */
|
|
118
|
+
remoteConfig?: boolean;
|
|
119
|
+
/** The signed-in user. */
|
|
120
|
+
user?: WireUser | null;
|
|
121
|
+
/** HMAC of the user's identifier, computed by your backend (see identity in docs/wire-format.md). */
|
|
122
|
+
userHash?: string;
|
|
123
|
+
/**
|
|
124
|
+
* Cap on events for the lifetime of the page. Default 100 in browsers;
|
|
125
|
+
* none on servers (Node, Edge), where `maxEventsPerMinute` bounds floods.
|
|
126
|
+
*/
|
|
127
|
+
maxEventsPerLifetime?: number;
|
|
128
|
+
/**
|
|
129
|
+
* Events sent in any 60 s window, all error types together. Default 300
|
|
130
|
+
* on servers (a crash loop throwing many different errors), none in
|
|
131
|
+
* browsers. On top of the per-type token bucket (10 at once, then one
|
|
132
|
+
* every 10 s per error type) that applies everywhere.
|
|
133
|
+
*/
|
|
134
|
+
maxEventsPerMinute?: number;
|
|
135
|
+
/**
|
|
136
|
+
* An async `beforeSend` (or the Node source-line read before it) that has
|
|
137
|
+
* not settled after this long is abandoned and its event dropped, so
|
|
138
|
+
* `flush()` and `wrapHandler` never wait on it. Default 5000 ms.
|
|
139
|
+
*/
|
|
140
|
+
beforeSendTimeoutMs?: number;
|
|
141
|
+
/** Events kept in memory while waiting to be sent. Default 100 in browsers, 500 on servers. */
|
|
142
|
+
maxQueueSize?: number;
|
|
143
|
+
/** Delay before a partial batch is sent (ms). Default 1000. */
|
|
144
|
+
flushInterval?: number;
|
|
145
|
+
/**
|
|
146
|
+
* A request to Starko that has not answered after this long is aborted and
|
|
147
|
+
* counts as a network failure (retried like one). Default 12 000 ms in the
|
|
148
|
+
* browser.
|
|
149
|
+
*/
|
|
150
|
+
requestTimeoutMs?: number;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* What a platform adds when it builds a client. Not part of the public
|
|
154
|
+
* options: `@starko-one/sdk/browser` and `/node` fill these in.
|
|
155
|
+
*/
|
|
156
|
+
interface PlatformOptions {
|
|
157
|
+
platform: Platform;
|
|
158
|
+
framePlatform: FramePlatform;
|
|
159
|
+
sdkName: string;
|
|
160
|
+
sdkVersion?: string;
|
|
161
|
+
stackParser: StackParser;
|
|
162
|
+
/**
|
|
163
|
+
* Decides `in_app` for a frame's filename. Return undefined when the SDK
|
|
164
|
+
* cannot know (a minified bundle may hold app and library code): the field
|
|
165
|
+
* is then omitted and the server decides after source-map resolution.
|
|
166
|
+
* Without a rule `in_app` is never sent.
|
|
167
|
+
*/
|
|
168
|
+
isInApp?: (filename: string | undefined) => boolean | undefined;
|
|
169
|
+
/** The session id to stamp on events (browser: widget recorder or minted id). */
|
|
170
|
+
getSessionId?: () => string | undefined;
|
|
171
|
+
transport: (options: TransportOptions) => Transport;
|
|
172
|
+
/** How long sending pauses after repeated failed batches, ms. Default 5 minutes. */
|
|
173
|
+
failurePauseMs?: number;
|
|
174
|
+
/** Platform default for `maxQueueSize` (browser 100, servers 500). */
|
|
175
|
+
defaultMaxQueueSize?: number;
|
|
176
|
+
/** Platform default for `maxEventsPerLifetime` (browser 100, servers none). */
|
|
177
|
+
defaultMaxEventsPerLifetime?: number;
|
|
178
|
+
/** Platform default for `maxEventsPerMinute` (servers 300, browser none). */
|
|
179
|
+
defaultMaxEventsPerMinute?: number;
|
|
180
|
+
}
|
|
181
|
+
type ClientOptions = Options & PlatformOptions;
|
|
182
|
+
|
|
183
|
+
/** This package's version (package.json, inlined at build time): `sdk.version` on every event. */
|
|
184
|
+
declare const SDK_VERSION: string;
|
|
185
|
+
/**
|
|
186
|
+
* UUID v4: `crypto.randomUUID` when available (secure contexts only), else
|
|
187
|
+
* `crypto.getRandomValues` (also on plain-http pages), else Math.random (ids
|
|
188
|
+
* only need to be unique, not secret).
|
|
189
|
+
*/
|
|
190
|
+
declare function uuid4(): string;
|
|
191
|
+
/** Console logger enabled by `debug`. Uses the console captured at load, before any breadcrumb patch. */
|
|
192
|
+
interface Logger {
|
|
193
|
+
enabled: boolean;
|
|
194
|
+
log(...args: unknown[]): void;
|
|
195
|
+
warn(...args: unknown[]): void;
|
|
196
|
+
/**
|
|
197
|
+
* A warning printed whatever `debug` says, once per `key` for this logger:
|
|
198
|
+
* for what the user must know and fix (events dropped by a limit, a host
|
|
199
|
+
* that redirects). Never pass a credential.
|
|
200
|
+
*/
|
|
201
|
+
alert(key: string, ...args: unknown[]): void;
|
|
202
|
+
}
|
|
203
|
+
declare function createLogger(enabled?: boolean): Logger;
|
|
204
|
+
/**
|
|
205
|
+
* Run `fn`, swallowing anything it throws (logged through `logger`), and
|
|
206
|
+
* return `fallback` instead. The guard every SDK entry point goes through.
|
|
207
|
+
*/
|
|
208
|
+
declare function safely<T>(logger: Logger | undefined, what: string, fn: () => T, fallback: T): T;
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* The send queue: the transport helper every platform shares. Events are
|
|
212
|
+
* batched (≤ `LIMITS.MAX_EVENTS_PER_ENVELOPE`, ≤ `LIMITS.MAX_BODY_BYTES`),
|
|
213
|
+
* sent one request at a time, and the response decides what happens next
|
|
214
|
+
* (docs/wire-format.md, "Responses"):
|
|
215
|
+
*
|
|
216
|
+
* | 2xx | done |
|
|
217
|
+
* | 3xx | dropped: a redirect is never followed (it would turn |
|
|
218
|
+
* | | the POST into a GET and send the key elsewhere); the |
|
|
219
|
+
* | | first one is logged with its `Location`, always |
|
|
220
|
+
* | 401 / 403 with `reason` unknown_workspace, disabled, origin_not_allowed |
|
|
221
|
+
* | | stop: drop everything, disable the client |
|
|
222
|
+
* | 401 / 403 `invalid` | drop (wrong or revoked secret key), say so once |
|
|
223
|
+
* | 413 | halve the batch and retry once; a failing half is dropped |
|
|
224
|
+
* | 429 `quota` | drop the batch, send nothing until `Retry-After` |
|
|
225
|
+
* | other 4xx (400, …) | drop the batch |
|
|
226
|
+
* | 0, 408, 429, 5xx, and 401 / 403 WITHOUT an explicit reason (a proxy, a |
|
|
227
|
+
* | captive portal) | retry: back-off with jitter, at least `Retry-After`, |
|
|
228
|
+
* | | at most `maxAttempts` (3) attempts per batch |
|
|
229
|
+
*
|
|
230
|
+
* A request that has not settled after `sendTimeoutMs` counts as a network
|
|
231
|
+
* failure (status 0), so one hung request never holds the queue.
|
|
232
|
+
*
|
|
233
|
+
* After `pauseAfter` (3) batches in a row are given up, sending pauses for
|
|
234
|
+
* `failurePauseMs` (default 5 minutes); `resume()` ends the pause early (the
|
|
235
|
+
* browser calls it on `online`). The queue is bounded: past `maxQueueSize`
|
|
236
|
+
* the oldest events are dropped. Retries are safe because the server counts
|
|
237
|
+
* an `event_id` once; `sent_at` is stamped per attempt.
|
|
238
|
+
*
|
|
239
|
+
* `gate` (servers): awaited before the first request of every send loop;
|
|
240
|
+
* the client uses it to read the remote config only when there is something
|
|
241
|
+
* to send. A gate that disables the queue drops what is unsent.
|
|
242
|
+
*
|
|
243
|
+
* Every batch the queue gives up on (dropped or out of attempts) makes the
|
|
244
|
+
* `flush` that was waiting for it resolve false.
|
|
245
|
+
*
|
|
246
|
+
* A keepalive flush (the page is going away) starts every request in the
|
|
247
|
+
* caller's synchronous turn, in parallel, without waiting for a request in
|
|
248
|
+
* flight; the events of a request in flight are sent again with keepalive,
|
|
249
|
+
* because the browser cancels an ordinary request when the page unloads. A
|
|
250
|
+
* duplicate is harmless (the server deduplicates by `event_id`); a loss is not.
|
|
251
|
+
*/
|
|
252
|
+
|
|
253
|
+
interface QueueOptions {
|
|
254
|
+
transport: Transport;
|
|
255
|
+
/** Wraps a batch in an envelope (`sent_at` is stamped per attempt). */
|
|
256
|
+
envelope(events: WireEvent[]): WireEnvelope;
|
|
257
|
+
logger?: Logger;
|
|
258
|
+
/** Default 100. */
|
|
259
|
+
maxQueueSize?: number;
|
|
260
|
+
/** Delay before a partial batch goes out, ms. Default 1000. */
|
|
261
|
+
flushInterval?: number;
|
|
262
|
+
/** Attempts per batch for retryable failures (the first included). Default 3. */
|
|
263
|
+
maxAttempts?: number;
|
|
264
|
+
/** Batches given up in a row before sending pauses. Default 3. */
|
|
265
|
+
pauseAfter?: number;
|
|
266
|
+
/** How long sending pauses after repeated failures, ms. Default 5 minutes. */
|
|
267
|
+
failurePauseMs?: number;
|
|
268
|
+
/** Default 1000 ms, doubled per attempt. */
|
|
269
|
+
backoffMs?: number;
|
|
270
|
+
/** Default 60 000 ms. */
|
|
271
|
+
maxBackoffMs?: number;
|
|
272
|
+
/** A request not settled after this long counts as a network failure. Default 30 000 ms. */
|
|
273
|
+
sendTimeoutMs?: number;
|
|
274
|
+
/** Called once when the server says the key is unknown or the workspace is off. */
|
|
275
|
+
onDisable?(status: number): void;
|
|
276
|
+
/** Awaited before the first request of a send loop (never rejects). */
|
|
277
|
+
gate?(): Promise<void>;
|
|
278
|
+
/** Test seam for jitter. */
|
|
279
|
+
random?(): number;
|
|
280
|
+
}
|
|
281
|
+
declare class EventQueue {
|
|
282
|
+
private items;
|
|
283
|
+
private timer;
|
|
284
|
+
/** The sequential send loop. */
|
|
285
|
+
private running;
|
|
286
|
+
/** Every request in flight. */
|
|
287
|
+
private sends;
|
|
288
|
+
/** Batches in flight without keepalive (a page-hide flush sends them again). */
|
|
289
|
+
private flying;
|
|
290
|
+
/** 429: nothing goes out before this time. */
|
|
291
|
+
private retryAt;
|
|
292
|
+
/** 5xx / network: back-off; a hide-time flush ignores it (last chance). */
|
|
293
|
+
private backoffUntil;
|
|
294
|
+
/** Repeated failures: nothing goes out before this time. */
|
|
295
|
+
private pausedUntil;
|
|
296
|
+
/** Batches given up in a row. */
|
|
297
|
+
private failures;
|
|
298
|
+
private disabled;
|
|
299
|
+
/** Batches given up on (dropped, out of attempts) since the queue started. */
|
|
300
|
+
private dropped;
|
|
301
|
+
private o;
|
|
302
|
+
constructor(opts: QueueOptions);
|
|
303
|
+
get size(): number;
|
|
304
|
+
/** A request is in flight. */
|
|
305
|
+
get isSending(): boolean;
|
|
306
|
+
get isDisabled(): boolean;
|
|
307
|
+
/** Waiting out a 429, a back-off or a failure pause: a flush now would send nothing. */
|
|
308
|
+
get isBlocked(): boolean;
|
|
309
|
+
/** Keep only the unsent events `keep` accepts (a remote config that arrived after they were queued). */
|
|
310
|
+
filter(keep: (event: WireEvent) => boolean): void;
|
|
311
|
+
/** Queue an event. One that cannot be serialised is dropped here, alone, instead of spoiling the batch it would travel in. */
|
|
312
|
+
add(event: WireEvent): void;
|
|
313
|
+
/** Drop everything and stop accepting events. */
|
|
314
|
+
disable(): void;
|
|
315
|
+
/** Send nothing for `ms` (a shutdown gave up: no new connection attempt may keep the process alive). */
|
|
316
|
+
holdOff(ms: number): void;
|
|
317
|
+
/** End a failure pause or back-off now (the network is back). A 429 `Retry-After` still holds. */
|
|
318
|
+
resume(): void;
|
|
319
|
+
/**
|
|
320
|
+
* Send everything now. Resolves true when the queue is empty and nothing
|
|
321
|
+
* is in flight within `timeoutMs`. With `keepalive` the requests are made
|
|
322
|
+
* for a page that is going away: all of them start before this returns
|
|
323
|
+
* (back-off is ignored, 429 and a failure pause are not).
|
|
324
|
+
*/
|
|
325
|
+
flush(timeoutMs?: number, keepalive?: boolean): Promise<boolean>;
|
|
326
|
+
private bound;
|
|
327
|
+
private blockedFor;
|
|
328
|
+
private clearTimer;
|
|
329
|
+
private schedule;
|
|
330
|
+
/** The sequential loop: one request at a time until the queue is empty or blocked. */
|
|
331
|
+
private drain;
|
|
332
|
+
/** Page going away: every batch, and the events of requests in flight, leave now with keepalive. */
|
|
333
|
+
private sendAll;
|
|
334
|
+
private take;
|
|
335
|
+
/** One request. The transport is called synchronously; resolves with `handle`'s verdict (false stops a loop). */
|
|
336
|
+
private send;
|
|
337
|
+
/** Items of `batch` that may go again: not delivered, not already back in the queue. */
|
|
338
|
+
private requeue;
|
|
339
|
+
/** Applies a response; false stops the current loop. */
|
|
340
|
+
private handle;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* The client: options, integrations, the event pipeline and the queue.
|
|
345
|
+
*
|
|
346
|
+
* Pipeline (docs/architecture.md), in this order:
|
|
347
|
+
* build → scope data applied → integrations' `processEvent` →
|
|
348
|
+
* `ignoreErrors` / `allowUrls` / `denyUrls` → remote suppression rules →
|
|
349
|
+
* sample rate (option × remote) → rate limiter → `beforeSend` → trim → queue.
|
|
350
|
+
* The rate limits (per-type bucket, per-minute budget, lifetime cap) are
|
|
351
|
+
* checked before `beforeSend` and spent only for events that reach the
|
|
352
|
+
* queue. Drops are reported whatever `debug` says (rate limits at most once a minute each).
|
|
353
|
+
*
|
|
354
|
+
* Remote config, `eager` mode (browsers): read at `init`; events that passed
|
|
355
|
+
* the local steps wait (at most `MAX_PENDING`) and continue once it arrives;
|
|
356
|
+
* a config that says `enabled: false` tears the integrations down and drops
|
|
357
|
+
* them. A page-hide flush does not wait: held events continue as if the
|
|
358
|
+
* config were the default (enabled).
|
|
359
|
+
*
|
|
360
|
+
* `lazy` mode (servers, `ServerClient` in src/node/server-client.ts):
|
|
361
|
+
* nothing is read at `init` (an idle process or a short script makes no
|
|
362
|
+
* request). Events are queued at once as if the config were the default;
|
|
363
|
+
* the queue reads the config just before its first request, and what it
|
|
364
|
+
* says applies to what is still unsent (`enabled: false` drops it and
|
|
365
|
+
* switches the client off).
|
|
366
|
+
*
|
|
367
|
+
* An async `beforeSend` that has not settled after `beforeSendTimeoutMs` is
|
|
368
|
+
* abandoned (its event dropped), and at most `MAX_INFLIGHT` run at once.
|
|
369
|
+
*
|
|
370
|
+
* Every public method is guarded: nothing the client does throws into the
|
|
371
|
+
* caller, whatever the arguments (`null` hints, proxies, throwing getters).
|
|
372
|
+
*/
|
|
373
|
+
|
|
374
|
+
declare class Client {
|
|
375
|
+
readonly options: ClientOptions;
|
|
376
|
+
readonly logger: Logger;
|
|
377
|
+
readonly transport: Transport;
|
|
378
|
+
protected readonly queue: EventQueue;
|
|
379
|
+
private readonly limiter;
|
|
380
|
+
private integrations;
|
|
381
|
+
private state;
|
|
382
|
+
protected remote: RemoteConfig | null;
|
|
383
|
+
private remoteReady;
|
|
384
|
+
private pending;
|
|
385
|
+
/** Async `beforeSend` results not settled yet: `flush()` waits for them. */
|
|
386
|
+
private inflight;
|
|
387
|
+
/** Rate-limit drops per limit, for the log line (see `limitDrop`). */
|
|
388
|
+
private drops;
|
|
389
|
+
constructor(options: ClientOptions);
|
|
390
|
+
/** Starts the client: integrations, remote config. Called once by the platform `init()`. */
|
|
391
|
+
init(integrations: Integration[]): this;
|
|
392
|
+
isEnabled(): boolean;
|
|
393
|
+
getIntegration<T extends Integration = Integration>(name: string): T | undefined;
|
|
394
|
+
/** The session id stamped on events (browser: the widget recorder's, or minted). */
|
|
395
|
+
getSessionId(): string | undefined;
|
|
396
|
+
/** The remote config once loaded (`null` while loading). */
|
|
397
|
+
getRemoteConfig(): RemoteConfig | null;
|
|
398
|
+
/** Capture a thrown value. Returns the event id (the earlier id when this error was already captured). */
|
|
399
|
+
captureException(exception: unknown, hint?: EventHint, scope?: Scope): string;
|
|
400
|
+
/** Capture a message (an exception of type "Message", with the caller's stack). */
|
|
401
|
+
captureMessage(message: string, level?: Level, hint?: EventHint, scope?: Scope): string;
|
|
402
|
+
/**
|
|
403
|
+
* Send a ready-made event (other platforms, custom producers). Missing
|
|
404
|
+
* `event_id` / `timestamp` / `platform` / `level` are filled in.
|
|
405
|
+
*/
|
|
406
|
+
captureEvent(event: Partial<WireEvent> & Pick<WireEvent, "exception_list">, hint?: EventHint, scope?: Scope): string;
|
|
407
|
+
addBreadcrumb(breadcrumb: Breadcrumb, hint?: Record<string, unknown>, scope?: Scope): void;
|
|
408
|
+
/**
|
|
409
|
+
* True while an event is on its way: waiting for the remote config, in an
|
|
410
|
+
* async `beforeSend`, or queued. Lets a server skip a flush that has
|
|
411
|
+
* nothing to send.
|
|
412
|
+
*/
|
|
413
|
+
hasPending(): boolean;
|
|
414
|
+
/**
|
|
415
|
+
* Send what is queued. True when everything went out within `timeoutMs`.
|
|
416
|
+
* With `keepalive` (the page is going away) the requests start before this
|
|
417
|
+
* returns, in the caller's turn: events held for the remote config are
|
|
418
|
+
* released as if the config were the default, and nothing waits for a
|
|
419
|
+
* request already in flight.
|
|
420
|
+
*/
|
|
421
|
+
flush(timeoutMs?: number, keepalive?: boolean): Promise<boolean>;
|
|
422
|
+
/** End a pause after repeated send failures (the browser calls it when the network is back). */
|
|
423
|
+
resume(): void;
|
|
424
|
+
/** Flush, then remove every hook. The client sends nothing afterwards. */
|
|
425
|
+
close(timeoutMs?: number): Promise<boolean>;
|
|
426
|
+
/** The guarded body of `captureException` / `captureMessage`; `syn` was made in the public method (skip 1 drops its frame). */
|
|
427
|
+
private capture;
|
|
428
|
+
private buildContext;
|
|
429
|
+
private baseEvent;
|
|
430
|
+
private envelope;
|
|
431
|
+
/** Steps up to the URL filters (synchronous), then the rest. */
|
|
432
|
+
private process;
|
|
433
|
+
private localFilter;
|
|
434
|
+
/** Remote suppression → sample rate → rate limiter → beforeSend → trim → queue. */
|
|
435
|
+
private finish;
|
|
436
|
+
/**
|
|
437
|
+
* An event a rate limit dropped. Said whatever `debug` says, at most once
|
|
438
|
+
* a minute per limit: the first drop at once, then how many were dropped
|
|
439
|
+
* since the previous line, naming the key of the drop that prints it.
|
|
440
|
+
*/
|
|
441
|
+
private limitDrop;
|
|
442
|
+
/** A line printed whatever `debug` says (no credential ever goes in). */
|
|
443
|
+
protected notice(...args: unknown[]): void;
|
|
444
|
+
/** What the queue awaits before its first request (servers: the lazy remote config). None here. */
|
|
445
|
+
protected configGate(): (() => Promise<void>) | undefined;
|
|
446
|
+
/** Eager mode: read at `init`, events held until it arrives. Servers override it (src/node/server-client.ts). */
|
|
447
|
+
protected loadRemoteConfig(): void;
|
|
448
|
+
/** GET the remote config (given up after `ms`: enabled, defaults) and `apply` it. Never rejects. */
|
|
449
|
+
protected readConfig(ms: number, apply: (rc: RemoteConfig) => void): Promise<void>;
|
|
450
|
+
/** Page going away before the remote config arrived: held events continue as if it were the default (enabled). */
|
|
451
|
+
private release;
|
|
452
|
+
protected applyRemoteConfig(rc: RemoteConfig): void;
|
|
453
|
+
/** Off for good (remote config disabled, 401/403): no hooks, nothing queued. */
|
|
454
|
+
protected shutdown(reason: string): void;
|
|
455
|
+
/** Last set up, first torn down: an integration that wrapped a function another one wrapped first unwraps before it. */
|
|
456
|
+
private teardown;
|
|
457
|
+
}
|
|
458
|
+
/** The file of the most recent frame that has a real file (the URL `allowUrls` / `denyUrls` match). */
|
|
459
|
+
declare function eventUrl(e: WireEvent): string | undefined;
|
|
460
|
+
|
|
461
|
+
/**
|
|
462
|
+
* The current client and the current scope, behind the top-level API.
|
|
463
|
+
*
|
|
464
|
+
* The default scope manager is a synchronous stack (browser): `withScope`
|
|
465
|
+
* forks the current scope for the duration of the callback. Node replaces it
|
|
466
|
+
* with an AsyncLocalStorage-backed manager through `setScopeManager`, so a
|
|
467
|
+
* request's scope does not leak into another.
|
|
468
|
+
*
|
|
469
|
+
* The state lives on `globalThis` under a registered symbol, not in this
|
|
470
|
+
* module: an app can end up with several copies of the SDK (a framework that
|
|
471
|
+
* bundles each route separately, an ESM and a CJS import, the script tag next
|
|
472
|
+
* to the npm package), and every copy must see the one client `init()` made.
|
|
473
|
+
*
|
|
474
|
+
* Copies of different versions. The symbol names the compatibility line of
|
|
475
|
+
* the copy (`0.1` for every 0.1.x, then the major: `1`, `2`, …):
|
|
476
|
+
* - same line (0.1.0 next to 0.1.4): ONE carrier, one client. A copy calling
|
|
477
|
+
* into a client made by another copy feature-checks the method first
|
|
478
|
+
* (`clientMethod`), so a newer copy never throws into its own guard (and
|
|
479
|
+
* silently stops flushing) because the older client lacks a method;
|
|
480
|
+
* - different lines (0.1.x next to 1.x): separate carriers. Each copy keeps
|
|
481
|
+
* its own client, scope and hooks; they never call into each other. Two
|
|
482
|
+
* `init()` calls are then two clients, as with two different SDKs.
|
|
483
|
+
* `version` records the copy that created the carrier (debugging aid).
|
|
484
|
+
*/
|
|
485
|
+
|
|
486
|
+
interface ScopeManager {
|
|
487
|
+
/** The scope events are captured with right now. */
|
|
488
|
+
getScope(): Scope;
|
|
489
|
+
/** Run `callback` with a fork of the current scope as the current scope. */
|
|
490
|
+
withScope<T>(callback: (scope: Scope) => T): T;
|
|
491
|
+
/**
|
|
492
|
+
* The scope an event captured now is built from, without making one
|
|
493
|
+
* (`getScope` may give code outside every request a scope of its own on a
|
|
494
|
+
* server: see src/node/scope.ts). Default: `getScope`.
|
|
495
|
+
*/
|
|
496
|
+
peekScope?(): Scope;
|
|
497
|
+
/**
|
|
498
|
+
* The scope `setUser(user)` / `identify` writes to, or undefined when the
|
|
499
|
+
* user must not be applied anywhere (the manager says why). Default:
|
|
500
|
+
* `getScope`.
|
|
501
|
+
*/
|
|
502
|
+
scopeForUser?(user: unknown): Scope | undefined;
|
|
503
|
+
}
|
|
504
|
+
declare function getClient<C extends Client = Client>(): C | undefined;
|
|
505
|
+
declare function setCurrentClient(client: Client | undefined): void;
|
|
506
|
+
/** The scope events are captured with right now (a `withScope` fork inside its callback). */
|
|
507
|
+
declare function getCurrentScope(): Scope;
|
|
508
|
+
/** The root scope (what `setUser` / `setTag` change outside `withScope`; on a server, only until it serves requests). */
|
|
509
|
+
declare function getGlobalScope(): Scope;
|
|
510
|
+
/** Install a platform scope manager (Node: AsyncLocalStorage). `undefined` restores the default. */
|
|
511
|
+
declare function setScopeManager(m: ScopeManager | undefined): void;
|
|
512
|
+
|
|
513
|
+
/**
|
|
514
|
+
* The top-level functions (same names on every platform). Each one works on
|
|
515
|
+
* the current client and scope, never throws, and is a no-op before `init`.
|
|
516
|
+
*
|
|
517
|
+
* Every setter changes the CURRENT scope. In browsers, and on a server
|
|
518
|
+
* before it serves requests, that is the global scope outside `withScope`.
|
|
519
|
+
* On a server that serves requests, it is the request's own scope inside a
|
|
520
|
+
* request, and outside any request a scope confined to the calling code
|
|
521
|
+
* (src/node/scope.ts): nothing set there reaches a request or another
|
|
522
|
+
* job's events.
|
|
523
|
+
*/
|
|
524
|
+
|
|
525
|
+
/** Capture a thrown value. Returns the event id ("" before `init`). */
|
|
526
|
+
declare function captureException(exception: unknown, hint?: EventHint): string;
|
|
527
|
+
/** Capture a message. `levelOrHint`: a level ("info" by default) or a full hint. */
|
|
528
|
+
declare function captureMessage(message: string, levelOrHint?: Level | EventHint): string;
|
|
529
|
+
/** Set (or clear with `null`) the user attached to events. */
|
|
530
|
+
declare function setUser(user: WireUser | null): void;
|
|
531
|
+
/**
|
|
532
|
+
* Alias of `setUser` that also sets the identity hash (HMAC-SHA256 of the
|
|
533
|
+
* identifier, computed by your backend; see docs/wire-format.md). `user`
|
|
534
|
+
* may be the id alone.
|
|
535
|
+
*/
|
|
536
|
+
declare function identify(user: WireUser | string, userHash?: string): void;
|
|
537
|
+
declare function setTag(key: string, value: unknown): void;
|
|
538
|
+
declare function setTags(tags: Record<string, unknown>): void;
|
|
539
|
+
declare function setExtra(key: string, value: unknown): void;
|
|
540
|
+
declare function setExtras(extras: Record<string, unknown>): void;
|
|
541
|
+
/** `null` removes the context. */
|
|
542
|
+
declare function setContext(name: string, context: Record<string, unknown> | null): void;
|
|
543
|
+
declare function addBreadcrumb(breadcrumb: Partial<Breadcrumb> & {
|
|
544
|
+
message?: string;
|
|
545
|
+
}, hint?: Record<string, unknown>): void;
|
|
546
|
+
/**
|
|
547
|
+
* Run `callback` with a fork of the current scope: tags, user or
|
|
548
|
+
* breadcrumbs set on it apply only to events captured inside. Returns the
|
|
549
|
+
* callback's result. An exception from the callback propagates (it is the
|
|
550
|
+
* app's), but the SDK's own failures never do.
|
|
551
|
+
*/
|
|
552
|
+
declare function withScope<T>(callback: (scope: Scope) => T): T;
|
|
553
|
+
/** Send queued events. True when everything went out within `timeoutMs`. */
|
|
554
|
+
declare function flush(timeoutMs?: number): Promise<boolean>;
|
|
555
|
+
/** Flush, then stop the SDK (hooks removed). */
|
|
556
|
+
declare function close(timeoutMs?: number): Promise<boolean>;
|
|
557
|
+
|
|
558
|
+
export { eventUrl as A, safely as B, Client as C, setCurrentClient as D, type EventHint as E, setScopeManager as F, uuid4 as G, type Integration as I, type Logger as L, type Options as O, type ParsedFrame as P, type QueueOptions as Q, SDK_VERSION as S, type TransportOptions as T, type Transport as a, type TransportResult as b, addBreadcrumb as c, captureException as d, captureMessage as e, close as f, flush as g, getClient as h, getCurrentScope as i, getGlobalScope as j, identify as k, setExtra as l, setExtras as m, setTag as n, setTags as o, setUser as p, type StackParser as q, type StackLineParser as r, setContext as s, type ClientOptions as t, EventQueue as u, type PlatformOptions as v, withScope as w, type ScopeManager as x, type TransportSendOptions as y, createLogger as z };
|