posthog-node 5.14.0 → 5.15.0

package/dist/extensions/feature-flags/feature-flags.js

@@ -68,7 +68,6 @@ class FeatureFlagsPoller {
         this.debugMode = false;
         this.shouldBeginExponentialBackoff = false;
         this.backOffCount = 0;
-        this.hasAttemptedCacheLoad = false;
         this.pollingInterval = pollingInterval;
         this.personalApiKey = personalApiKey;
         this.featureFlags = [];
@@ -296,15 +295,11 @@ class FeatureFlagsPoller {
         }
     }
     async loadFeatureFlags(forceReload = false) {
-        if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
-            this.hasAttemptedCacheLoad = true;
-            await this.loadFromCache('Loaded flags from cache');
-        }
-        if (this.loadingPromise) return this.loadingPromise;
-        if (!this.loadedSuccessfullyOnce || forceReload) {
-            this.loadingPromise = this._loadFeatureFlags();
-            await this.loadingPromise;
-        }
+        if (this.loadedSuccessfullyOnce && !forceReload) return;
+        if (!this.loadingPromise) this.loadingPromise = this._loadFeatureFlags().catch((err)=>this.logMsgIfDebug(()=>console.debug(`[FEATURE FLAGS] Failed to load feature flags: ${err}`))).finally(()=>{
+            this.loadingPromise = void 0;
+        });
+        return this.loadingPromise;
     }
     isLocalEvaluationReady() {
         return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
@@ -318,7 +313,7 @@ class FeatureFlagsPoller {
             clearTimeout(this.poller);
             this.poller = void 0;
         }
-        this.poller = setTimeout(()=>this._loadFeatureFlags(), this.getPollingInterval());
+        this.poller = setTimeout(()=>this.loadFeatureFlags(true), this.getPollingInterval());
         try {
             let shouldFetch = true;
             if (this.cacheProvider) try {
@@ -378,8 +373,6 @@ class FeatureFlagsPoller {
             }
         } catch (err) {
             if (err instanceof ClientError) this.onError?.(err);
-        } finally{
-            this.loadingPromise = void 0;
         }
     }
     getPersonalApiKeyRequestOptions(method = 'GET') {

package/dist/extensions/feature-flags/feature-flags.mjs

@@ -35,7 +35,6 @@ class FeatureFlagsPoller {
         this.debugMode = false;
         this.shouldBeginExponentialBackoff = false;
         this.backOffCount = 0;
-        this.hasAttemptedCacheLoad = false;
         this.pollingInterval = pollingInterval;
         this.personalApiKey = personalApiKey;
         this.featureFlags = [];
@@ -263,15 +262,11 @@ class FeatureFlagsPoller {
         }
     }
     async loadFeatureFlags(forceReload = false) {
-        if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
-            this.hasAttemptedCacheLoad = true;
-            await this.loadFromCache('Loaded flags from cache');
-        }
-        if (this.loadingPromise) return this.loadingPromise;
-        if (!this.loadedSuccessfullyOnce || forceReload) {
-            this.loadingPromise = this._loadFeatureFlags();
-            await this.loadingPromise;
-        }
+        if (this.loadedSuccessfullyOnce && !forceReload) return;
+        if (!this.loadingPromise) this.loadingPromise = this._loadFeatureFlags().catch((err)=>this.logMsgIfDebug(()=>console.debug(`[FEATURE FLAGS] Failed to load feature flags: ${err}`))).finally(()=>{
+            this.loadingPromise = void 0;
+        });
+        return this.loadingPromise;
     }
     isLocalEvaluationReady() {
         return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
@@ -285,7 +280,7 @@ class FeatureFlagsPoller {
             clearTimeout(this.poller);
             this.poller = void 0;
         }
-        this.poller = setTimeout(()=>this._loadFeatureFlags(), this.getPollingInterval());
+        this.poller = setTimeout(()=>this.loadFeatureFlags(true), this.getPollingInterval());
         try {
             let shouldFetch = true;
             if (this.cacheProvider) try {
@@ -345,8 +340,6 @@ class FeatureFlagsPoller {
             }
         } catch (err) {
             if (err instanceof ClientError) this.onError?.(err);
-        } finally{
-            this.loadingPromise = void 0;
         }
     }
     getPersonalApiKeyRequestOptions(method = 'GET') {

package/dist/types.d.ts

@@ -1,30 +1,32 @@
 import type { PostHogCoreOptions, FeatureFlagValue, JsonType, PostHogFetchOptions, PostHogFetchResponse } from '@posthog/core';
+import { ContextData, ContextOptions } from './extensions/context/types';
 import type { FlagDefinitionCacheProvider } from './extensions/feature-flags/cache';
-export interface IdentifyMessage {
+export type IdentifyMessage = {
     distinctId: string;
     properties?: Record<string | number, any>;
     disableGeoip?: boolean;
-}
-export interface SendFeatureFlagsOptions {
+};
+export type SendFeatureFlagsOptions = {
     onlyEvaluateLocally?: boolean;
     personProperties?: Record<string, any>;
     groupProperties?: Record<string, Record<string, any>>;
     flagKeys?: string[];
-}
-export interface EventMessage extends IdentifyMessage {
+};
+export type EventMessage = Omit<IdentifyMessage, 'distinctId'> & {
+    distinctId?: string;
     event: string;
     groups?: Record<string, string | number>;
     sendFeatureFlags?: boolean | SendFeatureFlagsOptions;
     timestamp?: Date;
     uuid?: string;
-}
-export interface GroupIdentifyMessage {
+};
+export type GroupIdentifyMessage = {
     groupType: string;
     groupKey: string;
     properties?: Record<string | number, any>;
     distinctId?: string;
     disableGeoip?: boolean;
-}
+};
 export type PropertyGroup = {
     type: 'AND' | 'OR';
     values: PropertyGroup[] | FlagProperty[];
@@ -294,6 +296,19 @@ export interface IPostHog {
      * already polled automatically at a regular interval.
      */
     reloadFeatureFlags(): Promise<void>;
+    /**
+     * @description Run a function with specific context that will be applied to all events captured within that context.
+     * @param data Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
+     * @param fn Function to run with the context
+     * @param options Context options (fresh)
+     * @returns The return value of the function
+     */
+    withContext<T>(data: Partial<ContextData>, fn: () => T, options?: ContextOptions): T;
+    /**
+     * @description Get the current context data.
+     * @returns The current context data, or undefined if no context is set
+     */
+    getContext(): ContextData | undefined;
     /**
      * @description Flushes the events still in the queue and clears the feature flags poller to allow for
      * a clean shutdown.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "5.14.0";
+export declare const version = "5.15.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     version: ()=>version
 });
-const version = '5.14.0';
+const version = '5.15.0';
 exports.version = __webpack_exports__.version;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "version"

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = '5.14.0';
+const version = '5.15.0';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "5.14.0",
+  "version": "5.15.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",
@@ -28,10 +28,11 @@
     "@posthog/core": "1.6.0"
   },
   "devDependencies": {
+    "@rslib/core": "0.10.6",
+    "@types/express": "^5.0.5",
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.0.0",
     "jest": "29.7.0",
-    "@types/jest": "^29.5.14",
-    "@rslib/core": "0.10.6",
     "@posthog-tooling/tsconfig-base": "1.1.0"
   },
   "keywords": [

package/src/client.ts

@@ -8,7 +8,6 @@ import {
   PostHogFetchResponse,
   PostHogFlagsAndPayloadsResponse,
   PostHogPersistedProperty,
-  Logger,
   PostHogCaptureOptions,
   isPlainObject,
   isBlockedUA,
@@ -30,6 +29,8 @@ import {
 import ErrorTracking from './extensions/error-tracking'
 import { safeSetTimeout, PostHogEventProperties } from '@posthog/core'
 import { PostHogMemoryStorage } from './storage-memory'
+import { uuidv7 } from '@posthog/core'
+import { ContextData, ContextOptions, IPostHogContext } from './extensions/context/types'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
 // so the fastest a poller should ever be set is 100ms.
@@ -45,6 +46,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   protected errorTracking: ErrorTracking
   private maxCacheSize: number
   public readonly options: PostHogOptions
+  protected readonly context?: IPostHogContext
 
   distinctIdHasSentFlagCalls: Record<string, string[]>
 
@@ -81,6 +83,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     super(apiKey, options)
 
     this.options = options
+    this.context = this.initializeContext()
 
     this.options.featureFlagsPollingInterval =
       typeof options.featureFlagsPollingInterval === 'number'
@@ -1159,6 +1162,60 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     await this.featureFlagsPoller?.loadFeatureFlags(true)
   }
 
+  protected abstract initializeContext(): IPostHogContext | undefined
+
+  /**
+   * Run a function with specific context that will be applied to all events captured within that context.
+   * It propagates the context to all subsequent calls down the call stack.
+   * Context properties like tags and sessionId will be automatically attached to all events.
+   *
+   * @example
+   * ```ts
+   * posthog.withContext(
+   *   { distinctId: 'user_123' },
+   *   () => {
+   *     posthog.capture({ event: 'button clicked' })
+   *   },
+   *   { fresh: false }
+   * )
+   * ```
+   *
+   * {@label Context}
+   *
+   * @param data - Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
+   * @param fn - Function to run with the context
+   * @param options - Context options (fresh)
+   * @returns The return value of the function
+   */
+  withContext<T>(data: Partial<ContextData>, fn: () => T, options?: ContextOptions): T {
+    if (!this.context) {
+      // Context not supported in this environment (e.g., edge runtime)
+      return fn()
+    }
+
+    return this.context.run(data, fn, options)
+  }
+
+  /**
+   * Get the current context data.
+   *
+   * @example
+   * ```ts
+   * // Get current context within a withContext block
+   * posthog.withContext({ distinctId: 'user_123' }, () => {
+   *   const context = posthog.getContext()
+   *   console.log(context?.distinctId) // 'user_123'
+   * })
+   * ```
+   *
+   * {@label Context}
+   *
+   * @returns The current context data, or undefined if no context is set
+   */
+  getContext(): ContextData | undefined {
+    return this.context?.get()
+  }
+
   /**
    * Shutdown the PostHog client gracefully.
    *
@@ -1439,11 +1496,29 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     const { distinctId, event, properties, groups, sendFeatureFlags, timestamp, disableGeoip, uuid }: EventMessage =
       props
 
+    const contextData = this.context?.get()
+
+    let mergedDistinctId = distinctId || contextData?.distinctId
+
+    const mergedProperties = {
+      ...(contextData?.properties || {}),
+      ...(properties || {}),
+    }
+
+    if (!mergedDistinctId) {
+      mergedDistinctId = uuidv7()
+      mergedProperties.$process_person_profile = false
+    }
+
+    if (contextData?.sessionId && !mergedProperties.$session_id) {
+      mergedProperties.$session_id = contextData.sessionId
+    }
+
     // Run before_send if configured
     const eventMessage = this._runBeforeSend({
-      distinctId,
+      distinctId: mergedDistinctId,
       event,
-      properties,
+      properties: mergedProperties,
       groups,
       sendFeatureFlags,
       timestamp,
@@ -1461,10 +1536,15 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         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)
+          return await this.getFeatureFlagsForEvent(
+            eventMessage.distinctId!,
+            groups,
+            disableGeoip,
+            sendFeatureFlagsOptions
+          )
         }
 
-        if (event === '$feature_flag_called') {
+        if (eventMessage.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 {}
         }
@@ -1514,7 +1594,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
 
     return {
-      distinctId: eventMessage.distinctId,
+      distinctId: eventMessage.distinctId!,
       event: eventMessage.event,
       properties: eventProperties,
       options: {

package/src/entrypoints/index.edge.ts

@@ -19,4 +19,8 @@ export class PostHog extends PostHogBackendClient {
   getLibraryId(): string {
     return 'posthog-edge'
   }
+
+  protected initializeContext(): undefined {
+    return undefined
+  }
 }

package/src/entrypoints/index.node.ts

@@ -6,6 +6,7 @@ import ErrorTracking from '../extensions/error-tracking'
 
 import { PostHogBackendClient } from '../client'
 import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
+import { PostHogContext } from '../extensions/context/context'
 
 ErrorTracking.errorPropertiesBuilder = new CoreErrorTracking.ErrorPropertiesBuilder(
   [
@@ -23,4 +24,8 @@ export class PostHog extends PostHogBackendClient {
   getLibraryId(): string {
     return 'posthog-node'
   }
+
+  protected initializeContext(): PostHogContext {
+    return new PostHogContext()
+  }
 }

package/src/extensions/context/context.ts

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { ContextData, ContextOptions, IPostHogContext } from './types'
+
+export class PostHogContext implements IPostHogContext {
+  private storage: AsyncLocalStorage<ContextData>
+
+  constructor() {
+    this.storage = new AsyncLocalStorage<ContextData>()
+  }
+
+  get(): ContextData | undefined {
+    return this.storage.getStore()
+  }
+
+  run<T>(context: ContextData, fn: () => T, options?: ContextOptions): T {
+    const fresh = options?.fresh !== false
+
+    if (fresh) {
+      return this.storage.run(context, fn)
+    } else {
+      const currentContext = this.get() || {}
+      const mergedContext: ContextData = {
+        distinctId: context.distinctId ?? currentContext.distinctId,
+        sessionId: context.sessionId ?? currentContext.sessionId,
+        properties: {
+          ...(currentContext.properties || {}),
+          ...(context.properties || {}),
+        },
+      }
+      return this.storage.run(mergedContext, fn)
+    }
+  }
+}

package/src/extensions/context/types.ts

@@ -0,0 +1,19 @@
+export interface ContextData {
+  distinctId?: string
+  sessionId?: string
+  properties?: Record<string, any>
+}
+
+export interface ContextOptions {
+  /**
+   * If true, replaces the current context entirely.
+   * If false, merges with the existing context (new values override existing ones).
+   * @default true
+   */
+  fresh?: boolean
+}
+
+export interface IPostHogContext {
+  get(): ContextData | undefined
+  run<T>(context: ContextData, fn: () => T, options?: ContextOptions): T
+}

package/src/extensions/error-tracking/autocapture.ts

@@ -50,13 +50,13 @@ export function addUncaughtExceptionListener(
   captureFn: (exception: Error, hint: CoreErrorTracking.EventHint) => void,
   onFatalFn: (exception: Error) => void
 ): void {
-  global.process.on('uncaughtException', makeUncaughtExceptionHandler(captureFn, onFatalFn))
+  globalThis.process?.on('uncaughtException', makeUncaughtExceptionHandler(captureFn, onFatalFn))
 }
 
 export function addUnhandledRejectionListener(
   captureFn: (exception: unknown, hint: CoreErrorTracking.EventHint) => void
 ): void {
-  global.process.on('unhandledRejection', (reason: unknown) => {
+  globalThis.process?.on('unhandledRejection', (reason: unknown) => {
     return captureFn(reason, {
       mechanism: {
         type: 'onunhandledrejection',

package/src/extensions/express.ts

@@ -1,15 +1,14 @@
-import type * as http from 'node:http'
-import { uuidv7 } from '@posthog/core'
 import ErrorTracking from './error-tracking'
 import { PostHogBackendClient } from '../client'
 import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
+import type { Request, Response } from 'express'
 
-type ExpressMiddleware = (req: http.IncomingMessage, res: http.ServerResponse, next: () => void) => void
+type ExpressMiddleware = (req: Request, res: Response, next: () => void) => void
 
 type ExpressErrorMiddleware = (
   error: MiddlewareError,
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
+  req: Request,
+  res: Response,
   next: (error: MiddlewareError) => void
 ) => void
 
@@ -28,13 +27,30 @@ export function setupExpressErrorHandler(
     use: (middleware: ExpressMiddleware | ExpressErrorMiddleware) => unknown
   }
 ): void {
-  app.use((error: MiddlewareError, _, __, next: (error: MiddlewareError) => void): void => {
-    const hint: CoreErrorTracking.EventHint = { mechanism: { type: 'middleware', handled: false } }
-    // Given stateless nature of Node SDK we capture exceptions using personless processing
-    // when no user can be determined e.g. in the case of exception autocapture
-    ErrorTracking.buildEventMessage(error, hint, uuidv7(), { $process_person_profile: false }).then((msg) =>
-      _posthog.capture(msg)
+  app.use(posthogErrorHandler(_posthog))
+}
+
+function posthogErrorHandler(posthog: PostHogBackendClient): ExpressErrorMiddleware {
+  return (error: MiddlewareError, req, res, next: (error: MiddlewareError) => void): void => {
+    const sessionId: string | undefined = req.headers['x-posthog-session-id'] as string | undefined
+    const distinctId: string | undefined = req.headers['x-posthog-distinct-id'] as string | undefined
+    const syntheticException = new Error('Synthetic exception')
+    const hint: CoreErrorTracking.EventHint = { mechanism: { type: 'middleware', handled: false }, syntheticException }
+
+    posthog.addPendingPromise(
+      ErrorTracking.buildEventMessage(error, hint, distinctId, {
+        $session_id: sessionId,
+        $current_url: req.url,
+        $request_method: req.method,
+        $request_path: req.path,
+        $user_agent: req.headers['user-agent'],
+        $response_status_code: res.statusCode,
+        $ip: req.headers['x-forwarded-for'] || req?.socket?.remoteAddress,
+      }).then((msg) => {
+        posthog.capture(msg)
+      })
     )
+
     next(error)
-  })
+  }
 }

package/src/extensions/feature-flags/feature-flags.ts

@@ -77,7 +77,6 @@ class FeatureFlagsPoller {
   backOffCount: number = 0
   onLoad?: (count: number) => void
   private cacheProvider?: FlagDefinitionCacheProvider
-  private hasAttemptedCacheLoad: boolean = false
   private loadingPromise?: Promise<void>
 
   constructor({
@@ -582,21 +581,19 @@ class FeatureFlagsPoller {
   }
 
   async loadFeatureFlags(forceReload = false): Promise<void> {
-    // On first load, try to initialize from cache (if a cache provider is configured)
-    if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
-      this.hasAttemptedCacheLoad = true
-      await this.loadFromCache('Loaded flags from cache')
+    if (this.loadedSuccessfullyOnce && !forceReload) {
+      return
     }
 
-    // If a fetch is already in progress, wait for it
-    if (this.loadingPromise) {
-      return this.loadingPromise
-    }
-
-    if (!this.loadedSuccessfullyOnce || forceReload) {
+    if (!this.loadingPromise) {
       this.loadingPromise = this._loadFeatureFlags()
-      await this.loadingPromise
+        .catch((err) => this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] Failed to load feature flags: ${err}`)))
+        .finally(() => {
+          this.loadingPromise = undefined
+        })
     }
+
+    return this.loadingPromise
   }
 
   /**
@@ -627,7 +624,7 @@ class FeatureFlagsPoller {
       this.poller = undefined
     }
 
-    this.poller = setTimeout(() => this._loadFeatureFlags(), this.getPollingInterval())
+    this.poller = setTimeout(() => this.loadFeatureFlags(true), this.getPollingInterval())
 
     try {
       let shouldFetch = true
@@ -764,8 +761,6 @@ class FeatureFlagsPoller {
       if (err instanceof ClientError) {
         this.onError?.(err)
       }
-    } finally {
-      this.loadingPromise = undefined
     }
   }
 

package/src/types.ts

@@ -5,23 +5,25 @@ import type {
   PostHogFetchOptions,
   PostHogFetchResponse,
 } from '@posthog/core'
+import { ContextData, ContextOptions } from './extensions/context/types'
 
 import type { FlagDefinitionCacheProvider } from './extensions/feature-flags/cache'
 
-export interface IdentifyMessage {
+export type IdentifyMessage = {
   distinctId: string
   properties?: Record<string | number, any>
   disableGeoip?: boolean
 }
 
-export interface SendFeatureFlagsOptions {
+export type SendFeatureFlagsOptions = {
   onlyEvaluateLocally?: boolean
   personProperties?: Record<string, any>
   groupProperties?: Record<string, Record<string, any>>
   flagKeys?: string[]
 }
 
-export interface EventMessage extends IdentifyMessage {
+export type EventMessage = Omit<IdentifyMessage, 'distinctId'> & {
+  distinctId?: string // Optional - can be provided via context
   event: string
   groups?: Record<string, string | number> // Mapping of group type to group id
   sendFeatureFlags?: boolean | SendFeatureFlagsOptions
@@ -29,7 +31,7 @@ export interface EventMessage extends IdentifyMessage {
   uuid?: string
 }
 
-export interface GroupIdentifyMessage {
+export type GroupIdentifyMessage = {
   groupType: string
   groupKey: string // Unique identifier for the group
   properties?: Record<string | number, any>
@@ -335,6 +337,21 @@ export interface IPostHog {
    */
   reloadFeatureFlags(): Promise<void>
 
+  /**
+   * @description Run a function with specific context that will be applied to all events captured within that context.
+   * @param data Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
+   * @param fn Function to run with the context
+   * @param options Context options (fresh)
+   * @returns The return value of the function
+   */
+  withContext<T>(data: Partial<ContextData>, fn: () => T, options?: ContextOptions): T
+
+  /**
+   * @description Get the current context data.
+   * @returns The current context data, or undefined if no context is set
+   */
+  getContext(): ContextData | undefined
+
   /**
    * @description Flushes the events still in the queue and clears the feature flags poller to allow for
    * a clean shutdown.

package/src/version.ts

@@ -1 +1 @@
-export const version = '5.14.0'
+export const version = '5.15.0'