posthog-node 4.2.3 → 4.3.1

package/lib/posthog-node/src/extensions/sentry-integration.d.ts

@@ -1,13 +1,6 @@
 /**
  * @file Adapted from [posthog-js](https://github.com/PostHog/posthog-js/blob/8157df935a4d0e71d2fefef7127aa85ee51c82d1/src/extensions/sentry-integration.ts) with modifications for the Node SDK.
  */
-import { type PostHog } from '../posthog-node';
-type _SentryEventProcessor = any;
-type _SentryHub = any;
-interface _SentryIntegration {
-    name: string;
-    setupOnce(addGlobalEventProcessor: (callback: _SentryEventProcessor) => void, getCurrentHub: () => _SentryHub): void;
-}
 /**
  * Integrate Sentry with PostHog. This will add a direct link to the person in Sentry, and an $exception event in PostHog.
  *
@@ -26,15 +19,34 @@ interface _SentryIntegration {
  * @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'])
  */
-export declare class PostHogSentryIntegration implements _SentryIntegration {
-    private readonly posthog;
-    private readonly posthogHost?;
-    private readonly organization?;
-    private readonly prefix?;
+import { type PostHog } from '../posthog-node';
+export declare const severityLevels: readonly ["fatal", "error", "warning", "log", "info", "debug"];
+export declare type SeverityLevel = (typeof severityLevels)[number];
+type _SentryEvent = any;
+type _SentryEventProcessor = any;
+type _SentryHub = any;
+interface _SentryIntegration {
+    name: string;
+    processEvent(event: _SentryEvent): _SentryEvent;
+}
+interface _SentryIntegrationClass {
+    name: string;
+    setupOnce(addGlobalEventProcessor: (callback: _SentryEventProcessor) => void, getCurrentHub: () => _SentryHub): void;
+}
+export type SentryIntegrationOptions = {
+    organization?: string;
+    projectId?: number;
+    prefix?: string;
+    severityAllowList?: SeverityLevel[] | '*';
+};
+export declare function createEventProcessor(_posthog: PostHog, { organization, projectId, prefix, severityAllowList }?: SentryIntegrationOptions): (event: _SentryEvent) => _SentryEvent;
+export declare function sentryIntegration(_posthog: PostHog, options?: SentryIntegrationOptions): _SentryIntegration;
+export declare class PostHogSentryIntegration implements _SentryIntegrationClass {
     readonly name = "posthog-node";
     static readonly POSTHOG_ID_TAG = "posthog_distinct_id";
-    constructor(posthog: PostHog, posthogHost?: string | undefined, organization?: string | undefined, prefix?: string | undefined);
-    setupOnce(addGlobalEventProcessor: (callback: _SentryEventProcessor) => void, getCurrentHub: () => _SentryHub): void;
+    setupOnce: (addGlobalEventProcessor: (callback: _SentryEventProcessor) => void, getCurrentHub: () => _SentryHub) => void;
+    constructor(_posthog: PostHog, organization?: string, prefix?: string, severityAllowList?: SeverityLevel[] | '*');
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "4.2.3",
+  "version": "4.3.1",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",

package/src/extensions/sentry-integration.ts

@@ -1,8 +1,32 @@
 /**
  * @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'])
+ */
+
 import { type PostHog } from '../posthog-node'
 
+export const severityLevels = ['fatal', 'error', 'warning', 'log', 'info', 'debug'] as const
+export declare type SeverityLevel = (typeof severityLevels)[number]
+
 // 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
 
@@ -11,115 +35,157 @@ import { type PostHog } from '../posthog-node'
 //     EventProcessor as _SentryEventProcessor,
 //     Exception as _SentryException,
 //     Hub as _SentryHub,
-//     Integration as _SentryIntegration,
 //     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 _SentryHub = 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 PostHogSentryExceptionProperties {
+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
-  $exception_type?: string
-  $exception_message?: string
-  $exception_personURL?: string
 }
 
-/**
- * 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/)
- */
-export class PostHogSentryIntegration implements _SentryIntegration {
-  public readonly name = 'posthog-node'
+export type SentryIntegrationOptions = {
+  organization?: string
+  projectId?: number
+  prefix?: string
+  severityAllowList?: SeverityLevel[] | '*'
+}
 
-  public static readonly POSTHOG_ID_TAG = 'posthog_distinct_id'
+const NAME = 'posthog-node'
 
-  public constructor(
-    private readonly posthog: PostHog,
-    private readonly posthogHost?: string,
-    private readonly organization?: string,
-    private readonly prefix?: string
-  ) {
-    this.posthogHost = posthog.options.host ?? 'https://us.i.posthog.com'
-  }
+export function createEventProcessor(
+  _posthog: PostHog,
+  { organization, projectId, prefix, severityAllowList = ['error'] }: 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
+    }
 
-  public setupOnce(
-    addGlobalEventProcessor: (callback: _SentryEventProcessor) => void,
-    getCurrentHub: () => _SentryHub
-  ): void {
-    addGlobalEventProcessor((event: _SentryEvent): _SentryEvent => {
-      if (event.exception?.values === undefined || event.exception.values.length === 0) {
-        return event
-      }
+    const uiHost = _posthog.options.host ?? 'https://us.i.posthog.com'
+    const personUrl = new URL(`/project/${_posthog.apiKey}/person/${userId}`, uiHost).toString()
 
-      if (!event.tags) {
-        event.tags = {}
-      }
+    event.tags['PostHog Person URL'] = personUrl
 
-      const sentry = getCurrentHub()
+    const exceptions: _SentryException[] = event.exception?.values || []
 
-      // 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
+    exceptions.map((exception) => {
+      if (exception.stacktrace) {
+        exception.stacktrace.type = 'raw'
       }
+    })
 
-      event.tags['PostHog Person URL'] = new URL(`/person/${userId}`, this.posthogHost).toString()
-
-      const properties: PostHogSentryExceptionProperties = {
-        // PostHog Exception Properties
-        $exception_message: event.exception.values[0]?.value,
-        $exception_type: event.exception.values[0]?.type,
-        $exception_personURL: event.tags['PostHog Person URL'],
-        // Sentry Exception Properties
-        $sentry_event_id: event.event_id,
-        $sentry_exception: event.exception,
-        $sentry_exception_message: event.exception.values[0]?.value,
-        $sentry_exception_type: event.exception.values[0]?.type,
-        $sentry_tags: event.tags,
-      }
+    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: exceptions,
+      // 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
+    }
+
+    _posthog.capture({ event: '$exception', distinctId: userId, properties })
+
+    return event
+  }
+}
 
-      const projectId = sentry.getClient()?.getDsn()?.projectId
-      if (this.organization !== undefined && projectId !== undefined && event.event_id !== undefined) {
-        properties.$sentry_url = `${this.prefix ?? 'https://sentry.io/organizations'}/${
-          this.organization
-        }/issues/?project=${projectId}&query=${event.event_id}`
-      }
+// V8 integration - function based
+export function sentryIntegration(_posthog: PostHog, options?: SentryIntegrationOptions): _SentryIntegration {
+  const processor = createEventProcessor(_posthog, options)
+  return {
+    name: NAME,
+    processEvent(event) {
+      return processor(event)
+    },
+  }
+}
 
-      this.posthog.capture({ event: '$exception', distinctId: userId, properties })
+// V7 integration - class based
+export class PostHogSentryIntegration implements _SentryIntegrationClass {
+  public readonly name = NAME
 
-      return event
-    })
+  public static readonly POSTHOG_ID_TAG = 'posthog_distinct_id'
+
+  public setupOnce: (
+    addGlobalEventProcessor: (callback: _SentryEventProcessor) => void,
+    getCurrentHub: () => _SentryHub
+  ) => void
+
+  constructor(_posthog: PostHog, organization?: string, prefix?: string, severityAllowList?: SeverityLevel[] | '*') {
+    // 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,
+        })
+      )
+    }
   }
 }

package/src/posthog-node.ts

@@ -294,59 +294,80 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
       disableGeoip?: boolean
     }
   ): Promise<JsonType | undefined> {
-    const { groups, disableGeoip } = options || {}
-    let { onlyEvaluateLocally, sendFeatureFlagEvents, personProperties, groupProperties } = options || {}
+    const { groups, disableGeoip, onlyEvaluateLocally = false, personProperties, groupProperties } = options || {}
 
-    const adjustedProperties = this.addLocalPersonAndGroupProperties(
+    const { allPersonProperties, allGroupProperties } = this.addLocalPersonAndGroupProperties(
       distinctId,
       groups,
       personProperties,
       groupProperties
     )
 
-    personProperties = adjustedProperties.allPersonProperties
-    groupProperties = adjustedProperties.allGroupProperties
-
-    let response = undefined
-
-    // Try to get match value locally if not provided
-    if (!matchValue) {
+    if (matchValue === undefined) {
       matchValue = await this.getFeatureFlag(key, distinctId, {
         ...options,
         onlyEvaluateLocally: true,
+        sendFeatureFlagEvents: false,
       })
     }
 
-    if (matchValue) {
-      response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
-    }
+    let response: string | boolean | undefined
+    let payload: JsonType | undefined
 
-    // set defaults
-    if (onlyEvaluateLocally == undefined) {
-      onlyEvaluateLocally = false
-    }
-    if (sendFeatureFlagEvents == undefined) {
-      sendFeatureFlagEvents = true
+    if (matchValue) {
+      response = matchValue
+      payload = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue)
+    } else {
+      response = undefined
+      payload = undefined
     }
 
-    // set defaults
-    if (onlyEvaluateLocally == undefined) {
-      onlyEvaluateLocally = false
-    }
+    // Determine if the payload was evaluated locally
+    const payloadWasLocallyEvaluated = payload !== undefined
 
-    const payloadWasLocallyEvaluated = response !== undefined
+    // 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
 
-    if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) {
-      response = await super.getFeatureFlagPayloadStateless(
-        key,
+    if (payloadWasLocallyEvaluated || onlyEvaluateLocally) {
+      if (response !== undefined) {
+        fetchedOrLocalFlags = { [key]: response }
+        fetchedOrLocalPayloads = { [key]: payload }
+      } else {
+        fetchedOrLocalFlags = {}
+        fetchedOrLocalPayloads = {}
+      }
+    } else {
+      const fetchedData = await super.getFeatureFlagsAndPayloadsStateless(
         distinctId,
         groups,
-        personProperties,
-        groupProperties,
+        allPersonProperties,
+        allGroupProperties,
         disableGeoip
       )
+      fetchedOrLocalFlags = fetchedData.flags || {}
+      fetchedOrLocalPayloads = fetchedData.payloads || {}
     }
-    return response
+
+    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
   }
 
   async isFeatureEnabled(

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

@@ -39,6 +39,7 @@ const createMockSentryException = (): any => ({
   server_name: 'localhost',
   timestamp: 1704203482.356,
   environment: 'production',
+  level: 'error',
   tags: { posthog_distinct_id: 'EXAMPLE_APP_GLOBAL' },
   breadcrumbs: [
     {
@@ -119,16 +120,25 @@ describe('PostHogSentryIntegration', () => {
         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/person/EXAMPLE_APP_GLOBAL',
+          $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: [] },
+                stacktrace: { frames: [], type: 'raw' },
                 mechanism: { type: 'generic', handled: true },
               },
             ],
@@ -137,7 +147,7 @@ describe('PostHogSentryIntegration', () => {
           $sentry_exception_type: 'Error',
           $sentry_tags: {
             posthog_distinct_id: 'EXAMPLE_APP_GLOBAL',
-            'PostHog Person URL': 'http://example.com/person/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',

package/test/posthog-node.spec.ts

@@ -897,13 +897,18 @@ describe('PostHog Node.js', () => {
                   rollout_percentage: 100,
                 },
               ],
+              payloads: { true: { variant: 'A' } },
             },
           },
         ],
       }
 
       mockedFetch.mockImplementation(
-        apiImplementation({ localFlags: flags, decideFlags: { 'decide-flag': 'decide-value' } })
+        apiImplementation({
+          localFlags: flags,
+          decideFlags: { 'decide-flag': 'decide-value' },
+          decideFlagPayloads: { 'beta-feature': { variant: 'A' } },
+        })
       )
 
       posthog = new PostHog('TEST_API_KEY', {
@@ -945,6 +950,34 @@ 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', {
@@ -1081,7 +1114,7 @@ describe('PostHog Node.js', () => {
       expect(mockedFetch).toHaveBeenCalledTimes(0)
 
       await expect(posthog.getFeatureFlagPayload('false-flag', '123', true)).resolves.toEqual(300)
-      expect(mockedFetch).toHaveBeenCalledTimes(0)
+      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
     })
 
     it('should not double parse json with getFeatureFlagPayloads and server eval', async () => {