@tracewayapp/core 1.2.2 → 2.0.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/dist/index.d.mts CHANGED
@@ -183,4 +183,334 @@ declare class EventBuffer<T extends TracewayEventBase> {
183
183
  private prune;
184
184
  }
185
185
 
186
- export { type CollectionFrame, type CustomEvent, EventBuffer, type EventBufferOptions, type ExceptionStackTrace, type LogEvent, METRIC_CPU_USED_PCNT, METRIC_MEM_TOTAL, METRIC_MEM_USED, type MetricRecord, type NavigationEvent, type NetworkEvent, type ParsedConnectionString, type ReportRequest, type SessionPayload, type SessionRecordingPayload, type Span, type Trace, type TracewayEvent, type TracewayEventBase, type TracewayOptions, generateUUID, msToNanoseconds, nowISO, parseConnectionString };
186
+ interface TracewayEndpoints {
187
+ /** Where the Traceway server is reachable, without a trailing slash. */
188
+ base: string;
189
+ logs: string;
190
+ traces: string;
191
+ opamp: string;
192
+ recordings: string;
193
+ }
194
+ /**
195
+ * Derives every endpoint the SDK talks to from the URL half of the
196
+ * connection string. Accepts the bare server URL as well as the 1.x form
197
+ * that ended in `/api/report`, so existing connection strings keep working.
198
+ */
199
+ declare function resolveEndpoints(apiUrl: string): TracewayEndpoints;
200
+
201
+ declare function bytesToUuid(bytes: Uint8Array): string;
202
+ declare function uuidToBytes(uuid: string): Uint8Array | null;
203
+ /** RFC 9562 UUIDv7: a millisecond timestamp followed by random bits, as OpAMP recommends for instance ids. */
204
+ declare function uuidv7(nowMs?: number): string;
205
+ /** FNV-1a mapped to [0, 1): a stable sampling decision for an id such as a session id. */
206
+ declare function unitHash(value: string): number;
207
+
208
+ /**
209
+ * The collection settings document. The server sends a partial overlay of it
210
+ * over OpAMP (`config_map["traceway"]`); the SDK merges that onto its
211
+ * built-in defaults and clamps the result to the ceilings set in `init()`.
212
+ */
213
+ /** `off` drops a signal, `buffer` keeps it on the device until a trigger or capture flushes it, `stream` sends it. */
214
+ type Mode = "off" | "buffer" | "stream";
215
+ declare const MODES: readonly Mode[];
216
+ declare const SIGNALS: readonly ["errors", "messages", "network", "console", "navigation", "userActions", "webVitals", "resourceTiming", "custom"];
217
+ type SignalName = (typeof SIGNALS)[number];
218
+ type Severity = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
219
+ declare const SEVERITIES: readonly Severity[];
220
+ interface SignalSettings {
221
+ mode: Mode;
222
+ sampleRate: number;
223
+ /** Console only: records below it are dropped. */
224
+ minSeverity?: Severity;
225
+ }
226
+ interface ReplaySettings {
227
+ mode: Mode;
228
+ /** Share of sessions whose replay may stream; the rest keep replay buffered. Decided per session id. */
229
+ sessionSampleRate: number;
230
+ maskAllInputs: boolean;
231
+ }
232
+ interface BufferSettings {
233
+ maxBytes: number;
234
+ maxAgeSeconds: number;
235
+ replayMaxBytes: number;
236
+ /** Keep the buffer in IndexedDB so it survives reloads and crashes. */
237
+ persist: boolean;
238
+ }
239
+ type ConditionOp = "eq" | "neq" | "in" | "not_in" | "contains" | "icontains" | "starts_with" | "glob" | "exists" | "not_exists" | "gt" | "gte" | "lt" | "lte" | "version";
240
+ interface Condition {
241
+ key: string;
242
+ op: ConditionOp;
243
+ value?: string | number | boolean;
244
+ values?: Array<string | number | boolean>;
245
+ }
246
+ type Matcher = Condition | {
247
+ all: Matcher[];
248
+ } | {
249
+ any: Matcher[];
250
+ } | {
251
+ not: Matcher;
252
+ };
253
+ type SignalSelector = Array<SignalName | "*">;
254
+ type TriggerAction =
255
+ /** Upload what the buffer holds from the last `lookbackSeconds`. */
256
+ {
257
+ type: "flush";
258
+ lookbackSeconds: number;
259
+ signals?: SignalSelector;
260
+ replay?: boolean;
261
+ }
262
+ /** Send the selected signals straight away for `durationSeconds` instead of buffering them. */
263
+ | {
264
+ type: "stream";
265
+ durationSeconds: number;
266
+ signals?: SignalSelector;
267
+ replay?: boolean;
268
+ }
269
+ /** Record and stream session replay for `durationSeconds`. */
270
+ | {
271
+ type: "startReplay";
272
+ durationSeconds: number;
273
+ }
274
+ /** Emit a marker event, so the dashboard can count how often this happens. */
275
+ | {
276
+ type: "emit";
277
+ eventName: string;
278
+ attributes?: Record<string, string>;
279
+ }
280
+ /**
281
+ * A capture started on the device: upload the last `lookbackSeconds`, then stream the selected signals (and
282
+ * replay) for `durationSeconds`. Unlike `stream` it survives page loads and is reported as a capture.
283
+ */
284
+ | {
285
+ type: "capture";
286
+ durationSeconds: number;
287
+ lookbackSeconds?: number;
288
+ signals?: SignalSelector;
289
+ replay?: boolean;
290
+ };
291
+ interface TriggerStep {
292
+ match: Matcher;
293
+ /** Longest gap allowed since the previous step; null or absent means no limit. */
294
+ withinSeconds?: number | null;
295
+ /** Matching records needed before the step completes, e.g. 5 error lines. Default 1. */
296
+ count?: number;
297
+ /** With `count`: all of them within this many seconds of each other (a sliding window). */
298
+ periodSeconds?: number | null;
299
+ }
300
+ interface Trigger {
301
+ id: string;
302
+ name?: string;
303
+ enabled?: boolean;
304
+ sampleRate?: number;
305
+ cooldownSeconds?: number;
306
+ maxPerSession?: number;
307
+ steps: TriggerStep[];
308
+ actions: TriggerAction[];
309
+ }
310
+ /** An on-demand capture requested from the dashboard; only the server creates these. */
311
+ interface Capture {
312
+ id: string;
313
+ until: string;
314
+ lookbackSeconds?: number;
315
+ signals?: SignalSelector;
316
+ replay?: boolean;
317
+ }
318
+ interface Settings {
319
+ schemaVersion: 1;
320
+ /** Kill switch: when false nothing but the OpAMP poll leaves the device. */
321
+ enabled: boolean;
322
+ signals: Record<SignalName, SignalSettings>;
323
+ sessions: {
324
+ enabled: boolean;
325
+ baselineSampleRate: number;
326
+ };
327
+ replay: ReplaySettings;
328
+ buffer: BufferSettings;
329
+ triggers: Trigger[];
330
+ captures: Capture[];
331
+ }
332
+ /** The most a signal may do on this page, set from the `init()` options. Remote settings can only go lower. */
333
+ interface Ceilings {
334
+ enabled: boolean;
335
+ signals: Record<SignalName, Mode>;
336
+ replay: Mode;
337
+ sessions: boolean;
338
+ }
339
+
340
+ declare const DEFAULT_EXCEPTION_TRIGGER_ID = "default-exception";
341
+ declare function defaultExceptionTrigger(): Trigger;
342
+ interface DefaultSettingsOptions {
343
+ /**
344
+ * 1.x `recordAllSessions`: stream every replay segment instead of keeping it for errors, and the breadcrumbs the
345
+ * player shows next to it (console, network, navigation, clicks, app events), which travel as telemetry.
346
+ */
347
+ recordAllSessions?: boolean;
348
+ baselineSampleRate?: number;
349
+ }
350
+ declare function defaultSettings(options?: DefaultSettingsOptions): Settings;
351
+ interface CeilingOptions {
352
+ enabled?: boolean;
353
+ sessionRecording?: boolean;
354
+ captureLogs?: boolean;
355
+ captureNetwork?: boolean;
356
+ captureNavigation?: boolean;
357
+ captureUserActions?: boolean;
358
+ captureWebVitals?: boolean;
359
+ captureResourceTiming?: boolean;
360
+ sessions?: boolean;
361
+ }
362
+ declare function ceilingsFrom(options?: CeilingOptions): Ceilings;
363
+
364
+ declare class SettingsError extends Error {
365
+ }
366
+ type Json = Record<string, unknown>;
367
+ /** Parses the document the server sent. Throws for anything this SDK cannot apply. */
368
+ declare function parseSettingsDocument(body: string | Uint8Array): Json;
369
+ declare function parseMatcher(value: unknown, depth?: number): Matcher | null;
370
+ /**
371
+ * Lays a remote overlay over `base`. Fields this SDK does not know are ignored
372
+ * so a newer server can add settings; malformed values of known fields are
373
+ * skipped individually instead of rejecting the whole document.
374
+ */
375
+ declare function applyOverlay(base: Settings, overlay: Json): Settings;
376
+ declare function lowerMode(a: Mode, b: Mode): Mode;
377
+ declare function modeRank(mode: Mode): number;
378
+ /**
379
+ * Lowers the page's ceilings to the `limits` a remote document carries: what the organization's plan accepts at
380
+ * ingest. Rules cannot set them, and no trigger or capture can exceed them, the same as the `init()` ceilings.
381
+ */
382
+ declare function applyLimits(ceilings: Ceilings, overlay: Json | null): Ceilings;
383
+ /** Holds every mode at or below what `init()` allowed on this page. */
384
+ declare function clampToCeilings(settings: Settings, ceilings: Ceilings): Settings;
385
+
386
+ interface StreamOverride {
387
+ /**
388
+ * `"*"` covers every signal that is not off; listing a signal also turns it on. Either way the result stays
389
+ * within the page's ceilings and the plan's limits.
390
+ */
391
+ signals: SignalSelector;
392
+ replay: boolean;
393
+ untilMs: number;
394
+ /**
395
+ * A capture: `"*"` also brings back the signals rules switched off, everything this page collects by default.
396
+ * Signals that are off in the defaults (resource timing) still need to be listed.
397
+ */
398
+ includeOff?: boolean;
399
+ }
400
+ /**
401
+ * The effective collection settings at any moment: built-in defaults, then
402
+ * the remote overlay, clamped to the page's ceilings, then any temporary
403
+ * "stream for a while" overrides from triggers and captures.
404
+ */
405
+ declare class ControlState {
406
+ private readonly defaults;
407
+ private readonly pageCeilings;
408
+ private readonly now;
409
+ private remote;
410
+ private effective;
411
+ private overrides;
412
+ private overrideSequence;
413
+ private listeners;
414
+ /** The page's ceilings lowered to the plan limits of the current remote document. */
415
+ private ceilings;
416
+ constructor(defaults: Settings, pageCeilings: Ceilings, now?: () => number);
417
+ settings(): Settings;
418
+ remoteOverlay(): Record<string, unknown> | null;
419
+ /** Applies a parsed remote document, or `null` to fall back to the defaults. */
420
+ applyRemote(overlay: Record<string, unknown> | null): void;
421
+ onChange(listener: (settings: Settings) => void): () => void;
422
+ addOverride(override: StreamOverride): void;
423
+ setOverrides(owner: string, overrides: StreamOverride[]): void;
424
+ nextOverrideExpiry(): number | undefined;
425
+ private activeOverrides;
426
+ canExport(signal: SignalName): boolean;
427
+ enabled(): boolean;
428
+ modeFor(signal: SignalName): Mode;
429
+ private covers;
430
+ replayMode(): Mode;
431
+ sampleRate(signal: SignalName): number;
432
+ }
433
+
434
+ /** Resolves a matcher key such as `event.name` or `attributes.http.response.status_code` to a value. */
435
+ type FieldLookup = (key: string) => unknown;
436
+ declare function compareVersions(a: string, b: string): number | null;
437
+ /** Checks a version against a constraint such as `>=2.1 <3` (comparators separated by spaces or commas, all must hold). */
438
+ declare function satisfiesVersion(version: string, constraint: string): boolean;
439
+ declare function matches(matcher: Matcher, lookup: FieldLookup): boolean;
440
+
441
+ interface ObservedEvent {
442
+ timeMs: number;
443
+ lookup: FieldLookup;
444
+ }
445
+ interface FiredTrigger {
446
+ trigger: Trigger;
447
+ actions: TriggerAction[];
448
+ /** The event that completed the trigger, e.g. the exception a clip belongs to. */
449
+ cause: ObservedEvent;
450
+ }
451
+ /**
452
+ * Runs the server-defined triggers against every event on the device. A
453
+ * trigger is a sequence of steps; each matching event advances it, a step
454
+ * that arrives later than its `withinSeconds` starts it over, and the last
455
+ * step fires the trigger's actions. Progress and fire counts are per session.
456
+ */
457
+ declare class TriggerEngine {
458
+ private readonly random;
459
+ private triggers;
460
+ readonly skipped: Map<string, string>;
461
+ sessionLimits: Record<string, {
462
+ fires: number;
463
+ lastFireMs: number;
464
+ }>;
465
+ private states;
466
+ constructor(random?: () => number);
467
+ setTriggers(triggers: Trigger[]): void;
468
+ resetSession(): void;
469
+ restoreSessionLimits(saved: unknown): void;
470
+ observe(event: ObservedEvent): FiredTrigger[];
471
+ /** Feeds one record to a trigger; true when it completed the last step. */
472
+ private advance;
473
+ private mayFire;
474
+ }
475
+
476
+ interface BufferEntry<T> {
477
+ timeMs: number;
478
+ signal: string;
479
+ bytes: number;
480
+ item: T;
481
+ }
482
+ interface RingBufferOptions {
483
+ maxBytes: number;
484
+ maxAgeMs: number;
485
+ now?: () => number;
486
+ }
487
+ /**
488
+ * Keeps the newest telemetry on the device within a byte and age budget.
489
+ * When the budget is exceeded the oldest entries go first; nothing leaves
490
+ * the device until a flush takes entries out.
491
+ */
492
+ declare class RingBuffer<T> {
493
+ private entries;
494
+ private totalBytes;
495
+ private maxBytes;
496
+ private maxAgeMs;
497
+ private readonly now;
498
+ private evicted;
499
+ constructor(options: RingBufferOptions);
500
+ configure(options: Omit<RingBufferOptions, "now">): void;
501
+ push(entry: BufferEntry<T>): void;
502
+ /** Removes and returns the entries recorded at or after `sinceMs` for the selected signals, oldest first. */
503
+ take(sinceMs: number, signals: ReadonlySet<string> | "*", untilMs?: number): BufferEntry<T>[];
504
+ /** The entries currently held, oldest first, without removing them. */
505
+ snapshot(): BufferEntry<T>[];
506
+ restore(entries: BufferEntry<T>[]): void;
507
+ retain(keep: (entry: BufferEntry<T>) => boolean): void;
508
+ clear(): void;
509
+ get size(): number;
510
+ get bytes(): number;
511
+ /** Entries dropped to stay within budget since the buffer was created. */
512
+ get evictedCount(): number;
513
+ private trim;
514
+ }
515
+
516
+ export { type BufferEntry, type BufferSettings, type Capture, type CeilingOptions, type Ceilings, type CollectionFrame, type Condition, type ConditionOp, ControlState, type CustomEvent, DEFAULT_EXCEPTION_TRIGGER_ID, type DefaultSettingsOptions, EventBuffer, type EventBufferOptions, type ExceptionStackTrace, type FieldLookup, type FiredTrigger, type LogEvent, METRIC_CPU_USED_PCNT, METRIC_MEM_TOTAL, METRIC_MEM_USED, MODES, type Matcher, type MetricRecord, type Mode, type NavigationEvent, type NetworkEvent, type ObservedEvent, type ParsedConnectionString, type ReplaySettings, type ReportRequest, RingBuffer, type RingBufferOptions, SEVERITIES, SIGNALS, type SessionPayload, type SessionRecordingPayload, type Settings, SettingsError, type Severity, type SignalName, type SignalSelector, type SignalSettings, type Span, type StreamOverride, type Trace, type TracewayEndpoints, type TracewayEvent, type TracewayEventBase, type TracewayOptions, type Trigger, type TriggerAction, TriggerEngine, type TriggerStep, applyLimits, applyOverlay, bytesToUuid, ceilingsFrom, clampToCeilings, compareVersions, defaultExceptionTrigger, defaultSettings, generateUUID, lowerMode, matches, modeRank, msToNanoseconds, nowISO, parseConnectionString, parseMatcher, parseSettingsDocument, resolveEndpoints, satisfiesVersion, unitHash, uuidToBytes, uuidv7 };
package/dist/index.d.ts CHANGED
@@ -183,4 +183,334 @@ declare class EventBuffer<T extends TracewayEventBase> {
183
183
  private prune;
184
184
  }
185
185
 
186
- export { type CollectionFrame, type CustomEvent, EventBuffer, type EventBufferOptions, type ExceptionStackTrace, type LogEvent, METRIC_CPU_USED_PCNT, METRIC_MEM_TOTAL, METRIC_MEM_USED, type MetricRecord, type NavigationEvent, type NetworkEvent, type ParsedConnectionString, type ReportRequest, type SessionPayload, type SessionRecordingPayload, type Span, type Trace, type TracewayEvent, type TracewayEventBase, type TracewayOptions, generateUUID, msToNanoseconds, nowISO, parseConnectionString };
186
+ interface TracewayEndpoints {
187
+ /** Where the Traceway server is reachable, without a trailing slash. */
188
+ base: string;
189
+ logs: string;
190
+ traces: string;
191
+ opamp: string;
192
+ recordings: string;
193
+ }
194
+ /**
195
+ * Derives every endpoint the SDK talks to from the URL half of the
196
+ * connection string. Accepts the bare server URL as well as the 1.x form
197
+ * that ended in `/api/report`, so existing connection strings keep working.
198
+ */
199
+ declare function resolveEndpoints(apiUrl: string): TracewayEndpoints;
200
+
201
+ declare function bytesToUuid(bytes: Uint8Array): string;
202
+ declare function uuidToBytes(uuid: string): Uint8Array | null;
203
+ /** RFC 9562 UUIDv7: a millisecond timestamp followed by random bits, as OpAMP recommends for instance ids. */
204
+ declare function uuidv7(nowMs?: number): string;
205
+ /** FNV-1a mapped to [0, 1): a stable sampling decision for an id such as a session id. */
206
+ declare function unitHash(value: string): number;
207
+
208
+ /**
209
+ * The collection settings document. The server sends a partial overlay of it
210
+ * over OpAMP (`config_map["traceway"]`); the SDK merges that onto its
211
+ * built-in defaults and clamps the result to the ceilings set in `init()`.
212
+ */
213
+ /** `off` drops a signal, `buffer` keeps it on the device until a trigger or capture flushes it, `stream` sends it. */
214
+ type Mode = "off" | "buffer" | "stream";
215
+ declare const MODES: readonly Mode[];
216
+ declare const SIGNALS: readonly ["errors", "messages", "network", "console", "navigation", "userActions", "webVitals", "resourceTiming", "custom"];
217
+ type SignalName = (typeof SIGNALS)[number];
218
+ type Severity = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
219
+ declare const SEVERITIES: readonly Severity[];
220
+ interface SignalSettings {
221
+ mode: Mode;
222
+ sampleRate: number;
223
+ /** Console only: records below it are dropped. */
224
+ minSeverity?: Severity;
225
+ }
226
+ interface ReplaySettings {
227
+ mode: Mode;
228
+ /** Share of sessions whose replay may stream; the rest keep replay buffered. Decided per session id. */
229
+ sessionSampleRate: number;
230
+ maskAllInputs: boolean;
231
+ }
232
+ interface BufferSettings {
233
+ maxBytes: number;
234
+ maxAgeSeconds: number;
235
+ replayMaxBytes: number;
236
+ /** Keep the buffer in IndexedDB so it survives reloads and crashes. */
237
+ persist: boolean;
238
+ }
239
+ type ConditionOp = "eq" | "neq" | "in" | "not_in" | "contains" | "icontains" | "starts_with" | "glob" | "exists" | "not_exists" | "gt" | "gte" | "lt" | "lte" | "version";
240
+ interface Condition {
241
+ key: string;
242
+ op: ConditionOp;
243
+ value?: string | number | boolean;
244
+ values?: Array<string | number | boolean>;
245
+ }
246
+ type Matcher = Condition | {
247
+ all: Matcher[];
248
+ } | {
249
+ any: Matcher[];
250
+ } | {
251
+ not: Matcher;
252
+ };
253
+ type SignalSelector = Array<SignalName | "*">;
254
+ type TriggerAction =
255
+ /** Upload what the buffer holds from the last `lookbackSeconds`. */
256
+ {
257
+ type: "flush";
258
+ lookbackSeconds: number;
259
+ signals?: SignalSelector;
260
+ replay?: boolean;
261
+ }
262
+ /** Send the selected signals straight away for `durationSeconds` instead of buffering them. */
263
+ | {
264
+ type: "stream";
265
+ durationSeconds: number;
266
+ signals?: SignalSelector;
267
+ replay?: boolean;
268
+ }
269
+ /** Record and stream session replay for `durationSeconds`. */
270
+ | {
271
+ type: "startReplay";
272
+ durationSeconds: number;
273
+ }
274
+ /** Emit a marker event, so the dashboard can count how often this happens. */
275
+ | {
276
+ type: "emit";
277
+ eventName: string;
278
+ attributes?: Record<string, string>;
279
+ }
280
+ /**
281
+ * A capture started on the device: upload the last `lookbackSeconds`, then stream the selected signals (and
282
+ * replay) for `durationSeconds`. Unlike `stream` it survives page loads and is reported as a capture.
283
+ */
284
+ | {
285
+ type: "capture";
286
+ durationSeconds: number;
287
+ lookbackSeconds?: number;
288
+ signals?: SignalSelector;
289
+ replay?: boolean;
290
+ };
291
+ interface TriggerStep {
292
+ match: Matcher;
293
+ /** Longest gap allowed since the previous step; null or absent means no limit. */
294
+ withinSeconds?: number | null;
295
+ /** Matching records needed before the step completes, e.g. 5 error lines. Default 1. */
296
+ count?: number;
297
+ /** With `count`: all of them within this many seconds of each other (a sliding window). */
298
+ periodSeconds?: number | null;
299
+ }
300
+ interface Trigger {
301
+ id: string;
302
+ name?: string;
303
+ enabled?: boolean;
304
+ sampleRate?: number;
305
+ cooldownSeconds?: number;
306
+ maxPerSession?: number;
307
+ steps: TriggerStep[];
308
+ actions: TriggerAction[];
309
+ }
310
+ /** An on-demand capture requested from the dashboard; only the server creates these. */
311
+ interface Capture {
312
+ id: string;
313
+ until: string;
314
+ lookbackSeconds?: number;
315
+ signals?: SignalSelector;
316
+ replay?: boolean;
317
+ }
318
+ interface Settings {
319
+ schemaVersion: 1;
320
+ /** Kill switch: when false nothing but the OpAMP poll leaves the device. */
321
+ enabled: boolean;
322
+ signals: Record<SignalName, SignalSettings>;
323
+ sessions: {
324
+ enabled: boolean;
325
+ baselineSampleRate: number;
326
+ };
327
+ replay: ReplaySettings;
328
+ buffer: BufferSettings;
329
+ triggers: Trigger[];
330
+ captures: Capture[];
331
+ }
332
+ /** The most a signal may do on this page, set from the `init()` options. Remote settings can only go lower. */
333
+ interface Ceilings {
334
+ enabled: boolean;
335
+ signals: Record<SignalName, Mode>;
336
+ replay: Mode;
337
+ sessions: boolean;
338
+ }
339
+
340
+ declare const DEFAULT_EXCEPTION_TRIGGER_ID = "default-exception";
341
+ declare function defaultExceptionTrigger(): Trigger;
342
+ interface DefaultSettingsOptions {
343
+ /**
344
+ * 1.x `recordAllSessions`: stream every replay segment instead of keeping it for errors, and the breadcrumbs the
345
+ * player shows next to it (console, network, navigation, clicks, app events), which travel as telemetry.
346
+ */
347
+ recordAllSessions?: boolean;
348
+ baselineSampleRate?: number;
349
+ }
350
+ declare function defaultSettings(options?: DefaultSettingsOptions): Settings;
351
+ interface CeilingOptions {
352
+ enabled?: boolean;
353
+ sessionRecording?: boolean;
354
+ captureLogs?: boolean;
355
+ captureNetwork?: boolean;
356
+ captureNavigation?: boolean;
357
+ captureUserActions?: boolean;
358
+ captureWebVitals?: boolean;
359
+ captureResourceTiming?: boolean;
360
+ sessions?: boolean;
361
+ }
362
+ declare function ceilingsFrom(options?: CeilingOptions): Ceilings;
363
+
364
+ declare class SettingsError extends Error {
365
+ }
366
+ type Json = Record<string, unknown>;
367
+ /** Parses the document the server sent. Throws for anything this SDK cannot apply. */
368
+ declare function parseSettingsDocument(body: string | Uint8Array): Json;
369
+ declare function parseMatcher(value: unknown, depth?: number): Matcher | null;
370
+ /**
371
+ * Lays a remote overlay over `base`. Fields this SDK does not know are ignored
372
+ * so a newer server can add settings; malformed values of known fields are
373
+ * skipped individually instead of rejecting the whole document.
374
+ */
375
+ declare function applyOverlay(base: Settings, overlay: Json): Settings;
376
+ declare function lowerMode(a: Mode, b: Mode): Mode;
377
+ declare function modeRank(mode: Mode): number;
378
+ /**
379
+ * Lowers the page's ceilings to the `limits` a remote document carries: what the organization's plan accepts at
380
+ * ingest. Rules cannot set them, and no trigger or capture can exceed them, the same as the `init()` ceilings.
381
+ */
382
+ declare function applyLimits(ceilings: Ceilings, overlay: Json | null): Ceilings;
383
+ /** Holds every mode at or below what `init()` allowed on this page. */
384
+ declare function clampToCeilings(settings: Settings, ceilings: Ceilings): Settings;
385
+
386
+ interface StreamOverride {
387
+ /**
388
+ * `"*"` covers every signal that is not off; listing a signal also turns it on. Either way the result stays
389
+ * within the page's ceilings and the plan's limits.
390
+ */
391
+ signals: SignalSelector;
392
+ replay: boolean;
393
+ untilMs: number;
394
+ /**
395
+ * A capture: `"*"` also brings back the signals rules switched off, everything this page collects by default.
396
+ * Signals that are off in the defaults (resource timing) still need to be listed.
397
+ */
398
+ includeOff?: boolean;
399
+ }
400
+ /**
401
+ * The effective collection settings at any moment: built-in defaults, then
402
+ * the remote overlay, clamped to the page's ceilings, then any temporary
403
+ * "stream for a while" overrides from triggers and captures.
404
+ */
405
+ declare class ControlState {
406
+ private readonly defaults;
407
+ private readonly pageCeilings;
408
+ private readonly now;
409
+ private remote;
410
+ private effective;
411
+ private overrides;
412
+ private overrideSequence;
413
+ private listeners;
414
+ /** The page's ceilings lowered to the plan limits of the current remote document. */
415
+ private ceilings;
416
+ constructor(defaults: Settings, pageCeilings: Ceilings, now?: () => number);
417
+ settings(): Settings;
418
+ remoteOverlay(): Record<string, unknown> | null;
419
+ /** Applies a parsed remote document, or `null` to fall back to the defaults. */
420
+ applyRemote(overlay: Record<string, unknown> | null): void;
421
+ onChange(listener: (settings: Settings) => void): () => void;
422
+ addOverride(override: StreamOverride): void;
423
+ setOverrides(owner: string, overrides: StreamOverride[]): void;
424
+ nextOverrideExpiry(): number | undefined;
425
+ private activeOverrides;
426
+ canExport(signal: SignalName): boolean;
427
+ enabled(): boolean;
428
+ modeFor(signal: SignalName): Mode;
429
+ private covers;
430
+ replayMode(): Mode;
431
+ sampleRate(signal: SignalName): number;
432
+ }
433
+
434
+ /** Resolves a matcher key such as `event.name` or `attributes.http.response.status_code` to a value. */
435
+ type FieldLookup = (key: string) => unknown;
436
+ declare function compareVersions(a: string, b: string): number | null;
437
+ /** Checks a version against a constraint such as `>=2.1 <3` (comparators separated by spaces or commas, all must hold). */
438
+ declare function satisfiesVersion(version: string, constraint: string): boolean;
439
+ declare function matches(matcher: Matcher, lookup: FieldLookup): boolean;
440
+
441
+ interface ObservedEvent {
442
+ timeMs: number;
443
+ lookup: FieldLookup;
444
+ }
445
+ interface FiredTrigger {
446
+ trigger: Trigger;
447
+ actions: TriggerAction[];
448
+ /** The event that completed the trigger, e.g. the exception a clip belongs to. */
449
+ cause: ObservedEvent;
450
+ }
451
+ /**
452
+ * Runs the server-defined triggers against every event on the device. A
453
+ * trigger is a sequence of steps; each matching event advances it, a step
454
+ * that arrives later than its `withinSeconds` starts it over, and the last
455
+ * step fires the trigger's actions. Progress and fire counts are per session.
456
+ */
457
+ declare class TriggerEngine {
458
+ private readonly random;
459
+ private triggers;
460
+ readonly skipped: Map<string, string>;
461
+ sessionLimits: Record<string, {
462
+ fires: number;
463
+ lastFireMs: number;
464
+ }>;
465
+ private states;
466
+ constructor(random?: () => number);
467
+ setTriggers(triggers: Trigger[]): void;
468
+ resetSession(): void;
469
+ restoreSessionLimits(saved: unknown): void;
470
+ observe(event: ObservedEvent): FiredTrigger[];
471
+ /** Feeds one record to a trigger; true when it completed the last step. */
472
+ private advance;
473
+ private mayFire;
474
+ }
475
+
476
+ interface BufferEntry<T> {
477
+ timeMs: number;
478
+ signal: string;
479
+ bytes: number;
480
+ item: T;
481
+ }
482
+ interface RingBufferOptions {
483
+ maxBytes: number;
484
+ maxAgeMs: number;
485
+ now?: () => number;
486
+ }
487
+ /**
488
+ * Keeps the newest telemetry on the device within a byte and age budget.
489
+ * When the budget is exceeded the oldest entries go first; nothing leaves
490
+ * the device until a flush takes entries out.
491
+ */
492
+ declare class RingBuffer<T> {
493
+ private entries;
494
+ private totalBytes;
495
+ private maxBytes;
496
+ private maxAgeMs;
497
+ private readonly now;
498
+ private evicted;
499
+ constructor(options: RingBufferOptions);
500
+ configure(options: Omit<RingBufferOptions, "now">): void;
501
+ push(entry: BufferEntry<T>): void;
502
+ /** Removes and returns the entries recorded at or after `sinceMs` for the selected signals, oldest first. */
503
+ take(sinceMs: number, signals: ReadonlySet<string> | "*", untilMs?: number): BufferEntry<T>[];
504
+ /** The entries currently held, oldest first, without removing them. */
505
+ snapshot(): BufferEntry<T>[];
506
+ restore(entries: BufferEntry<T>[]): void;
507
+ retain(keep: (entry: BufferEntry<T>) => boolean): void;
508
+ clear(): void;
509
+ get size(): number;
510
+ get bytes(): number;
511
+ /** Entries dropped to stay within budget since the buffer was created. */
512
+ get evictedCount(): number;
513
+ private trim;
514
+ }
515
+
516
+ export { type BufferEntry, type BufferSettings, type Capture, type CeilingOptions, type Ceilings, type CollectionFrame, type Condition, type ConditionOp, ControlState, type CustomEvent, DEFAULT_EXCEPTION_TRIGGER_ID, type DefaultSettingsOptions, EventBuffer, type EventBufferOptions, type ExceptionStackTrace, type FieldLookup, type FiredTrigger, type LogEvent, METRIC_CPU_USED_PCNT, METRIC_MEM_TOTAL, METRIC_MEM_USED, MODES, type Matcher, type MetricRecord, type Mode, type NavigationEvent, type NetworkEvent, type ObservedEvent, type ParsedConnectionString, type ReplaySettings, type ReportRequest, RingBuffer, type RingBufferOptions, SEVERITIES, SIGNALS, type SessionPayload, type SessionRecordingPayload, type Settings, SettingsError, type Severity, type SignalName, type SignalSelector, type SignalSettings, type Span, type StreamOverride, type Trace, type TracewayEndpoints, type TracewayEvent, type TracewayEventBase, type TracewayOptions, type Trigger, type TriggerAction, TriggerEngine, type TriggerStep, applyLimits, applyOverlay, bytesToUuid, ceilingsFrom, clampToCeilings, compareVersions, defaultExceptionTrigger, defaultSettings, generateUUID, lowerMode, matches, modeRank, msToNanoseconds, nowISO, parseConnectionString, parseMatcher, parseSettingsDocument, resolveEndpoints, satisfiesVersion, unitHash, uuidToBytes, uuidv7 };