posthog-node 4.11.7 → 4.13.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 4.13.0 - 2025-04-21
+
+1. feat: Add method to wait for local evaluation feature flag definitions to be loaded
+
+# 4.12.0 – 2025-04-17
+
+1. chore: roll out new feature flag evaluation backend to majority of customers
+
 # 4.11.7 - 2025-04-16
 
 1. fix: do not reference `node:` prefix as it is not supported by Next.js edge runtime

package/lib/index.cjs.js

@@ -22,7 +22,7 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var version = "4.11.7";
+var version = "4.13.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -194,6 +194,90 @@ const parsePayload = (response) => {
     }
 };
 
+// Rollout constants
+const NEW_FLAGS_ROLLOUT_PERCENTAGE = 1;
+// The fnv1a hashes of the tokens that are explicitly excluded from the rollout
+// see https://github.com/PostHog/posthog-js-lite/blob/main/posthog-core/src/utils.ts#L84
+// are hashed API tokens from our top 10 for each category supported by this SDK.
+const NEW_FLAGS_EXCLUDED_HASHES = new Set([
+    // Node
+    '61be3dd8',
+    '96f6df5f',
+    '8cfdba9b',
+    'bf027177',
+    'e59430a8',
+    '7fa5500b',
+    '569798e9',
+    '04809ff7',
+    '0ebc61a5',
+    '32de7f98',
+    '3beeb69a',
+    '12d34ad9',
+    '733853ec',
+    '0645bb64',
+    '5dcbee21',
+    'b1f95fa3',
+    '2189e408',
+    '82b460c2',
+    '3a8cc979',
+    '29ef8843',
+    '2cdbf767',
+    '38084b54',
+    // React Native
+    '50f9f8de',
+    '41d0df91',
+    '5c236689',
+    'c11aedd3',
+    'ada46672',
+    'f4331ee1',
+    '42fed62a',
+    'c957462c',
+    'd62f705a',
+    // Web (lots of teams per org, hence lots of API tokens)
+    'e0162666',
+    '01b3e5cf',
+    '441cef7f',
+    'bb9cafee',
+    '8f348eb0',
+    'b2553f3a',
+    '97469d7d',
+    '39f21a76',
+    '03706dcc',
+    '27d50569',
+    '307584a7',
+    '6433e92e',
+    '150c7fbb',
+    '49f57f22',
+    '3772f65b',
+    '01eb8256',
+    '3c9e9234',
+    'f853c7f7',
+    'c0ac4b67',
+    'cd609d40',
+    '10ca9b1a',
+    '8a87f11b',
+    '8e8e5216',
+    '1f6b63b3',
+    'db7943dd',
+    '79b7164c',
+    '07f78e33',
+    '2d21b6fd',
+    '952db5ee',
+    'a7d3b43f',
+    '1924dd9c',
+    '84e1b8f6',
+    'dff631b6',
+    'c5aa8a79',
+    'fa133a95',
+    '498a4508',
+    '24748755',
+    '98f3d658',
+    '21bbda67',
+    '7dbfed69',
+    'be3ec24c',
+    'fc80b8e2',
+    '75cc0998',
+]);
 function assert(truthyValue, message) {
     if (!truthyValue || typeof truthyValue !== 'string' || isEmpty(truthyValue)) {
         throw new Error(message);
@@ -244,6 +328,30 @@ function safeSetTimeout(fn, timeout) {
 }
 function getFetch() {
     return typeof fetch !== 'undefined' ? fetch : typeof global.fetch !== 'undefined' ? global.fetch : undefined;
+}
+// FNV-1a hash function
+// https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function
+// I know, I know, I'm rolling my own hash function, but I didn't want to take on
+// a crypto dependency and this is just temporary anyway
+function fnv1a(str) {
+    let hash = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+    }
+    // Convert to hex string, padding to 8 chars
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+function isTokenInRollout(token, percentage = 0, excludedHashes) {
+    const tokenHash = fnv1a(token);
+    // Check excluded hashes (we're explicitly including these tokens from the rollout)
+    if (excludedHashes?.has(tokenHash)) {
+        return false;
+    }
+    // Convert hash to int and divide by max value to get number between 0-1
+    const hashInt = parseInt(tokenHash, 16);
+    const hashFloat = hashInt / 0xffffffff;
+    return hashFloat < percentage;
 }
 
 // Copyright (c) 2013 Pieroxy <pieroxy@pieroxy.net>
@@ -1323,7 +1431,11 @@ class PostHogCoreStateless {
      ***/
     async getDecide(distinctId, groups = {}, personProperties = {}, groupProperties = {}, extraPayload = {}) {
         await this._initPromise;
-        const url = `${this.host}/decide/?v=4`;
+        // Check if the API token is in the new flags rollout
+        // This is a temporary measure to ensure that we can still use the old flags API
+        // while we migrate to the new flags API
+        const useFlags = isTokenInRollout(this.apiKey, NEW_FLAGS_ROLLOUT_PERCENTAGE, NEW_FLAGS_EXCLUDED_HASHES);
+        const url = useFlags ? `${this.host}/flags/?v=2` : `${this.host}/decide/?v=4`;
         const fetchOptions = {
             method: 'POST',
             headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
@@ -1876,6 +1988,7 @@ class FeatureFlagsPoller {
     this.fetch = options.fetch || fetch$1;
     this.onError = options.onError;
     this.customHeaders = customHeaders;
+    this.onLoad = options.onLoad;
     void this.loadFeatureFlags();
   }
   debug(enabled = true) {
@@ -2092,6 +2205,13 @@ class FeatureFlagsPoller {
       await this._loadFeatureFlags();
     }
   }
+  /**
+   * Returns true if the feature flags poller has loaded successfully at least once and has more than 0 feature flags.
+   * This is useful to check if local evaluation is ready before calling getFeatureFlag.
+   */
+  isLocalEvaluationReady() {
+    return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
+  }
   /**
    * If a client is misconfigured with an invalid or improper API key, the polling interval is doubled each time
    * until a successful request is made, up to a maximum of 60 seconds.
@@ -2167,6 +2287,7 @@ class FeatureFlagsPoller {
             this.loadedSuccessfullyOnce = true;
             this.shouldBeginExponentialBackoff = false;
             this.backOffCount = 0;
+            this.onLoad?.(this.featureFlags.length);
             break;
           }
         default:
@@ -2957,16 +3078,28 @@ async function propertiesFromUnknownInput(stackParser, input, hint) {
     handled: true,
     type: 'generic'
   };
-  const error = getError(mechanism, input, hint);
-  const exception = await exceptionFromError(stackParser, error);
-  exception.value = exception.value || '';
-  exception.type = exception.type || 'Error';
-  exception.mechanism = mechanism;
+  const errorList = getErrorList(mechanism, input, hint);
+  const exceptionList = await Promise.all(errorList.map(async error => {
+    const exception = await exceptionFromError(stackParser, error);
+    exception.value = exception.value || '';
+    exception.type = exception.type || 'Error';
+    exception.mechanism = mechanism;
+    return exception;
+  }));
   const properties = {
-    $exception_list: [exception]
+    $exception_list: exceptionList
   };
   return properties;
 }
+// Flatten error causes into a list of errors
+// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+function getErrorList(mechanism, input, hint) {
+  const error = getError(mechanism, input, hint);
+  if (error.cause) {
+    return [error, ...getErrorList(mechanism, error.cause, hint)];
+  }
+  return [error];
+}
 function getError(mechanism, exception, hint) {
   if (isError(exception)) {
     return exception;
@@ -2993,7 +3126,7 @@ function getErrorPropertyFromObject(obj) {
   for (const prop in obj) {
     if (Object.prototype.hasOwnProperty.call(obj, prop)) {
       const value = obj[prop];
-      if (value instanceof Error) {
+      if (isError(value)) {
         return value;
       }
     }
@@ -3420,6 +3553,9 @@ class PostHog extends PostHogCoreStateless {
         onError: err => {
           this._events.emit('error', err);
         },
+        onLoad: count => {
+          this._events.emit('localEvaluationFlagsLoaded', count);
+        },
         customHeaders: this.getCustomHeaders()
       });
     }
@@ -3552,6 +3688,28 @@ class PostHog extends PostHogCoreStateless {
       disableGeoip: data.disableGeoip
     });
   }
+  isLocalEvaluationReady() {
+    return this.featureFlagsPoller?.isLocalEvaluationReady() ?? false;
+  }
+  async waitForLocalEvaluationReady(timeoutMs = THIRTY_SECONDS) {
+    if (this.isLocalEvaluationReady()) {
+      return true;
+    }
+    if (this.featureFlagsPoller === undefined) {
+      return false;
+    }
+    return new Promise(resolve => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        resolve(false);
+      }, timeoutMs);
+      const cleanup = this._events.on('localEvaluationFlagsLoaded', count => {
+        clearTimeout(timeout);
+        cleanup();
+        resolve(count > 0);
+      });
+    });
+  }
   async getFeatureFlag(key, distinctId, options) {
     const {
       groups,
@@ -3729,6 +3887,10 @@ class PostHog extends PostHogCoreStateless {
       disableGeoip
     }, distinctId);
   }
+  /**
+   * Reloads the feature flag definitions from the server for local evaluation.
+   * This is useful to call if you want to ensure that the feature flags are up to date before calling getFeatureFlag.
+   */
   async reloadFeatureFlags() {
     await this.featureFlagsPoller?.loadFeatureFlags(true);
   }