posthog-node 3.6.2 → 4.0.0-beta.1

package/lib/index.d.ts

@@ -1,21 +1,37 @@
 /// <reference types="node" />
-declare type PosthogCoreOptions = {
+declare type PostHogCoreOptions = {
+    /** PostHog API host, usually 'https://app.posthog.com' or 'https://eu.posthog.com' */
     host?: string;
+    /** The number of events to queue before sending to PostHog (flushing) */
     flushAt?: number;
+    /** The interval in milliseconds between periodic flushes */
     flushInterval?: number;
-    enable?: boolean;
+    /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */
+    disabled?: boolean;
+    /** If set to false the SDK will not track until the `optIn` function is called. */
+    defaultOptIn?: boolean;
+    /** Whether to track that `getFeatureFlag` was called (used by Experiments) */
     sendFeatureFlagEvent?: boolean;
+    /** Whether to load feature flags when initialized or not */
     preloadFeatureFlags?: boolean;
+    /** Option to bootstrap the library with given distinctId and feature flags */
     bootstrap?: {
         distinctId?: string;
         isIdentifiedId?: boolean;
         featureFlags?: Record<string, boolean | string>;
         featureFlagPayloads?: Record<string, JsonType>;
     };
+    /** How many times we will retry HTTP requests. Defaults to 3. */
     fetchRetryCount?: number;
+    /** The delay between HTTP request retries, Defaults to 3 seconds. */
     fetchRetryDelay?: number;
+    /** Timeout in milliseconds for any calls. Defaults to 10 seconds. */
     requestTimeout?: number;
+    /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */
+    featureFlagsRequestTimeoutMs?: 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 */
     captureMode?: 'json' | 'form';
     disableGeoip?: boolean;
 };
@@ -79,7 +95,7 @@ declare type PostHogDecideResponse = {
     errorsWhileComputingFlags: boolean;
     sessionRecording: boolean;
 };
-declare type PosthogFlagsAndPayloadsResponse = {
+declare type PostHogFlagsAndPayloadsResponse = {
     featureFlags: PostHogDecideResponse['featureFlags'];
     featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];
 };
@@ -88,9 +104,9 @@ declare type JsonType = string | number | boolean | null | {
 } | Array<JsonType>;
 
 interface RetriableOptions {
-    retryCount?: number;
-    retryDelay?: number;
-    retryCheck?: (err: any) => boolean;
+    retryCount: number;
+    retryDelay: number;
+    retryCheck: (err: any) => boolean;
 }
 
 declare class SimpleEventEmitter {
@@ -108,44 +124,49 @@ declare abstract class PostHogCoreStateless {
     private flushAt;
     private flushInterval;
     private requestTimeout;
+    private featureFlagsRequestTimeoutMs;
     private captureMode;
     private removeDebugCallback?;
-    private debugMode;
     private disableGeoip;
-    private _optoutOverride;
+    disabled: boolean;
+    private defaultOptIn;
     private pendingPromises;
     protected _events: SimpleEventEmitter;
     protected _flushTimer?: any;
     protected _retryOptions: RetriableOptions;
+    protected _initPromise: Promise<void>;
+    protected _isInitialized: boolean;
     abstract fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse>;
     abstract getLibraryId(): string;
     abstract getLibraryVersion(): string;
     abstract getCustomUserAgent(): string | void;
     abstract getPersistedProperty<T>(key: PostHogPersistedProperty): T | undefined;
     abstract setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected wrap(fn: () => void): void;
     protected getCommonEventProperties(): any;
     get optedOut(): boolean;
-    optIn(): void;
-    optOut(): void;
+    optIn(): Promise<void>;
+    optOut(): Promise<void>;
     on(event: string, cb: (...args: any[]) => void): () => void;
     debug(enabled?: boolean): void;
+    get isDebug(): boolean;
     private buildPayload;
     protected addPendingPromise(promise: Promise<any>): void;
     /***
      *** TRACKING
      ***/
-    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
-    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): this;
+    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): void;
     /***
      *** FEATURE FLAGS
      ***/
@@ -166,8 +187,8 @@ declare abstract class PostHogCoreStateless {
     flushAsync(): Promise<any>;
     flush(callback?: (err?: any, data?: any) => void): void;
     private fetchWithRetry;
-    shutdownAsync(): Promise<void>;
-    shutdown(): void;
+    shutdownAsync(shutdownTimeoutMs?: number): Promise<void>;
+    shutdown(shutdownTimeoutMs?: number): void;
 }
 
 interface IdentifyMessage {
@@ -305,15 +326,16 @@ declare type PostHogNodeV1 = {
     /**
      * @description Flushes the events still in the queue and clears the feature flags poller to allow for
      * a clean shutdown.
+     *
+     * @param shutdownTimeoutMs The shutdown timeout, in milliseconds. Defaults to 30000 (30s).
      */
-    shutdown(): void;
+    shutdown(shutdownTimeoutMs?: number): void;
 };
 
-declare type PostHogOptions = PosthogCoreOptions & {
+declare type PostHogOptions = PostHogCoreOptions & {
     persistence?: 'memory';
     personalApiKey?: string;
     featureFlagsPollingInterval?: number;
-    requestTimeout?: number;
     maxCacheSize?: number;
     fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
 };
@@ -330,8 +352,8 @@ declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     getLibraryId(): string;
     getLibraryVersion(): string;
     getCustomUserAgent(): string;
-    enable(): void;
-    disable(): void;
+    enable(): Promise<void>;
+    disable(): Promise<void>;
     debug(enabled?: boolean): void;
     capture({ distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip, uuid, }: EventMessage): void;
     identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void;
@@ -377,11 +399,11 @@ declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
         disableGeoip?: boolean;
-    }): Promise<PosthogFlagsAndPayloadsResponse>;
+    }): Promise<PostHogFlagsAndPayloadsResponse>;
     groupIdentify({ groupType, groupKey, properties, distinctId, disableGeoip }: GroupIdentifyMessage): void;
     reloadFeatureFlags(): Promise<void>;
-    shutdown(): void;
-    shutdownAsync(): Promise<void>;
+    shutdown(shutdownTimeoutMs?: number): void;
+    shutdownAsync(shutdownTimeoutMs?: number): Promise<void>;
     private addLocalPersonAndGroupProperties;
 }