posthog-node 2.0.0-alpha9 → 2.1.0

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 declare type PosthogCoreOptions = {
     host?: string;
     flushAt?: number;
@@ -9,6 +10,21 @@ declare type PosthogCoreOptions = {
     fetchRetryDelay?: number;
     sessionExpirationTimeSeconds?: number;
     captureMode?: 'json' | 'form';
+};
+declare type PostHogFetchOptions = {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    mode?: 'no-cors';
+    credentials?: 'omit';
+    headers: {
+        [key: string]: string;
+    };
+    body?: string;
+    signal?: AbortSignal;
+};
+declare type PostHogFetchResponse = {
+    status: number;
+    text: () => Promise<string>;
+    json: () => Promise<any>;
 };
 
 interface IdentifyMessageV1 {
@@ -35,7 +51,7 @@ declare type PostHogNodeV1 = {
      * @param event We recommend using [verb] [noun], like movie played or movie updated to easily identify what your events mean later on.
      * @param properties OPTIONAL | which can be a object with any information you'd like to add
      * @param groups OPTIONAL | object of what groups are related to this event, example: { company: 'id:5' }. Can be used to analyze companies instead of users.
-     * @param sendFeatureFlags OPTIONAL | Used with experiments
+     * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
      */
     capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessageV1): void;
     /**
@@ -66,14 +82,47 @@ declare type PostHogNodeV1 = {
      * allow you to safely deploy and roll back new features. Once you've created a feature flag in PostHog,
      * you can use this method to check if the flag is on for a given user, allowing you to create logic to turn
      * features on and off for different user groups or individual users.
-     * IMPORTANT: To use this method, you need to specify `personalApiKey` in your config! More info: https://posthog.com/docs/api/overview
      * @param key the unique key of your feature flag
      * @param distinctId the current unique id
-     * @param defaultResult optional - default value to be returned if the feature flag is not on for the user
-     * @param groups optional - what groups are currently active (group analytics)
+     * @param options: dict with optional parameters below
+     * @param groups optional - what groups are currently active (group analytics). Required if the flag depends on groups.
+     * @param personProperties optional - what person properties are known. Used to compute flags locally, if personalApiKey is present.
+     * @param groupProperties optional - what group properties are known. Used to compute flags locally, if personalApiKey is present.
+     * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
+     * @param sendFeatureFlagEvents optional - whether to send feature flag events. Used for Experiments. Defaults to true.
+     *
+     * @returns true if the flag is on, false if the flag is off, undefined if there was an error.
      */
-    isFeatureEnabled(key: string, distinctId: string, defaultResult?: boolean, groups?: Record<string, string>): Promise<boolean>;
-    getFeatureFlag(key: string, distinctId: string, groups?: Record<string, string>): Promise<string | boolean | undefined>;
+    isFeatureEnabled(key: string, distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+    }): Promise<boolean | undefined>;
+    /**
+     * @description PostHog feature flags (https://posthog.com/docs/features/feature-flags)
+     * allow you to safely deploy and roll back new features. Once you've created a feature flag in PostHog,
+     * you can use this method to check if the flag is on for a given user, allowing you to create logic to turn
+     * features on and off for different user groups or individual users.
+     * @param key the unique key of your feature flag
+     * @param distinctId the current unique id
+     * @param options: dict with optional parameters below
+     * @param groups optional - what groups are currently active (group analytics). Required if the flag depends on groups.
+     * @param personProperties optional - what person properties are known. Used to compute flags locally, if personalApiKey is present.
+     * @param groupProperties optional - what group properties are known. Used to compute flags locally, if personalApiKey is present.
+     * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
+     * @param sendFeatureFlagEvents optional - whether to send feature flag events. Used for Experiments. Defaults to true.
+     *
+     * @returns true or string(for multivariates) if the flag is on, false if the flag is off, undefined if there was an error.
+     */
+    getFeatureFlag(key: string, distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+    }): Promise<string | boolean | undefined>;
     /**
      * @description Sets a groups properties, which allows asking questions like "Who are the most active companies"
      * using my product in PostHog.
@@ -97,26 +146,53 @@ declare type PostHogNodeV1 = {
 
 declare type PostHogOptions = PosthogCoreOptions & {
     persistence?: 'memory';
+    personalApiKey?: string;
+    featureFlagsPollingInterval?: number;
+    requestTimeout?: number;
+    maxCacheSize?: number;
+    fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
 };
-declare class PostHogGlobal implements PostHogNodeV1 {
+declare class PostHog implements PostHogNodeV1 {
     private _sharedClient;
+    private featureFlagsPoller?;
+    private maxCacheSize;
+    distinctIdHasSentFlagCalls: Record<string, string[]>;
     constructor(apiKey: string, options?: PostHogOptions);
     private reInit;
     enable(): void;
     disable(): void;
-    capture({ distinctId, event, properties, groups }: EventMessageV1): void;
+    capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessageV1): void;
     identify({ distinctId, properties }: IdentifyMessageV1): void;
     alias(data: {
         distinctId: string;
         alias: string;
     }): void;
-    getFeatureFlag(key: string, distinctId: string, groups?: Record<string, string> | undefined): Promise<string | boolean | undefined>;
-    isFeatureEnabled(key: string, distinctId: string, defaultResult?: boolean | undefined, groups?: Record<string, string> | undefined): Promise<boolean>;
+    getFeatureFlag(key: string, distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+    }): Promise<string | boolean | undefined>;
+    isFeatureEnabled(key: string, distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+    }): Promise<boolean | undefined>;
+    getAllFlags(distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+    }): Promise<Record<string, string | boolean>>;
     groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void;
     reloadFeatureFlags(): Promise<void>;
+    flush(): void;
     shutdown(): void;
     shutdownAsync(): Promise<void>;
     debug(enabled?: boolean): void;
 }
 
-export { PostHogGlobal, PostHogOptions, PostHogGlobal as default };
+export { PostHog, PostHogOptions };