posthog-node 4.10.2 → 4.11.1

package/lib/index.d.ts

@@ -245,7 +245,7 @@ type PostHogCoreOptions = {
     bootstrap?: {
         distinctId?: string;
         isIdentifiedId?: boolean;
-        featureFlags?: Record<string, boolean | string>;
+        featureFlags?: Record<string, FeatureFlagValue>;
         featureFlagPayloads?: Record<string, JsonType>;
     };
     /** How many times we will retry HTTP requests. Defaults to 3. */
@@ -270,8 +270,10 @@ declare enum PostHogPersistedProperty {
     AnonymousId = "anonymous_id",
     DistinctId = "distinct_id",
     Props = "props",
+    FeatureFlagDetails = "feature_flag_details",
     FeatureFlags = "feature_flags",
     FeatureFlagPayloads = "feature_flag_payloads",
+    BootstrapFeatureFlagDetails = "bootstrap_feature_flag_details",
     BootstrapFeatureFlags = "bootstrap_feature_flags",
     BootstrapFeatureFlagPayloads = "bootstrap_feature_flag_payloads",
     OverrideFeatureFlags = "override_feature_flags",
@@ -328,13 +330,17 @@ interface PostHogRemoteConfig {
      */
     hasFeatureFlags?: boolean;
 }
+type FeatureFlagValue = string | boolean;
 interface PostHogDecideResponse extends Omit<PostHogRemoteConfig, 'surveys' | 'hasFeatureFlags'> {
     featureFlags: {
-        [key: string]: string | boolean;
+        [key: string]: FeatureFlagValue;
     };
     featureFlagPayloads: {
         [key: string]: JsonType;
     };
+    flags: {
+        [key: string]: FeatureFlagDetail;
+    };
     errorsWhileComputingFlags: boolean;
     sessionRecording?: boolean | {
         [key: string]: JsonType;
@@ -342,13 +348,63 @@ interface PostHogDecideResponse extends Omit<PostHogRemoteConfig, 'surveys' | 'h
     quotaLimited?: string[];
     requestId?: string;
 }
-type PostHogFlagsAndPayloadsResponse = {
-    featureFlags: PostHogDecideResponse['featureFlags'];
-    featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];
+/**
+ * Creates a type with all properties of T, but makes only K properties required while the rest remain optional.
+ *
+ * @template T - The base type containing all properties
+ * @template K - Union type of keys from T that should be required
+ *
+ * @example
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email?: string;
+ *   age?: number;
+ * }
+ *
+ * // Makes 'id' and 'name' required, but 'email' and 'age' optional
+ * type RequiredUser = PartialWithRequired<User, 'id' | 'name'>;
+ *
+ * const user: RequiredUser = {
+ *   id: 1,      // Must be provided
+ *   name: "John" // Must be provided
+ *   // email and age are optional
+ * };
+ */
+type PartialWithRequired<T, K extends keyof T> = {
+    [P in K]: T[P];
+} & {
+    [P in Exclude<keyof T, K>]?: T[P];
 };
+/**
+ * These are the fields we care about from PostHogDecideResponse for feature flags.
+ */
+type PostHogFeatureFlagDetails = PartialWithRequired<PostHogDecideResponse, 'flags' | 'featureFlags' | 'featureFlagPayloads' | 'requestId'>;
+/**
+ * Models legacy flags and payloads return type for many public methods.
+ */
+type PostHogFlagsAndPayloadsResponse = Partial<Pick<PostHogDecideResponse, 'featureFlags' | 'featureFlagPayloads'>>;
 type JsonType = string | number | boolean | null | {
     [key: string]: JsonType;
-} | Array<JsonType>;
+} | Array<JsonType>;
+type FeatureFlagDetail = {
+    key: string;
+    enabled: boolean;
+    variant: string | undefined;
+    reason: EvaluationReason | undefined;
+    metadata: FeatureFlagMetadata | undefined;
+};
+type FeatureFlagMetadata = {
+    id: number | undefined;
+    version: number | undefined;
+    description: string | undefined;
+    payload: string | undefined;
+};
+type EvaluationReason = {
+    code: string | undefined;
+    condition_index: number | undefined;
+    description: string | undefined;
+};
 
 interface RetriableOptions {
     retryCount: number;
@@ -430,12 +486,15 @@ declare abstract class PostHogCoreStateless {
      ***/
     protected getDecide(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, extraPayload?: Record<string, any>): Promise<PostHogDecideResponse | undefined>;
     protected getFeatureFlagStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<{
-        response: boolean | string | undefined;
+        response: FeatureFlagValue | undefined;
         requestId: string | undefined;
     }>;
+    protected getFeatureFlagDetailStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<{
+        response: FeatureFlagDetail | undefined;
+        requestId: string | undefined;
+    } | undefined>;
     protected getFeatureFlagPayloadStateless(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean): Promise<JsonType | undefined>;
     protected getFeatureFlagPayloadsStateless(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean, flagKeysToEvaluate?: string[]): Promise<PostHogDecideResponse['featureFlagPayloads'] | undefined>;
-    protected _parsePayload(response: any): any;
     protected getFeatureFlagsStateless(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean, flagKeysToEvaluate?: string[]): Promise<{
         flags: PostHogDecideResponse['featureFlags'] | undefined;
         payloads: PostHogDecideResponse['featureFlagPayloads'] | undefined;
@@ -446,6 +505,7 @@ declare abstract class PostHogCoreStateless {
         payloads: PostHogDecideResponse['featureFlagPayloads'] | undefined;
         requestId: PostHogDecideResponse['requestId'] | undefined;
     }>;
+    protected getFeatureFlagDetailsStateless(distinctId: string, groups?: Record<string, string | number>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>, disableGeoip?: boolean, flagKeysToEvaluate?: string[]): Promise<PostHogFeatureFlagDetails | undefined>;
     /***
      *** SURVEYS
      ***/
@@ -569,7 +629,7 @@ type PostHogNodeV1 = {
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
-    }): Promise<string | boolean | undefined>;
+    }): Promise<FeatureFlagValue | undefined>;
     /**
      * @description Retrieves payload associated with the specified flag and matched value that is passed in.
      *
@@ -596,7 +656,7 @@ type PostHogNodeV1 = {
      *
      * @returns payload of a json type object
      */
-    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: FeatureFlagValue, options?: {
         onlyEvaluateLocally?: boolean;
     }): Promise<JsonType | undefined>;
     /**
@@ -687,8 +747,8 @@ declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
         disableGeoip?: boolean;
-    }): Promise<string | boolean | undefined>;
-    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
+    }): Promise<FeatureFlagValue | undefined>;
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: FeatureFlagValue, options?: {
         groups?: Record<string, string>;
         personProperties?: Record<string, string>;
         groupProperties?: Record<string, Record<string, string>>;
@@ -711,7 +771,7 @@ declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
         disableGeoip?: boolean;
-    }): Promise<Record<string, string | boolean>>;
+    }): Promise<Record<string, FeatureFlagValue>>;
     getAllFlagsAndPayloads(distinctId: string, options?: {
         groups?: Record<string, string>;
         personProperties?: Record<string, string>;