swetrix 4.1.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/src/utils.ts

@@ -48,6 +48,28 @@ export const getReferrer = (): string | undefined => {
   return document.referrer || undefined
 }
 
+/**
+ * Returns the URL query string (without the leading `?`) of the current
+ * page, or `undefined` if there is none.
+ *
+ * Falls back to a query string embedded in `location.hash` (e.g. when a
+ * hash router uses `/#/path?foo=bar`) so we still capture click IDs in
+ * SPA hash-routed setups.
+ */
+export const getQueryString = (): string | undefined => {
+  if (location.search && location.search.length > 1) {
+    return location.search.slice(1)
+  }
+
+  const hashIndex = location.hash.indexOf('?')
+  if (hashIndex > -1) {
+    const hashQuery = location.hash.slice(hashIndex + 1)
+    if (hashQuery) return hashQuery
+  }
+
+  return undefined
+}
+
 export const getUTMSource = () => findInSearch(utmSourceRegex)
 
 export const getUTMMedium = () => findInSearch(utmMediumRegex) || getGclid()

package/tests/errors.test.ts

@@ -1,5 +1,6 @@
 import { init, trackError, trackErrors } from '../src/index'
 import { Lib } from '../src/Lib'
+import { setLocation } from './testUtils'
 
 jest.mock('../src/Lib', () => {
   const originalModule = jest.requireActual('../src/Lib')
@@ -71,15 +72,7 @@ describe('Error Tracking', () => {
 
     libInstance = init(PROJECT_ID, { devMode: true }) as Lib
 
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'example.com',
-        pathname: '/test-page',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'example.com', pathname: '/test-page' })
 
     window.addEventListener = jest.fn()
     window.removeEventListener = jest.fn()

package/tests/events.test.ts

@@ -1,5 +1,6 @@
 import { init, track } from '../src/index'
 import { Lib } from '../src/Lib'
+import { setLocation } from './testUtils'
 
 jest.mock('../src/Lib', () => {
   const originalModule = jest.requireActual('../src/Lib')
@@ -21,15 +22,7 @@ describe('Custom Event Tracking', () => {
 
     libInstance = init(PROJECT_ID, { devMode: true }) as Lib
 
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'example.com',
-        pathname: '/test-page',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'example.com', pathname: '/test-page' })
   })
 
   test('track function should track a custom event', async () => {

package/tests/experiments.test.ts

@@ -1,5 +1,6 @@
 import { init, getExperiment, getExperiments, clearExperimentsCache } from '../src/index'
 import { Lib } from '../src/Lib'
+import { setLocation } from './testUtils'
 
 // Mock fetch globally
 const mockFetch = jest.fn()
@@ -16,15 +17,7 @@ describe('A/B Testing Experiments', () => {
     // Reset fetch mock
     mockFetch.mockReset()
 
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'example.com',
-        pathname: '/test-page',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'example.com', pathname: '/test-page' })
   })
 
   describe('getExperiments', () => {

package/tests/initialisation.test.ts

@@ -1,5 +1,6 @@
 import { init } from '../src/index'
 import { Lib } from '../src/Lib'
+import { setLocation } from './testUtils'
 
 jest.mock('../src/Lib', () => {
   const originalModule = jest.requireActual('../src/Lib')
@@ -19,19 +20,12 @@ describe('Library Initialisation', () => {
 
     jest.resetModules()
 
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'example.com',
-        pathname: '/test-page',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'example.com', pathname: '/test-page' })
 
     Object.defineProperty(navigator, 'doNotTrack', {
       value: null,
       writable: true,
+      configurable: true,
     })
   })
 
@@ -45,15 +39,7 @@ describe('Library Initialisation', () => {
 
   test('init with devMode should work on localhost', () => {
     // Arrange
-    Object.defineProperty(window, 'location', {
-      value: {
-        hostname: 'localhost',
-        pathname: '/',
-        hash: '',
-        search: '',
-      },
-      writable: true,
-    })
+    setLocation({ hostname: 'localhost', pathname: '/' })
 
     // Act
     const instance = init('test-project-id', { devMode: true })
@@ -68,6 +54,7 @@ describe('Library Initialisation', () => {
     Object.defineProperty(navigator, 'doNotTrack', {
       value: '1',
       writable: true,
+      configurable: true,
     })
 
     // Act

package/tests/jsdomEnvironment.ts

@@ -0,0 +1,20 @@
+import JSDOMEnvironment from 'jest-environment-jsdom'
+import type { EnvironmentContext, JestEnvironmentConfig } from '@jest/environment'
+
+/**
+ * Extends jest-environment-jsdom to expose a `__setLocation` global so tests
+ * can change `window.location` via `JSDOM#reconfigure`. Direct assignment or
+ * `Object.defineProperty(window, 'location', ...)` no longer works in jsdom 22+
+ * because the property is defined as non-configurable.
+ */
+export default class CustomJSDOMEnvironment extends JSDOMEnvironment {
+  constructor(config: JestEnvironmentConfig, context: EnvironmentContext) {
+    super(config, context)
+
+    const dom = (this as any).dom
+
+    ;(this.global as any).__setLocation = (url: string) => {
+      dom.reconfigure({ url })
+    }
+  }
+}

package/tests/pageview.test.ts

@@ -1,5 +1,6 @@
 import { init, pageview, trackViews } from '../src/index'
 import { Lib } from '../src/Lib'
+import { setLocation } from './testUtils'
 
 jest.mock('../src/Lib', () => {
   const originalModule = jest.requireActual('../src/Lib')
@@ -21,19 +22,12 @@ describe('Pageview Tracking', () => {
 
     libInstance = init(PROJECT_ID, { devMode: true }) as Lib
 
-    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,
     })
   })