posthog-node 2.2.2 → 2.3.0

package/lib/posthog-core/src/index.d.ts

@@ -1,4 +1,4 @@
-import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PosthogCoreOptions, PostHogEventProperties, PostHogPersistedProperty } from './types';
+import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PosthogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, JsonType } from './types';
 import { RetriableOptions } from './utils';
 export * as utils from './utils';
 import { LZString } from './lz-string';
@@ -79,8 +79,16 @@ export declare abstract class PostHogCore {
     private decideAsync;
     private _decideAsync;
     private setKnownFeatureFlags;
+    private setKnownFeatureFlagPayloads;
     getFeatureFlag(key: string): boolean | string | undefined;
+    getFeatureFlagPayload(key: string): JsonType | undefined;
+    getFeatureFlagPayloads(): PostHogDecideResponse['featureFlagPayloads'] | undefined;
+    _parsePayload(response: any): any;
     getFeatureFlags(): PostHogDecideResponse['featureFlags'] | undefined;
+    getFeatureFlagsAndPayloads(): {
+        flags: PostHogDecideResponse['featureFlags'] | undefined;
+        payloads: PostHogDecideResponse['featureFlagPayloads'] | undefined;
+    };
     isFeatureEnabled(key: string): boolean | undefined;
     reloadFeatureFlagsAsync(sendAnonDistinctId?: boolean): Promise<PostHogDecideResponse['featureFlags']>;
     onFeatureFlags(cb: (flags: PostHogDecideResponse['featureFlags']) => void): () => void;

package/lib/posthog-core/src/types.d.ts

@@ -10,6 +10,7 @@ export declare type PosthogCoreOptions = {
         distinctId?: string;
         isIdentifiedId?: boolean;
         featureFlags?: Record<string, boolean | string>;
+        featureFlagPayloads?: Record<string, JsonType>;
     };
     fetchRetryCount?: number;
     fetchRetryDelay?: number;
@@ -22,6 +23,7 @@ export declare enum PostHogPersistedProperty {
     DistinctId = "distinct_id",
     Props = "props",
     FeatureFlags = "feature_flags",
+    FeatureFlagPayloads = "feature_flag_payloads",
     OverrideFeatureFlags = "override_feature_flags",
     Queue = "queue",
     OptedOut = "opted_out",
@@ -75,5 +77,16 @@ export declare type PostHogDecideResponse = {
     featureFlags: {
         [key: string]: string | boolean;
     };
+    featureFlagPayloads: {
+        [key: string]: JsonType;
+    };
+    errorsWhileComputingFlags: boolean;
     sessionRecording: boolean;
 };
+export declare type PosthogFlagsAndPayloadsResponse = {
+    featureFlags: PostHogDecideResponse['featureFlags'];
+    featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];
+};
+export declare type JsonType = string | number | boolean | null | {
+    [key: string]: JsonType;
+} | Array<JsonType>;

package/lib/posthog-node/src/feature-flags.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import { FeatureFlagCondition, PostHogFeatureFlag } from './types';
-import { PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src';
+import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src';
 declare class ClientError extends Error {
     constructor(message: string);
 }
@@ -20,6 +20,7 @@ declare class FeatureFlagsPoller {
     personalApiKey: string;
     projectApiKey: string;
     featureFlags: Array<PostHogFeatureFlag>;
+    featureFlagsByKey: Record<string, PostHogFeatureFlag>;
     groupTypeMapping: Record<string, string>;
     loadedSuccessfullyOnce: boolean;
     timeout?: number;
@@ -28,8 +29,10 @@ declare class FeatureFlagsPoller {
     fetch: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
     constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host, ...options }: FeatureFlagsPollerOptions);
     getFeatureFlag(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<string | boolean | undefined>;
-    getAllFlags(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<{
+    computeFeatureFlagPayloadLocally(key: string, matchValue: string | boolean): Promise<JsonType | undefined>;
+    getAllFlagsAndPayloads(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): Promise<{
         response: Record<string, string | boolean>;
+        payloads: Record<string, JsonType>;
         fallbackToDecide: boolean;
     }>;
     computeFlagLocally(flag: PostHogFeatureFlag, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, string>, groupProperties?: Record<string, Record<string, string>>): string | boolean;

package/lib/posthog-node/src/posthog-node.d.ts

@@ -1,4 +1,4 @@
-import { PosthogCoreOptions, PostHogFetchOptions, PostHogFetchResponse } from '../../posthog-core/src';
+import { JsonType, PosthogCoreOptions, PostHogFetchOptions, PostHogFetchResponse, PosthogFlagsAndPayloadsResponse } from '../../posthog-core/src';
 import { EventMessageV1, GroupIdentifyMessage, IdentifyMessageV1, PostHogNodeV1 } from './types';
 export declare type PostHogOptions = PosthogCoreOptions & {
     persistence?: 'memory';
@@ -30,6 +30,13 @@ export declare class PostHog implements PostHogNodeV1 {
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
     }): Promise<string | boolean | undefined>;
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+        sendFeatureFlagEvents?: boolean;
+    }): Promise<JsonType | undefined>;
     isFeatureEnabled(key: string, distinctId: string, options?: {
         groups?: Record<string, string>;
         personProperties?: Record<string, string>;
@@ -43,6 +50,12 @@ export declare class PostHog implements PostHogNodeV1 {
         groupProperties?: Record<string, Record<string, string>>;
         onlyEvaluateLocally?: boolean;
     }): Promise<Record<string, string | boolean>>;
+    getAllFlagsAndPayloads(distinctId: string, options?: {
+        groups?: Record<string, string>;
+        personProperties?: Record<string, string>;
+        groupProperties?: Record<string, Record<string, string>>;
+        onlyEvaluateLocally?: boolean;
+    }): Promise<PosthogFlagsAndPayloadsResponse>;
     groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void;
     reloadFeatureFlags(): Promise<void>;
     flush(): void;

package/lib/posthog-node/src/types.d.ts

@@ -1,3 +1,4 @@
+import { JsonType } from 'posthog-core/src';
 export interface IdentifyMessageV1 {
     distinctId: string;
     properties?: Record<string | number, any>;
@@ -35,6 +36,7 @@ export declare type PostHogFeatureFlag = {
                 rollout_percentage: number;
             }[];
         };
+        payloads?: Record<string, JsonType>;
     };
     deleted: boolean;
     active: boolean;
@@ -125,6 +127,23 @@ export declare type PostHogNodeV1 = {
         onlyEvaluateLocally?: boolean;
         sendFeatureFlagEvents?: boolean;
     }): Promise<string | boolean | undefined>;
+    /**
+     * @description Retrieves payload associated with the specified flag and matched value that is passed in.
+     * (Expected to be used in conjuction with getFeatureFlag but allows for manual lookup).
+     * If matchValue isn't passed, getFeatureFlag is called implicitly.
+     * Will try to evaluate for payload locally first otherwise default to network call if allowed
+     *
+     * @param key the unique key of your feature flag
+     * @param distinctId the current unique id
+     * @param matchValue optional- the matched flag string or boolean
+     * @param options: dict with optional parameters below
+     * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
+     *
+     * @returns payload of a json type object
+     */
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue?: string | boolean, options?: {
+        onlyEvaluateLocally?: boolean;
+    }): Promise<JsonType | undefined>;
     /**
      * @description Sets a groups properties, which allows asking questions like "Who are the most active companies"
      * using my product in PostHog.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "PostHog Node.js integration",
   "repository": "PostHog/posthog-node",
   "scripts": {

package/src/feature-flags.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'crypto'
 import { FeatureFlagCondition, PostHogFeatureFlag } from './types'
 import { version } from '../package.json'
-import { PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src'
+import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src'
 import { safeSetTimeout } from 'posthog-core/src/utils'
 import { fetch } from './fetch'
 
@@ -44,6 +44,7 @@ class FeatureFlagsPoller {
   personalApiKey: string
   projectApiKey: string
   featureFlags: Array<PostHogFeatureFlag>
+  featureFlagsByKey: Record<string, PostHogFeatureFlag>
   groupTypeMapping: Record<string, string>
   loadedSuccessfullyOnce: boolean
   timeout?: number
@@ -62,6 +63,7 @@ class FeatureFlagsPoller {
     this.pollingInterval = pollingInterval
     this.personalApiKey = personalApiKey
     this.featureFlags = []
+    this.featureFlagsByKey = {}
     this.groupTypeMapping = {}
     this.loadedSuccessfullyOnce = false
     this.timeout = timeout
@@ -100,10 +102,9 @@ class FeatureFlagsPoller {
     if (featureFlag !== undefined) {
       try {
         response = this.computeFlagLocally(featureFlag, distinctId, groups, personProperties, groupProperties)
-        console.debug(`Successfully computed flag locally: ${key} -> ${response}`)
       } catch (e) {
         if (e instanceof InconclusiveMatchError) {
-          console.debug(`Can't compute flag locally: ${key}: ${e}`)
+          console.error(`InconclusiveMatchError when computing flag locally: ${key}: ${e}`)
         } else if (e instanceof Error) {
           console.error(`Error computing flag locally: ${key}: ${e}`)
         }
@@ -113,20 +114,53 @@ class FeatureFlagsPoller {
     return response
   }
 
-  async getAllFlags(
+  async computeFeatureFlagPayloadLocally(key: string, matchValue: string | boolean): Promise<JsonType | undefined> {
+    await this.loadFeatureFlags()
+
+    let response = undefined
+
+    if (!this.loadedSuccessfullyOnce) {
+      return undefined
+    }
+
+    if (typeof matchValue == 'boolean') {
+      response = this.featureFlagsByKey?.[key]?.filters?.payloads?.[matchValue.toString()]
+    } else if (typeof matchValue == 'string') {
+      response = this.featureFlagsByKey?.[key]?.filters?.payloads?.[matchValue]
+    }
+
+    // Undefined means a loading or missing data issue. Null means evaluation happened and there was no match
+    if (response === undefined) {
+      return null
+    }
+
+    return response
+  }
+
+  async getAllFlagsAndPayloads(
     distinctId: string,
     groups: Record<string, string> = {},
     personProperties: Record<string, string> = {},
     groupProperties: Record<string, Record<string, string>> = {}
-  ): Promise<{ response: Record<string, string | boolean>; fallbackToDecide: boolean }> {
+  ): Promise<{
+    response: Record<string, string | boolean>
+    payloads: Record<string, JsonType>
+    fallbackToDecide: boolean
+  }> {
     await this.loadFeatureFlags()
 
     const response: Record<string, string | boolean> = {}
+    const payloads: Record<string, JsonType> = {}
     let fallbackToDecide = this.featureFlags.length == 0
 
-    this.featureFlags.map((flag) => {
+    this.featureFlags.map(async (flag) => {
       try {
-        response[flag.key] = this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties)
+        const matchValue = this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties)
+        response[flag.key] = matchValue
+        const matchPayload = await this.computeFeatureFlagPayloadLocally(flag.key, matchValue)
+        if (matchPayload) {
+          payloads[flag.key] = matchPayload
+        }
       } catch (e) {
         if (e instanceof InconclusiveMatchError) {
           // do nothing
@@ -137,7 +171,7 @@ class FeatureFlagsPoller {
       }
     })
 
-    return { response, fallbackToDecide }
+    return { response, payloads, fallbackToDecide }
   }
 
   computeFlagLocally(
@@ -316,12 +350,23 @@ class FeatureFlagsPoller {
           `Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview`
         )
       }
+
+      if (res && res.status !== 200) {
+        // something else went wrong, or the server is down.
+        // In this case, don't override existing flags
+        return
+      }
+
       const responseJson = await res.json()
       if (!('flags' in responseJson)) {
         console.error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`)
       }
 
       this.featureFlags = responseJson.flags || []
+      this.featureFlagsByKey = this.featureFlags.reduce(
+        (acc, curr) => ((acc[curr.key] = curr), acc),
+        <Record<string, PostHogFeatureFlag>>{}
+      )
       this.groupTypeMapping = responseJson.group_type_mapping || {}
       this.loadedSuccessfullyOnce = true
     } catch (err) {

package/src/posthog-node.ts

@@ -1,10 +1,12 @@
 import { version } from '../package.json'
 
 import {
+  JsonType,
   PostHogCore,
   PosthogCoreOptions,
   PostHogFetchOptions,
   PostHogFetchResponse,
+  PosthogFlagsAndPayloadsResponse,
   PostHogPersistedProperty,
 } from '../../posthog-core/src'
 import { PostHogMemoryStorage } from '../../posthog-core/src/storage-memory'
@@ -84,7 +86,7 @@ export class PostHog implements PostHogNodeV1 {
             : THIRTY_SECONDS,
         personalApiKey: options.personalApiKey,
         projectApiKey: apiKey,
-        timeout: options.requestTimeout ?? 10,
+        timeout: options.requestTimeout ?? 10000, // 10 seconds
         host: this._sharedClient.host,
         fetch: options.fetch,
       })
@@ -203,6 +205,73 @@ export class PostHog implements PostHogNodeV1 {
     return response
   }
 
+  async getFeatureFlagPayload(
+    key: string,
+    distinctId: string,
+    matchValue?: string | boolean,
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+      sendFeatureFlagEvents?: boolean
+    }
+  ): Promise<JsonType | undefined> {
+    const { groups, personProperties, groupProperties } = options || {}
+    let { onlyEvaluateLocally, sendFeatureFlagEvents } = options || {}
+    let response = undefined
+
+    // Try to get match value locally if not provided
+    if (!matchValue) {
+      matchValue = await this.getFeatureFlag(key, distinctId, {
+        ...options,
+        onlyEvaluateLocally: true,
+      })
+    }
+
+    if (matchValue) {
+      response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
+    }
+
+    // set defaults
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = false
+    }
+    if (sendFeatureFlagEvents == undefined) {
+      sendFeatureFlagEvents = true
+    }
+
+    // set defaults
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = false
+    }
+
+    const payloadWasLocallyEvaluated = response !== undefined
+
+    if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) {
+      this.reInit(distinctId)
+      if (groups != undefined) {
+        this._sharedClient.groups(groups)
+      }
+
+      if (personProperties) {
+        this._sharedClient.personProperties(personProperties)
+      }
+
+      if (groupProperties) {
+        this._sharedClient.groupProperties(groupProperties)
+      }
+      await this._sharedClient.reloadFeatureFlagsAsync(false)
+      response = this._sharedClient.getFeatureFlagPayload(key)
+    }
+
+    try {
+      return JSON.parse(response as any)
+    } catch {
+      return response
+    }
+  }
+
   async isFeatureEnabled(
     key: string,
     distinctId: string,
@@ -230,6 +299,19 @@ export class PostHog implements PostHogNodeV1 {
       onlyEvaluateLocally?: boolean
     }
   ): Promise<Record<string, string | boolean>> {
+    const response = await this.getAllFlagsAndPayloads(distinctId, options)
+    return response.featureFlags
+  }
+
+  async getAllFlagsAndPayloads(
+    distinctId: string,
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+    }
+  ): Promise<PosthogFlagsAndPayloadsResponse> {
     const { groups, personProperties, groupProperties } = options || {}
     let { onlyEvaluateLocally } = options || {}
 
@@ -238,17 +320,19 @@ export class PostHog implements PostHogNodeV1 {
       onlyEvaluateLocally = false
     }
 
-    const localEvaluationResult = await this.featureFlagsPoller?.getAllFlags(
+    const localEvaluationResult = await this.featureFlagsPoller?.getAllFlagsAndPayloads(
       distinctId,
       groups,
       personProperties,
       groupProperties
     )
 
-    let response = {}
+    let featureFlags = {}
+    let featureFlagPayloads = {}
     let fallbackToDecide = true
     if (localEvaluationResult) {
-      response = localEvaluationResult.response
+      featureFlags = localEvaluationResult.response
+      featureFlagPayloads = localEvaluationResult.payloads
       fallbackToDecide = localEvaluationResult.fallbackToDecide
     }
 
@@ -266,15 +350,22 @@ export class PostHog implements PostHogNodeV1 {
         this._sharedClient.groupProperties(groupProperties)
       }
       await this._sharedClient.reloadFeatureFlagsAsync(false)
-      const remoteEvaluationResult = this._sharedClient.getFeatureFlags()
-
-      return { ...response, ...remoteEvaluationResult }
+      const remoteEvaluationResult = this._sharedClient.getFeatureFlagsAndPayloads()
+      featureFlags = {
+        ...featureFlags,
+        ...(remoteEvaluationResult.flags || {}),
+      }
+      featureFlagPayloads = {
+        ...featureFlagPayloads,
+        ...(remoteEvaluationResult.payloads || {}),
+      }
     }
 
-    return response
+    return { featureFlags, featureFlagPayloads }
   }
 
   groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void {
+    this.reInit(`$${groupType}_${groupKey}`)
     this._sharedClient.groupIdentify(groupType, groupKey, properties)
   }
 

package/src/types.ts

@@ -1,3 +1,5 @@
+import { JsonType } from 'posthog-core/src'
+
 export interface IdentifyMessageV1 {
   distinctId: string
   properties?: Record<string | number, any>
@@ -39,6 +41,7 @@ export type PostHogFeatureFlag = {
         rollout_percentage: number
       }[]
     }
+    payloads?: Record<string, JsonType>
   }
   deleted: boolean
   active: boolean
@@ -140,6 +143,29 @@ export type PostHogNodeV1 = {
     }
   ): Promise<string | boolean | undefined>
 
+  /**
+   * @description Retrieves payload associated with the specified flag and matched value that is passed in.
+   * (Expected to be used in conjuction with getFeatureFlag but allows for manual lookup).
+   * If matchValue isn't passed, getFeatureFlag is called implicitly.
+   * Will try to evaluate for payload locally first otherwise default to network call if allowed
+   *
+   * @param key the unique key of your feature flag
+   * @param distinctId the current unique id
+   * @param matchValue optional- the matched flag string or boolean
+   * @param options: dict with optional parameters below
+   * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
+   *
+   * @returns payload of a json type object
+   */
+  getFeatureFlagPayload(
+    key: string,
+    distinctId: string,
+    matchValue?: string | boolean,
+    options?: {
+      onlyEvaluateLocally?: boolean
+    }
+  ): Promise<JsonType | undefined>
+
   /**
    * @description Sets a groups properties, which allows asking questions like "Who are the most active companies"
    * using my product in PostHog.