posthog-node 5.8.0 → 5.8.2

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 { PostHogCoreStateless, getFeatureFlagValue } from '@posthog/core';
+import { PostHogCoreStateless, getFeatureFlagValue, safeSetTimeout as safeSetTimeout$1 } 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.
@@ -316,7 +316,7 @@ function makeUncaughtExceptionHandler(captureFn, onFatalFn) {
     });
     if (!calledFatalError && processWouldExit) {
       calledFatalError = true;
-      onFatalFn();
+      onFatalFn(error);
     }
   }, {
     _posthogErrorHandler: true
@@ -327,7 +327,7 @@ function addUncaughtExceptionListener(captureFn, onFatalFn) {
 }
 function addUnhandledRejectionListener(captureFn) {
   global.process.on('unhandledRejection', reason => {
-    captureFn(reason, {
+    return captureFn(reason, {
       mechanism: {
         type: 'onunhandledrejection',
         handled: false
@@ -344,8 +344,7 @@ let cachedFilenameChunkIds;
 function getFilenameToChunkIdMap(stackParser) {
   const chunkIdMap = globalThis._posthogChunkIds;
   if (!chunkIdMap) {
-    console.error('No chunk id map found');
-    return {};
+    return null;
   }
   const chunkIdKeys = Object.keys(chunkIdMap);
   if (cachedFilenameChunkIds && chunkIdKeys.length === lastKeysCount) {
@@ -616,7 +615,7 @@ function parseStackFrames(stackParser, error) {
 function applyChunkIds(frames, parser) {
   const filenameChunkIdMap = getFilenameToChunkIdMap(parser);
   frames.forEach(frame => {
-    if (frame.filename) {
+    if (frame.filename && filenameChunkIdMap) {
       frame.chunk_id = filenameChunkIdMap[frame.filename];
     }
   });
@@ -645,6 +644,12 @@ function clampToRange(value, min, max, logger, fallbackValue) {
 }
 
 class BucketedRateLimiter {
+    stop() {
+        if (this._removeInterval) {
+            clearInterval(this._removeInterval);
+            this._removeInterval = void 0;
+        }
+    }
     constructor(_options){
         this._options = _options;
         this._buckets = {};
@@ -676,7 +681,7 @@ class BucketedRateLimiter {
         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._removeInterval = setInterval(()=>{
             this._refillBuckets();
         }, this._refillInterval);
     }
@@ -690,6 +695,22 @@ function safeSetTimeout(fn, timeout) {
 
 const SHUTDOWN_TIMEOUT = 2000;
 class ErrorTracking {
+  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();
+  }
   static async buildEventMessage(error, hint, distinctId, additionalProperties) {
     const properties = {
       ...additionalProperties
@@ -709,31 +730,16 @@ class ErrorTracking {
       }
     };
   }
-  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() {
     if (this.isEnabled()) {
       addUncaughtExceptionListener(this.onException.bind(this), this.onFatalError.bind(this));
       addUnhandledRejectionListener(this.onException.bind(this));
     }
   }
-  onException(exception, hint) {
-    return ErrorTracking.buildEventMessage(exception, hint).then(msg => {
-      const exceptionProperties = msg.properties;
+  async onException(exception, hint) {
+    this.client.addPendingPromise((async () => {
+      const eventMessage = await ErrorTracking.buildEventMessage(exception, hint);
+      const exceptionProperties = eventMessage.properties;
       const exceptionType = exceptionProperties?.$exception_list[0].type ?? 'Exception';
       const isRateLimited = this._rateLimiter.consumeRateLimit(exceptionType);
       if (isRateLimited) {
@@ -742,15 +748,20 @@ class ErrorTracking {
         });
         return;
       }
-      this.client.capture(msg);
-    });
+      return this.client.capture(eventMessage);
+    })());
   }
-  async onFatalError() {
+  async onFatalError(exception) {
+    console.error(exception);
     await this.client.shutdown(SHUTDOWN_TIMEOUT);
+    process.exit(1);
   }
   isEnabled() {
     return !this.client.isDisabled && this._exceptionAutocaptureEnabled;
   }
+  shutdown() {
+    this._rateLimiter.stop();
+  }
 }
 
 function setupExpressErrorHandler(_posthog, app) {
@@ -1173,7 +1184,7 @@ function snipLine(line, colno) {
   return newLine;
 }
 
-var version = "5.8.0";
+var version = "5.8.2";
 
 /**
  * A lazy value that is only computed when needed. Inspired by C#'s Lazy<T> class.
@@ -2074,6 +2085,35 @@ const THIRTY_SECONDS = 30 * 1000;
 const MAX_CACHE_SIZE = 50 * 1000;
 // The actual exported Nodejs API.
 class PostHogBackendClient extends PostHogCoreStateless {
+  /**
+   * Initialize a new PostHog client instance.
+   *
+   * @example
+   * ```ts
+   * // Basic initialization
+   * const client = new PostHogBackendClient(
+   *   'your-api-key',
+   *   { host: 'https://app.posthog.com' }
+   * )
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With personal API key
+   * const client = new PostHogBackendClient(
+   *   'your-api-key',
+   *   {
+   *     host: 'https://app.posthog.com',
+   *     personalApiKey: 'your-personal-api-key'
+   *   }
+   * )
+   * ```
+   *
+   * {@label Initialization}
+   *
+   * @param apiKey - Your PostHog project API key
+   * @param options - Configuration options for the client
+   */
   constructor(apiKey, options = {}) {
     super(apiKey, options);
     this._memoryStorage = new PostHogMemoryStorage();
@@ -2109,176 +2149,302 @@ class PostHogBackendClient extends PostHogCoreStateless {
     this.distinctIdHasSentFlagCalls = {};
     this.maxCacheSize = options.maxCacheSize || MAX_CACHE_SIZE;
   }
+  /**
+   * Get a persisted property value from memory storage.
+   *
+   * @example
+   * ```ts
+   * // Get user ID
+   * const userId = client.getPersistedProperty('userId')
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Get session ID
+   * const sessionId = client.getPersistedProperty('sessionId')
+   * ```
+   *
+   * {@label Initialization}
+   *
+   * @param key - The property key to retrieve
+   * @returns The stored property value or undefined if not found
+   */
   getPersistedProperty(key) {
     return this._memoryStorage.getProperty(key);
   }
+  /**
+   * Set a persisted property value in memory storage.
+   *
+   * @example
+   * ```ts
+   * // Set user ID
+   * client.setPersistedProperty('userId', 'user_123')
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Set session ID
+   * client.setPersistedProperty('sessionId', 'session_456')
+   * ```
+   *
+   * {@label Initialization}
+   *
+   * @param key - The property key to set
+   * @param value - The value to store (null to remove)
+   */
   setPersistedProperty(key, value) {
     return this._memoryStorage.setProperty(key, value);
   }
+  /**
+   * Make an HTTP request using the configured fetch function or default fetch.
+   *
+   * @example
+   * ```ts
+   * // POST request
+   * const response = await client.fetch('/api/endpoint', {
+   *   method: 'POST',
+   *   headers: { 'Content-Type': 'application/json' },
+   *   body: JSON.stringify(data)
+   * })
+   * ```
+   *
+   * @internal
+   *
+   * {@label Initialization}
+   *
+   * @param url - The URL to fetch
+   * @param options - Fetch options
+   * @returns Promise resolving to the fetch response
+   */
   fetch(url, options) {
     return this.options.fetch ? this.options.fetch(url, options) : fetch(url, options);
   }
+  /**
+   * Get the library version from package.json.
+   *
+   * @example
+   * ```ts
+   * // Get version
+   * const version = client.getLibraryVersion()
+   * console.log(`Using PostHog SDK version: ${version}`)
+   * ```
+   *
+   * {@label Initialization}
+   *
+   * @returns The current library version string
+   */
   getLibraryVersion() {
     return version;
   }
+  /**
+   * Get the custom user agent string for this client.
+   *
+   * @example
+   * ```ts
+   * // Get user agent
+   * const userAgent = client.getCustomUserAgent()
+   * // Returns: "posthog-node/5.7.0"
+   * ```
+   *
+   * {@label Identification}
+   *
+   * @returns The formatted user agent string
+   */
   getCustomUserAgent() {
     return `${this.getLibraryId()}/${this.getLibraryVersion()}`;
   }
+  /**
+   * Enable the PostHog client (opt-in).
+   *
+   * @example
+   * ```ts
+   * // Enable client
+   * await client.enable()
+   * // Client is now enabled and will capture events
+   * ```
+   *
+   * {@label Privacy}
+   *
+   * @returns Promise that resolves when the client is enabled
+   */
   enable() {
     return super.optIn();
   }
+  /**
+   * Disable the PostHog client (opt-out).
+   *
+   * @example
+   * ```ts
+   * // Disable client
+   * await client.disable()
+   * // Client is now disabled and will not capture events
+   * ```
+   *
+   * {@label Privacy}
+   *
+   * @returns Promise that resolves when the client is disabled
+   */
   disable() {
     return super.optOut();
   }
+  /**
+   * Enable or disable debug logging.
+   *
+   * @example
+   * ```ts
+   * // Enable debug logging
+   * client.debug(true)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Disable debug logging
+   * client.debug(false)
+   * ```
+   *
+   * {@label Initialization}
+   *
+   * @param enabled - Whether to enable debug logging
+   */
   debug(enabled = true) {
     super.debug(enabled);
     this.featureFlagsPoller?.debug(enabled);
   }
+  /**
+   * Capture an event manually.
+   *
+   * @example
+   * ```ts
+   * // Basic capture
+   * client.capture({
+   *   distinctId: 'user_123',
+   *   event: 'button_clicked',
+   *   properties: { button_color: 'red' }
+   * })
+   * ```
+   *
+   * {@label Capture}
+   *
+   * @param props - The event properties
+   * @returns void
+   */
   capture(props) {
     if (typeof props === 'string') {
       this.logMsgIfDebug(() => console.warn('Called capture() with a string as the first argument when an object was expected.'));
     }
-    const {
+    this.addPendingPromise(this.prepareEventMessage(props).then(({
       distinctId,
       event,
       properties,
-      groups,
-      sendFeatureFlags,
-      timestamp,
-      disableGeoip,
-      uuid
-    } = props;
-    // Run before_send if configured
-    const eventMessage = this._runBeforeSend({
-      distinctId,
-      event,
-      properties,
-      groups,
-      sendFeatureFlags,
-      timestamp,
-      disableGeoip,
-      uuid
-    });
-    if (!eventMessage) {
-      return;
-    }
-    const _capture = props => {
-      super.captureStateless(eventMessage.distinctId, eventMessage.event, props, {
-        timestamp: eventMessage.timestamp,
-        disableGeoip: eventMessage.disableGeoip,
-        uuid: eventMessage.uuid
+      options
+    }) => {
+      return super.captureStateless(distinctId, event, properties, {
+        timestamp: options.timestamp,
+        disableGeoip: options.disableGeoip,
+        uuid: options.uuid
       });
-    };
-    // :TRICKY: If we flush, or need to shut down, to not lose events we want this promise to resolve before we flush
-    const capturePromise = Promise.resolve().then(async () => {
-      if (sendFeatureFlags) {
-        // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
-        const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined;
-        return await this.getFeatureFlagsForEvent(distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
-      }
-      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 {};
-      }
-      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;
+    }).catch(err => {
+      if (err) {
+        console.error(err);
       }
-      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,
-        ...(eventMessage.properties || {}),
-        $groups: eventMessage.groups || groups
-      });
-    });
-    this.addPendingPromise(capturePromise);
+    }));
   }
+  /**
+   * Capture an event immediately (synchronously).
+   *
+   * @example
+   * ```ts
+   * // Basic immediate capture
+   * await client.captureImmediate({
+   *   distinctId: 'user_123',
+   *   event: 'button_clicked',
+   *   properties: { button_color: 'red' }
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With feature flags
+   * await client.captureImmediate({
+   *   distinctId: 'user_123',
+   *   event: 'user_action',
+   *   sendFeatureFlags: true
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With custom feature flags options
+   * await client.captureImmediate({
+   *   distinctId: 'user_123',
+   *   event: 'user_action',
+   *   sendFeatureFlags: {
+   *     onlyEvaluateLocally: true,
+   *     personProperties: { plan: 'premium' },
+   *     groupProperties: { org: { tier: 'enterprise' } }
+   *     flagKeys: ['flag1', 'flag2']
+   *   }
+   * })
+   * ```
+   *
+   * {@label Capture}
+   *
+   * @param props - The event properties
+   * @returns Promise that resolves when the event is captured
+   */
   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.'));
+      this.logMsgIfDebug(() => console.warn('Called captureImmediate() with a string as the first argument when an object was expected.'));
     }
-    const {
-      distinctId,
-      event,
-      properties,
-      groups,
-      sendFeatureFlags,
-      timestamp,
-      disableGeoip,
-      uuid
-    } = props;
-    // Run before_send if configured
-    const eventMessage = this._runBeforeSend({
+    return this.addPendingPromise(this.prepareEventMessage(props).then(({
       distinctId,
       event,
       properties,
-      groups,
-      sendFeatureFlags,
-      timestamp,
-      disableGeoip,
-      uuid
-    });
-    if (!eventMessage) {
-      return;
-    }
-    const _capture = props => {
-      return super.captureStatelessImmediate(eventMessage.distinctId, eventMessage.event, props, {
-        timestamp: eventMessage.timestamp,
-        disableGeoip: eventMessage.disableGeoip,
-        uuid: eventMessage.uuid
+      options
+    }) => {
+      return super.captureStatelessImmediate(distinctId, event, properties, {
+        timestamp: options.timestamp,
+        disableGeoip: options.disableGeoip,
+        uuid: options.uuid
       });
-    };
-    const capturePromise = Promise.resolve().then(async () => {
-      if (sendFeatureFlags) {
-        // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
-        const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined;
-        return await this.getFeatureFlagsForEvent(distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
-      }
-      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 {};
+    }).catch(err => {
+      if (err) {
+        console.error(err);
       }
-      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,
-        ...(eventMessage.properties || {}),
-        $groups: eventMessage.groups || groups
-      });
-    });
-    await capturePromise;
+    }));
   }
+  /**
+   * Identify a user and set their properties.
+   *
+   * @example
+   * ```ts
+   * // Basic identify with properties
+   * client.identify({
+   *   distinctId: 'user_123',
+   *   properties: {
+   *     name: 'John Doe',
+   *     email: 'john@example.com',
+   *     plan: 'premium'
+   *   }
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Using $set and $set_once
+   * client.identify({
+   *   distinctId: 'user_123',
+   *   properties: {
+   *     $set: { name: 'John Doe', email: 'john@example.com' },
+   *     $set_once: { first_login: new Date().toISOString() }
+   *   }
+   * })
+   * ```
+   *
+   * {@label Identification}
+   *
+   * @param data - The identify data containing distinctId and properties
+   */
   identify({
     distinctId,
     properties,
@@ -2297,6 +2463,26 @@ class PostHogBackendClient extends PostHogCoreStateless {
       disableGeoip
     });
   }
+  /**
+   * Identify a user and set their properties immediately (synchronously).
+   *
+   * @example
+   * ```ts
+   * // Basic immediate identify
+   * await client.identifyImmediate({
+   *   distinctId: 'user_123',
+   *   properties: {
+   *     name: 'John Doe',
+   *     email: 'john@example.com'
+   *   }
+   * })
+   * ```
+   *
+   * {@label Identification}
+   *
+   * @param data - The identify data containing distinctId and properties
+   * @returns Promise that resolves when the identify is processed
+   */
   async identifyImmediate({
     distinctId,
     properties,
@@ -2314,19 +2500,96 @@ class PostHogBackendClient extends PostHogCoreStateless {
       disableGeoip
     });
   }
+  /**
+   * Create an alias to link two distinct IDs together.
+   *
+   * @example
+   * ```ts
+   * // Link an anonymous user to an identified user
+   * client.alias({
+   *   distinctId: 'anonymous_123',
+   *   alias: 'user_456'
+   * })
+   * ```
+   *
+   * {@label Identification}
+   *
+   * @param data - The alias data containing distinctId and alias
+   */
   alias(data) {
     super.aliasStateless(data.alias, data.distinctId, undefined, {
       disableGeoip: data.disableGeoip
     });
   }
+  /**
+   * Create an alias to link two distinct IDs together immediately (synchronously).
+   *
+   * @example
+   * ```ts
+   * // Link an anonymous user to an identified user immediately
+   * await client.aliasImmediate({
+   *   distinctId: 'anonymous_123',
+   *   alias: 'user_456'
+   * })
+   * ```
+   *
+   * {@label Identification}
+   *
+   * @param data - The alias data containing distinctId and alias
+   * @returns Promise that resolves when the alias is processed
+   */
   async aliasImmediate(data) {
     await super.aliasStatelessImmediate(data.alias, data.distinctId, undefined, {
       disableGeoip: data.disableGeoip
     });
   }
+  /**
+   * Check if local evaluation of feature flags is ready.
+   *
+   * @example
+   * ```ts
+   * // Check if ready
+   * if (client.isLocalEvaluationReady()) {
+   *   // Local evaluation is ready, can evaluate flags locally
+   *   const flag = await client.getFeatureFlag('flag-key', 'user_123')
+   * } else {
+   *   // Local evaluation not ready, will use remote evaluation
+   *   const flag = await client.getFeatureFlag('flag-key', 'user_123')
+   * }
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @returns true if local evaluation is ready, false otherwise
+   */
   isLocalEvaluationReady() {
     return this.featureFlagsPoller?.isLocalEvaluationReady() ?? false;
   }
+  /**
+   * Wait for local evaluation of feature flags to be ready.
+   *
+   * @example
+   * ```ts
+   * // Wait for local evaluation
+   * const isReady = await client.waitForLocalEvaluationReady()
+   * if (isReady) {
+   *   console.log('Local evaluation is ready')
+   * } else {
+   *   console.log('Local evaluation timed out')
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Wait with custom timeout
+   * const isReady = await client.waitForLocalEvaluationReady(10000) // 10 seconds
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param timeoutMs - Timeout in milliseconds (default: 30000)
+   * @returns Promise that resolves to true if ready, false if timed out
+   */
   async waitForLocalEvaluationReady(timeoutMs = THIRTY_SECONDS) {
     if (this.isLocalEvaluationReady()) {
       return true;
@@ -2346,6 +2609,47 @@ class PostHogBackendClient extends PostHogCoreStateless {
       });
     });
   }
+  /**
+   * Get the value of a feature flag for a specific user.
+   *
+   * @example
+   * ```ts
+   * // Basic feature flag check
+   * const flagValue = await client.getFeatureFlag('new-feature', 'user_123')
+   * if (flagValue === 'variant-a') {
+   *   // Show variant A
+   * } else if (flagValue === 'variant-b') {
+   *   // Show variant B
+   * } else {
+   *   // Flag is disabled or not found
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With groups and properties
+   * const flagValue = await client.getFeatureFlag('org-feature', 'user_123', {
+   *   groups: { organization: 'acme-corp' },
+   *   personProperties: { plan: 'enterprise' },
+   *   groupProperties: { organization: { tier: 'premium' } }
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Only evaluate locally
+   * const flagValue = await client.getFeatureFlag('local-flag', 'user_123', {
+   *   onlyEvaluateLocally: true
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param key - The feature flag key
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to the flag value or undefined
+   */
   async getFeatureFlag(key, distinctId, options) {
     const {
       groups,
@@ -2365,7 +2669,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
       onlyEvaluateLocally = false;
     }
     if (sendFeatureFlagEvents == undefined) {
-      sendFeatureFlagEvents = true;
+      sendFeatureFlagEvents = this.options.sendFeatureFlagEvent ?? true;
     }
     let response = await this.featureFlagsPoller?.getFeatureFlag(key, distinctId, groups, personProperties, groupProperties);
     const flagWasLocallyEvaluated = response !== undefined;
@@ -2409,6 +2713,41 @@ class PostHogBackendClient extends PostHogCoreStateless {
     }
     return response;
   }
+  /**
+   * Get the payload for a feature flag.
+   *
+   * @example
+   * ```ts
+   * // Get payload for a feature flag
+   * const payload = await client.getFeatureFlagPayload('flag-key', 'user_123')
+   * if (payload) {
+   *   console.log('Flag payload:', payload)
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Get payload with specific match value
+   * const payload = await client.getFeatureFlagPayload('flag-key', 'user_123', 'variant-a')
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With groups and properties
+   * const payload = await client.getFeatureFlagPayload('org-flag', 'user_123', undefined, {
+   *   groups: { organization: 'acme-corp' },
+   *   personProperties: { plan: 'enterprise' }
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param key - The feature flag key
+   * @param distinctId - The user's distinct ID
+   * @param matchValue - Optional match value to get payload for
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to the flag payload or undefined
+   */
   async getFeatureFlagPayload(key, distinctId, matchValue, options) {
     const {
       groups,
@@ -2416,7 +2755,6 @@ class PostHogBackendClient extends PostHogCoreStateless {
     } = options || {};
     let {
       onlyEvaluateLocally,
-      sendFeatureFlagEvents,
       personProperties,
       groupProperties
     } = options || {};
@@ -2441,15 +2779,30 @@ class PostHogBackendClient extends PostHogCoreStateless {
     if (onlyEvaluateLocally == undefined) {
       onlyEvaluateLocally = false;
     }
-    if (sendFeatureFlagEvents == undefined) {
-      sendFeatureFlagEvents = true;
-    }
     const payloadWasLocallyEvaluated = response !== undefined;
     if (!payloadWasLocallyEvaluated && !onlyEvaluateLocally) {
       response = await super.getFeatureFlagPayloadStateless(key, distinctId, groups, personProperties, groupProperties, disableGeoip);
     }
     return response;
   }
+  /**
+   * Get the remote config payload for a feature flag.
+   *
+   * @example
+   * ```ts
+   * // Get remote config payload
+   * const payload = await client.getRemoteConfigPayload('flag-key')
+   * if (payload) {
+   *   console.log('Remote config payload:', payload)
+   * }
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param flagKey - The feature flag key
+   * @returns Promise that resolves to the remote config payload or undefined
+   * @throws Error if personal API key is not provided
+   */
   async getRemoteConfigPayload(flagKey) {
     if (!this.options.personalApiKey) {
       throw new Error('Personal API key is required for remote config payload decryption');
@@ -2473,6 +2826,38 @@ class PostHogBackendClient extends PostHogCoreStateless {
     }
     return parsed;
   }
+  /**
+   * Check if a feature flag is enabled for a specific user.
+   *
+   * @example
+   * ```ts
+   * // Basic feature flag check
+   * const isEnabled = await client.isFeatureEnabled('new-feature', 'user_123')
+   * if (isEnabled) {
+   *   // Feature is enabled
+   *   console.log('New feature is active')
+   * } else {
+   *   // Feature is disabled
+   *   console.log('New feature is not active')
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With groups and properties
+   * const isEnabled = await client.isFeatureEnabled('org-feature', 'user_123', {
+   *   groups: { organization: 'acme-corp' },
+   *   personProperties: { plan: 'enterprise' }
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param key - The feature flag key
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to true if enabled, false if disabled, undefined if not found
+   */
   async isFeatureEnabled(key, distinctId, options) {
     const feat = await this.getFeatureFlag(key, distinctId, options);
     if (feat === undefined) {
@@ -2480,10 +2865,77 @@ class PostHogBackendClient extends PostHogCoreStateless {
     }
     return !!feat || false;
   }
+  /**
+   * Get all feature flag values for a specific user.
+   *
+   * @example
+   * ```ts
+   * // Get all flags for a user
+   * const allFlags = await client.getAllFlags('user_123')
+   * console.log('User flags:', allFlags)
+   * // Output: { 'flag-1': 'variant-a', 'flag-2': false, 'flag-3': 'variant-b' }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With specific flag keys
+   * const specificFlags = await client.getAllFlags('user_123', {
+   *   flagKeys: ['flag-1', 'flag-2']
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With groups and properties
+   * const orgFlags = await client.getAllFlags('user_123', {
+   *   groups: { organization: 'acme-corp' },
+   *   personProperties: { plan: 'enterprise' }
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to a record of flag keys and their values
+   */
   async getAllFlags(distinctId, options) {
     const response = await this.getAllFlagsAndPayloads(distinctId, options);
     return response.featureFlags || {};
   }
+  /**
+   * Get all feature flag values and payloads for a specific user.
+   *
+   * @example
+   * ```ts
+   * // Get all flags and payloads for a user
+   * const result = await client.getAllFlagsAndPayloads('user_123')
+   * console.log('Flags:', result.featureFlags)
+   * console.log('Payloads:', result.featureFlagPayloads)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With specific flag keys
+   * const result = await client.getAllFlagsAndPayloads('user_123', {
+   *   flagKeys: ['flag-1', 'flag-2']
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Only evaluate locally
+   * const result = await client.getAllFlagsAndPayloads('user_123', {
+   *   onlyEvaluateLocally: true
+   * })
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @param distinctId - The user's distinct ID
+   * @param options - Optional configuration for flag evaluation
+   * @returns Promise that resolves to flags and payloads
+   */
   async getAllFlagsAndPayloads(distinctId, options) {
     const {
       groups,
@@ -2527,6 +2979,41 @@ class PostHogBackendClient extends PostHogCoreStateless {
       featureFlagPayloads
     };
   }
+  /**
+   * Create or update a group and its properties.
+   *
+   * @example
+   * ```ts
+   * // Create a company group
+   * client.groupIdentify({
+   *   groupType: 'company',
+   *   groupKey: 'acme-corp',
+   *   properties: {
+   *     name: 'Acme Corporation',
+   *     industry: 'Technology',
+   *     employee_count: 500
+   *   },
+   *   distinctId: 'user_123'
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Update organization properties
+   * client.groupIdentify({
+   *   groupType: 'organization',
+   *   groupKey: 'org-456',
+   *   properties: {
+   *     plan: 'enterprise',
+   *     region: 'US-West'
+   *   }
+   * })
+   * ```
+   *
+   * {@label Identification}
+   *
+   * @param data - The group identify data
+   */
   groupIdentify({
     groupType,
     groupKey,
@@ -2539,14 +3026,52 @@ class PostHogBackendClient extends PostHogCoreStateless {
     }, 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.
+   * Reload feature flag definitions from the server for local evaluation.
+   *
+   * @example
+   * ```ts
+   * // Force reload of feature flags
+   * await client.reloadFeatureFlags()
+   * console.log('Feature flags reloaded')
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Reload before checking a specific flag
+   * await client.reloadFeatureFlags()
+   * const flag = await client.getFeatureFlag('flag-key', 'user_123')
+   * ```
+   *
+   * {@label Feature flags}
+   *
+   * @returns Promise that resolves when flags are reloaded
    */
   async reloadFeatureFlags() {
     await this.featureFlagsPoller?.loadFeatureFlags(true);
   }
+  /**
+   * Shutdown the PostHog client gracefully.
+   *
+   * @example
+   * ```ts
+   * // Shutdown with default timeout
+   * await client._shutdown()
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Shutdown with custom timeout
+   * await client._shutdown(5000) // 5 seconds
+   * ```
+   *
+   * {@label Shutdown}
+   *
+   * @param shutdownTimeoutMs - Timeout in milliseconds for shutdown
+   * @returns Promise that resolves when shutdown is complete
+   */
   async _shutdown(shutdownTimeoutMs) {
     this.featureFlagsPoller?.stopPoller();
+    this.errorTracking.shutdown();
     return super._shutdown(shutdownTimeoutMs);
   }
   async _requestRemoteConfigPayload(flagKey) {
@@ -2565,7 +3090,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
     let abortTimeout = null;
     if (this.options.requestTimeout && typeof this.options.requestTimeout === 'number') {
       const controller = new AbortController();
-      abortTimeout = safeSetTimeout(() => {
+      abortTimeout = safeSetTimeout$1(() => {
         controller.abort();
       }, this.options.requestTimeout);
       options.signal = controller.signal;
@@ -2672,20 +3197,159 @@ class PostHogBackendClient extends PostHogCoreStateless {
       allGroupProperties
     };
   }
+  /**
+   * Capture an error exception as an event.
+   *
+   * @example
+   * ```ts
+   * // Capture an error with user ID
+   * try {
+   *   // Some risky operation
+   *   riskyOperation()
+   * } catch (error) {
+   *   client.captureException(error, 'user_123')
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Capture with additional properties
+   * try {
+   *   apiCall()
+   * } catch (error) {
+   *   client.captureException(error, 'user_123', {
+   *     endpoint: '/api/users',
+   *     method: 'POST',
+   *     status_code: 500
+   *   })
+   * }
+   * ```
+   *
+   * {@label Error tracking}
+   *
+   * @param error - The error to capture
+   * @param distinctId - Optional user distinct ID
+   * @param additionalProperties - Optional additional properties to include
+   */
   captureException(error, distinctId, additionalProperties) {
     const syntheticException = new Error('PostHog syntheticException');
-    ErrorTracking.buildEventMessage(error, {
+    this.addPendingPromise(ErrorTracking.buildEventMessage(error, {
       syntheticException
-    }, distinctId, additionalProperties).then(msg => {
-      this.capture(msg);
-    });
+    }, distinctId, additionalProperties).then(msg => this.capture(msg)));
   }
+  /**
+   * Capture an error exception as an event immediately (synchronously).
+   *
+   * @example
+   * ```ts
+   * // Capture an error immediately with user ID
+   * try {
+   *   // Some risky operation
+   *   riskyOperation()
+   * } catch (error) {
+   *   await client.captureExceptionImmediate(error, 'user_123')
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Capture with additional properties
+   * try {
+   *   apiCall()
+   * } catch (error) {
+   *   await client.captureExceptionImmediate(error, 'user_123', {
+   *     endpoint: '/api/users',
+   *     method: 'POST',
+   *     status_code: 500
+   *   })
+   * }
+   * ```
+   *
+   * {@label Error tracking}
+   *
+   * @param error - The error to capture
+   * @param distinctId - Optional user distinct ID
+   * @param additionalProperties - Optional additional properties to include
+   * @returns Promise that resolves when the error is captured
+   */
   async captureExceptionImmediate(error, distinctId, additionalProperties) {
     const syntheticException = new Error('PostHog syntheticException');
-    const evtMsg = await ErrorTracking.buildEventMessage(error, {
+    this.addPendingPromise(ErrorTracking.buildEventMessage(error, {
       syntheticException
-    }, distinctId, additionalProperties);
-    return await this.captureImmediate(evtMsg);
+    }, distinctId, additionalProperties).then(msg => this.captureImmediate(msg)));
+  }
+  async prepareEventMessage(props) {
+    const {
+      distinctId,
+      event,
+      properties,
+      groups,
+      sendFeatureFlags,
+      timestamp,
+      disableGeoip,
+      uuid
+    } = props;
+    // Run before_send if configured
+    const eventMessage = this._runBeforeSend({
+      distinctId,
+      event,
+      properties,
+      groups,
+      sendFeatureFlags,
+      timestamp,
+      disableGeoip,
+      uuid
+    });
+    if (!eventMessage) {
+      return Promise.reject(null);
+    }
+    // :TRICKY: If we flush, or need to shut down, to not lose events we want this promise to resolve before we flush
+    const eventProperties = await Promise.resolve().then(async () => {
+      if (sendFeatureFlags) {
+        // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
+        const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined;
+        return await this.getFeatureFlagsForEvent(distinctId, groups, disableGeoip, sendFeatureFlagsOptions);
+      }
+      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 {};
+      }
+      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
+      const props = {
+        ...additionalProperties,
+        ...(eventMessage.properties || {}),
+        $groups: eventMessage.groups || groups
+      };
+      return props;
+    });
+    return {
+      distinctId: eventMessage.distinctId,
+      event: eventMessage.event,
+      properties: eventProperties,
+      options: {
+        timestamp: eventMessage.timestamp,
+        disableGeoip: eventMessage.disableGeoip,
+        uuid: eventMessage.uuid
+      }
+    };
   }
   _runBeforeSend(eventMessage) {
     const beforeSend = this.options.before_send;