posthog-js/lib/src/types.d.ts

Posthog-js allows you to automatically capture usage and send events to PostHog.

import { PostHog } from './posthog-core';
import type { SAMPLED } from './extensions/replay/external/triggerMatching';
import { Compression, type RemoteConfig, type RemoteConfigResult as BrowserCommonRemoteConfigResult, type SessionRecordingRemoteConfig } from '@posthog/browser-common';
import type { ExtensionConstructor } from './extensions/types';
import type { Autocapture } from './autocapture';
import type { DeadClicksAutocapture } from './extensions/dead-clicks-autocapture';
import type { ExceptionObserver } from './extensions/exception-autocapture';
import type { HistoryAutocapture } from './extensions/history-autocapture';
import type { TracingHeaders } from './extensions/tracing-headers';
import type { WebVitalsAutocapture } from './extensions/web-vitals';
import type { SessionRecording } from './extensions/replay/session-recording';
import type { Heatmaps } from './heatmaps';
import type { PostHogProductTours } from './posthog-product-tours';
import type { SiteApps } from './site-apps';
import type { BrowserSurveys } from './browser-surveys';
import type { Toolbar } from './extensions/toolbar';
import type { PostHogExceptions } from './posthog-exceptions';
import type { WebExperiments } from './web-experiments';
import type { PostHogConversations } from './extensions/conversations/posthog-conversations';
import type { PostHogFeatureFlags } from './posthog-featureflags';
import type { PostHogLogs } from './posthog-logs';
import type { PostHogMetrics } from './posthog-metrics';
export type { Property, Properties, JsonType, JsonRecord } from '@posthog/types';
export type { KnownEventName, EventName, CaptureResult, CaptureOptions, BeforeSendFn } from '@posthog/types';
export type { FeatureFlagsCallback, FeatureFlagDetail, FeatureFlagMetadata, EvaluationReason, FeatureFlagResult, FeatureFlagOptions, IsFeatureEnabledOptions, RemoteConfigFeatureFlagCallback, EarlyAccessFeature, EarlyAccessFeatureStage, EarlyAccessFeatureCallback, EarlyAccessFeatureResponse, FeatureFlagOverrides, FeatureFlagPayloadOverrides, FeatureFlagOverrideOptions, OverrideFeatureFlagsOptions, } from '@posthog/types';
export type { Headers, RequestResponse, RequestCallback } from '@posthog/types';
export type { SessionRecordingCanvasOptions, CanvasMaskRegion, InitiatorType, NetworkRequest, CapturedNetworkRequest, SessionIdChangedCallback, SeverityLevel, } from '@posthog/types';
export type { AutocaptureCompatibleElement, DomAutocaptureEvents, AutocaptureConfig, RageclickConfig, BootstrapConfig, ResetOptions, SupportedWebVitalsMetrics, PerformanceCaptureConfig, DeadClickCandidate, ExceptionAutoCaptureConfig, ExceptionStepsConfig, DeadClicksAutoCaptureConfig, HeatmapConfig, ConfigDefaults, ExternalIntegrationKind, ErrorTrackingOptions, MaskInputOptions, SlimDOMOptions, SessionRecordingSamplingConfig, SessionRecordingOptions, RequestQueueConfig, CapturePageviewOptions, } from '@posthog/types';
export type { ToolbarUserIntent, ToolbarSource, ToolbarVersion, ToolbarParams } from '@posthog/types';
export type { LogSeverityLevel, OtlpSeverityText, OtlpSeverityEntry, LogAttributeValue, LogAttributes, CaptureLogOptions, Logger, OtlpAnyValue, OtlpKeyValue, OtlpLogRecord, OtlpLogsPayload, } from '@posthog/types';
export type { LogSdkContext } from '@posthog/core';
export { Compression };
export type { RemoteConfig, FlagVariant, SessionRecordingRemoteConfig, SessionRecordingUrlTrigger, SessionRecordingEventTrigger, SessionRecordingTriggerPropertyFilter, SessionRecordingTriggerGroup, NetworkRecordOptions, PropertyMatchType, ErrorTrackingSuppressionRule, ErrorTrackingSuppressionRuleValue, } from '@posthog/browser-common';
export type { MetricAttributeValue, MetricAttributes, MetricType, CaptureMetricOptions, MetricSample, BeforeSendMetricFn, OtlpMetricsPayload, MetricsConfig, } from '@posthog/types';
export type { KnownUnsafeEditableEvent } from '@posthog/core';
import type { JsonType, Properties, EventName, FeatureFlagDetail, PostHogConfig as BasePostHogConfig, PostHog as BasePostHogInterface, RequestResponse } from '@posthog/types';
export type PostHogInterface = Omit<BasePostHogInterface, 'config' | 'init' | 'set_config'> & {
    config: PostHogConfig;
    set_config(config: Partial<PostHogConfig>): void;
};
export type PostHogConfig = Omit<BasePostHogConfig, 'loaded'> & {
    loaded: (posthog: PostHogInterface) => void;
    /**
     * Disables capturing the `$device_model` super-property.
     *
     * When capturing is enabled (the default), PostHog resolves the hardware model once during init
     * via `navigator.userAgentData.getHighEntropyValues(['model'])` and registers it as the raw OEM
     * code (e.g. `Pixel 7`). This is Chromium-only and only meaningful on Android — it resolves to
     * `undefined` on Safari/Firefox and to an empty string on desktop, in which cases nothing is
     * registered.
     *
     * This opt-out is offered because `getHighEntropyValues` is still experimental and Chromium-only
     * (not yet a cross-browser standard); set it to `true` to skip the call entirely.
     *
     * @default false
     */
    disableDeviceModel?: boolean;
    /**
     * Internal: Extension class overrides for tree-shaking support.
     * When provided, these classes are used instead of the default imports.
     * This enables entrypoints to control which extensions are bundled.
     * @internal
     */
    __extensionClasses?: {
        exceptions?: ExtensionConstructor<PostHogExceptions>;
        historyAutocapture?: ExtensionConstructor<HistoryAutocapture>;
        tracingHeaders?: ExtensionConstructor<TracingHeaders>;
        siteApps?: ExtensionConstructor<SiteApps>;
        sessionRecording?: ExtensionConstructor<SessionRecording>;
        autocapture?: ExtensionConstructor<Autocapture>;
        productTours?: ExtensionConstructor<PostHogProductTours>;
        heatmaps?: ExtensionConstructor<Heatmaps>;
        webVitalsAutocapture?: ExtensionConstructor<WebVitalsAutocapture>;
        exceptionObserver?: ExtensionConstructor<ExceptionObserver>;
        deadClicksAutocapture?: ExtensionConstructor<DeadClicksAutocapture>;
        surveys?: ExtensionConstructor<BrowserSurveys>;
        toolbar?: ExtensionConstructor<Toolbar>;
        experiments?: ExtensionConstructor<WebExperiments>;
        conversations?: ExtensionConstructor<PostHogConversations>;
        featureFlags?: ExtensionConstructor<PostHogFeatureFlags>;
        logs?: ExtensionConstructor<PostHogLogs>;
        metrics?: ExtensionConstructor<PostHogMetrics>;
    };
};
type NextOptions = {
    revalidate: false | 0 | number;
    tags: string[];
};
export interface RequestWithOptions {
    url: string;
    data?: Record<string, any> | Record<string, any>[];
    headers?: Record<string, any>;
    transport?: 'XHR' | 'fetch' | 'sendBeacon';
    method?: 'POST' | 'GET';
    urlQueryArgs?: {
        compression: Compression;
    };
    callback?: (response: RequestResponse) => void;
    timeout?: number;
    noRetries?: boolean;
    disableTransport?: ('XHR' | 'fetch' | 'sendBeacon')[];
    compression?: Compression | 'best-available';
    /** Used when best-available compression negotiation does not select a format. */
    compressionFallback?: Compression;
    /**
     * Controls where the request dispatch time is sent.
     * - `body` adds ISO `sent_at` to the request object, or every object in an array (for example, flags and recordings).
     * - `capture-body` wraps events in `{ api_key, batch, sent_at }` with an ISO timestamp.
     * - `query` adds numeric `sent_at` to POST requests or cache-busting `_` to GET requests.
     */
    timestampMode?: 'body' | 'capture-body' | 'query';
    fetchOptions?: {
        cache?: RequestInit['cache'];
        next?: NextOptions;
    };
    /**
     * When set, `_send_request` invokes `callback` with a synthetic response
     * on the paths that otherwise drop a request without notifying the caller
     * (client not loaded, server rate limit). Opt-in so existing callers keep
     * their current behavior; the logs pipeline uses it to keep records for a
     * later retry instead of losing them silently.
     */
    fireCallbackOnDrop?: boolean;
}
export interface QueuedRequestWithOptions extends RequestWithOptions {
    /** key of queue, e.g. 'sessionRecording' vs 'event' */
    batchKey?: string;
}
export interface RetriableRequestWithOptions extends QueuedRequestWithOptions {
    retriesPerformedSoFar?: number;
}
/** the config stored in persistence when session recording remote config is received */
export type SessionRecordingPersistedConfig = Omit<SessionRecordingRemoteConfig, 'recordCanvas' | 'canvasFps' | 'canvasQuality' | 'networkPayloadCapture' | 'sampleRate' | 'minimumDurationMilliseconds'> & {
    /**
     * Used to determine if the persisted config is still valid or we need to wait for a new one
     * only accepts undefined since older versions of the library didn't set this.
     */
    cache_timestamp?: number;
    enabled: boolean;
    networkPayloadCapture: SessionRecordingRemoteConfig['networkPayloadCapture'] & {
        capturePerformance: RemoteConfig['capturePerformance'];
    };
    canvasRecording: {
        enabled: SessionRecordingRemoteConfig['recordCanvas'];
        fps: SessionRecordingRemoteConfig['canvasFps'];
        quality: SessionRecordingRemoteConfig['canvasQuality'];
    };
    sampleRate: number | null;
    minimumDurationMilliseconds: number | null | undefined;
};
/**
 * Outcome of a remote config fetch: the config, or an explicit failure.
 * @internal
 */
export type RemoteConfigResult = BrowserCommonRemoteConfigResult;
/**
 * Flags returns feature flags and their payloads
 */
export interface FlagsResponse extends RemoteConfig {
    featureFlags: Record<string, string | boolean>;
    featureFlagPayloads: Record<string, JsonType>;
    errorsWhileComputingFlags: boolean;
    requestId?: string;
    flags: Record<string, FeatureFlagDetail>;
    evaluatedAt?: number;
    /**
     * Server-controlled gate for minimal `$feature_flag_called` events. `true` only when the
     * project opted in; omitted otherwise. Absence always means full events.
     */
    minimalFlagCalledEvents?: boolean;
}
export type SiteAppGlobals = {
    event: {
        uuid: string;
        event: EventName;
        properties: Properties;
        timestamp?: Date;
        elements_chain?: string;
        distinct_id?: string;
    };
    person: {
        properties: Properties;
    };
    groups: Record<string, {
        id: string;
        type: string;
        properties: Properties;
    }>;
};
export type SiteAppLoader = {
    id: string;
    init: (config: {
        posthog: PostHog;
        callback: (success: boolean) => void;
    }) => {
        processEvent?: (globals: SiteAppGlobals) => void;
    };
};
export type SiteApp = {
    id: string;
    loaded: boolean;
    errored: boolean;
    processedBuffer: boolean;
    processEvent?: (globals: SiteAppGlobals) => void;
};
export interface PersistentStore {
    _is_supported: () => boolean;
    _error: (error: any) => void;
    _parse: (name: string) => any;
    _get: (name: string) => any;
    _set: (name: string, value: any, expire_days?: number | null, cross_subdomain?: boolean, secure?: boolean, debug?: boolean) => boolean;
    _remove: (name: string, cross_subdomain?: boolean) => void;
}
export type EventHandler = (event: Event) => boolean | void;
export type SnippetArrayItem = [method: string, ...args: any[]];
export type ErrorEventArgs = [
    event: string | Event,
    source?: string | undefined,
    lineno?: number | undefined,
    colno?: number | undefined,
    error?: Error | undefined
];
export declare const severityLevels: readonly ["fatal", "error", "warning", "log", "info", "debug"];
export type SessionStartReason = 'sampling_overridden' | 'recording_initialized' | 'linked_flag_matched' | 'linked_flag_overridden' | typeof SAMPLED | 'session_id_changed' | 'url_trigger_matched' | 'event_trigger_matched';
export type OverrideConfig = {
    sampling: boolean;
    linked_flag: boolean;
    url_trigger: boolean;
    event_trigger: boolean;
};