posthog-node 5.7.0 → 5.8.0

package/dist/node/index.mjs

@@ -1,7 +1,7 @@
 import { dirname, posix, sep } from 'path';
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
-import { safeSetTimeout, PostHogCoreStateless, getFeatureFlagValue } from '@posthog/core';
+import { PostHogCoreStateless, getFeatureFlagValue } from '@posthog/core';
 
 /**
  * @file Adapted from [posthog-js](https://github.com/PostHog/posthog-js/blob/8157df935a4d0e71d2fefef7127aa85ee51c82d1/src/extensions/sentry-integration.ts) with modifications for the Node SDK.
@@ -623,6 +623,71 @@ function applyChunkIds(frames, parser) {
   return frames;
 }
 
+const ObjProto = Object.prototype;
+const type_utils_toString = ObjProto.toString;
+const isNumber = (x)=>'[object Number]' == type_utils_toString.call(x);
+
+function clampToRange(value, min, max, logger, fallbackValue) {
+    if (min > max) {
+        logger.warn('min cannot be greater than max.');
+        min = max;
+    }
+    if (isNumber(value)) if (value > max) {
+        logger.warn(' cannot be  greater than max: ' + max + '. Using max value instead.');
+        return max;
+    } else {
+        if (!(value < min)) return value;
+        logger.warn(' cannot be less than min: ' + min + '. Using min value instead.');
+        return min;
+    }
+    logger.warn(' must be a number. using max or fallback. max: ' + max + ', fallback: ' + fallbackValue);
+    return clampToRange(max, min, max, logger);
+}
+
+class BucketedRateLimiter {
+    constructor(_options){
+        this._options = _options;
+        this._buckets = {};
+        this._refillBuckets = ()=>{
+            Object.keys(this._buckets).forEach((key)=>{
+                const newTokens = this._getBucket(key) + this._refillRate;
+                if (newTokens >= this._bucketSize) delete this._buckets[key];
+                else this._setBucket(key, newTokens);
+            });
+        };
+        this._getBucket = (key)=>this._buckets[String(key)];
+        this._setBucket = (key, value)=>{
+            this._buckets[String(key)] = value;
+        };
+        this.consumeRateLimit = (key)=>{
+            var _this__getBucket;
+            let tokens = null != (_this__getBucket = this._getBucket(key)) ? _this__getBucket : this._bucketSize;
+            tokens = Math.max(tokens - 1, 0);
+            if (0 === tokens) return true;
+            this._setBucket(key, tokens);
+            const hasReachedZero = 0 === tokens;
+            if (hasReachedZero) {
+                var _this__onBucketRateLimited, _this;
+                null == (_this__onBucketRateLimited = (_this = this)._onBucketRateLimited) || _this__onBucketRateLimited.call(_this, key);
+            }
+            return hasReachedZero;
+        };
+        this._onBucketRateLimited = this._options._onBucketRateLimited;
+        this._bucketSize = clampToRange(this._options.bucketSize, 0, 100, this._options._logger);
+        this._refillRate = clampToRange(this._options.refillRate, 0, this._bucketSize, this._options._logger);
+        this._refillInterval = clampToRange(this._options.refillInterval, 0, 86400000, this._options._logger);
+        setInterval(()=>{
+            this._refillBuckets();
+        }, this._refillInterval);
+    }
+}
+
+function safeSetTimeout(fn, timeout) {
+    const t = setTimeout(fn, timeout);
+    (null == t ? void 0 : t.unref) && (null == t || t.unref());
+    return t;
+}
+
 const SHUTDOWN_TIMEOUT = 2000;
 class ErrorTracking {
   static async buildEventMessage(error, hint, distinctId, additionalProperties) {
@@ -644,9 +709,20 @@ class ErrorTracking {
       }
     };
   }
-  constructor(client, options) {
+  constructor(client, options, _logger) {
     this.client = client;
     this._exceptionAutocaptureEnabled = options.enableExceptionAutocapture || false;
+    this._logger = _logger;
+    // by default captures ten exceptions before rate limiting by exception type
+    // refills at a rate of one token / 10 second period
+    // e.g. will capture 1 exception rate limited exception every 10 seconds until burst ends
+    this._rateLimiter = new BucketedRateLimiter({
+      refillRate: 1,
+      bucketSize: 10,
+      refillInterval: 10000,
+      // ten seconds in milliseconds
+      _logger: this._logger
+    });
     this.startAutocaptureIfEnabled();
   }
   startAutocaptureIfEnabled() {
@@ -656,7 +732,16 @@ class ErrorTracking {
     }
   }
   onException(exception, hint) {
-    void ErrorTracking.buildEventMessage(exception, hint).then(msg => {
+    return ErrorTracking.buildEventMessage(exception, hint).then(msg => {
+      const exceptionProperties = msg.properties;
+      const exceptionType = exceptionProperties?.$exception_list[0].type ?? 'Exception';
+      const isRateLimited = this._rateLimiter.consumeRateLimit(exceptionType);
+      if (isRateLimited) {
+        this._logger.info('Skipping exception capture because of client rate limiting.', {
+          exception: exceptionType
+        });
+        return;
+      }
       this.client.capture(msg);
     });
   }
@@ -1088,7 +1173,7 @@ function snipLine(line, colno) {
   return newLine;
 }
 
-var version = "5.7.0";
+var version = "5.8.0";
 
 /**
  * A lazy value that is only computed when needed. Inspired by C#'s Lazy<T> class.
@@ -1376,7 +1461,70 @@ class FeatureFlagsPoller {
     }
     return null;
   }
-  async matchFeatureFlagProperties(flag, distinctId, properties) {
+  async evaluateFlagDependency(property, distinctId, properties, evaluationCache) {
+    const targetFlagKey = property.key;
+    if (!this.featureFlagsByKey) {
+      throw new InconclusiveMatchError('Feature flags not available for dependency evaluation');
+    }
+    // Check if dependency_chain is present - it should always be provided for flag dependencies
+    if (!('dependency_chain' in property)) {
+      throw new InconclusiveMatchError(`Flag dependency property for '${targetFlagKey}' is missing required 'dependency_chain' field`);
+    }
+    const dependencyChain = property.dependency_chain;
+    // Check for missing or invalid dependency chain (This should never happen, but being defensive)
+    if (!Array.isArray(dependencyChain)) {
+      throw new InconclusiveMatchError(`Flag dependency property for '${targetFlagKey}' has an invalid 'dependency_chain' (expected array, got ${typeof dependencyChain})`);
+    }
+    // Handle circular dependency (empty chain means circular)  (This should never happen, but being defensive)
+    if (dependencyChain.length === 0) {
+      throw new InconclusiveMatchError(`Circular dependency detected for flag '${targetFlagKey}' (empty dependency chain)`);
+    }
+    // Evaluate all dependencies in the chain order
+    for (const depFlagKey of dependencyChain) {
+      if (!(depFlagKey in evaluationCache)) {
+        // Need to evaluate this dependency first
+        const depFlag = this.featureFlagsByKey[depFlagKey];
+        if (!depFlag) {
+          // Missing flag dependency - cannot evaluate locally
+          throw new InconclusiveMatchError(`Missing flag dependency '${depFlagKey}' for flag '${targetFlagKey}'`);
+        } else if (!depFlag.active) {
+          // Inactive flag evaluates to false
+          evaluationCache[depFlagKey] = false;
+        } else {
+          // Recursively evaluate the dependency
+          try {
+            const depResult = await this.matchFeatureFlagProperties(depFlag, distinctId, properties, evaluationCache);
+            evaluationCache[depFlagKey] = depResult;
+          } catch (error) {
+            // If we can't evaluate a dependency, store throw InconclusiveMatchError(`Missing flag dependency '${depFlagKey}' for flag '${targetFlagKey}'`)
+            throw new InconclusiveMatchError(`Error evaluating flag dependency '${depFlagKey}' for flag '${targetFlagKey}': ${error}`);
+          }
+        }
+      }
+      // Check if dependency evaluation was inconclusive
+      const cachedResult = evaluationCache[depFlagKey];
+      if (cachedResult === null || cachedResult === undefined) {
+        throw new InconclusiveMatchError(`Dependency '${depFlagKey}' could not be evaluated`);
+      }
+    }
+    // The target flag is specified in property.key (This should match the last element in the dependency chain)
+    const targetFlagValue = evaluationCache[targetFlagKey];
+    return this.flagEvaluatesToExpectedValue(property.value, targetFlagValue);
+  }
+  flagEvaluatesToExpectedValue(expectedValue, flagValue) {
+    // If the expected value is a boolean, then return true if the flag evaluated to true (or any string variant)
+    // If the expected value is false, then only return true if the flag evaluated to false.
+    if (typeof expectedValue === 'boolean') {
+      return expectedValue === flagValue || typeof flagValue === 'string' && flagValue !== '' && expectedValue === true;
+    }
+    // If the expected value is a string, then return true if and only if the flag evaluated to the expected value.
+    if (typeof expectedValue === 'string') {
+      return flagValue === expectedValue;
+    }
+    // The `flag_evaluates_to` operator is not supported for numbers and arrays.
+    return false;
+  }
+  async matchFeatureFlagProperties(flag, distinctId, properties, evaluationCache = {}) {
     const flagFilters = flag.filters || {};
     const flagConditions = flagFilters.groups || [];
     let isInconclusive = false;
@@ -1398,7 +1546,7 @@ class FeatureFlagsPoller {
     });
     for (const condition of sortedFlagConditions) {
       try {
-        if (await this.isConditionMatch(flag, distinctId, condition, properties)) {
+        if (await this.isConditionMatch(flag, distinctId, condition, properties, evaluationCache)) {
           const variantOverride = condition.variant;
           const flagVariants = flagFilters.multivariate?.variants || [];
           if (variantOverride && flagVariants.some(variant => variant.key === variantOverride)) {
@@ -1424,7 +1572,7 @@ class FeatureFlagsPoller {
     // We can only return False when all conditions are False
     return false;
   }
-  async isConditionMatch(flag, distinctId, condition, properties) {
+  async isConditionMatch(flag, distinctId, condition, properties, evaluationCache = {}) {
     const rolloutPercentage = condition.rollout_percentage;
     const warnFunction = msg => {
       this.logMsgIfDebug(() => console.warn(msg));
@@ -1436,8 +1584,7 @@ class FeatureFlagsPoller {
         if (propertyType === 'cohort') {
           matches = matchCohort(prop, properties, this.cohorts, this.debugMode);
         } else if (propertyType === 'flag') {
-          this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Flag dependency filters are not supported in local evaluation. ` + `Skipping condition for flag '${flag.key}' with dependency on flag '${prop.key || 'unknown'}'`));
-          continue;
+          matches = await this.evaluateFlagDependency(prop, distinctId, properties, evaluationCache);
         } else {
           matches = matchProperty(prop, properties, warnFunction);
         }
@@ -1702,6 +1849,10 @@ function matchProperty(property, propertyValues, warnFunction) {
     case 'is_date_after':
     case 'is_date_before':
       {
+        // Boolean values should never be used with date operations
+        if (typeof value === 'boolean') {
+          throw new InconclusiveMatchError(`Date operations cannot be performed on boolean values`);
+        }
         let parsedDate = relativeDateParseForFeatureFlagMatching(String(value));
         if (parsedDate == null) {
           parsedDate = convertToDateTime(value);
@@ -1885,6 +2036,37 @@ class PostHogMemoryStorage {
   }
 }
 
+const _createLogger = (prefix, logMsgIfDebug) => {
+  const logger = {
+    _log: (level, ...args) => {
+      logMsgIfDebug(() => {
+        const consoleLog = console[level];
+        consoleLog(prefix, ...args);
+      });
+    },
+    info: (...args) => {
+      logger._log('log', ...args);
+    },
+    warn: (...args) => {
+      logger._log('warn', ...args);
+    },
+    error: (...args) => {
+      logger._log('error', ...args);
+    },
+    critical: (...args) => {
+      // Critical errors are always logged to the console
+      // eslint-disable-next-line no-console
+      console.error(prefix, ...args);
+    },
+    uninitializedWarning: methodName => {
+      logger.error(`You must initialize PostHog before calling ${methodName}`);
+    },
+    createLogger: additionalPrefix => _createLogger(`${prefix} ${additionalPrefix}`, logMsgIfDebug)
+  };
+  return logger;
+};
+const createLogger = logMsgIfDebug => _createLogger('[PostHog.js]', logMsgIfDebug);
+
 // Standard local evaluation rate limit is 600 per minute (10 per second),
 // so the fastest a poller should ever be set is 100ms.
 const MINIMUM_POLLING_INTERVAL = 100;
@@ -1896,6 +2078,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
     super(apiKey, options);
     this._memoryStorage = new PostHogMemoryStorage();
     this.options = options;
+    this.logger = createLogger(this.logMsgIfDebug.bind(this));
     this.options.featureFlagsPollingInterval = typeof options.featureFlagsPollingInterval === 'number' ? Math.max(options.featureFlagsPollingInterval, MINIMUM_POLLING_INTERVAL) : THIRTY_SECONDS;
     if (options.personalApiKey) {
       if (options.personalApiKey.includes('phc_')) {
@@ -1922,7 +2105,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
         });
       }
     }
-    this.errorTracking = new ErrorTracking(this, options);
+    this.errorTracking = new ErrorTracking(this, options, this.logger);
     this.distinctIdHasSentFlagCalls = {};
     this.maxCacheSize = options.maxCacheSize || MAX_CACHE_SIZE;
   }