posthog-node 4.14.0 → 4.15.0

package/lib/index.d.ts

@@ -441,12 +441,19 @@ declare abstract class PostHogCoreStateless {
      *** TRACKING
      ***/
     protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    protected identifyStatelessImmediate(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
     }, options?: PostHogCaptureOptions): void;
+    protected captureStatelessImmediate(distinctId: string, event: string, properties?: {
+        [key: string]: any;
+    }, options?: PostHogCaptureOptions): Promise<void>;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
     }, options?: PostHogCaptureOptions): void;
+    protected aliasStatelessImmediate(alias: string, distinctId: string, properties?: {
+        [key: string]: any;
+    }, options?: PostHogCaptureOptions): Promise<void>;
     /***
      *** GROUPS
      ***/
@@ -495,6 +502,8 @@ declare abstract class PostHogCoreStateless {
      *** QUEUEING AND FLUSHING
      ***/
     protected enqueue(type: string, _message: any, options?: PostHogCaptureOptions): void;
+    protected sendImmediate(type: string, _message: any, options?: PostHogCaptureOptions): Promise<void>;
+    private prepareMessage;
     private clearFlushTimer;
     /**
      * Helper for flushing the queue in the background
@@ -542,6 +551,15 @@ type PostHogNodeV1 = {
      * @param sendFeatureFlags OPTIONAL | Used with experiments. Determines whether to send feature flag values with the event.
      */
     capture({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): void;
+    /**
+     * @description Capture an event immediately. Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+     * @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. Determines whether to send feature flag values with the event.
+     */
+    captureImmediate({ distinctId, event, properties, groups, sendFeatureFlags }: EventMessage): Promise<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.
@@ -550,6 +568,13 @@ type PostHogNodeV1 = {
      * @param properties with a dict with any key: value pairs
      */
     identify({ distinctId, properties }: IdentifyMessage): void;
+    /**
+     * @description Identify lets you add metadata on your users so you can more easily identify who they are in PostHog.
+     * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+     * @param distinctId which uniquely identifies your user
+     * @param properties with a dict with any key: value pairs
+     */
+    identifyImmediate({ distinctId, properties }: IdentifyMessage): Promise<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?"
@@ -565,6 +590,16 @@ type PostHogNodeV1 = {
         distinctId: string;
         alias: string;
     }): 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.
+     * Useful for edge environments where the usual queue-based sending is not preferable. Do not mix immediate and non-immediate calls.
+     * @param distinctId the current unique id
+     * @param alias the unique ID of the user before
+     */
+    aliasImmediate(data: {
+        distinctId: string;
+        alias: string;
+    }): Promise<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,
@@ -726,12 +761,19 @@ declare class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
     disable(): Promise<void>;
     debug(enabled?: boolean): void;
     capture(props: EventMessage): void;
+    captureImmediate(props: EventMessage): Promise<void>;
     identify({ distinctId, properties, disableGeoip }: IdentifyMessage): void;
+    identifyImmediate({ distinctId, properties, disableGeoip }: IdentifyMessage): Promise<void>;
     alias(data: {
         distinctId: string;
         alias: string;
         disableGeoip?: boolean;
     }): void;
+    aliasImmediate(data: {
+        distinctId: string;
+        alias: string;
+        disableGeoip?: boolean;
+    }): Promise<void>;
     isLocalEvaluationReady(): boolean;
     waitForLocalEvaluationReady(timeoutMs?: number): Promise<boolean>;
     getFeatureFlag(key: string, distinctId: string, options?: {

package/lib/index.esm.js

@@ -1,6 +1,6 @@
 import { posix, dirname, sep } from 'path';
 
-var version = "4.14.0";
+var version = "4.15.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -256,6 +256,7 @@ const NEW_FLAGS_EXCLUDED_HASHES = new Set([
     'fc80b8e2',
     '75cc0998',
 ]);
+const STRING_FORMAT = 'utf8';
 function assert(truthyValue, message) {
     if (!truthyValue || typeof truthyValue !== 'string' || isEmpty(truthyValue)) {
         throw new Error(message);
@@ -1194,11 +1195,21 @@ const uuidv7 = () => uuidv7obj().toString();
 const uuidv7obj = () => (defaultGenerator || (defaultGenerator = new V7Generator())).generate();
 
 class PostHogFetchHttpError extends Error {
-    constructor(response) {
-        super('HTTP error while fetching PostHog: ' + response.status);
+    constructor(response, reqByteLength) {
+        super('HTTP error while fetching PostHog: status=' + response.status + ', reqByteLength=' + reqByteLength);
         this.response = response;
+        this.reqByteLength = reqByteLength;
         this.name = 'PostHogFetchHttpError';
     }
+    get status() {
+        return this.response.status;
+    }
+    get text() {
+        return this.response.text();
+    }
+    get json() {
+        return this.response.json();
+    }
 }
 class PostHogFetchNetworkError extends Error {
     constructor(error) {
@@ -1210,6 +1221,20 @@ class PostHogFetchNetworkError extends Error {
         this.name = 'PostHogFetchNetworkError';
     }
 }
+async function logFlushError(err) {
+    if (err instanceof PostHogFetchHttpError) {
+        let text = '';
+        try {
+            text = await err.text;
+        }
+        catch { }
+        console.error(`Error while flushing PostHog: message=${err.message}, response body=${text}`, err);
+    }
+    else {
+        console.error('Error while flushing PostHog', err);
+    }
+    return Promise.resolve();
+}
 function isPostHogFetchError(err) {
     return typeof err === 'object' && (err instanceof PostHogFetchHttpError || err instanceof PostHogFetchNetworkError);
 }
@@ -1343,12 +1368,26 @@ class PostHogCoreStateless {
             this.enqueue('identify', payload, options);
         });
     }
+    async identifyStatelessImmediate(distinctId, properties, options) {
+        const payload = {
+            ...this.buildPayload({
+                distinct_id: distinctId,
+                event: '$identify',
+                properties,
+            }),
+        };
+        await this.sendImmediate('identify', payload, options);
+    }
     captureStateless(distinctId, event, properties, options) {
         this.wrap(() => {
             const payload = this.buildPayload({ distinct_id: distinctId, event, properties });
             this.enqueue('capture', payload, options);
         });
     }
+    async captureStatelessImmediate(distinctId, event, properties, options) {
+        const payload = this.buildPayload({ distinct_id: distinctId, event, properties });
+        await this.sendImmediate('capture', payload, options);
+    }
     aliasStateless(alias, distinctId, properties, options) {
         this.wrap(() => {
             const payload = this.buildPayload({
@@ -1363,6 +1402,18 @@ class PostHogCoreStateless {
             this.enqueue('alias', payload, options);
         });
     }
+    async aliasStatelessImmediate(alias, distinctId, properties, options) {
+        const payload = this.buildPayload({
+            event: '$create_alias',
+            distinct_id: distinctId,
+            properties: {
+                ...(properties || {}),
+                distinct_id: distinctId,
+                alias,
+            },
+        });
+        await this.sendImmediate('alias', payload, options);
+    }
     /***
      *** GROUPS
      ***/
@@ -1606,25 +1657,7 @@ class PostHogCoreStateless {
                 this._events.emit(type, `Library is disabled. Not sending event. To re-enable, call posthog.optIn()`);
                 return;
             }
-            const message = {
-                ..._message,
-                type: type,
-                library: this.getLibraryId(),
-                library_version: this.getLibraryVersion(),
-                timestamp: options?.timestamp ? options?.timestamp : currentISOTime(),
-                uuid: options?.uuid ? options.uuid : uuidv7(),
-            };
-            const addGeoipDisableProperty = options?.disableGeoip ?? this.disableGeoip;
-            if (addGeoipDisableProperty) {
-                if (!message.properties) {
-                    message.properties = {};
-                }
-                message['properties']['$geoip_disable'] = true;
-            }
-            if (message.distinctId) {
-                message.distinct_id = message.distinctId;
-                delete message.distinctId;
-            }
+            const message = this.prepareMessage(type, _message, options);
             const queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
             if (queue.length >= this.maxQueueSize) {
                 queue.shift();
@@ -1642,6 +1675,73 @@ class PostHogCoreStateless {
             }
         });
     }
+    async sendImmediate(type, _message, options) {
+        if (this.disabled) {
+            this.logMsgIfDebug(() => console.warn('[PostHog] The client is disabled'));
+            return;
+        }
+        if (!this._isInitialized) {
+            await this._initPromise;
+        }
+        if (this.optedOut) {
+            this._events.emit(type, `Library is disabled. Not sending event. To re-enable, call posthog.optIn()`);
+            return;
+        }
+        const data = {
+            api_key: this.apiKey,
+            batch: [this.prepareMessage(type, _message, options)],
+            sent_at: currentISOTime(),
+        };
+        if (this.historicalMigration) {
+            data.historical_migration = true;
+        }
+        const payload = JSON.stringify(data);
+        const url = this.captureMode === 'form'
+            ? `${this.host}/e/?ip=1&_=${currentTimestamp()}&v=${this.getLibraryVersion()}`
+            : `${this.host}/batch/`;
+        const fetchOptions = this.captureMode === 'form'
+            ? {
+                method: 'POST',
+                mode: 'no-cors',
+                credentials: 'omit',
+                headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: `data=${encodeURIComponent(LZString.compressToBase64(payload))}&compression=lz64`,
+            }
+            : {
+                method: 'POST',
+                headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
+                body: payload,
+            };
+        try {
+            await this.fetchWithRetry(url, fetchOptions);
+        }
+        catch (err) {
+            this._events.emit('error', err);
+            throw err;
+        }
+    }
+    prepareMessage(type, _message, options) {
+        const message = {
+            ..._message,
+            type: type,
+            library: this.getLibraryId(),
+            library_version: this.getLibraryVersion(),
+            timestamp: options?.timestamp ? options?.timestamp : currentISOTime(),
+            uuid: options?.uuid ? options.uuid : uuidv7(),
+        };
+        const addGeoipDisableProperty = options?.disableGeoip ?? this.disableGeoip;
+        if (addGeoipDisableProperty) {
+            if (!message.properties) {
+                message.properties = {};
+            }
+            message['properties']['$geoip_disable'] = true;
+        }
+        if (message.distinctId) {
+            message.distinct_id = message.distinctId;
+            delete message.distinctId;
+        }
+        return message;
+    }
     clearFlushTimer() {
         if (this._flushTimer) {
             clearTimeout(this._flushTimer);
@@ -1653,7 +1753,9 @@ class PostHogCoreStateless {
      * Avoids unnecessary promise errors
      */
     flushBackground() {
-        void this.flush().catch(() => { });
+        void this.flush().catch(async (err) => {
+            await logFlushError(err);
+        });
     }
     async flush() {
         if (!this.flushPromise) {
@@ -1737,6 +1839,8 @@ class PostHogCoreStateless {
             setTimeout(() => ctrl.abort(), ms);
             return ctrl.signal;
         });
+        const body = options.body ? options.body : '';
+        const reqByteLength = Buffer.byteLength(body, STRING_FORMAT);
         return await retriable(async () => {
             let res = null;
             try {
@@ -1754,7 +1858,7 @@ class PostHogCoreStateless {
             // https://developer.mozilla.org/en-US/docs/Web/API/Request/mode#no-cors
             const isNoCors = options.mode === 'no-cors';
             if (!isNoCors && (res.status < 200 || res.status >= 400)) {
-                throw new PostHogFetchHttpError(res);
+                throw new PostHogFetchHttpError(res, reqByteLength);
             }
             return res;
         }, { ...this._retryOptions, ...retryOptions });
@@ -1786,7 +1890,7 @@ class PostHogCoreStateless {
                 if (!isPostHogFetchError(e)) {
                     throw e;
                 }
-                this.logMsgIfDebug(() => console.error('Error while shutting down PostHog', e));
+                await logFlushError(e);
             }
         };
         return Promise.race([
@@ -3667,6 +3771,79 @@ class PostHog extends PostHogCoreStateless {
     });
     this.addPendingPromise(capturePromise);
   }
+  async captureImmediate(props) {
+    if (typeof props === 'string') {
+      this.logMsgIfDebug(() => console.warn('Called capture() with a string as the first argument when an object was expected.'));
+    }
+    const {
+      distinctId,
+      event,
+      properties,
+      groups,
+      sendFeatureFlags,
+      timestamp,
+      disableGeoip,
+      uuid
+    } = props;
+    const _capture = props => {
+      return super.captureStatelessImmediate(distinctId, event, props, {
+        timestamp,
+        disableGeoip,
+        uuid
+      });
+    };
+    const _getFlags = async (distinctId, groups, disableGeoip) => {
+      return (await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)).flags;
+    };
+    const capturePromise = Promise.resolve().then(async () => {
+      if (sendFeatureFlags) {
+        // If we are sending feature flags, we need to make sure we have the latest flags
+        // return await super.getFeatureFlagsStateless(distinctId, groups, undefined, undefined, disableGeoip)
+        return await _getFlags(distinctId, groups, disableGeoip);
+      }
+      if (event === '$feature_flag_called') {
+        // If we're capturing a $feature_flag_called event, we don't want to enrich the event with cached flags that may be out of date.
+        return {};
+      }
+      if ((this.featureFlagsPoller?.featureFlags?.length || 0) > 0) {
+        // Otherwise we may as well check for the flags locally and include them if they are already loaded
+        const groupsWithStringValues = {};
+        for (const [key, value] of Object.entries(groups || {})) {
+          groupsWithStringValues[key] = String(value);
+        }
+        return await this.getAllFlags(distinctId, {
+          groups: groupsWithStringValues,
+          disableGeoip,
+          onlyEvaluateLocally: true
+        });
+      }
+      return {};
+    }).then(flags => {
+      // Derive the relevant flag properties to add
+      const additionalProperties = {};
+      if (flags) {
+        for (const [feature, variant] of Object.entries(flags)) {
+          additionalProperties[`$feature/${feature}`] = variant;
+        }
+      }
+      const activeFlags = Object.keys(flags || {}).filter(flag => flags?.[flag] !== false).sort();
+      if (activeFlags.length > 0) {
+        additionalProperties['$active_feature_flags'] = activeFlags;
+      }
+      return additionalProperties;
+    }).catch(() => {
+      // Something went wrong getting the flag info - we should capture the event anyways
+      return {};
+    }).then(additionalProperties => {
+      // No matter what - capture the event
+      _capture({
+        ...additionalProperties,
+        ...properties,
+        $groups: groups
+      });
+    });
+    await capturePromise;
+  }
   identify({
     distinctId,
     properties,
@@ -3685,11 +3862,33 @@ class PostHog extends PostHogCoreStateless {
       disableGeoip
     });
   }
+  async identifyImmediate({
+    distinctId,
+    properties,
+    disableGeoip
+  }) {
+    // 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;
+    await super.identifyStatelessImmediate(distinctId, {
+      $set: userProps,
+      $set_once: userPropsOnce
+    }, {
+      disableGeoip
+    });
+  }
   alias(data) {
     super.aliasStateless(data.alias, data.distinctId, undefined, {
       disableGeoip: data.disableGeoip
     });
   }
+  async aliasImmediate(data) {
+    await super.aliasStatelessImmediate(data.alias, data.distinctId, undefined, {
+      disableGeoip: data.disableGeoip
+    });
+  }
   isLocalEvaluationReady() {
     return this.featureFlagsPoller?.isLocalEvaluationReady() ?? false;
   }