swetrix 4.1.0 → 4.3.0

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/tests/testUtils.ts

@@ -0,0 +1,27 @@
+interface LocationParts {
+  hostname?: string
+  pathname?: string
+  hash?: string
+  search?: string
+  protocol?: string
+}
+
+/**
+ * Sets `window.location` by reconfiguring the underlying jsdom instance via the
+ * global helper installed by `jsdomEnvironment.ts`. Defaults preserve a stable
+ * "example.com/" base so individual fields can be set in isolation.
+ */
+export const setLocation = (parts: LocationParts = {}): void => {
+  const protocol = parts.protocol ?? 'http:'
+  const hostname = parts.hostname ?? 'example.com'
+  const pathname = parts.pathname ?? '/'
+  const search = parts.search ?? ''
+  const hash = parts.hash ?? ''
+
+  const setter = (globalThis as any).__setLocation as ((url: string) => void) | undefined
+  if (typeof setter !== 'function') {
+    throw new Error('__setLocation is not available - check that the custom jsdom environment is configured')
+  }
+
+  setter(`${protocol}//${hostname}${pathname}${search}${hash}`)
+}

package/tests/utils.test.ts

@@ -1,35 +1,32 @@
 import * as utils from '../src/utils'
+import { setLocation } from './testUtils'
 
 describe('Utility Functions', () => {
   beforeEach(() => {
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'example.com',
-        pathname: '/test-page',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'example.com', pathname: '/test-page' })
 
     Object.defineProperty(document, 'referrer', {
       value: 'https://google.com',
       writable: true,
+      configurable: true,
     })
 
     Object.defineProperty(navigator, 'language', {
       value: 'en-US',
       writable: true,
+      configurable: true,
     })
 
     Object.defineProperty(navigator, 'languages', {
       value: ['en-US', 'en'],
       writable: true,
+      configurable: true,
     })
 
     Object.defineProperty(navigator, 'webdriver', {
       value: false,
       writable: true,
+      configurable: true,
     })
   })
 
@@ -38,50 +35,28 @@ describe('Utility Functions', () => {
   })
 
   test('isLocalhost should detect localhost', () => {
-    // Arrange
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'localhost',
-      },
-      writable: true,
-    })
-
-    // Act & Assert
+    setLocation({ hostname: 'localhost' })
     expect(utils.isLocalhost()).toBe(true)
 
-    // Test 127.0.0.1
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: '127.0.0.1',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: '127.0.0.1' })
     expect(utils.isLocalhost()).toBe(true)
 
-    // Test non-localhost
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'example.com',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'example.com' })
     expect(utils.isLocalhost()).toBe(false)
   })
 
   test('isAutomated should detect webdriver', () => {
-    // Arrange
     Object.defineProperty(navigator, 'webdriver', {
       value: true,
       writable: true,
+      configurable: true,
     })
-
-    // Act & Assert
     expect(utils.isAutomated()).toBe(true)
 
-    // Test non-automated
     Object.defineProperty(navigator, 'webdriver', {
       value: false,
       writable: true,
+      configurable: true,
     })
     expect(utils.isAutomated()).toBe(false)
   })
@@ -89,129 +64,77 @@ describe('Utility Functions', () => {
   test('getLocale should return the browser language', () => {
     expect(utils.getLocale()).toBe('en-US')
 
-    // Test with navigator.languages undefined
     const originalLanguages = navigator.languages
-    // Instead of deleting, set to undefined
     Object.defineProperty(navigator, 'languages', {
       value: undefined,
       writable: true,
+      configurable: true,
     })
-    expect(utils.getLocale()).toBe('en-US') // Should use navigator.language as fallback
+    expect(utils.getLocale()).toBe('en-US')
 
-    // Restore the original value
     Object.defineProperty(navigator, 'languages', {
       value: originalLanguages,
       writable: true,
+      configurable: true,
     })
   })
 
   test('getReferrer should return the document referrer', () => {
     expect(utils.getReferrer()).toBe('https://google.com')
 
-    // Test with empty referrer
     Object.defineProperty(document, 'referrer', {
       value: '',
       writable: true,
+      configurable: true,
     })
     expect(utils.getReferrer()).toBeUndefined()
   })
 
-  test('getPath should handle different URL formats', () => {
-    // Arrange
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/test-page',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+  test('getQueryString should return the URL query string without the leading ?', () => {
+    setLocation({ pathname: '/landing', search: '?fbclid=AbCdEf123&utm_source=newsletter' })
+    expect(utils.getQueryString()).toBe('fbclid=AbCdEf123&utm_source=newsletter')
 
-    // Act & Assert - basic path
+    setLocation({ pathname: '/landing' })
+    expect(utils.getQueryString()).toBeUndefined()
+
+    // Hash-routed SPAs sometimes carry the query string after the `#`.
+    setLocation({ pathname: '/', hash: '#/landing?gclid=xyz' })
+    expect(utils.getQueryString()).toBe('gclid=xyz')
+  })
+
+  test('getPath should handle different URL formats', () => {
+    setLocation({ pathname: '/test-page' })
     expect(utils.getPath({})).toBe('/test-page')
 
-    // Test with hash
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/test-page',
-        hash: '#section1',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ pathname: '/test-page', hash: '#section1' })
     expect(utils.getPath({ hash: true })).toBe('/test-page#section1')
 
-    // Test with search
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/test-page',
-        hash: '',
-        search: '?param=value',
-      },
-      writable: true,
-    })
+    setLocation({ pathname: '/test-page', search: '?param=value' })
     expect(utils.getPath({ search: true })).toBe('/test-page?param=value')
 
-    // Test with both hash and search
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/test-page',
-        hash: '#section1',
-        search: '?param=value',
-      },
-      writable: true,
-    })
+    setLocation({ pathname: '/test-page', hash: '#section1', search: '?param=value' })
     expect(utils.getPath({ hash: true, search: true })).toBe('/test-page#section1?param=value')
 
-    // Test with search in hash
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/test-page',
-        hash: '#section1?param=value',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ pathname: '/test-page', hash: '#section1?param=value' })
     expect(utils.getPath({ hash: true, search: true })).toBe('/test-page#section1?param=value')
   })
 
   test('getUTM* functions should extract UTM parameters', () => {
-    // Arrange
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/landing',
-        hash: '',
-        search: '?utm_source=google&utm_medium=cpc&utm_campaign=summer&utm_term=analytics&utm_content=ad1',
-      },
-      writable: true,
+    setLocation({
+      pathname: '/landing',
+      search: '?utm_source=google&utm_medium=cpc&utm_campaign=summer&utm_term=analytics&utm_content=ad1',
     })
 
-    // Act & Assert
     expect(utils.getUTMSource()).toBe('google')
     expect(utils.getUTMMedium()).toBe('cpc')
     expect(utils.getUTMCampaign()).toBe('summer')
     expect(utils.getUTMTerm()).toBe('analytics')
     expect(utils.getUTMContent()).toBe('ad1')
 
-    // Test with 'ref' and 'source' parameters as well
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/landing',
-        hash: '',
-        search: '?ref=twitter',
-      },
-      writable: true,
-    })
+    setLocation({ pathname: '/landing', search: '?ref=twitter' })
     expect(utils.getUTMSource()).toBe('twitter')
 
-    Object.defineProperty(window, 'location', {
-      value: {
-        pathname: '/landing',
-        hash: '',
-        search: '?source=newsletter',
-      },
-      writable: true,
-    })
+    setLocation({ pathname: '/landing', search: '?source=newsletter' })
     expect(utils.getUTMSource()).toBe('newsletter')
   })
 })

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"]
 }