@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.
- package/LICENSE +25 -0
- package/README.md +42 -0
- package/dist/batcher.d.ts +58 -0
- package/dist/batcher.js +106 -0
- package/dist/breadcrumbs.d.ts +22 -0
- package/dist/breadcrumbs.js +45 -0
- package/dist/config.d.ts +60 -0
- package/dist/config.js +134 -0
- package/dist/container.d.ts +33 -0
- package/dist/container.js +48 -0
- package/dist/core.d.ts +175 -0
- package/dist/core.js +414 -0
- package/dist/dispatcher.d.ts +43 -0
- package/dist/dispatcher.js +74 -0
- package/dist/errors.d.ts +40 -0
- package/dist/errors.js +186 -0
- package/dist/ids.d.ts +29 -0
- package/dist/ids.js +58 -0
- package/dist/index.d.ts +39 -0
- package/dist/index.js +39 -0
- package/dist/network.d.ts +123 -0
- package/dist/network.js +510 -0
- package/dist/performance.d.ts +33 -0
- package/dist/performance.js +54 -0
- package/dist/queue.d.ts +70 -0
- package/dist/queue.js +105 -0
- package/dist/redact.d.ts +19 -0
- package/dist/redact.js +61 -0
- package/dist/replay-gate.d.ts +69 -0
- package/dist/replay-gate.js +78 -0
- package/dist/safe.d.ts +26 -0
- package/dist/safe.js +88 -0
- package/dist/session.d.ts +80 -0
- package/dist/session.js +111 -0
- package/dist/store.d.ts +44 -0
- package/dist/store.js +49 -0
- package/dist/transport.d.ts +62 -0
- package/dist/transport.js +84 -0
- package/dist/types.d.ts +92 -0
- package/dist/types.js +26 -0
- package/package.json +45 -0
package/dist/store.js
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Durable storage boundary.
|
|
3
|
+
*
|
|
4
|
+
* Deliberately tiny — four operations. The queue is written against this, not
|
|
5
|
+
* against `expo-file-system`, so swapping API generations (or dropping to
|
|
6
|
+
* memory when persistence is unavailable) is a one-file change and the queue
|
|
7
|
+
* logic stays testable in Node.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Storage directories.
|
|
11
|
+
*
|
|
12
|
+
* Named here rather than in `store-expo.ts` because that module statically
|
|
13
|
+
* imports `expo-file-system`, which Node cannot load — anything importing it
|
|
14
|
+
* is device-only, tests included.
|
|
15
|
+
*
|
|
16
|
+
* The queue and the config cache must never share a directory:
|
|
17
|
+
* `SendQueue.peek()` treats every file it can see as a queued batch and
|
|
18
|
+
* deletes whatever fails to parse as one.
|
|
19
|
+
*/
|
|
20
|
+
export const QUEUE_DIR = 'session-capture-queue';
|
|
21
|
+
export const CONFIG_DIR = 'session-capture-config';
|
|
22
|
+
/**
|
|
23
|
+
* In-memory fallback.
|
|
24
|
+
*
|
|
25
|
+
* Used by tests, and on any platform where persistence is unavailable. Losing
|
|
26
|
+
* events on process death is bad; refusing to start is worse, so the SDK
|
|
27
|
+
* degrades rather than throwing (section 24).
|
|
28
|
+
*/
|
|
29
|
+
export class MemoryStore {
|
|
30
|
+
constructor() {
|
|
31
|
+
this.entries = new Map();
|
|
32
|
+
}
|
|
33
|
+
async list() {
|
|
34
|
+
return [...this.entries.keys()].sort();
|
|
35
|
+
}
|
|
36
|
+
async read(name) {
|
|
37
|
+
return this.entries.get(name) ?? null;
|
|
38
|
+
}
|
|
39
|
+
async write(name, contents) {
|
|
40
|
+
this.entries.set(name, contents);
|
|
41
|
+
}
|
|
42
|
+
async remove(name) {
|
|
43
|
+
this.entries.delete(name);
|
|
44
|
+
}
|
|
45
|
+
/** Test helper. */
|
|
46
|
+
get size() {
|
|
47
|
+
return this.entries.size;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Delivery: classification, backoff, and backpressure.
|
|
3
|
+
*
|
|
4
|
+
* The distinction that matters most here is retryable versus permanent. A
|
|
5
|
+
* batch the server will never accept — malformed, wrong project, unsupported
|
|
6
|
+
* schema — must be discarded, not retried. Retrying it forever is the poison
|
|
7
|
+
* message pattern, and on a mobile client it burns the user's battery and data
|
|
8
|
+
* to achieve nothing (section 30).
|
|
9
|
+
*/
|
|
10
|
+
import type { EventBatch } from './types.ts';
|
|
11
|
+
export type SendOutcome = {
|
|
12
|
+
kind: 'sent';
|
|
13
|
+
}
|
|
14
|
+
/** Try again later. `retryAfterMs` is set when the server asked for a delay. */
|
|
15
|
+
| {
|
|
16
|
+
kind: 'retry';
|
|
17
|
+
reason: string;
|
|
18
|
+
retryAfterMs?: number;
|
|
19
|
+
}
|
|
20
|
+
/** Never going to succeed. Discard. */
|
|
21
|
+
| {
|
|
22
|
+
kind: 'permanent';
|
|
23
|
+
reason: string;
|
|
24
|
+
};
|
|
25
|
+
export interface TransportOptions {
|
|
26
|
+
endpoint: string;
|
|
27
|
+
apiKey: string;
|
|
28
|
+
sdkVersion: string;
|
|
29
|
+
fetchImpl?: typeof fetch;
|
|
30
|
+
/**
|
|
31
|
+
* Ask the platform to finish this request even if the page goes away.
|
|
32
|
+
*
|
|
33
|
+
* The web's exit path: a `fetch` started while a tab is closing is normally
|
|
34
|
+
* killed mid-flight, and `keepalive` is the promise that it will not be. It
|
|
35
|
+
* caps the body at 64 KB — over that the request rejects, the batch is
|
|
36
|
+
* treated as needing a retry, and it stays queued for the next visit, which
|
|
37
|
+
* is the right answer either way.
|
|
38
|
+
*
|
|
39
|
+
* Read on every send rather than captured, so a caller can flip it on for
|
|
40
|
+
* the last drain and leave it off for the ordinary ones.
|
|
41
|
+
*/
|
|
42
|
+
readonly keepalive?: boolean;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Decide what a status code means for a queued batch.
|
|
46
|
+
*
|
|
47
|
+
* - 2xx delivered
|
|
48
|
+
* - 408, 425, 429, 5xx transient; the server may accept it later
|
|
49
|
+
* - other 4xx the request itself is wrong and will stay wrong
|
|
50
|
+
*/
|
|
51
|
+
export declare function classifyStatus(status: number): SendOutcome;
|
|
52
|
+
/** Parse `Retry-After`, which may be seconds or an HTTP date. */
|
|
53
|
+
export declare function parseRetryAfter(value: string | null, now?: number): number | undefined;
|
|
54
|
+
/**
|
|
55
|
+
* Exponential backoff with full jitter.
|
|
56
|
+
*
|
|
57
|
+
* Jitter is not decoration. Without it, every device that failed during an
|
|
58
|
+
* outage retries at the same instant when the service returns, and the
|
|
59
|
+
* thundering herd knocks it straight back over.
|
|
60
|
+
*/
|
|
61
|
+
export declare function backoffDelay(attempts: number, random?: () => number): number;
|
|
62
|
+
export declare function sendBatch(options: TransportOptions, batch: EventBatch): Promise<SendOutcome>;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Delivery: classification, backoff, and backpressure.
|
|
3
|
+
*
|
|
4
|
+
* The distinction that matters most here is retryable versus permanent. A
|
|
5
|
+
* batch the server will never accept — malformed, wrong project, unsupported
|
|
6
|
+
* schema — must be discarded, not retried. Retrying it forever is the poison
|
|
7
|
+
* message pattern, and on a mobile client it burns the user's battery and data
|
|
8
|
+
* to achieve nothing (section 30).
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Decide what a status code means for a queued batch.
|
|
12
|
+
*
|
|
13
|
+
* - 2xx delivered
|
|
14
|
+
* - 408, 425, 429, 5xx transient; the server may accept it later
|
|
15
|
+
* - other 4xx the request itself is wrong and will stay wrong
|
|
16
|
+
*/
|
|
17
|
+
export function classifyStatus(status) {
|
|
18
|
+
if (status >= 200 && status < 300) {
|
|
19
|
+
return { kind: 'sent' };
|
|
20
|
+
}
|
|
21
|
+
if (status === 408 || status === 425 || status === 429 || status >= 500) {
|
|
22
|
+
return { kind: 'retry', reason: `http ${status}` };
|
|
23
|
+
}
|
|
24
|
+
// 401 included deliberately: a revoked key is not fixed by retrying, and
|
|
25
|
+
// hammering an endpoint with a dead credential is how a client gets blocked.
|
|
26
|
+
return { kind: 'permanent', reason: `http ${status}` };
|
|
27
|
+
}
|
|
28
|
+
/** Parse `Retry-After`, which may be seconds or an HTTP date. */
|
|
29
|
+
export function parseRetryAfter(value, now = Date.now()) {
|
|
30
|
+
if (!value)
|
|
31
|
+
return undefined;
|
|
32
|
+
const seconds = Number(value);
|
|
33
|
+
if (Number.isFinite(seconds)) {
|
|
34
|
+
return Math.max(0, seconds * 1000);
|
|
35
|
+
}
|
|
36
|
+
const when = Date.parse(value);
|
|
37
|
+
return Number.isNaN(when) ? undefined : Math.max(0, when - now);
|
|
38
|
+
}
|
|
39
|
+
const BASE_DELAY_MS = 1000;
|
|
40
|
+
const MAX_DELAY_MS = 5 * 60 * 1000;
|
|
41
|
+
/**
|
|
42
|
+
* Exponential backoff with full jitter.
|
|
43
|
+
*
|
|
44
|
+
* Jitter is not decoration. Without it, every device that failed during an
|
|
45
|
+
* outage retries at the same instant when the service returns, and the
|
|
46
|
+
* thundering herd knocks it straight back over.
|
|
47
|
+
*/
|
|
48
|
+
export function backoffDelay(attempts, random = Math.random) {
|
|
49
|
+
const exponential = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.max(0, attempts));
|
|
50
|
+
return Math.floor(random() * exponential);
|
|
51
|
+
}
|
|
52
|
+
export async function sendBatch(options, batch) {
|
|
53
|
+
const doFetch = options.fetchImpl ?? fetch;
|
|
54
|
+
const url = `${options.endpoint.replace(/\/$/, '')}/v1/mobile/events`;
|
|
55
|
+
let response;
|
|
56
|
+
try {
|
|
57
|
+
response = await doFetch(url, {
|
|
58
|
+
method: 'POST',
|
|
59
|
+
headers: {
|
|
60
|
+
'content-type': 'application/json',
|
|
61
|
+
authorization: `Bearer ${options.apiKey}`,
|
|
62
|
+
'x-sdk-version': options.sdkVersion,
|
|
63
|
+
},
|
|
64
|
+
body: JSON.stringify(batch),
|
|
65
|
+
// Ignored by runtimes that do not know it, which is what makes it safe
|
|
66
|
+
// to send unconditionally from a shared transport.
|
|
67
|
+
keepalive: options.keepalive === true,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
catch (err) {
|
|
71
|
+
// No response at all: offline, DNS failure, TLS problem. Always worth
|
|
72
|
+
// retrying — this is the case the durable queue exists for.
|
|
73
|
+
return {
|
|
74
|
+
kind: 'retry',
|
|
75
|
+
reason: err instanceof Error ? err.message : 'network error',
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
const outcome = classifyStatus(response.status);
|
|
79
|
+
if (outcome.kind === 'retry') {
|
|
80
|
+
const retryAfterMs = parseRetryAfter(typeof response.headers?.get === 'function' ? response.headers.get('retry-after') : null);
|
|
81
|
+
return retryAfterMs === undefined ? outcome : { ...outcome, retryAfterMs };
|
|
82
|
+
}
|
|
83
|
+
return outcome;
|
|
84
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire format types.
|
|
3
|
+
*
|
|
4
|
+
* `crates/event-schema` is the source of truth (section 51). These are
|
|
5
|
+
* hand-written for Phase 1; Phase 2 generates them from that crate so the two
|
|
6
|
+
* cannot drift. Drift here surfaces as malformed events from production
|
|
7
|
+
* devices — undebuggable from the field, and unfixable on apps that already
|
|
8
|
+
* shipped.
|
|
9
|
+
*/
|
|
10
|
+
/** Current wire format version. */
|
|
11
|
+
export declare const SCHEMA_VERSION: 1;
|
|
12
|
+
export type EventType = 'session_start' | 'session_end' | 'screen_view' | 'user_action' | 'navigation' | 'network_request' | 'error' | 'performance' | 'lifecycle' | 'breadcrumb' | 'custom';
|
|
13
|
+
/** Event types that are always captured, regardless of sample rate. */
|
|
14
|
+
export declare const UNSAMPLED_TYPES: readonly EventType[];
|
|
15
|
+
export interface CaptureEvent {
|
|
16
|
+
/** Idempotency identifier. The backend tolerates duplicates (section 16). */
|
|
17
|
+
id: string;
|
|
18
|
+
type: EventType;
|
|
19
|
+
sessionId: string;
|
|
20
|
+
/**
|
|
21
|
+
* Monotonic within a session. This — not `timestamp` — is what orders the
|
|
22
|
+
* timeline. Device clocks are frequently wrong (section 15).
|
|
23
|
+
*/
|
|
24
|
+
sequence: number;
|
|
25
|
+
/** Device clock, milliseconds. Display only. */
|
|
26
|
+
timestamp: number;
|
|
27
|
+
data?: Record<string, unknown>;
|
|
28
|
+
}
|
|
29
|
+
export interface EventBatch {
|
|
30
|
+
schemaVersion: typeof SCHEMA_VERSION;
|
|
31
|
+
projectId: string;
|
|
32
|
+
sdkVersion: string;
|
|
33
|
+
/** Device clock when sent. The server computes skew against its own. */
|
|
34
|
+
sentAt: number;
|
|
35
|
+
events: CaptureEvent[];
|
|
36
|
+
}
|
|
37
|
+
/** Options accepted by `init`. */
|
|
38
|
+
export interface InitOptions {
|
|
39
|
+
/**
|
|
40
|
+
* Ingestion key. NOT a secret — it is extractable from any shipped binary
|
|
41
|
+
* and may only write events, never read them (section 34).
|
|
42
|
+
*/
|
|
43
|
+
apiKey: string;
|
|
44
|
+
/**
|
|
45
|
+
* Sent on every batch. The server still validates it against the API key
|
|
46
|
+
* binding rather than trusting it (section 37).
|
|
47
|
+
*/
|
|
48
|
+
projectId: string;
|
|
49
|
+
endpoint: string;
|
|
50
|
+
/**
|
|
51
|
+
* Start disabled and enable later once consent is obtained. While disabled
|
|
52
|
+
* nothing is captured *or* buffered (section 36).
|
|
53
|
+
*/
|
|
54
|
+
enabled?: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Your app's version. Attached to session_start so errors and sessions can
|
|
57
|
+
* be attributed to a release.
|
|
58
|
+
*/
|
|
59
|
+
appVersion?: string;
|
|
60
|
+
/**
|
|
61
|
+
* Patch `fetch` to capture requests. Defaults to true.
|
|
62
|
+
*
|
|
63
|
+
* Set false for apps that already instrument their network layer, or where
|
|
64
|
+
* patching a global is unacceptable.
|
|
65
|
+
*/
|
|
66
|
+
captureNetwork?: boolean;
|
|
67
|
+
/** Overridden by remote config when it loads. */
|
|
68
|
+
debug?: boolean;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Delivered by `GET /v1/config`, cached to disk, refetched periodically.
|
|
72
|
+
*
|
|
73
|
+
* `enabled: false` is the kill switch — the only way to stop an SDK that has
|
|
74
|
+
* already shipped inside someone else's app (section 39).
|
|
75
|
+
*/
|
|
76
|
+
export interface RemoteConfig {
|
|
77
|
+
enabled: boolean;
|
|
78
|
+
/** Session-level. Decided once at session start, never per event. */
|
|
79
|
+
sampleRate: number;
|
|
80
|
+
batchSize: number;
|
|
81
|
+
flushIntervalMs: number;
|
|
82
|
+
maskedKeys: string[];
|
|
83
|
+
urlDenyList: string[];
|
|
84
|
+
captureBodies: boolean;
|
|
85
|
+
/** Continuous visual replay, for the optional replay package (section 23). */
|
|
86
|
+
replayEnabled: boolean;
|
|
87
|
+
/** Session-level, like `sampleRate`. Decided once at session start. */
|
|
88
|
+
replaySampleRate: number;
|
|
89
|
+
configVersion: number;
|
|
90
|
+
}
|
|
91
|
+
/** Used until remote config loads, and whenever fetching it fails. */
|
|
92
|
+
export declare const DEFAULT_CONFIG: RemoteConfig;
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire format types.
|
|
3
|
+
*
|
|
4
|
+
* `crates/event-schema` is the source of truth (section 51). These are
|
|
5
|
+
* hand-written for Phase 1; Phase 2 generates them from that crate so the two
|
|
6
|
+
* cannot drift. Drift here surfaces as malformed events from production
|
|
7
|
+
* devices — undebuggable from the field, and unfixable on apps that already
|
|
8
|
+
* shipped.
|
|
9
|
+
*/
|
|
10
|
+
/** Current wire format version. */
|
|
11
|
+
export const SCHEMA_VERSION = 1;
|
|
12
|
+
/** Event types that are always captured, regardless of sample rate. */
|
|
13
|
+
export const UNSAMPLED_TYPES = ['error'];
|
|
14
|
+
/** Used until remote config loads, and whenever fetching it fails. */
|
|
15
|
+
export const DEFAULT_CONFIG = {
|
|
16
|
+
enabled: true,
|
|
17
|
+
sampleRate: 1.0,
|
|
18
|
+
batchSize: 50,
|
|
19
|
+
flushIntervalMs: 10000,
|
|
20
|
+
maskedKeys: [],
|
|
21
|
+
urlDenyList: [],
|
|
22
|
+
captureBodies: false,
|
|
23
|
+
replayEnabled: false,
|
|
24
|
+
replaySampleRate: 0,
|
|
25
|
+
configVersion: 0,
|
|
26
|
+
};
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@nagoorkani/session-capture-core",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Platform-free core for the session-capture SDKs",
|
|
5
|
+
"license": "UNLICENSED",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"default": "./dist/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"sideEffects": false,
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"README.md",
|
|
19
|
+
"LICENSE"
|
|
20
|
+
],
|
|
21
|
+
"devDependencies": {
|
|
22
|
+
"@types/node": "^22.0.0",
|
|
23
|
+
"typescript": "^5.6.0"
|
|
24
|
+
},
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=22.6"
|
|
27
|
+
},
|
|
28
|
+
"publishConfig": {
|
|
29
|
+
"access": "public"
|
|
30
|
+
},
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/Nagoorkani2393/session-capture.git",
|
|
34
|
+
"directory": "sdk/core"
|
|
35
|
+
},
|
|
36
|
+
"homepage": "https://github.com/Nagoorkani2393/session-capture/tree/main/sdk/core#readme",
|
|
37
|
+
"bugs": {
|
|
38
|
+
"url": "https://github.com/Nagoorkani2393/session-capture/issues"
|
|
39
|
+
},
|
|
40
|
+
"scripts": {
|
|
41
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
42
|
+
"typecheck": "tsc --noEmit",
|
|
43
|
+
"test": "node --test --experimental-strip-types \"src/**/*.test.ts\""
|
|
44
|
+
}
|
|
45
|
+
}
|