posthog-node 5.0.0-alpha.1 → 5.1.0

package/src/types.ts

@@ -1,231 +0,0 @@
-import { FeatureFlagValue, JsonType } from '../../posthog-core/src'
-
-export interface IdentifyMessage {
-  distinctId: string
-  properties?: Record<string | number, any>
-  disableGeoip?: boolean
-}
-
-export interface EventMessage extends IdentifyMessage {
-  event: string
-  groups?: Record<string, string | number> // Mapping of group type to group id
-  sendFeatureFlags?: boolean
-  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: string | number | (string | number)[]
-  operator?: string
-  negation?: boolean
-}
-
-export type FeatureFlagCondition = {
-  properties: FlagProperty[]
-  rollout_percentage?: number
-  variant?: string
-}
-
-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
-  /** @deprecated This field will be removed in a future version. **/
-  is_simple_flag: boolean
-  rollout_percentage: null | number
-  ensure_experience_continuity: boolean
-  experiment_set: number[]
-}
-
-export type PostHogNodeV1 = {
-  /**
-   * @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 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 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 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/test/crypto.spec.ts

@@ -1,36 +0,0 @@
-import * as crypto from '../src/crypto'
-import * as cryptoHelpers from '../src/crypto-helpers'
-
-describe('crypto', () => {
-  describe('hashSHA1', () => {
-    const testString = 'some-flag.some_distinct_id'
-    const expectedHash = 'e4ce124e800a818c63099f95fa085dc2b620e173'
-
-    afterEach(() => {
-      jest.restoreAllMocks() // <- Reset all mocks after each test
-    })
-
-    it('should hash correctly using Node.js crypto', async () => {
-      jest.spyOn(cryptoHelpers, 'getWebCrypto').mockResolvedValue(undefined)
-
-      const hash = await crypto.hashSHA1(testString)
-      expect(hash).toBe(expectedHash)
-    })
-
-    it('should hash correctly using Web Crypto API', async () => {
-      jest.spyOn(cryptoHelpers, 'getNodeCrypto').mockResolvedValue(undefined)
-
-      const hash = await crypto.hashSHA1(testString)
-      expect(hash).toBe(expectedHash)
-    })
-
-    it('should throw if no crypto implementation is available', async () => {
-      jest.spyOn(cryptoHelpers, 'getNodeCrypto').mockResolvedValue(undefined)
-      jest.spyOn(cryptoHelpers, 'getWebCrypto').mockResolvedValue(undefined)
-
-      await expect(crypto.hashSHA1(testString)).rejects.toThrow(
-        'No crypto implementation available. Tried Node Crypto API and Web SubtleCrypto API'
-      )
-    })
-  })
-})

package/test/extensions/error-conversion.spec.ts

@@ -1,44 +0,0 @@
-import { propertiesFromUnknownInput } from '../../src/extensions/error-tracking/error-conversion'
-import { defaultStackParser } from '../../src/extensions/error-tracking/stack-trace'
-import { ErrorProperties } from '../../src/extensions/error-tracking/types'
-
-describe('error conversion', () => {
-  async function getExceptionList(error: unknown): Promise<ErrorProperties['$exception_list']> {
-    const syntheticException = new Error('PostHog syntheticException')
-    const exceptionProperties = await propertiesFromUnknownInput(defaultStackParser, error, {
-      syntheticException,
-    })
-    return exceptionProperties.$exception_list
-  }
-
-  it('should create an exception list from a string', async () => {
-    const exceptionList = await getExceptionList('My string error')
-    expect(exceptionList.length).toEqual(1)
-    expect(exceptionList[0].value).toEqual('My string error')
-  })
-
-  it('should use the error key in object', async () => {
-    const errorObject = { error: new Error('My special error') }
-    const exceptionList = await getExceptionList(errorObject)
-    expect(exceptionList.length).toEqual(1)
-    expect(exceptionList[0].value).toEqual('My special error')
-  })
-
-  it('should create an exception list from an error cause', async () => {
-    const originalError = new Error('original error')
-    const error = new Error('test error', { cause: originalError })
-    const exceptionList = await getExceptionList(error)
-    expect(exceptionList.length).toEqual(2)
-    expect(exceptionList[0].value).toEqual('test error')
-    expect(exceptionList[1].value).toEqual('original error')
-  })
-
-  it('should create an exception list from a non error cause', async () => {
-    const originalError = { error_code: 'XASKJASK' }
-    const error = new Error('test error', { cause: originalError })
-    const exceptionList = await getExceptionList(error)
-    expect(exceptionList.length).toEqual(2)
-    expect(exceptionList[0].value).toEqual('test error')
-    expect(exceptionList[1].value).toEqual('Object captured as exception with keys: error_code')
-  })
-})

package/test/extensions/sentry-integration.spec.ts

@@ -1,162 +0,0 @@
-// import { PostHog } from '../'
-import { PostHog as PostHog } from '../../src/posthog-node'
-import { PostHogSentryIntegration } from '../../src/extensions/sentry-integration'
-import { waitForPromises } from 'posthog-core/test/test-utils/test-utils'
-
-jest.mock('../../package.json', () => ({ version: '1.2.3' }))
-
-const mockedFetch = jest.spyOn(globalThis, 'fetch').mockImplementation()
-
-const getLastBatchEvents = (): any[] | undefined => {
-  expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.objectContaining({ method: 'POST' }))
-
-  // reverse mock calls array to get the last call
-  const call = mockedFetch.mock.calls.reverse().find((x) => (x[0] as string).includes('/batch/'))
-  if (!call) {
-    return undefined
-  }
-  return JSON.parse((call[1] as any).body as any).batch
-}
-
-const createMockSentryException = (): any => ({
-  exception: {
-    values: [
-      {
-        type: 'Error',
-        value: 'example error',
-        stacktrace: {
-          frames: [],
-        },
-        mechanism: { type: 'generic', handled: true },
-      },
-    ],
-  },
-  event_id: '80a7023ac32c47f7acb0adaed600d149',
-  platform: 'node',
-  contexts: {},
-  server_name: 'localhost',
-  timestamp: 1704203482.356,
-  environment: 'production',
-  level: 'error',
-  tags: { posthog_distinct_id: 'EXAMPLE_APP_GLOBAL' },
-  breadcrumbs: [
-    {
-      timestamp: 1704203481.422,
-      category: 'console',
-      level: 'log',
-      message: '⚡: Server is running at http://localhost:8010',
-    },
-    {
-      timestamp: 1704203481.658,
-      category: 'console',
-      level: 'log',
-      message:
-        "PostHog Debug error [ClientError: Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview]",
-    },
-  ],
-  sdkProcessingMetadata: {
-    propagationContext: { traceId: 'ea26146e5a354cb0b3b1daebb3f90e33', spanId: '8d642089c3daa272' },
-  },
-})
-
-describe('PostHogSentryIntegration', () => {
-  let posthog: PostHog
-  let posthogSentry: PostHogSentryIntegration
-
-  jest.useFakeTimers()
-
-  beforeEach(() => {
-    posthog = new PostHog('TEST_API_KEY', {
-      host: 'http://example.com',
-      fetchRetryCount: 0,
-    })
-
-    posthogSentry = new PostHogSentryIntegration(posthog)
-
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () =>
-        Promise.resolve({
-          status: 'ok',
-        }),
-    } as any)
-  })
-
-  afterEach(async () => {
-    // ensure clean shutdown & no test interdependencies
-    await posthog.shutdown()
-  })
-
-  it('should forward sentry exceptions to posthog', async () => {
-    expect(mockedFetch).toHaveBeenCalledTimes(0)
-
-    const mockSentry = {
-      getClient: () => ({
-        getDsn: () => ({
-          projectId: 123,
-        }),
-      }),
-    }
-
-    let processorFunction: any
-
-    posthogSentry.setupOnce(
-      (fn) => (processorFunction = fn),
-      () => mockSentry
-    )
-
-    processorFunction(createMockSentryException())
-
-    await waitForPromises() // First flush
-    jest.runOnlyPendingTimers() // Flush timer
-    await waitForPromises() // Second flush
-    const batchEvents = getLastBatchEvents()
-
-    expect(batchEvents).toEqual([
-      {
-        distinct_id: 'EXAMPLE_APP_GLOBAL',
-        event: '$exception',
-        properties: {
-          $exception_level: 'error',
-          $exception_list: [
-            {
-              mechanism: { handled: true, type: 'generic' },
-              stacktrace: { frames: [], type: 'raw' },
-              type: 'Error',
-              value: 'example error',
-            },
-          ],
-          $exception_message: 'example error',
-          $exception_type: 'Error',
-          $exception_personURL: 'http://example.com/project/TEST_API_KEY/person/EXAMPLE_APP_GLOBAL',
-          $sentry_event_id: '80a7023ac32c47f7acb0adaed600d149',
-          $sentry_exception: {
-            values: [
-              {
-                type: 'Error',
-                value: 'example error',
-                stacktrace: { frames: [] },
-                mechanism: { type: 'generic', handled: true },
-              },
-            ],
-          },
-          $sentry_exception_message: 'example error',
-          $sentry_exception_type: 'Error',
-          $sentry_tags: {
-            posthog_distinct_id: 'EXAMPLE_APP_GLOBAL',
-            'PostHog Person URL': 'http://example.com/project/TEST_API_KEY/person/EXAMPLE_APP_GLOBAL',
-          },
-          $lib: 'posthog-node',
-          $lib_version: '1.2.3',
-          $geoip_disable: true,
-        },
-        type: 'capture',
-        library: 'posthog-node',
-        library_version: '1.2.3',
-        timestamp: expect.any(String),
-        uuid: expect.any(String),
-      },
-    ])
-  })
-})