@spotify-confidence/session-recording 0.0.0 → 0.17.2

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+//#region ../csr-common/src/events.d.ts
+type ConsoleLogLevel = "log" | "warn" | "error" | "debug" | "info";
+//#endregion
+//#region ../csr-common/src/uploader/client-context.d.ts
+/**
+* JSON-shaped values accepted in a Context — matches `google.protobuf.Struct`.
+*/
+type ContextValue = string | number | boolean | null | ContextValue[] | {
+  [key: string]: ContextValue;
+};
+/**
+* Browser-environment metadata captured at session init. Sent verbatim in the
+* `context` field of the InitSession request.
+*/
+type UserAgentContext = {
+  userAgent?: string; /** Coarse OS family — `windows`, `macos`, `ios`, `android`, `linux`, or `unknown`. */
+  os?: string; /** Coarse browser family — `chrome`, `firefox`, `safari`, `edge`, or `unknown`. */
+  browser?: string; /** Browser major version. */
+  browserVersion?: string;
+  mobile?: boolean; /** BCP-47 language tag (e.g. `en-US`). */
+  languageCode?: string; /** IANA time zone (e.g. `Europe/Stockholm`). */
+  timeZone?: string; /** Viewport in CSS pixels. */
+  viewportWidth?: number;
+  viewportHeight?: number; /** Physical screen in CSS pixels. */
+  screenWidth?: number;
+  screenHeight?: number;
+  devicePixelRatio?: number; /** Initial document URI — without query/hash to avoid leaking PII. */
+  uri?: string;
+  referrer?: string;
+};
+interface ClientContext {
+  userAgent?: UserAgentContext;
+  [key: string]: ContextValue | undefined;
+}
+//#endregion
+//#region src/index.d.ts
+interface InitSessionRecorderOptions {
+  /** Per-tenant secret. */
+  clientSecret: string;
+  /** End-user identifier (visitor / device id). */
+  targetingKey?: string;
+  /** CSS selectors whose text content should be masked. */
+  maskSelectors?: string[];
+  /** CSS selectors whose subtrees should be blocked (replaced with a placeholder, never serialized). */
+  blockSelectors?: string[];
+  /** Mask values of every `<input>` / `<textarea>` / `contenteditable`. Defaults to `true`. */
+  maskInputs?: boolean;
+  /** Capture browser console output. Defaults to `false`. Pass `true` for all levels or `{ levels: [...] }` for specific ones. */
+  captureConsoleLogs?: boolean | {
+    levels: ConsoleLogLevel[];
+  };
+  /** Capture fetch/XHR metadata (method, URL, status, duration). Defaults to `false`. */
+  captureNetworkRequests?: boolean;
+  /** Capture client-side route changes (pathname only). Defaults to `true`. */
+  captureRouteChanges?: boolean;
+  /** Backend base URL. Defaults to the Confidence production endpoint. */
+  apiUrl?: string;
+  /** WebSocket ingest URL. Defaults to the Confidence production endpoint. */
+  websocketUrl?: string;
+  /** Application version or commit hash, e.g. "1.2.3" or "abc1234". Stored on the recording for filtering. */
+  appVersion?: string;
+  /** Custom dimensions merged into the session context alongside auto-collected browser metadata. */
+  context?: ClientContext;
+  /**
+  * `'automatic'` (default) — starts recording as soon as the session is established.
+  * `'manual'` — does nothing until `start()` is called, bypassing sampling and targeting rules.
+  */
+  mode?: "automatic" | "manual";
+  /** Verbose tracer for debugging — called with one-line lifecycle/transport messages. */
+  debugLogger?: (msg: string) => void;
+}
+interface SessionRecorder {
+  /** Start recording. In `automatic` mode this is a no-op. In `manual` mode it establishes a session and begins recording. */
+  start(): void;
+  /** Stop recording permanently. Idempotent. */
+  stop(): void;
+  /** Attach a custom tag to this recording. Tags with the same key accumulate values. Omit value for a valueless marker. */
+  tag(key: string, value?: string): void;
+  /** Record a numeric measurement. Measurements with the same key are summed. Omit value to count occurrences (each call adds 1). */
+  measure(key: string, value?: number): void;
+  /** Whether the recorder is actively capturing events. */
+  readonly isRecording: boolean;
+}
+/**
+* Create a session recorder. In `automatic` mode (default) recording begins
+* as soon as a session is established. In `manual` mode nothing happens
+* until {@link SessionRecorder.start} is called.
+*
+* Always returns a {@link SessionRecorder} — safe to call, never throws.
+*/
+declare function initSessionRecorder(options: InitSessionRecorderOptions): SessionRecorder;
+//#endregion
+export { InitSessionRecorderOptions, SessionRecorder, initSessionRecorder };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+//#region ../csr-common/src/events.d.ts
+type ConsoleLogLevel = "log" | "warn" | "error" | "debug" | "info";
+//#endregion
+//#region ../csr-common/src/uploader/client-context.d.ts
+/**
+* JSON-shaped values accepted in a Context — matches `google.protobuf.Struct`.
+*/
+type ContextValue = string | number | boolean | null | ContextValue[] | {
+  [key: string]: ContextValue;
+};
+/**
+* Browser-environment metadata captured at session init. Sent verbatim in the
+* `context` field of the InitSession request.
+*/
+type UserAgentContext = {
+  userAgent?: string; /** Coarse OS family — `windows`, `macos`, `ios`, `android`, `linux`, or `unknown`. */
+  os?: string; /** Coarse browser family — `chrome`, `firefox`, `safari`, `edge`, or `unknown`. */
+  browser?: string; /** Browser major version. */
+  browserVersion?: string;
+  mobile?: boolean; /** BCP-47 language tag (e.g. `en-US`). */
+  languageCode?: string; /** IANA time zone (e.g. `Europe/Stockholm`). */
+  timeZone?: string; /** Viewport in CSS pixels. */
+  viewportWidth?: number;
+  viewportHeight?: number; /** Physical screen in CSS pixels. */
+  screenWidth?: number;
+  screenHeight?: number;
+  devicePixelRatio?: number; /** Initial document URI — without query/hash to avoid leaking PII. */
+  uri?: string;
+  referrer?: string;
+};
+interface ClientContext {
+  userAgent?: UserAgentContext;
+  [key: string]: ContextValue | undefined;
+}
+//#endregion
+//#region src/index.d.ts
+interface InitSessionRecorderOptions {
+  /** Per-tenant secret. */
+  clientSecret: string;
+  /** End-user identifier (visitor / device id). */
+  targetingKey?: string;
+  /** CSS selectors whose text content should be masked. */
+  maskSelectors?: string[];
+  /** CSS selectors whose subtrees should be blocked (replaced with a placeholder, never serialized). */
+  blockSelectors?: string[];
+  /** Mask values of every `<input>` / `<textarea>` / `contenteditable`. Defaults to `true`. */
+  maskInputs?: boolean;
+  /** Capture browser console output. Defaults to `false`. Pass `true` for all levels or `{ levels: [...] }` for specific ones. */
+  captureConsoleLogs?: boolean | {
+    levels: ConsoleLogLevel[];
+  };
+  /** Capture fetch/XHR metadata (method, URL, status, duration). Defaults to `false`. */
+  captureNetworkRequests?: boolean;
+  /** Capture client-side route changes (pathname only). Defaults to `true`. */
+  captureRouteChanges?: boolean;
+  /** Backend base URL. Defaults to the Confidence production endpoint. */
+  apiUrl?: string;
+  /** WebSocket ingest URL. Defaults to the Confidence production endpoint. */
+  websocketUrl?: string;
+  /** Application version or commit hash, e.g. "1.2.3" or "abc1234". Stored on the recording for filtering. */
+  appVersion?: string;
+  /** Custom dimensions merged into the session context alongside auto-collected browser metadata. */
+  context?: ClientContext;
+  /**
+  * `'automatic'` (default) — starts recording as soon as the session is established.
+  * `'manual'` — does nothing until `start()` is called, bypassing sampling and targeting rules.
+  */
+  mode?: "automatic" | "manual";
+  /** Verbose tracer for debugging — called with one-line lifecycle/transport messages. */
+  debugLogger?: (msg: string) => void;
+}
+interface SessionRecorder {
+  /** Start recording. In `automatic` mode this is a no-op. In `manual` mode it establishes a session and begins recording. */
+  start(): void;
+  /** Stop recording permanently. Idempotent. */
+  stop(): void;
+  /** Attach a custom tag to this recording. Tags with the same key accumulate values. Omit value for a valueless marker. */
+  tag(key: string, value?: string): void;
+  /** Record a numeric measurement. Measurements with the same key are summed. Omit value to count occurrences (each call adds 1). */
+  measure(key: string, value?: number): void;
+  /** Whether the recorder is actively capturing events. */
+  readonly isRecording: boolean;
+}
+/**
+* Create a session recorder. In `automatic` mode (default) recording begins
+* as soon as a session is established. In `manual` mode nothing happens
+* until {@link SessionRecorder.start} is called.
+*
+* Always returns a {@link SessionRecorder} — safe to call, never throws.
+*/
+declare function initSessionRecorder(options: InitSessionRecorderOptions): SessionRecorder;
+//#endregion
+export { InitSessionRecorderOptions, SessionRecorder, initSessionRecorder };