import type { Logger } from '@posthog/core' import type { Properties } from '@posthog/types' import type { Compression } from './types/compression' import type { Disposable } from './disposable' import type { Extension } from './extension' import type { KeyValueStore } from './persistence' import type { ExtensionToken } from './token' import type { Listener } from './pubsub' import type { RemoteConfigResult } from './types/remote-config' /** Recursively marks object properties as readonly while preserving callable values. */ export type DeepReadonly = T extends (...args: never[]) => unknown ? T : T extends object ? { readonly [K in keyof T]: DeepReadonly } : T /** The current session, stamped on events to tie them to a session and a browser tab. */ export interface SessionContext { /** The stable session identifier attached to events captured during this session. */ readonly sessionId: string /** The logical browser tab/window identifier attached alongside the session id. */ readonly windowId: string /** When the session started, as a Unix timestamp in milliseconds. */ readonly sessionStartTimestamp: number /** Most recent session activity, as a Unix timestamp in milliseconds. */ readonly lastActivityTimestamp: number } /** A captured event, as observed by `onEvent`. */ export interface CapturedEventInfo { /** The finalized captured event name. */ readonly event: string /** The final event properties after client defaults and dynamic properties are applied. */ readonly properties: DeepReadonly> } /** Per-call capture overrides, mirroring the client's public capture options. */ export interface CaptureOptions { /** Send immediately without batching, using best-effort unload-safe delivery. */ delivery?: 'unload' /** Override the event timestamp sent to PostHog. UTC is preferred; non-UTC input is converted to UTC. */ timestamp?: Date /** Override the event UUID used for de-duplication. */ uuid?: string /** Person properties to set, emitted as `$set`. */ set?: Record /** Person properties to set if unset, emitted as `$set_once`. */ setOnce?: Record } /** A minimal response from {@link Client.sendRequest}. */ export interface ApiResponse { /** The HTTP status code returned by the transport, or a client-defined best-effort status for sendBeacon sends. */ statusCode: number /** The response body parsed as JSON when available. */ json?: unknown /** The response body as text when available. */ text?: string /** The transport error when the request failed before receiving an HTTP response. */ error?: unknown } /** Configured host used to resolve a relative request path. */ export type RequestTarget = 'api' | 'flags' | 'assets' /** Browser transport requested for a send. */ export type RequestTransport = 'XHR' | 'fetch' | 'sendBeacon' /** Options for sending a request through {@link Client.sendRequest}. */ export interface SendRequestInit { /** Configured host to send through; defaults to the regular API host. */ target?: RequestTarget /** HTTP method to use; the host transport's default applies when omitted. */ method?: 'GET' | 'POST' /** JSON-serialized by the client. */ body?: unknown /** Query string parameters appended to the request URL. */ query?: Record /** Additional headers merged with the host SDK's configured request headers. */ headers?: Record /** * Browser transport to prefer. Fetch is the normal runtime transport. Use `sendBeacon` only for an eligible * best-effort teardown POST. Its response confirms browser handoff, not delivery. */ transport?: RequestTransport /** Abort the request if it does not complete within this many milliseconds. */ timeoutMs?: number /** Compression used by the browser transport. */ compression?: Compression | 'best-available' /** Where POST requests add `sent_at`. For GET, `query` adds the cache-busting `_` parameter and `body` has no effect. */ sentAt?: 'body' | 'query' } /** * The host SDK surface handed to an extension in `setup`. A conforming host * provides it as an adapter over its own analytics, transport, persistence, * event, and remote-config internals. */ export interface Client { /** The id events are currently attributed to. */ readonly distinctId: string /** The anonymous device id carried across identify calls. */ readonly anonymousId: string /** The actual persisted device id, absent in cookieless contexts. */ readonly deviceId: string | undefined /** Live host SDK metadata. */ readonly library: { readonly name: string; readonly version: string } /** Initial person properties used for feature evaluation. */ readonly initialPersonProperties: DeepReadonly> /** Active group memberships attached to events as `$groups`. */ readonly groups: DeepReadonly> /** The current session, if one exists. Reading it need not create one. */ readonly session: SessionContext | undefined /** Effective consent opt-out state. Cookieless capture may still be permitted while opted out. */ readonly isOptedOut: boolean /** Whether the host currently permits data capture. */ readonly canCapture: boolean /** Whether the client rate limit drops an event captured now. Reading it must not use a token. */ readonly isRateLimited?: boolean /** * Synchronously admits an analytics event to the client's normal pipeline. * Returns `false` when the client rate limit dropped the event, so the caller can send it again later. * An event that is dropped for another reason, for example by `before_send`, returns `true`. */ capture(event: string, properties?: Properties | null, options?: CaptureOptions): boolean /** Registers a synchronous producer of properties merged into every captured event. */ registerDynamicEventProperties(producer: () => Record): Disposable /** Returns the extension registered under a typed stable name, or `undefined` when it is not installed. */ getExtension(token: ExtensionToken): T | undefined /** Returns the extension registered under a stable name, or `undefined` when it is not installed. */ getExtension(name: string): T | undefined /** Observes session IDs through the host's session notifications, without creating a session. May replay an existing session on subscription. */ readonly onSession: Listener /** Fires for every captured event through a deeply readonly view. */ readonly onEvent: Listener /** Replays the latest available remote-config outcome and fires subsequent outcomes when the host makes them available. */ readonly onRemoteConfig: Listener> /** Public project token used to authenticate endpoint-specific requests. */ readonly projectToken: string /** Sends a request through the host SDK's transport. */ sendRequest(path: string, init?: SendRequestInit): Promise /** Initializable, synchronously buffered key-value storage backed by the host client's persistence. */ readonly kv: KeyValueStore /** Logger that follows the host client's debug/noise policy. */ readonly logger: Logger }