Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

52.1 KB
Raw Blame
import {
  isInBrowser,
  isLocalhost,
  isAutomated,
  getLocale,
  getTimezone,
  getReferrer,
  getQueryString,
  getUTMCampaign,
  getUTMMedium,
  getUTMSource,
  getUTMTerm,
  getUTMContent,
  getPath,
} from './utils.js'

type RrwebEvent = Record<string, unknown>

type RrwebEmit = (event: RrwebEvent) => void

interface RrwebRecordOptions {
  emit?: RrwebEmit
  [key: string]: unknown
}

interface RrwebRecordFn {
  (options: RrwebRecordOptions): (() => void) | undefined
  takeFullSnapshot?: (isCheckout?: boolean) => void
}

interface RrwebGlobal {
  record?: RrwebRecordFn
  Replayer?: unknown
}

type RrwebRecordModule = RrwebGlobal & {
  default?: RrwebGlobal
}

type SessionReplayPreloadOption = boolean | { rrwebUrl?: string }

interface SessionReplayStartResponse {
  replayId: string
  nextChunkIndex: number
}

declare global {
  interface Window {
    // Legacy global set by full rrweb bundles (self-hosted or custom rrwebUrl).
    rrweb?: RrwebGlobal
    // Global set by the @rrweb/record UMD bundle we ship.
    rrwebRecord?: RrwebGlobal | RrwebRecordFn
    __SWETRIX_RRWEB_LOADING__?: Promise<void>
  }
}

/**
 * Key / value metadata describing an identified user (email, plan, signup
 * date, ...). Values are stored as strings; `null` removes a trait.
 */
export type Traits = Record<string, string | number | boolean | null>

export interface OutboundLinksOptions {
  search?: boolean
  hash?: boolean
  ignoreDomains?: readonly string[]
}

export interface AutoCaptureOptions {
  outboundLinks?: boolean | OutboundLinksOptions
}

export interface LibOptions {
  events?: AutoCaptureOptions

  /**
   * When set to `true`, localhost events will be sent to server.
   */
  devMode?: boolean

  /**
   * When set to `true`, the tracking library won't send any data to server.
   * Useful for development purposes when this value is set based on `.env` var.
   */
  disabled?: boolean

  /**
   * By setting this flag to `true`, we will not collect ANY kind of data about the user with the DNT setting.
   */
  respectDNT?: boolean

  /** Set a custom URL of the API server; the default value is "https://api.swetrix.com/log"  */
  apiURL?: string

  /**
   * Optional profile ID for long-term user tracking.
   * If set, it will be used for all pageviews and events unless overridden per-call.
   */
  profileId?: string

  /**
   * Preload session replay recorder code. Recording only starts after calling startSessionReplay().
   */
  preloadSessionReplay?: SessionReplayPreloadOption
}

export interface TrackEventOptions {
  /** The custom event name. */
  ev: string

  /** If set to `true`, only 1 event with the same ID will be saved per user session. */
  unique?: boolean

  /** Event-related metadata object with string values. */
  meta?: {
    [key: string]: string | number | boolean | null | undefined
  }

  /** Optional profile ID for long-term user tracking. Overrides the global profileId if set. */
  profileId?: string
}

// Partial user-editable pageview payload
export interface IPageViewPayload {
  lc?: string
  tz?: string
  ref?: string
  so?: string
  me?: string
  ca?: string
  te?: string
  co?: string
  pg?: string | null
  title?: string | null

  /**
   * Raw URL query string of the landing page (without the leading `?`).
   * Used server-side to recover the traffic source from ad/social click
   * IDs (gclid, fbclid, etc.) when the browser stripped the referrer.
   */
  qs?: string

  /** Pageview-related metadata object with string values. */
  meta?: {
    [key: string]: string | number | boolean | null | undefined
  }

  /** Optional profile ID for long-term user tracking. Overrides the global profileId if set. */
  profileId?: string
}

// Partial user-editable error payload
export interface IErrorEventPayload {
  name: string
  message?: string | null
  lineno?: number | null
  colno?: number | null
  filename?: string | null
  stackTrace?: string | null
  meta?: {
    [key: string]: string | number | boolean | null | undefined
  }
}

export interface IInternalErrorEventPayload extends IErrorEventPayload {
  lc?: string
  tz?: string
  pg?: string | null
}

interface IPerfPayload {
  dns: number
  tls: number
  conn: number
  response: number
  render: number
  dom_load: number
  page_load: number
  ttfb: number
}

/**
 * Options for evaluating feature flags.
 */
export interface FeatureFlagsOptions {
  /**
   * Optional profile ID for long-term user tracking.
   * If not provided, an anonymous profile ID will be generated server-side based on IP and user agent.
   * Overrides the global profileId if set.
   */
  profileId?: string
}

/**
 * Options for evaluating experiments.
 */
export interface ExperimentOptions {
  /**
   * Optional profile ID for long-term user tracking.
   * If not provided, an anonymous profile ID will be generated server-side based on IP and user agent.
   * Overrides the global profileId if set.
   */
  profileId?: string
}

/**
 * Cached feature flags and experiments with timestamp.
 */
interface CachedData {
  flags: Record<string, boolean>
  experiments: Record<string, string>
  timestamp: number
  /** The profileId used when fetching this cached data */
  profileId?: string
}

/**
 * The object returned by `trackPageViews()`, used to stop tracking pages.
 */
export interface PageActions {
  /** Stops the tracking of pages. */
  stop: () => void
}

/**
 * The object returned by `trackErrors()`, used to stop tracking errors.
 */
export interface ErrorActions {
  /** Stops the tracking of errors. */
  stop: () => void
}

const SESSION_REPLAY_PRIVACY_VALUES = ['total', 'normal', 'none'] as const

export type SessionReplayPrivacy = (typeof SESSION_REPLAY_PRIVACY_VALUES)[number]

export interface SessionReplayOptions {
  privacy?: SessionReplayPrivacy
  rrweb?: RrwebRecordOptions
  flushIntervalMs?: number
  maxEventsPerChunk?: number
  maxBytesPerChunk?: number
  maxBytesPerEvent?: number
  sampleRate?: number
  maxDurationMs?: number
  idleTimeoutMs?: number
  maskAllText?: boolean
  recordIframes?: boolean
}

export interface SessionReplayActions {
  stop: () => Promise<void>
  flush: () => Promise<void>
}

export interface PageData {
  /** Current URL path. */
  path: string

  /** The object returned by `trackPageViews()`, used to stop tracking pages. */
  actions: PageActions
}

export interface ErrorOptions {
  /**
   * A number that indicates how many errors should be sent to the server.
   * Accepts values between 0 and 1. For example, if set to 0.5 - only ~50% of errors will be sent to Swetrix.
   * For testing, we recommend setting this value to 1. For production, you should configure it depending on your needs as each error event counts towards your plan.
   *
   * The default value for this option is 1.
   */
  sampleRate?: number

  /**
   * Callback to edit / prevent sending errors.
   *
   * @param payload - The error payload.
   * @returns The edited payload or `false` to prevent sending the error event. If `true` is returned, the payload will be sent as-is.
   */
  callback?: (payload: IInternalErrorEventPayload) => Partial<IInternalErrorEventPayload> | boolean
}

export interface PageViewsOptions {
  /**
   * If set to `true`, only unique events will be saved.
   * This param is useful when tracking single-page landing websites.
   */
  unique?: boolean

  /** Send Heartbeat requests when the website tab is not active in the browser. */
  heartbeatOnBackground?: boolean

  /**
   * Set to `true` to enable hash-based routing, or provide an array of hash values to include.
   * For example, use `true` for pages like /#/path, or `['pricing', 'features']` to include only those hashes.
   */
  hash?: boolean | readonly string[]

  /**
   * Set to `true` to enable search-based routing, or provide an array of query parameter names to include.
   * For example, use `true` for /path?search, or `['search', 'page']` to ignore all other parameters.
   */
  search?: boolean | readonly string[]

  /**
   * Callback to edit / prevent sending pageviews.
   *
   * @param payload - The pageview payload.
   * @returns The edited payload or `false` to prevent sending the pageview. If `true` is returned, the payload will be sent as-is.
   */
  callback?: (payload: IPageViewPayload) => Partial<IPageViewPayload> | boolean
}

export const defaultActions = {
  stop() {},
}

export const defaultSessionReplayActions: SessionReplayActions = {
  async stop() {},
  async flush() {},
}

const DEFAULT_API_HOST = 'https://api.swetrix.com/log'
const DEFAULT_API_BASE = 'https://api.swetrix.com'

/**
 * Events carry the raw, site-supplied profileId; the server stores them behind
 * this prefix. Mirrored here so getProfileId() can report the ID events are
 * actually stored under without an extra round trip.
 */
const USER_PROFILE_PREFIX = 'usr_'

const toStoredProfileId = (profileId: string) => `${USER_PROFILE_PREFIX}${profileId.trim()}`

const DEFAULT_RRWEB_FILE = 'replaylibrary.min.js'
const DEFAULT_RRWEB_URL = `https://cdn.jsdelivr.net/npm/swetrix@latest/dist/${DEFAULT_RRWEB_FILE}`
const DEFAULT_SESSION_REPLAY_FLUSH_INTERVAL = 5000
const DEFAULT_SESSION_REPLAY_MAX_EVENTS = 100
const DEFAULT_SESSION_REPLAY_MAX_CHUNK_BYTES = 512 * 1024
const DEFAULT_SESSION_REPLAY_MAX_EVENT_BYTES = 5 * 1024 * 1024
const DEFAULT_SESSION_REPLAY_MAX_DURATION_MS = 30 * 60 * 1000
const DEFAULT_SESSION_REPLAY_PRIVACY: SessionReplayPrivacy = 'total'
const DEFAULT_SESSION_REPLAY_SAMPLING = {
  mousemove: 50,
  scroll: 150,
  input: 'last',
}
const DEFAULT_SESSION_REPLAY_SLIM_DOM_OPTIONS = {
  script: true,
  comment: true,
  headFavicon: true,
  headWhitespace: true,
  headMetaDescKeywords: true,
  headMetaSocial: true,
  headMetaRobots: true,
  headMetaHttpEquiv: true,
  headMetaAuthorship: true,
  headMetaVerification: true,
}
const RRWEB_EVENT_FULL_SNAPSHOT = 2
// Chunk indices are reserved server-side, so retrying with the same index is
// idempotent - the backend dedupes on (replayId, chunkIndex).
const SESSION_REPLAY_CHUNK_RETRY_DELAYS_MS = [2_000, 5_000, 15_000]
// Snapshots are the largest payload we send, so a hop that rejects big bodies
// rejects every re-seed too. Cap the attempts rather than re-uploading a
// multi-megabyte snapshot on a loop for the rest of the session.
const SESSION_REPLAY_MAX_SNAPSHOT_RESEEDS = 3
const SESSION_REPLAY_ACTIVITY_EVENTS = ['click', 'keydown', 'mousedown', 'mousemove', 'scroll', 'touchstart'] as const

// Default cache duration: 5 minutes
const DEFAULT_CACHE_DURATION = 5 * 60 * 1000

const getStringByteLength = (value: string) => {
  if (typeof TextEncoder !== 'undefined') {
    return new TextEncoder().encode(value).length
  }

  if (typeof Blob !== 'undefined') {
    return new Blob([value]).size
  }

  return value.length
}

export class Lib {
  private pageData: PageData | null = null
  private pageViewsOptions?: PageViewsOptions | null = null
  private errorsOptions?: ErrorOptions | null = null
  private perfStatsCollected: boolean = false
  private activePage: string | null = null
  private errorListenerExists = false
  private cachedData: CachedData | null = null
  private rrwebLoader: Promise<void> | null = null
  private sessionReplayActions: SessionReplayActions | null = null
  private sessionReplayInitPromise: Promise<SessionReplayActions> | null = null
  // The server-side (usr_-prefixed) profile ID returned by the identify API
  private identifiedProfileId: string | null = null
  // The last profile ID sent to the identify API (to avoid duplicate requests)
  private lastIdentifySent: string | null = null

  constructor(
    private projectID: string,
    private options?: LibOptions,
  ) {
    this.trackPathChange = this.trackPathChange.bind(this)
    this.heartbeat = this.heartbeat.bind(this)
    this.captureError = this.captureError.bind(this)
    this.captureOutboundLink = this.captureOutboundLink.bind(this)

    if (this.options?.events?.outboundLinks && this.canTrack()) {
      document.addEventListener('click', this.captureOutboundLink, true)
      document.addEventListener('auxclick', this.captureOutboundLink, true)
    }

    if (this.getSessionReplayPreloadOption()) {
      void this.preloadSessionReplay().catch(() => undefined)
    }
  }

  stopAutoCapture(): void {
    if (!isInBrowser()) return
    document.removeEventListener('click', this.captureOutboundLink, true)
    document.removeEventListener('auxclick', this.captureOutboundLink, true)
  }

  private captureOutboundLink(event: MouseEvent): void {
    if (!this.canTrack() || (event.type === 'click' ? event.button !== 0 : event.button !== 1)) return

    const path = event.composedPath?.() || [event.target]
    const link = path.find((node) => node instanceof Element && node.matches('a[href], area[href]')) as
      | Element
      | undefined
    if (!link || path.some((node) => node instanceof Element && node.hasAttribute('data-swetrix-ignore'))) return

    const option = this.options?.events?.outboundLinks
    const config = typeof option === 'object' ? option : {}

    try {
      const url = new URL(link.getAttribute('href')!, document.baseURI)
      const hostname = url.hostname.replace(/^www\./, '')
      if (!['http:', 'https:'].includes(url.protocol) || hostname === window.location.hostname.replace(/^www\./, ''))
        return
      if (config.ignoreDomains?.some((domain) => hostname === domain.toLowerCase().replace(/^www\./, ''))) return

      url.username = ''
      url.password = ''
      if (!config.search) url.search = ''
      if (!config.hash) url.hash = ''
      if (url.href.length > 2048) return

      void this.sendRequest('outbound', {
        ...this.getEventContext(),
        qs: getQueryString()?.slice(0, 2048),
        url: url.href,
        title: document.title?.slice(0, 2048) || undefined,
      }).catch(() => undefined)
    } catch {}
  }

  captureError(event: ErrorEvent): void {
    if (typeof this.errorsOptions?.sampleRate === 'number' && this.errorsOptions.sampleRate >= Math.random()) {
      return
    }

    this.submitError(
      {
        // The file in which error occured.
        filename: event.filename,

        // The line of code error occured on.
        lineno: event.lineno,

        // The column of code error occured on.
        colno: event.colno,

        // Name of the error, if not exists (i.e. it's a custom thrown error). The initial value of name is "Error", but just in case lets explicitly set it here too.
        name: event.error?.name || 'Error',

        // Description of the error. By default, we use message from Error object, is it does not contain the error name
        // (we want to split error name and message so we could group them together later in dashboard).
        // If message in error object does not exist - lets use a message from the Error event itself.
        message: event.error?.message || event.message,

        // Stack trace of the error, if available.
        stackTrace: event.error?.stack,
      },
      true,
    )
  }

  trackErrors(options?: ErrorOptions): ErrorActions {
    if (this.errorListenerExists || !this.canTrack()) {
      return defaultActions
    }

    this.errorsOptions = options

    window.addEventListener('error', this.captureError)
    this.errorListenerExists = true

    return {
      stop: () => {
        window.removeEventListener('error', this.captureError)
        this.errorListenerExists = false
      },
    }
  }

  submitError(payload: IErrorEventPayload, evokeCallback?: boolean): void {
    const privateData = {
      pid: this.projectID,
    }

    const errorPayload = {
      pg:
        this.activePage ||
        getPath({
          hash: this.pageViewsOptions?.hash,
          search: this.pageViewsOptions?.search,
        }),
      lc: getLocale(),
      tz: getTimezone(),
      ...payload,
    }

    if (evokeCallback && this.errorsOptions?.callback) {
      const callbackResult = this.errorsOptions.callback(errorPayload)

      if (callbackResult === false) {
        return
      }

      if (callbackResult && typeof callbackResult === 'object') {
        Object.assign(errorPayload, callbackResult)
      }
    }

    Object.assign(errorPayload, privateData)

    this.sendRequest('error', errorPayload)
  }

  async track(event: TrackEventOptions): Promise<void> {
    if (!this.canTrack()) {
      return
    }

    await this.sendRequest('custom', {
      ...event,
      ...this.getEventContext(),
      profileId: event.profileId ?? this.options?.profileId,
    })
  }

  private getEventContext() {
    return {
      pid: this.projectID,
      pg:
        this.activePage ||
        getPath({
          hash: this.pageViewsOptions?.hash,
          search: this.pageViewsOptions?.search,
        }),
      lc: getLocale(),
      tz: getTimezone(),
      ref: getReferrer(),
      so: getUTMSource(),
      me: getUTMMedium(),
      ca: getUTMCampaign(),
      te: getUTMTerm(),
      co: getUTMContent(),
      qs: getQueryString(),
      profileId: this.options?.profileId,
    }
  }

  trackPageViews(options?: PageViewsOptions): PageActions {
    if (!this.canTrack()) {
      return defaultActions
    }

    if (this.pageData) {
      return this.pageData.actions
    }

    this.pageViewsOptions = options
    let interval: ReturnType<typeof setInterval>

    if (!options?.unique) {
      interval = setInterval(this.trackPathChange, 2000)
    }

    setTimeout(this.heartbeat, 3000)
    const hbInterval = setInterval(this.heartbeat, 28000)

    const path = getPath({
      hash: options?.hash,
      search: options?.search,
    })

    this.pageData = {
      path,
      actions: {
        stop: () => {
          clearInterval(interval)
          clearInterval(hbInterval)
        },
      },
    }

    this.trackPage(path, options?.unique)
    return this.pageData.actions
  }

  getPerformanceStats(): IPerfPayload | {} {
    if (!this.canTrack() || this.perfStatsCollected || !window.performance?.getEntriesByType) {
      return {}
    }

    const perf = window.performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming

    if (!perf) {
      return {}
    }

    this.perfStatsCollected = true

    return {
      // Network
      dns: perf.domainLookupEnd - perf.domainLookupStart, // DNS Resolution
      tls: perf.secureConnectionStart ? perf.requestStart - perf.secureConnectionStart : 0, // TLS Setup; checking if secureConnectionStart is not 0 (it's 0 for non-https websites)
      conn: perf.secureConnectionStart
        ? perf.secureConnectionStart - perf.connectStart
        : perf.connectEnd - perf.connectStart, // Connection time
      response: perf.responseEnd - perf.responseStart, // Response Time (Download)

      // Frontend
      render: perf.domComplete - perf.domContentLoadedEventEnd, // Browser rendering the HTML time
      dom_load: perf.domContentLoadedEventEnd - perf.responseEnd, // DOM loading timing
      page_load: perf.loadEventStart, // Page load time

      // Backend
      ttfb: perf.responseStart - perf.requestStart,
    }
  }

  /**
   * Fetches all feature flags for the project.
   * Results are cached for 5 minutes by default and share a cache with experiments.
   *
   * @param options - Options for evaluating feature flags (`profileId` only).
   * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
   * @returns A promise that resolves to a record of flag keys to boolean values.
   */
  async getFeatureFlags(options?: FeatureFlagsOptions, forceRefresh?: boolean): Promise<Record<string, boolean>> {
    if (!isInBrowser()) {
      return {}
    }

    const requestedProfileId = options?.profileId ?? this.options?.profileId

    // Check cache first - must match profileId and not be expired
    if (!forceRefresh && this.cachedData) {
      const now = Date.now()
      const isSameProfile = this.cachedData.profileId === requestedProfileId
      if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {
        return this.cachedData.flags
      }
    }

    try {
      await this.fetchFlagsAndExperiments(options)
      return this.cachedData?.flags || {}
    } catch (error) {
      console.warn('[Swetrix] Error fetching feature flags:', error)
      return this.cachedData?.flags || {}
    }
  }

  /**
   * Internal method to fetch both feature flags and experiments from the API.
   */
  private async fetchFlagsAndExperiments(options?: FeatureFlagsOptions | ExperimentOptions): Promise<void> {
    const apiBase = this.getApiBase()
    const body: { pid: string; profileId?: string } = {
      pid: this.projectID,
    }

    // Use profileId from options, or fall back to global profileId
    const profileId = options?.profileId ?? this.options?.profileId
    if (profileId) {
      body.profileId = profileId
    }

    const response = await fetch(`${apiBase}/feature-flag/evaluate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    })

    if (!response.ok) {
      console.warn('[Swetrix] Failed to fetch feature flags and experiments:', response.status)
      return
    }

    const data = (await response.json()) as {
      flags: Record<string, boolean>
      experiments?: Record<string, string>
    }

    // Use profileId from options, or fall back to global profileId
    const cachedProfileId = options?.profileId ?? this.options?.profileId

    // Update cache with both flags and experiments
    this.cachedData = {
      flags: data.flags || {},
      experiments: data.experiments || {},
      timestamp: Date.now(),
      profileId: cachedProfileId,
    }
  }

  /**
   * Gets the value of a single feature flag.
   *
   * @param key - The feature flag key.
   * @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.
   */
  async getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue: boolean = false): Promise<boolean> {
    const flags = await this.getFeatureFlags(options)
    return flags[key] ?? defaultValue
  }

  /**
   * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
   */
  clearFeatureFlagsCache(): void {
    this.cachedData = null
  }

  /**
   * Identify the current visitor with your own user ID (e.g. after they log in).
   *
   * The visitor's current anonymous profile gets linked to the identified
   * profile server-side, so their pre-login activity is attributed to it. All
   * events sent after this call are associated with the identified profile.
   *
   * Swetrix stores nothing in the browser, so call identify() on every page
   * load while the user is logged in. Call reset() when they log out.
   *
   * @param profileId A unique, stable identifier of the user, e.g. an internal
   * user ID. It's stored as you provide it, so don't pass values you wouldn't
   * want to see in your dashboard.
   * @param traits Optional key / value metadata to show on the user's profile,
   * e.g. their email, plan or signup date. Traits are merged with the ones
   * already stored; pass `null` to remove one.
   */
  async identify(profileId: string, traits?: Traits): Promise<void> {
    if (typeof profileId !== 'string' || !profileId.trim()) {
      console.error('[Swetrix] identify() expects a non-empty string profileId')
      return
    }

    const trimmed = profileId.trim()

    this.options = {
      ...this.options,
      profileId: trimmed,
    }

    // Traits are part of the payload, so re-send when only they changed
    const identifyKey = `${trimmed}:${traits ? JSON.stringify(traits) : ''}`

    if (!this.canTrack() || this.lastIdentifySent === identifyKey) {
      return
    }

    this.lastIdentifySent = identifyKey

    // The profile changed, so cached flags / experiments may no longer apply
    this.clearFeatureFlagsCache()

    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/identify`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ pid: this.projectID, profileId: trimmed, traits }),
      })

      if (!response.ok) {
        return
      }

      const data = (await response.json()) as { profileId: string | null }
      this.identifiedProfileId = data.profileId || null
    } catch {
      // Keep the profileId set locally even if the identify request failed -
      // events will still be attributed to the identified profile
    }
  }

  /**
   * Updates the traits of the already identified visitor without having to
   * repeat their user ID. Only the keys you pass are touched; pass `null` to
   * remove a trait.
   */
  async setTraits(traits: Traits): Promise<void> {
    const profileId = this.options?.profileId

    if (!profileId) {
      console.error('[Swetrix] setTraits() requires the visitor to be identified via identify() first')
      return
    }

    if (!traits || typeof traits !== 'object' || Array.isArray(traits)) {
      console.error('[Swetrix] setTraits() expects an object of traits')
      return
    }

    await this.identify(profileId, traits)
  }

  /**
   * Resets the visitor's identity set via identify() (e.g. after they log
   * out), so subsequent events are tracked anonymously again. Important on
   * shared devices - otherwise the next visitor would be tracked under the
   * previous user's identity.
   */
  reset(): void {
    if (this.options) {
      delete this.options.profileId
    }

    this.identifiedProfileId = null
    this.lastIdentifySent = null
    this.clearFeatureFlagsCache()
  }

  /**
   * 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 (`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.
   *
   * @example
   * ```typescript
   * const experiments = await getExperiments({ profileId: 'user-123' })
   * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
   * ```
   */
  async getExperiments(options?: ExperimentOptions, forceRefresh?: boolean): Promise<Record<string, string>> {
    if (!isInBrowser()) {
      return {}
    }

    const requestedProfileId = options?.profileId ?? this.options?.profileId

    // Check cache first - must match profileId and not be expired
    if (!forceRefresh && this.cachedData) {
      const now = Date.now()
      const isSameProfile = this.cachedData.profileId === requestedProfileId
      if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {
        return this.cachedData.experiments
      }
    }

    try {
      await this.fetchFlagsAndExperiments(options)
      return this.cachedData?.experiments || {}
    } catch (error) {
      console.warn('[Swetrix] Error fetching experiments:', error)
      return this.cachedData?.experiments || {}
    }
  }

  /**
   * Gets the variant key for a specific A/B test experiment.
   *
   * @param experimentId - The experiment ID.
   * @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', { profileId: 'user-123' })
   *
   * // Optional fallback variant:
   * const variantWithFallback = await getExperiment('checkout-redesign', undefined, 'control')
   *
   * if (variant === 'new-checkout') {
   *   // Show new checkout flow
   * } else {
   *   // Show control (original) checkout
   * }
   * ```
   */
  async getExperiment(
    experimentId: string,
    options?: ExperimentOptions,
    defaultVariant: string | null = null,
  ): Promise<string | null> {
    const experiments = await this.getExperiments(options)
    return experiments[experimentId] ?? defaultVariant
  }

  /**
   * Clears the cached experiments (alias for clearFeatureFlagsCache since they share the same cache).
   */
  clearExperimentsCache(): void {
    this.cachedData = null
  }

  /**
   * Gets the profile ID the current visitor's events are stored under.
   * If the visitor was identified via identify(), or a profileId was set via
   * init options, returns the identified (usr_-prefixed) ID. Otherwise,
   * requests server to generate an anonymous one from IP/UA hash.
   *
   * This ID can be used for revenue attribution with payment providers.
   *
   * @returns A promise that resolves to the profile ID string, or null on error.
   *
   * @example
   * ```typescript
   * const profileId = await swetrix.getProfileId()
   *
   * // Pass to Paddle Checkout for revenue attribution
   * Paddle.Checkout.open({
   *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
   *   customData: {
   *     swetrix_profile_id: profileId,
   *     swetrix_session_id: await swetrix.getSessionId()
   *   }
   * })
   * ```
   */
  async getProfileId(): Promise<string | null> {
    // If the visitor was identified, return the server-side (usr_-prefixed)
    // profile ID, which is what events are stored under
    if (this.identifiedProfileId) {
      return this.identifiedProfileId
    }

    // A profileId set via init() (or a failed identify() call) is sent raw on
    // events and prefixed server-side, so return the prefixed form here too -
    // returning the raw value would not match anything in the dashboard
    if (this.options?.profileId) {
      return toStoredProfileId(this.options.profileId)
    }

    if (!isInBrowser()) {
      return null
    }

    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/profile-id`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ pid: this.projectID }),
      })

      if (!response.ok) {
        return null
      }

      const data = (await response.json()) as { profileId: string | null }
      return data.profileId
    } catch {
      return null
    }
  }

  /**
   * Gets the current session ID for the visitor.
   * Session IDs are generated server-side based on IP and user agent.
   *
   * This ID can be used for revenue attribution with payment providers.
   *
   * @returns A promise that resolves to the session ID string, or null on error.
   *
   * @example
   * ```typescript
   * const sessionId = await swetrix.getSessionId()
   *
   * // Pass to Paddle Checkout for revenue attribution
   * Paddle.Checkout.open({
   *   items: [{ priceId: 'pri_01234567890', quantity: 1 }],
   *   customData: {
   *     swetrix_profile_id: await swetrix.getProfileId(),
   *     swetrix_session_id: sessionId
   *   }
   * })
   * ```
   */
  async getSessionId(): Promise<string | null> {
    if (!isInBrowser()) {
      return null
    }

    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/session-id`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ pid: this.projectID }),
      })

      if (!response.ok) {
        return null
      }

      const data = (await response.json()) as { sessionId: string | null }
      return data.sessionId
    } catch {
      return null
    }
  }

  async startSessionReplay(options: SessionReplayOptions = {}): Promise<SessionReplayActions> {
    if (this.sessionReplayActions) {
      return this.sessionReplayActions
    }

    if (this.sessionReplayInitPromise) {
      return this.sessionReplayInitPromise
    }

    const initPromise = this.initialiseSessionReplay(options)
    this.sessionReplayInitPromise = initPromise

    try {
      return await initPromise
    } finally {
      if (this.sessionReplayInitPromise === initPromise) {
        this.sessionReplayInitPromise = null
      }
    }
  }

  private async initialiseSessionReplay(options: SessionReplayOptions): Promise<SessionReplayActions> {
    if (this.sessionReplayActions) {
      return this.sessionReplayActions
    }

    if (!this.canTrack()) {
      return defaultSessionReplayActions
    }

    const maxDurationMs =
      typeof options.maxDurationMs === 'number' && options.maxDurationMs > 0
        ? options.maxDurationMs
        : DEFAULT_SESSION_REPLAY_MAX_DURATION_MS

    if (!this.shouldSampleSessionReplay(options.sampleRate)) {
      return defaultSessionReplayActions
    }

    try {
      await this.preloadSessionReplay()
    } catch {
      return defaultSessionReplayActions
    }

    const record = this.getRrwebRecorder()
    if (!record) {
      return defaultSessionReplayActions
    }

    const privacy = this.getSessionReplayPrivacy(options.privacy)
    const proposedReplayId = this.createReplayId()
    const started = await this.sendSessionReplayStart(proposedReplayId, privacy)

    if (!started) {
      return defaultSessionReplayActions
    }

    const replayId = started.replayId

    const flushIntervalMs =
      typeof options.flushIntervalMs === 'number' && options.flushIntervalMs > 0
        ? options.flushIntervalMs
        : DEFAULT_SESSION_REPLAY_FLUSH_INTERVAL
    const maxEventsPerChunk =
      typeof options.maxEventsPerChunk === 'number' && options.maxEventsPerChunk > 0
        ? Math.floor(options.maxEventsPerChunk)
        : DEFAULT_SESSION_REPLAY_MAX_EVENTS
    const maxBytesPerChunkCandidate =
      typeof options.maxBytesPerChunk === 'number' ? Math.floor(options.maxBytesPerChunk) : Number.NaN
    const maxBytesPerChunk =
      maxBytesPerChunkCandidate >= 1 ? maxBytesPerChunkCandidate : DEFAULT_SESSION_REPLAY_MAX_CHUNK_BYTES
    const maxBytesPerEventCandidate =
      typeof options.maxBytesPerEvent === 'number' ? Math.floor(options.maxBytesPerEvent) : Number.NaN
    const maxBytesPerEvent =
      maxBytesPerEventCandidate >= 1 ? maxBytesPerEventCandidate : DEFAULT_SESSION_REPLAY_MAX_EVENT_BYTES
    const idleTimeoutMs =
      typeof options.idleTimeoutMs === 'number' && options.idleTimeoutMs > 0 ? options.idleTimeoutMs : null

    let chunkIndex = started.nextChunkIndex
    let snapshotReseeds = 0
    let stopped = false
    let events: RrwebEvent[] = []
    let eventsByteLength = 0
    let flushing = Promise.resolve()
    let maxDurationTimer: ReturnType<typeof setTimeout> | undefined
    let idleTimer: ReturnType<typeof setTimeout> | undefined

    const flush = async (useBeacon = false) => {
      if (!events.length) return

      const chunk = events
      events = []
      eventsByteLength = 0
      const currentChunkIndex = chunkIndex++

      flushing = flushing
        .catch(() => undefined)
        .then(async () => {
          const delivered = await this.sendSessionReplayChunk(replayId, privacy, currentChunkIndex, chunk, useBeacon)

          // Losing a full snapshot makes every later event unrenderable, so
          // re-seed the stream instead of recording into the void.
          if (
            !delivered &&
            !stopped &&
            snapshotReseeds < SESSION_REPLAY_MAX_SNAPSHOT_RESEEDS &&
            chunk.some((event) => event.type === RRWEB_EVENT_FULL_SNAPSHOT)
          ) {
            snapshotReseeds += 1
            try {
              record.takeFullSnapshot?.()
            } catch {}
          }
        })

      await flushing
    }

    const userEmit = options.rrweb?.emit
    const recordOptions = this.getSessionReplayRecordOptions(
      privacy,
      options.rrweb,
      (event) => {
        try {
          userEmit?.(event)
        } catch {}

        let eventByteLength = 0

        try {
          eventByteLength = getStringByteLength(JSON.stringify(event))
        } catch {
          return
        }

        if (eventByteLength > maxBytesPerEvent) {
          return
        }

        if (events.length && eventsByteLength + eventByteLength > maxBytesPerChunk) {
          void flush()
        }

        events.push(event)
        eventsByteLength += eventByteLength
        if (events.length >= maxEventsPerChunk || eventsByteLength >= maxBytesPerChunk) {
          void flush()
        }
      },
      Boolean(options.recordIframes),
      options.maskAllText,
    )

    const stopRecording = record(recordOptions)
    const timer = setInterval(() => void flush(), flushIntervalMs)
    const flushOnPageExit = () => void flush(true)
    const flushOnHidden = () => {
      if (document.visibilityState === 'hidden') {
        void flush(true)
      }
    }
    const clearIdleTimer = () => {
      if (idleTimer) {
        clearTimeout(idleTimer)
        idleTimer = undefined
      }
    }
    const stopSessionReplay = async () => {
      if (stopped) return
      stopped = true
      clearInterval(timer)
      if (maxDurationTimer) {
        clearTimeout(maxDurationTimer)
      }
      clearIdleTimer()
      window.removeEventListener('pagehide', flushOnPageExit)
      document.removeEventListener('visibilitychange', flushOnHidden)
      SESSION_REPLAY_ACTIVITY_EVENTS.forEach((eventName) => {
        window.removeEventListener(eventName, resetIdleTimer)
      })
      stopRecording?.()
      await flush()
      this.sessionReplayActions = null
      this.sessionReplayInitPromise = null
    }
    const resetIdleTimer = () => {
      if (!idleTimeoutMs || stopped) return
      clearIdleTimer()
      idleTimer = setTimeout(() => void stopSessionReplay(), idleTimeoutMs)
    }

    window.addEventListener('pagehide', flushOnPageExit)
    document.addEventListener('visibilitychange', flushOnHidden)

    maxDurationTimer = setTimeout(() => void stopSessionReplay(), maxDurationMs)

    if (idleTimeoutMs) {
      SESSION_REPLAY_ACTIVITY_EVENTS.forEach((eventName) => {
        window.addEventListener(eventName, resetIdleTimer, { passive: true })
      })
      resetIdleTimer()
    }

    this.sessionReplayActions = {
      stop: stopSessionReplay,
      flush: async () => {
        await flush()
      },
    }

    return this.sessionReplayActions
  }

  private shouldSampleSessionReplay(sampleRate?: number): boolean {
    if (typeof sampleRate !== 'number') {
      return true
    }

    if (sampleRate <= 0) {
      return false
    }

    if (sampleRate >= 1) {
      return true
    }

    return Math.random() < sampleRate
  }

  private getSessionReplayPrivacy(privacy: unknown): SessionReplayPrivacy {
    return SESSION_REPLAY_PRIVACY_VALUES.includes(privacy as SessionReplayPrivacy)
      ? (privacy as SessionReplayPrivacy)
      : DEFAULT_SESSION_REPLAY_PRIVACY
  }

  /**
   * Gets the API base URL (without /log suffix).
   */
  private getApiBase(): string {
    if (this.options?.apiURL) {
      // Remove trailing /log if present
      return this.options.apiURL.replace(/\/log\/?$/, '')
    }
    return DEFAULT_API_BASE
  }

  private heartbeat(): void {
    if (!this.pageViewsOptions?.heartbeatOnBackground && document.visibilityState === 'hidden') {
      return
    }

    const data: { pid: string; profileId?: string } = {
      pid: this.projectID,
    }

    if (this.options?.profileId) {
      data.profileId = this.options.profileId
    }

    this.sendRequest('hb', data)
  }

  // Tracking path changes. If path changes -> calling this.trackPage method
  private trackPathChange(): void {
    if (!this.pageData) return
    const newPath = getPath({
      hash: this.pageViewsOptions?.hash,
      search: this.pageViewsOptions?.search,
    })
    const { path } = this.pageData

    if (path !== newPath) {
      this.trackPage(newPath, false)
    }
  }

  private trackPage(pg: string, unique: boolean = false): void {
    if (!this.pageData) return
    this.pageData.path = pg

    const perf = this.getPerformanceStats()

    this.activePage = pg
    this.submitPageView({ pg }, unique, perf, true)
  }

  submitPageView(
    payload: Partial<IPageViewPayload>,
    unique: boolean,
    perf: IPerfPayload | {},
    evokeCallback?: boolean,
  ): void {
    const privateData = {
      pid: this.projectID,
      perf,
      unique,
    }

    const pvPayload = {
      title: isInBrowser() ? document.title : undefined,
      lc: getLocale(),
      tz: getTimezone(),
      ref: getReferrer(),
      so: getUTMSource(),
      me: getUTMMedium(),
      ca: getUTMCampaign(),
      te: getUTMTerm(),
      co: getUTMContent(),
      qs: getQueryString(),
      profileId: this.options?.profileId,
      ...payload,
    }

    if (evokeCallback && this.pageViewsOptions?.callback) {
      const callbackResult = this.pageViewsOptions.callback(pvPayload as IPageViewPayload)

      if (callbackResult === false) {
        return
      }

      if (callbackResult && typeof callbackResult === 'object') {
        Object.assign(pvPayload, callbackResult)
      }
    }

    if (evokeCallback) {
      this.activePage = pvPayload.pg || null
    }

    if (typeof pvPayload.title === 'string') {
      pvPayload.title = pvPayload.title.slice(0, 2048)
    }

    Object.assign(pvPayload, privateData)

    this.sendRequest('', pvPayload)
  }

  private canTrack(): boolean {
    if (
      this.options?.disabled ||
      !isInBrowser() ||
      (this.options?.respectDNT && window.navigator?.doNotTrack === '1') ||
      (!this.options?.devMode && isLocalhost()) ||
      isAutomated()
    ) {
      return false
    }

    return true
  }

  private getSessionReplayUrl(): string {
    const replayOption = this.getSessionReplayPreloadOption()
    if (replayOption && typeof replayOption === 'object' && replayOption.rrwebUrl) {
      return replayOption.rrwebUrl
    }

    return this.getDefaultSessionReplayUrl()
  }

  private getSessionReplayPreloadOption(): SessionReplayPreloadOption | undefined {
    return this.options?.preloadSessionReplay
  }

  private getDefaultSessionReplayUrl(): string {
    if (!isInBrowser()) {
      return DEFAULT_RRWEB_URL
    }

    const trackerScript = this.getTrackerScript()

    if (trackerScript?.src) {
      const { hostname, pathname } = new URL(trackerScript.src)
      if (hostname === 'swetrix.org' && /^\/swetrix(\.min)?\.js$/i.test(pathname)) {
        return DEFAULT_RRWEB_URL
      }

      return new URL(DEFAULT_RRWEB_FILE, trackerScript.src).toString()
    }

    return DEFAULT_RRWEB_URL
  }

  private getTrackerScript(): HTMLScriptElement | undefined {
    const trackerScript = Array.from(document.scripts).find((script) => {
      if (!script.src) {
        return false
      }

      try {
        const { pathname } = new URL(script.src)
        return /(^|\/)swetrix(\.min)?\.js$/i.test(pathname)
      } catch {
        return false
      }
    })

    return trackerScript
  }

  private getRrwebRecorder(): RrwebRecordFn | undefined {
    if (!isInBrowser()) {
      return undefined
    }

    if (typeof window.rrweb?.record === 'function') {
      return window.rrweb.record
    }

    const globalRecord = window.rrwebRecord
    if (typeof globalRecord === 'function') {
      return globalRecord
    }

    if (globalRecord && typeof globalRecord.record === 'function') {
      return globalRecord.record
    }

    return undefined
  }

  private preloadSessionReplay(): Promise<void> {
    if (!isInBrowser()) {
      return Promise.resolve()
    }

    if (this.getRrwebRecorder()) {
      return Promise.resolve()
    }

    if (this.rrwebLoader) {
      return this.rrwebLoader
    }

    if (window.__SWETRIX_RRWEB_LOADING__) {
      this.rrwebLoader = window.__SWETRIX_RRWEB_LOADING__
      void this.rrwebLoader.catch(() => {
        if (window.__SWETRIX_RRWEB_LOADING__ === this.rrwebLoader) {
          delete window.__SWETRIX_RRWEB_LOADING__
        }
        this.rrwebLoader = null
      })
      return this.rrwebLoader
    }

    this.rrwebLoader = this.loadSessionReplayRecorder()

    window.__SWETRIX_RRWEB_LOADING__ = this.rrwebLoader
    const loader = this.rrwebLoader
    void loader.catch(() => {
      if (window.__SWETRIX_RRWEB_LOADING__ === loader) {
        delete window.__SWETRIX_RRWEB_LOADING__
      }
      if (this.rrwebLoader === loader) {
        this.rrwebLoader = null
      }
    })

    return this.rrwebLoader
  }

  private async loadSessionReplayRecorder(): Promise<void> {
    const replayOption = this.getSessionReplayPreloadOption()
    const hasCustomReplayUrl = replayOption && typeof replayOption === 'object' && replayOption.rrwebUrl

    if (hasCustomReplayUrl || this.getTrackerScript()) {
      await this.loadSessionReplayScript(this.getSessionReplayUrl())
      return
    }

    if (await this.loadSessionReplayPackage()) {
      return
    }

    await this.loadSessionReplayScript(this.getDefaultSessionReplayUrl())
  }

  private async loadSessionReplayPackage(): Promise<boolean> {
    try {
      const rrwebModule = (await import('@rrweb/record')) as RrwebRecordModule
      const record = rrwebModule.record || rrwebModule.default?.record

      if (typeof record !== 'function') {
        return false
      }

      window.rrwebRecord = { record }
      return true
    } catch {
      return false
    }
  }

  private loadSessionReplayScript(url: string): Promise<void> {
    return new Promise<void>((resolve, reject) => {
      const script = document.createElement('script')
      script.async = true
      script.src = url
      script.crossOrigin = 'anonymous'
      script.onload = () => resolve()
      script.onerror = () => reject(new Error('Failed to load rrweb'))
      document.head.appendChild(script)
    })
  }

  private getSessionReplayRecordOptions(
    privacy: unknown,
    userOptions: RrwebRecordOptions | undefined,
    emit: RrwebEmit,
    recordIframes: boolean,
    maskAllText?: boolean,
  ): RrwebRecordOptions {
    const hasUserSampling = userOptions && Object.prototype.hasOwnProperty.call(userOptions, 'sampling')
    const hasUserSlimDOMOptions = userOptions && Object.prototype.hasOwnProperty.call(userOptions, 'slimDOMOptions')
    const sampling =
      typeof userOptions?.sampling === 'object' && userOptions.sampling !== null
        ? {
            ...DEFAULT_SESSION_REPLAY_SAMPLING,
            ...(userOptions.sampling as Record<string, unknown>),
          }
        : hasUserSampling
          ? userOptions?.sampling
          : DEFAULT_SESSION_REPLAY_SAMPLING
    const slimDOMOptions =
      typeof userOptions?.slimDOMOptions === 'object' && userOptions.slimDOMOptions !== null
        ? {
            ...DEFAULT_SESSION_REPLAY_SLIM_DOM_OPTIONS,
            ...(userOptions.slimDOMOptions as Record<string, unknown>),
          }
        : hasUserSlimDOMOptions
          ? userOptions?.slimDOMOptions
          : DEFAULT_SESSION_REPLAY_SLIM_DOM_OPTIONS
    const options: RrwebRecordOptions = {
      recordCanvas: false,
      recordCrossOriginIframes: false,
      collectFonts: false,
      inlineImages: false,
      ...userOptions,
      sampling,
      slimDOMOptions,
      emit,
    }

    const maskInputOptions =
      typeof options.maskInputOptions === 'object' && options.maskInputOptions !== null
        ? (options.maskInputOptions as Record<string, unknown>)
        : {}

    const resolvedPrivacy = this.getSessionReplayPrivacy(privacy)
    const defaultBlockSelector = recordIframes ? undefined : 'iframe'
    const resolvedMaskAllText = typeof maskAllText === 'boolean' ? maskAllText : resolvedPrivacy === 'total'
    const textMaskingOptions = resolvedMaskAllText ? { maskTextSelector: '*' } : {}

    if (resolvedPrivacy === 'total') {
      return {
        ...options,
        ...textMaskingOptions,
        maskAllInputs: true,
        blockSelector: this.mergeSelectors(
          this.mergeSelectors(options.blockSelector, defaultBlockSelector),
          'img, picture, video, audio, canvas, svg',
        ),
        recordCanvas: false,
        inlineImages: false,
        emit,
      }
    }

    if (resolvedPrivacy === 'normal') {
      return {
        ...options,
        ...textMaskingOptions,
        maskAllInputs: true,
        blockSelector: this.mergeSelectors(options.blockSelector, defaultBlockSelector),
        emit,
      }
    }

    return {
      ...options,
      ...textMaskingOptions,
      blockSelector: this.mergeSelectors(options.blockSelector, defaultBlockSelector),
      maskInputOptions: {
        ...maskInputOptions,
        password: true,
      },
      emit,
    }
  }

  private mergeSelectors(existing: unknown, required?: string): string | undefined {
    if (!required) {
      return typeof existing === 'string' ? existing : undefined
    }

    if (typeof existing === 'string' && existing.trim()) {
      return `${existing}, ${required}`
    }

    return required
  }

  private createReplayId(): string {
    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
      return crypto.randomUUID()
    }

    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
  }

  private async sendSessionReplayStart(
    replayId: string,
    privacy: SessionReplayPrivacy,
  ): Promise<SessionReplayStartResponse | null> {
    try {
      const apiBase = this.getApiBase()
      const response = await fetch(`${apiBase}/log/session-replay/start`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          pid: this.projectID,
          replayId,
          privacy,
          pg:
            this.activePage ||
            getPath({
              hash: this.pageViewsOptions?.hash,
              search: this.pageViewsOptions?.search,
            }),
          lc: getLocale(),
          tz: getTimezone(),
          profileId: this.options?.profileId,
        }),
      })

      if (!response.ok) {
        return null
      }

      try {
        const result = (await response.json()) as Partial<{
          replayId: unknown
          nextChunkIndex: unknown
        }>
        const resolvedReplayId = typeof result.replayId === 'string' && result.replayId ? result.replayId : replayId
        const resolvedChunkIndex =
          typeof result.nextChunkIndex === 'number' &&
          Number.isFinite(result.nextChunkIndex) &&
          result.nextChunkIndex >= 0
            ? Math.floor(result.nextChunkIndex)
            : 0

        return {
          replayId: resolvedReplayId,
          nextChunkIndex: resolvedChunkIndex,
        }
      } catch {
        return {
          replayId,
          nextChunkIndex: 0,
        }
      }
    } catch {
      return null
    }
  }

  private async sendSessionReplayChunk(
    replayId: string,
    privacy: SessionReplayPrivacy,
    chunkIndex: number,
    events: RrwebEvent[],
    useBeacon: boolean,
  ): Promise<boolean> {
    const apiBase = this.getApiBase()
    const url = `${apiBase}/log/session-replay/chunk`
    const payload = JSON.stringify({
      pid: this.projectID,
      replayId,
      privacy,
      chunkIndex,
      events,
    })

    if (useBeacon && typeof navigator.sendBeacon === 'function') {
      // sendBeacon refuses payloads over its ~64 KB quota; fall through to
      // fetch when it does.
      const sent = navigator.sendBeacon(url, new Blob([payload], { type: 'application/json' }))
      if (sent) return true
    }

    // On the beacon path the page is unloading, so there is no time to retry.
    const attempts = useBeacon ? 1 : SESSION_REPLAY_CHUNK_RETRY_DELAYS_MS.length + 1

    for (let attempt = 0; attempt < attempts; attempt++) {
      if (attempt > 0) {
        await new Promise((resolve) => setTimeout(resolve, SESSION_REPLAY_CHUNK_RETRY_DELAYS_MS[attempt - 1]))
      }

      try {
        const response = await fetch(url, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          // Browsers reject keepalive bodies over ~64 KB, so oversized
          // payloads go through a regular request instead.
          keepalive: useBeacon && payload.length < 60_000,
          body: payload,
        })

        if (response.ok) {
          return true
        }

        // Client errors (except timeouts and rate limits) won't succeed on
        // retry.
        if (response.status < 500 && response.status !== 408 && response.status !== 429) {
          return false
        }
      } catch {}
    }

    return false
  }

  private async sendRequest(path: string, body: object): Promise<void> {
    const host = this.options?.apiURL || DEFAULT_API_HOST
    const payload = JSON.stringify(body)
    await fetch(`${host}/${path}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      // Lets the request survive page unloads (e.g. tracking an outbound
      // link click). Browsers reject keepalive bodies over ~64 KB, so
      // oversized payloads fall back to a regular request.
      keepalive: payload.length < 60_000,
      body: payload,
    })
  }
}