@posthog/next 0.1.0 → 0.4.44

package/src/server/getPostHog.ts

@@ -2,10 +2,11 @@ import 'server-only'
 
 import { isFunction } from '@posthog/core'
 import type { PostHogOptions, IPostHog } from 'posthog-node'
-import { cookies } from 'next/headers'
-import { getOrCreateNodeClient } from './nodeClientCache'
-import { readPostHogCookie, cookieStateToProperties, isOptedOut } from '../shared/cookie'
-import { resolveApiKey } from '../shared/config'
+import { cookies, headers } from 'next/headers.js'
+import { getOrCreateNodeClient } from './nodeClientCache.js'
+import { readPostHogCookie, isOptedOut } from '../shared/cookie.js'
+import { resolveApiKey, resolveHostOrDefault } from '../shared/config.js'
+import { readTracingHeaders, buildContextData } from '../shared/tracing-headers.js'
 
 /**
  * Returns a PostHog server client scoped to the current request.
@@ -14,7 +15,7 @@ import { resolveApiKey } from '../shared/config'
  * request-scoped client. Methods like `getAllFlags()`, `getFeatureFlagResult()`,
  * and `capture()` automatically use the current user's identity.
  *
- * Calls `cookies()` internally, which opts the route into dynamic rendering.
+ * Calls `cookies()` and `headers()` internally, which opts the route into dynamic rendering.
  *
  * @param apiKey - PostHog project API key. If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY`.
  * @param options - Optional `posthog-node` configuration (e.g., `{ host: '...' }`).
@@ -34,8 +35,8 @@ import { resolveApiKey } from '../shared/config'
  */
 export async function getPostHog(apiKey?: string, options?: Partial<PostHogOptions>): Promise<IPostHog> {
     const resolvedApiKey = resolveApiKey(apiKey)
-    const host = options?.host ?? process.env.NEXT_PUBLIC_POSTHOG_HOST
-    const resolvedOptions = host ? { ...options, host } : options
+    const host = resolveHostOrDefault(options?.host)
+    const resolvedOptions = { ...options, host }
     const client = await getOrCreateNodeClient(resolvedApiKey, resolvedOptions)
     const cookieStore = await cookies()
 
@@ -44,8 +45,9 @@ export async function getPostHog(apiKey?: string, options?: Partial<PostHogOptio
     }
 
     const state = readPostHogCookie(cookieStore, resolvedApiKey)
-    const properties = cookieStateToProperties(state)
-    const contextData = { distinctId: state?.distinctId, sessionId: state?.sessionId, properties }
+    const headerStore = await headers()
+    const tracing = readTracingHeaders(headerStore)
+    const contextData = buildContextData(tracing, state)
 
     // Wrap the shared client in a Proxy that applies request-scoped context
     // to every method call. We can't use enterContext() here because

package/src/shared/config.ts

@@ -1,5 +1,6 @@
 import type { PostHogConfig } from 'posthog-js'
 import type { PostHogOptions } from 'posthog-node'
+import { DEFAULT_API_HOST } from './constants.js'
 
 /**
  * Configuration for the client-side PostHog provider.
@@ -19,8 +20,13 @@ export type PostHogServerConfig = PostHogOptions
  *
  * Throws if neither is available.
  */
+export function normalizeConfigValue(value?: unknown): string | undefined {
+    const normalizedValue = typeof value === 'string' ? value.trim() : ''
+    return normalizedValue || undefined
+}
+
 export function resolveApiKey(apiKey?: string): string {
-    const resolved = apiKey || process.env.NEXT_PUBLIC_POSTHOG_KEY
+    const resolved = normalizeConfigValue(apiKey) ?? normalizeConfigValue(process.env.NEXT_PUBLIC_POSTHOG_KEY)
     if (!resolved) {
         throw new Error(
             '[PostHog Next.js] apiKey is required. Either pass it explicitly or set the NEXT_PUBLIC_POSTHOG_KEY environment variable.'
@@ -29,6 +35,14 @@ export function resolveApiKey(apiKey?: string): string {
     return resolved
 }
 
+export function resolveHost(host?: string): string | undefined {
+    return normalizeConfigValue(host) ?? normalizeConfigValue(process.env.NEXT_PUBLIC_POSTHOG_HOST)
+}
+
+export function resolveHostOrDefault(host?: string): string {
+    return resolveHost(host) ?? DEFAULT_API_HOST
+}
+
 /**
  * Next.js-specific defaults for the posthog-js client.
  *

package/src/shared/cookie.ts

@@ -1,5 +1,5 @@
 import { uuidv7, isNoLike, isArray } from '@posthog/core'
-import { COOKIE_PREFIX, COOKIE_SUFFIX } from './constants'
+import { COOKIE_PREFIX, COOKIE_SUFFIX } from './constants.js'
 
 /**
  * Minimal cookie-reading interface compatible with Next.js `cookies()`,

package/src/shared/tracing-headers.ts

@@ -0,0 +1,67 @@
+import { isFunction, isArray } from '@posthog/core'
+import type { PostHogCookieState } from './cookie.js'
+import { cookieStateToProperties } from './cookie.js'
+
+/**
+ * Header names used by the PostHog browser SDK's tracing headers feature.
+ *
+ * When `__add_tracing_headers` is enabled in the browser SDK, these headers
+ * are added to outgoing fetch/XHR requests so that server-side code can
+ * correlate events back to the browser session.
+ */
+export const POSTHOG_SESSION_ID_HEADER = 'x-posthog-session-id'
+export const POSTHOG_DISTINCT_ID_HEADER = 'x-posthog-distinct-id'
+export const POSTHOG_WINDOW_ID_HEADER = 'x-posthog-window-id'
+
+export interface TracingHeaderValues {
+    distinctId?: string
+    sessionId?: string
+    windowId?: string
+}
+
+/**
+ * Extracts PostHog tracing header values from request headers.
+ *
+ * Accepts either a Headers-like object with a `.get()` method (e.g. from
+ * `next/headers`) or a plain record (e.g. `ctx.req.headers` in Pages Router).
+ */
+export function readTracingHeaders(
+    headers: { get(name: string): string | null } | Record<string, string | string[] | undefined>
+): TracingHeaderValues {
+    const getValue = (name: string): string | undefined => {
+        if (isFunction((headers as { get: unknown }).get)) {
+            return (headers as { get(name: string): string | null }).get(name) ?? undefined
+        }
+        const value = (headers as Record<string, string | string[] | undefined>)[name]
+        return typeof value === 'string' ? value : isArray(value) ? value[0] : undefined
+    }
+
+    return {
+        distinctId: getValue(POSTHOG_DISTINCT_ID_HEADER) || undefined,
+        sessionId: getValue(POSTHOG_SESSION_ID_HEADER) || undefined,
+        windowId: getValue(POSTHOG_WINDOW_ID_HEADER) || undefined,
+    }
+}
+
+/**
+ * Builds context data by merging cookie state with tracing headers.
+ *
+ * Tracing headers take precedence over cookie values for `distinctId` and
+ * `sessionId` because they represent the browser's current state and are
+ * set per-request by the browser SDK.
+ */
+export function buildContextData(
+    tracing: TracingHeaderValues,
+    state: PostHogCookieState | null
+): { distinctId: string | undefined; sessionId: string | undefined; properties: Record<string, string> | undefined } {
+    const mergedProperties: Record<string, string> = {
+        ...cookieStateToProperties(state),
+        ...(tracing.sessionId ? { $session_id: tracing.sessionId } : {}),
+        ...(tracing.windowId ? { $window_id: tracing.windowId } : {}),
+    }
+    return {
+        distinctId: tracing.distinctId || state?.distinctId,
+        sessionId: tracing.sessionId || state?.sessionId,
+        properties: Object.keys(mergedProperties).length > 0 ? mergedProperties : undefined,
+    }
+}