posthog-node 3.2.1 → 3.4.0

package/lib/posthog-node/index.d.ts

@@ -1 +1,2 @@
 export * from './src/posthog-node';
+export * from './src/extensions/sentry-integration';

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

@@ -0,0 +1,40 @@
+/**
+ * @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';
+declare type _SentryEventProcessor = any;
+declare 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.
+ *
+ * ### 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 declare class PostHogSentryIntegration implements _SentryIntegration {
+    private readonly posthog;
+    private readonly posthogHost?;
+    private readonly organization?;
+    private readonly prefix?;
+    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;
+}
+export {};

package/lib/posthog-node/src/feature-flags.d.ts

@@ -55,4 +55,5 @@ declare class FeatureFlagsPoller {
     stopPoller(): void;
 }
 declare function matchProperty(property: FeatureFlagCondition['properties'][number], propertyValues: Record<string, any>): boolean;
-export { FeatureFlagsPoller, matchProperty, InconclusiveMatchError, ClientError };
+declare function relativeDateParseForFeatureFlagMatching(value: string): Date | null;
+export { FeatureFlagsPoller, matchProperty, relativeDateParseForFeatureFlagMatching, InconclusiveMatchError, ClientError, };

package/lib/posthog-node/src/posthog-node.d.ts

@@ -12,7 +12,7 @@ export declare class PostHog extends PostHogCoreStateless implements PostHogNode
     private _memoryStorage;
     private featureFlagsPoller?;
     private maxCacheSize;
-    private options;
+    readonly options: PostHogOptions;
     distinctIdHasSentFlagCalls: Record<string, string[]>;
     constructor(apiKey: string, options?: PostHogOptions);
     getPersistedProperty(key: PostHogPersistedProperty): any | undefined;

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "posthog-node",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "description": "PostHog Node.js integration",
-  "repository": "PostHog/posthog-node",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PostHog/posthog-js-lite.git",
+    "directory": "posthog-node"
+  },
   "scripts": {
     "prepublishOnly": "cd .. && yarn build"
   },

package/src/extensions/sentry-integration.ts

@@ -0,0 +1,125 @@
+/**
+ * @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'
+
+// 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,
+//     Integration as _SentryIntegration,
+//     Primitive as _SentryPrimitive,
+// } 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 _SentryPrimitive = any
+
+interface _SentryIntegration {
+  name: string
+  setupOnce(addGlobalEventProcessor: (callback: _SentryEventProcessor) => void, getCurrentHub: () => _SentryHub): void
+}
+
+interface PostHogSentryExceptionProperties {
+  $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'
+
+  public static readonly POSTHOG_ID_TAG = 'posthog_distinct_id'
+
+  public constructor(
+    private readonly posthog: PostHog,
+    private readonly posthogHost?: string,
+    private readonly organization?: string,
+    private readonly prefix?: string
+  ) {
+    this.posthogHost = posthog.options.host ?? 'https://app.posthog.com'
+  }
+
+  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
+      }
+
+      if (!event.tags) {
+        event.tags = {}
+      }
+
+      const sentry = getCurrentHub()
+
+      // 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
+      }
+
+      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 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}`
+      }
+
+      this.posthog.capture({ event: '$exception', distinctId: userId, properties })
+
+      return event
+    })
+  }
+}

package/src/feature-flags.ts

@@ -464,11 +464,32 @@ function matchProperty(
 
   const overrideValue = propertyValues[key]
 
+  function computeExactMatch(value: any, overrideValue: any): boolean {
+    if (Array.isArray(value)) {
+      return value.map((val) => String(val).toLowerCase()).includes(String(overrideValue).toLowerCase())
+    }
+    return String(value).toLowerCase() === String(overrideValue).toLowerCase()
+  }
+
+  function compare(lhs: any, rhs: any, operator: string): boolean {
+    if (operator === 'gt') {
+      return lhs > rhs
+    } else if (operator === 'gte') {
+      return lhs >= rhs
+    } else if (operator === 'lt') {
+      return lhs < rhs
+    } else if (operator === 'lte') {
+      return lhs <= rhs
+    } else {
+      throw new Error(`Invalid operator: ${operator}`)
+    }
+  }
+
   switch (operator) {
     case 'exact':
-      return Array.isArray(value) ? value.indexOf(overrideValue) !== -1 : value === overrideValue
+      return computeExactMatch(value, overrideValue)
     case 'is_not':
-      return Array.isArray(value) ? value.indexOf(overrideValue) === -1 : value !== overrideValue
+      return !computeExactMatch(value, overrideValue)
     case 'is_set':
       return key in propertyValues
     case 'icontains':
@@ -480,25 +501,54 @@ function matchProperty(
     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
+    case 'lte': {
+      // :TRICKY: We adjust comparison based on the override value passed in,
+      // to make sure we handle both numeric and string comparisons appropriately.
+      let parsedValue = typeof value === 'number' ? value : null
+
+      if (typeof value === 'string') {
+        try {
+          parsedValue = parseFloat(value)
+        } catch (err) {
+          // pass
+        }
+      }
+
+      if (parsedValue != null && overrideValue != null) {
+        // check both null and undefined
+        if (typeof overrideValue === 'string') {
+          return compare(overrideValue, String(value), operator)
+        } else {
+          return compare(overrideValue, parsedValue, operator)
+        }
+      } else {
+        return compare(String(overrideValue), String(value), operator)
+      }
+    }
     case 'is_date_after':
-    case 'is_date_before': {
-      const parsedDate = convertToDateTime(value)
+    case 'is_date_before':
+    case 'is_relative_date_before':
+    case 'is_relative_date_after': {
+      let parsedDate = null
+      if (['is_relative_date_before', 'is_relative_date_after'].includes(operator)) {
+        parsedDate = relativeDateParseForFeatureFlagMatching(String(value))
+      } else {
+        parsedDate = convertToDateTime(value)
+      }
+
+      if (parsedDate == null) {
+        throw new InconclusiveMatchError(`Invalid date: ${value}`)
+      }
       const overrideDate = convertToDateTime(overrideValue)
-      if (operator === 'is_date_before') {
+      if (['is_date_before', 'is_relative_date_before'].includes(operator)) {
         return overrideDate < parsedDate
       }
       return overrideDate > parsedDate
     }
     default:
-      console.error(`Unknown operator: ${operator}`)
-      return false
+      throw new InconclusiveMatchError(`Unknown operator: ${operator}`)
   }
 }
 
@@ -636,4 +686,47 @@ function convertToDateTime(value: string | number | (string | number)[] | Date):
   }
 }
 
-export { FeatureFlagsPoller, matchProperty, InconclusiveMatchError, ClientError }
+function relativeDateParseForFeatureFlagMatching(value: string): Date | null {
+  const regex = /^(?<number>[0-9]+)(?<interval>[a-z])$/
+  const match = value.match(regex)
+  const parsedDt = new Date(new Date().toISOString())
+
+  if (match) {
+    if (!match.groups) {
+      return null
+    }
+
+    const number = parseInt(match.groups['number'])
+
+    if (number >= 10000) {
+      // Guard against overflow, disallow numbers greater than 10_000
+      return null
+    }
+    const interval = match.groups['interval']
+    if (interval == 'h') {
+      parsedDt.setUTCHours(parsedDt.getUTCHours() - number)
+    } else if (interval == 'd') {
+      parsedDt.setUTCDate(parsedDt.getUTCDate() - number)
+    } else if (interval == 'w') {
+      parsedDt.setUTCDate(parsedDt.getUTCDate() - number * 7)
+    } else if (interval == 'm') {
+      parsedDt.setUTCMonth(parsedDt.getUTCMonth() - number)
+    } else if (interval == 'y') {
+      parsedDt.setUTCFullYear(parsedDt.getUTCFullYear() - number)
+    } else {
+      return null
+    }
+
+    return parsedDt
+  } else {
+    return null
+  }
+}
+
+export {
+  FeatureFlagsPoller,
+  matchProperty,
+  relativeDateParseForFeatureFlagMatching,
+  InconclusiveMatchError,
+  ClientError,
+}

package/src/posthog-node.ts

@@ -35,7 +35,7 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
 
   private featureFlagsPoller?: FeatureFlagsPoller
   private maxCacheSize: number
-  private options: PostHogOptions
+  public readonly options: PostHogOptions
 
   distinctIdHasSentFlagCalls: Record<string, string[]>
 

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

@@ -0,0 +1,150 @@
+// import { PostHog } from '../'
+import { PostHog as PostHog } from '../../src/posthog-node'
+import { PostHogSentryIntegration } from '../../src/extensions/sentry-integration'
+jest.mock('../../src/fetch')
+import fetch from '../../src/fetch'
+
+jest.mock('../../package.json', () => ({ version: '1.2.3' }))
+
+const mockedFetch = jest.mocked(fetch, true)
+
+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',
+  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.shutdownAsync()
+  })
+
+  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())
+
+    jest.runOnlyPendingTimers()
+    const batchEvents = getLastBatchEvents()
+
+    expect(batchEvents).toEqual([
+      {
+        distinct_id: 'EXAMPLE_APP_GLOBAL',
+        event: '$exception',
+        properties: {
+          $exception_message: 'example error',
+          $exception_type: 'Error',
+          $exception_personURL: 'http://example.com/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/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),
+      },
+    ])
+  })
+})