@dash0/sdk-web 0.23.0 → 0.25.0

package/src/api/start-view_test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { KeyValue, LogRecord } from "../types/otlp";
+
+vi.mock("../transport", () => ({
+  sendLog: vi.fn(),
+}));
+
+import { sendLog } from "../transport";
+import { startView } from "./start-view";
+import { vars } from "../vars";
+
+const sendLogMock = sendLog as unknown as ReturnType<typeof vi.fn>;
+
+describe("startView", () => {
+  beforeEach(() => {
+    sendLogMock.mockClear();
+    vars.endpoints = [{ url: "https://example.com", authToken: "auth_abc123" }];
+    vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    vars.endpoints = [];
+  });
+
+  it("accepts a string shorthand and uses it as the title", () => {
+    startView("/settings");
+
+    expect(sendLogMock).toHaveBeenCalledTimes(1);
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+  });
+
+  it("accepts an options object with attributes", () => {
+    startView("/settings", { attributes: { "app.screen": "settings" } });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+    expect(log.attributes).toEqual(expect.arrayContaining([{ key: "app.screen", value: { stringValue: "settings" } }]));
+  });
+
+  it("parses a relative url option and reflects it in page.url.path", () => {
+    startView("/settings", { url: "/settings" });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([{ key: "page.url.path", value: { stringValue: "/settings" } }])
+    );
+  });
+
+  it("falls back to the current location on an invalid url", () => {
+    startView("/settings", { url: "http://" });
+
+    expect(sendLogMock).toHaveBeenCalledTimes(1);
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([
+        // eslint-disable-next-line no-restricted-globals
+        { key: "page.url.full", value: { stringValue: window.location.href } },
+        // eslint-disable-next-line no-restricted-globals
+        { key: "page.url.domain", value: { stringValue: window.location.hostname } },
+      ])
+    );
+  });
+
+  it("resolves an absolute cross-origin url override", () => {
+    startView("/settings", { url: "https://other-origin.example/path" });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([
+        { key: "page.url.full", value: { stringValue: "https://other-origin.example/path" } },
+        { key: "page.url.domain", value: { stringValue: "other-origin.example" } },
+        { key: "page.url.path", value: { stringValue: "/path" } },
+      ])
+    );
+  });
+
+  it("does not touch history or location", () => {
+    // eslint-disable-next-line no-restricted-globals
+    const originalHref = window.location.href;
+    // eslint-disable-next-line no-restricted-globals
+    const originalLength = window.history.length;
+
+    startView("/settings");
+
+    // eslint-disable-next-line no-restricted-globals
+    expect(window.location.href).toBe(originalHref);
+    // eslint-disable-next-line no-restricted-globals
+    expect(window.history.length).toBe(originalLength);
+  });
+
+  it("ignores calls without a name, as they can arrive via the untyped script entrypoint", () => {
+    // @ts-expect-error deliberately calling without arguments, mirroring dash0("startView")
+    startView();
+    startView(undefined as unknown as string);
+    startView(null as unknown as string);
+
+    expect(sendLogMock).not.toHaveBeenCalled();
+  });
+
+  it("ignores calls with a non-string or empty name", () => {
+    startView(123 as unknown as string);
+    startView({ name: "/settings" } as unknown as string);
+    startView("");
+
+    expect(sendLogMock).not.toHaveBeenCalled();
+  });
+
+  it("tolerates a nullish options argument", () => {
+    startView("/settings", null as unknown as undefined);
+
+    expect(sendLogMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("is a no-op before init (no endpoints configured)", () => {
+    vars.endpoints = [];
+
+    startView("/settings");
+
+    expect(sendLogMock).not.toHaveBeenCalled();
+  });
+});

package/src/entrypoint/npm-package.ts

@@ -9,12 +9,16 @@ export * from "../api/events";
 export * from "../api/log-level";
 export { terminateSession } from "../api/session";
 export { reportError } from "../api/report-error";
+export { startView } from "../api/start-view";
+export { startSessionRecording, stopSessionRecording } from "../api/session-recording";
 
 // Additional utility types
 export type { AttributeValueType } from "../utils/otel";
 export type { AnyValue } from "../types/otlp";
 export type { PageViewMeta, PropagatorConfig, PropagatorType } from "../vars";
 export type { UrlAttributeScrubber, UrlAttributeRecord } from "../attributes/url";
+export type { StartViewOptions } from "../api/start-view";
+export type { SessionRecorder, SessionRecorderOptions, SessionRecordingSettings } from "../types/session-recording";
 
 export function init(opts: InitOptions): void {
   debug(`${INIT_MESSAGE} (via package)`);

package/src/entrypoint/npm-package_test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import * as npmPackage from "./npm-package";
+
+describe("npm-package entrypoint", () => {
+  it("exports startView", () => {
+    expect(typeof npmPackage.startView).toBe("function");
+  });
+});

package/src/entrypoint/script.ts

@@ -8,6 +8,8 @@ import { terminateSession } from "../api/session";
 import { addSignalAttribute, removeSignalAttribute } from "../api/attributes";
 import { sendEvent } from "../api/events";
 import { setActiveLogLevel } from "../api/log-level";
+import { startView } from "../api/start-view";
+import { startSessionRecording, stopSessionRecording } from "../api/session-recording";
 
 /**
  * All the APIs exposed through the script tag via `dash0('{{api name}}')`
@@ -22,6 +24,9 @@ const scriptApis = {
   removeSignalAttribute,
   setActiveLogLevel,
   sendEvent,
+  startView,
+  startSessionRecording,
+  stopSessionRecording,
 } as const;
 
 type GlobalObject = {

package/src/entrypoint/session-recording-script.ts

@@ -0,0 +1,23 @@
+/**
+ * Script-tag entrypoint, built to `dist/dash0-session-recording.iife.js`.
+ *
+ * This bundle contains only rrweb's recorder. It must not import any SDK module (see eslint.config.js), so the
+ * main SDK bundle stays the single owner of configuration, session and transport state. It hands the recorder
+ * to the SDK in two ways, so it can be loaded in any order relative to the initializer snippet and `dash0.iife.js`:
+ *
+ * - `window.dash0Recorder`: picked up by the SDK when `init()` runs. Covers the case where this bundle executes
+ *   before the initializer snippet has defined the `dash0` command queue.
+ * - `dash0("startSessionRecording", record)`: covers the case where the SDK is already initialized, or the
+ *   command queue exists and will be drained on `init()`.
+ */
+/* eslint-disable no-restricted-globals */
+import { record } from "@rrweb/record";
+
+type Dash0Global = ((...args: unknown[]) => void) | undefined;
+
+(window as unknown as { dash0Recorder?: unknown }).dash0Recorder = record;
+
+const dash0 = (window as unknown as { dash0?: Dash0Global }).dash0;
+if (typeof dash0 === "function") {
+  dash0("startSessionRecording", record);
+}

package/src/entrypoint/session-recording.ts

@@ -0,0 +1,13 @@
+/**
+ * npm entrypoint of `@dash0/sdk-web/session-recording`.
+ *
+ * This bundle contains only rrweb's recorder. It must not import any SDK module (see eslint.config.js), so the
+ * main SDK bundle stays the single owner of configuration, session and transport state.
+ */
+import { record } from "@rrweb/record";
+import type { SessionRecorder } from "../types/session-recording";
+
+/**
+ * The rrweb recorder. Pass it to `init({ sessionRecording: { recorder } })` or to `startSessionRecording(recorder)`.
+ */
+export const recorder = record as unknown as SessionRecorder;

package/src/instrumentations/navigation/event.ts

@@ -1,4 +1,4 @@
-import { addAttribute, getTraceContextForPageLoad } from "../../utils/otel";
+import { addAttribute, addAttributes, AttributeValueType, getTraceContextForPageLoad } from "../../utils/otel";
 import {
   EVENT_NAME,
   EVENT_NAMES,
@@ -12,7 +12,7 @@ import { doc, NO_VALUE_FALLBACK } from "../../utils";
 import { addCommonAttributes } from "../../attributes";
 import { sendLog } from "../../transport";
 import { PageViewMeta, vars } from "../../vars";
-import { KeyValue, LogRecord } from "../../types/otlp";
+import { AnyValue, KeyValue, LogRecord } from "../../types/otlp";
 
 function getPageViewMeta(url?: URL): PageViewMeta {
   if (!url) return {};
@@ -20,32 +20,41 @@ function getPageViewMeta(url?: URL): PageViewMeta {
   return vars.pageViewInstrumentation.generateMetadata?.(url) ?? {};
 }
 
-export function transmitPageViewEvent(timeUnixNano: string, url?: URL, virtual?: boolean, replaced?: boolean) {
-  const meta = getPageViewMeta(url);
+type BuildPageViewLogOptions = {
+  timeUnixNano: string;
+  url?: URL;
+  title?: string;
+  metaAttributes?: Record<string, AttributeValueType | AnyValue>;
+  customAttributes?: Record<string, AttributeValueType | AnyValue>;
+  pageViewType: (typeof PAGE_VIEW_TYPE_VALUES)[keyof typeof PAGE_VIEW_TYPE_VALUES];
+  changeState?: (typeof PAGE_VIEW_CHANGE_STATE_VALUES)[keyof typeof PAGE_VIEW_CHANGE_STATE_VALUES];
+};
 
+function buildAndSendPageViewLog(opts: BuildPageViewLogOptions) {
   const attributes: KeyValue[] = [];
   addAttribute(attributes, EVENT_NAME, EVENT_NAMES.PAGE_VIEW);
 
-  if (meta.attributes) {
-    Object.entries(meta.attributes).forEach(([key, value]) => addAttribute(attributes, key, value));
+  if (opts.metaAttributes) {
+    Object.entries(opts.metaAttributes).forEach(([key, value]) => addAttribute(attributes, key, value));
   }
-  addCommonAttributes(attributes, { url });
+  addCommonAttributes(attributes, { url: opts.url });
+
+  // Add custom attributes last to allow overrides
+  addAttributes(attributes, opts.customAttributes);
 
   const bodyAttributes: KeyValue[] = [];
-  addAttribute(bodyAttributes, "title", meta.title ?? doc?.title ?? NO_VALUE_FALLBACK);
+  addAttribute(bodyAttributes, "title", opts.title ?? doc?.title ?? NO_VALUE_FALLBACK);
   if (doc?.referrer) {
     addAttribute(bodyAttributes, "referrer", doc.referrer);
   }
 
-  addAttribute(bodyAttributes, PAGE_VIEW_TYPE, virtual ? PAGE_VIEW_TYPE_VALUES.VIRTUAL : PAGE_VIEW_TYPE_VALUES.INITIAL);
-  addAttribute(
-    bodyAttributes,
-    PAGE_VIEW_CHANGE_STATE,
-    replaced ? PAGE_VIEW_CHANGE_STATE_VALUES.REPLACE : PAGE_VIEW_CHANGE_STATE_VALUES.PUSH
-  );
+  addAttribute(bodyAttributes, PAGE_VIEW_TYPE, opts.pageViewType);
+  if (opts.changeState) {
+    addAttribute(bodyAttributes, PAGE_VIEW_CHANGE_STATE, opts.changeState);
+  }
 
   const log: LogRecord = {
-    timeUnixNano: timeUnixNano,
+    timeUnixNano: opts.timeUnixNano,
     attributes: attributes,
     severityNumber: LOG_SEVERITIES.INFO,
     severityText: "INFO",
@@ -64,3 +73,42 @@ export function transmitPageViewEvent(timeUnixNano: string, url?: URL, virtual?:
 
   sendLog(log);
 }
+
+export function transmitPageViewEvent(timeUnixNano: string, url?: URL, virtual?: boolean, replaced?: boolean) {
+  const meta = getPageViewMeta(url);
+
+  buildAndSendPageViewLog({
+    timeUnixNano,
+    url,
+    title: meta.title,
+    metaAttributes: meta.attributes,
+    pageViewType: virtual ? PAGE_VIEW_TYPE_VALUES.VIRTUAL : PAGE_VIEW_TYPE_VALUES.INITIAL,
+    changeState: replaced ? PAGE_VIEW_CHANGE_STATE_VALUES.REPLACE : PAGE_VIEW_CHANGE_STATE_VALUES.PUSH,
+  });
+}
+
+export type ManualPageViewOptions = {
+  timeUnixNano: string;
+  url?: URL;
+  title: string;
+  attributes?: Record<string, AttributeValueType | AnyValue>;
+};
+
+/**
+ * Emits a manually-triggered page view log, e.g. from the public `startView` API.
+ * Deliberately does NOT read `vars.pageViewInstrumentation.generateMetadata` and does NOT
+ * include a `change_state` body key (a manual view is neither a pushState nor replaceState).
+ * The emitted `type` is PAGE_VIEW_TYPE_VALUES.VIRTUAL, matching automatic virtual page views —
+ * manual views are deliberately indistinguishable from virtual ones downstream.
+ * Caller-provided attributes are added after the SDK-generated ones so they can override them,
+ * matching the sendEvent semantics.
+ */
+export function transmitManualPageViewEvent(opts: ManualPageViewOptions) {
+  buildAndSendPageViewLog({
+    timeUnixNano: opts.timeUnixNano,
+    url: opts.url,
+    title: opts.title,
+    customAttributes: opts.attributes,
+    pageViewType: PAGE_VIEW_TYPE_VALUES.VIRTUAL,
+  });
+}

package/src/instrumentations/navigation/event_test.ts

@@ -0,0 +1,171 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { KeyValue, LogRecord } from "../../types/otlp";
+
+vi.mock("../../transport", () => ({
+  sendLog: vi.fn(),
+}));
+
+import { sendLog } from "../../transport";
+import { transmitPageViewEvent, transmitManualPageViewEvent } from "./event";
+import { vars } from "../../vars";
+
+const sendLogMock = sendLog as unknown as ReturnType<typeof vi.fn>;
+
+describe("transmitPageViewEvent", () => {
+  beforeEach(() => {
+    sendLogMock.mockClear();
+    vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("transmits an initial page view with type=INITIAL and change_state=pushState", () => {
+    transmitPageViewEvent("1700000000000000000", new URL("https://example.com/landing"));
+
+    expect(sendLogMock).toHaveBeenCalledTimes(1);
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+
+    expect(log.timeUnixNano).toBe("1700000000000000000");
+    expect(log.severityNumber).toBe(9);
+    expect(log.severityText).toBe("INFO");
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([{ key: "event.name", value: { stringValue: "browser.page_view" } }])
+    );
+
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    expect(bodyValues).toEqual(
+      expect.arrayContaining([
+        { key: "type", value: { doubleValue: 0 } },
+        { key: "change_state", value: { stringValue: "pushState" } },
+      ])
+    );
+  });
+
+  it("transmits a virtual page view with type=VIRTUAL and change_state=replaceState when replaced", () => {
+    transmitPageViewEvent("1700000000000000000", new URL("https://example.com/settings"), true, true);
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    expect(bodyValues).toEqual(
+      expect.arrayContaining([
+        { key: "type", value: { doubleValue: 1 } },
+        { key: "change_state", value: { stringValue: "replaceState" } },
+      ])
+    );
+  });
+
+  it("applies generateMetadata title and attributes when provided", () => {
+    vars.pageViewInstrumentation = {
+      trackVirtualPageViews: true,
+      includeParts: [],
+      generateMetadata: () => ({ title: "Custom Title", attributes: { "app.screen": "settings" } }),
+    };
+
+    transmitPageViewEvent("1700000000000000000", new URL("https://example.com/settings"), true);
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    expect(log.attributes).toEqual(expect.arrayContaining([{ key: "app.screen", value: { stringValue: "settings" } }]));
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "Custom Title" } }]));
+  });
+});
+
+describe("transmitManualPageViewEvent", () => {
+  beforeEach(() => {
+    sendLogMock.mockClear();
+    vars.pageViewInstrumentation = {
+      trackVirtualPageViews: true,
+      includeParts: [],
+      generateMetadata: () => ({ title: "should not be used", attributes: { should_not_appear: true } }),
+    };
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+  });
+
+  it("emits type=VIRTUAL and no change_state key", () => {
+    transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+
+    expect(bodyValues).toEqual(
+      expect.arrayContaining([
+        { key: "type", value: { doubleValue: 1 } },
+        { key: "title", value: { stringValue: "/settings" } },
+      ])
+    );
+    expect(bodyValues.find((v) => v.key === "change_state")).toBeUndefined();
+  });
+
+  it("does not invoke vars.pageViewInstrumentation.generateMetadata", () => {
+    const generateMetadata = vi.fn().mockReturnValue({ title: "ignored" });
+    vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [], generateMetadata };
+
+    transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+
+    expect(generateMetadata).not.toHaveBeenCalled();
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+  });
+
+  it("merges custom attributes into signal attributes", () => {
+    transmitManualPageViewEvent({
+      timeUnixNano: "1700000000000000000",
+      title: "/settings",
+      attributes: { "app.screen": "settings", "app.tab_index": 2 },
+    });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([
+        { key: "app.screen", value: { stringValue: "settings" } },
+        { key: "app.tab_index", value: { doubleValue: 2 } },
+      ])
+    );
+  });
+
+  it("adds custom attributes after SDK-generated ones so they can override", () => {
+    transmitManualPageViewEvent({
+      timeUnixNano: "1700000000000000000",
+      title: "/settings",
+      url: new URL("https://example.com/real-path"),
+      attributes: { "page.url.path": "/custom-path" },
+    });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const pathAttributes = (log.attributes as KeyValue[]).filter((attr) => attr.key === "page.url.path");
+    expect(pathAttributes.length).toBeGreaterThan(1);
+    expect(pathAttributes[pathAttributes.length - 1]).toEqual({
+      key: "page.url.path",
+      value: { stringValue: "/custom-path" },
+    });
+  });
+
+  it("passes url through to page.url.* attributes when provided", () => {
+    transmitManualPageViewEvent({
+      timeUnixNano: "1700000000000000000",
+      title: "/settings",
+      url: new URL("https://example.com/settings"),
+    });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    expect(log.attributes).toEqual(
+      expect.arrayContaining([{ key: "page.url.path", value: { stringValue: "/settings" } }])
+    );
+  });
+
+  it("includes referrer the same way the auto path does", () => {
+    transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+
+    const log = sendLogMock.mock.calls[0]![0] as LogRecord;
+    const bodyValues = log.body?.kvlistValue?.values as KeyValue[];
+    // doc.referrer is empty string in jsdom by default, so "referrer" key should be absent
+    expect(bodyValues.find((v) => v.key === "referrer")).toBeUndefined();
+  });
+});

package/src/instrumentations/session-recording/chunker.ts

@@ -0,0 +1,118 @@
+import { setTimeout, clearTimeout } from "../../utils/timers";
+import { SessionRecordingEvent } from "../../types/session-recording";
+
+const RRWEB_EVENT_TYPE_FULL_SNAPSHOT = 2;
+const RRWEB_EVENT_TYPE_META = 4;
+
+export type Chunk = {
+  /**
+   * Zero-based, monotonic within one recording.
+   */
+  seq: number;
+  /**
+   * The rrweb events as a serialized JSON array.
+   */
+  body: string;
+  eventCount: number;
+  hasSnapshot: boolean;
+  /**
+   * Milliseconds since the unix epoch of the first and the last event in the chunk.
+   */
+  startTime: number;
+  endTime: number;
+};
+
+export type ChunkerOptions = {
+  maxBytes: number;
+  maxMillis: number;
+  onChunk: (chunk: Chunk) => void;
+};
+
+export type Chunker = {
+  add(event: SessionRecordingEvent): void;
+  flush(): void;
+  /**
+   * Drops buffered events without emitting a chunk and cancels the pending time-based flush. Used when the
+   * recorder failed to start after it already emitted events, so no stray chunk is transmitted later.
+   */
+  discard(): void;
+};
+
+/**
+ * Buffers rrweb events and hands them out as chunks. A chunk closes when its serialized size reaches
+ * `maxBytes`, when `maxMillis` have passed since its first event, when a new full snapshot begins, or when
+ * `flush()` is called. Events are serialized once, on arrival, so a flush is a join and not a second stringify.
+ */
+export function newChunker(opts: ChunkerOptions): Chunker {
+  let serialized: string[] = [];
+  let byteSize = 0;
+  let hasSnapshot = false;
+  let startTime = 0;
+  let endTime = 0;
+  let seq = 0;
+  let pendingFlushTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  return { add, flush, discard };
+
+  function add(event: SessionRecordingEvent): void {
+    // A Meta event announces a new full snapshot. Close the current chunk first so the snapshot starts a fresh
+    // one and a replay can begin at that chunk.
+    if (event.type === RRWEB_EVENT_TYPE_META && serialized.length > 0) {
+      flush();
+    }
+
+    const json = JSON.stringify(event);
+    if (json == null) return;
+
+    if (serialized.length === 0) {
+      startTime = event.timestamp;
+      pendingFlushTimeout = setTimeout(flush, opts.maxMillis);
+    }
+
+    serialized.push(json);
+    byteSize += json.length;
+    endTime = event.timestamp;
+    if (event.type === RRWEB_EVENT_TYPE_FULL_SNAPSHOT) {
+      hasSnapshot = true;
+    }
+
+    if (byteSize >= opts.maxBytes) {
+      flush();
+    }
+  }
+
+  function discard(): void {
+    clearPendingFlush();
+    serialized = [];
+    byteSize = 0;
+    hasSnapshot = false;
+  }
+
+  function clearPendingFlush(): void {
+    if (pendingFlushTimeout != null) {
+      clearTimeout(pendingFlushTimeout);
+      pendingFlushTimeout = null;
+    }
+  }
+
+  function flush(): void {
+    clearPendingFlush();
+
+    if (serialized.length === 0) return;
+
+    const chunk: Chunk = {
+      seq: seq++,
+      body: "[" + serialized.join(",") + "]",
+      eventCount: serialized.length,
+      hasSnapshot,
+      startTime,
+      endTime,
+    };
+
+    serialized = [];
+    byteSize = 0;
+    hasSnapshot = false;
+
+    opts.onChunk(chunk);
+  }
+}