posthog-js
Version:
Posthog-js allows you to automatically capture usage and send events to PostHog.
1,928 lines • 71.7 kB
TypeScript
import { PostHog, PostHog as PostHog$1 } from './module';
import { ActionStepStringMatching, ActionStepType, BasicSurveyQuestion, Compression, ConversationsRemoteConfig, DisplaySurveyOptions, DisplaySurveyPopoverOptions, DisplaySurveyType, ErrorTrackingSuppressionRule, ErrorTrackingSuppressionRuleValue, FlagVariant, FlagsResponse, LinkSurveyQuestion, MultipleSurveyQuestion, NetworkRecordOptions, PropertyFilters, PropertyMatchType, PropertyOperator, RatingSurveyQuestion, RemoteConfig, RemoteConfig as RemoteConfig$1, RemoteConfigResult as RemoteConfigResult$1, SessionRecordingEventTrigger, SessionRecordingRemoteConfig, SessionRecordingRemoteConfig as SessionRecordingRemoteConfig$1, SessionRecordingTriggerGroup, SessionRecordingTriggerPropertyFilter, SessionRecordingUrlTrigger, Survey, SurveyActionType, SurveyActionType as SurveyActionType$1, SurveyAppearance, SurveyCallback, SurveyConfig, SurveyElement, SurveyEventName, SurveyEventProperties, SurveyEventType, SurveyEventWithFilters, SurveyEventWithFilters as SurveyEventWithFilters$1, SurveyPosition, SurveyQuestion, SurveyQuestionBranchingType, SurveyQuestionDescriptionContentType, SurveyQuestionType, SurveyRenderReason, SurveyResponseValue, SurveySchedule, SurveyTabPosition, SurveyType, SurveyWidgetType, SurveyWithTypeAndAppearance, WidgetPosition } from "@posthog/browser-common";
import { Autocapture } from "@posthog/browser-common/autocapture";
import { ErrorTracking, KnownUnsafeEditableEvent, LogSdkContext, SurveyPosition as SurveyPosition$1 } from "@posthog/core";
import { ConsoleLogsLoader } from "@posthog/browser-common/logs-types";
import rageclick_default from "@posthog/browser-common/rageclick";
import { PostHogSurveys } from "@posthog/browser-common/surveys";
import { PostHogFeatureFlags } from "@posthog/browser-common/feature-flags";
import { PostHogLogs } from "@posthog/browser-common/logs";
import { AutocaptureCompatibleElement, AutocaptureConfig, BeforeSendFn, BeforeSendMetricFn, BootstrapConfig, BrowserMetricsConfig, CanvasMaskRegion, CaptureLogOptions, CaptureMetricOptions, CaptureOptions, CapturePageviewOptions, CaptureResult, CapturedNetworkRequest, ConfigDefaults, DeadClickCandidate, DeadClicksAutoCaptureConfig, DomAutocaptureEvents, EarlyAccessFeature, EarlyAccessFeatureCallback, EarlyAccessFeatureResponse, EarlyAccessFeatureStage, ErrorTrackingOptions, EvaluationReason, EventName, EventName as EventName$1, ExceptionAutoCaptureConfig, ExceptionStepsConfig, ExternalIntegrationKind, FeatureFlagDetail, FeatureFlagMetadata, FeatureFlagOptions, FeatureFlagOverrideOptions, FeatureFlagOverrides, FeatureFlagPayloadOverrides, FeatureFlagResult, FeatureFlagsCallback, Headers, HeatmapConfig, InitiatorType, IsFeatureEnabledOptions, JsonRecord, JsonType, KnownEventName, LogAttributeValue, LogAttributes, LogSeverityLevel, Logger, MaskInputOptions, MetricAttributeValue, MetricAttributes, MetricSample, MetricType, MetricsConfig, NetworkMetricsConfig, NetworkMetricsRequest, NetworkMetricsResponse, NetworkRequest, OtlpAnyValue, OtlpKeyValue, OtlpLogRecord, OtlpLogsPayload, OtlpMetricsPayload, OtlpSeverityEntry, OtlpSeverityText, OverrideFeatureFlagsOptions, PerformanceCaptureConfig, PostHog as PostHog$2, PostHogConfig as PostHogConfig$1, Properties, Properties as Properties$1, Property, RageclickConfig, RemoteConfigFeatureFlagCallback, RequestCallback, RequestQueueConfig, RequestResponse, RequestResponse as RequestResponse$1, ResetOptions, SegmentEnrichmentFilterFn, SegmentIntegrationConfig, SessionIdChangedCallback, SessionRecordingCanvasOptions, SessionRecordingOptions, SessionRecordingSamplingConfig, SeverityLevel, SlimDOMOptions, SupportedWebVitalsMetrics, ToolbarParams, ToolbarSource, ToolbarUserIntent, ToolbarVersion, WebMCPCaptureConfig } from "@posthog/types";
//#region lib/src/extensions/replay/external/triggerMatching.d.ts
declare const SAMPLED = "sampled";
type TriggerType = 'url' | 'event';
/**
* Session recording starts in buffering mode while waiting for "flags response".
* Once the response is received, it might be disabled, active or sampled.
* When "sampled" that means a sample rate is set, and the last time the session ID rotated
* the sample rate determined this session should be sent to the server.
*/
declare const sessionRecordingStatuses: readonly ["disabled", "sampled", "active", "buffering", "paused", "lazy_loading", "awaiting_config", "missing_config", "rrweb_error"];
type SessionRecordingStatus = (typeof sessionRecordingStatuses)[number];
//#endregion
//#region lib/src/extensions/types.d.ts
type ExtensionConstructor<T extends Extension> = new (instance: PostHog$1, ...args: any[]) => T;
interface Extension {
initialize?(): boolean | void;
/**
* Receives the full remote config fetch result. Handlers must narrow on
* `result.ok` before reading config fields, and encode their failure
* behavior explicitly in the `!result.ok` branch.
*/
onRemoteConfig?(result: RemoteConfigResult): void;
}
//#endregion
//#region lib/src/posthog-conversations-types.d.ts
/**
* Author types for messages in a conversation
*/
type MessageAuthorType = 'customer' | 'AI' | 'human';
/**
* TipTap mark types for inline formatting
*/
interface TipTapMark {
type: 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'link';
attrs?: {
href?: string;
target?: string;
[key: string]: unknown;
};
}
/**
* TipTap node representing content in the document tree
*/
interface TipTapNode {
type: string;
attrs?: Record<string, unknown>;
content?: TipTapNode[];
marks?: TipTapMark[];
text?: string;
}
/**
* TipTap document - the root node of rich content
*/
interface TipTapDoc {
type: 'doc';
content?: TipTapNode[];
}
/**
* A message in a conversation
*/
interface Message {
/**
* Unique identifier for the message
*/
id: string;
/**
* The message content as plain text (fallback)
*/
content: string;
/**
* Rich content in TipTap JSON format (preferred for rendering)
* Falls back to `content` if missing or invalid
*/
rich_content?: TipTapDoc;
/**
* Type of the message author
*/
author_type: MessageAuthorType;
/**
* Display name of the message author
*/
author_name?: string;
/**
* ISO timestamp when the message was created
*/
created_at: string;
/**
* Whether this is an internal note (not shown to customer)
*/
is_private: boolean;
}
/**
* Status of a support ticket
*/
type TicketStatus = 'new' | 'open' | 'pending' | 'on_hold' | 'resolved';
/**
* A support ticket in the conversations system
*/
interface Ticket {
/**
* Unique identifier for the ticket
*/
id: string;
/**
* Current status of the ticket
*/
status: TicketStatus;
/**
* Preview of the last message
*/
last_message?: string;
/**
* ISO timestamp of the last message
*/
last_message_at?: string;
/**
* Total number of messages in this ticket
*/
message_count: number;
/**
* ISO timestamp when the ticket was created
*/
created_at: string;
/**
* Array of messages (only present in detailed ticket view)
*/
messages?: Message[];
/**
* Number of unread messages from the team
*/
unread_count?: number;
}
/**
* Visual state of the conversations widget
*/
type ConversationsWidgetState = 'open' | 'closed';
/**
* Response from sending a message
*/
interface SendMessageResponse {
/**
* ID of the ticket this message belongs to
*/
ticket_id: string;
/**
* ID of the newly created message
*/
message_id: string;
/**
* Current status of the ticket
*/
ticket_status: TicketStatus;
/**
* ISO timestamp when the message was created
*/
created_at: string;
/**
* Number of unread messages from the team
* After customer sends a message, this is always 0
*/
unread_count: number;
}
/**
* Response from fetching messages
*/
interface GetMessagesResponse {
/**
* ID of the ticket
*/
ticket_id: string;
/**
* Current status of the ticket
*/
ticket_status: TicketStatus;
/**
* Array of messages
*/
messages: Message[];
/**
* Whether there are more messages to fetch
*/
has_more: boolean;
/**
* Number of unread messages from the team
*/
unread_count: number;
}
/**
* Response from marking messages as read
*/
interface MarkAsReadResponse {
/**
* Whether the operation was successful
*/
success: boolean;
/**
* Number of unread messages (should be 0 after marking as read)
*/
unread_count: number;
}
/**
* Options for fetching tickets list
*/
interface GetTicketsOptions {
/**
* Filter by ticket status (e.g., 'open', 'closed')
*/
status?: string;
/**
* Number of tickets to return (default: 20)
*/
limit?: number;
/**
* Pagination offset (default: 0)
*/
offset?: number;
}
/**
* Response from fetching tickets list
*/
interface GetTicketsResponse {
/**
* Total count of tickets
*/
count: number;
/**
* Array of tickets
*/
results: Ticket[];
}
/**
* Payload for restoring ticket access from a one-time token
*/
interface RestoreFromTokenPayload {
/**
* Opaque one-time restore token from email link
*/
restore_token: string;
/**
* Current browser widget session ID requesting restore
*/
widget_session_id: string;
/**
* Optional distinct ID for debugging/observability
*/
distinct_id?: string;
/**
* Optional current URL for backend observability
*/
current_url?: string;
}
type RestoreFromTokenStatus = 'success' | 'expired' | 'invalid' | 'used';
/**
* Response from restore token exchange endpoint
*/
interface RestoreFromTokenResponse {
/**
* Restore result
*/
status: RestoreFromTokenStatus;
/**
* Canonical widget session ID to use after restore
*/
widget_session_id?: string;
/**
* Migrated ticket IDs, if any
*/
migrated_ticket_ids?: string[];
/**
* Optional machine-readable backend code
*/
code?: string;
}
/**
* Payload for requesting a self-service restore link email
*/
interface RequestRestoreLinkPayload {
email: string;
request_url: string;
}
/**
* Response from self-service restore link request
*/
interface RequestRestoreLinkResponse {
ok: true;
}
/**
* User traits to send with messages
*/
interface ConversationsTraits {
name?: string | null;
email?: string | null;
[key: string]: string | number | boolean | null | undefined;
}
/**
* User-provided identification data (collected via the widget form)
*/
interface UserProvidedTraits {
name?: string;
email?: string;
}
/**
* Session context captured when creating a new ticket
*/
interface SessionContext {
/**
* URL to the session replay at the time the ticket was created
* Includes timestamp to jump to the exact moment
*/
session_replay_url?: string;
/**
* Page URL where the ticket was created
*/
current_url?: string;
}
/**
* Payload for sending a message via the conversations API
*/
interface SendMessagePayload {
/**
* Widget session ID for access control
*/
widget_session_id: string;
/**
* Distinct ID for linking to PostHog Person
*/
distinct_id: string;
/**
* The message content to send
*/
message: string;
/**
* User identification traits
*/
traits: {
name: string | null;
email: string | null;
};
/**
* Ticket ID to send the message to (null to create a new ticket)
*/
ticket_id: string | null;
/**
* Session ID captured when creating a new ticket
* Stored as a separate queryable DB field
*/
session_id?: string;
/**
* Session context captured when creating a new ticket
* Stored in a JSONField for flexibility
*/
session_context?: SessionContext;
/**
* Verified distinct_id for HMAC identity mode (requires identity_hash)
*/
identity_distinct_id?: string;
/**
* HMAC-SHA256 of identity_distinct_id, signed with the Secret API key from Support settings.
* Project secret API keys (project settings) and personal API keys are rejected.
*/
identity_hash?: string;
}
type ConversationsUnavailableReason = 'disabled_by_config' | 'consent_opted_out' | 'disabled_for_toolbar' | 'remote_config_pending' | 'remote_config_failed' | 'disabled_in_project' | 'missing_token' | 'extensions_unavailable' | 'load_failed' | 'initializing' | 'not_loaded';
//#endregion
//#region lib/src/extensions/replay/types/rrweb-types.d.ts
type attributes = {
[key: string]: string | number | true | null;
};
declare const NodeType: {
readonly Document: 0;
readonly DocumentType: 1;
readonly Element: 2;
readonly Text: 3;
readonly CDATA: 4;
readonly Comment: 5;
};
type NodeType = (typeof NodeType)[keyof typeof NodeType];
type documentNode = {
type: typeof NodeType.Document;
childNodes: serializedNodeWithId[];
compatMode?: string;
};
type documentTypeNode = {
type: typeof NodeType.DocumentType;
name: string;
publicId: string;
systemId: string;
};
type elementNode = {
type: typeof NodeType.Element;
tagName: string;
attributes: attributes;
childNodes: serializedNodeWithId[];
isSVG?: true;
needBlock?: boolean;
isCustom?: true;
};
type textNode = {
type: typeof NodeType.Text;
textContent: string;
isStyle?: true;
};
type cdataNode = {
type: typeof NodeType.CDATA;
textContent: '';
};
type commentNode = {
type: typeof NodeType.Comment;
textContent: string;
};
type serializedNode = (documentNode | documentTypeNode | elementNode | textNode | cdataNode | commentNode) & {
rootId?: number;
isShadowHost?: boolean;
isShadow?: boolean;
};
type serializedNodeWithId = serializedNode & {
id: number;
};
declare const EventType: {
readonly DomContentLoaded: 0;
readonly Load: 1;
readonly FullSnapshot: 2;
readonly IncrementalSnapshot: 3;
readonly Meta: 4;
readonly Custom: 5;
readonly Plugin: 6;
};
type EventType = (typeof EventType)[keyof typeof EventType];
declare const IncrementalSource: {
readonly Mutation: 0;
readonly MouseMove: 1;
readonly MouseInteraction: 2;
readonly Scroll: 3;
readonly ViewportResize: 4;
readonly Input: 5;
readonly TouchMove: 6;
readonly MediaInteraction: 7;
readonly StyleSheetRule: 8;
readonly CanvasMutation: 9;
readonly Font: 10;
readonly Log: 11;
readonly Drag: 12;
readonly StyleDeclaration: 13;
readonly Selection: 14;
readonly AdoptedStyleSheet: 15;
readonly CustomElement: 16;
};
type IncrementalSource = (typeof IncrementalSource)[keyof typeof IncrementalSource];
type domContentLoadedEvent = {
type: typeof EventType.DomContentLoaded;
data: unknown;
};
type loadedEvent = {
type: typeof EventType.Load;
data: unknown;
};
type fullSnapshotEvent = {
type: typeof EventType.FullSnapshot;
data: {
node: serializedNodeWithId;
initialOffset: {
top: number;
left: number;
};
};
};
type metaEvent = {
type: typeof EventType.Meta;
data: {
href: string;
width: number;
height: number;
};
};
type customEventData<T = unknown> = {
tag: string;
payload: T;
href?: string;
};
type customEvent<T = unknown> = {
type: typeof EventType.Custom;
data: customEventData<T>;
};
type pluginEvent<T = unknown> = {
type: typeof EventType.Plugin;
data: {
plugin: string;
payload: T;
};
};
type styleOMValue = {
[key: string]: styleValueWithPriority | string | false;
};
type styleValueWithPriority = [string, string];
type textMutation = {
id: number;
value: string | null;
};
type attributeMutation = {
id: number;
attributes: {
[key: string]: string | styleOMValue | null;
};
};
type removedNodeMutation = {
parentId: number;
id: number;
isShadow?: boolean;
};
type addedNodeMutation = {
parentId: number;
previousId?: number | null;
nextId: number | null;
node: serializedNodeWithId;
};
type mutationCallbackParam = {
texts: textMutation[];
attributes: attributeMutation[];
removes: removedNodeMutation[];
adds: addedNodeMutation[];
isAttachIframe?: true;
};
type mutationData = {
source: typeof IncrementalSource.Mutation;
} & mutationCallbackParam;
type mousePosition = {
x: number;
y: number;
id: number;
timeOffset: number;
};
declare const MouseInteractions: {
readonly MouseUp: 0;
readonly MouseDown: 1;
readonly Click: 2;
readonly ContextMenu: 3;
readonly DblClick: 4;
readonly Focus: 5;
readonly Blur: 6;
readonly TouchStart: 7;
readonly TouchMove_Departed: 8;
readonly TouchEnd: 9;
readonly TouchCancel: 10;
};
type MouseInteractions = (typeof MouseInteractions)[keyof typeof MouseInteractions];
declare const PointerTypes: {
readonly Mouse: 0;
readonly Pen: 1;
readonly Touch: 2;
};
type PointerTypes = (typeof PointerTypes)[keyof typeof PointerTypes];
type mouseInteractionParam = {
type: MouseInteractions;
id: number;
x?: number;
y?: number;
pointerType?: PointerTypes;
};
type mouseInteractionData = {
source: typeof IncrementalSource.MouseInteraction;
} & mouseInteractionParam;
type mousemoveData = {
source: typeof IncrementalSource.MouseMove | typeof IncrementalSource.TouchMove | typeof IncrementalSource.Drag;
positions: mousePosition[];
};
type scrollPosition = {
id: number;
x: number;
y: number;
};
type scrollData = {
source: typeof IncrementalSource.Scroll;
} & scrollPosition;
type viewportResizeDimension = {
width: number;
height: number;
};
type viewportResizeData = {
source: typeof IncrementalSource.ViewportResize;
} & viewportResizeDimension;
type inputValue = {
text: string;
isChecked: boolean;
userTriggered?: boolean;
};
type inputData = {
source: typeof IncrementalSource.Input;
id: number;
} & inputValue;
declare const MediaInteractions: {
readonly Play: 0;
readonly Pause: 1;
readonly Seeked: 2;
readonly VolumeChange: 3;
readonly RateChange: 4;
};
type MediaInteractions = (typeof MediaInteractions)[keyof typeof MediaInteractions];
type mediaInteractionParam = {
type: MediaInteractions;
id: number;
currentTime?: number;
volume?: number;
muted?: boolean;
loop?: boolean;
playbackRate?: number;
};
type mediaInteractionData = {
source: typeof IncrementalSource.MediaInteraction;
} & mediaInteractionParam;
type styleSheetAddRule = {
rule: string;
index?: number | number[];
};
type styleSheetDeleteRule = {
index: number | number[];
};
type styleSheetRuleParam = {
id?: number;
styleId?: number;
removes?: styleSheetDeleteRule[];
adds?: styleSheetAddRule[];
replace?: string;
replaceSync?: string;
};
type styleSheetRuleData = {
source: typeof IncrementalSource.StyleSheetRule;
} & styleSheetRuleParam;
declare const CanvasContext: {
readonly '2D': 0;
readonly WebGL: 1;
readonly WebGL2: 2;
};
type CanvasContext = (typeof CanvasContext)[keyof typeof CanvasContext];
type canvasMutationCommand = {
property: string;
args: Array<unknown>;
setter?: true;
};
type canvasMutationParam = {
id: number;
type: CanvasContext;
commands: canvasMutationCommand[];
} | ({
id: number;
type: CanvasContext;
} & canvasMutationCommand);
type canvasMutationData = {
source: typeof IncrementalSource.CanvasMutation;
} & canvasMutationParam;
type fontParam = {
family: string;
fontSource: string;
buffer: boolean;
descriptors?: FontFaceDescriptors;
};
type fontData = {
source: typeof IncrementalSource.Font;
} & fontParam;
type SelectionRange = {
start: number;
startOffset: number;
end: number;
endOffset: number;
};
type selectionParam = {
ranges: Array<SelectionRange>;
};
type selectionData = {
source: typeof IncrementalSource.Selection;
} & selectionParam;
type styleDeclarationParam = {
id?: number;
styleId?: number;
index: number[];
set?: {
property: string;
value: string | null;
priority: string | undefined;
};
remove?: {
property: string;
};
};
type styleDeclarationData = {
source: typeof IncrementalSource.StyleDeclaration;
} & styleDeclarationParam;
type adoptedStyleSheetParam = {
id: number;
styles?: {
styleId: number;
rules: styleSheetAddRule[];
}[];
styleIds: number[];
};
type adoptedStyleSheetData = {
source: typeof IncrementalSource.AdoptedStyleSheet;
} & adoptedStyleSheetParam;
type customElementParam = {
define?: {
name: string;
};
};
type customElementData = {
source: typeof IncrementalSource.CustomElement;
} & customElementParam;
type incrementalData = mutationData | mousemoveData | mouseInteractionData | scrollData | viewportResizeData | inputData | mediaInteractionData | styleSheetRuleData | canvasMutationData | fontData | selectionData | styleDeclarationData | adoptedStyleSheetData | customElementData;
type incrementalSnapshotEvent = {
type: typeof EventType.IncrementalSnapshot;
data: incrementalData;
};
type eventWithoutTime = domContentLoadedEvent | loadedEvent | fullSnapshotEvent | incrementalSnapshotEvent | metaEvent | customEvent | pluginEvent;
type eventWithTime = eventWithoutTime & {
timestamp: number;
delay?: number;
};
//#endregion
//#region lib/src/utils/globals.d.ts
interface LazyLoadedDeadClicksAutocaptureInterface {
start: (observerTarget: Node) => void;
stop: () => void;
}
//#endregion
//#region lib/src/extensions/dead-clicks-autocapture.d.ts
declare class DeadClicksAutocapture implements Extension {
readonly instance: PostHog$1;
readonly isEnabled: (dca: DeadClicksAutocapture) => boolean;
readonly onCapture?: DeadClicksAutoCaptureConfig['__onCapture'];
get lazyLoadedDeadClicksAutocapture(): LazyLoadedDeadClicksAutocaptureInterface | undefined;
private _lazyLoadedDeadClicksAutocapture;
constructor(instance: PostHog$1, isEnabled: (dca: DeadClicksAutocapture) => boolean, onCapture?: DeadClicksAutoCaptureConfig['__onCapture']);
onRemoteConfig(result: RemoteConfigResult): void;
startIfEnabledOrStop(): void;
private _loadScript;
private _start;
stop(): void;
}
//#endregion
//#region lib/src/extensions/exception-autocapture/index.d.ts
declare class ExceptionObserver {
private _instance;
private _rateLimiter;
private _remoteEnabled;
private _config;
private _unwrapOnError;
private _unwrapUnhandledRejection;
private _unwrapConsoleError;
constructor(instance: PostHog$1);
private _requiredConfig;
get isEnabled(): boolean;
startIfEnabledOrStop(): void;
private _loadScript;
private _startCapturing;
private _stopCapturing;
onRemoteConfig(result: RemoteConfigResult): void;
onConfigChange(): void;
captureException(errorProperties: ErrorTracking.ErrorProperties): void;
}
//#endregion
//#region lib/src/extensions/history-autocapture.d.ts
/**
* Captures pageviews when selected URL components change through the history API, browser back/forward navigation,
* or hash navigation.
*/
declare class HistoryAutocapture implements Extension {
private _instance;
private _popstateListener;
private _hashchangeListener;
private _lastLocation;
private _pendingPageview;
private _isFlushingPageview;
constructor(instance: PostHog$1);
initialize(): void;
get isEnabled(): boolean;
startIfEnabled(): void;
startIfEnabledOrStop(): void;
stop(): void;
monitorHistoryChanges(): void;
private _patchHistoryMethod;
private _getCurrentLocation;
private _getCaptureOptions;
private _shouldCaptureHashChanges;
private _hasLocationChanged;
private _capturePageview;
private _isUrlChanging;
private _flushPendingPageview;
private _setupPopstateListener;
private _setupHashchangeListener;
}
//#endregion
//#region lib/src/extensions/tracing-headers.d.ts
declare class TracingHeaders implements Extension {
private readonly _instance;
private _restoreXHRPatch;
private _restoreFetchPatch;
private _hostnamesForPatch;
constructor(_instance: PostHog$1);
initialize(): void;
private _loadScript;
private _getConfiguredHostnames;
private _syncHostnamesForPatch;
private _stopCapturing;
startIfEnabledOrStop(): void;
private _startCapturing;
}
//#endregion
//#region lib/src/extensions/web-vitals/index.d.ts
declare class WebVitalsAutocapture {
private readonly _instance;
private _enabledServerSide;
private _initialized;
private _buffer;
private _delayedFlushTimer;
constructor(_instance: PostHog$1);
private get _perfConfig();
get allowedMetrics(): SupportedWebVitalsMetrics[];
get flushToCaptureTimeoutMs(): number;
get attributionMetrics(): SupportedWebVitalsMetrics[];
get useAttribution(): boolean;
get useSoftNavs(): boolean;
get _maxAllowedValue(): number;
get isEnabled(): boolean;
startIfEnabled(): void;
onRemoteConfig(result: RemoteConfigResult): void;
private get _callbackFlavor();
private _loadScript;
private _maskedURL;
private _flushToCapture;
private _addToBuffer;
private _startCapturing;
}
//#endregion
//#region lib/src/extensions/replay/session-recording.d.ts
declare class SessionRecording implements Extension {
private readonly _instance;
_forceAllowLocalhostNetworkCapture: boolean;
private _recordingStatus;
private get _config();
private get _persistence();
private _persistFlagsOnSessionListener;
private _lazyLoadedSessionRecording;
private _sessionRecordingDisposed;
private _documentWasEverVisible;
private _onVisibilityChange;
get started(): boolean;
get status(): SessionRecordingStatus;
constructor(_instance: PostHog$1);
initialize(): void;
dispose({ discardBufferedEvents }?: {
discardBufferedEvents?: boolean;
}): void;
private get _isRecordingEnabled();
startIfEnabledOrStop(startReason?: SessionStartReason): void;
/**
* session recording waits until it receives remote config before loading the script
* this is to ensure we can control the script name remotely
* and because we wait until we have local and remote config to determine if we should start at all
* if start is called and there is no remote config then we wait until there is
*/
private _lazyLoadAndStart;
stopRecording(): void;
private _discardRecording;
private _resetSampling;
private _validateSampleRate;
private _persistRemoteConfig;
onRemoteConfig(result: RemoteConfigResult): void;
log(message: string, level?: 'log' | 'warn' | 'error'): void;
private get _scriptName();
private _isRemoteConfigFresh;
private _onScriptLoaded;
/**
* this is maintained on the public API only because it has always been on the public API
* if you are calling this directly you are certainly doing something wrong
* @deprecated
*/
onRRwebEmit(rawEvent: eventWithTime): void;
/**
* this ignores the linked flag config and (if other conditions are met) causes capture to start
*
* It is not usual to call this directly,
* instead call `posthog.startSessionRecording({linked_flag: true})`
* */
overrideLinkedFlag(): void;
/**
* this ignores the sampling config and (if other conditions are met) causes capture to start
*
* It is not usual to call this directly,
* instead call `posthog.startSessionRecording({sampling: true})`
* */
overrideSampling(): void;
/**
* this ignores the URL/Event trigger config and (if other conditions are met) causes capture to start
*
* It is not usual to call this directly,
* instead call `posthog.startSessionRecording({trigger: 'url' | 'event'})`
* */
overrideTrigger(triggerType: TriggerType): void;
get sdkDebugProperties(): Properties;
/**
* This adds a custom event to the session recording
*
* It is not intended for arbitrary public use - playback only displays known custom events
* And is exposed on the public interface only so that other parts of the SDK are able to use it
*
* if you are calling this from client code, you're probably looking for `posthog.capture('$custom_event', {...})`
*/
tryAddCustomEvent(tag: string, payload: any): boolean;
flushBeforeIdentityReset(): void;
}
//#endregion
//#region lib/src/heatmaps.d.ts
type HeatmapEventBuffer = {
[key: string]: Properties[];
} | undefined;
declare class Heatmaps implements Extension {
instance: PostHog$1;
rageclicks: rageclick_default;
_enabledServerSide: boolean;
private get _config();
_initialized: boolean;
_mouseMoveTimeout: ReturnType<typeof setTimeout> | undefined;
private _buffer;
private _flushInterval;
private _deadClicksCapture;
private _onClickHandler;
private _onMouseMoveHandler;
private _flushHandler;
private _onVisibilityChange_handler;
constructor(instance: PostHog$1);
initialize(): void;
get flushIntervalMilliseconds(): number;
get isEnabled(): boolean;
startIfEnabled(): void;
onRemoteConfig(result: RemoteConfigResult): void;
getAndClearBuffer(): HeatmapEventBuffer;
private _onDeadClick;
private _onVisibilityChange;
private _setupListeners;
private _removeListeners;
private _getProperties;
private _onClick;
private _onMouseMove;
private _capture;
private _flush;
}
//#endregion
//#region lib/src/extensions/product-tours/element-inference.d.ts
interface InferredSelector {
autoData: string;
text: string | null;
excludeText?: boolean;
precision?: number;
}
//#endregion
//#region lib/src/posthog-product-tours-types.d.ts
interface JSONContent {
type?: string;
attrs?: Record<string, any>;
content?: JSONContent[];
marks?: {
type: string;
attrs?: Record<string, any>;
}[];
text?: string;
}
type ProductTourStepType = 'element' | 'modal' | 'survey' | 'banner';
interface ProductTourBannerConfig {
behavior: 'sticky' | 'static' | 'custom';
selector?: string;
action?: {
type: 'none' | 'link' | 'trigger_tour';
link?: string;
tourId?: string;
};
animation?: {
duration?: number;
};
}
/** Button actions available on modal steps */
type ProductTourButtonAction = 'dismiss' | 'link' | 'next_step' | 'previous_step' | 'trigger_tour';
interface ProductTourStepButton {
text: string;
action: ProductTourButtonAction;
/** URL to open when action is 'link' */
link?: string;
/** Tour ID to trigger when action is 'trigger_tour' */
tourId?: string;
}
interface ProductTourStepButtons {
primary?: ProductTourStepButton;
secondary?: ProductTourStepButton;
}
type ProductTourSurveyQuestionType = 'open' | 'rating';
interface ProductTourSurveyQuestion {
type: ProductTourSurveyQuestionType;
questionText: string;
/** Rating display type - emoji or number */
display?: 'emoji' | 'number';
/** Rating scale - 3 or 5 for emoji, 5 or 10 for number */
scale?: 3 | 5 | 10;
/** Label for low end of rating scale (e.g., "Not likely") */
lowerBoundLabel?: string;
/** Label for high end of rating scale (e.g., "Very likely") */
upperBoundLabel?: string;
submitButtonText?: string;
backButtonText?: string;
}
interface ProductTourStep {
id: string;
type: ProductTourStepType;
selector?: string;
progressionTrigger: 'button' | 'click';
content: JSONContent | null;
/** Pre-rendered HTML content from the editor. If present, SDK should use this instead of rendering from JSONContent. */
contentHtml?: string;
/** Inline survey question config - if present, this is a survey step */
survey?: ProductTourSurveyQuestion;
/** ID of the auto-created survey for this step (set by backend) */
linkedSurveyId?: string;
/** ID of the survey question (set by backend, used for event tracking) */
linkedSurveyQuestionId?: string;
/** Enhanced element data for more reliable lookup at runtime */
inferenceData?: InferredSelector;
/** Use CSS selector instead of inference. Defaults to false (use inference). */
useManualSelector?: boolean;
/** Maximum tooltip width in pixels (defaults to 320px) */
maxWidth?: number;
/** Position for modal/survey steps (defaults to middle_center) */
modalPosition?: SurveyPosition$1;
/** Button configuration for modal steps */
buttons?: ProductTourStepButtons;
/** Banner configuration (only for banner steps) */
bannerConfig?: ProductTourBannerConfig;
/** translation data for this tour step */
translations?: Record<string, ProductTourStepTranslation>;
}
/** all translatable content for a given tour step */
interface ProductTourStepTranslation {
content?: ProductTourStep['content'];
contentHtml?: ProductTourStep['contentHtml'];
buttons?: {
primary?: Pick<ProductTourStepButton, 'text'>;
secondary?: Pick<ProductTourStepButton, 'text'>;
};
survey?: Pick<ProductTourSurveyQuestion, 'questionText' | 'lowerBoundLabel' | 'upperBoundLabel' | 'submitButtonText' | 'backButtonText'>;
}
/** maps to main repo EffectiveProductTourType */
type ProductTourType = 'tour' | 'announcement' | 'banner';
interface ProductTourWaitPeriod {
days: number;
types: ProductTourType[];
}
interface ProductTourConditions {
url?: string;
urlMatchType?: PropertyMatchType;
selector?: string;
autoShowDelaySeconds?: number;
events?: {
values: SurveyEventWithFilters$1[];
} | null;
cancelEvents?: {
values: SurveyEventWithFilters$1[];
} | null;
actions?: {
values: SurveyActionType$1[];
} | null;
linkedFlagVariant?: string;
deviceTypes?: string[];
seenTourWaitPeriod?: ProductTourWaitPeriod;
}
interface ProductTourAppearance {
backgroundColor?: string;
textColor?: string;
buttonColor?: string;
borderRadius?: number;
buttonBorderRadius?: number;
borderColor?: string;
fontFamily?: string;
boxShadow?: string;
showOverlay?: boolean;
whiteLabel?: boolean;
/** defaults to true, auto-set to false for announcements/banners */
dismissOnClickOutside?: boolean;
zIndex?: number;
}
type ProductTourDisplayFrequency = 'show_once' | 'until_interacted' | 'always';
interface ProductTour {
id: string;
name: string;
description?: string;
tour_type: ProductTourType;
auto_launch?: boolean;
start_date: string | null;
end_date: string | null;
current_iteration?: number;
conditions?: ProductTourConditions;
appearance?: ProductTourAppearance;
steps: ProductTourStep[];
internal_targeting_flag_key?: string;
linked_flag_key?: string;
display_frequency?: ProductTourDisplayFrequency;
disable_image_preload?: boolean;
}
type ProductTourCallback = (tours: ProductTour[], context?: {
isLoaded: boolean;
error?: string;
}) => void;
type ProductTourSelectorError = 'not_found' | 'multiple_matches' | 'not_visible';
type ProductTourDismissReason = 'user_clicked_skip' | 'user_clicked_outside' | 'escape_key' | 'element_unavailable' | 'container_unavailable';
type ProductTourRenderReason = 'auto' | 'api' | 'trigger' | 'event';
declare const DEFAULT_PRODUCT_TOUR_APPEARANCE: Required<ProductTourAppearance>;
interface ShowTourOptions {
reason?: ProductTourRenderReason;
enableStrictValidation?: boolean;
}
declare const ProductTourEventName: {
readonly SHOWN: "product tour shown";
readonly DISMISSED: "product tour dismissed";
readonly COMPLETED: "product tour completed";
readonly STEP_SHOWN: "product tour step shown";
readonly STEP_COMPLETED: "product tour step completed";
readonly BUTTON_CLICKED: "product tour button clicked";
readonly STEP_SELECTOR_FAILED: "product tour step selector failed";
readonly BANNER_CONTAINER_SELECTOR_FAILED: "product tour banner container selector failed";
readonly BANNER_ACTION_CLICKED: "product tour banner action clicked";
};
type ProductTourEventName = (typeof ProductTourEventName)[keyof typeof ProductTourEventName];
declare const ProductTourEventProperties: {
readonly TOUR_ID: "$product_tour_id";
readonly TOUR_NAME: "$product_tour_name";
readonly TOUR_ITERATION: "$product_tour_iteration";
readonly TOUR_RENDER_REASON: "$product_tour_render_reason";
readonly TOUR_STEP_ID: "$product_tour_step_id";
readonly TOUR_STEP_ORDER: "$product_tour_step_order";
readonly TOUR_STEP_TYPE: "$product_tour_step_type";
readonly TOUR_DISMISS_REASON: "$product_tour_dismiss_reason";
readonly TOUR_BUTTON_TEXT: "$product_tour_button_text";
readonly TOUR_BUTTON_ACTION: "$product_tour_button_action";
readonly TOUR_BUTTON_LINK: "$product_tour_button_link";
readonly TOUR_BUTTON_TOUR_ID: "$product_tour_button_tour_id";
readonly TOUR_STEPS_COUNT: "$product_tour_steps_count";
readonly TOUR_STEP_SELECTOR: "$product_tour_step_selector";
readonly TOUR_STEP_SELECTOR_FOUND: "$product_tour_step_selector_found";
readonly TOUR_STEP_ELEMENT_TAG: "$product_tour_step_element_tag";
readonly TOUR_STEP_ELEMENT_ID: "$product_tour_step_element_id";
readonly TOUR_STEP_ELEMENT_CLASSES: "$product_tour_step_element_classes";
readonly TOUR_STEP_ELEMENT_TEXT: "$product_tour_step_element_text";
readonly TOUR_ERROR: "$product_tour_error";
readonly TOUR_MATCHES_COUNT: "$product_tour_matches_count";
readonly TOUR_FAILURE_PHASE: "$product_tour_failure_phase";
readonly TOUR_WAITED_FOR_ELEMENT: "$product_tour_waited_for_element";
readonly TOUR_WAIT_DURATION_MS: "$product_tour_wait_duration_ms";
readonly TOUR_BANNER_SELECTOR: "$product_tour_banner_selector";
readonly TOUR_LINKED_SURVEY_ID: "$product_tour_linked_survey_id";
readonly USE_MANUAL_SELECTOR: "$use_manual_selector";
readonly INFERENCE_DATA_PRESENT: "$inference_data_present";
readonly TOUR_LAST_SEEN_DATE: "$product_tour_last_seen_date";
readonly TOUR_TYPE: "$product_tour_type";
};
type ProductTourEventProperties = (typeof ProductTourEventProperties)[keyof typeof ProductTourEventProperties];
//#endregion
//#region lib/src/posthog-product-tours.d.ts
declare class PostHogProductTours implements Extension {
private _instance;
private _productTourManager;
private _cachedTours;
private get _persistence();
constructor(instance: PostHog$1);
initialize(): void;
onRemoteConfig(result: RemoteConfigResult): void;
loadIfEnabled(): void;
private _loadScript;
private _startProductTours;
getProductTours(callback: ProductTourCallback, forceReload?: boolean): void;
getActiveProductTours(callback: ProductTourCallback): void;
showProductTour(tourId: string): void;
previewTour(tour: ProductTour): void;
dismissProductTour(): void;
nextStep(): void;
previousStep(): void;
clearCache(): void;
resetTour(tourId: string): void;
resetAllTours(): void;
cancelPendingTour(tourId: string): void;
}
//#endregion
//#region lib/src/site-apps.d.ts
declare class SiteApps implements Extension {
private _instance;
apps: Record<string, SiteApp>;
private _stopBuffering?;
private _bufferedInvocations;
private _siteAppElementPatchCount;
private _restoreSiteAppElementPatches?;
constructor(_instance: PostHog$1);
get isEnabled(): boolean;
private _eventCollector;
get siteAppLoaders(): SiteAppLoader[] | undefined;
initialize(): void;
globalsForEvent(event: CaptureResult): SiteAppGlobals;
private _prepareElementForSiteApp;
private _patchSiteAppElementInsertionMethods;
private _releaseSiteAppElementPatches;
private _runWithPreparedSiteAppElements;
setupSiteApp(loader: SiteAppLoader): void;
private _setupSiteApps;
private _onCapturedEvent;
onRemoteConfig(result: RemoteConfigResult): void;
}
//#endregion
//#region lib/src/browser-surveys.d.ts
/** Browser-v1 configuration and lazy-loading adapter for the shared surveys extension. */
declare class BrowserSurveys extends PostHogSurveys {
constructor(instance: PostHog$1);
}
//#endregion
//#region lib/src/extensions/toolbar.d.ts
declare class Toolbar implements Extension {
instance: PostHog$1;
constructor(instance: PostHog$1);
private _setToolbarState;
private _getToolbarState;
initialize(): boolean;
/**
* To load the toolbar, we need an access token and other state. That state comes from one of three places:
* 1. In the URL hash params
* 2. From session storage under the key `toolbarParams` if the toolbar was initialized on a previous page
*/
maybeLoadToolbar(location?: Location | undefined, localStorage?: Storage | undefined, history?: History | undefined): boolean;
private _callLoadToolbar;
loadToolbar(params?: ToolbarParams): boolean;
/** @deprecated Use "loadToolbar" instead. */
_loadEditor(params: ToolbarParams): boolean;
/** @deprecated Use "maybeLoadToolbar" instead. */
maybeLoadEditor(location?: Location | undefined, localStorage?: Storage | undefined, history?: History | undefined): boolean;
}
//#endregion
//#region lib/src/posthog-exceptions.d.ts
declare class PostHogExceptions implements Extension {
private readonly _instance;
private _suppressionRules;
private _errorPropertiesBuilder;
private _exceptionStepsBuffer;
private _exceptionStepsConfig;
constructor(instance: PostHog$1);
onConfigChange(): void;
onRemoteConfig(result: RemoteConfigResult): void;
private get _captureExtensionExceptions();
buildProperties(input: unknown, metadata?: {
handled?: boolean;
syntheticException?: Error;
}): ErrorTracking.ErrorProperties;
addExceptionStep(message: string, properties?: Properties): void;
sendExceptionEvent(properties: Properties): CaptureResult | undefined;
private _addBufferedExceptionSteps;
private _addDroppedExceptionStep;
private _coerceExceptionStepProperties;
private _getExceptionStepsConfig;
private _matchesSuppressionRule;
private _isExtensionException;
private _isInjectedBrowserScriptException;
private _isPostHogException;
private _isExceptionList;
}
//#endregion
//#region lib/src/web-experiments-types.d.ts
interface WebExperimentTransform {
attributes?: {
name: string;
value: string;
}[];
selector?: string;
text?: string;
html?: string;
imgUrl?: string;
css?: string;
}
type WebExperimentUrlMatchType = 'regex' | 'not_regex' | 'exact' | 'is_not' | 'icontains' | 'not_icontains';
interface WebExperimentVariant {
conditions?: {
url?: string;
urlMatchType?: WebExperimentUrlMatchType;
utm?: {
utm_source?: string;
utm_medium?: string;
utm_campaign?: string;
utm_term?: string;
};
};
variant_name: string;
transforms: WebExperimentTransform[];
}
interface WebExperiment {
id: number;
name: string;
feature_flag_key?: string;
variants: Record<string, WebExperimentVariant>;
}
type WebExperimentsCallback = (webExperiments: WebExperiment[]) => void;
//#endregion
//#region lib/src/web-experiments.d.ts
declare class WebExperiments implements Extension {
private _instance;
private _flagToExperiments?;
private get _config();
constructor(_instance: PostHog$1);
initialize(): void;
onFeatureFlags(flags: string[]): void;
previewWebExperiment(): void;
loadIfEnabled(): void;
getWebExperimentsAndEvaluateDisplayLogic: (forceReload?: boolean) => void;
getWebExperiments(callback: WebExperimentsCallback, forceReload: boolean, previewing?: boolean): void;
private _showPreviewWebExperiment;
private static _matchesTestVariant;
private static _matchUrlConditions;
static getWindowLocation(): Location | undefined;
private static _matchUTMConditions;
private static _logInfo;
private _applyTransforms;
_is_bot(): boolean | undefined;
}
//#endregion
//#region lib/src/extensions/conversations/posthog-conversations.d.ts
declare class PostHogConversations implements Extension {
private _instance;
private _isConversationsEnabled?;
private _conversationsManager;
private _isInitializing;
private _remoteConfig;
private _remoteConfigSuccessful?;
private _loadFailed;
private _resetGeneration;
constructor(_instance: PostHog$1);
initialize(): void;
onRemoteConfig(result: RemoteConfigResult): void;
reset(): void;
loadIfEnabled(): void;
/** Helper to finalize conversations initialization */
private _completeInitialization;
/** Helper to handle initialization errors */
private _handleLoadError;
/**
* Show the conversations widget (button and chat panel)
*/
show(): void;
/**
* Hide the conversations widget completely (button and chat panel)
*/
hide(): void;
/**
* Check if conversations are available (enabled in remote config AND loaded)
* Use this to check if conversations API can be used.
*/
isAvailable(): boolean;
/**
* Explain why {@link isAvailable} is currently false, or null when conversations are available.
* Lets a caller that falls back to another channel record the specific cause (bundle blocked,
* disabled in the project, remote config not loaded yet, still initializing, …) rather than
* collapsing every case into a single "unavailable" signal.
*/
getUnavailableReason(): ConversationsUnavailableReason | null;
/**
* Check if the widget is currently visible (rendered and shown)
*/
isVisible(): boolean;
/**
* Send a message programmatically
* Creates a new ticket if none exists or if newTicket is true
*
* @param message - The message text to send
* @param userTraits - Optional user identification data (name, email)
* @param newTicket - If true, forces creation of a new ticket (starts new conversation)
* @returns Promise with response or null if conversations not available yet
* @note Conversations must be available first (check with isAvailable())
*
* @example
* // Send to existing or create new conversation
* const response = await posthog.conversations.sendMessage('Hello!', {
* name: 'John Doe',
* email: 'john@example.com'
* })
*
* @example
* // Force creation of a new conversation/ticket
* const newConvo = await posthog.conversations.sendMessage('Start fresh', undefined, true)
*/
sendMessage(message: string, userTraits?: UserProvidedTraits, newTicket?: boolean): Promise<SendMessageResponse | null>;
/**
* Get messages for the current or specified ticket
*
* @param ticketId - Optional ticket ID (defaults to current active ticket)
* @param after - Optional ISO timestamp to fetch messages after
* @returns Promise with messages response or null if conversations not available yet
* @note Conversations must be available first (check with isAvailable())
*
* @example
* // Get messages for current ticket
* const messages = await posthog.conversations.getMessages()
*
* // Get messages for specific ticket
* const messages = await posthog.conversations.getMessages('ticket-uuid')
*/
getMessages(ticketId?: string, after?: string): Promise<GetMessagesResponse | null>;
/**
* Mark messages as read for the current or specified ticket
*
* @param ticketId - Optional ticket ID (defaults to current active ticket)
* @returns Promise with response or null if conversations not available yet
* @note Conversations must be available first (check with isAvailable())
*
* @example
* await posthog.conversations.markAsRead()
*/
markAsRead(ticketId?: string): Promise<MarkAsReadResponse | null>;
/**
* Get list of tickets for the current widget session
*
* @param options - Optional filtering and pagination options
* @returns Promise with tickets response or null if conversations not available yet
* @note Conversations must be available first (check with isAvailable())
*
* @example
* const tickets = await posthog.conversations.getTickets({
* limit: 10,
* offset: 0,
* status: 'open'
* })
*/
getTickets(options?: GetTicketsOptions): Promise<GetTicketsResponse | null>;
/**
* Request a restore link email for previous conversations.
*
* @param email - Email address associated with previous conversations
* @returns Promise with generic success response or null if conversations unavailable
*/
requestRestoreLink(email: string): Promise<RequestRestoreLinkResponse | null>;
/**
* Redeem a restore token and relink eligible tickets to this browser session.
*
* @param restoreToken - Opaque restore token from restore email link
* @returns Promise with restore status or null if conversations unavailable
*/
restoreFromToken(restoreToken: string): Promise<RestoreFromTokenResponse | null>;
/**
* Parse and redeem `ph_conv_restore` token from the current URL.
*
* @returns Promise with restore status, or null when no token/conversations unavailable
*/
restoreFromUrlToken(): Promise<RestoreFromTokenResponse | null>;
/**
* Get the current active ticket ID
* Returns null if no conversation has been started yet or if not available
*
* @returns Ticket ID or null
* @note Safe to call before conversations are available, will return null
*
* @example
* const ticketId = posthog.conversations.getCurrentTicketId()
* if (ticketId) {
* console.log('Current ticket ID:', ticketId)
* }
*/
getCurrentTicketId(): string | null;
/**
* Get the widget session ID (persistent browser identifier)
* This ID is used for access control and stays the same across page loads
* Returns null if conversations not available yet
*
* @returns Session ID or null if not available
* @note Safe to call before conversations are available, will return null
*
* @example
* const sessionId = posthog.conversations.getWidgetSessionId()
* if (!sessionId) {
* // Conversations not available yet
* posthog.conversations.show()
* }
*/
getWidgetSessionId(): string | null;
/** @internal Called by PostHog.setIdentity() -- forwards to the manager without recursing */
_onIdentityChanged(): void;
/** @internal Called by PostHog.clearIdentity() -- forwards to the manager without recursing */
_onIdentityCleared(): void;
}
//#endregion
//#region lib/src/posthog-persistence.d.ts
/**
* PostHog Persistence Object
* @constructor
*/
declare class PostHogPersistence {
private _config;
props: Properties;
private _storage;
private _campaign_params_url;
private readonly _name;
_disabled: boolean | undefined;
private _secure;
private _expire_days;
private _default_expiry;
private _cross_subdomain;
private _slotState;
private _splitStorageEligible;
private _storesIdentityInCookie;
private _splitStorage;
private readonly _ownsSplitStorage;
private _pendingSaveTimer;
private _lastSeenCookiePropertiesFingerprint;
private _lastSeenMainCookieValue;
private _cookieIdentityChangePending;
private _cookieSyncSuppressed;
private _pendingCrossTabFeatureFlagChanges;
private _storageMigrationInProgress;
private _localIdentityChangePending;
private _crossTabFeatureFlagIdentityMismatch;
private _metaIdentifierChangePending;
private _metaIdentifierStorageSnapshot;
private readonly _crossTabFeatureFlagHandlers;
private _onStorage?;
/**
* @param {PostHogConfig} config initial PostHog configuration
* @param {boolean=} isDisabled should persistence be disabled (e.g. because of consent management)
* @param {boolean=} allowDisabledRead restore stored state read-only during disabled initialization
*/
constructor(config: PostHogConfig, isDisabled?: boolean, ownsSplitStorage?: boolean, allowDisabledRead?: boolean);
markCrossTabFeatureFlagChanges(changes: Record<string, readonly string[] | true>): void;
onCrossTabFeatureFlagChange(handler: () => void): () => void;
destroy(): void;
private _syncCrossTabFeatureFlagProperties;
private _hasCrossTabFeatureFlagIdentityMismatch;
private _rememberCrossTabStorageFingerprint;
private _mergeCrossTabFeatureFlagProperties;
private _reconcileCrossTabFeatureFlagPropertiesBeforeWrite;
private _setCrossTabFeatureFlagChangesPending;
private _markAllCrossTabFeatureFlagChangesPending;
private _markLoadedCrossTabFeatureFlagChangesPending;
private _mergePendingCrossTabFeatureFlagChanges;
private _markPendingCrossTabFeatureFlagChanges;
private _saveDebounceMs;
private _rememberCurrentCookieProperties;
/**
* Adopt shared-cookie changes made by a sibling subdomain without replacing
* localStorage-only or pending in-memory properties. Returns true when a new
* non-empty cookie snapshot was observed.
*/
syncCookieProperties(): boolean;
private _syncCookieProperties;
consumeCookieIdentityChange(): boolean;
_beginCookieSyncSuppression(ignoreDisabled?: boolean): boolean;
_publishSuppressedCookieSnapshot(): void;
_endCookieSyncSuppression(publish?: boolean): void;
/**
* Returns whether persistence is disabled. Only available in SDKs > 1.257.1. Do not use on extensions, otherwise
* it'll break backwards compatibility for any version before 1.257.1.
*/
isDisabled?(): boolean;
private _buildStorage;
private _groupEntryName;
private _resolveSplitStorage;
properties(): Properties;
/**
* Reload persisted properties from storage.
*
* @param allowDisabled - Read without migration writes while disabled, for initial identity restoration
* or when shared consent changed before the in-memory disabled state was reconciled.
*/
load(allowDisabled?: boolean): void;
private _loadGroupEntries;
private _mainCarriesGroupKey;
private _groupEntryIsStale;
/**
* Refresh a single key from on-disk storage into `this.props` without
* touching the rest. Used by `SessionIdManager` on the cross-tab idle
* path so we can pick up a sibling tab's SESSION_ID write without
* either:
* - flushing our own (potentially stale) whole-props blob to storage
* via `flush()`, which would clobber the sibling's write, or
* - replacing all of `props` via `load()`, which would discard any
* in-memory writes that haven't yet been debounced to storage.
*/
refreshKey(prop: string): void;
private _refreshKeys;
/**
* Refresh the Meta identifier keys from storage, so a sibling tab's update is not lost.
* capture() calls this on every event, so it parses storage only when storage has changed
* since the identifiers last matched it. A full parse on each click made INP regress.
*/
refreshMetaIdentifiers(): void;
private _rememberMetaIdentifierStorageSnapshot;
private _storageSnapshot;
/**
* NOTE: Saving frequently causes issues with Recordings and Consent Management Platform (CMP) tools which
* observe cookie changes, and modify their UI, often causing infinite loops.
* As such callers of this should ideally check that the data has changed beforehand
*/
save(): void;
/**
* Force any pending debounced save to land in storage immediately.
* No-op when there is no pending timer — crucially, this means the
* `beforeunload` / `pagehide` listeners installed in the constructor
* cannot accidentally resurrect a storage entry that `remove()` or
* `clear()` just deleted. Without this guard, the listener would
* call `_writeNow()` and write the in-memory `props` (now `{}`) back
* to storage, breaking `posthog.reset()` / opt-out flows.
*/
flush(): void;
private _writeNow;
private _writeNowSplit;
private _partitionProps;
private _entryFingerprint;
private _writeEntry;
remove({ keepGroupEntries }?: {
keepGroupEntries?: boolean;
}): void;
clear(): void;
/**
* @param {Object} props
* @param {*=} default_value
* @param {number=} days
*/
register_once(props: Properties, default_value: any, days?: number): boolean;
/**
* @param {Object} props
* @param {number=} days
*/
register(props: Properties, days?: number): boolean;
unregister(propOrProps: string | readonly string[]): void;
update_campaign_params(): Properties | undefined;
update_search_keyword(): void;
update_referrer_info(): void;
set_initial_person_info(): void;
get_initial_props(): Properties;
safe_merge(props: Properties): Properties;
update_config(config: PostHogConfig, oldConfig: PostHogConfig, isDisabled?: boolean): void;
private _truncateExistingPersonInfoForCookie;
set_disabled(disabled: boolean): void;
set_cross_subdomain(cross_subdomain: boolean): void;
set_secure(secure: boolean): void;
set_event_timer(event_name: string, timestamp: number): void;
remove_event_timer(event_name: string): number;
get_property(prop: string): any;
set_property(prop: string, to: any): void;
private _setProp;
private _deleteProp;
private _markGroupDirty;
private _slotWriteState;
}
//#endregion
//#region lib/src/posthog-featureflags.d.ts
/** Legacy constructor and configuration mapping for the shared flags extension. */
declare class PostHogFeatureFlags$1 extends PostHogFeatureFlags {
readonly name: import("@posthog/browser-common").ExtensionToken<PostHogFeatureFlags$1>;
private readonly _mutableConfigSource;
private readonly _instance;
constructor(instance: PostHog$1);
protected get _crossTabPersistence(): PostHogPersistence | undefined;
updateConfig(config: PostHogConfig, remoteRequestsDisabled: boolean): void;
}
//#endregion
//#region lib/src/posthog-logs.d.ts
/** Legacy configuration, log context, and console script loading. */
declare class PostHogLogs$1 extends PostHogLogs {
private readonly _instance;
readonly name: import("@posthog/browser-common").ExtensionToken<PostHogLogs$1>;
constructor(_instance: PostHog$1);
protected get _isRequestReady(): boolean;
protected _getConsoleLoader(): ConsoleLogsLoader | undefined;
}
//#endregion
//#region lib/src/posthog-metrics.d.ts
/**
* The `posthog.metrics` extension: a statsd-style pre-aggregating client.
*
* ```ts
* posthog.metrics.count('orders_created', 1)
* posthog.metrics.gauge('active_connections', 42)
* posthog.metrics.histogram('api_latency', 187, { unit: 'ms' })
* ```
*
* Aggregation, series identity, and flush policy live in core's
* `PostHogMetrics`; this wrapper adapts it to the browser request layer.
*/
declare class PostHogMetrics implements Extension {
private readonly _instance;
private readonly _logger;
private _core;
private _resolvedFrom;
private _stopNetworkMetrics;
private _disposed;
constructor(_instance: PostHog$1);
initialize(): void;
onConfigChange(): void;
private _getCore;
/** Add to a counter — things that only go up. Value defaults to 1. */
count(name: string, value?: number, options?: CaptureMetricOptions): void;
/** Record the current value of something that goes up and down. */
gauge(name: string, value: number, options?: CaptureMetricOptions): void;
/** Record one observation of a distribution (latency, payload size). */
histogram(name: string, value: number, options?: CaptureMetricOptions): void;
/**
* Sends the aggregated window now. With a transport, the window is
* drained synchronously — bypassing the flush serializer, which could be
* awaiting an in-flight send that will never finish during unload — and
* the payload is handed to that transport in the same tick, so the
* pagehide `sendBeacon` drain survives the page going away. A drained
* window is not retried; the page is gone either way.
*/
flush(transport?: 'XHR' | 'fetch' | 'sendBeacon'): Promise<void>;
reset(): void;
/**
* Stops everything this extension installed: the global `fetch` and
* `XMLHttpRequest` wrappers, and the aggregator's pending window and timer.
* `shutdown()` calls this after its final flush, so a shut down instance
* leaves nothing behind in the page.
*/
dispose(): void;
private _createHost;
private _sendMetricsBatch;
private _metricsUrl;
}
//#endregion
//#region lib/src/extensions/webmcp.d.ts
declare class WebMCP {
private readonly _instance;
private _isPatched;
constructor(_instance: PostHog$1);
initialize(): void;
startIfEnabled(): void;
private _wrapTool;
private _captureToolCall;
}
//#endregion
//#region lib/src/types.d.ts
type PostHogInterface = Omit<PostHog$2, 'config' | 'init' | 'set_config'> & {
config: PostHogConfig;
set_config(config: Partial<PostHogConfig>): void;
};
type PostHogConfig = Omit<PostHogConfig$1, '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$1>;
logs?: ExtensionConstructor<PostHogLogs$1>;
metrics?: ExtensionConstructor<PostHogMetrics>;
webMCP?: ExtensionConstructor<WebMCP>;
};
};
type NextOptions = {
revalidate: false | 0 | number;
tags: string[];
};
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$1) => void;
timeout?: number;
noRetries?: boolean;
disableTransport?: ('XHR' | 'fetch' | 'sendBeacon')[];
compression?: Compression | 'best-available';
/**
* Bypasses asynchronous CompressionStream gzip in favor of synchronous compression.
* Used for immediate requests so compression does not delay dispatch until after a navigation or page unload.
*/
preferSyncCompression?: boolean;
/** 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;
}
interface QueuedRequestWithOptions extends RequestWithOptions {
/** key of queue, e.g. 'sessionRecording' vs 'event' */
batchKey?: string;
/** requests sharing a batchKey are still sent separately when this differs */
batchGroup?: string;
}
interface RetriableRequestWithOptions extends QueuedRequestWithOptions {
retriesPerformedSoFar?: number;
}
/** the config stored in persistence when session recording remote config is received */
type SessionRecordingPersistedConfig = Omit<SessionRecordingRemoteConfig$1, '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$1['networkPayloadCapture'] & {
capturePerformance: RemoteConfig$1['capturePerformance'];
};
canvasRecording: {
enabled: SessionRecordingRemoteConfig$1['recordCanvas'];
fps: SessionRecordingRemoteConfig$1['canvasFps'];
quality: SessionRecordingRemoteConfig$1['canvasQuality'];
};
sampleRate: number | null;
minimumDurationMilliseconds: number | null | undefined;
};
/**
* Outcome of a remote config fetch: the config, or an explicit failure.
* @internal
*/
type RemoteConfigResult = RemoteConfigResult$1;
type SiteAppGlobals = {
event: {
uuid: string;
event: EventName$1;
properties: Properties$1;
timestamp?: Date;
elements_chain?: string;
distinct_id?: string;
};
person: {
properties: Properties$1;
};
groups: Record<string, {
id: string;
type: string;
properties: Properties$1;
}>;
};
type SiteAppLoader = {
id: string;
init: (config: {
posthog: PostHog$1;
callback: (success: boolean) => void;
}) => {
processEvent?: (globals: SiteAppGlobals) => void;
};
};
type SiteApp = {
id: string;
loaded: boolean;
errored: boolean;
processedBuffer: boolean;
processEvent?: (globals: SiteAppGlobals) => void;
};
interface PersistentStore {
_is_supported: () => boolean;
_error: (error: any) => void;
_parse: (name: string) => any;
_get: (name: string) => any;
_rawText?: (name: string) => string;
_set: (name: string, value: any, expire_days?: number | null, cross_subdomain?: boolean, secure?: boolean, debug?: boolean) => boolean;
_remove: (name: string, cross_subdomain?: boolean) => void;
}
type EventHandler = (event: Event) => boolean | void;
type SnippetArrayItem = [method: string, ...args: any[]];
type ErrorEventArgs = [event: string | Event, source?: string | undefined, lineno?: number | undefined, colno?: number | undefined, error?: Error | undefined];
declare const severityLevels: readonly ["fatal", "error", "warning", "log", "info", "debug"];
type SessionStartReason = 'sampling_overridden' | 'recording_initialized' | 'linked_flag_matched' | 'linked_flag_overridden' | typeof SAMPLED | 'session_id_changed' | 'url_trigger_matched' | 'event_trigger_matched';
type OverrideConfig = {
sampling: boolean;
linked_flag: boolean;
url_trigger: boolean;
event_trigger: boolean;
};
//#endregion
//#region lib/src/entrypoints/main.cjs.d.ts
declare const posthog: import('./module').PostHog;
//#endregion
export { type ActionStepStringMatching, type ActionStepType, type AutocaptureCompatibleElement, type AutocaptureConfig, type BasicSurveyQuestion, type BeforeSendFn, type BeforeSendMetricFn, type BootstrapConfig, type BrowserMetricsConfig, type CanvasMaskRegion, type CaptureLogOptions, type CaptureMetricOptions, type CaptureOptions, type CapturePageviewOptions, type CaptureResult, type CapturedNetworkRequest, Compression, type ConfigDefaults, type ConversationsRemoteConfig, ConversationsTraits, ConversationsUnavailableReason, ConversationsWidgetState, DEFAULT_PRODUCT_TOUR_APPEARANCE, type DeadClickCandidate, type DeadClicksAutoCaptureConfig, type DisplaySurveyOptions, type DisplaySurveyPopoverOptions, DisplaySurveyType, type DomAutocaptureEvents, type EarlyAccessFeature, type EarlyAccessFeatureCallback, type EarlyAccessFeatureResponse, type EarlyAccessFeatureStage, ErrorEventArgs, type ErrorTrackingOptions, type ErrorTrackingSuppressionRule, type ErrorTrackingSuppressionRuleValue, type EvaluationReason, EventHandler, type EventName, type ExceptionAutoCaptureConfig, type ExceptionStepsConfig, type ExternalIntegrationKind, type FeatureFlagDetail, type FeatureFlagMetadata, type FeatureFlagOptions, type FeatureFlagOverrideOptions, type FeatureFlagOverrides, type FeatureFlagPayloadOverrides, type FeatureFlagResult, type FeatureFlagsCallback, type FlagVariant, type FlagsResponse, GetMessagesResponse, GetTicketsOptions, GetTicketsResponse, type Headers, type HeatmapConfig, type InitiatorType, type IsFeatureEnabledOptions, JSONContent, type JsonRecord, type JsonType, type KnownEventName, type KnownUnsafeEditableEvent, type LinkSurveyQuestion, type LogAttributeValue, type LogAttributes, type LogSdkContext, type LogSeverityLevel, type Logger, MarkAsReadResponse, type MaskInputOptions, Message, MessageAuthorType, type MetricAttributeValue, type MetricAttributes, type MetricSample, type MetricType, type MetricsConfig, type MultipleSurveyQuestion, type NetworkMetricsConfig, type NetworkMetricsRequest, type NetworkMetricsResponse, type NetworkRecordOptions, type NetworkRequest, type OtlpAnyValue, type OtlpKeyValue, type OtlpLogRecord, type OtlpLogsPayload, type OtlpMetricsPayload, type OtlpSeverityEntry, type OtlpSeverityText, OverrideConfig, type OverrideFeatureFlagsOptions, type PerformanceCaptureConfig, PersistentStore, PostHog, PostHogConfig, PostHogInterface, ProductTour, ProductTourAppearance, ProductTourBannerConfig, ProductTourButtonAction, ProductTourCallback, ProductTourConditions, ProductTourDismissReason, ProductTourDisplayFrequency, ProductTourEventName, ProductTourEventProperties, ProductTourRenderReason, ProductTourSelectorError, ProductTourStep, ProductTourStepButton, ProductTourStepButtons, ProductTourStepTranslation, ProductTourStepType, ProductTourSurveyQuestion, ProductTourSurveyQuestionType, ProductTourType, ProductTourWaitPeriod, type Properties, type Property, type PropertyFilters, type PropertyMatchType, type PropertyOperator, QueuedRequestWithOptions, type RageclickConfig, type RatingSurveyQuestion, type RemoteConfig, type RemoteConfigFeatureFlagCallback, RemoteConfigResult, type RequestCallback, type RequestQueueConfig, type RequestResponse, RequestRestoreLinkPayload, RequestRestoreLinkResponse, RequestWithOptions, type ResetOptions, RestoreFromTokenPayload, RestoreFromTokenResponse, RestoreFromTokenStatus, RetriableRequestWithOptions, type SegmentEnrichmentFilterFn, type SegmentIntegrationConfig, SendMessagePayload, SendMessageResponse, SessionContext, type SessionIdChangedCallback, type SessionRecordingCanvasOptions, type SessionRecordingEventTrigger, type SessionRecordingOptions, SessionRecordingPersistedConfig, type SessionRecordingRemoteConfig, type SessionRecordingSamplingConfig, type SessionRecordingTriggerGroup, type SessionRecordingTriggerPropertyFilter, type SessionRecordingUrlTrigger, SessionStartReason, type SeverityLevel, ShowTourOptions, SiteApp, SiteAppGlobals, SiteAppLoader, type SlimDOMOptions, SnippetArrayItem, type SupportedWebVitalsMetrics, type Survey, type SurveyActionType, type SurveyAppearance, type SurveyCallback, type SurveyConfig, type SurveyElement, SurveyEventName, SurveyEventProperties, SurveyEventType, type SurveyEventWithFilters, SurveyPosition, type SurveyQuestion, SurveyQuestionBranchingType, type SurveyQuestionDescriptionContentType, SurveyQuestionType, type SurveyRenderReason, type SurveyResponseValue, SurveySchedule, SurveyTabPosition, SurveyType, SurveyWidgetType, type SurveyWithTypeAndAppearance, Ticket, TicketStatus, TipTapDoc, TipTapMark, TipTapNode, type ToolbarParams, type ToolbarSource, type ToolbarUserIntent, type ToolbarVersion, UserProvidedTraits, type WebMCPCaptureConfig, type WidgetPosition, posthog as default, posthog, severityLevels };