posthog-node 4.2.2 → 4.3.0

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

@@ -6,7 +6,7 @@ import { SimpleEventEmitter } from './eventemitter';
 export declare abstract class PostHogCoreStateless {
     readonly apiKey: string;
     readonly host: string;
-    private flushAt;
+    readonly flushAt: number;
     private maxBatchSize;
     private maxQueueSize;
     private flushInterval;

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.2",
+  "version": "4.3.0",
   "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

@@ -174,12 +174,19 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
 
   identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void {
     // Catch properties passed as $set and move them to the top level
-    const personProperties = properties?.$set || properties
+
+    // promote $set and $set_once to top level
+    const userPropsOnce = properties?.$set_once
+    delete properties?.$set_once
+
+    // if no $set is provided we assume all properties are $set
+    const userProps = properties?.$set || properties
 
     super.identifyStateless(
       distinctId,
       {
-        $set: personProperties,
+        $set: userProps,
+        $set_once: userPropsOnce,
       },
       { disableGeoip }
     )

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

@@ -154,9 +154,9 @@ describe('PostHog Node.js', () => {
       ])
     })
 
-    it('should handle identify mistakenly using $set', async () => {
+    it('should handle identify using $set and $set_once', async () => {
       expect(mockedFetch).toHaveBeenCalledTimes(0)
-      posthog.identify({ distinctId: '123', properties: { foo: 'bar', $set: { foo: 'other' } } })
+      posthog.identify({ distinctId: '123', properties: { $set: { foo: 'bar' }, $set_once: { vip: true } } })
       jest.runOnlyPendingTimers()
       await waitForPromises()
       const batchEvents = getLastBatchEvents()
@@ -166,7 +166,33 @@ describe('PostHog Node.js', () => {
           event: '$identify',
           properties: {
             $set: {
-              foo: 'other',
+              foo: 'bar',
+            },
+            $set_once: {
+              vip: true,
+            },
+            $geoip_disable: true,
+          },
+        },
+      ])
+    })
+
+    it('should handle identify using $set_once', async () => {
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+      posthog.identify({ distinctId: '123', properties: { foo: 'bar', $set_once: { vip: true } } })
+      jest.runOnlyPendingTimers()
+      await waitForPromises()
+      const batchEvents = getLastBatchEvents()
+      expect(batchEvents).toMatchObject([
+        {
+          distinct_id: '123',
+          event: '$identify',
+          properties: {
+            $set: {
+              foo: 'bar',
+            },
+            $set_once: {
+              vip: true,
             },
             $geoip_disable: true,
           },