posthog-node 1.3.0 → 2.0.0-alpha3

package/package.json

@@ -1,69 +1,37 @@
 {
-    "name": "posthog-node",
-    "version": "1.3.0",
-    "description": "PostHog Node.js integration",
-    "license": "MIT",
-    "repository": "PostHog/posthog-node",
-    "author": {
-        "name": "PostHog",
-        "email": "hey@posthog.com",
-        "url": "https://posthog.com"
-    },
-    "engines": {
-        "node": ">=4"
-    },
-    "size-limit": [
-        {
-            "limit": "25 KB",
-            "path": "index.js"
-        }
-    ],
-    "scripts": {
-        "dependencies": "yarn",
-        "size": "size-limit",
-        "test": "nyc ava tests/*.js",
-        "report-coverage": "nyc report --reporter=lcov > coverage.lcov && codecov",
-        "format": "prettier --write ."
-    },
-    "files": [
-        "index.js",
-        "index.d.ts",
-        "event-validation.js",
-        "cli.js",
-        "feature-flags.js"
-    ],
-    "bin": {
-        "posthog": "cli.js"
-    },
-    "keywords": [
-        "posthog",
-        "stats",
-        "analysis",
-        "funnels"
-    ],
-    "dependencies": {
-        "axios": "0.24.0",
-        "axios-retry": "^3.1.9",
-        "component-type": "^1.2.1",
-        "join-component": "^1.1.0",
-        "md5": "^2.3.0",
-        "ms": "^2.1.3",
-        "remove-trailing-slash": "^0.1.1",
-        "uuid": "^8.3.2"
-    },
-    "devDependencies": {
-        "ava": "^3.15.0",
-        "basic-auth": "^2.0.1",
-        "body-parser": "^1.17.1",
-        "codecov": "^3.0.0",
-        "commander": "^2.9.0",
-        "delay": "^4.2.0",
-        "express": "^4.15.2",
-        "nyc": "^14.1.1",
-        "pify": "^4.0.1",
-        "prettier": "^2.3.1",
-        "sinon": "^7.3.2",
-        "size-limit": "^1.3.5",
-        "snyk": "^1.171.1"
-    }
+  "name": "posthog-node",
+  "version": "2.0.0-alpha3",
+  "description": "PostHog Node.js integration",
+  "repository": "PostHog/posthog-node",
+  "scripts": {
+    "prepublish": "cd .. && yarn build"
+  },
+  "engines": {
+    "node": ">=10"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "PostHog",
+    "email": "hey@posthog.com",
+    "url": "https://posthog.com"
+  },
+  "main": "lib/index.cjs.js",
+  "module": "lib/index.esm.js",
+  "types": "lib/index.d.ts",
+  "dependencies": {
+    "undici": "^5.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "commander": "^9.3.0"
+  },
+  "keywords": [
+    "posthog",
+    "stats",
+    "analysis",
+    "funnels"
+  ],
+  "bin": {
+    "posthog": "cli.js"
+  }
 }

package/src/posthog-node.ts

@@ -0,0 +1,133 @@
+import { version } from '../package.json'
+import undici from 'undici'
+import {
+  PostHogCore,
+  PosthogCoreOptions,
+  PostHogFetchOptions,
+  PostHogFetchResponse,
+  PostHogPersistedProperty,
+} from '../../posthog-core/src'
+import { EventMessageV1, GroupIdentifyMessage, IdentifyMessageV1, PostHogNodeV1 } from './types'
+
+export type PostHogOptions = PosthogCoreOptions
+
+class PostHog extends PostHogCore {
+  private _memoryStorage: { [key: string]: any | undefined } = {}
+
+  constructor(apiKey: string, options: PostHogOptions = {}) {
+    options.captureMode = options?.captureMode || 'json'
+    options.preloadFeatureFlags = false // Don't preload as this makes no sense without a distinctId
+
+    super(apiKey, options)
+  }
+
+  getPersistedProperty(key: PostHogPersistedProperty): any | undefined {
+    return this._memoryStorage[key]
+  }
+
+  setPersistedProperty(key: PostHogPersistedProperty, value: any | null): void {
+    this._memoryStorage[key] = value !== null ? value : undefined
+  }
+
+  getSessionId(): string | undefined {
+    // Sessions don't make sense for Node
+    return undefined
+  }
+
+  fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse> {
+    return undici.fetch(url, options)
+  }
+
+  getLibraryId(): string {
+    return 'posthog-node'
+  }
+  getLibraryVersion(): string {
+    return version
+  }
+  getCustomUserAgent(): string {
+    return `posthog-node/${version}`
+  }
+}
+
+// The actual exported Nodejs API.
+export class PostHogGlobal implements PostHogNodeV1 {
+  private _sharedClient: PostHog
+
+  constructor(apiKey: string, options: PostHogOptions = {}) {
+    options.decidePollInterval = 0 // Forcefully set to 0 so we don't auto-reload
+    this._sharedClient = new PostHog(apiKey, options)
+  }
+
+  private reInit(distinctId: string): void {
+    // Remove all state except the queue
+    const queue = this._sharedClient.getPersistedProperty(PostHogPersistedProperty.Queue)
+    this._sharedClient.reset()
+    this._sharedClient.setPersistedProperty(PostHogPersistedProperty.Queue, queue)
+    this._sharedClient.setPersistedProperty(PostHogPersistedProperty.DistinctId, distinctId)
+  }
+
+  enable(): void {
+    return this._sharedClient.optIn()
+  }
+
+  disable(): void {
+    return this._sharedClient.optOut()
+  }
+
+  capture({ distinctId, event, properties, groups }: EventMessageV1): void {
+    this.reInit(distinctId)
+    if (groups) {
+      this._sharedClient.groups(groups)
+    }
+    this._sharedClient.capture(event, properties)
+  }
+
+  identify({ distinctId, properties }: IdentifyMessageV1): void {
+    this.reInit(distinctId)
+    this._sharedClient.identify(distinctId, properties)
+  }
+
+  alias(data: { distinctId: string; alias: string }): void {
+    this.reInit(data.distinctId)
+    this._sharedClient.alias(data.alias)
+  }
+
+  async getFeatureFlag(
+    key: string,
+    distinctId: string,
+    groups?: Record<string, string> | undefined
+  ): Promise<string | boolean | undefined> {
+    this.reInit(distinctId)
+    if (groups) {
+      this._sharedClient.groups(groups)
+    }
+    await this._sharedClient.reloadFeatureFlagsAsync()
+    return this._sharedClient.getFeatureFlag(key)
+  }
+
+  async isFeatureEnabled(
+    key: string,
+    distinctId: string,
+    defaultResult?: boolean | undefined,
+    groups?: Record<string, string> | undefined
+  ): Promise<boolean> {
+    const feat = this.getFeatureFlag(key, distinctId, groups)
+    return !!feat || defaultResult || false
+  }
+
+  groupIdentify({ groupType, groupKey, properties }: GroupIdentifyMessage): void {
+    this._sharedClient.groupIdentify(groupType, groupKey, properties)
+  }
+
+  reloadFeatureFlags(): Promise<void> {
+    throw new Error('Method not implemented.')
+  }
+
+  shutdown(): void {
+    void this._sharedClient.shutdownAsync()
+  }
+
+  shutdownAsync(): Promise<void> {
+    return this._sharedClient.shutdownAsync()
+  }
+}

package/src/types.ts

@@ -0,0 +1,99 @@
+export interface IdentifyMessageV1 {
+  distinctId: string
+  properties?: Record<string | number, any>
+}
+
+export interface EventMessageV1 extends IdentifyMessageV1 {
+  event: string
+  groups?: Record<string, string | number> // Mapping of group type to group id
+  sendFeatureFlags?: boolean
+}
+
+export interface GroupIdentifyMessage {
+  groupType: string
+  groupKey: string // Unique identifier for the group
+  properties?: Record<string | number, any>
+}
+
+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
+   */
+  capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessageV1): 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 }: IdentifyMessageV1): 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.
+   * IMPORTANT: To use this method, you need to specify `personalApiKey` in your config! More info: https://posthog.com/docs/api/overview
+   * @param key the unique key of your feature flag
+   * @param distinctId the current unique id
+   * @param defaultResult optional - default value to be returned if the feature flag is not on for the user
+   * @param groups optional - what groups are currently active (group analytics)
+   */
+  isFeatureEnabled(
+    key: string,
+    distinctId: string,
+    defaultResult?: boolean,
+    groups?: Record<string, string>
+  ): Promise<boolean>
+
+  getFeatureFlag(
+    key: string,
+    distinctId: string,
+    groups?: Record<string, string>
+  ): Promise<string | boolean | 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.
+   */
+  shutdown(): void
+}

package/test/posthog-node.spec.ts

@@ -0,0 +1,92 @@
+import PostHog from '../'
+jest.mock('undici')
+import undici from 'undici'
+
+const mockedUndici = jest.mocked(undici, true)
+
+const getLastBatchEvents = (): any[] | undefined => {
+  expect(mockedUndici.fetch).toHaveBeenCalledWith(
+    'http://example.com/batch/',
+    expect.objectContaining({ method: 'POST' })
+  )
+
+  const call = mockedUndici.fetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+  if (!call) {
+    return undefined
+  }
+  return JSON.parse((call[1] as any).body as any).batch
+}
+
+describe('PostHog Core', () => {
+  let posthog: PostHog
+
+  jest.useFakeTimers()
+
+  beforeEach(() => {
+    posthog = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+    })
+
+    mockedUndici.fetch.mockResolvedValue({
+      status: 200,
+      text: () => Promise.resolve('ok'),
+      json: () =>
+        Promise.resolve({
+          status: 'ok',
+        }),
+    } as any)
+  })
+
+  describe('legacy methods', () => {
+    it('should capture an event to shared queue', async () => {
+      expect(mockedUndici.fetch).toHaveBeenCalledTimes(0)
+      posthog.capture({ distinctId: '123', event: 'test-event', properties: { foo: 'bar' }, groups: { org: 123 } })
+
+      jest.runOnlyPendingTimers()
+      const batchEvents = getLastBatchEvents()
+      expect(batchEvents).toMatchObject([
+        {
+          distinct_id: '123',
+          event: 'test-event',
+          properties: {
+            $groups: { org: 123 },
+            foo: 'bar',
+          },
+        },
+      ])
+    })
+
+    it('should capture identify events on shared queue', async () => {
+      expect(mockedUndici.fetch).toHaveBeenCalledTimes(0)
+      posthog.identify({ distinctId: '123', properties: { foo: 'bar' } })
+      jest.runOnlyPendingTimers()
+      const batchEvents = getLastBatchEvents()
+      expect(batchEvents).toMatchObject([
+        {
+          distinct_id: '123',
+          event: '$identify',
+          properties: {
+            foo: 'bar',
+          },
+        },
+      ])
+    })
+
+    it('should capture alias events on shared queue', async () => {
+      expect(mockedUndici.fetch).toHaveBeenCalledTimes(0)
+      posthog.alias({ distinctId: '123', alias: '1234' })
+      jest.runOnlyPendingTimers()
+      const batchEvents = getLastBatchEvents()
+      expect(batchEvents).toMatchObject([
+        {
+          distinct_id: '123',
+          event: '$create_alias',
+          properties: {
+            distinct_id: '123',
+            alias: '1234',
+          },
+        },
+      ])
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "types": ["node"]
+  }
+}

package/LICENSE

@@ -1,21 +0,0 @@
-Copyright (c) 2020 PostHog (part of Hiberly Inc)
-
-Copyright (c) 2013 Segment Inc. friends@segment.com
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/cli.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-'use strict'
-
-const program = require('commander')
-const PostHog = require('.')
-const pkg = require('./package')
-
-const toObject = (str) => JSON.parse(str)
-
-program
-    .version(pkg.version)
-    .option('-k, --apiKey <key>', 'the PostHog api key to use')
-    .option('-h, --host <host>', 'the PostHog API hostname to use')
-    .option('-t, --type <type>', 'the PostHog message type')
-
-    .option('-d, --distinctId <id>', 'the distinct id to send the event as')
-
-    .option('-e, --event <event>', 'the event name to send with the event')
-    .option('-p, --properties <properties>', 'the event properties to send (JSON-encoded)', toObject)
-
-    .option('-a, --alias <previousId>', 'alias for the distinct id')
-
-    .parse(process.argv)
-
-if (program.args.length !== 0) {
-    program.help()
-}
-
-const apiKey = program.apiKey
-const host = program.host
-const type = program.type
-
-const distinctId = program.distinctId
-
-const event = program.event
-const properties = program.properties
-const alias = program.alias
-
-const run = (method, args) => {
-    const posthog = new PostHog(apiKey, { host, flushAt: 1 })
-    posthog[method](args, (err) => {
-        if (err) {
-            console.error(err.stack)
-            process.exit(1)
-        }
-    })
-}
-
-switch (type) {
-    case 'capture':
-        run('capture', {
-            event,
-            properties,
-            distinctId,
-        })
-        break
-    case 'identify':
-        run('identify', {
-            properties,
-            distinctId,
-        })
-        break
-    case 'alias':
-        run('alias', {
-            alias,
-            distinctId,
-        })
-        break
-    default:
-        console.error('invalid type:', type)
-        process.exit(1)
-}

package/event-validation.js

@@ -1,121 +0,0 @@
-var type = require('component-type')
-var join = require('join-component')
-var assert = require('assert')
-
-// PostHog messages can be a maximum of 32 kB.
-var MAX_SIZE = 32 << 10
-
-module.exports = eventValidation
-
-/**
- * Validate an event.
- */
-
-function eventValidation(event, type) {
-    validateGenericEvent(event)
-    type = type || event.type
-    assert(type, 'You must pass an event type.')
-    switch (type) {
-        case 'capture':
-            return validateCaptureEvent(event)
-        case 'identify':
-            return validateIdentifyEvent(event)
-        case 'alias':
-            return validateAliasEvent(event)
-        case 'groupIdentify':
-            return validateGroupIdentifyEvent(event)
-        case 'isFeatureEnabled':
-            return validateIsFeatureEnabled(event)
-        default:
-            assert(0, 'Invalid event type: "' + type + '"')
-    }
-}
-
-/**
- * Validate a "capture" event.
- */
-
-function validateCaptureEvent(event) {
-    assert(event.distinctId, 'You must pass a "distinctId".')
-    assert(event.event, 'You must pass an "event".')
-}
-
-/**
- * Validate a "identify" event.
- */
-
-function validateIdentifyEvent(event) {
-    assert(event.distinctId, 'You must pass a "distinctId".')
-}
-
-/**
- * Validate an "alias" event.
- */
-
-function validateAliasEvent(event) {
-    assert(event.distinctId, 'You must pass a "distinctId".')
-    assert(event.alias, 'You must pass a "alias".')
-}
-
-/**
- * Validate an "groupIdentify" event.
- */
-
- function validateGroupIdentifyEvent(event) {
-    assert(event.groupType, 'You must pass a "groupType".')
-    assert(event.groupKey, 'You must pass a "groupKey".')
-}
-
-/**
- * Validate a "isFeatureEnabled" call
- */
-
- function validateIsFeatureEnabled(event) {
-    assert(event.key, 'You must pass a "key".')
-    assert(event.distinctId, 'You must pass a "distinctId".')
-    assert(type(event.defaultResult) == 'boolean', '"defaultResult" must be a boolean.')
-    if (event.groups) {
-        assert(type(event.groups) == 'object', 'You must pass an object for "groups".')
-    }
-}
-
-
-/**
- * Validation rules.
- */
-
-var genericValidationRules = {
-    event: 'string',
-    properties: 'object',
-    alias: 'string',
-    timestamp: 'date',
-    distinctId: 'string',
-    type: 'string',
-}
-
-/**
- * Validate an event object.
- */
-
-function validateGenericEvent(event) {
-    assert(type(event) === 'object', 'You must pass a message object.')
-    var json = JSON.stringify(event)
-    // Strings are variable byte encoded, so json.length is not sufficient.
-    assert(Buffer.byteLength(json, 'utf8') < MAX_SIZE, 'Your message must be < 32 kB.')
-
-    for (var key in genericValidationRules) {
-        var val = event[key]
-        if (!val) continue
-        var rule = genericValidationRules[key]
-        if (type(rule) !== 'array') {
-            rule = [rule]
-        }
-        var a = rule[0] === 'object' ? 'an' : 'a'
-        assert(
-            rule.some(function (e) {
-                return type(val) === e
-            }),
-            '"' + key + '" must be ' + a + ' ' + join(rule, 'or') + '.'
-        )
-    }
-}