@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/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
+ }
@@ -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
+ }