posthog-config.ts

/**
 * PostHog configuration types
 */

import type { JsonType, Properties } from './common'
import type { LogAttributes, BeforeSendLogFn } from './capture-log'
import type { MetricAttributes, BeforeSendMetricFn } from './capture-metric'
import type { BeforeSendFn, CaptureResult } from './capture'
import type { RequestResponse } from './request'
import type {
    CanvasMaskRegion,
    CapturedNetworkRequest,
    NetworkRequest,
    SessionRecordingCanvasOptions,
} from './session-recording'
import type { SegmentAnalytics } from './segment'
import type { PostHog } from './posthog'

export type AutocaptureCompatibleElement = 'a' | 'button' | 'form' | 'input' | 'select' | 'textarea' | 'label'
export type DomAutocaptureEvents = 'click' | 'change' | 'submit'

/**
 * If an array is passed for an allowlist, autocapture events will only be sent for elements matching
 * at least one of the elements in the array. Multiple allowlists can be used
 */
export interface AutocaptureConfig {
    /**
     * List of URLs to allow autocapture on, can be strings to match
     * or regexes e.g. ['https://example.com', 'test.com/.*']
     * this is useful when you want to autocapture on specific pages only
     *
     * if you set both url_allowlist and url_ignorelist,
     * we check the allowlist first and then the ignorelist.
     * the ignorelist can override the allowlist
     */
    url_allowlist?: (string | RegExp)[]

    /**
     * List of URLs to not allow autocapture on, can be strings to match
     * or regexes e.g. ['https://example.com', 'test.com/.*']
     * this is useful when you want to autocapture on most pages but not some specific ones
     *
     * if you set both url_allowlist and url_ignorelist,
     * we check the allowlist first and then the ignorelist.
     * the ignorelist can override the allowlist
     */
    url_ignorelist?: (string | RegExp)[]

    /**
     * List of DOM events to allow autocapture on  e.g. ['click', 'change', 'submit']
     */
    dom_event_allowlist?: DomAutocaptureEvents[]

    /**
     * List of DOM elements to allow autocapture on
     * e.g. ['a', 'button', 'form', 'input', 'select', 'textarea', 'label']
     *
     * We consider the tree of elements from the root to the target element of the click event
     * so for the tree `div > div > button > svg`
     * if the allowlist has `button` then we allow the capture when the `button` or the `svg` is the click target
     * but not if either of the `div`s are detected as the click target
     */
    element_allowlist?: AutocaptureCompatibleElement[]

    /**
     * List of CSS selectors to allow autocapture on
     * e.g. ['[ph-capture]']
     * we consider the tree of elements from the root to the target element of the click event
     * so for the tree div > div > button > svg
     * and allow list config `['[id]']`
     * we will capture the click if the click-target or its parents has any id
     *
     * Everything is allowed when there's no allowlist
     */
    css_selector_allowlist?: string[]

    /**
     * List of CSS selectors to ignore autocapture on
     * e.g. ['[data-ph-no-autocapture]']
     * we consider the tree of elements from the root to the target element of the click event
     * so for the tree div > div > button > svg
     * and ignore list config `['[id]']`
     * we will ignore the click if the click-target or its parents has any id
     *
     * Nothing is ignored when there's an empty ignorelist, e.g. []
     * If no ignorelist is set, we default to ignoring .ph-no-autocapture and [data-ph-no-autocapture]
     * Note: providing any custom list fully replaces the defaults — include .ph-no-autocapture
     * and [data-ph-no-autocapture] explicitly if you still want them honoured.
     */
    css_selector_ignorelist?: string[]

    /**
     * Exclude certain element attributes from autocapture
     * E.g. ['aria-label'] or [data-attr-pii]
     */
    element_attribute_ignorelist?: string[]

    /**
     * When true, autocapture captures cut, copy, and paste interactions. Paste events do not contain pasted text.
     */
    capture_copied_text?: boolean
}

export interface RageclickConfig {
    /**
     * List of CSS selectors to ignore rageclicks on
     * e.g. ['.my-calendar-button']
     * we consider the tree of elements from the root to the target element of the click event
     * so for the tree div > div > button > svg
     * and ignore list config `['[id]']`
     * we will ignore the rageclick if the click-target or its parents has any id
     *
     * Nothing is ignored when there's an empty ignorelist, e.g. []
     * If no ignorelist is set, we default to ignoring .ph-no-rageclick
     * If an element has .ph-no-capture, it will always be ignored by rageclick and autocapture
     */
    css_selector_ignorelist?: string[]
    /**
     * Controls automatic exclusion of elements by text content from rageclick detection.
     * Useful for pagination buttons, loading spinners, and other repeatedly-clicked UI elements.
     * - `true`: Use default keywords ['next', 'previous', 'prev', '>', '<']
     * - `false`: Disable content-based exclusion
     * - `string[]`: Use custom keywords (max 10 items, otherwise use css_selector_ignorelist)
     *
     * Checks if element text content or aria-label matches any of the keywords (case-insensitive).
     * Word keywords match as substrings; symbol-only keywords (e.g. '+', '-', '>') match exactly,
     * so they don't suppress text like "sign-up", "5 > 3", or "C++".
     *
     * @default undefined
     * (`true` when `defaults` is `'2025-11-30'` or later;
     * `['next', 'previous', 'prev', '>', '<', '+', '-', '−', '–']` when `defaults` is `'2026-05-30'` or later)
     */
    content_ignorelist?: boolean | string[]

    /**
     * Excludes text-editing surfaces (textarea, text-like inputs, and contenteditable elements)
     * from rageclick detection, since rapid repeated clicks there are double/triple-click text
     * selection rather than rage.
     * Enabled by default from the 2026-05-30 config defaults onwards.
     * @default false
     */
    ignore_text_selection?: boolean

    /**
     * Maximum pixel distance between clicks to still be considered a rage click.
     * @default 30
     */
    threshold_px?: number

    /**
     * Number of consecutive clicks within the timeout to qualify as a rage click.
     * @default 3
     */
    click_count?: number

    /**
     * Maximum time window (in milliseconds) between the first and last click.
     * @default 1000
     */
    timeout_ms?: number
}

export interface BootstrapConfig {
    /**
     * Distinct ID to use before the SDK has loaded persisted identity.
     */
    distinctID?: string

    /**
     * Whether `distinctID` already identifies a known person profile.
     */
    isIdentifiedID?: boolean

    /**
     * Feature flag values to use immediately until the SDK fetches fresh values.
     */
    featureFlags?: Record<string, boolean | string>

    /**
     * Feature flag payloads to use together with bootstrapped `featureFlags`.
     */
    featureFlagPayloads?: Record<string, JsonType>

    /**
     * Optionally provide a sessionID, this is so that you can provide an existing sessionID here to continue a user's session across a domain or device. It MUST be:
     * - unique to this user
     * - a valid UUID v7
     * - the timestamp part must be <= the timestamp of the first event in the session
     * - the timestamp of the last event in the session must be < the timestamp part + 24 hours
     */
    sessionID?: string
}

export interface ResetOptions {
    /**
     * Whether to generate a new device ID as well as a new distinct ID.
     * @default false
     */
    resetDeviceID?: boolean

    /**
     * Identity, feature flag, and session values to apply after resetting.
     */
    bootstrap?: BootstrapConfig
}

export type SupportedWebVitalsMetrics = 'LCP' | 'CLS' | 'FCP' | 'INP'

export interface PerformanceCaptureConfig {
    /**
     *  Works with session replay to use the browser's native performance observer to capture performance metrics
     */
    network_timing?: boolean

    /**
     * Use chrome's web vitals library to wrap fetch and capture web vitals
     *
     * When `cookieless_mode` is active, there is no client-side SessionIdManager; vitals are still
     * captured. Nested `$web_vitals_*_event` payloads omit `$session_id` / `$window_id`; PostHog ingestion assigns
     * `$session_id` server-side for cookieless traffic when project cookieless settings are enabled (same as other events).
     */
    web_vitals?: boolean

    /**
     * We observe very large values reported by the Chrome web vitals library
     * These outliers are likely not real, useful values, and we exclude them
     * You can set this to 0 in order to include all values, NB this is not recommended
     *
     * @default 15 * 60 * 1000 (15 minutes)
     */
    __web_vitals_max_value?: number

    /**
     * By default all 4 metrics are captured
     * You can set this config to restrict which metrics are captured
     * e.g. ['CLS', 'FCP'] to only capture those two metrics
     * NB setting this does not override whether the capture is enabled
     *
     * @default ['LCP', 'CLS', 'FCP', 'INP']
     */
    web_vitals_allowed_metrics?: SupportedWebVitalsMetrics[]

    /**
     * We delay flushing web vitals metrics to reduce the number of events we send
     * This is the maximum time we will wait before sending the metrics
     *
     * @default 5000
     */
    web_vitals_delayed_flush_ms?: number

    /**
     * Which web vitals metrics include attribution data. Attribution names the
     * cause of a metric, such as the slow interaction target for INP or the load-phase
     * breakdown for LCP, which is what makes a slow number diagnosable.
     *
     * Pass `true` to attribute all metrics, `false` for none, or an array to name them.
     * The default attributes INP and LCP only. CLS is excluded by default because its
     * attribution holds detached DOM nodes and can leak memory in single-page apps.
     *
     * @default ['INP', 'LCP']
     */
    web_vitals_attribution?: boolean | SupportedWebVitalsMetrics[]

    /**
     * Scope web vitals metrics to the browser's Soft Navigation entries, so that
     * client-side route changes in single-page apps each start a fresh measurement
     * window instead of accumulating against the original hard-navigation timestamp.
     *
     * Without this, an SPA's LCP observer keeps treating the "largest paint so far"
     * as belonging to the initial page load across every subsequent route change,
     * which inflates LCP (and the other metrics) by the time spent on the app.
     *
     * This is a preview option (opt-in) because it relies on Chrome's Soft Navigation Detection API,
     * which is still experimental. When enabled, PostHog loads a pinned stable web-vitals 6.x
     * bundle and passes `reportSoftNavs` to the observers. The default path remains on the
     * existing web-vitals 5.x bundle. In browsers without soft-nav support, metrics fall
     * back to their existing hard-navigation behavior.
     *
     * @default false
     */
    __preview_web_vitals_soft_navs?: boolean
}

export interface DeadClickCandidate {
    node: Element
    // clicks carry a MouseEvent, swipes carry the TouchEvent that ended the gesture
    originalEvent: MouseEvent | TouchEvent
    timestamp: number
    // whether this candidate came from a click (default) or a touch swipe gesture
    type?: 'click' | 'swipe'
    // for swipe candidates, the dominant direction of the gesture
    swipeDirection?: 'left' | 'right' | 'up' | 'down'
    // for swipe candidates, the straight-line distance in CSS pixels between where the gesture started and ended
    swipeDistancePx?: number
    // time between click and the most recent scroll
    scrollDelayMs?: number
    // time between click and the most recent mutation
    mutationDelayMs?: number
    // time between click and the most recent selection changed event
    selectionChangedDelayMs?: number
    // delay between the click and the nearest visibility change within the suppression window, on
    // either side — a tab going to or from hidden near a click (opening a new tab, or waking the
    // tab) is a liveness signal, so it only ever suppresses a dead click, never causes one. recorded
    // as the event fires (not read from a shared timestamp at check time) so a later transition
    // can't overwrite the click-correlated one
    visibilityChangedDelayMs?: number
    // as above for window focus/blur — a click that opens a new window/popup may only surface as
    // the current window losing focus, so this is the liveness signal for that case
    focusChangedDelayMs?: number
    // if neither scroll nor mutation seen before threshold passed
    absoluteDelayMs?: number
}

/**
 * Controls buffering and payload limits for exception steps added via `addExceptionStep`.
 *
 * NOTE: This type is also defined in `@posthog/core` (exception-steps.ts). Keep both in sync.
 */
export type ExceptionStepsConfig = {
    /**
     * Determines whether PostHog should collect exception steps and attach them to the next captured exception.
     *
     * @default true
     */
    enabled?: boolean

    /**
     * The maximum UTF-8 byte budget for exception steps buffered in memory.
     * Oldest steps are evicted when the budget is exceeded.
     *
     * @default 32768 (~32KB)
     */
    max_bytes?: number
}

export type ExceptionAutoCaptureConfig = {
    /**
     * Determines whether PostHog should capture unhandled errors.
     *
     * @default true
     */
    capture_unhandled_errors?: boolean

    /**
     * Determines whether PostHog should capture unhandled promise rejections.
     *
     * @default true
     */
    capture_unhandled_rejections?: boolean

    /**
     * Determines whether PostHog should capture console errors.
     *
     * @default false
     */
    capture_console_errors?: boolean
}

export type DeadClicksAutoCaptureConfig = {
    /**
     * We'll not consider a click to be a dead click, if it's followed by a scroll within `scroll_threshold_ms` milliseconds
     *
     * @default 100
     */
    scroll_threshold_ms?: number

    /**
     * We'll not consider a click to be a dead click, if it's followed by a selection change within `selection_change_threshold_ms` milliseconds
     *
     * @default 100
     */
    selection_change_threshold_ms?: number

    /**
     * We'll not consider a click to be a dead click, if it's followed by a mutation within `mutation_threshold_ms` milliseconds
     *
     * @default 2500
     */
    mutation_threshold_ms?: number

    /**
     * By default, clicks with modifier keys (ctrl, shift, alt, meta/cmd) held down are not considered dead clicks,
     * since these typically indicate intentional actions like "open in new tab".
     *
     * Set this to true to capture dead clicks even when modifier keys are held.
     *
     * @default false
     */
    capture_clicks_with_modifier_keys?: boolean

    /**
     * Determines whether PostHog should also detect "dead swipes" — touch swipe gestures
     * (typically on mobile/touch devices) that produce no observable screen change
     * (no scroll, mutation or selection change while the gesture is in progress, and no
     * scroll, mutation, selection or visibility change afterwards). These usually indicate
     * a failed navigation, e.g. swiping to go back or to move a carousel with nothing
     * happening.
     *
     * Dead swipes are captured as `$dead_swipe` events. This only applies to the dead-click
     * autocapture path, not the heatmaps path.
     *
     * Swipes over surfaces whose response cannot be observed — canvas, video and other
     * media/plugin elements under the finger — are never captured, and capture is limited
     * per page load (see `max_dead_swipes_per_page_load`).
     *
     * @default true
     */
    capture_dead_swipes?: boolean

    /**
     * The minimum straight-line distance in CSS pixels between where a touch gesture starts
     * and ends for it to be considered a swipe (rather than a tap). Only used when
     * `capture_dead_swipes` is enabled.
     *
     * @default 30
     */
    swipe_threshold_px?: number

    /**
     * The maximum number of dead swipes captured per page load. Swipe gestures are plentiful
     * on touch devices, so a page whose responses the detector cannot see is capped rather
     * than allowed to flood events. Only used when `capture_dead_swipes` is enabled.
     *
     * @default 10
     */
    max_dead_swipes_per_page_load?: number

    /**
     * List of CSS selectors to ignore dead clicks on
     * e.g. ['.my-download-link']
     * we consider the tree of elements from the root to the target element of the click event
     * so for the tree div > div > a > svg
     * and ignore list config `['[download]']`
     * we will ignore the dead click if the click-target or its parents has any download attribute
     *
     * Nothing is ignored when there's an empty ignorelist, e.g. []
     * If no ignorelist is set, we default to ignoring .ph-no-deadclick and .ph-no-capture
     * A custom ignorelist fully replaces the default — include .ph-no-capture if you want it to suppress dead-click capture as well
     */
    css_selector_ignorelist?: string[]

    /**
     * Allows setting behavior for when a dead click is captured.
     * For e.g. to support capture to heatmaps
     *
     * If not provided the default behavior is to auto-capture dead click events
     *
     * Only intended to be provided by our own SDK
     */
    __onCapture?: ((click: DeadClickCandidate, properties: Properties) => void) | undefined
} & Pick<AutocaptureConfig, 'element_attribute_ignorelist'>

export interface HeatmapConfig {
    /**
     * How often to send batched data in `$heatmap_data` events
     * If set to 0 or not set, sends using the default interval of 1 second
     *
     * @default 1000
     */
    flush_interval_milliseconds: number
}

/**
 * Configuration defaults snapshot used by `PostHogConfig.defaults`.
 * Later dates include all earlier default changes.
 */
export type ConfigDefaults =
    | '2026-08-30'
    | '2026-08-29'
    | '2026-06-25'
    | '2026-05-30'
    | '2026-01-30'
    | '2025-11-30'
    | '2025-05-24'
    | 'unset'

export type ExternalIntegrationKind = 'intercom' | 'crispChat'

/**
 * Shared configuration for the error tracking burst-protection rate limiter.
 *
 * Burst protection is scoped **per exception type** — the limiter is keyed by exception type, so
 * each distinct `$exception` type gets its own token bucket and there is no aggregate cap across
 * all types. It applies only to autocaptured exceptions; manual `captureException` calls are
 * never rate limited. These options let customers with high-cardinality exception types tune the
 * per-type allowance, and are shared between the browser and Node SDKs.
 */
export interface ExceptionRateLimiterConfig {
    /**
     * ADVANCED: alters the refill rate for the error tracking rate limiter's token bucket.
     * Normally only altered alongside PostHog support guidance.
     * Accepts values between 0 and 100.
     *
     * @default 1
     */
    exceptionRateLimiterRefillRate?: number

    /**
     * ADVANCED: alters the bucket size for the error tracking rate limiter's token bucket.
     * Normally only altered alongside PostHog support guidance.
     * Accepts values between 0 and 100.
     *
     * @default 10
     */
    exceptionRateLimiterBucketSize?: number
}

export interface ErrorTrackingOptions extends ExceptionRateLimiterConfig {
    /**
     * Decide whether exceptions thrown by browser extensions or by scripts injected by the
     * browser itself (for example Firefox for iOS and Chrome for iOS user scripts) should be
     * captured. When false, both categories are dropped before capture.
     *
     * @default false
     */
    captureExtensionExceptions?: boolean

    /**
     * UNSTABLE: determines whether exception caused by the PostHog SDK will be captured
     *
     * @default false
     */
    __capturePostHogExceptions?: boolean

    /**
     * @deprecated Use {@link ExceptionRateLimiterConfig.exceptionRateLimiterRefillRate} instead.
     * Still honoured as a fallback, but will be removed in a future major version.
     */
    __exceptionRateLimiterRefillRate?: number

    /**
     * @deprecated Use {@link ExceptionRateLimiterConfig.exceptionRateLimiterBucketSize} instead.
     * Still honoured as a fallback, but will be removed in a future major version.
     */
    __exceptionRateLimiterBucketSize?: number

    /**
     * Controls buffering and payload limits for exception steps added via `addExceptionStep`.
     */
    exception_steps?: ExceptionStepsConfig
}

/**
 * Mask input options for session recording
 */
export interface MaskInputOptions {
    color?: boolean
    date?: boolean
    'datetime-local'?: boolean
    email?: boolean
    month?: boolean
    number?: boolean
    range?: boolean
    search?: boolean
    tel?: boolean
    text?: boolean
    time?: boolean
    url?: boolean
    week?: boolean
    textarea?: boolean
    select?: boolean
    password?: boolean
}

/**
 * Slim DOM options for session recording
 */
export interface SlimDOMOptions {
    script?: boolean
    comment?: boolean
    headFavicon?: boolean
    headWhitespace?: boolean
    headMetaDescKeywords?: boolean
    headMetaSocial?: boolean
    headMetaRobots?: boolean
    headMetaHttpEquiv?: boolean
    headMetaAuthorship?: boolean
    headMetaVerification?: boolean
    headTitleMutations?: boolean
}

/**
 * Sampling options for session recording, a subset of rrweb's sampling strategy
 */
export interface SessionRecordingSamplingConfig {
    /**
     * Controls capture of mouse movement within a recorded session.
     * `false` disables capture entirely; NB this also disables touchmove and drag capture.
     * A number throttles capture so that positions are captured at most once every N milliseconds.
     * When `undefined` (or `true`), rrweb's default applies: capture throttled to every 50ms.
     * @default undefined
     */
    mousemove?: boolean | number
    /**
     * When `false`, disables capture of mouse interaction events
     * (click, mouse up/down, hover, and touch start/end).
     * NB replays will not show clicks when this is disabled.
     * @default undefined
     */
    mouseInteraction?: boolean
}

export interface SessionRecordingOptions {
    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default 'ph-no-capture'
     */
    blockClass?: string | RegExp

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default null
     */
    blockSelector?: string | null

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default 'ph-ignore-input'
     */
    ignoreClass?: string | RegExp

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default 'ph-mask'
     */
    maskTextClass?: string | RegExp

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     */
    maskTextSelector?: string | null

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     */
    maskTextFn?: ((text: string, element?: HTMLElement) => string) | null

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     */
    maskAllInputs?: boolean

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     */
    maskInputOptions?: Partial<MaskInputOptions>

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     */
    maskInputFn?: ((text: string, element?: HTMLElement) => string) | null

    /**
     * Derived from `rrweb.record` options. Masks every string-valued source DOM attribute,
     * including rendering attributes such as `class`, `id`, `style`, `src`, `href`, and
     * synthesized form values. Only rrweb-generated layout metadata is retained, so this
     * option intentionally reduces replay fidelity. Mutually exclusive with
     * `maskAttributeFn`: when both are set this option wins and the callback is ignored.
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default false
     */
    maskAllElementAttributes?: boolean

    /**
     * Derived from `rrweb.record` options. Called with `(name, value, element)` for every
     * non-empty string-valued attribute in the final serialized representation so you can mask
     * specific attributes. Returning the original value leaves it visible. Mutually exclusive
     * with `maskAllElementAttributes`: when both are set that option wins and this callback
     * is ignored, so a callback cannot accidentally unmask what the coarse option hides.
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     */
    maskAttributeFn?: ((name: string, value: string, element?: Element) => string) | null

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default {}
     */
    slimDOMOptions?: true | Partial<SlimDOMOptions> | 'all'

    /**
     * Captures sanitized Schema.org JSON-LD as session replay custom events.
     * JSON-LD inside a text mask or blocked element is never captured.
     * The recorder keeps `@id` values without changes.
     * The event tag is `$json_ld`. The payload is a JSON-LD object or array.
     * The recorder removes all script nodes from snapshots when this option is enabled.
     * The JSON-LD observer starts only when this option is true at recording start.
     * @see https://github.com/PostHog/posthog-js/blob/main/packages/browser/src/extensions/replay/external/json-ld.ts
     * @default false before the `2026-08-30` defaults, otherwise true
     */
    captureJsonLd?: boolean

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default false
     */
    collectFonts?: boolean

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default true
     */
    inlineStylesheet?: boolean

    /**
     * Max CSSRules inlined synchronously per full snapshot. Sheets past the
     * budget keep their `rel`/`href` and are inlined across idle callbacks
     * instead of blocking the snapshot; the queue is flushed synchronously
     * (bounded) when recording stops and on `pagehide`. The residual risk:
     * replay falls back to loading a sheet from its original href (which may
     * be purged, auth-gated, or renamed by replay time) only if the tab dies
     * without `pagehide` firing, the teardown flush hits its safety cap, or
     * stringifying the sheet fails.
     * The default is applied by posthog-js when it starts the recorder; the
     * recorder itself is unbounded without it.
     * Set 0 to inline everything up front (the pre-budget behaviour).
     * @default 10000
     */
    inlineStylesheetBudgetRules?: number

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default false
     */
    recordCrossOriginIframes?: boolean

    /**
     * ADVANCED: limit which DOM attributes are observed for mutations, by passing
     * the list to the native `MutationObserver` `attributeFilter`. Mutations to
     * unlisted attributes never reach the recorder at all, so they cost no
     * recording CPU - useful to exclude high-frequency inline `style` mutations
     * from JS-driven animations on animation-heavy pages.
     *
     * Attributes left off the list are invisible to replay, so only set this when
     * that loss of fidelity is acceptable. When unset (the default) or set to an
     * empty array, all attributes are observed.
     *
     * Normally only altered alongside posthog support guidance.
     */
    attributeFilter?: string[]

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default false
     */
    recordHeaders?: boolean

    /**
     * Derived from `rrweb.record` options
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default false
     */
    recordBody?: boolean

    /**
     * When recording network bodies, read them through a streaming reader that stops at the
     * payload size limit instead of buffering the whole body and then discarding it. Bounds the
     * memory and pre-request latency of capturing a very large body. Reads only a clone of the
     * body, never the stream the page consumes.
     * @default false
     */
    streamNetworkBody?: boolean

    /**
     * Allows local config to override remote canvas recording settings from the flags response.
     * To mask content inside a recorded canvas, see `canvasCapture.maskRegionsFn`.
     */
    captureCanvas?: SessionRecordingCanvasOptions

    /**
     * Tune how canvas frames are captured for replay. Only has any effect when canvas recording
     * is enabled.
     *
     * - `resolutionScale`: capture canvas frames at a fraction of their display resolution. A
     *   number in `(0, 1]`; `1` is full-resolution capture (the default) and, e.g., `0.6` captures
     *   at 60%. Out-of-range or non-finite values are clamped into `(0, 1]`. Aspect ratio is
     *   preserved and replay upscales the frame back to the original display size, so playback
     *   dimensions are unchanged, just softer. Resolution is the highest-leverage lever for canvas
     *   byte size, since bytes scale with pixel area.
     * - `maskRegionsFn`: mask regions of a recorded canvas — see its doc comment.
     */
    canvasCapture?: {
        resolutionScale?: number

        /**
         * If set, called once per canvas per captured frame; the returned regions
         * (CSS pixels, relative to the canvas element) are painted black before the
         * frame is encoded. Lets apps that render into canvas (e.g. Flutter web)
         * mask content that DOM-based masking cannot see. Re-read from config on
         * every frame, so the real provider can be swapped in after recording has
         * started.
         *
         * Return `[]` for a frame with nothing to mask (recorded as is), or `null`
         * if regions could not be computed — that frame is skipped rather than
         * recorded unmasked. Anything other than an array — `null`, a thrown error,
         * or an implicit `undefined` from an untyped caller — skips that frame.
         * Not setting this at all records the canvas unmasked.
         *
         * The provider is called for every canvas on the page, including
         * canvases inside shadow DOM. For a canvas it does not manage, return
         * `[]` ("nothing to mask") — returning `null` skips that canvas's
         * frames entirely.
         *
         * Called synchronously on the main thread for every captured frame (canvas
         * FPS is 4 by default, 12 max), so keep it cheap — avoid forcing layout,
         * and return few regions.
         *
         * Setting this also changes DOM full snapshots (taken at recording start and
         * at each `full_snapshot_interval_millis`): they normally serialize canvas
         * pixels on a separate path (`rr_dataURL`) that never sees these regions, so
         * when this option is set that serialization is skipped entirely. Whether
         * to skip is re-evaluated at each snapshot, so a provider installed via
         * `set_config` after recording started is honored at the next snapshot
         * without a recorder restart. A canvas appears blank in a snapshot until
         * the next canvas frame paints it — ~250ms at the default 4 fps while its
         * pixels are changing, and at most 30s otherwise, because every canvas
         * the provider answers (with regions or `[]`) re-sends an unchanged frame
         * as a keyframe every 30s; a canvas whose frames are skipped (`null`)
         * stays blank. Without this option, snapshot behavior is unchanged.
         *
         * An app whose real provider only exists once its runtime has booted picks
         * what happens in between by what it declares in `posthog.init`: a function
         * covering the whole canvas blacks those frames out, `() => null` skips
         * them, and declaring nothing records them.
         *
         * Client-side only, cannot be set via remote configuration.
         *
         * @default undefined
         */
        maskRegionsFn?: ((canvas: HTMLCanvasElement) => CanvasMaskRegion[] | null | undefined) | null
    }

    /**
     * Modify the network request before it is captured. Returning null or undefined stops it being captured.
     *
     * Initial navigation and performance-timing entries are also passed to this function. They have
     * `isInitial === true`, can have `method === undefined`, and contain the page URL in `name`. If the
     * function returns null or undefined for an initial entry, PostHog retains the replay-required timing
     * metadata but omits its URL, headers, and body. Return a modified entry to retain a redacted URL.
     */
    maskCapturedNetworkRequestFn?: ((data: CapturedNetworkRequest) => CapturedNetworkRequest | null | undefined) | null

    /** @deprecated - use maskCapturedNetworkRequestFn instead  */
    maskNetworkRequestFn?: ((data: NetworkRequest) => NetworkRequest | null | undefined) | null

    /**
     * ADVANCED: while a user is active we take a full snapshot of the browser every interval.
     * For very few sites playback performance might be better with different interval.
     * Set to 0 to disable
     *
     * @default 1000 * 60 * 5 (5 minutes)
     */
    full_snapshot_interval_millis?: number

    /**
     * ADVANCED: controls how much recent replay data is kept in memory while session recording waits for a
     * conditional trigger. The recorder periodically takes a full snapshot and discards older buffered events,
     * so increasing this interval retains more pre-trigger history but can increase memory usage and
     * CPU usage. Performance impacts on your site can start to be visible to users with larger values.
     * Values must be between 1,000 ms and 3,600,000 ms (1 hour, inclusive); values outside this range,
     * or non-finite values, are ignored.
     *
     * @default 1000 * 60 (1 minute)
     */
    trigger_pending_buffer_interval_millis?: number

    /**
     * ADVANCED: whether to partially compress rrweb events before sending them to the server,
     * defaults to true, can be set to false to disable partial compression
     * NB requests are still compressed when sent to the server regardless of this setting
     *
     * @default true
     */
    compress_events?: boolean

    /**
     * ADVANCED: Controls when session recording considers the user idle.
     *
     * If no replay user interaction occurs for this many milliseconds, the recorder marks the recording idle,
     * emits a `sessionIdle` replay marker, flushes buffered replay events, and drops most subsequent replay
     * events until user activity resumes. If activity resumes before `session_idle_timeout_seconds`, recording
     * continues under the same `$session_id`.
     *
     * This does not control `$session_id` rotation. Session rotation is controlled by `session_idle_timeout_seconds`,
     * so this value should be lower than `session_idle_timeout_seconds * 1000`.
     *
     * @default 1000 * 60 * 5 (5 minutes)
     */
    session_idle_threshold_ms?: number

    /**
     * ADVANCED: alters the refill rate for the token bucket mutation throttling
     * Normally only altered alongside posthog support guidance.
     * Accepts values between 0 and 100
     *
     * @default 10
     */
    __mutationThrottlerRefillRate?: number

    /**
     * ADVANCED: alters the bucket size for the token bucket mutation throttling
     * Normally only altered alongside posthog support guidance.
     * Accepts values between 0 and 100
     *
     * @default 100
     */
    __mutationThrottlerBucketSize?: number

    /**
     * ADVANCED: the sustained mutation byte budget, in bytes per second.
     * Mutation events beyond the budget are dropped and the recording resyncs with a full snapshot.
     * Only takes effect when `__mutationBytesBucketSize` is set.
     * Normally only altered alongside posthog support guidance.
     *
     * @default 25600
     */
    __mutationBytesRefillRate?: number

    /**
     * ADVANCED: enables the mutation byte budget by setting its burst allowance, in bytes.
     * Also the largest single mutation event that will be recorded.
     * Unset (the default), the byte budget is off. 1048576 (1MB) is a sensible starting point.
     * Normally only altered alongside posthog support guidance.
     *
     * @default undefined
     */
    __mutationBytesBucketSize?: number

    /**
     * When true, minimum duration is checked against the actual buffer data (first to last timestamp)
     * rather than session duration. This ensures recordings are not sent until they contain the minimum
     * duration of actual data, even across page navigations.
     *
     * @default false
     */
    strictMinimumDuration?: boolean

    /**
     * Derived from `rrweb.record` options. Controls how often certain event types are captured
     * within an already-recorded session, e.g. `{ mousemove: false }` stops recording mouse movement.
     *
     * Not to be confused with `sampleRate` below, which controls whether a session is recorded
     * at all, or with `posthog.startSessionRecording({ sampling: true })`, which overrides that
     * session-level sample rate.
     *
     * NB disabled event types no longer count as user activity for replay idle detection
     * (`session_idle_threshold_ms`). For example, with `mousemove: false` pure mouse movement
     * no longer keeps a session active, while clicks, scrolls, and inputs still do.
     *
     * @see https://github.com/rrweb-io/rrweb/blob/master/guide.md
     * @default undefined
     */
    sampling?: SessionRecordingSamplingConfig

    /**
     * The sample rate for session recordings, a number between 0 and 1.
     * For example, 0.5 means roughly 50% of sessions will be recorded.
     *
     * When `undefined`, falls back to the remote config setting.
     * When set, takes precedence over the remote config.
     *
     * @default undefined
     */
    sampleRate?: number
}

// we used to call a request that was sent to the queue with options attached `RequestQueueOptions`
// so we can't call the options used to configure the behavior of the RequestQueue that as well,
// so instead we call them config
export interface RequestQueueConfig {
    /**
     *  ADVANCED - alters the frequency which PostHog sends events to the server.
     *  generally speaking this is only set when apps have automatic page refreshes, or very short visits.
     *  Defaults to 3 seconds when not set
     *  Allowed values between 250 and 5000
     * */
    flush_interval_ms?: number
}

/**
 * Survey configuration options
 */
export interface SurveyConfig {
    prefillFromUrl?: boolean
    autoSubmitIfComplete?: boolean
    autoSubmitDelay?: number
}

/**
 * Options for the captureLog API and posthog.logger convenience methods.
 */
export interface LogCaptureOptions {
    /**
     * The service name for log records.
     * Maps to the OTel resource attribute 'service.name'.
     *
     * @default 'unknown_service'
     */
    serviceName?: string
    /**
     * The deployment environment for log records (e.g. 'production', 'staging').
     * Maps to the OTel resource attribute 'deployment.environment'.
     */
    environment?: string
    /**
     * The service version for log records (e.g. '1.2.3').
     * Maps to the OTel resource attribute 'service.version'.
     */
    serviceVersion?: string
    /**
     * Additional resource attributes applied to all log records.
     * These describe the service/deployment, not individual log entries.
     * Named fields (serviceName, environment, serviceVersion) are set first;
     * resourceAttributes can override them.
     *
     * @example { 'host.name': 'web-01', 'cloud.region': 'us-east-1' }
     */
    resourceAttributes?: LogAttributes
    /**
     * Flush interval in milliseconds for batched log records.
     *
     * @default 3000
     */
    flushIntervalMs?: number
    /**
     * Maximum number of log records to buffer before forcing a flush. The queue
     * may grow beyond this while a flush is in flight (e.g. during a synchronous
     * burst) and is bounded separately by the per-interval rate cap.
     *
     * @default 100
     */
    maxBufferSize?: number
    /**
     * Maximum number of log records accepted per flush interval. Subsequent calls
     * within the same window are dropped with a single warning, protecting
     * against runaway loggers flooding the network. Also sizes the in-memory
     * buffer's eviction backstop, so a window's worth of records is held while a
     * flush is in flight; raising it raises the worst-case in-memory footprint.
     *
     * @default 1000
     */
    maxLogsPerInterval?: number
    /**
     * Pre-send filter for log records, as a single function or a left-to-right
     * chain. Each function inspects, mutates, or drops a record (return `null`
     * to drop) before it enters the rate cap or the buffer.
     */
    beforeSend?: BeforeSendLogFn | BeforeSendLogFn[]
}

/**
 * Logs configuration options
 */
export interface LogsConfig extends LogCaptureOptions {
    /**
     * Automatically capture `console.*` calls as structured log records.
     * Review console output before enabling, as messages can include sensitive values
     * written by your code or by third-party libraries.
     *
     * @default undefined
     */
    captureConsoleLogs?: boolean
}

/**
 * Options for the posthog.metrics API (count, gauge, histogram).
 */
export interface MetricsConfig {
    /**
     * The service name for metric series.
     * Maps to the OTel resource attribute 'service.name'.
     *
     * @default 'unknown_service'
     */
    serviceName?: string
    /**
     * The deployment environment for metric series (e.g. 'production', 'staging').
     * Maps to the OTel resource attribute 'deployment.environment'.
     */
    environment?: string
    /**
     * The service version for metric series (e.g. '1.2.3').
     * Maps to the OTel resource attribute 'service.version'.
     */
    serviceVersion?: string
    /**
     * Additional resource attributes applied to every metrics batch.
     * These describe the service/deployment, not individual series.
     * Named fields (serviceName, environment, serviceVersion) are set first;
     * resourceAttributes can override them.
     *
     * @example { 'host.name': 'web-01', 'cloud.region': 'us-east-1' }
     */
    resourceAttributes?: MetricAttributes
    /**
     * How often the aggregated window is flushed, in milliseconds. Samples
     * are folded into per-series aggregates in memory between flushes — one
     * data point per series per window, no matter how many calls.
     *
     * @default 10000
     */
    flushIntervalMs?: number
    /**
     * Cardinality guardrail: maximum distinct series (name + type + unit +
     * attribute combination) held per flush window. Samples for series
     * beyond the cap are dropped with a single warning per window.
     *
     * @default 1000
     */
    maxSeriesPerFlush?: number
    /**
     * Pre-aggregation filter for metric samples, as a single function or a
     * left-to-right chain. Each function inspects, mutates, or drops a
     * sample (return `null` to drop) before it is aggregated.
     */
    beforeSend?: BeforeSendMetricFn | BeforeSendMetricFn[]
}

// See https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options
type NextOptions = { revalidate: false | 0 | number; tags: string[] }

/**
 * Selects which same-page URL changes automatically capture a `$pageview`.
 * Each option defaults to `false` when omitted.
 */
export interface CapturePageviewOptions {
    /** Capture a pageview when `location.pathname` changes. */
    path?: boolean
    /** Capture a pageview when `location.search` changes. */
    search?: boolean
    /** Capture a pageview when `location.hash` changes, unless `disable_capture_url_hashes` is enabled. */
    hash?: boolean
}

/**
 * Configuration options for the PostHog JavaScript SDK.
 * @see https://posthog.com/docs/libraries/js#config
 */
export interface PostHogConfig {
    /** URL of your PostHog instance.
     *
     * @default 'https://us.i.posthog.com'
     */
    api_host: string

    /**
     * URL to use for feature flag requests specifically.
     * If not set, feature flag requests will use the URL derived from `api_host`.
     * This is useful when you want to route feature flag requests to a different endpoint than other analytic APIs.
     *
     * @default null
     */
    flags_api_host?: string | null

    /**
     * Rewrites the URL used for PostHog API, feature flag, and asset requests.
     * This is intended for customers who use a reverse proxy and need custom paths.
     * The proxy must map the rewritten paths back to the canonical PostHog paths.
     *
     * UI links are not rewritten.
     *
     * @example
     * ```js
     * posthog.init('phc_...', {
     *     api_host: 'https://a.example.com',
     *     rewriteRequestPath: (url) => {
     *         if (url.pathname === '/e/') {
     *             url.pathname = '/my-events/'
     *         } else if (url.pathname === '/s/') {
     *             url.pathname = '/my-replay/'
     *         } else if (url.pathname === '/flags/') {
     *             url.pathname = '/my-flags/'
     *         }
     *         return url
     *     },
     * })
     * ```
     *
     * @param url - The fully resolved request URL. It may be mutated or replaced.
     * @returns The URL that the SDK should request.
     */
    rewriteRequestPath?: (url: URL) => URL

    /**
     * If using a reverse proxy for `api_host` then this should be the actual PostHog app URL (e.g. https://us.posthog.com).
     * This ensures that links to PostHog point to the correct host.
     *
     * @default null
     */
    ui_host: string | null

    /**
     * The transport method to use for API requests.
     *
     * @default 'fetch'
     */
    api_transport?: 'XHR' | 'fetch'

    /**
     * The token for your PostHog project.
     * It should NOT be provided manually in the config, but rather passed as the first parameter to `posthog.init()`.
     */
    token: string

    /**
     * The name this instance will be identified by.
     * You don't need to set this most of the time,
     * but can be useful if you have several Posthog instances running at the same time.
     *
     * @default 'posthog'
     */
    name: string

    /**
     * Determines whether PostHog should autocapture events.
     * This setting does not affect capturing pageview events (see `capture_pageview`).
     *
     * by default autocapture is ignored on elements that match a `ph-no-capture` css class on the element or a parent
     * @default true
     */
    autocapture: boolean | AutocaptureConfig

    /**
     * Determines whether PostHog should capture rage clicks.
     *
     * By default, rage clicks are ignored on elements that match a `ph-no-capture` or `ph-no-rageclick` CSS class on the element or a parent.
     * When `defaults` is `'2025-11-30'` or later, the default is `{ content_ignorelist: true }`.
     * When `defaults` is `'2026-05-30'` or later, the default also excludes stepper controls (`+`, `-`, `−`, `–`) and text-selection surfaces.
     *
     * @default true
     */
    rageclick: boolean | RageclickConfig

    /**
     * Determines if cookie should be set on the top level domain (example.com).
     * If PostHog-js is loaded on a subdomain (test.example.com), and `cross_subdomain_cookie` is set to false,
     * it'll set the cookie on the subdomain only (test.example.com).
     *
     * NOTE: It will be set to `false` if we detect that the domain is a subdomain of a platform that is excluded from cross-subdomain cookie setting.
     * The current list of excluded platforms is `herokuapp.com`, `vercel.app`, and `netlify.app`.
     *
     * @see `isCrossDomainCookie`
     * @default true
     */
    cross_subdomain_cookie: boolean

    /**
     * Determines how PostHog stores information about the user. See [persistence](https://posthog.com/docs/libraries/js#persistence) for details.
     *
     * @default 'localStorage+cookie'
     */
    persistence: 'localStorage' | 'cookie' | 'memory' | 'localStorage+cookie' | 'sessionStorage'

    /**
     * The name for the super properties persistent store
     *
     * @default ''
     */
    persistence_name: string

    /** @deprecated - Use 'persistence_name' instead */
    cookie_name?: string

    /**
     * List of custom property names that should be stored in cookies (in addition to the default ones)
     * when using 'localStorage+cookie' persistence mode. This allows these properties to be shared
     * across subdomains when cross_subdomain_cookie is enabled.
     *
     * @default []
     */
    cookie_persisted_properties?: readonly string[]

    /**
     * A function to be called once the PostHog scripts have loaded successfully.
     *
     * @param posthog_instance - The PostHog instance that has been loaded.
     */
    loaded: (posthog_instance: PostHog) => void

    /**
     * Determines whether PostHog should strip URL fragments (`#...`) from automatically captured URL fields.
     * Disabled by default for backwards compatibility, and enabled automatically when `config.defaults` is
     * `'2026-06-25'` or later. Set to `true` to strip hashes from:
     *
     * - `$current_url` on automatically captured browser events, including `$pageview`
     * - `$initial_current_url`
     * - `$session_entry_url`
     * - `$elements[*].attr__href` and `$external_click_url` for autocapture and dead-click autocapture
     * - Next.js Pages Router `$pageview` `$current_url`
     * - web vitals `$current_url`
     * - logs `url.full`
     * - conversations `current_url` and `request_url`
     * - session replay rrweb meta/custom-event `href` URLs
     * - heatmap data URLs
     *
     * If your SPA relies on hash-based routes for analytics, enabling this is a breaking behavior change.
     * If you want to capture hashes selectively, leave this disabled and use `before_send` to remove
     * sensitive hash values before events are sent.
     *
     * @default false when `config.defaults` is unset or earlier than `'2026-06-25'`, otherwise `true`
     */
    disable_capture_url_hashes: boolean

    /**
     * Determines whether PostHog should save referrer information.
     *
     * @default true
     */
    save_referrer: boolean

    /**
     * Determines whether PostHog should save marketing parameters.
     * These are `utm_*` paramaters and friends.
     *
     * @see {CAMPAIGN_PARAMS} from './utils/event-utils' - Default campaign parameters like utm_source, utm_medium, etc.
     * @default true
     */
    save_campaign_params: boolean

    /** @deprecated - Use `save_campaign_params` instead */
    store_google?: boolean

    /**
     * Used to extend the list of campaign parameters that are saved by default.
     *
     * @see {CAMPAIGN_PARAMS} from './utils/event-utils' - Default campaign parameters like utm_source, utm_medium, etc.
     * @default []
     */
    custom_campaign_params: string[]

    /**
     * Used to extend the list of user agents that are blocked by default.
     *
     * @see {DEFAULT_BLOCKED_UA_STRS} from './utils/blocked-uas' - Default list of blocked user agents.
     * @default []
     */
    custom_blocked_useragents: string[]

    /**
     * Determines whether PostHog should be in debug mode.
     * You can enable this to get more detailed logging.
     *
     * You can also enable this on your website by appending `?__posthog_debug=true` at the end of your URL
     * You can also call `posthog.debug()` in your code to enable debug mode
     *
     * @default false
     */
    debug: boolean

    /** @deprecated Use `debug` instead */
    verbose?: boolean

    /**
     * Determines whether PostHog should capture pageview events automatically.
     * Can be:
     * - `true`: Capture the initial pageview
     * - `false`: Don't capture any pageviews
     * - `'history_change'`: Capture the initial pageview and pageviews when the path, query string, or hash changes.
     *   `disable_capture_url_hashes` still suppresses hash-only changes.
     * - An object: Capture the initial pageview and pageviews when any selected URL component changes
     *
     * @default true (or `'history_change'` when `defaults` is `'2025-05-24'` or later)
     */
    capture_pageview: boolean | 'history_change' | CapturePageviewOptions

    /**
     * Determines whether PostHog should capture pageleave events.
     * If set to `true`, it will capture pageleave events for all pages.
     * If set to `'if_capture_pageview'`, it will only capture pageleave events if `capture_pageview` is enabled.
     *
     * @default 'if_capture_pageview'
     */
    capture_pageleave: boolean | 'if_capture_pageview'

    /**
     * Determines the number of days to store cookies for.
     *
     * @default 365
     */
    cookie_expiration: number

    /**
     * Determines whether PostHog should upgrade old cookies.
     * If set to `true`, the library will check for a cookie from our old js library and import super properties from it, then the old cookie is deleted.
     * This option only works in the initialization, so make sure you set it when you create the library.
     *
     * @default false
     */
    upgrade: boolean

    /**
     * Determines whether PostHog should disable session recording.
     *
     * @default false
     */
    disable_session_recording: boolean

    /**
     * Determines whether PostHog should disable persistence.
     * If set to `true`, the library will not save any data to the browser. It will also delete any data previously saved to the browser.
     *
     * @default false
     */
    disable_persistence: boolean

    /** @deprecated - use `disable_persistence` instead */
    disable_cookie?: boolean

    /**
     * Coalesce rapid `Persistence.save()` calls into a single write.
     *
     * Set to a positive number (milliseconds) to debounce writes to localStorage / cookie
     * by that window. The in-memory `props` object is always updated synchronously so
     * within-tab reads see the latest values immediately. Cross-tab `storage` events
     * (which carry the full persistence value as a payload) are reduced proportionally
     * to the debounce window.
     *
     * Pending writes are flushed on `beforeunload` and `pagehide` so no state is lost
     * on tab close. The cross-tab visibility delay is bounded by the configured window.
     *
     * Defaults to `0` (no debouncing, write synchronously) for backwards compatibility.
     * On pages that capture many events per second, `250` is a reasonable starting point
     * to reduce localStorage write pressure and cross-tab IPC traffic. The `2026-05-30`
     * config default opts into `250` automatically.
     *
     * @default 0
     */
    persistence_save_debounce_ms?: number

    /**
     * Store the feature-flag config cluster and survey config in their own
     * localStorage entries (`<name>__flags`, `<name>__surveys`) instead of the
     * single main persistence blob. These payloads are large and change rarely,
     * so keeping them out of the main blob stops them riding on every
     * high-frequency main-blob write and broadcasting cross-tab `storage` events.
     *
     * Only applies when persistence resolves to `localStorage` / `localStorage+cookie`
     * (the split is pointless for `memory` / `sessionStorage` and impossible for `cookie`).
     * On load the old main-blob location is read once and migrated forward, so
     * upgrades never miss a cached flag. The `2026-05-30` config default opts in.
     *
     * @default false
     */
    split_storage?: boolean

    /**
     * Detect the Google Search App (GSA) as its own `$browser` value instead of
     * the underlying webview it embeds — Mobile Safari on iOS, Chrome on Android.
     * Detection keys off the `GSA/` marker present in the UA on every platform.
     *
     * Off by default for backwards-compatibility: enabling it reattributes
     * existing GSA traffic away from Mobile Safari / Chrome, which would
     * otherwise look like those browsers suddenly losing share. The `2026-05-30`
     * config default opts in.
     *
     * @default false
     */
    detect_google_search_app?: boolean

    /**
     * Determines whether PostHog should disable all surveys functionality.
     *
     * @default false
     */
    disable_surveys: boolean

    /**
     * Determines whether PostHog should disable automatic display of surveys. If this is true, popup or widget surveys will not be shown when display conditions are met.
     *
     * @default false
     */
    disable_surveys_automatic_display: boolean

    /**
     * Determines whether PostHog should disable all product tours functionality.
     *
     * @default false
     */
    disable_product_tours: boolean

    /**
     * Survey-specific configuration options.
     *
     * @default undefined
     */
    surveys?: SurveyConfig

    /**
     * Logs-specific configuration options.
     *
     * @default undefined
     */
    logs?: LogsConfig

    /**
     * Metrics-specific configuration options for the posthog.metrics API.
     *
     * @default undefined
     */
    metrics?: MetricsConfig

    /**
     * Determines whether PostHog should disable all conversations functionality.
     *
     * @default false
     */
    disable_conversations: boolean

    /**
     * Verified distinct_id for HMAC-based identity verification.
     * When both `identity_distinct_id` and `identity_hash` are provided,
     * products like conversations use server-verified identity instead of
     * anonymous session identifiers.
     *
     * Can be set at init time or later via `posthog.setIdentity()`.
     *
     * @example
     * ```js
     * posthog.init('phc_...', {
     *     identity_distinct_id: 'user_123',
     *     identity_hash: 'a1b2c3d4e5f6...',
     * })
     * ```
     */
    identity_distinct_id?: string

    /**
     * HMAC-SHA256 of `identity_distinct_id` using the project's API secret.
     * Must be provided together with `identity_distinct_id`.
     */
    identity_hash?: string

    /**
     * Determines whether PostHog should disable web experiments.
     *
     * Currently disabled while we're in BETA. It will be toggled to `true` in a future release.
     *
     * @default true
     */
    disable_web_experiments: boolean

    /**
     * Determines whether PostHog should disable any external dependency loading.
     * This will prevent PostHog from requesting any external scripts such as those needed for Session Replay, Surveys or Site Apps.
     *
     * @default false
     */
    disable_external_dependency_loading: boolean

    /**
     * Determines whether PostHog should load external dependency scripts from
     * semver-qualified asset paths such as /static/1.370.0/recorder.js instead
     * of the legacy /static/recorder.js?v=1.370.0 form. Set to `true` to use only
     * versioned paths, `false` to use only legacy paths, or `'fallback'` to try
     * the versioned path first and retry with the legacy path if it fails.
     *
     * @default 'fallback'
     */
    strict_script_versioning: boolean | 'fallback'

    /**
     * Optional host override for static assets loaded by PostHog, such as
     * recorder.js, surveys.js, or toolbar.js. Only applies to /static/* asset
     * paths; dynamic assets like remote config continue to use the regular
     * asset host derived from api_host.
     *
     * @default null
     */
    asset_host: string | null

    /**
     * A function to be called when a script is being loaded.
     * This can be used to modify the script before it is loaded.
     * This is useful for adding a nonce to the script, for example.
     *
     * @param script - The script element that is being loaded.
     * @returns The modified script element, or null if the script should not be loaded.
     */
    prepare_external_dependency_script?: (script: HTMLScriptElement) => HTMLScriptElement | null

    /**
     * A function to be called when a stylesheet is being loaded.
     * This can be used to modify the stylesheet before it is loaded.
     * This is useful for adding a nonce to the stylesheet, for example.
     *
     * @param stylesheet - The stylesheet element that is being loaded.
     * @returns The modified stylesheet element, or null if the stylesheet should not be loaded.
     */
    prepare_external_dependency_stylesheet?: (stylesheet: HTMLStyleElement) => HTMLStyleElement | null

    /**
     * Where to inject external dependency scripts (recorder, surveys, etc.) in the DOM.
     * - 'body': Injects scripts into document.body (legacy behavior)
     * - 'head': Injects scripts into document.head (avoids SSR hydration errors)
     *
     * @default 'body' (or 'head' when defaults >= '2026-01-30')
     */
    external_scripts_inject_target?: 'body' | 'head'

    /**
     * Determines whether PostHog should enable recording console logs.
     *
     * This is related to the Session Recording feature. For more session recording
     * settings, see the `session_recording` and `capture_performance` configuration option.
     * When undefined, it falls back to the remote config setting.
     *
     * @default undefined
     */
    enable_recording_console_log?: boolean

    /**
     * Determines whether PostHog should use secure cookies.
     * If this is `true`, PostHog cookies will be marked as secure,
     * meaning they will only be transmitted over HTTPS.
     *
     * @default window.location.protocol === 'https:'
     */
    secure_cookie: boolean

    /**
     * Determines if users should be opted out of PostHog tracking by default,
     * requiring additional logic to opt them into capturing by calling `posthog.opt_in_capturing()`.
     *
     * @default false
     */
    opt_out_capturing_by_default: boolean

    /**
     * Determines where we'll save the information about whether users are opted out of capturing.
     *
     * @default 'localStorage'
     */
    opt_out_capturing_persistence_type: 'localStorage' | 'cookie'

    /**
     * Determines if users should be opted out of browser data storage by this PostHog instance by default,
     * requiring additional logic to opt them into capturing by calling `posthog.opt_in_capturing()`.
     *
     * @default false
     */
    opt_out_persistence_by_default?: boolean

    /**
     * Determines if users should be opted out of user agent filtering such as googlebot or other bots.
     * If this is set to `true`, PostHog will set `$browser_type` to either `bot` or `browser` for all events,
     * but will process all events as if they were from a browser.
     *
     * @default false
     */
    opt_out_useragent_filter: boolean

    /** @deprecated Use `consent_persistence_name` instead. This will be removed in a future major version. */
    opt_out_capturing_cookie_prefix: string | null

    /**
     * Determines the key for the cookie / local storage used to store the information about whether users are opted in/out of capturing.
     * When `null`, we used a key based on your token.
     *
     * @default null
     * @see `ConsentManager._storageKey`
     */
    consent_persistence_name: string | null

    /**
     * Determines if users should be opted in to site apps.
     *
     * @default false
     */
    opt_in_site_apps: boolean

    /**
     * Determines whether PostHog should respect the Do Not Track header when computing
     * consent in `ConsentManager`.
     *
     * @see `ConsentManager`
     * @default false
     */
    respect_dnt: boolean

    /**
     * A list of properties that should never be sent with capture calls.
     *
     * @default []
     */
    property_denylist: string[]

    /** @deprecated - use `property_denylist` instead  */
    property_blacklist?: string[]

    /**
     * A list of headers that should be sent with requests to the PostHog API.
     *
     * @default {}
     */
    request_headers: { [header_name: string]: string }

    /** @deprecated - use `request_headers` instead  */
    xhr_headers?: { [header_name: string]: string }

    /**
     * A function that is called when a request to the PostHog API fails.
     *
     * @param error - The `RequestResponse` object that occurred.
     */
    on_request_error?: (error: RequestResponse) => void

    /** @deprecated - use `on_request_error` instead  */
    on_xhr_error?: (failedRequest: XMLHttpRequest) => void

    /**
     * Determines whether PostHog should batch requests to the PostHog API.
     *
     * @default true
     */
    request_batching: boolean

    /**
     * Determines the maximum length of the properties string that can be sent with capture calls.
     *
     * @default 65535
     */
    properties_string_max_length: number

    /**
     * Configuration defaults for breaking changes. When set to a specific date,
     * enables new default behaviors that were introduced on that date.
     *
     * - `'unset'`: Use legacy default behaviors
     * - `'2025-05-24'`: Use updated default behaviors (e.g. capture_pageview defaults to 'history_change')
     * - `'2025-11-30'`: Defaults from '2025-05-24' plus additional changes (e.g. strict minimum duration for replay and rageclick content ignore list defaults to active)
     * - `'2026-01-30'`: Defaults from '2025-11-30' plus external_scripts_inject_target defaults to 'head' (avoids SSR hydration errors)
     * - `'2026-05-30'`: Defaults from '2026-01-30' plus `persistence_save_debounce_ms` defaults to `250`, `split_storage` and `detect_google_search_app` default to `true`, and rageclick defaults also exclude stepper controls and text-selection surfaces
     * - `'2026-06-25'`: Defaults from '2026-05-30' plus `session_recording.streamNetworkBody` defaults to `true` (streams network bodies to enforce the payload size limit)
     * - `'2026-08-29'`: Defaults from '2026-06-25' plus `cookieWinsOnConflict` defaults to `true` (the shared cross-subdomain cookie wins over stale per-origin localStorage)
     * - `'2026-08-30'`: Defaults from '2026-08-29' plus `session_recording.captureJsonLd` defaults to `true`
     *
     * @default 'unset'
     */
    defaults: ConfigDefaults

    /**
     * EXPERIMENTAL: Defers initialization of non-critical extensions (autocapture, session recording, etc.)
     * to the next event loop tick using setTimeout. This reduces main thread blocking during SDK
     * initialization for better page load performance, while keeping critical functionality
     * (persistence, sessions, capture) available immediately.
     *
     * When enabled:
     * - Persistence, sessions, and basic capture work immediately
     * - Extensions (autocapture, recording, heatmaps, etc.) start after yielding back to the browser
     *
     * @default false (will be true for defaults >= '2025-11-06' in the future)
     * @experimental
     */
    __preview_deferred_init_extensions: boolean

    /**
     * In `'localStorage+cookie'` persistence mode, prefer shared cookie values over
     * per-origin localStorage when both stores carry the same key. The SDK also checks
     * for cookie changes before captures and persistence writes so already-open sibling
     * subdomains adopt identity changes made by `identify()` or `reset()`.
     *
     * When `defaults` is `'2026-08-29'` or later, this defaults to `true`.
     *
     * @default false
     */
    cookieWinsOnConflict: boolean

    /**
     * @deprecated Use `cookieWinsOnConflict` instead.
     */
    __preview_cookie_wins_on_conflict: boolean

    /**
     * Determines the session recording options.
     *
     * For more session recording settings, see the `enable_recording_console_log` and `capture_performance` configuration option.
     * When `defaults` is `'2025-11-30'` or later, `strictMinimumDuration` defaults to `true`.
     *
     * @see `SessionRecordingOptions`
     * @default {}
     */
    session_recording: SessionRecordingOptions

    /**
     * Determines the error tracking options.
     *
     * @see `ErrorTrackingOptions`
     * @default {}
     */
    error_tracking: ErrorTrackingOptions

    /**
     * Determines the session idle timeout in seconds.
     *
     * If no events are captured for this many seconds, the next event starts a
     * new session with a new `$session_id` (and `$window_id`). The SDK may also proactively reset the stored session
     * after the timeout while the page is idle, so the next event creates a new session.
     *
     * Session recording has a separate idle threshold: `session_recording.session_idle_threshold_ms`. That setting
     * only controls when the user is considered idle, it does not rotate `$session_id`.
     *
     * Must be between 60 seconds and 10 hours. Values outside this range are clamped.
     *
     * @default 30 * 60 -- 30 minutes
     */
    session_idle_timeout_seconds: number

    /**
     * Prevent autocapture from capturing any attribute names on elements.
     *
     * @default false
     */
    mask_all_element_attributes: boolean

    /**
     * Prevent autocapture from capturing `textContent` on elements.
     *
     * @default false
     */
    mask_all_text: boolean

    /**
     * Mask personal data properties from the current URL.
     * This will mask personal data properties such as advertising IDs (gclid, fbclid, etc.), and you can also add
     * custom properties to mask with `custom_personal_data_properties`.
     * @default false
     * @see {PERSONAL_DATA_CAMPAIGN_PARAMS} - Default campaign parameters that are masked by default.
     * @see {PostHogConfig.custom_personal_data_properties} - Custom list of personal data properties to mask.
     */
    mask_personal_data_properties: boolean

    /**
     * Custom list of personal data properties to mask.
     *
     * E.g. if you added `email` to this list, then any `email` property in the URL will be masked.
     * https://www.example.com/login?email=john.doe%40example.com => https://www.example.com/login?email=<MASKED>
     *
     * @default []
     * @see {PostHogConfig.mask_personal_data_properties} - Must be enabled for this to take effect.
     */
    custom_personal_data_properties: string[]

    /**
     * One of the very first things the PostHog library does when init() is called
     * is make a request to the /flags endpoint on PostHog's backend.
     * This endpoint contains information on how to run the PostHog library
     * so events are properly received in the backend, and it also contains
     * feature flag evaluation information for the current user.
     *
     * This endpoint is required to run most features of this library.
     * However, if you're not using any of the described features,
     * you may wish to turn off the call completely to avoid an extra request
     * and reduce resource usage on both the client and the server.
     *
     * WARNING: Disabling this will also prevent remote configuration from loading,
     * which could mean features like web vitals, surveys, and other features configured
     * in PostHog settings are disabled unless explicitly enabled via client-side config.
     * When setting this to true, make sure to explicitly configure any features you
     * want to use (e.g., capture_performance, autocapture, etc.) in your SDK's init config.
     *
     * @default false
     */
    advanced_disable_flags?: boolean

    /**
     * @deprecated Use `advanced_disable_flags` instead. This will be removed in a future major version.
     *
     * One of the very first things the PostHog library does when init() is called
     * is make a request to the /decide endpoint on PostHog's backend.
     * This endpoint contains information on how to run the PostHog library
     * so events are properly received in the backend.
     *
     * This endpoint is required to run most features of the library.
     * However, if you're not using any of the described features,
     * you may wish to turn off the call completely to avoid an extra request
     * and reduce resource usage on both the client and the server.
     *
     * @default false
     */
    advanced_disable_decide?: boolean

    /**
     * Will keep /flags running, but without evaluating any feature flags.
     * Useful for when you need to load the config data associated with the flags endpoint
     * (e.g. /flags?v=2&config=true) without evaluating any feature flags.  Most folks use this
     * to save money on feature flag evaluation (by bootstrapping feature flags on the server side).
     *
     * @default false
     */
    advanced_disable_feature_flags: boolean

    /**
     * Stops from firing feature flag requests on first page load.
     * Only requests feature flags when user identity or properties are updated,
     * or you manually request for flags to be loaded.
     *
     * @default false
     */
    advanced_disable_feature_flags_on_first_load: boolean

    /**
     * Evaluation contexts for feature flags.
     * When set, only feature flags that have at least one matching evaluation tag
     * will be evaluated for this SDK instance. Feature flags with no evaluation tags
     * will always be evaluated.
     *
     * Examples: ['production', 'web', 'checkout']
     *
     * @default undefined
     */
    evaluation_contexts?: readonly string[]

    /**
     * List of feature flag keys to remotely evaluate for this SDK instance.
     * When set, only these flags are evaluated by `/flags`; omitted flags are not remotely evaluated.
     * Dependencies of the requested flags may still be evaluated internally by PostHog.
     * If unset, all eligible flags are evaluated.
     *
     * Examples: ['checkout-redesign', 'new-onboarding']
     *
     * @default undefined
     */
    flag_keys?: readonly string[]

    /**
     * Evaluation environments for feature flags.
     * @deprecated Use evaluation_contexts instead. This property will be removed in a future version.
     */
    evaluation_environments?: readonly string[]

    /**
     * Determines whether PostHog should disable toolbar metrics.
     * This is our internal instrumentation for our toolbar in your website.
     *
     * @default false
     */
    advanced_disable_toolbar_metrics: boolean

    /**
     * Determines whether PostHog should only evaluate feature flags for surveys.
     * Useful for when you want to use this library to evaluate feature flags for surveys only but you have additional feature flags
     * that you evaluate on the server side.
     *
     * @default false
     */
    advanced_only_evaluate_survey_feature_flags: boolean
    /**
     * When this is enabled, surveys will always be initialized, regardless of the /flags response or remote config settings.
     * This is useful if you want to use surveys but disable all other flag-dependent functionality.
     * Used internally for displaying external surveys without making a /flags request.
     *
     * @default false
     */
    advanced_enable_surveys: boolean

    /**
     * Sets timeout for fetching feature flags
     *
     * @default 3000
     */
    feature_flag_request_timeout_ms: number

    /**
     * Sets the maximum age (in milliseconds) for cached feature flag values.
     * When the cache is older than this value:
     * - `getFeatureFlag()` will return `undefined` instead of stale cached values
     * - `$feature/` properties will not be attached to events
     * - A background refresh will be triggered automatically
     *
     * This prevents stale feature flag values from being used when the `/flags` request
     * fails (e.g., due to ad blockers or network issues).
     *
     * When not set or set to `0`, cache expiration is disabled (cached values never expire).
     *
     * @default 0
     */
    feature_flag_cache_ttl_ms?: number

    /**
     * When enabled, `$feature_flag_called` event deduplication is scoped to the current session.
     *
     * By default, the SDK deduplicates `$feature_flag_called` events globally and only re-emits
     * them when `identify` (with a new distinct ID) or `reset` is called. This can be problematic
     * for experiments: if a flag is checked before an experiment starts, the event is cached and
     * won't fire again for that user until identify/reset, meaning the experiment never sees the event.
     *
     * When this option is `true`, the deduplication cache is keyed on the session ID, so each new
     * session will re-emit `$feature_flag_called` for every flag that is checked.
     *
     * @default false
     */
    advanced_feature_flags_dedup_per_session: boolean

    /**
     * Sets timeout for fetching surveys
     *
     * @default 10000
     */
    surveys_request_timeout_ms: number

    /**
     * Controls how often feature flags are automatically refreshed in long-running sessions.
     *
     * By default, feature flags are refreshed every 5 minutes (300000ms) to pick up server-side
     * flag changes without requiring a page reload. This is useful for SPAs and long-running tabs.
     *
     * **Tradeoffs:**
     * - **Shorter intervals**: Feature flag changes propagate faster, but increases network requests and server load.
     * - **Longer intervals**: Reduces network traffic (better for mobile/battery), but flag changes take longer to propagate.
     * - **Disabled (0 or any negative value)**: No background refreshes. Flags only update on page load or manual `reloadFeatureFlags()` calls.
     *   Use this if you control flag updates manually or have infrequent flag changes.
     *
     * Hidden pages skip scheduled refreshes and reload due flags when they become visible.
     * This option does not reload remote config.
     *
     * @default 300000 (5 minutes)
     */
    remote_config_refresh_interval_ms?: number

    /**
     * Function to get the device ID.
     * This doesn't usually need to be set, but can be useful if you want to use a custom device ID.
     *
     * @param uuid - The UUID we would use for the device ID.
     * @returns The device ID.
     *
     * @default (uuid) => uuid
     */
    get_device_id: (uuid: string) => string

    /**
     * This function or array of functions - if provided - are called immediately before sending data to the server.
     * It allows you to edit data before it is sent, or choose not to send it all.
     * if provided as an array the functions are called in the order they are provided
     * any one function returning null means the event will not be sent
     */
    before_send?: BeforeSendFn | BeforeSendFn[]

    /**
     * Overrides the URL used for client-side URL targeting: session replay URL triggers, the
     * session replay URL blocklist, survey URL display conditions, product tour URL conditions,
     * web experiment URL conditions, and autocapture URL allow/ignore lists.
     *
     * These features match against `window.location.href` directly, which does not reflect
     * any `$current_url` you rewrite in `before_send`. In environments where the browser URL
     * is not meaningful for targeting — e.g. Electron/desktop apps served from a generated
     * host — return the logical URL you want these features to match against. This does not
     * change the `$current_url` property captured on events (use `before_send` for that).
     *
     * @param defaultUrl - the URL PostHog would otherwise use (`window.location.href`)
     * @returns the URL to use for client-side URL matching
     * @default undefined (uses `window.location.href`)
     */
    get_current_url?: (defaultUrl: string) => string

    /** @deprecated - use `before_send` instead */
    sanitize_properties: ((properties: Properties, event_name: string) => Properties) | null

    /** @deprecated - use `before_send` instead */
    _onCapture: (eventName: string, eventData: CaptureResult) => void

    /**
     * Determines whether to capture performance metrics.
     * These include Network Timing for Session Replay and Web Vitals.
     *
     * The `network_timing` option is only used by the Session Replay feature.
     * For more session recording settings, see the `session_recording` and `enable_recording_console_log` configuration option.
     *
     * When `undefined`, fallback to the remote configuration.
     * If `false`, neither network timing nor web vitals will work.
     * If an object, that will override the remote configuration.
     *
     * @see {PerformanceCaptureConfig}
     * @default undefined
     */
    capture_performance?: boolean | PerformanceCaptureConfig

    /**
     * Determines whether to disable compression when sending events to the server.
     * WARNING: Should only be used for testing. Could negatively impact performance.
     *
     * @default false
     */
    disable_compression: boolean

    /**
     * An object containing the `distinctID`, `isIdentifiedID`, and `featureFlags` keys,
     * where `distinctID` is a string, and `featureFlags` is an object of key-value pairs.
     *
     * Since there is a delay between initializing PostHog and fetching feature flags,
     * feature flags are not always available immediately.
     * This makes them unusable if you want to do something like redirecting a user
     * to a different page based on a feature flag.
     *
     * You can, therefore, fetch the feature flags in your server and pre-fill them here,
     * allowing PostHog to know the feature flag values immediately.
     *
     * After the SDK fetches feature flags from PostHog, it will use those flag values instead of bootstrapped ones.
     *
     * @default {}
     */
    bootstrap: BootstrapConfig

    /**
     * The segment analytics object.
     *
     * @see https://posthog.com/docs/libraries/segment
     */
    segment?: SegmentAnalytics

    /**
     * Determines whether to capture heatmaps.
     *
     * @see {HeatmapConfig}
     * @default undefined
     */
    capture_heatmaps?: boolean | HeatmapConfig

    /** @deprecated Use `capture_heatmaps` instead. */
    enable_heatmaps?: boolean

    /**
     * Determines whether to capture dead clicks.
     *
     * by default dead clicks are ignored on elements that match a `ph-no-capture` or `ph-no-deadclick` css class on the element or a parent
     *
     * @see {DeadClicksAutoCaptureConfig}
     * @default undefined
     */
    capture_dead_clicks?: boolean | DeadClicksAutoCaptureConfig

    /**
     * Determines whether to capture exceptions.
     *
     * @see {ExceptionAutoCaptureConfig}
     * @default undefined
     */
    capture_exceptions?: boolean | ExceptionAutoCaptureConfig

    /**
     * Determines whether to disable scroll properties.
     * These allow you to keep track of how far down someone scrolled in your website.
     *
     * @default false
     */
    disable_scroll_properties?: boolean

    /**
     * Let the pageview scroll stats use a custom css selector for the root element, e.g. `main`
     * It will use `window.document.documentElement` if not specified.
     */
    scroll_root_selector?: string | string[]

    /**
     * You can control whether events from PostHog-js have person processing enabled with the `person_profiles` config setting.
     * There are three options:
     * - `person_profiles: 'always'` - we will process persons data for all events
     * - `person_profiles: 'never'` - we won't process persons for any event. This means that anonymous users will not be merged once they sign up or login, so you lose the ability to create funnels that track users from anonymous to identified. All events (including `$identify`) will be sent with `$process_person_profile: False`.
     * - `person_profiles: 'identified_only'` _(default)_ - we will only process persons when you call `posthog.identify`, `posthog.alias`, `posthog.setPersonProperties`, `posthog.unsetPersonProperties`, `posthog.group`, `posthog.setPersonPropertiesForFlags` or `posthog.setGroupPropertiesForFlags` Anonymous users won't get person profiles.
     *
     * @default 'identified_only'
     */
    person_profiles?: 'always' | 'never' | 'identified_only'

    /** @deprecated - use `person_profiles` instead  */
    process_person?: 'always' | 'never' | 'identified_only'

    /**
     * Client side rate limiting.
     *
     * A token bucket, per browser, that stops a runaway loop on your site from flooding capture.
     * When it drains, further `capture` calls are dropped and a one-off `$$client_ingestion_warning`
     * is sent reporting how many events were dropped and the page and session that tripped it -
     * usually the fastest way to find the loop. Raise these limits if you legitimately capture in
     * bursts; a warning under the defaults is more often a bug on the page than a limit set too low.
     */
    rate_limiting?: {
        /**
         * The average number of events per second that should be permitted
         *
         * @default 10
         */
        events_per_second?: number

        /**
         * How many events can be captured in a burst. This defaults to 10 times the events_per_second count
         *
         * @default 10 * `events_per_second`
         */
        events_burst_limit?: number
    }

    /**
     * Used when sending data via `fetch`, use with care.
     * This is intentionally meant to be used with NextJS `fetch`
     *
     * Incorrect `cache` usage may cause out-of-date data for feature flags, actions tracking, etc.
     * See https://nextjs.org/docs/app/api-reference/functions/fetch#fetchurl-options
     */
    fetch_options?: {
        cache?: RequestCache
        next_options?: NextOptions
    }

    /**
     * Used to change the behavior of the request queue.
     * This is an advanced feature and should be used with caution.
     */
    request_queue_config?: RequestQueueConfig

    /**
     * Used to set-up external integrations with PostHog data - such as session replays, distinct id, etc.
     */
    integrations?: Record<ExternalIntegrationKind, boolean>

    /**
     * Enables cookieless mode. In this mode, PostHog will not set any cookies, or use session or local storage. User
     * identity is handled by generating a privacy-preserving hash on PostHog's servers.
     *
     * Web Vitals (`capture_performance.web_vitals`) are supported: metrics are sent without client session IDs;
     * ingestion assigns `$session_id` when cookieless mode is enabled for the project.
     *
     * - 'always' - enable cookieless mode immediately on startup, use this if you do not intend to show a cookie banner
     * - 'on_reject' - enable cookieless mode only if the user rejects cookies, use this if you want to show a cookie banner. If the user accepts cookies, cookieless mode will not be used, and PostHog will use cookies and local storage as usual.
     *
     * Note that you MUST enable cookieless mode in your PostHog project's settings, otherwise all your cookieless events will be ignored. We plan to remove this requirement in the future.
     * */
    cookieless_mode?: 'always' | 'on_reject'

    /**
     * A hostname pattern to match test environments. When the current hostname matches,
     * `setInternalOrTestUser()` is called automatically on startup, enabling person processing
     * and setting `$internal_or_test_user: true`.
     *
     * Can be a string (exact match) or RegExp (pattern match).
     * Set to `null` to explicitly disable (useful when using `defaults: '2026-01-30'`).
     *
     * @default undefined (when defaults is before '2026-01-30')
     * @default /^(localhost|127\.0\.0\.1)$/ (when defaults >= '2026-01-30')
     *
     * @example
     * ```js
     * // Exact match
     * posthog.init('token', { internal_or_test_user_hostname: 'example.com' })
     *
     * // Regex pattern
     * posthog.init('token', { internal_or_test_user_hostname: /\.local$/ })
     *
     * // Disable
     * posthog.init('token', { internal_or_test_user_hostname: null })
     * ```
     */
    internal_or_test_user_hostname?: string | RegExp | null

    /**
     * Display language override for Product Tours.
     *
     * Must be a valid BCP 47 language code.
     *
     * In the future this will be used for Surveys and other products that
     * deliver in-app experiences to end-users.
     */
    override_display_language?: string | null

    /**
     * A list of hostnames for which to inject PostHog tracing headers to all requests
     * (X-POSTHOG-DISTINCT-ID, X-POSTHOG-SESSION-ID, X-POSTHOG-WINDOW-ID). Used to link
     * frontend sessions to backend traces (see https://posthog.com/docs/llm-analytics/link-session-replay).
     */
    tracing_headers?: string[]

    /**
     * @deprecated Use {@link tracing_headers} instead. Kept for backwards compatibility.
     */
    addTracingHeaders?: string[]

    // ------- PREVIEW CONFIGS -------

    /**
     * @deprecated Use {@link tracing_headers} instead. Kept for backwards compatibility.
     */
    __add_tracing_headers?: string[]

    /**
     * @deprecated This option is a no-op. The browser SDK already uses the `/flags/?v=2` endpoint.
     * */
    __preview_flags_v2?: boolean

    /**
     * @deprecated This option is a no-op. Session replay is lazy-loaded by default.
     * */
    __preview_eager_load_replay?: boolean

    /**
     * Prevents posthog-js from using the `navigator.sendBeacon` API to send events.
     * Enabling this option may hurt the reliability of sending $pageleave events.
     */
    disable_beacon?: boolean

    /**
     * @deprecated Use `disable_beacon` instead.
     */
    __preview_disable_beacon?: boolean

    /**
     * @deprecated This option is a no-op. The browser SDK no longer sets `XMLHttpRequest.withCredentials`.
     */
    __preview_disable_xhr_credentials?: boolean

    /**
     * @deprecated Use {@link strict_script_versioning} and {@link asset_host} instead.
     * When set to true, this is equivalent to strict_script_versioning: true.
     * When set to a string, this is equivalent to strict_script_versioning: true
     * and asset_host set to that string.
     */
    __preview_external_dependency_versioned_paths?: boolean | string

    /**
     * PREVIEW - MAY CHANGE WITHOUT WARNING - DO NOT USE IN PRODUCTION
     * Enables collection of bot traffic as $bot_pageview events with detailed bot detection
     * properties instead of dropping them entirely. Use it alongside opt_out_useragent_filter
     */
    __preview_capture_bot_pageviews?: boolean

    // ------- RETIRED CONFIGS - NO REPLACEMENT OR USAGE -------

    /**
     * @deprecated - does nothing
     * was present only for PostHog testing of replay lazy loading
     * */
    __preview_lazy_load_replay?: boolean

    /** @deprecated - NOT USED ANYMORE, kept here for backwards compatibility reasons */
    api_method?: string

    /** @deprecated - NOT USED ANYMORE, kept here for backwards compatibility reasons */
    inapp_protocol?: string

    /** @deprecated - NOT USED ANYMORE, kept here for backwards compatibility reasons */
    inapp_link_new_window?: boolean

    /**
     * @deprecated - THIS OPTION HAS NO EFFECT, kept here for backwards compatibility reasons.
     * Use a custom transformation or "Discard IP data" project setting instead: @see https://posthog.com/tutorials/web-redact-properties#hiding-customer-ip-address.
     */
    ip: boolean
}