posthog-node 5.8.1 → 5.8.3

package/dist/edge/index.cjs

@@ -780,7 +780,7 @@ function setupExpressErrorHandler(_posthog, app) {
   });
 }
 
-var version = "5.8.1";
+var version = "5.8.3";
 
 /**
  * A lazy value that is only computed when needed. Inspired by C#'s Lazy<T> class.
@@ -967,12 +967,14 @@ class FeatureFlagsPoller {
     const payloads = {};
     let fallbackToFlags = this.featureFlags.length == 0;
     const flagsToEvaluate = flagKeysToExplicitlyEvaluate ? flagKeysToExplicitlyEvaluate.map(key => this.featureFlagsByKey[key]).filter(Boolean) : this.featureFlags;
+    // Create a shared evaluation cache to prevent memory leaks when processing many flags
+    const sharedEvaluationCache = {};
     await Promise.all(flagsToEvaluate.map(async flag => {
       try {
         const {
           value: matchValue,
           payload: matchPayload
-        } = await this.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties);
+        } = await this.computeFlagAndPayloadLocally(flag, distinctId, groups, personProperties, groupProperties, undefined /* matchValue */, sharedEvaluationCache);
         response[flag.key] = matchValue;
         if (matchPayload) {
           payloads[flag.key] = matchPayload;
@@ -992,9 +994,11 @@ class FeatureFlagsPoller {
       fallbackToFlags
     };
   }
-  async computeFlagAndPayloadLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}, matchValue) {
-    // Always ensure flags are loaded for payload computation
-    await this.loadFeatureFlags();
+  async computeFlagAndPayloadLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}, matchValue, evaluationCache, skipLoadCheck = false) {
+    // Only load flags if not already loaded and not skipping the check
+    if (!skipLoadCheck) {
+      await this.loadFeatureFlags();
+    }
     if (!this.loadedSuccessfullyOnce) {
       return {
         value: false,
@@ -1006,7 +1010,7 @@ class FeatureFlagsPoller {
     if (matchValue !== undefined) {
       flagValue = matchValue;
     } else {
-      flagValue = await this.computeFlagValueLocally(flag, distinctId, groups, personProperties, groupProperties);
+      flagValue = await this.computeFlagValueLocally(flag, distinctId, groups, personProperties, groupProperties, evaluationCache);
     }
     // Always compute payload based on the final flagValue (whether provided or computed)
     const payload = this.getFeatureFlagPayload(flag.key, flagValue);
@@ -1015,7 +1019,7 @@ class FeatureFlagsPoller {
       payload
     };
   }
-  async computeFlagValueLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
+  async computeFlagValueLocally(flag, distinctId, groups = {}, personProperties = {}, groupProperties = {}, evaluationCache = {}) {
     if (flag.ensure_experience_continuity) {
       throw new InconclusiveMatchError('Flag has experience continuity enabled');
     }
@@ -1035,9 +1039,9 @@ class FeatureFlagsPoller {
         return false;
       }
       const focusedGroupProperties = groupProperties[groupName];
-      return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties);
+      return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties, evaluationCache);
     } else {
-      return await this.matchFeatureFlagProperties(flag, distinctId, personProperties);
+      return await this.matchFeatureFlagProperties(flag, distinctId, personProperties, evaluationCache);
     }
   }
   getFeatureFlagPayload(key, flagValue) {
@@ -1681,6 +1685,35 @@ const THIRTY_SECONDS = 30 * 1000;
 const MAX_CACHE_SIZE = 50 * 1000;
 // The actual exported Nodejs API.
 class PostHogBackendClient extends core.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();
@@ -1716,31 +1749,185 @@ class PostHogBackendClient extends core.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.'));
@@ -1762,6 +1949,49 @@ class PostHogBackendClient extends core.PostHogCoreStateless {
       }
     }));
   }
+  /**
+   * 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 captureImmediate() with a string as the first argument when an object was expected.'));
@@ -1783,6 +2013,38 @@ class PostHogBackendClient extends core.PostHogCoreStateless {
       }
     }));
   }
+  /**
+   * 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,
@@ -1801,6 +2063,26 @@ class PostHogBackendClient extends core.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,
@@ -1818,19 +2100,96 @@ class PostHogBackendClient extends core.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;
@@ -1850,6 +2209,47 @@ class PostHogBackendClient extends core.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,
@@ -1869,7 +2269,7 @@ class PostHogBackendClient extends core.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;
@@ -1913,6 +2313,41 @@ class PostHogBackendClient extends core.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,
@@ -1920,7 +2355,6 @@ class PostHogBackendClient extends core.PostHogCoreStateless {
     } = options || {};
     let {
       onlyEvaluateLocally,
-      sendFeatureFlagEvents,
       personProperties,
       groupProperties
     } = options || {};
@@ -1945,15 +2379,30 @@ class PostHogBackendClient extends core.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');
@@ -1977,6 +2426,38 @@ class PostHogBackendClient extends core.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) {
@@ -1984,10 +2465,77 @@ class PostHogBackendClient extends core.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,
@@ -2031,6 +2579,41 @@ class PostHogBackendClient extends core.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,
@@ -2043,12 +2626,49 @@ class PostHogBackendClient extends core.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();
@@ -2177,12 +2797,81 @@ class PostHogBackendClient extends core.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');
     this.addPendingPromise(ErrorTracking.buildEventMessage(error, {
       syntheticException
     }, 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');
     this.addPendingPromise(ErrorTracking.buildEventMessage(error, {