posthog-node 1.1.5 → 1.3.0

package/README.md

@@ -22,3 +22,5 @@ This library is largely based on the `analytics-node` package.
 ## Questions?
 
 ### [Join our Slack community.](https://posthog.com/slack)
+
+

package/event-validation.js

@@ -22,6 +22,10 @@ function eventValidation(event, type) {
             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 + '"')
     }
@@ -53,6 +57,29 @@ function validateAliasEvent(event) {
     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.
  */

package/feature-flags.js

@@ -5,6 +5,17 @@ const version = require('./package.json').version
 
 const LONG_SCALE = 0xfffffffffffffff
 
+class ClientError extends Error {
+    constructor(message, extra) {
+        super()
+        Error.captureStackTrace(this, this.constructor)
+        this.name = 'ClientError'
+        this.message = message
+        if (extra) {
+            this.extra = extra
+        }
+    }
+}
 
 class FeatureFlagsPoller {
     constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host, featureFlagCalledCallback }) {
@@ -21,7 +32,7 @@ class FeatureFlagsPoller {
         void this.loadFeatureFlags()
     }
 
-    async isFeatureEnabled(key, distinctId, defaultResult = false) {
+    async isFeatureEnabled(key, distinctId, defaultResult = false, groups = {}) {
         await this.loadFeatureFlags()
 
         if (!this.loadedSuccessfullyOnce) {
@@ -50,7 +61,7 @@ class FeatureFlagsPoller {
                 rolloutPercentage: featureFlag.rolloutPercentage,
             })
         } else {
-            const res = await this._request({ path: 'decide', method: 'POST', data: { distinct_id: distinctId } })
+            const res = await this._request({ path: 'decide', method: 'POST', data: { groups, distinct_id: distinctId } })
             isFlagEnabledResponse = res.data.featureFlags.indexOf(key) >= 0
         }
 
@@ -72,16 +83,24 @@ class FeatureFlagsPoller {
         }
         this.poller = setTimeout(() => this._loadFeatureFlags(), this.pollingInterval)
 
-        const res = await this._request({ path: 'api/feature_flag', usePersonalApiKey: true })
+        try {
+            const res = await this._request({ path: 'api/feature_flag', usePersonalApiKey: true })
+            if (res && res.status === 401) {
+                throw new ClientError(
+                    `Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview`
+                )
+            }
+
+            this.featureFlags = res.data.results.filter(flag => flag.active)
 
-        if (res && res.status === 401) {
-            throw new Error(
-                `Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview`
-            )
+            this.loadedSuccessfullyOnce = true
+        } catch (err) {
+            // if an error that is not an instance of ClientError is thrown
+            // we silently ignore the error when reloading feature flags
+            if (err instanceof ClientError) {
+                throw err
+            }
         }
-
-        this.featureFlags = res.data.results.filter(flag => flag.active)
-        this.loadedSuccessfullyOnce = true
     }
 
     // sha1('a.b') should equal '69f6642c9d71b463485b4faf4e989dc3fe77a8c6'
@@ -125,9 +144,10 @@ class FeatureFlagsPoller {
             req.timeout = typeof this.timeout === 'string' ? ms(this.timeout) : this.timeout
         }
 
+
         let res
         try {
-            res = await axios(req)
+            res = await axios.request(req)
         } catch (err) {
             throw new Error(`Request to ${path} failed with error: ${err.message}`)
         }

package/index.d.ts

@@ -17,6 +17,16 @@ declare module 'posthog-node' {
 
     interface EventMessage extends IdentifyMessage {
         event: string
+        groups?: Record<string, string | number> // Mapping of group type to group id
+    }
+
+    type GroupType = string
+    type GroupKey = string
+
+    interface GroupIdentifyMessage {
+        groupType: GroupType
+        groupKey: GroupKey // Unique identifier for the group
+        properties?: Record<string | number, any>
     }
 
     export default class PostHog {
@@ -28,9 +38,10 @@ declare module 'posthog-node' {
          * 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 dict with any information you'd like to add
+         * @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.
          */
-        capture({ distinctId, event, properties }: EventMessage): void
+        capture({ distinctId, event, properties, groups }: EventMessage): void
 
         /**
          * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog,
@@ -56,20 +67,31 @@ declare module 'posthog-node' {
 
 
         /**
-         * @description PostHog feature flags (https://posthog.com/docs/features/feature-flags) 
+         * @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 
+         * 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): Promise<boolean>
+        isFeatureEnabled(key: string, distinctId: string, defaultResult?: boolean, groups?: Record<GroupType, GroupKey>): Promise<boolean>
 
 
         /**
-         * @description Force an immediate reload of the polled feature flags. Please note that they are 
+         * @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>

package/index.js

@@ -131,13 +131,18 @@ class PostHog {
     capture(message, callback) {
         this._validate(message, 'capture')
 
-        const apiMessage = Object.assign({}, message, {
-            properties: Object.assign({}, message.properties, {
-                $lib: 'posthog-node',
-                $lib_version: version,
-            }),
+        const properties = Object.assign({}, message.properties, {
+            $lib: 'posthog-node',
+            $lib_version: version,
         })
 
+        if ('groups' in message) {
+            properties.$groups = message.groups
+            delete message.groups
+        }
+
+        const apiMessage = Object.assign({}, message, { properties })
+
         this.enqueue('capture', apiMessage, callback)
         return this
     }
@@ -170,6 +175,30 @@ class PostHog {
         return this
     }
 
+    /**
+     * @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(message, callback) {
+        this._validate(message, 'groupIdentify')
+
+        const captureMessage = {
+            event: '$groupidentify',
+            distinctId: `\$${message.groupType}_${message.groupKey}`,
+            properties: {
+                $group_type: message.groupType,
+                $group_key: message.groupKey,
+                $group_set: message.properties || {}
+            }
+        }
+
+        return this.capture(captureMessage, callback)
+    }
+
     /**
      * Add a `message` of type `type` to the queue and
      * check whether it should be flushed.
@@ -218,9 +247,11 @@ class PostHog {
         }
     }
 
-    async isFeatureEnabled(key, distinctId, defaultResult) {
+    async isFeatureEnabled(key, distinctId, defaultResult = false, groups = {}) {
+        this._validate({ key, distinctId, defaultResult, groups }, 'isFeatureEnabled')
         assert(this.personalApiKey, 'You have to specify the option personalApiKey to use feature flags.')
-        return await this.featureFlagsPoller.isFeatureEnabled(key, distinctId, defaultResult)
+
+        return await this.featureFlagsPoller.isFeatureEnabled(key, distinctId, defaultResult, groups)
     }
 
     async reloadFeatureFlags() {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "posthog-node",
-    "version": "1.1.5",
+    "version": "1.3.0",
     "description": "PostHog Node.js integration",
     "license": "MIT",
     "repository": "PostHog/posthog-node",
@@ -42,7 +42,7 @@
         "funnels"
     ],
     "dependencies": {
-        "axios": "^0.21.1",
+        "axios": "0.24.0",
         "axios-retry": "^3.1.9",
         "component-type": "^1.2.1",
         "join-component": "^1.1.0",
@@ -52,7 +52,7 @@
         "uuid": "^8.3.2"
     },
     "devDependencies": {
-        "ava": "^0.25.0",
+        "ava": "^3.15.0",
         "basic-auth": "^2.0.1",
         "body-parser": "^1.17.1",
         "codecov": "^3.0.0",