@nagoorkani/session-capture-core 0.1.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.
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Drains the queue.
3
+ *
4
+ * Single-flight on purpose: only one drain runs at a time. Two concurrent
5
+ * drains would read the same oldest batches and deliver them twice — the
6
+ * backend deduplicates, but spending a user's data plan to send events the
7
+ * server will throw away is not something to rely on.
8
+ */
9
+ import { backoffDelay, sendBatch } from "./transport.js";
10
+ export class Dispatcher {
11
+ constructor(options) {
12
+ this.draining = false;
13
+ /** Wall-clock time before which no send should be attempted. */
14
+ this.pausedUntil = 0;
15
+ this.queue = options.queue;
16
+ this.transport = options.transport;
17
+ this.batchesPerDrain = options.batchesPerDrain ?? 5;
18
+ this.now = options.now ?? Date.now;
19
+ this.onOutcome = options.onOutcome;
20
+ }
21
+ /** True while backpressure is in effect. */
22
+ get paused() {
23
+ return this.now() < this.pausedUntil;
24
+ }
25
+ get pausedForMs() {
26
+ return Math.max(0, this.pausedUntil - this.now());
27
+ }
28
+ /**
29
+ * Send what is queued.
30
+ *
31
+ * Returns the number of batches delivered. Stops early on the first batch
32
+ * that needs retrying: the queue is ordered, and a failure almost always
33
+ * means the network or the server is unavailable for the next one too.
34
+ * Continuing would just burn attempts on every queued batch at once.
35
+ */
36
+ async drain() {
37
+ if (this.draining || this.paused)
38
+ return 0;
39
+ this.draining = true;
40
+ let sent = 0;
41
+ try {
42
+ const entries = await this.queue.peek(this.batchesPerDrain);
43
+ for (const entry of entries) {
44
+ const outcome = await sendBatch(this.transport, entry.batch);
45
+ this.onOutcome?.(outcome, entry);
46
+ if (outcome.kind === 'sent') {
47
+ await this.queue.remove(entry.name);
48
+ sent += 1;
49
+ continue;
50
+ }
51
+ if (outcome.kind === 'permanent') {
52
+ // The server will never take this. Keeping it would block every
53
+ // batch behind it forever.
54
+ await this.queue.remove(entry.name);
55
+ continue;
56
+ }
57
+ // Retryable. Honour an explicit Retry-After over our own backoff:
58
+ // the server knows more about when it will be ready than we do.
59
+ const delay = outcome.retryAfterMs ?? backoffDelay(entry.attempts);
60
+ this.pausedUntil = this.now() + delay;
61
+ await this.queue.recordFailure(entry);
62
+ break;
63
+ }
64
+ }
65
+ finally {
66
+ this.draining = false;
67
+ }
68
+ return sent;
69
+ }
70
+ /** Clear backpressure, e.g. when the app returns to the foreground. */
71
+ resume() {
72
+ this.pausedUntil = 0;
73
+ }
74
+ }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Error capture.
3
+ *
4
+ * Errors are the reason people install this, so they bypass sampling entirely
5
+ * (section 35) and are the one event type worth capturing aggressively.
6
+ *
7
+ * The SDK sends type, message, and stack. Grouping happens server-side, so a
8
+ * fingerprinting change does not need an app release to take effect.
9
+ */
10
+ export interface CapturedError {
11
+ type: string;
12
+ message: string;
13
+ stack?: string;
14
+ /** False for a global handler catch — the app did not expect this one. */
15
+ handled: boolean;
16
+ /** True when the platform considers the error fatal to the app. */
17
+ fatal?: boolean;
18
+ }
19
+ /**
20
+ * Normalize anything throwable into a capturable shape.
21
+ *
22
+ * JavaScript permits throwing any value — strings, objects, undefined — and a
23
+ * crash reporter that assumes `Error` will itself throw while handling the
24
+ * crash.
25
+ */
26
+ export declare function describeError(value: unknown, handled: boolean): CapturedError;
27
+ export type ErrorHandler = (error: CapturedError) => void;
28
+ type Uninstall = () => void;
29
+ /**
30
+ * Install global error and rejection handlers.
31
+ *
32
+ * React Native exposes `ErrorUtils`; a browser fires an `error` event on
33
+ * `window` instead. The promise rejection path is the same `addEventListener`
34
+ * in both. All of it is optional — an environment providing none simply
35
+ * captures fewer errors, which is far better than failing to start.
36
+ */
37
+ export declare function installErrorHandlers(onError: ErrorHandler): Uninstall;
38
+ /** Test-only. */
39
+ export declare function resetErrorHandlerState(): void;
40
+ export {};
package/dist/errors.js ADDED
@@ -0,0 +1,186 @@
1
+ /**
2
+ * Error capture.
3
+ *
4
+ * Errors are the reason people install this, so they bypass sampling entirely
5
+ * (section 35) and are the one event type worth capturing aggressively.
6
+ *
7
+ * The SDK sends type, message, and stack. Grouping happens server-side, so a
8
+ * fingerprinting change does not need an app release to take effect.
9
+ */
10
+ /** Stacks are unbounded in principle and this rides on every error. */
11
+ const MAX_STACK_CHARS = 8 * 1024;
12
+ const MAX_MESSAGE_CHARS = 1024;
13
+ /**
14
+ * Normalize anything throwable into a capturable shape.
15
+ *
16
+ * JavaScript permits throwing any value — strings, objects, undefined — and a
17
+ * crash reporter that assumes `Error` will itself throw while handling the
18
+ * crash.
19
+ */
20
+ export function describeError(value, handled) {
21
+ if (value instanceof Error) {
22
+ return {
23
+ type: value.name || 'Error',
24
+ message: (value.message || '').slice(0, MAX_MESSAGE_CHARS),
25
+ stack: value.stack?.slice(0, MAX_STACK_CHARS),
26
+ handled,
27
+ };
28
+ }
29
+ if (typeof value === 'string') {
30
+ return {
31
+ type: 'Error',
32
+ message: value.slice(0, MAX_MESSAGE_CHARS),
33
+ handled,
34
+ };
35
+ }
36
+ // Objects, numbers, null, undefined. Stringify defensively: a getter on the
37
+ // thrown object can itself throw.
38
+ let message;
39
+ try {
40
+ message = typeof value === 'object' && value !== null
41
+ ? JSON.stringify(value)
42
+ : String(value);
43
+ }
44
+ catch {
45
+ message = '[unserializable]';
46
+ }
47
+ return {
48
+ type: 'UnknownError',
49
+ message: (message ?? 'undefined').slice(0, MAX_MESSAGE_CHARS),
50
+ handled,
51
+ };
52
+ }
53
+ let installed = false;
54
+ /**
55
+ * Install global error and rejection handlers.
56
+ *
57
+ * React Native exposes `ErrorUtils`; a browser fires an `error` event on
58
+ * `window` instead. The promise rejection path is the same `addEventListener`
59
+ * in both. All of it is optional — an environment providing none simply
60
+ * captures fewer errors, which is far better than failing to start.
61
+ */
62
+ export function installErrorHandlers(onError) {
63
+ if (installed) {
64
+ // Double-installing would report every error twice and, worse, chain the
65
+ // previous handler into itself.
66
+ return () => { };
67
+ }
68
+ installed = true;
69
+ const uninstalls = [];
70
+ uninstalls.push(installGlobalErrorHandler(onError));
71
+ uninstalls.push(installRejectionHandler(onError));
72
+ return () => {
73
+ installed = false;
74
+ for (const fn of uninstalls) {
75
+ try {
76
+ fn();
77
+ }
78
+ catch {
79
+ // Teardown must never throw into the host app.
80
+ }
81
+ }
82
+ };
83
+ }
84
+ function installGlobalErrorHandler(onError) {
85
+ const errorUtils = globalThis.ErrorUtils;
86
+ if (!errorUtils?.setGlobalHandler || !errorUtils.getGlobalHandler) {
87
+ return installErrorEventHandler(onError);
88
+ }
89
+ const previous = errorUtils.getGlobalHandler();
90
+ errorUtils.setGlobalHandler((error, isFatal) => {
91
+ try {
92
+ const captured = describeError(error, false);
93
+ captured.fatal = isFatal ?? false;
94
+ onError(captured);
95
+ }
96
+ catch {
97
+ // Reporting must never suppress the app's own crash handling.
98
+ }
99
+ // Always chain. Swallowing this would break every other error reporter
100
+ // and React Native's own red-box, which is not ours to take away.
101
+ previous?.(error, isFatal);
102
+ });
103
+ return () => {
104
+ if (previous)
105
+ errorUtils.setGlobalHandler?.(previous);
106
+ };
107
+ }
108
+ /**
109
+ * The browser half of the same job.
110
+ *
111
+ * An uncaught throw reaches `window` as an `error` event carrying the original
112
+ * value on `event.error`. Listening rather than assigning `window.onerror`:
113
+ * that property holds one handler, so taking it would evict whatever the host
114
+ * already had there.
115
+ *
116
+ * A framework that catches its own errors — Vue does — never lets them reach
117
+ * here, which is why the Vue package also hangs off `app.config.errorHandler`.
118
+ */
119
+ function installErrorEventHandler(onError) {
120
+ const target = globalThis;
121
+ if (typeof target.addEventListener !== 'function') {
122
+ return () => { };
123
+ }
124
+ const handler = (event) => {
125
+ try {
126
+ const thrown = event?.error;
127
+ // Some sources report only a message — a cross-origin script, or a
128
+ // `dispatchEvent` of a bare ErrorEvent. Better a typed message than
129
+ // dropping the error.
130
+ const value = thrown ?? event?.message ?? event;
131
+ onError(describeError(value, false));
132
+ }
133
+ catch {
134
+ // Never interfere with the host's own error handling.
135
+ }
136
+ };
137
+ try {
138
+ target.addEventListener('error', handler);
139
+ }
140
+ catch {
141
+ return () => { };
142
+ }
143
+ return () => {
144
+ try {
145
+ target.removeEventListener?.('error', handler);
146
+ }
147
+ catch {
148
+ // Ignore.
149
+ }
150
+ };
151
+ }
152
+ function installRejectionHandler(onError) {
153
+ const target = globalThis;
154
+ if (typeof target.addEventListener !== 'function') {
155
+ return () => { };
156
+ }
157
+ const handler = (event) => {
158
+ try {
159
+ const reason = event?.reason ?? event;
160
+ const captured = describeError(reason, false);
161
+ captured.type = captured.type === 'Error' ? 'UnhandledRejection' : captured.type;
162
+ onError(captured);
163
+ }
164
+ catch {
165
+ // Never interfere with the host's own rejection handling.
166
+ }
167
+ };
168
+ try {
169
+ target.addEventListener('unhandledrejection', handler);
170
+ }
171
+ catch {
172
+ return () => { };
173
+ }
174
+ return () => {
175
+ try {
176
+ target.removeEventListener?.('unhandledrejection', handler);
177
+ }
178
+ catch {
179
+ // Ignore.
180
+ }
181
+ };
182
+ }
183
+ /** Test-only. */
184
+ export function resetErrorHandlerState() {
185
+ installed = false;
186
+ }
package/dist/ids.d.ts ADDED
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Identifiers and hashing.
3
+ *
4
+ * ponytail: no uuid dependency. A UUID library costs bundle size for a
5
+ * guarantee this does not need — event IDs only have to be unique per device,
6
+ * and the backend deduplicates by `eventId` anyway (section 16).
7
+ */
8
+ /**
9
+ * Generate a prefixed identifier.
10
+ *
11
+ * Timestamp gives ordering and uniqueness across restarts; the random suffix
12
+ * separates events created within the same millisecond, which happens
13
+ * constantly during a burst of captures.
14
+ */
15
+ export declare function createId(prefix: string): string;
16
+ /**
17
+ * FNV-1a, 32-bit.
18
+ *
19
+ * Used only to turn a session ID into a stable sampling decision. Not a
20
+ * security primitive and never used as one.
21
+ */
22
+ export declare function hashString(input: string): number;
23
+ /**
24
+ * Decide whether a session is captured.
25
+ *
26
+ * Deterministic in `sessionId`, so the same session always resolves the same
27
+ * way and the decision can be made once at session start (section 35).
28
+ */
29
+ export declare function isSampled(sessionId: string, sampleRate: number): boolean;
package/dist/ids.js ADDED
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Identifiers and hashing.
3
+ *
4
+ * ponytail: no uuid dependency. A UUID library costs bundle size for a
5
+ * guarantee this does not need — event IDs only have to be unique per device,
6
+ * and the backend deduplicates by `eventId` anyway (section 16).
7
+ */
8
+ /**
9
+ * Generate a prefixed identifier.
10
+ *
11
+ * Timestamp gives ordering and uniqueness across restarts; the random suffix
12
+ * separates events created within the same millisecond, which happens
13
+ * constantly during a burst of captures.
14
+ */
15
+ export function createId(prefix) {
16
+ const time = Date.now().toString(36);
17
+ const random = Math.random().toString(36).slice(2, 10);
18
+ return `${prefix}_${time}${random}`;
19
+ }
20
+ /**
21
+ * FNV-1a, 32-bit.
22
+ *
23
+ * Used only to turn a session ID into a stable sampling decision. Not a
24
+ * security primitive and never used as one.
25
+ */
26
+ export function hashString(input) {
27
+ let hash = 0x811c9dc5;
28
+ for (let i = 0; i < input.length; i += 1) {
29
+ hash ^= input.charCodeAt(i);
30
+ // Math.imul, because a plain `hash * 16777619` exceeds 2^53 and silently
31
+ // loses precision.
32
+ hash = Math.imul(hash, 0x01000193);
33
+ }
34
+ // FNV-1a alone leaves the high bits poorly mixed for short, structurally
35
+ // similar inputs — and the sampling decision reads exactly those bits, so
36
+ // the bias shows up directly as capturing the wrong fraction of sessions.
37
+ // This is MurmurHash3's finalizer, which is the cheap standard fix.
38
+ hash ^= hash >>> 16;
39
+ hash = Math.imul(hash, 0x85ebca6b);
40
+ hash ^= hash >>> 13;
41
+ hash = Math.imul(hash, 0xc2b2ae35);
42
+ hash ^= hash >>> 16;
43
+ return hash >>> 0;
44
+ }
45
+ /**
46
+ * Decide whether a session is captured.
47
+ *
48
+ * Deterministic in `sessionId`, so the same session always resolves the same
49
+ * way and the decision can be made once at session start (section 35).
50
+ */
51
+ export function isSampled(sessionId, sampleRate) {
52
+ if (sampleRate >= 1)
53
+ return true;
54
+ if (sampleRate <= 0)
55
+ return false;
56
+ // 32-bit space scaled to [0, 1).
57
+ return hashString(sessionId) / 0x100000000 < sampleRate;
58
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * @nagoorkani/session-capture-core
3
+ *
4
+ * Everything the SDK does that is not about a platform: sessions, sampling,
5
+ * batching, the durable queue, redaction, remote config, transport, and the
6
+ * error/network/performance capture that hangs off globals a browser and a
7
+ * React Native runtime both provide.
8
+ *
9
+ * It installs nothing by itself and imports no platform module. A platform
10
+ * package — `@nagoorkani/session-capture-expo`, `@nagoorkani/session-capture-vue` — supplies the
11
+ * three things that genuinely differ: where bytes are stored, how the host
12
+ * signals foreground and background, and what the device is. Everything else
13
+ * living here rather than in each of them is the point: a second copy of the
14
+ * redaction and sampling rules is exactly the drift the privacy invariant
15
+ * exists to prevent.
16
+ *
17
+ * Re-exported wholesale rather than curated. The consumers are the platform
18
+ * packages in this repository, not the public — each of those exports its own
19
+ * narrow surface, and a hand-picked list here would be a third one to keep in
20
+ * step.
21
+ */
22
+ export * from './batcher.ts';
23
+ export * from './breadcrumbs.ts';
24
+ export * from './config.ts';
25
+ export * from './container.ts';
26
+ export * from './core.ts';
27
+ export * from './dispatcher.ts';
28
+ export * from './errors.ts';
29
+ export * from './ids.ts';
30
+ export * from './network.ts';
31
+ export * from './performance.ts';
32
+ export * from './queue.ts';
33
+ export * from './redact.ts';
34
+ export * from './replay-gate.ts';
35
+ export * from './safe.ts';
36
+ export * from './session.ts';
37
+ export * from './store.ts';
38
+ export * from './transport.ts';
39
+ export * from './types.ts';
package/dist/index.js ADDED
@@ -0,0 +1,39 @@
1
+ /**
2
+ * @nagoorkani/session-capture-core
3
+ *
4
+ * Everything the SDK does that is not about a platform: sessions, sampling,
5
+ * batching, the durable queue, redaction, remote config, transport, and the
6
+ * error/network/performance capture that hangs off globals a browser and a
7
+ * React Native runtime both provide.
8
+ *
9
+ * It installs nothing by itself and imports no platform module. A platform
10
+ * package — `@nagoorkani/session-capture-expo`, `@nagoorkani/session-capture-vue` — supplies the
11
+ * three things that genuinely differ: where bytes are stored, how the host
12
+ * signals foreground and background, and what the device is. Everything else
13
+ * living here rather than in each of them is the point: a second copy of the
14
+ * redaction and sampling rules is exactly the drift the privacy invariant
15
+ * exists to prevent.
16
+ *
17
+ * Re-exported wholesale rather than curated. The consumers are the platform
18
+ * packages in this repository, not the public — each of those exports its own
19
+ * narrow surface, and a hand-picked list here would be a third one to keep in
20
+ * step.
21
+ */
22
+ export * from "./batcher.js";
23
+ export * from "./breadcrumbs.js";
24
+ export * from "./config.js";
25
+ export * from "./container.js";
26
+ export * from "./core.js";
27
+ export * from "./dispatcher.js";
28
+ export * from "./errors.js";
29
+ export * from "./ids.js";
30
+ export * from "./network.js";
31
+ export * from "./performance.js";
32
+ export * from "./queue.js";
33
+ export * from "./redact.js";
34
+ export * from "./replay-gate.js";
35
+ export * from "./safe.js";
36
+ export * from "./session.js";
37
+ export * from "./store.js";
38
+ export * from "./transport.js";
39
+ export * from "./types.js";
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Network capture.
3
+ *
4
+ * This module monkey-patches `XMLHttpRequest` inside someone else's
5
+ * application. It is the most dangerous code in the SDK, so the rules from
6
+ * section 24 are non-negotiable:
7
+ *
8
+ * - patch once, idempotently — double-wrapping doubles every event
9
+ * - always call through to the original
10
+ * - never swallow an error the app expects to receive
11
+ * - never capture bodies by default
12
+ * - apply the header deny-list at capture time, not later
13
+ * - skip requests to the ingestion endpoint itself
14
+ *
15
+ * That last rule is not optional: without it the SDK observes its own uploads
16
+ * and generates telemetry about generating telemetry, forever.
17
+ *
18
+ * ## Both, because there is no single choke point
19
+ *
20
+ * Bare React Native's `fetch` is `whatwg-fetch`, which runs on top of
21
+ * `XMLHttpRequest` — so an XHR patch sees it. Expo replaces `globalThis.fetch`
22
+ * with a native implementation (`expo/src/winter/runtime.native.ts` installs
23
+ * `expo/fetch` unless `EXPO_PUBLIC_USE_RN_FETCH=1`), and that one never
24
+ * touches XHR. Patching only XHR makes every `fetch()` in an Expo app
25
+ * invisible; patching only `fetch` makes axios and every other XHR client
26
+ * invisible. Both get patched.
27
+ *
28
+ * The two hand off so nothing is reported twice. `whatwg-fetch` calls
29
+ * `xhr.open`/`xhr.send` synchronously inside the Promise executor, so the
30
+ * moment `fetch` returns its promise we already know whether an XHR served it.
31
+ * If one did, the XHR side reports — it has response headers and a buffered
32
+ * body — and the fetch side stays quiet. If none did, the request was native
33
+ * and the fetch side reports.
34
+ *
35
+ * A fetch polyfill that reached XHR *asynchronously* would defeat that and be
36
+ * counted twice. `whatwg-fetch` does not, and it is the only XHR-backed fetch
37
+ * in play.
38
+ */
39
+ /**
40
+ * Minimal structural types for the fetch surface.
41
+ *
42
+ * The DOM lib is deliberately not enabled: React Native is not a browser, and
43
+ * pulling in `lib.dom` would declare hundreds of globals that do not exist at
44
+ * runtime. These cover exactly what is touched here.
45
+ */
46
+ type HeaderPairs = readonly (readonly [string, string])[];
47
+ type HeaderLike = {
48
+ forEach: (cb: (value: string, key: string) => void) => void;
49
+ };
50
+ export type HeadersInput = HeaderPairs | HeaderLike | Record<string, string>;
51
+ export interface RequestOptions {
52
+ method?: string;
53
+ headers?: HeadersInput;
54
+ [key: string]: unknown;
55
+ }
56
+ export interface ResponseLike {
57
+ status: number;
58
+ /** WHATWG `Headers`. Reading it does not consume the body. */
59
+ headers?: HeaderLike;
60
+ /** Present on any WHATWG Response. Absent on a hand-rolled stub. */
61
+ clone?: () => {
62
+ text: () => Promise<string>;
63
+ };
64
+ }
65
+ export type FetchLike = (input: unknown, init?: RequestOptions) => Promise<ResponseLike>;
66
+ export interface NetworkEvent {
67
+ url: string;
68
+ method: string;
69
+ status?: number;
70
+ durationMs: number;
71
+ /** Set when the request failed before producing a response. */
72
+ error?: string;
73
+ requestHeaders?: Record<string, unknown>;
74
+ /** XHR only. The fetch fallback cannot see these without holding the response. */
75
+ responseHeaders?: Record<string, unknown>;
76
+ /** Only when `captureBodies` is on, and only for a shape that can be redacted. */
77
+ requestBody?: string;
78
+ responseBody?: string;
79
+ }
80
+ /**
81
+ * Minimal structural types for the XHR surface, for the same reason the fetch
82
+ * ones exist above: `lib.dom` is off.
83
+ */
84
+ export interface XhrLike {
85
+ open(method: string, url: string, ...rest: unknown[]): void;
86
+ send(body?: unknown): void;
87
+ setRequestHeader(name: string, value: string): void;
88
+ addEventListener(type: string, listener: () => void): void;
89
+ getAllResponseHeaders(): string;
90
+ readonly status: number;
91
+ readonly responseType: string;
92
+ readonly responseText: string;
93
+ }
94
+ export interface NetworkOptions {
95
+ /** Requests to this origin are never captured. */
96
+ ingestEndpoint: string;
97
+ urlDenyList: readonly string[];
98
+ maskedKeys: readonly string[];
99
+ /**
100
+ * Per-project, from remote config, off by default (section 36).
101
+ *
102
+ * Optional on purpose: a caller that forgets it gets no body capture, which
103
+ * is the safe direction to fail in.
104
+ */
105
+ captureBodies?: boolean;
106
+ onEvent: (event: NetworkEvent) => void;
107
+ now?: () => number;
108
+ }
109
+ type Uninstall = () => void;
110
+ /** Strip query strings before capture: they routinely carry tokens. */
111
+ export declare function sanitizeUrl(url: string): string;
112
+ export declare function shouldCapture(url: string, ingestEndpoint: string, denyList: readonly string[]): boolean;
113
+ /**
114
+ * Install network capture.
115
+ *
116
+ * XHR when the host has it, which in React Native it always does. The `fetch`
117
+ * path is the fallback for a host that does not, and the two are never
118
+ * installed together — see the note at the top of this file.
119
+ *
120
+ * Returns a function that restores the originals.
121
+ */
122
+ export declare function installNetworkCapture(options: NetworkOptions): Uninstall;
123
+ export {};