posthog-node 2.0.0-alpha8 → 2.0.2

package/src/feature-flags.ts

@@ -0,0 +1,396 @@
+import { createHash } from 'crypto'
+import { request } from 'undici'
+import { FeatureFlagCondition, PostHogFeatureFlag } from './types'
+import { version } from '../package.json'
+import { ResponseData } from 'undici/types/dispatcher'
+
+// eslint-disable-next-line
+const LONG_SCALE = 0xfffffffffffffff
+
+class ClientError extends Error {
+  constructor(message: string) {
+    super()
+    Error.captureStackTrace(this, this.constructor)
+    this.name = 'ClientError'
+    this.message = message
+    Object.setPrototypeOf(this, ClientError.prototype)
+  }
+}
+
+class InconclusiveMatchError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+    // instanceof doesn't work in ES3 or ES5
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    // this is the workaround
+    Object.setPrototypeOf(this, InconclusiveMatchError.prototype)
+  }
+}
+
+type FeatureFlagsPollerOptions = {
+  personalApiKey: string
+  projectApiKey: string
+  host: string
+  pollingInterval: number
+  timeout?: number
+}
+
+class FeatureFlagsPoller {
+  pollingInterval: number
+  personalApiKey: string
+  projectApiKey: string
+  featureFlags: Array<PostHogFeatureFlag>
+  groupTypeMapping: Record<string, string>
+  loadedSuccessfullyOnce: boolean
+  timeout?: number
+  host: FeatureFlagsPollerOptions['host']
+  poller?: NodeJS.Timeout
+
+  constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host }: FeatureFlagsPollerOptions) {
+    this.pollingInterval = pollingInterval
+    this.personalApiKey = personalApiKey
+    this.featureFlags = []
+    this.groupTypeMapping = {}
+    this.loadedSuccessfullyOnce = false
+    this.timeout = timeout
+    this.projectApiKey = projectApiKey
+    this.host = host
+    this.poller = undefined
+
+    void this.loadFeatureFlags()
+  }
+
+  async getFeatureFlag(
+    key: string,
+    distinctId: string,
+    groups: Record<string, string> = {},
+    personProperties: Record<string, string> = {},
+    groupProperties: Record<string, Record<string, string>> = {}
+  ): Promise<string | boolean | undefined> {
+    await this.loadFeatureFlags()
+
+    let response = undefined
+    let featureFlag = undefined
+
+    if (!this.loadedSuccessfullyOnce) {
+      return response
+    }
+
+    for (const flag of this.featureFlags) {
+      if (key === flag.key) {
+        featureFlag = flag
+        break
+      }
+    }
+
+    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}`)
+        } else if (e instanceof Error) {
+          console.error(`Error computing flag locally: ${key}: ${e}`)
+        }
+      }
+    }
+
+    return response
+  }
+
+  async getAllFlags(
+    distinctId: string,
+    groups: Record<string, string> = {},
+    personProperties: Record<string, string> = {},
+    groupProperties: Record<string, Record<string, string>> = {}
+  ): Promise<{ response: Record<string, string | boolean>; fallbackToDecide: boolean }> {
+    await this.loadFeatureFlags()
+
+    const response: Record<string, string | boolean> = {}
+    let fallbackToDecide = this.featureFlags.length == 0
+
+    this.featureFlags.map((flag) => {
+      try {
+        response[flag.key] = this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties)
+      } catch (e) {
+        if (e instanceof InconclusiveMatchError) {
+          // do nothing
+        } else if (e instanceof Error) {
+          console.error(`Error computing flag locally: ${flag.key}: ${e}`)
+        }
+        fallbackToDecide = true
+      }
+    })
+
+    return { response, fallbackToDecide }
+  }
+
+  computeFlagLocally(
+    flag: PostHogFeatureFlag,
+    distinctId: string,
+    groups: Record<string, string> = {},
+    personProperties: Record<string, string> = {},
+    groupProperties: Record<string, Record<string, string>> = {}
+  ): string | boolean {
+    if (flag.ensure_experience_continuity) {
+      throw new InconclusiveMatchError('Flag has experience continuity enabled')
+    }
+
+    if (!flag.active) {
+      return false
+    }
+
+    const flagFilters = flag.filters || {}
+    const aggregation_group_type_index = flagFilters.aggregation_group_type_index
+
+    if (aggregation_group_type_index != undefined) {
+      const groupName = this.groupTypeMapping[String(aggregation_group_type_index)]
+
+      if (!groupName) {
+        console.warn(
+          `[FEATURE FLAGS] Unknown group type index ${aggregation_group_type_index} for feature flag ${flag.key}`
+        )
+        throw new InconclusiveMatchError('Flag has unknown group type index')
+      }
+
+      if (!(groupName in groups)) {
+        console.warn(`[FEATURE FLAGS] Can't compute group feature flag: ${flag.key} without group names passed in`)
+        return false
+      }
+
+      const focusedGroupProperties = groupProperties[groupName]
+      return this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties)
+    } else {
+      return this.matchFeatureFlagProperties(flag, distinctId, personProperties)
+    }
+  }
+
+  matchFeatureFlagProperties(
+    flag: PostHogFeatureFlag,
+    distinctId: string,
+    properties: Record<string, string>
+  ): string | boolean {
+    const flagFilters = flag.filters || {}
+    const flagConditions = flagFilters.groups || []
+    let isInconclusive = false
+    let result = undefined
+
+    flagConditions.forEach((condition) => {
+      try {
+        if (this.isConditionMatch(flag, distinctId, condition, properties)) {
+          result = this.getMatchingVariant(flag, distinctId) || true
+        }
+      } catch (e) {
+        if (e instanceof InconclusiveMatchError) {
+          isInconclusive = true
+        } else {
+          throw e
+        }
+      }
+    })
+
+    if (result !== undefined) {
+      return result
+    } else if (isInconclusive) {
+      throw new InconclusiveMatchError("Can't determine if feature flag is enabled or not with given properties")
+    }
+
+    // We can only return False when all conditions are False
+    return false
+  }
+
+  isConditionMatch(
+    flag: PostHogFeatureFlag,
+    distinctId: string,
+    condition: FeatureFlagCondition,
+    properties: Record<string, string>
+  ): boolean {
+    const rolloutPercentage = condition.rollout_percentage
+
+    if ((condition.properties || []).length > 0) {
+      const matchAll = condition.properties.every((property) => {
+        return matchProperty(property, properties)
+      })
+      if (!matchAll) {
+        return false
+      } else if (rolloutPercentage == undefined) {
+        // == to include `null` as a match, not just `undefined`
+        return true
+      }
+    }
+
+    if (rolloutPercentage != undefined && _hash(flag.key, distinctId) > rolloutPercentage / 100.0) {
+      return false
+    }
+
+    return true
+  }
+
+  getMatchingVariant(flag: PostHogFeatureFlag, distinctId: string): string | boolean | undefined {
+    const hashValue = _hash(flag.key, distinctId, 'variant')
+    const matchingVariant = this.variantLookupTable(flag).find((variant) => {
+      return hashValue >= variant.valueMin && hashValue < variant.valueMax
+    })
+
+    if (matchingVariant) {
+      return matchingVariant.key
+    }
+    return undefined
+  }
+
+  variantLookupTable(flag: PostHogFeatureFlag): { valueMin: number; valueMax: number; key: string }[] {
+    const lookupTable: { valueMin: number; valueMax: number; key: string }[] = []
+    let valueMin = 0
+    let valueMax = 0
+    const flagFilters = flag.filters || {}
+    const multivariates: {
+      key: string
+      rollout_percentage: number
+    }[] = flagFilters.multivariate?.variants || []
+
+    multivariates.forEach((variant) => {
+      valueMax = valueMin + variant.rollout_percentage / 100.0
+      lookupTable.push({ valueMin, valueMax, key: variant.key })
+      valueMin = valueMax
+    })
+    return lookupTable
+  }
+
+  async loadFeatureFlags(forceReload = false): Promise<void> {
+    if (!this.loadedSuccessfullyOnce || forceReload) {
+      await this._loadFeatureFlags()
+    }
+  }
+
+  async _loadFeatureFlags(): Promise<void> {
+    if (this.poller) {
+      clearTimeout(this.poller)
+      this.poller = undefined
+    }
+    this.poller = setTimeout(() => this._loadFeatureFlags(), this.pollingInterval)
+
+    try {
+      const res = await this._requestFeatureFlagDefinitions()
+
+      if (res && res.statusCode === 401) {
+        throw new ClientError(
+          `Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview`
+        )
+      }
+      const responseJson = await res.body.json()
+      if (!('flags' in responseJson)) {
+        console.error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`)
+      }
+
+      this.featureFlags = responseJson.flags || []
+      this.groupTypeMapping = responseJson.group_type_mapping || {}
+      this.loadedSuccessfullyOnce = true
+    } catch (err) {
+      // if an error that is not an instance of ClientError is thrown
+      // we silently ignore the error when reloading feature flags
+      if (err instanceof ClientError) {
+        throw err
+      }
+    }
+  }
+
+  async _requestFeatureFlagDefinitions(): Promise<ResponseData> {
+    const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}`
+    const headers = {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${this.personalApiKey}`,
+      'user-agent': `posthog-node/${version}`,
+    }
+
+    const options: Parameters<typeof request>[1] = {
+      method: 'GET',
+      headers: headers,
+    }
+
+    if (this.timeout && typeof this.timeout === 'number') {
+      options.bodyTimeout = this.timeout
+    }
+
+    let res
+    try {
+      res = await request(url, options)
+    } catch (err) {
+      throw new Error(`Request failed with error: ${err}`)
+    }
+
+    return res
+  }
+
+  stopPoller(): void {
+    clearTimeout(this.poller)
+  }
+}
+
+// # This function takes a distinct_id and a feature flag key and returns a float between 0 and 1.
+// # Given the same distinct_id and key, it'll always return the same float. These floats are
+// # 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 {
+  const sha1Hash = createHash('sha1')
+  sha1Hash.update(`${key}.${distinctId}${salt}`)
+  return parseInt(sha1Hash.digest('hex').slice(0, 15), 16) / LONG_SCALE
+}
+
+function matchProperty(
+  property: FeatureFlagCondition['properties'][number],
+  propertyValues: Record<string, any>
+): boolean {
+  const key = property.key
+  const value = property.value
+  const operator = property.operator || 'exact'
+
+  if (!(key in propertyValues)) {
+    throw new InconclusiveMatchError(`Property ${key} not found in propertyValues`)
+  } else if (operator === 'is_not_set') {
+    throw new InconclusiveMatchError(`Operator is_not_set is not supported`)
+  }
+
+  const overrideValue = propertyValues[key]
+
+  switch (operator) {
+    case 'exact':
+      return Array.isArray(value) ? value.indexOf(overrideValue) !== -1 : value === overrideValue
+    case 'is_not':
+      return Array.isArray(value) ? value.indexOf(overrideValue) === -1 : value !== overrideValue
+    case 'is_set':
+      return key in propertyValues
+    case 'icontains':
+      return String(overrideValue).toLowerCase().includes(String(value).toLowerCase())
+    case 'not_icontains':
+      return !String(overrideValue).toLowerCase().includes(String(value).toLowerCase())
+    case 'regex':
+      return isValidRegex(String(value)) && String(overrideValue).match(String(value)) !== null
+    case 'not_regex':
+      return isValidRegex(String(value)) && String(overrideValue).match(String(value)) === null
+    case 'gt':
+      return typeof overrideValue == typeof value && overrideValue > value
+    case 'gte':
+      return typeof overrideValue == typeof value && overrideValue >= value
+    case 'lt':
+      return typeof overrideValue == typeof value && overrideValue < value
+    case 'lte':
+      return typeof overrideValue == typeof value && overrideValue <= value
+    default:
+      console.error(`Unknown operator: ${operator}`)
+      return false
+  }
+}
+
+function isValidRegex(regex: string): boolean {
+  try {
+    new RegExp(regex)
+    return true
+  } catch (err) {
+    return false
+  }
+}
+
+export { FeatureFlagsPoller, matchProperty, InconclusiveMatchError, ClientError }

package/src/posthog-node.ts

@@ -9,17 +9,29 @@ import {
 } from '../../posthog-core/src'
 import { PostHogMemoryStorage } from '../../posthog-core/src/storage-memory'
 import { EventMessageV1, GroupIdentifyMessage, IdentifyMessageV1, PostHogNodeV1 } from './types'
+import { FeatureFlagsPoller } from './feature-flags'
 
 export type PostHogOptions = PosthogCoreOptions & {
   persistence?: 'memory'
+  personalApiKey?: string
+  // The interval in milliseconds between polls for refreshing feature flag definitions
+  featureFlagsPollingInterval?: number
+  // Timeout in milliseconds for feature flag definitions calls. Defaults to 30 seconds.
+  requestTimeout?: number
+  // Maximum size of cache that deduplicates $feature_flag_called calls per user.
+  maxCacheSize?: number
 }
 
-class PostHog extends PostHogCore {
+const THIRTY_SECONDS = 30 * 1000
+const MAX_CACHE_SIZE = 50 * 1000
+
+class PostHogClient extends PostHogCore {
   private _memoryStorage = new PostHogMemoryStorage()
 
   constructor(apiKey: string, options: PostHogOptions = {}) {
     options.captureMode = options?.captureMode || 'json'
     options.preloadFeatureFlags = false // Don't preload as this makes no sense without a distinctId
+    options.sendFeatureFlagEvent = false // Let `posthog-node` handle this on its own, since we're dealing with multiple distinctIDs
 
     super(apiKey, options)
   }
@@ -53,23 +65,34 @@ class PostHog extends PostHogCore {
 }
 
 // The actual exported Nodejs API.
-export class PostHogGlobal implements PostHogNodeV1 {
-  private _sharedClient: PostHog
+export class PostHog implements PostHogNodeV1 {
+  private _sharedClient: PostHogClient
+  private featureFlagsPoller?: FeatureFlagsPoller
+  private maxCacheSize: number
+
+  distinctIdHasSentFlagCalls: Record<string, string[]>
 
   constructor(apiKey: string, options: PostHogOptions = {}) {
-    options.decidePollInterval = 0 // Forcefully set to 0 so we don't auto-reload
-    this._sharedClient = new PostHog(apiKey, options)
+    this._sharedClient = new PostHogClient(apiKey, options)
+    if (options.personalApiKey) {
+      this.featureFlagsPoller = new FeatureFlagsPoller({
+        pollingInterval:
+          typeof options.featureFlagsPollingInterval === 'number'
+            ? options.featureFlagsPollingInterval
+            : THIRTY_SECONDS,
+        personalApiKey: options.personalApiKey,
+        projectApiKey: apiKey,
+        timeout: options.requestTimeout,
+        host: this._sharedClient.host,
+      })
+    }
+    this.distinctIdHasSentFlagCalls = {}
+    this.maxCacheSize = options.maxCacheSize || MAX_CACHE_SIZE
   }
 
   private reInit(distinctId: string): void {
-    // Certain properties we want to persist
-    const propertiesToKeep = [PostHogPersistedProperty.Queue, PostHogPersistedProperty.OptedOut]
-
-    for (const key in PostHogPersistedProperty) {
-      if (!propertiesToKeep.includes(key as any)) {
-        this._sharedClient.setPersistedProperty((PostHogPersistedProperty as any)[key], null)
-      }
-    }
+    // Certain properties we want to persist. Queue is persisted always by default.
+    this._sharedClient.reset([PostHogPersistedProperty.OptedOut])
     this._sharedClient.setPersistedProperty(PostHogPersistedProperty.DistinctId, distinctId)
   }
 
@@ -81,12 +104,12 @@ export class PostHogGlobal implements PostHogNodeV1 {
     return this._sharedClient.optOut()
   }
 
-  capture({ distinctId, event, properties, groups }: EventMessageV1): void {
+  capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessageV1): void {
     this.reInit(distinctId)
     if (groups) {
       this._sharedClient.groups(groups)
     }
-    this._sharedClient.capture(event, properties)
+    this._sharedClient.capture(event, properties, sendFeatureFlags || false)
   }
 
   identify({ distinctId, properties }: IdentifyMessageV1): void {
@@ -102,39 +125,170 @@ export class PostHogGlobal implements PostHogNodeV1 {
   async getFeatureFlag(
     key: string,
     distinctId: string,
-    groups?: Record<string, string> | undefined
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+      sendFeatureFlagEvents?: boolean
+    }
   ): Promise<string | boolean | undefined> {
-    this.reInit(distinctId)
-    if (groups) {
-      this._sharedClient.groups(groups)
+    const { groups, personProperties, groupProperties } = options || {}
+    let { onlyEvaluateLocally, sendFeatureFlagEvents } = options || {}
+
+    // set defaults
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = false
+    }
+    if (sendFeatureFlagEvents == undefined) {
+      sendFeatureFlagEvents = true
+    }
+
+    let response = await this.featureFlagsPoller?.getFeatureFlag(
+      key,
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+
+    const flagWasLocallyEvaluated = response !== undefined
+
+    if (!flagWasLocallyEvaluated && !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.getFeatureFlag(key)
+    }
+
+    const featureFlagReportedKey = `${key}_${response}`
+
+    if (
+      sendFeatureFlagEvents &&
+      (!(distinctId in this.distinctIdHasSentFlagCalls) ||
+        !this.distinctIdHasSentFlagCalls[distinctId].includes(featureFlagReportedKey))
+    ) {
+      if (Object.keys(this.distinctIdHasSentFlagCalls).length >= this.maxCacheSize) {
+        this.distinctIdHasSentFlagCalls = {}
+      }
+      if (Array.isArray(this.distinctIdHasSentFlagCalls[distinctId])) {
+        this.distinctIdHasSentFlagCalls[distinctId].push(featureFlagReportedKey)
+      } else {
+        this.distinctIdHasSentFlagCalls[distinctId] = [featureFlagReportedKey]
+      }
+      this.capture({
+        distinctId,
+        event: '$feature_flag_called',
+        properties: {
+          $feature_flag: key,
+          $feature_flag_response: response,
+          locally_evaluated: flagWasLocallyEvaluated,
+        },
+        groups,
+      })
     }
-    await this._sharedClient.reloadFeatureFlagsAsync()
-    return this._sharedClient.getFeatureFlag(key)
+    return response
   }
 
   async isFeatureEnabled(
     key: string,
     distinctId: string,
-    defaultResult?: boolean | undefined,
-    groups?: Record<string, string> | undefined
-  ): Promise<boolean> {
-    const feat = await this.getFeatureFlag(key, distinctId, groups)
-    return !!feat || defaultResult || false
+    options?: {
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      onlyEvaluateLocally?: boolean
+      sendFeatureFlagEvents?: boolean
+    }
+  ): Promise<boolean | undefined> {
+    const feat = await this.getFeatureFlag(key, distinctId, options)
+    if (feat === undefined) {
+      return undefined
+    }
+    return !!feat || false
+  }
+
+  async 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>> {
+    const { groups, personProperties, groupProperties } = options || {}
+    let { onlyEvaluateLocally } = options || {}
+
+    // set defaults
+    if (onlyEvaluateLocally == undefined) {
+      onlyEvaluateLocally = false
+    }
+
+    const localEvaluationResult = await this.featureFlagsPoller?.getAllFlags(
+      distinctId,
+      groups,
+      personProperties,
+      groupProperties
+    )
+
+    let response = {}
+    let fallbackToDecide = true
+    if (localEvaluationResult) {
+      response = localEvaluationResult.response
+      fallbackToDecide = localEvaluationResult.fallbackToDecide
+    }
+
+    if (fallbackToDecide && !onlyEvaluateLocally) {
+      this.reInit(distinctId)
+      if (groups) {
+        this._sharedClient.groups(groups)
+      }
+
+      if (personProperties) {
+        this._sharedClient.personProperties(personProperties)
+      }
+
+      if (groupProperties) {
+        this._sharedClient.groupProperties(groupProperties)
+      }
+      await this._sharedClient.reloadFeatureFlagsAsync(false)
+      const remoteEvaluationResult = this._sharedClient.getFeatureFlags()
+
+      return { ...response, ...remoteEvaluationResult }
+    }
+
+    return response
   }
 
   groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void {
     this._sharedClient.groupIdentify(groupType, groupKey, properties)
   }
 
-  reloadFeatureFlags(): Promise<void> {
-    throw new Error('Method not implemented.')
+  async reloadFeatureFlags(): Promise<void> {
+    await this.featureFlagsPoller?.loadFeatureFlags(true)
+  }
+
+  flush(): void {
+    this._sharedClient.flush()
   }
 
   shutdown(): void {
-    void this._sharedClient.shutdownAsync()
+    void this.shutdownAsync()
   }
 
-  shutdownAsync(): Promise<void> {
+  async shutdownAsync(): Promise<void> {
+    this.featureFlagsPoller?.stopPoller()
     return this._sharedClient.shutdownAsync()
   }