posthog-node 4.10.2 → 4.11.1

package/lib/index.esm.js

@@ -1,17 +1,18 @@
-import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { posix, dirname, sep } from 'node:path';
 
-var version = "4.10.2";
+var version = "4.11.1";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
     PostHogPersistedProperty["AnonymousId"] = "anonymous_id";
     PostHogPersistedProperty["DistinctId"] = "distinct_id";
     PostHogPersistedProperty["Props"] = "props";
+    PostHogPersistedProperty["FeatureFlagDetails"] = "feature_flag_details";
     PostHogPersistedProperty["FeatureFlags"] = "feature_flags";
     PostHogPersistedProperty["FeatureFlagPayloads"] = "feature_flag_payloads";
+    PostHogPersistedProperty["BootstrapFeatureFlagDetails"] = "bootstrap_feature_flag_details";
     PostHogPersistedProperty["BootstrapFeatureFlags"] = "bootstrap_feature_flags";
     PostHogPersistedProperty["BootstrapFeatureFlagPayloads"] = "bootstrap_feature_flag_payloads";
     PostHogPersistedProperty["OverrideFeatureFlags"] = "override_feature_flags";
@@ -31,11 +32,100 @@ var PostHogPersistedProperty;
     PostHogPersistedProperty["RemoteConfig"] = "remote_config";
 })(PostHogPersistedProperty || (PostHogPersistedProperty = {}));
 
+const normalizeDecideResponse = (decideResponse) => {
+    if ('flags' in decideResponse) {
+        // Convert v4 format to v3 format
+        const featureFlags = getFlagValuesFromFlags(decideResponse.flags);
+        const featureFlagPayloads = getPayloadsFromFlags(decideResponse.flags);
+        return {
+            ...decideResponse,
+            featureFlags,
+            featureFlagPayloads,
+        };
+    }
+    else {
+        // Convert v3 format to v4 format
+        const featureFlags = decideResponse.featureFlags ?? {};
+        const featureFlagPayloads = Object.fromEntries(Object.entries(decideResponse.featureFlagPayloads || {}).map(([k, v]) => [k, parsePayload(v)]));
+        const flags = Object.fromEntries(Object.entries(featureFlags).map(([key, value]) => [
+            key,
+            getFlagDetailFromFlagAndPayload(key, value, featureFlagPayloads[key]),
+        ]));
+        return {
+            ...decideResponse,
+            featureFlags,
+            featureFlagPayloads,
+            flags,
+        };
+    }
+};
+function getFlagDetailFromFlagAndPayload(key, value, payload) {
+    return {
+        key: key,
+        enabled: typeof value === 'string' ? true : value,
+        variant: typeof value === 'string' ? value : undefined,
+        reason: undefined,
+        metadata: {
+            id: undefined,
+            version: undefined,
+            payload: payload ? JSON.stringify(payload) : undefined,
+            description: undefined,
+        },
+    };
+}
+/**
+ * Get the flag values from the flags v4 response.
+ * @param flags - The flags
+ * @returns The flag values
+ */
+const getFlagValuesFromFlags = (flags) => {
+    return Object.fromEntries(Object.entries(flags ?? {})
+        .map(([key, detail]) => [key, getFeatureFlagValue(detail)])
+        .filter(([, value]) => value !== undefined));
+};
+/**
+ * Get the payloads from the flags v4 response.
+ * @param flags - The flags
+ * @returns The payloads
+ */
+const getPayloadsFromFlags = (flags) => {
+    const safeFlags = flags ?? {};
+    return Object.fromEntries(Object.keys(safeFlags)
+        .filter((flag) => {
+        const details = safeFlags[flag];
+        return details.enabled && details.metadata && details.metadata.payload !== undefined;
+    })
+        .map((flag) => {
+        const payload = safeFlags[flag].metadata?.payload;
+        return [flag, payload ? parsePayload(payload) : undefined];
+    }));
+};
+const getFeatureFlagValue = (detail) => {
+    return detail === undefined ? undefined : detail.variant ?? detail.enabled;
+};
+const parsePayload = (response) => {
+    if (typeof response !== 'string') {
+        return response;
+    }
+    try {
+        return JSON.parse(response);
+    }
+    catch {
+        return response;
+    }
+};
+
 function assert(truthyValue, message) {
-    if (!truthyValue) {
+    if (!truthyValue || typeof truthyValue !== 'string' || isEmpty(truthyValue)) {
         throw new Error(message);
     }
 }
+function isEmpty(truthyValue) {
+    if (truthyValue.trim().length === 0) {
+        return true;
+    }
+    return false;
+}
 function removeTrailingSlash(url) {
     return url?.replace(/\/+$/, '');
 }
@@ -1154,7 +1244,7 @@ class PostHogCoreStateless {
      ***/
     async getDecide(distinctId, groups = {}, personProperties = {}, groupProperties = {}, extraPayload = {}) {
         await this._initPromise;
-        const url = `${this.host}/decide/?v=3`;
+        const url = `${this.host}/decide/?v=4`;
         const fetchOptions = {
             method: 'POST',
             headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
@@ -1170,6 +1260,7 @@ class PostHogCoreStateless {
         // Don't retry /decide API calls
         return this.fetchWithRetry(url, fetchOptions, { retryCount: 0 }, this.featureFlagsRequestTimeoutMs)
             .then((response) => response.json())
+            .then((response) => normalizeDecideResponse(response))
             .catch((error) => {
             this._events.emit('error', error);
             return undefined;
@@ -1177,17 +1268,15 @@ class PostHogCoreStateless {
     }
     async getFeatureFlagStateless(key, distinctId, groups = {}, personProperties = {}, groupProperties = {}, disableGeoip) {
         await this._initPromise;
-        const decideResponse = await this.getFeatureFlagsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, [key]);
-        const featureFlags = decideResponse.flags;
-        if (!featureFlags) {
+        const flagDetailResponse = await this.getFeatureFlagDetailStateless(key, distinctId, groups, personProperties, groupProperties, disableGeoip);
+        if (flagDetailResponse === undefined) {
             // If we haven't loaded flags yet, or errored out, we respond with undefined
             return {
                 response: undefined,
                 requestId: undefined,
             };
         }
-        let response = featureFlags[key];
-        // `/decide` v3 returns all flags
+        let response = getFeatureFlagValue(flagDetailResponse.response);
         if (response === undefined) {
             // For cases where the flag is unknown, return false
             response = false;
@@ -1195,6 +1284,19 @@ class PostHogCoreStateless {
         // If we have flags we either return the value (true or string) or false
         return {
             response,
+            requestId: flagDetailResponse.requestId,
+        };
+    }
+    async getFeatureFlagDetailStateless(key, distinctId, groups = {}, personProperties = {}, groupProperties = {}, disableGeoip) {
+        await this._initPromise;
+        const decideResponse = await this.getFeatureFlagDetailsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, [key]);
+        if (decideResponse === undefined) {
+            return undefined;
+        }
+        const featureFlags = decideResponse.flags;
+        const flagDetail = featureFlags[key];
+        return {
+            response: flagDetail,
             requestId: decideResponse.requestId,
         };
     }
@@ -1216,19 +1318,27 @@ class PostHogCoreStateless {
         const payloads = (await this.getFeatureFlagsAndPayloadsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, flagKeysToEvaluate)).payloads;
         return payloads;
     }
-    _parsePayload(response) {
-        try {
-            return JSON.parse(response);
-        }
-        catch {
-            return response;
-        }
-    }
     async getFeatureFlagsStateless(distinctId, groups = {}, personProperties = {}, groupProperties = {}, disableGeoip, flagKeysToEvaluate) {
         await this._initPromise;
         return await this.getFeatureFlagsAndPayloadsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, flagKeysToEvaluate);
     }
     async getFeatureFlagsAndPayloadsStateless(distinctId, groups = {}, personProperties = {}, groupProperties = {}, disableGeoip, flagKeysToEvaluate) {
+        await this._initPromise;
+        const featureFlagDetails = await this.getFeatureFlagDetailsStateless(distinctId, groups, personProperties, groupProperties, disableGeoip, flagKeysToEvaluate);
+        if (!featureFlagDetails) {
+            return {
+                flags: undefined,
+                payloads: undefined,
+                requestId: undefined,
+            };
+        }
+        return {
+            flags: featureFlagDetails.featureFlags,
+            payloads: featureFlagDetails.featureFlagPayloads,
+            requestId: featureFlagDetails.requestId,
+        };
+    }
+    async getFeatureFlagDetailsStateless(distinctId, groups = {}, personProperties = {}, groupProperties = {}, disableGeoip, flagKeysToEvaluate) {
         await this._initPromise;
         const extraPayload = {};
         if (disableGeoip ?? this.disableGeoip) {
@@ -1238,30 +1348,25 @@ class PostHogCoreStateless {
             extraPayload['flag_keys_to_evaluate'] = flagKeysToEvaluate;
         }
         const decideResponse = await this.getDecide(distinctId, groups, personProperties, groupProperties, extraPayload);
+        if (decideResponse === undefined) {
+            // We probably errored out, so return undefined
+            return undefined;
+        }
         // if there's an error on the decideResponse, log a console error, but don't throw an error
-        if (decideResponse?.errorsWhileComputingFlags) {
+        if (decideResponse.errorsWhileComputingFlags) {
             console.error('[FEATURE FLAGS] Error while computing feature flags, some flags may be missing or incorrect. Learn more at https://posthog.com/docs/feature-flags/best-practices');
         }
         // Add check for quota limitation on feature flags
-        if (decideResponse?.quotaLimited?.includes(QuotaLimitedFeature.FeatureFlags)) {
+        if (decideResponse.quotaLimited?.includes(QuotaLimitedFeature.FeatureFlags)) {
             console.warn('[FEATURE FLAGS] Feature flags quota limit exceeded - feature flags unavailable. Learn more about billing limits at https://posthog.com/docs/billing/limits-alerts');
             return {
-                flags: undefined,
-                payloads: undefined,
+                flags: {},
+                featureFlags: {},
+                featureFlagPayloads: {},
                 requestId: decideResponse?.requestId,
             };
         }
-        const flags = decideResponse?.featureFlags;
-        const payloads = decideResponse?.featureFlagPayloads;
-        let parsedPayloads = payloads;
-        if (payloads) {
-            parsedPayloads = Object.fromEntries(Object.entries(payloads).map(([k, v]) => [k, this._parsePayload(v)]));
-        }
-        return {
-            flags,
-            payloads: parsedPayloads,
-            requestId: decideResponse?.requestId,
-        };
+        return decideResponse;
     }
     /***
      *** SURVEYS
@@ -1548,6 +1653,100 @@ if (!_fetch) {
 // NOTE: We have to export this as default, even though we prefer named exports as we are relying on detecting "fetch" in the global scope
 var fetch$1 = _fetch;
 
+/**
+ * A lazy value that is only computed when needed. Inspired by C#'s Lazy<T> class.
+ */
+class Lazy {
+  constructor(factory) {
+    this.factory = factory;
+  }
+  /**
+   * Gets the value, initializing it if necessary.
+   * Multiple concurrent calls will share the same initialization promise.
+   */
+  async getValue() {
+    if (this.value !== undefined) {
+      return this.value;
+    }
+    if (this.initializationPromise === undefined) {
+      this.initializationPromise = (async () => {
+        try {
+          const result = await this.factory();
+          this.value = result;
+          return result;
+        } finally {
+          // Clear the promise so we can retry if needed
+          this.initializationPromise = undefined;
+        }
+      })();
+    }
+    return this.initializationPromise;
+  }
+  /**
+   * Returns true if the value has been initialized.
+   */
+  isInitialized() {
+    return this.value !== undefined;
+  }
+  /**
+   * Returns a promise that resolves when the value is initialized.
+   * If already initialized, resolves immediately.
+   */
+  async waitForInitialization() {
+    if (this.isInitialized()) {
+      return;
+    }
+    await this.getValue();
+  }
+}
+
+/// <reference lib="dom" />
+const nodeCrypto = new Lazy(async () => {
+  try {
+    return await import('crypto');
+  } catch {
+    return undefined;
+  }
+});
+async function getNodeCrypto() {
+  return await nodeCrypto.getValue();
+}
+const webCrypto = new Lazy(async () => {
+  if (typeof globalThis.crypto?.subtle !== 'undefined') {
+    return globalThis.crypto.subtle;
+  }
+  try {
+    // Node.js: use built-in webcrypto and assign it if needed
+    const crypto = await nodeCrypto.getValue();
+    if (crypto?.webcrypto?.subtle) {
+      return crypto.webcrypto.subtle;
+    }
+  } catch {
+    // Ignore if not available
+  }
+  return undefined;
+});
+async function getWebCrypto() {
+  return await webCrypto.getValue();
+}
+
+/// <reference lib="dom" />
+async function hashSHA1(text) {
+  // Try Node.js crypto first
+  const nodeCrypto = await getNodeCrypto();
+  if (nodeCrypto) {
+    return nodeCrypto.createHash('sha1').update(text).digest('hex');
+  }
+  const webCrypto = await getWebCrypto();
+  // Fall back to Web Crypto API
+  if (webCrypto) {
+    const hashBuffer = await webCrypto.digest('SHA-1', new TextEncoder().encode(text));
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map(byte => byte.toString(16).padStart(2, '0')).join('');
+  }
+  throw new Error('No crypto implementation available. Tried Node Crypto API and Web SubtleCrypto API');
+}
+
 // eslint-disable-next-line
 const LONG_SCALE = 0xfffffffffffffff;
 const NULL_VALUES_ALLOWED_OPERATORS = ['is_not'];
@@ -1623,7 +1822,7 @@ class FeatureFlagsPoller {
     }
     if (featureFlag !== undefined) {
       try {
-        response = this.computeFlagLocally(featureFlag, distinctId, groups, personProperties, groupProperties);
+        response = await this.computeFlagLocally(featureFlag, distinctId, groups, personProperties, groupProperties);
         this.logMsgIfDebug(() => console.debug(`Successfully computed flag locally: ${key} -> ${response}`));
       } catch (e) {
         if (e instanceof InconclusiveMatchError) {
@@ -1661,9 +1860,9 @@ class FeatureFlagsPoller {
     const response = {};
     const payloads = {};
     let fallbackToDecide = this.featureFlags.length == 0;
-    this.featureFlags.map(async flag => {
+    await Promise.all(this.featureFlags.map(async flag => {
       try {
-        const matchValue = this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties);
+        const matchValue = await this.computeFlagLocally(flag, distinctId, groups, personProperties, groupProperties);
         response[flag.key] = matchValue;
         const matchPayload = await this.computeFeatureFlagPayloadLocally(flag.key, matchValue);
         if (matchPayload) {
@@ -1675,14 +1874,14 @@ class FeatureFlagsPoller {
         }
         fallbackToDecide = true;
       }
-    });
+    }));
     return {
       response,
       payloads,
       fallbackToDecide
     };
   }
-  computeFlagLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
+  async computeFlagLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
     if (flag.ensure_experience_continuity) {
       throw new InconclusiveMatchError('Flag has experience continuity enabled');
     }
@@ -1702,12 +1901,12 @@ class FeatureFlagsPoller {
         return false;
       }
       const focusedGroupProperties = groupProperties[groupName];
-      return this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties);
+      return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties);
     } else {
-      return this.matchFeatureFlagProperties(flag, distinctId, personProperties);
+      return await this.matchFeatureFlagProperties(flag, distinctId, personProperties);
     }
   }
-  matchFeatureFlagProperties(flag, distinctId, properties) {
+  async matchFeatureFlagProperties(flag, distinctId, properties) {
     const flagFilters = flag.filters || {};
     const flagConditions = flagFilters.groups || [];
     let isInconclusive = false;
@@ -1729,13 +1928,13 @@ class FeatureFlagsPoller {
     });
     for (const condition of sortedFlagConditions) {
       try {
-        if (this.isConditionMatch(flag, distinctId, condition, properties)) {
+        if (await this.isConditionMatch(flag, distinctId, condition, properties)) {
           const variantOverride = condition.variant;
           const flagVariants = flagFilters.multivariate?.variants || [];
           if (variantOverride && flagVariants.some(variant => variant.key === variantOverride)) {
             result = variantOverride;
           } else {
-            result = this.getMatchingVariant(flag, distinctId) || true;
+            result = (await this.getMatchingVariant(flag, distinctId)) || true;
           }
           break;
         }
@@ -1755,7 +1954,7 @@ class FeatureFlagsPoller {
     // We can only return False when all conditions are False
     return false;
   }
-  isConditionMatch(flag, distinctId, condition, properties) {
+  async isConditionMatch(flag, distinctId, condition, properties) {
     const rolloutPercentage = condition.rollout_percentage;
     const warnFunction = msg => {
       this.logMsgIfDebug(() => console.warn(msg));
@@ -1777,13 +1976,13 @@ class FeatureFlagsPoller {
         return true;
       }
     }
-    if (rolloutPercentage != undefined && _hash(flag.key, distinctId) > rolloutPercentage / 100.0) {
+    if (rolloutPercentage != undefined && (await _hash(flag.key, distinctId)) > rolloutPercentage / 100.0) {
       return false;
     }
     return true;
   }
-  getMatchingVariant(flag, distinctId) {
-    const hashValue = _hash(flag.key, distinctId, 'variant');
+  async getMatchingVariant(flag, distinctId) {
+    const hashValue = await _hash(flag.key, distinctId, 'variant');
     const matchingVariant = this.variantLookupTable(flag).find(variant => {
       return hashValue >= variant.valueMin && hashValue < variant.valueMax;
     });
@@ -1954,10 +2153,9 @@ class FeatureFlagsPoller {
 // # Given the same distinct_id and key, it'll always return the same float. These floats are
 // # uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
 // # we can do _hash(key, distinct_id) < 0.2
-function _hash(key, distinctId, salt = '') {
-  const sha1Hash = createHash('sha1');
-  sha1Hash.update(`${key}.${distinctId}${salt}`);
-  return parseInt(sha1Hash.digest('hex').slice(0, 15), 16) / LONG_SCALE;
+async function _hash(key, distinctId, salt = '') {
+  const hashString = await hashSHA1(`${key}.${distinctId}${salt}`);
+  return parseInt(hashString.slice(0, 15), 16) / LONG_SCALE;
 }
 function matchProperty(property, propertyValues, warnFunction) {
   const key = property.key;
@@ -3200,7 +3398,7 @@ class PostHog extends PostHogCoreStateless {
           additionalProperties[`$feature/${feature}`] = variant;
         }
       }
-      const activeFlags = Object.keys(flags || {}).filter(flag => flags?.[flag] !== false);
+      const activeFlags = Object.keys(flags || {}).filter(flag => flags?.[flag] !== false).sort();
       if (activeFlags.length > 0) {
         additionalProperties['$active_feature_flags'] = activeFlags;
       }
@@ -3265,10 +3463,15 @@ class PostHog extends PostHogCoreStateless {
     let response = await this.featureFlagsPoller?.getFeatureFlag(key, distinctId, groups, personProperties, groupProperties);
     const flagWasLocallyEvaluated = response !== undefined;
     let requestId = undefined;
+    let flagDetail = undefined;
     if (!flagWasLocallyEvaluated && !onlyEvaluateLocally) {
-      const remoteResponse = await super.getFeatureFlagStateless(key, distinctId, groups, personProperties, groupProperties, disableGeoip);
-      response = remoteResponse.response;
-      requestId = remoteResponse.requestId;
+      const remoteResponse = await super.getFeatureFlagDetailStateless(key, distinctId, groups, personProperties, groupProperties, disableGeoip);
+      if (remoteResponse === undefined) {
+        return undefined;
+      }
+      flagDetail = remoteResponse.response;
+      response = getFeatureFlagValue(flagDetail);
+      requestId = remoteResponse?.requestId;
     }
     const featureFlagReportedKey = `${key}_${response}`;
     if (sendFeatureFlagEvents && (!(distinctId in this.distinctIdHasSentFlagCalls) || !this.distinctIdHasSentFlagCalls[distinctId].includes(featureFlagReportedKey))) {
@@ -3286,6 +3489,9 @@ class PostHog extends PostHogCoreStateless {
         properties: {
           $feature_flag: key,
           $feature_flag_response: response,
+          $feature_flag_id: flagDetail?.metadata?.id,
+          $feature_flag_version: flagDetail?.metadata?.version,
+          $feature_flag_reason: flagDetail?.reason?.description ?? flagDetail?.reason?.code,
           locally_evaluated: flagWasLocallyEvaluated,
           [`$feature/${key}`]: response,
           $feature_flag_request_id: requestId
@@ -3311,16 +3517,21 @@ class PostHog extends PostHogCoreStateless {
     personProperties = adjustedProperties.allPersonProperties;
     groupProperties = adjustedProperties.allGroupProperties;
     let response = undefined;
-    // Try to get match value locally if not provided
-    if (!matchValue) {
-      matchValue = await this.getFeatureFlag(key, distinctId, {
-        ...options,
-        onlyEvaluateLocally: true
-      });
-    }
-    if (matchValue) {
-      response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue);
+    const localEvaluationEnabled = this.featureFlagsPoller !== undefined;
+    if (localEvaluationEnabled) {
+      // Try to get match value locally if not provided
+      if (!matchValue) {
+        matchValue = await this.getFeatureFlag(key, distinctId, {
+          ...options,
+          onlyEvaluateLocally: true,
+          sendFeatureFlagEvents: false
+        });
+      }
+      if (matchValue) {
+        response = await this.featureFlagsPoller?.computeFeatureFlagPayloadLocally(key, matchValue);
+      }
     }
+    //}
     // set defaults
     if (onlyEvaluateLocally == undefined) {
       onlyEvaluateLocally = false;
@@ -3350,7 +3561,7 @@ class PostHog extends PostHogCoreStateless {
   }
   async getAllFlags(distinctId, options) {
     const response = await this.getAllFlagsAndPayloads(distinctId, options);
-    return response.featureFlags;
+    return response.featureFlags || {};
   }
   async getAllFlagsAndPayloads(distinctId, options) {
     const {