posthog-node 4.3.1 → 4.4.0

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

@@ -49,6 +49,8 @@ export declare enum PostHogPersistedProperty {
     Props = "props",
     FeatureFlags = "feature_flags",
     FeatureFlagPayloads = "feature_flag_payloads",
+    BootstrapFeatureFlags = "bootstrap_feature_flags",
+    BootstrapFeatureFlagPayloads = "bootstrap_feature_flag_payloads",
     OverrideFeatureFlags = "override_feature_flags",
     Queue = "queue",
     OptedOut = "opted_out",
@@ -58,7 +60,8 @@ export declare enum PostHogPersistedProperty {
     GroupProperties = "group_properties",
     InstalledAppBuild = "installed_app_build",
     InstalledAppVersion = "installed_app_version",
-    SessionReplay = "session_replay"
+    SessionReplay = "session_replay",
+    DecideEndpointWasHit = "decide_endpoint_was_hit"
 }
 export type PostHogFetchOptions = {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH';

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

@@ -140,13 +140,25 @@ 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
+     *
+     * IMPORTANT: The `matchValue` parameter should be the value you previously obtained from `getFeatureFlag()`.
+     * If matchValue isn't passed (or is undefined), this method will automatically call `getFeatureFlag()`
+     * internally to fetch the flag value, which could result in a network call to the PostHog server if this flag can
+     * not be evaluated locally. This means that omitting `matchValue` will potentially:
+     * - Bypass local evaluation
+     * - Count as an additional flag evaluation against your quota
+     * - Impact performance due to the extra network request
+     *
+     * Example usage:
+     * ```js
+     * const flagValue = await client.getFeatureFlag('my-flag', distinctId);
+     * const payload = await client.getFeatureFlagPayload('my-flag', distinctId, flagValue);
+     * ```
      *
      * @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 matchValue The flag value previously obtained from calling `getFeatureFlag()`. Can be a string or boolean.
+     *                   To avoid extra network calls, pass this parameter when you can.
      * @param options: dict with optional parameters below
      * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",
@@ -23,12 +23,12 @@
   "module": "lib/index.esm.js",
   "types": "lib/index.d.ts",
   "dependencies": {
-    "axios": "^1.7.4",
-    "rusha": "^0.8.14"
+    "axios": "^1.7.4"
   },
   "devDependencies": {
     "@types/node": "^18.0.0",
-    "commander": "^9.3.0"
+    "commander": "^9.3.0",
+    "mitata": "^1.0.21"
   },
   "keywords": [
     "posthog",

package/src/feature-flags.ts

@@ -1,4 +1,4 @@
-import { createHash } from 'rusha'
+import { createHash } from 'node:crypto'
 import { FeatureFlagCondition, FlagProperty, PostHogFeatureFlag, PropertyGroup } from './types'
 import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src'
 import { safeSetTimeout } from 'posthog-core/src/utils'
@@ -458,8 +458,7 @@ class FeatureFlagsPoller {
 // # uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
 // # we can do _hash(key, distinct_id) < 0.2
 function _hash(key: string, distinctId: string, salt: string = ''): number {
-  // rusha is a fast sha1 implementation in pure javascript
-  const sha1Hash = createHash()
+  const sha1Hash = createHash('sha1')
   sha1Hash.update(`${key}.${distinctId}${salt}`)
   return parseInt(sha1Hash.digest('hex').slice(0, 15), 16) / LONG_SCALE
 }

package/src/posthog-node.ts

@@ -294,80 +294,59 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       disableGeoip?: boolean
     }
   ): Promise<JsonType | undefined> {
-    const { groups, disableGeoip, onlyEvaluateLocally = false, personProperties, groupProperties } = options || {}
+    const { groups, disableGeoip } = options || {}
+    let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {}
 
-    const { allPersonProperties, allGroupProperties } = this.addLocalPersonAndGroupProperties(
+    const adjustedProperties = this.addLocalPersonAndGroupProperties(
       distinctId,
       groups,
       personProperties,
       groupProperties
     )
 
-    if (matchValue === undefined) {
+    personProperties = adjustedProperties.allPersonProperties
+    groupProperties = adjustedProperties.allGroupProperties
+
+    let response = undefined
+
+    // Try to get match value locally if not provided
+    if (!matchValue) {
       matchValue = await this.getFeatureFlag(key, distinctId, {
         ...options,
         onlyEvaluateLocally: true,
-        sendFeatureFlagEvents: false,
       })
     }
 
-    let response: string | boolean | undefined
-    let payload: JsonType | undefined
-
     if (matchValue) {
-      response = matchValue
-      payload = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
-    } else {
-      response = undefined
-      payload = undefined
+      response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
+    }
+
+    // set defaults
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = false
+    }
+    if (sendFeatureFlagEvents == undefined) {
+      sendFeatureFlagEvents = true
     }
 
-    // Determine if the payload was evaluated locally
-    const payloadWasLocallyEvaluated = payload !== undefined
+    // set defaults
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = false
+    }
 
-    // Fetch final flags and payloads either locally or from the remote server
-    let fetchedOrLocalFlags: Record<string, string | boolean> | undefined
-    let fetchedOrLocalPayloads: Record<string, JsonType | undefined> | undefined
+    const payloadWasLocallyEvaluated = response !== undefined
 
-    if (payloadWasLocallyEvaluated || onlyEvaluateLocally) {
-      if (response !== undefined) {
-        fetchedOrLocalFlags = { [key]: response }
-        fetchedOrLocalPayloads = { [key]: payload }
-      } else {
-        fetchedOrLocalFlags = {}
-        fetchedOrLocalPayloads = {}
-      }
-    } else {
-      const fetchedData = await super.getFeatureFlagsAndPayloadsStateless(
+    if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) {
+      response = await super.getFeatureFlagPayloadStateless(
+        key,
         distinctId,
         groups,
-        allPersonProperties,
-        allGroupProperties,
+        personProperties,
+        groupProperties,
         disableGeoip
       )
-      fetchedOrLocalFlags = fetchedData.flags || {}
-      fetchedOrLocalPayloads = fetchedData.payloads || {}
     }
-
-    const finalResponse = fetchedOrLocalFlags[key]
-    const finalPayload = fetchedOrLocalPayloads[key]
-    const finalLocallyEvaluated = payloadWasLocallyEvaluated
-
-    this.capture({
-      distinctId,
-      event: '$feature_flag_called',
-      properties: {
-        $feature_flag: key,
-        $feature_flag_response: finalResponse,
-        $feature_flag_payload: finalPayload,
-        locally_evaluated: finalLocallyEvaluated,
-        [`$feature/${key}`]: finalResponse,
-      },
-      groups,
-      disableGeoip,
-    })
-
-    return finalPayload
+    return response
   }
 
   async isFeatureEnabled(

package/src/types.ts

@@ -158,13 +158,25 @@ export type PostHogNodeV1 = {
 
   /**
    * @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
+   *
+   * IMPORTANT: The `matchValue` parameter should be the value you previously obtained from `getFeatureFlag()`.
+   * If matchValue isn't passed (or is undefined), this method will automatically call `getFeatureFlag()`
+   * internally to fetch the flag value, which could result in a network call to the PostHog server if this flag can
+   * not be evaluated locally. This means that omitting `matchValue` will potentially:
+   * - Bypass local evaluation
+   * - Count as an additional flag evaluation against your quota
+   * - Impact performance due to the extra network request
+   *
+   * Example usage:
+   * ```js
+   * const flagValue = await client.getFeatureFlag('my-flag', distinctId);
+   * const payload = await client.getFeatureFlagPayload('my-flag', distinctId, flagValue);
+   * ```
    *
    * @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 matchValue The flag value previously obtained from calling `getFeatureFlag()`. Can be a string or boolean.
+   *                   To avoid extra network calls, pass this parameter when you can.
    * @param options: dict with optional parameters below
    * @param onlyEvaluateLocally optional - whether to only evaluate the flag locally. Defaults to false.
    *

package/test/posthog-node.spec.ts

@@ -897,18 +897,13 @@ describe('PostHog Node.js', () => {
                   rollout_percentage: 100,
                 },
               ],
-              payloads: { true: { variant: 'A' } },
             },
           },
         ],
       }
 
       mockedFetch.mockImplementation(
-        apiImplementation({
-          localFlags: flags,
-          decideFlags: { 'decide-flag': 'decide-value' },
-          decideFlagPayloads: { 'beta-feature': { variant: 'A' } },
-        })
+        apiImplementation({ localFlags: flags, decideFlags: { 'decide-flag': 'decide-value' } })
       )
 
       posthog = new PostHog('TEST_API_KEY', {
@@ -950,34 +945,6 @@ describe('PostHog Node.js', () => {
       )
       mockedFetch.mockClear()
 
-      expect(
-        await posthog.getFeatureFlagPayload('beta-feature', 'some-distinct-id', undefined, {
-          personProperties: { region: 'USA', name: 'Aloha' },
-        })
-      ).toEqual({ variant: 'A' })
-
-      // TRICKY: There's now an extra step before events are queued, so need to wait for that to resolve
-      jest.runOnlyPendingTimers()
-      await waitForPromises()
-      await posthog.flush()
-
-      expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
-
-      expect(getLastBatchEvents()?.[0]).toEqual(
-        expect.objectContaining({
-          distinct_id: 'some-distinct-id',
-          event: '$feature_flag_called',
-          properties: expect.objectContaining({
-            $feature_flag: 'beta-feature',
-            $feature_flag_response: true,
-            $feature_flag_payload: { variant: 'A' },
-            locally_evaluated: true,
-            [`$feature/${'beta-feature'}`]: true,
-          }),
-        })
-      )
-      mockedFetch.mockClear()
-
       // # called again for same user, shouldn't call capture again
       expect(
         await posthog.getFeatureFlag('beta-feature', 'some-distinct-id', {
@@ -1114,7 +1081,7 @@ describe('PostHog Node.js', () => {
       expect(mockedFetch).toHaveBeenCalledTimes(0)
 
       await expect(posthog.getFeatureFlagPayload('false-flag', '123', true)).resolves.toEqual(300)
-      expect(mockedFetch).toHaveBeenCalledTimes(1) // this now calls the server, because in this case the flag is not locally evaluated but we have a payload that we need to calculate
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
     })
 
     it('should not double parse json with getFeatureFlagPayloads and server eval', async () => {

package/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    "types": ["node", "rusha"],
-    "typeRoots": ["./node_modules/@types", "../node_modules/@types", "./src/types"]
+    "types": ["node"],
+    "typeRoots": ["./node_modules/@types", "../node_modules/@types"]
   }
 }

package/src/types/rusha.d.ts

@@ -1,23 +0,0 @@
-// Adjusted from type definitions for rusha 0.8
-// Project: https://github.com/srijs/rusha#readme
-// Definitions by: Jacopo Scazzosi <https://github.com/jacoscaz>
-// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// Minimum TypeScript Version: 4.0
-
-/// <reference types="node" />
-
-interface Hash {
-  update(value: string | number[] | ArrayBuffer | Buffer): Hash
-  digest(encoding?: undefined): ArrayBuffer
-  digest(encoding: 'hex'): string
-}
-
-interface Rusha {
-  createHash(): Hash
-}
-
-declare const Rusha: Rusha
-
-declare module 'rusha' {
-  export = Rusha
-}