posthog-node 5.8.8 → 5.9.0

package/src/extensions/feature-flags/lazy.ts

@@ -0,0 +1,55 @@
+/**
+ * A lazy value that is only computed when needed. Inspired by C#'s Lazy<T> class.
+ */
+export class Lazy<T> {
+  private value: T | undefined
+  private factory: () => Promise<T>
+  private initializationPromise: Promise<T> | undefined
+
+  constructor(factory: () => Promise<T>) {
+    this.factory = factory
+  }
+
+  /**
+   * Gets the value, initializing it if necessary.
+   * Multiple concurrent calls will share the same initialization promise.
+   */
+  async getValue(): Promise<T> {
+    if (this.value !== undefined) {
+      return this.value
+    }
+
+    if (this.initializationPromise === undefined) {
+      this.initializationPromise = (async () => {
+        try {
+          const result = await this.factory()
+          this.value = result
+          return result
+        } finally {
+          // Clear the promise so we can retry if needed
+          this.initializationPromise = undefined
+        }
+      })()
+    }
+
+    return this.initializationPromise
+  }
+
+  /**
+   * Returns true if the value has been initialized.
+   */
+  isInitialized(): boolean {
+    return this.value !== undefined
+  }
+
+  /**
+   * Returns a promise that resolves when the value is initialized.
+   * If already initialized, resolves immediately.
+   */
+  async waitForInitialization(): Promise<void> {
+    if (this.isInitialized()) {
+      return
+    }
+    await this.getValue()
+  }
+}

package/src/extensions/sentry-integration.ts

@@ -0,0 +1,216 @@
+/**
+ * @file Adapted from [posthog-js](https://github.com/PostHog/posthog-js/blob/8157df935a4d0e71d2fefef7127aa85ee51c82d1/src/extensions/sentry-integration.ts) with modifications for the Node SDK.
+ */
+/**
+ * Integrate Sentry with PostHog. This will add a direct link to the person in Sentry, and an $exception event in PostHog.
+ *
+ * ### Usage
+ *
+ *     Sentry.init({
+ *          dsn: 'https://example',
+ *          integrations: [
+ *              new PostHogSentryIntegration(posthog)
+ *          ]
+ *     })
+ *
+ *     Sentry.setTag(PostHogSentryIntegration.POSTHOG_ID_TAG, 'some distinct id');
+ *
+ * @param {Object} [posthog] The posthog object
+ * @param {string} [organization] Optional: The Sentry organization, used to send a direct link from PostHog to Sentry
+ * @param {Number} [projectId] Optional: The Sentry project id, used to send a direct link from PostHog to Sentry
+ * @param {string} [prefix] Optional: Url of a self-hosted sentry instance (default: https://sentry.io/organizations/)
+ * @param {SeverityLevel[] | '*'} [severityAllowList] Optional: send events matching the provided levels. Use '*' to send all events (default: ['error'])
+ * @param {boolean} [sendExceptionsToPostHog] Optional: capture exceptions as events in PostHog (default: true)
+ */
+
+import { SeverityLevel } from './error-tracking/types'
+import { type PostHogBackendClient } from '../client'
+
+// NOTE - we can't import from @sentry/types because it changes frequently and causes clashes
+// We only use a small subset of the types, so we can just define the integration overall and use any for the rest
+
+// import {
+//     Event as _SentryEvent,
+//     EventProcessor as _SentryEventProcessor,
+//     Exception as _SentryException,
+//     Hub as _SentryHub,
+//     Primitive as _SentryPrimitive,
+//     Integration as _SentryIntegration,
+//     IntegrationClass as _SentryIntegrationClass,
+// } from '@sentry/types'
+
+// Uncomment the above and comment the below to get type checking for development
+
+type _SentryEvent = any
+type _SentryEventProcessor = any
+type _SentryException = any
+type _SentryHub = any
+type _SentryPrimitive = any
+
+interface _SentryIntegration {
+  name: string
+  processEvent(event: _SentryEvent): _SentryEvent
+}
+
+interface _SentryIntegrationClass {
+  name: string
+  setupOnce(addGlobalEventProcessor: (callback: _SentryEventProcessor) => void, getCurrentHub: () => _SentryHub): void
+}
+
+interface SentryExceptionProperties {
+  $sentry_event_id?: string
+  $sentry_exception?: { values?: _SentryException[] }
+  $sentry_exception_message?: string
+  $sentry_exception_type?: string
+  $sentry_tags: { [key: string]: _SentryPrimitive }
+  $sentry_url?: string
+}
+
+export type SentryIntegrationOptions = {
+  organization?: string
+  projectId?: number
+  prefix?: string
+  severityAllowList?: SeverityLevel[] | '*'
+  sendExceptionsToPostHog?: boolean
+}
+
+const NAME = 'posthog-node'
+
+export function createEventProcessor(
+  _posthog: PostHogBackendClient,
+  {
+    organization,
+    projectId,
+    prefix,
+    severityAllowList = ['error'],
+    sendExceptionsToPostHog = true,
+  }: SentryIntegrationOptions = {}
+): (event: _SentryEvent) => _SentryEvent {
+  return (event) => {
+    const shouldProcessLevel = severityAllowList === '*' || severityAllowList.includes(event.level)
+    if (!shouldProcessLevel) {
+      return event
+    }
+    if (!event.tags) {
+      event.tags = {}
+    }
+
+    // Get the PostHog user ID from a specific tag, which users can set on their Sentry scope as they need.
+    const userId = event.tags[PostHogSentryIntegration.POSTHOG_ID_TAG]
+    if (userId === undefined) {
+      // If we can't find a user ID, don't bother linking the event. We won't be able to send anything meaningful to PostHog without it.
+      return event
+    }
+
+    const uiHost = _posthog.options.host ?? 'https://us.i.posthog.com'
+    const personUrl = new URL(`/project/${_posthog.apiKey}/person/${userId}`, uiHost).toString()
+
+    event.tags['PostHog Person URL'] = personUrl
+
+    const exceptions: _SentryException[] = event.exception?.values || []
+
+    const exceptionList = exceptions.map((exception) => ({
+      ...exception,
+      stacktrace: exception.stacktrace
+        ? {
+            ...exception.stacktrace,
+            type: 'raw',
+            frames: (exception.stacktrace.frames || []).map((frame: any) => {
+              return { ...frame, platform: 'node:javascript' }
+            }),
+          }
+        : undefined,
+    }))
+
+    const properties: SentryExceptionProperties & {
+      // two properties added to match any exception auto-capture
+      // added manually to avoid any dependency on the lazily loaded content
+      $exception_message: any
+      $exception_type: any
+      $exception_list: any
+      $exception_personURL: string
+      $exception_level: SeverityLevel
+    } = {
+      // PostHog Exception Properties,
+      $exception_message: exceptions[0]?.value || event.message,
+      $exception_type: exceptions[0]?.type,
+      $exception_personURL: personUrl,
+      $exception_level: event.level,
+      $exception_list: exceptionList,
+      // Sentry Exception Properties
+      $sentry_event_id: event.event_id,
+      $sentry_exception: event.exception,
+      $sentry_exception_message: exceptions[0]?.value || event.message,
+      $sentry_exception_type: exceptions[0]?.type,
+      $sentry_tags: event.tags,
+    }
+
+    if (organization && projectId) {
+      properties['$sentry_url'] =
+        (prefix || 'https://sentry.io/organizations/') +
+        organization +
+        '/issues/?project=' +
+        projectId +
+        '&query=' +
+        event.event_id
+    }
+
+    if (sendExceptionsToPostHog) {
+      _posthog.capture({ event: '$exception', distinctId: userId, properties })
+    }
+
+    return event
+  }
+}
+
+// V8 integration - function based
+export function sentryIntegration(
+  _posthog: PostHogBackendClient,
+  options?: SentryIntegrationOptions
+): _SentryIntegration {
+  const processor = createEventProcessor(_posthog, options)
+  return {
+    name: NAME,
+    processEvent(event) {
+      return processor(event)
+    },
+  }
+}
+
+// V7 integration - class based
+export class PostHogSentryIntegration implements _SentryIntegrationClass {
+  public readonly name = NAME
+
+  public static readonly POSTHOG_ID_TAG = 'posthog_distinct_id'
+
+  public setupOnce: (
+    addGlobalEventProcessor: (callback: _SentryEventProcessor) => void,
+    getCurrentHub: () => _SentryHub
+  ) => void
+
+  constructor(
+    _posthog: PostHogBackendClient,
+    organization?: string,
+    prefix?: string,
+    severityAllowList?: SeverityLevel[] | '*',
+    sendExceptionsToPostHog?: boolean
+  ) {
+    // setupOnce gets called by Sentry when it intializes the plugin
+    this.name = NAME
+    this.setupOnce = function (
+      addGlobalEventProcessor: (callback: _SentryEventProcessor) => void,
+      getCurrentHub: () => _SentryHub
+    ) {
+      const projectId = getCurrentHub()?.getClient()?.getDsn()?.projectId
+      addGlobalEventProcessor(
+        createEventProcessor(_posthog, {
+          organization,
+          projectId,
+          prefix,
+          severityAllowList,
+          sendExceptionsToPostHog: sendExceptionsToPostHog ?? true,
+        })
+      )
+    }
+  }
+}

package/src/storage-memory.ts

@@ -0,0 +1,13 @@
+import { PostHogPersistedProperty } from '@posthog/core'
+
+export class PostHogMemoryStorage {
+  private _memoryStorage: { [key: string]: any | undefined } = {}
+
+  getProperty(key: PostHogPersistedProperty): any | undefined {
+    return this._memoryStorage[key]
+  }
+
+  setProperty(key: PostHogPersistedProperty, value: any | null): void {
+    this._memoryStorage[key] = value !== null ? value : undefined
+  }
+}

package/src/types.ts

@@ -0,0 +1,294 @@
+import type {
+  PostHogCoreOptions,
+  FeatureFlagValue,
+  JsonType,
+  PostHogFetchOptions,
+  PostHogFetchResponse,
+} from '@posthog/core'
+
+export interface IdentifyMessage {
+  distinctId: string
+  properties?: Record<string | number, any>
+  disableGeoip?: boolean
+}
+
+export interface SendFeatureFlagsOptions {
+  onlyEvaluateLocally?: boolean
+  personProperties?: Record<string, any>
+  groupProperties?: Record<string, Record<string, any>>
+  flagKeys?: string[]
+}
+
+export interface EventMessage extends IdentifyMessage {
+  event: string
+  groups?: Record<string, string | number> // Mapping of group type to group id
+  sendFeatureFlags?: boolean | SendFeatureFlagsOptions
+  timestamp?: Date
+  uuid?: string
+}
+
+export interface GroupIdentifyMessage {
+  groupType: string
+  groupKey: string // Unique identifier for the group
+  properties?: Record<string | number, any>
+  distinctId?: string // optional distinctId to associate message with a person
+  disableGeoip?: boolean
+}
+
+export type PropertyGroup = {
+  type: 'AND' | 'OR'
+  values: PropertyGroup[] | FlagProperty[]
+}
+
+export type FlagProperty = {
+  key: string
+  type?: string
+  value: FlagPropertyValue
+  operator?: string
+  negation?: boolean
+  dependency_chain?: string[]
+}
+
+export type FlagPropertyValue = string | number | (string | number)[] | boolean
+
+export type FeatureFlagCondition = {
+  properties: FlagProperty[]
+  rollout_percentage?: number
+  variant?: string
+}
+
+export type BeforeSendFn = (event: EventMessage | null) => EventMessage | null
+
+export type PostHogOptions = PostHogCoreOptions & {
+  persistence?: 'memory'
+  personalApiKey?: string
+  privacyMode?: boolean
+  enableExceptionAutocapture?: boolean
+  // The interval in milliseconds between polls for refreshing feature flag definitions. Defaults to 30 seconds.
+  featureFlagsPollingInterval?: number
+  // Maximum size of cache that deduplicates $feature_flag_called calls per user.
+  maxCacheSize?: number
+  fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>
+  // Whether to enable feature flag polling for local evaluation by default. Defaults to true when personalApiKey is provided.
+  // We recommend setting this to false if you are only using the personalApiKey for evaluating remote config payloads via `getRemoteConfigPayload` and not using local evaluation.
+  enableLocalEvaluation?: boolean
+  /**
+   * Allows modification or dropping of events before they're sent to PostHog.
+   * If an array is provided, the functions are run in order.
+   * If a function returns null, the event will be dropped.
+   */
+  before_send?: BeforeSendFn | BeforeSendFn[]
+}
+
+export type PostHogFeatureFlag = {
+  id: number
+  name: string
+  key: string
+  filters?: {
+    aggregation_group_type_index?: number
+    groups?: FeatureFlagCondition[]
+    multivariate?: {
+      variants: {
+        key: string
+        rollout_percentage: number
+      }[]
+    }
+    payloads?: Record<string, string>
+  }
+  deleted: boolean
+  active: boolean
+  rollout_percentage: null | number
+  ensure_experience_continuity: boolean
+  experiment_set: number[]
+}
+
+export interface IPostHog {
+  /**
+   * @description Capture allows you to capture anything a user does within your system,
+   * which you can later use in PostHog to find patterns in usage,
+   * work out which features to improve or where people are giving up.
+   * A capture call requires:
+   * @param distinctId which uniquely identifies your user
+   * @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. Determines whether to send feature flag values with the event.
+   */
+  capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): void
+
+  /**
+   * @description Capture an event immediately. Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+   * @param distinctId which uniquely identifies your user
+   * @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. Determines whether to send feature flag values with the event.
+   */
+  captureImmediate({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): Promise<void>
+
+  /**
+   * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog,
+   * and even do things like segment users by these properties.
+   * An identify call requires:
+   * @param distinctId which uniquely identifies your user
+   * @param properties with a dict with any key: value pairs
+   */
+  identify({ distinctId, properties }: IdentifyMessage): void
+
+  /**
+   * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog.
+   * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+   * @param distinctId which uniquely identifies your user
+   * @param properties with a dict with any key: value pairs
+   */
+  identifyImmediate({ distinctId, properties }: IdentifyMessage): Promise<void>
+
+  /**
+   * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
+   * This will allow you to answer questions like "Which marketing channels leads to users churning after a month?"
+   * or "What do users do on our website before signing up?"
+   * In a purely back-end implementation, this means whenever an anonymous user does something, you'll want to send a session ID with the capture call.
+   * Then, when that users signs up, you want to do an alias call with the session ID and the newly created user ID.
+   * The same concept applies for when a user logs in. If you're using PostHog in the front-end and back-end,
+   *  doing the identify call in the frontend will be enough.:
+   * @param distinctId the current unique id
+   * @param alias the unique ID of the user before
+   */
+  alias(data: { distinctId: string; alias: string }): void
+
+  /**
+   * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
+   * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+   * @param distinctId the current unique id
+   * @param alias the unique ID of the user before
+   */
+  aliasImmediate(data: { distinctId: string; alias: string }): Promise<void>
+
+  /**
+   * @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 if the flag is on, false if the flag is off, undefined if there was an error.
+   */
+  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<FeatureFlagValue | undefined>
+
+  /**
+   * @description Retrieves payload associated with the specified flag and matched value that is passed in.
+   *
+   * 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 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.
+   *
+   * @returns payload of a json type object
+   */
+  getFeatureFlagPayload(
+    key: string,
+    distinctId: string,
+    matchValue?: FeatureFlagValue,
+    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.
+   *
+   * @param groupType Type of group (ex: 'company'). Limited to 5 per project
+   * @param groupKey Unique identifier for that type of group (ex: 'id:5')
+   * @param properties OPTIONAL | which can be a object with any information you'd like to add
+   */
+  groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void
+
+  /**
+   * @description Force an immediate reload of the polled feature flags. Please note that they are
+   * already polled automatically at a regular interval.
+   */
+  reloadFeatureFlags(): Promise<void>
+
+  /**
+   * @description Flushes the events still in the queue and clears the feature flags poller to allow for
+   * a clean shutdown.
+   *
+   * @param shutdownTimeoutMs The shutdown timeout, in milliseconds. Defaults to 30000 (30s).
+   */
+  shutdown(shutdownTimeoutMs?: number): void
+
+  /**
+   * @description Waits for local evaluation to be ready, with an optional timeout.
+   * @param timeoutMs - Maximum time to wait in milliseconds. Defaults to 30 seconds.
+   * @returns A promise that resolves to true if local evaluation is ready, false if the timeout was reached.
+   */
+  waitForLocalEvaluationReady(timeoutMs?: number): Promise<boolean>
+
+  /**
+   * @description Returns true if local evaluation is ready, false if it's not.
+   * @returns true if local evaluation is ready, false if it's not.
+   */
+  isLocalEvaluationReady(): boolean
+}

package/src/utils/logger.ts

@@ -0,0 +1,39 @@
+import { Logger } from '@posthog/core'
+
+const _createLogger = (prefix: string, logMsgIfDebug: (fn: () => void) => void): Logger => {
+  const logger: Logger = {
+    _log: (level: 'log' | 'warn' | 'error', ...args: any[]) => {
+      logMsgIfDebug(() => {
+        const consoleLog = console[level]
+        consoleLog(prefix, ...args)
+      })
+    },
+
+    info: (...args: any[]) => {
+      logger._log('log', ...args)
+    },
+
+    warn: (...args: any[]) => {
+      logger._log('warn', ...args)
+    },
+
+    error: (...args: any[]) => {
+      logger._log('error', ...args)
+    },
+
+    critical: (...args: any[]) => {
+      // Critical errors are always logged to the console
+      // eslint-disable-next-line no-console
+      console.error(prefix, ...args)
+    },
+
+    uninitializedWarning: (methodName: string) => {
+      logger.error(`You must initialize PostHog before calling ${methodName}`)
+    },
+
+    createLogger: (additionalPrefix: string) => _createLogger(`${prefix} ${additionalPrefix}`, logMsgIfDebug),
+  }
+  return logger
+}
+
+export const createLogger = (logMsgIfDebug: (fn: () => void) => void) => _createLogger('[PostHog.js]', logMsgIfDebug)

package/src/version.ts

@@ -0,0 +1 @@
+export const version = '5.9.0'