swetrix 4.2.0 → 4.3.0

package/src/index.ts

@@ -11,6 +11,9 @@ import {
   IPageViewPayload,
   FeatureFlagsOptions,
   ExperimentOptions,
+  SessionReplayOptions,
+  SessionReplayActions,
+  defaultSessionReplayActions,
 } from './Lib.js'
 
 export let LIB_INSTANCE: Lib | null = null
@@ -82,6 +85,16 @@ export function trackErrors(options?: ErrorOptions): ErrorActions {
   return LIB_INSTANCE.trackErrors(options)
 }
 
+export function startSessionReplay(
+  options?: SessionReplayOptions,
+): Promise<SessionReplayActions> {
+  if (!LIB_INSTANCE) {
+    return Promise.resolve(defaultSessionReplayActions)
+  }
+
+  return LIB_INSTANCE.startSessionReplay(options)
+}
+
 /**
  * This function is used to manually track an error event.
  * It's useful if you want to track specific errors in your application.
@@ -124,17 +137,16 @@ export function pageview(options: IPageviewOptions): void {
 
 /**
  * Fetches all feature flags for the project.
- * Results are cached for 5 minutes by default.
+ * Results are cached for 5 minutes by default and share a cache with experiments.
  *
- * @param options - Options for evaluating feature flags (visitorId, attributes).
+ * @param options - Options for evaluating feature flags (`profileId` only).
  * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
  * @returns A promise that resolves to a record of flag keys to boolean values.
  *
  * @example
  * ```typescript
  * const flags = await getFeatureFlags({
- *   visitorId: 'user-123',
- *   attributes: { cc: 'US', dv: 'desktop' }
+ *   profileId: 'user-123'
  * })
  *
  * if (flags['new-checkout']) {
@@ -155,13 +167,13 @@ export async function getFeatureFlags(
  * Gets the value of a single feature flag.
  *
  * @param key - The feature flag key.
- * @param options - Options for evaluating the feature flag (visitorId, attributes).
- * @param defaultValue - Default value to return if the flag is not found. Defaults to false.
+ * @param options - Options for evaluating the feature flag (`profileId` only).
+ * @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
  * @returns A promise that resolves to the boolean value of the flag.
  *
  * @example
  * ```typescript
- * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })
+ * const isEnabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
  *
  * if (isEnabled) {
  *   // Enable dark mode
@@ -179,8 +191,8 @@ export async function getFeatureFlag(
 }
 
 /**
- * Clears the cached feature flags, forcing a fresh fetch on the next call.
- * Useful when you know the user's context has changed significantly.
+ * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
+ * Useful when you know the user's profile has changed.
  */
 export function clearFeatureFlagsCache(): void {
   if (!LIB_INSTANCE) return
@@ -189,10 +201,10 @@ export function clearFeatureFlagsCache(): void {
 }
 
 /**
- * Fetches all A/B test experiments for the project.
+ * Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
  * Results are cached for 5 minutes by default (shared cache with feature flags).
  *
- * @param options - Options for evaluating experiments.
+ * @param options - Options for evaluating experiments (`profileId` only).
  * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
  * @returns A promise that resolves to a record of experiment IDs to variant keys.
  *
@@ -223,13 +235,16 @@ export async function getExperiments(
  * Gets the variant key for a specific A/B test experiment.
  *
  * @param experimentId - The experiment ID.
- * @param options - Options for evaluating the experiment.
- * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @param options - Options for evaluating the experiment (`profileId` only).
+ * @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
  * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
  *
  * @example
  * ```typescript
- * const variant = await getExperiment('checkout-redesign-experiment-id')
+ * const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
+ *
+ * // Optional fallback variant:
+ * const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', undefined, 'control')
  *
  * if (variant === 'new-checkout') {
  *   // Show new checkout flow

package/src/types/rrweb-shim.d.ts

@@ -0,0 +1,11 @@
+declare module 'rrweb' {
+  export const record: unknown
+  export const Replayer: unknown
+
+  const rrweb: {
+    record?: unknown
+    Replayer?: unknown
+  }
+
+  export default rrweb
+}

package/tests/sessionReplay.test.ts

@@ -0,0 +1,389 @@
+/// <reference types="jest" />
+
+import { Lib } from '../src/Lib'
+import { setLocation } from './testUtils'
+
+const PROJECT_ID = 'test-project-id'
+const RRWEB_URL = 'https://cdn.jsdelivr.net/npm/swetrix@latest/dist/replaylibrary.min.js'
+const mockRrwebRecord = jest.fn()
+
+jest.mock('rrweb', () => ({
+  record: mockRrwebRecord,
+}))
+
+const loadTracker = async () => {
+  jest.resetModules()
+  return import('../src/index')
+}
+
+const resetReplayGlobals = () => {
+  delete (window as any).rrweb
+  delete (window as any).__SWETRIX_RRWEB_LOADING__
+  document.head.innerHTML = ''
+  document.body.innerHTML = ''
+}
+
+const usePackageRrweb = () => {
+  const stopRecording = jest.fn()
+  mockRrwebRecord.mockImplementation((recordOptions) => {
+    ;(mockRrwebRecord as any).options = recordOptions
+    return stopRecording
+  })
+
+  return {
+    recordOptions: () => (mockRrwebRecord as any).options,
+    stopRecording,
+  }
+}
+
+describe('Session replay tracking', () => {
+  let fetchMock: jest.Mock
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockRrwebRecord.mockReset()
+    delete (mockRrwebRecord as any).options
+    jest.useRealTimers()
+    resetReplayGlobals()
+    setLocation({ hostname: 'example.com', pathname: '/checkout' })
+
+    Object.defineProperty(navigator, 'doNotTrack', {
+      value: null,
+      writable: true,
+      configurable: true,
+    })
+
+    fetchMock = jest.fn().mockResolvedValue({ ok: true })
+    Object.defineProperty(globalThis, 'fetch', {
+      value: fetchMock,
+      writable: true,
+      configurable: true,
+    })
+  })
+
+  test('init with preloadSessionReplay loads npm rrweb but does not record', async () => {
+    const { init } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true, preloadSessionReplay: true })
+    await (window as any).__SWETRIX_RRWEB_LOADING__
+
+    expect((window as any).rrweb.record).toBe(mockRrwebRecord)
+    expect(document.querySelector(`script[src="${RRWEB_URL}"]`)).toBeNull()
+    expect(mockRrwebRecord).not.toHaveBeenCalled()
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  test('session replay script uses jsDelivr for the public swetrix.org loader', async () => {
+    const script = document.createElement('script')
+    script.src = 'https://swetrix.org/swetrix.js'
+    document.head.appendChild(script)
+
+    const { init } = await loadTracker()
+    init(PROJECT_ID, { devMode: true, preloadSessionReplay: true })
+
+    expect(
+      document.querySelector<HTMLScriptElement>(
+        `script[src="${RRWEB_URL}"]`,
+      ),
+    ).toBeTruthy()
+    expect(mockRrwebRecord).not.toHaveBeenCalled()
+  })
+
+  test('preloadSessionReplay can load rrweb from a custom script URL', async () => {
+    const rrwebUrl = 'https://cdn.example.com/rrweb.min.js'
+    const { init } = await loadTracker()
+
+    init(PROJECT_ID, {
+      devMode: true,
+      preloadSessionReplay: { rrwebUrl },
+    })
+
+    expect(
+      document.querySelector<HTMLScriptElement>(`script[src="${rrwebUrl}"]`),
+    ).toBeTruthy()
+    expect(mockRrwebRecord).not.toHaveBeenCalled()
+  })
+
+  test('startSessionReplay imports npm rrweb, records events, and flushes chunks', async () => {
+    const { recordOptions } = usePackageRrweb()
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    const actions = await startSessionReplay({
+      flushIntervalMs: 60_000,
+      maxEventsPerChunk: 2,
+    })
+    const options = recordOptions()
+    expect(options.maskTextSelector).toBe('*')
+    expect(document.querySelector(`script[src="${RRWEB_URL}"]`)).toBeNull()
+
+    const startCall = fetchMock.mock.calls.find(([url]) =>
+      String(url).includes('/session-replay/start'),
+    )
+    expect(startCall).toBeTruthy()
+    expect(JSON.parse(startCall![1].body as string)).toEqual(
+      expect.objectContaining({ privacy: 'total' }),
+    )
+
+    options.emit({ type: 2, timestamp: 100 })
+    options.emit({ type: 3, timestamp: 200 })
+
+    await actions.flush()
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.swetrix.com/log/session-replay/start',
+      expect.objectContaining({ method: 'POST' }),
+    )
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.swetrix.com/log/session-replay/chunk',
+      expect.objectContaining({
+        method: 'POST',
+        body: expect.stringContaining('"chunkIndex":0'),
+      }),
+    )
+
+    await actions.stop()
+  })
+
+  test('concurrent startSessionReplay calls share one recorder', async () => {
+    const { stopRecording } = usePackageRrweb()
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    const [firstActions, secondActions] = await Promise.all([
+      startSessionReplay({ flushIntervalMs: 60_000 }),
+      startSessionReplay({ flushIntervalMs: 10_000 }),
+    ])
+
+    expect(firstActions).toBe(secondActions)
+    expect(mockRrwebRecord).toHaveBeenCalledTimes(1)
+    expect(
+      fetchMock.mock.calls.filter(([url]) =>
+        String(url).includes('/session-replay/start'),
+      ),
+    ).toHaveLength(1)
+
+    await firstActions.stop()
+    expect(stopRecording).toHaveBeenCalledTimes(1)
+  })
+
+  test('sampleRate can skip recording before loading rrweb', async () => {
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    const actions = await startSessionReplay({ sampleRate: 0 })
+    await actions.flush()
+    await actions.stop()
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(document.querySelector(`script[src="${RRWEB_URL}"]`)).toBeNull()
+    expect(mockRrwebRecord).not.toHaveBeenCalled()
+  })
+
+  test('maxDurationMs stops recording and flushes buffered events', async () => {
+    jest.useFakeTimers()
+    const { recordOptions, stopRecording } = usePackageRrweb()
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    await startSessionReplay({
+      flushIntervalMs: 60_000,
+      maxDurationMs: 1000,
+    })
+    recordOptions().emit({ type: 2, timestamp: 100 })
+
+    await jest.advanceTimersByTimeAsync(1000)
+    await Promise.resolve()
+
+    expect(stopRecording).toHaveBeenCalledTimes(1)
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.swetrix.com/log/session-replay/chunk',
+      expect.objectContaining({
+        body: expect.stringContaining('"timestamp":100'),
+      }),
+    )
+  })
+
+  test('idleTimeoutMs stops after inactivity and resets on activity', async () => {
+    jest.useFakeTimers()
+    const { recordOptions, stopRecording } = usePackageRrweb()
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    await startSessionReplay({
+      flushIntervalMs: 60_000,
+      idleTimeoutMs: 1000,
+    })
+    recordOptions().emit({ type: 2, timestamp: 200 })
+
+    await jest.advanceTimersByTimeAsync(900)
+    window.dispatchEvent(new Event('mousemove'))
+    await jest.advanceTimersByTimeAsync(900)
+
+    expect(stopRecording).not.toHaveBeenCalled()
+
+    await jest.advanceTimersByTimeAsync(100)
+    await Promise.resolve()
+
+    expect(stopRecording).toHaveBeenCalledTimes(1)
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.swetrix.com/log/session-replay/chunk',
+      expect.objectContaining({
+        body: expect.stringContaining('"timestamp":200'),
+      }),
+    )
+  })
+
+  test('privacy modes map to rrweb options and keep internal emit', () => {
+    const lib = new Lib(PROJECT_ID, { devMode: true })
+    const emit = jest.fn()
+
+    const total = (lib as any).getSessionReplayRecordOptions(
+      'total',
+      { blockSelector: '.secret', emit: jest.fn() },
+      emit,
+    )
+    expect(total.maskAllInputs).toBe(true)
+    expect(total.maskTextSelector).toBe('*')
+    expect(total.blockSelector).toContain('.secret')
+    expect(total.blockSelector).toContain('img')
+    expect(total.recordCanvas).toBe(false)
+    expect(total.inlineImages).toBe(false)
+    expect(total.emit).toBe(emit)
+
+    const normal = (lib as any).getSessionReplayRecordOptions(
+      'normal',
+      {},
+      emit,
+    )
+    expect(normal.maskAllInputs).toBe(true)
+    expect(normal.emit).toBe(emit)
+
+    const freeLove = (lib as any).getSessionReplayRecordOptions(
+      'none',
+      { maskInputOptions: { email: false } },
+      emit,
+    )
+    expect(freeLove.maskInputOptions).toEqual({
+      email: false,
+      password: true,
+    })
+    expect(freeLove.emit).toBe(emit)
+  })
+
+  test('invalid privacy values fall back to total privacy', async () => {
+    const { recordOptions } = usePackageRrweb()
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    const actions = await startSessionReplay({
+      privacy: 'totl' as any,
+    })
+    const startCall = fetchMock.mock.calls.find(([url]) =>
+      String(url).includes('/session-replay/start'),
+    )
+
+    expect(startCall).toBeTruthy()
+    expect(JSON.parse(startCall![1].body as string)).toEqual(
+      expect.objectContaining({ privacy: 'total' }),
+    )
+    expect(recordOptions().maskTextSelector).toBe('*')
+
+    await actions.stop()
+  })
+
+  test('script rrweb loader clears failed loads so startSessionReplay can retry', async () => {
+    const record = jest.fn(() => jest.fn())
+    const trackerScript = document.createElement('script')
+    trackerScript.src = 'https://example.com/swetrix.js'
+    document.head.appendChild(trackerScript)
+    const rrwebUrl = 'https://example.com/replaylibrary.min.js'
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    const failedStart = startSessionReplay()
+    const failedScript = document.querySelector<HTMLScriptElement>(
+      `script[src="${rrwebUrl}"]`,
+    )
+    expect(failedScript).toBeTruthy()
+    failedScript!.dispatchEvent(new Event('error'))
+
+    await failedStart
+    expect((window as any).__SWETRIX_RRWEB_LOADING__).toBeUndefined()
+
+    const retryStart = startSessionReplay()
+    const scripts = document.querySelectorAll<HTMLScriptElement>(
+      `script[src="${rrwebUrl}"]`,
+    )
+    expect(scripts[1]).toBeTruthy()
+    expect(scripts[1]).not.toBe(failedScript)
+    ;(window as any).rrweb = { record }
+    scripts[1].dispatchEvent(new Event('load'))
+
+    const actions = await retryStart
+    expect((window as any).rrweb.record).toBe(record)
+    expect(record).toHaveBeenCalled()
+
+    await actions.stop()
+  })
+
+  test('user rrweb emit is composed with Swetrix uploads', async () => {
+    const { recordOptions } = usePackageRrweb()
+    const userEmit = jest.fn()
+    const { init, startSessionReplay } = await loadTracker()
+
+    init(PROJECT_ID, { devMode: true })
+    const actions = await startSessionReplay({
+      rrweb: { emit: userEmit, maskAllInputs: true },
+    })
+    const event = { type: 2, timestamp: 300 }
+    recordOptions().emit(event)
+    await actions.flush()
+
+    expect(userEmit).toHaveBeenCalledWith(event)
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.swetrix.com/log/session-replay/chunk',
+      expect.objectContaining({
+        body: expect.stringContaining('"timestamp":300'),
+      }),
+    )
+
+    await actions.stop()
+  })
+
+  test('DNT and disabled tracking return no-op controls without uploading', async () => {
+    Object.defineProperty(navigator, 'doNotTrack', {
+      value: '1',
+      writable: true,
+      configurable: true,
+    })
+
+    const { init, startSessionReplay } = await loadTracker()
+    init(PROJECT_ID, { devMode: true, respectDNT: true })
+
+    const actions = await startSessionReplay()
+    await actions.flush()
+    await actions.stop()
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(document.querySelector(`script[src="${RRWEB_URL}"]`)).toBeNull()
+    expect(mockRrwebRecord).not.toHaveBeenCalled()
+
+    resetReplayGlobals()
+    mockRrwebRecord.mockReset()
+    Object.defineProperty(navigator, 'doNotTrack', {
+      value: null,
+      writable: true,
+      configurable: true,
+    })
+
+    const disabledModule = await loadTracker()
+    disabledModule.init(PROJECT_ID, { devMode: true, disabled: true })
+    const disabledActions = await disabledModule.startSessionReplay()
+    await disabledActions.flush()
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(document.querySelector(`script[src="${RRWEB_URL}"]`)).toBeNull()
+    expect(mockRrwebRecord).not.toHaveBeenCalled()
+  })
+})

package/tsconfig.esnext.json

@@ -8,7 +8,11 @@
     "sourceMap": true,
     "declaration": true,
     "outDir": "dist/esnext",
-    "typeRoots": ["node_modules/@types"]
+    "baseUrl": ".",
+    "paths": {
+      "rrweb": ["src/types/rrweb-shim.d.ts"]
+    },
+    "types": []
   },
   "include": ["src"]
 }

package/tsconfig.json

@@ -7,7 +7,12 @@
     "strict": true,
     "sourceMap": true,
     "declaration": false,
-    "allowSyntheticDefaultImports": true
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "rrweb": ["src/types/rrweb-shim.d.ts"]
+    },
+    "types": []
   },
   "include": ["src"]
 }

package/tsconfig.test.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["jest", "node"]
+  },
+  "include": ["src", "tests"]
+}