posthog-js-lite 3.5.1 → 4.0.0

package/lib/index.d.ts

@@ -50,8 +50,8 @@ type PostHogCoreOptions = {
     remoteConfigRequestTimeoutMs?: number;
     /** For Session Analysis how long before we expire a session (defaults to 30 mins) */
     sessionExpirationTimeSeconds?: number;
-    /** Whether to post events to PostHog in JSON or compressed format. Defaults to 'json' */
-    captureMode?: 'json' | 'form';
+    /** Whether to disable GZIP compression */
+    disableCompression?: boolean;
     disableGeoip?: boolean;
     /** Special flag to indicate ingested data is for a historical migration. */
     historicalMigration?: boolean;
@@ -70,6 +70,7 @@ declare enum PostHogPersistedProperty {
     Queue = "queue",
     OptedOut = "opted_out",
     SessionId = "session_id",
+    SessionStartTimestamp = "session_start_timestamp",
     SessionLastTimestamp = "session_timestamp",
     PersonProperties = "person_properties",
     GroupProperties = "group_properties",
@@ -89,7 +90,7 @@ type PostHogFetchOptions = {
     headers: {
         [key: string]: string;
     };
-    body?: string;
+    body?: string | Blob;
     signal?: AbortSignal;
 };
 type PostHogCaptureOptions = {
@@ -105,7 +106,10 @@ type PostHogFetchResponse = {
     json: () => Promise<any>;
 };
 type PostHogEventProperties = {
-    [key: string]: any;
+    [key: string]: JsonType;
+};
+type PostHogGroupProperties = {
+    [type: string]: string | number;
 };
 type PostHogAutocaptureElement = {
     $el_text?: string;
@@ -114,13 +118,19 @@ type PostHogAutocaptureElement = {
     nth_child?: number;
     nth_of_type?: number;
     order?: number;
-} & {
-    [key: string]: any;
-};
+} & PostHogEventProperties;
+declare enum Compression {
+    GZipJS = "gzip-js",
+    Base64 = "base64"
+}
 type PostHogRemoteConfig = {
     sessionRecording?: boolean | {
         [key: string]: JsonType;
     };
+    /**
+     * Supported compression algorithms
+     */
+    supportedCompression?: Compression[];
     /**
      * Whether surveys are enabled
      */
@@ -182,7 +192,7 @@ type PartialWithRequired<T, K extends keyof T> = {
 type PostHogFeatureFlagDetails = PartialWithRequired<PostHogDecideResponse, 'flags' | 'featureFlags' | 'featureFlagPayloads' | 'requestId'>;
 type JsonType = string | number | boolean | null | {
     [key: string]: JsonType;
-} | Array<JsonType>;
+} | Array<JsonType> | JsonType[];
 type FeatureFlagDetail = {
     key: string;
     enabled: boolean;
@@ -366,8 +376,6 @@ declare enum ActionStepStringMatching {
 type ActionStepType = {
     event?: string;
     selector?: string;
-    /** @deprecated Only `selector` should be used now. */
-    tag_name?: string;
     text?: string;
     /** @default StringMatching.Exact */
     text_matching?: ActionStepStringMatching;
@@ -408,11 +416,11 @@ declare abstract class PostHogCoreStateless {
     private requestTimeout;
     private featureFlagsRequestTimeoutMs;
     private remoteConfigRequestTimeoutMs;
-    private captureMode;
     private removeDebugCallback?;
     private disableGeoip;
     private historicalMigration;
     protected disabled: boolean;
+    protected disableCompression: boolean;
     private defaultOptIn;
     private pendingPromises;
     protected _events: SimpleEventEmitter;
@@ -430,7 +438,7 @@ declare abstract class PostHogCoreStateless {
     constructor(apiKey: string, options?: PostHogCoreOptions);
     protected logMsgIfDebug(fn: () => void): void;
     protected wrap(fn: () => void): void;
-    protected getCommonEventProperties(): any;
+    protected getCommonEventProperties(): PostHogEventProperties;
     get optedOut(): boolean;
     optIn(): Promise<void>;
     optOut(): Promise<void>;
@@ -445,18 +453,10 @@ declare abstract class PostHogCoreStateless {
      ***/
     protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     protected identifyStatelessImmediate(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
-    protected captureStateless(distinctId: string, event: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): void;
-    protected captureStatelessImmediate(distinctId: string, event: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): Promise<void>;
-    protected aliasStateless(alias: string, distinctId: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): void;
-    protected aliasStatelessImmediate(alias: string, distinctId: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): Promise<void>;
+    protected captureStateless(distinctId: string, event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    protected captureStatelessImmediate(distinctId: string, event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
+    protected aliasStateless(alias: string, distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    protected aliasStatelessImmediate(alias: string, distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
     /***
      *** GROUPS
      ***/
@@ -497,9 +497,7 @@ declare abstract class PostHogCoreStateless {
     private _props;
     protected get props(): PostHogEventProperties;
     protected set props(val: PostHogEventProperties | undefined);
-    register(properties: {
-        [key: string]: any;
-    }): Promise<void>;
+    register(properties: PostHogEventProperties): Promise<void>;
     unregister(property: string): Promise<void>;
     /***
      *** QUEUEING AND FLUSHING
@@ -513,7 +511,29 @@ declare abstract class PostHogCoreStateless {
      * Avoids unnecessary promise errors
      */
     private flushBackground;
-    flush(): Promise<any[]>;
+    /**
+     * Flushes the queue
+     *
+     * This function will return a promise that will resolve when the flush is complete,
+     * or reject if there was an error (for example if the server or network is down).
+     *
+     * If there is already a flush in progress, this function will wait for that flush to complete.
+     *
+     * It's recommended to do error handling in the callback of the promise.
+     *
+     * @example
+     * posthog.flush().then(() => {
+     *   console.log('Flush complete')
+     * }).catch((err) => {
+     *   console.error('Flush failed', err)
+     * })
+     *
+     *
+     * @throws PostHogFetchHttpError
+     * @throws PostHogFetchNetworkError
+     * @throws Error
+     */
+    flush(): Promise<void>;
     protected getCustomHeaders(): {
         [key: string]: string;
     };
@@ -532,13 +552,14 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     private flagCallReported;
     protected _decideResponsePromise?: Promise<PostHogDecideResponse | undefined>;
     protected _sessionExpirationTimeSeconds: number;
+    private _sessionMaxLengthSeconds;
     protected sessionProps: PostHogEventProperties;
     constructor(apiKey: string, options?: PostHogCoreOptions);
     protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
     private clearProps;
     on(event: string, cb: (...args: any[]) => void): () => void;
     reset(propertiesToKeep?: PostHogPersistedProperty[]): void;
-    protected getCommonEventProperties(): any;
+    protected getCommonEventProperties(): PostHogEventProperties;
     private enrichProperties;
     /**
      * * @returns {string} The stored session ID for the current session. This may be an empty string if the client is not yet fully initialized.
@@ -553,25 +574,19 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
      * * @returns {string} The stored distinct ID. This may be an empty string if the client is not yet fully initialized.
      */
     getDistinctId(): string;
-    registerForSession(properties: {
-        [key: string]: any;
-    }): void;
+    registerForSession(properties: PostHogEventProperties): void;
     unregisterForSession(property: string): void;
     /***
      *** TRACKING
      ***/
     identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
-    capture(event: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): void;
+    capture(event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     alias(alias: string): void;
     autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
-    groups(groups: {
-        [type: string]: string | number;
-    }): void;
+    groups(groups: PostHogGroupProperties): void;
     group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
@@ -581,18 +596,10 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
         [type: string]: string;
     }): void;
     resetPersonPropertiesForFlags(): void;
-    /** @deprecated - Renamed to setPersonPropertiesForFlags */
-    personProperties(properties: {
-        [type: string]: string;
-    }): void;
     setGroupPropertiesForFlags(properties: {
         [type: string]: Record<string, string>;
     }): void;
     resetGroupPropertiesForFlags(): void;
-    /** @deprecated - Renamed to setGroupPropertiesForFlags */
-    groupProperties(properties: {
-        [type: string]: Record<string, string>;
-    }): void;
     private remoteConfigAsync;
     /***
      *** FEATURE FLAGS
@@ -603,7 +610,7 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     private _decideAsync;
     private setKnownFeatureFlagDetails;
     private getKnownFeatureFlagDetails;
-    private getKnownFeatureFlags;
+    protected getKnownFeatureFlags(): PostHogDecideResponse['featureFlags'] | undefined;
     private getKnownFeatureFlagPayloads;
     private getBootstrappedFeatureFlagDetails;
     private setBootstrappedFeatureFlagDetails;
@@ -628,9 +635,7 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     /***
      *** ERROR TRACKING
      ***/
-    captureException(error: unknown, additionalProperties?: {
-        [key: string]: any;
-    }): void;
+    captureException(error: unknown, additionalProperties?: PostHogEventProperties): void;
     /**
      * Capture written user feedback for a LLM trace. Numeric values are converted to strings.
      * @param traceId The trace ID to capture feedback for.
@@ -666,7 +671,7 @@ declare class PostHog extends PostHogCore {
     getLibraryId(): string;
     getLibraryVersion(): string;
     getCustomUserAgent(): void;
-    getCommonEventProperties(): any;
+    getCommonEventProperties(): PostHogEventProperties;
     private setupHistoryEventTracking;
     private captureNavigationEvent;
 }