@posthog/next 0.1.0

package/dist/server/getPostHog.d.ts

@@ -0,0 +1,29 @@
+import 'server-only';
+import type { PostHogOptions, IPostHog } from 'posthog-node';
+/**
+ * Returns a PostHog server client scoped to the current request.
+ *
+ * Reads the user's identity from the PostHog cookie and returns a
+ * 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.
+ *
+ * @param apiKey - PostHog project API key. If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY`.
+ * @param options - Optional `posthog-node` configuration (e.g., `{ host: '...' }`).
+ * @returns A `posthog-node` client scoped to the current user.
+ *
+ * @example
+ * ```ts
+ * import { getPostHog } from '@posthog/next'
+ *
+ * export default async function Page() {
+ *     const posthog = await getPostHog()
+ *     const flags = await posthog.getAllFlags()
+ *     posthog.capture({ event: 'page_viewed' })
+ *     return <div>...</div>
+ * }
+ * ```
+ */
+export declare function getPostHog(apiKey?: string, options?: Partial<PostHogOptions>): Promise<IPostHog>;
+//# sourceMappingURL=getPostHog.d.ts.map

package/dist/server/getPostHog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPostHog.d.ts","sourceRoot":"","sources":["../../src/server/getPostHog.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAM5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CA+BtG"}

package/dist/server/getPostHog.js

@@ -0,0 +1,61 @@
+import 'server-only';
+import { isFunction } from '@posthog/core';
+import { cookies } from 'next/headers';
+import { getOrCreateNodeClient } from './nodeClientCache';
+import { readPostHogCookie, cookieStateToProperties, isOptedOut } from '../shared/cookie';
+import { resolveApiKey } from '../shared/config';
+/**
+ * Returns a PostHog server client scoped to the current request.
+ *
+ * Reads the user's identity from the PostHog cookie and returns a
+ * 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.
+ *
+ * @param apiKey - PostHog project API key. If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY`.
+ * @param options - Optional `posthog-node` configuration (e.g., `{ host: '...' }`).
+ * @returns A `posthog-node` client scoped to the current user.
+ *
+ * @example
+ * ```ts
+ * import { getPostHog } from '@posthog/next'
+ *
+ * export default async function Page() {
+ *     const posthog = await getPostHog()
+ *     const flags = await posthog.getAllFlags()
+ *     posthog.capture({ event: 'page_viewed' })
+ *     return <div>...</div>
+ * }
+ * ```
+ */
+export async function getPostHog(apiKey, options) {
+    const resolvedApiKey = resolveApiKey(apiKey);
+    const host = options?.host ?? process.env.NEXT_PUBLIC_POSTHOG_HOST;
+    const resolvedOptions = host ? { ...options, host } : options;
+    const client = await getOrCreateNodeClient(resolvedApiKey, resolvedOptions);
+    const cookieStore = await cookies();
+    if (isOptedOut(cookieStore, resolvedApiKey)) {
+        return client;
+    }
+    const state = readPostHogCookie(cookieStore, resolvedApiKey);
+    const properties = cookieStateToProperties(state);
+    const contextData = { distinctId: state?.distinctId, sessionId: state?.sessionId, properties };
+    // Wrap the shared client in a Proxy that applies request-scoped context
+    // to every method call. We can't use enterContext() here because
+    // AsyncLocalStorage.enterWith() doesn't propagate back to the caller
+    // across the await boundary of this async function.
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'withContext') {
+                return Reflect.get(target, prop, receiver);
+            }
+            const value = Reflect.get(target, prop, receiver);
+            if (isFunction(value)) {
+                return (...args) => target.withContext(contextData, () => value.apply(target, args));
+            }
+            return value;
+        },
+    });
+}
+//# sourceMappingURL=getPostHog.js.map

package/dist/server/getPostHog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPostHog.js","sourceRoot":"","sources":["../../src/server/getPostHog.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAA;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAe,EAAE,OAAiC,EAAqB;IACpG,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAA;IAClE,MAAM,eAAe,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAA;IAC7D,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,cAAc,EAAE,eAAe,CAAC,CAAA;IAC3E,MAAM,WAAW,GAAG,MAAM,OAAO,EAAE,CAAA;IAEnC,IAAI,UAAU,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,CAAC;QAC1C,OAAO,MAAM,CAAA;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,iBAAiB,CAAC,WAAW,EAAE,cAAc,CAAC,CAAA;IAC5D,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAA;IACjD,MAAM,WAAW,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,CAAA;IAE9F,wEAAwE;IACxE,iEAAiE;IACjE,qEAAqE;IACrE,oDAAoD;IACpD,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACrB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxB,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;gBACzB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;YAC9C,CAAC;YACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;YACjD,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;YACnG,CAAC;YACD,OAAO,KAAK,CAAA;QAAA,CACf;KACJ,CAAa,CAAA;AAAA,CACjB"}

package/dist/server/nodeClientCache.d.ts

@@ -0,0 +1,14 @@
+import { PostHog } from 'posthog-node';
+import type { PostHogOptions } from 'posthog-node';
+/**
+ * Returns a cached PostHog node client, creating one if needed.
+ *
+ * Clients are cached by project key + host. Only the options from the first
+ * call for a given key+host pair take effect; subsequent calls with different
+ * options (e.g. flushAt, flushInterval) will return the existing client.
+ *
+ * On first call, awaits auto-detection of @vercel/functions waitUntil
+ * and merges it into options. Explicit options.waitUntil takes priority.
+ */
+export declare function getOrCreateNodeClient(apiKey: string, options?: Partial<PostHogOptions>): Promise<PostHog>;
+//# sourceMappingURL=nodeClientCache.d.ts.map

package/dist/server/nodeClientCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeClientCache.d.ts","sourceRoot":"","sources":["../../src/server/nodeClientCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAYlD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAa/G"}

package/dist/server/nodeClientCache.js

@@ -0,0 +1,33 @@
+import { PostHog } from 'posthog-node';
+const cache = new Map();
+// Auto-detect waitUntil from @vercel/functions at module load.
+// Fails gracefully in environments where it's not available.
+const autoDetectedWaitUntil = import(
+/* webpackIgnore: true */ '@vercel/functions')
+    .then((mod) => mod.waitUntil)
+    .catch(() => undefined);
+/**
+ * Returns a cached PostHog node client, creating one if needed.
+ *
+ * Clients are cached by project key + host. Only the options from the first
+ * call for a given key+host pair take effect; subsequent calls with different
+ * options (e.g. flushAt, flushInterval) will return the existing client.
+ *
+ * On first call, awaits auto-detection of @vercel/functions waitUntil
+ * and merges it into options. Explicit options.waitUntil takes priority.
+ */
+export async function getOrCreateNodeClient(apiKey, options) {
+    const key = `${apiKey}:${options?.host ?? ''}`;
+    let client = cache.get(key);
+    if (!client) {
+        const waitUntil = options?.waitUntil ?? (await autoDetectedWaitUntil);
+        const mergedOptions = {
+            ...(waitUntil ? { waitUntil } : {}),
+            ...options,
+        };
+        client = new PostHog(apiKey, mergedOptions);
+        cache.set(key, client);
+    }
+    return client;
+}
+//# sourceMappingURL=nodeClientCache.js.map

package/dist/server/nodeClientCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeClientCache.js","sourceRoot":"","sources":["../../src/server/nodeClientCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGtC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAA;AAExC,+DAA+D;AAC/D,6DAA6D;AAC7D,MAAM,qBAAqB,GAAyD,MAAM;AACtF,yBAAyB,CAAC,mBAAmB,CAChD;KACI,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC;KAC5B,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;AAE3B;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,MAAc,EAAE,OAAiC,EAAoB;IAC7G,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,EAAE,IAAI,IAAI,EAAE,EAAE,CAAA;IAC9C,IAAI,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,CAAC,MAAM,qBAAqB,CAAC,CAAA;QACrE,MAAM,aAAa,GAA4B;YAC3C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,OAAO;SACb,CAAA;QACD,MAAM,GAAG,IAAI,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;QAC3C,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,MAAM,CAAA;AAAA,CAChB"}

package/dist/shared/config.d.ts

@@ -0,0 +1,36 @@
+import type { PostHogConfig } from 'posthog-js';
+import type { PostHogOptions } from 'posthog-node';
+/**
+ * Configuration for the client-side PostHog provider.
+ * Extends the standard posthog-js config.
+ */
+export type PostHogClientConfig = Partial<PostHogConfig>;
+/**
+ * Configuration for the server-side PostHog client.
+ * Extends the standard posthog-node options.
+ */
+export type PostHogServerConfig = PostHogOptions;
+/**
+ * Resolves the PostHog API key from an explicit value or the
+ * `NEXT_PUBLIC_POSTHOG_KEY` environment variable.
+ *
+ * Throws if neither is available.
+ */
+export declare function resolveApiKey(apiKey?: string): string;
+/**
+ * Next.js-specific defaults for the posthog-js client.
+ *
+ * These ensure the server can read both identity and consent state from cookies:
+ * - `capture_pageview: false` — disables posthog-js automatic pageviews so the
+ *   `PostHogPageView` component can handle them without duplicates
+ * - `persistence: 'localStorage+cookie'` — already the posthog-js default, made explicit
+ * - `opt_out_capturing_persistence_type: 'cookie'` — writes consent state to a cookie
+ *   so middleware/server components can read it (posthog-js default is 'localStorage')
+ * - `opt_out_persistence_by_default: true` — when opted out, disables persistence
+ *   so posthog-js does not write cookies or localStorage; the middleware
+ *   handles deleting the identity cookie separately
+ *
+ * Users can override any of these via the `options` prop on PostHogProvider.
+ */
+export declare const NEXTJS_CLIENT_DEFAULTS: Partial<PostHogConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/shared/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;AAExD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAA;AAEhD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,EAAE,OAAO,CAAC,aAAa,CAKzD,CAAA"}

package/dist/shared/config.js

@@ -0,0 +1,35 @@
+/**
+ * Resolves the PostHog API key from an explicit value or the
+ * `NEXT_PUBLIC_POSTHOG_KEY` environment variable.
+ *
+ * Throws if neither is available.
+ */
+export function resolveApiKey(apiKey) {
+    const resolved = apiKey || 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.');
+    }
+    return resolved;
+}
+/**
+ * Next.js-specific defaults for the posthog-js client.
+ *
+ * These ensure the server can read both identity and consent state from cookies:
+ * - `capture_pageview: false` — disables posthog-js automatic pageviews so the
+ *   `PostHogPageView` component can handle them without duplicates
+ * - `persistence: 'localStorage+cookie'` — already the posthog-js default, made explicit
+ * - `opt_out_capturing_persistence_type: 'cookie'` — writes consent state to a cookie
+ *   so middleware/server components can read it (posthog-js default is 'localStorage')
+ * - `opt_out_persistence_by_default: true` — when opted out, disables persistence
+ *   so posthog-js does not write cookies or localStorage; the middleware
+ *   handles deleting the identity cookie separately
+ *
+ * Users can override any of these via the `options` prop on PostHogProvider.
+ */
+export const NEXTJS_CLIENT_DEFAULTS = {
+    capture_pageview: false,
+    persistence: 'localStorage+cookie',
+    opt_out_capturing_persistence_type: 'cookie',
+    opt_out_persistence_by_default: true,
+};
+//# sourceMappingURL=config.js.map

package/dist/shared/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe,EAAU;IACnD,MAAM,QAAQ,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAA;IAC9D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACX,0HAA0H,CAC7H,CAAA;IACL,CAAC;IACD,OAAO,QAAQ,CAAA;AAAA,CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC1D,gBAAgB,EAAE,KAAK;IACvB,WAAW,EAAE,qBAAqB;IAClC,kCAAkC,EAAE,QAAQ;IAC5C,8BAA8B,EAAE,IAAI;CACvC,CAAA"}

package/dist/shared/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const COOKIE_PREFIX = "ph_";
+export declare const COOKIE_SUFFIX = "_posthog";
+export declare const DEFAULT_API_HOST = "https://us.i.posthog.com";
+export declare const COOKIE_MAX_AGE_SECONDS: number;
+export declare const DEFAULT_INGEST_PATH = "/ingest";
+//# sourceMappingURL=constants.d.ts.map

package/dist/shared/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,QAAQ,CAAA;AAClC,eAAO,MAAM,aAAa,aAAa,CAAA;AACvC,eAAO,MAAM,gBAAgB,6BAA6B,CAAA;AAC1D,eAAO,MAAM,sBAAsB,QAAqB,CAAA;AACxD,eAAO,MAAM,mBAAmB,YAAY,CAAA"}

package/dist/shared/constants.js

@@ -0,0 +1,6 @@
+export const COOKIE_PREFIX = 'ph_';
+export const COOKIE_SUFFIX = '_posthog';
+export const DEFAULT_API_HOST = 'https://us.i.posthog.com';
+export const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
+export const DEFAULT_INGEST_PATH = '/ingest';
+//# sourceMappingURL=constants.js.map

package/dist/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAClC,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAA;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAA;AAC1D,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAA"}

package/dist/shared/cookie.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Minimal cookie-reading interface compatible with Next.js `cookies()`,
+ * `request.cookies`, and plain objects.
+ */
+export interface CookieStore {
+    get(name: string): {
+        value: string;
+    } | undefined;
+}
+/**
+ * Adapts a raw `Cookie` header string into a {@link CookieStore}.
+ */
+export declare function cookieStoreFromHeader(cookieHeader: string): CookieStore;
+export interface PostHogCookieState {
+    distinctId: string;
+    isIdentified: boolean;
+    sessionId?: string;
+    deviceId?: string;
+}
+/**
+ * Returns the PostHog cookie name for the given API key.
+ *
+ * PostHog-js stores state in a cookie named `ph_<sanitized_token>_posthog`.
+ * The token is sanitized by replacing `+` with `PL`, `/` with `SL`, `=` with `EQ`.
+ *
+ * @param apiKey - The PostHog project API key
+ * @returns The cookie name string
+ */
+export declare function getPostHogCookieName(apiKey: string): string;
+/**
+ * Serializes an anonymous ID into the JSON format posthog-js expects.
+ *
+ * When `distinct_id === $device_id`, posthog-js treats the user as anonymous.
+ *
+ * @param anonymousId - The anonymous distinct ID to serialize
+ * @returns JSON string suitable for the PostHog cookie value
+ */
+export declare function serializePostHogCookie(anonymousId: string): string;
+/**
+ * Reads and parses the PostHog cookie from a cookie store.
+ *
+ * Compatible with Next.js `cookies()`, `request.cookies`, and any object
+ * with a `get(name)` method that returns `{ value: string } | undefined`.
+ */
+export declare function readPostHogCookie(cookies: CookieStore, apiKey: string): PostHogCookieState | null;
+/**
+ * Converts cookie state into PostHog properties (e.g. `$session_id`, `$device_id`).
+ */
+export declare function cookieStateToProperties(state: PostHogCookieState | null): Record<string, string> | undefined;
+/**
+ * Parses a PostHog cookie value and extracts identity information.
+ *
+ * The cookie value is a JSON object containing `distinct_id` and `$user_state`.
+ * A user is considered identified if `$user_state` is `'identified'`.
+ *
+ * @param cookieValue - The raw cookie string value
+ * @returns Parsed identity state, or null if the cookie is missing/invalid
+ */
+export declare function parsePostHogCookie(cookieValue: string): PostHogCookieState | null;
+export interface ConsentCookieConfig {
+    consent_persistence_name?: string | null;
+    opt_out_capturing_cookie_prefix?: string | null;
+}
+export declare function getConsentCookieName(apiKey: string, config?: ConsentCookieConfig): string;
+export interface ConsentConfig extends ConsentCookieConfig {
+    opt_out_capturing_by_default?: boolean;
+}
+export declare function isOptedOut(cookies: CookieStore, apiKey: string, config?: ConsentConfig): boolean;
+//# sourceMappingURL=cookie.d.ts.map

package/dist/shared/cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/shared/cookie.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CACnD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAWvE;AAED,MAAM,WAAW,kBAAkB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CASlE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAIjG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAY5G;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAuBjF;AAED,MAAM,WAAW,mBAAmB;IAChC,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,+BAA+B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAClD;AAID,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAQzF;AAED,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACtD,4BAA4B,CAAC,EAAE,OAAO,CAAA;CACzC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAUhG"}

package/dist/shared/cookie.js

@@ -0,0 +1,126 @@
+import { uuidv7, isNoLike, isArray } from '@posthog/core';
+import { COOKIE_PREFIX, COOKIE_SUFFIX } from './constants';
+/**
+ * Adapts a raw `Cookie` header string into a {@link CookieStore}.
+ */
+export function cookieStoreFromHeader(cookieHeader) {
+    const cookies = {};
+    if (cookieHeader) {
+        for (const pair of cookieHeader.split(';')) {
+            const [key, ...valueParts] = pair.trim().split('=');
+            if (key) {
+                cookies[key.trim()] = decodeURIComponent(valueParts.join('=').trim());
+            }
+        }
+    }
+    return { get: (name) => (name in cookies ? { value: cookies[name] } : undefined) };
+}
+/**
+ * Returns the PostHog cookie name for the given API key.
+ *
+ * PostHog-js stores state in a cookie named `ph_<sanitized_token>_posthog`.
+ * The token is sanitized by replacing `+` with `PL`, `/` with `SL`, `=` with `EQ`.
+ *
+ * @param apiKey - The PostHog project API key
+ * @returns The cookie name string
+ */
+export function getPostHogCookieName(apiKey) {
+    const sanitized = apiKey.replace(/\+/g, 'PL').replace(/\//g, 'SL').replace(/=/g, 'EQ');
+    return `${COOKIE_PREFIX}${sanitized}${COOKIE_SUFFIX}`;
+}
+/**
+ * Serializes an anonymous ID into the JSON format posthog-js expects.
+ *
+ * When `distinct_id === $device_id`, posthog-js treats the user as anonymous.
+ *
+ * @param anonymousId - The anonymous distinct ID to serialize
+ * @returns JSON string suitable for the PostHog cookie value
+ */
+export function serializePostHogCookie(anonymousId) {
+    const now = Date.now();
+    const sessionId = uuidv7();
+    return JSON.stringify({
+        distinct_id: anonymousId,
+        $device_id: anonymousId,
+        $user_state: 'anonymous',
+        $sesid: [now, sessionId, now],
+    });
+}
+/**
+ * Reads and parses the PostHog cookie from a cookie store.
+ *
+ * Compatible with Next.js `cookies()`, `request.cookies`, and any object
+ * with a `get(name)` method that returns `{ value: string } | undefined`.
+ */
+export function readPostHogCookie(cookies, apiKey) {
+    const cookieName = getPostHogCookieName(apiKey);
+    const cookie = cookies.get(cookieName);
+    return cookie ? parsePostHogCookie(cookie.value) : null;
+}
+/**
+ * Converts cookie state into PostHog properties (e.g. `$session_id`, `$device_id`).
+ */
+export function cookieStateToProperties(state) {
+    if (!state) {
+        return undefined;
+    }
+    const props = {};
+    if (state.sessionId) {
+        props.$session_id = state.sessionId;
+    }
+    if (state.deviceId) {
+        props.$device_id = state.deviceId;
+    }
+    return Object.keys(props).length > 0 ? props : undefined;
+}
+/**
+ * Parses a PostHog cookie value and extracts identity information.
+ *
+ * The cookie value is a JSON object containing `distinct_id` and `$user_state`.
+ * A user is considered identified if `$user_state` is `'identified'`.
+ *
+ * @param cookieValue - The raw cookie string value
+ * @returns Parsed identity state, or null if the cookie is missing/invalid
+ */
+export function parsePostHogCookie(cookieValue) {
+    if (!cookieValue) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(cookieValue);
+        if (!parsed || typeof parsed !== 'object' || !parsed.distinct_id) {
+            return null;
+        }
+        // $sesid is stored as [lastActivityTimestamp, sessionId, sessionStartTimestamp]
+        const sesid = isArray(parsed.$sesid) ? parsed.$sesid[1] : undefined;
+        return {
+            distinctId: String(parsed.distinct_id),
+            isIdentified: parsed.$user_state === 'identified',
+            sessionId: typeof sesid === 'string' ? sesid : undefined,
+            deviceId: typeof parsed.$device_id === 'string' ? parsed.$device_id : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const CONSENT_PREFIX = '__ph_opt_in_out_';
+export function getConsentCookieName(apiKey, config) {
+    if (config?.consent_persistence_name) {
+        return config.consent_persistence_name;
+    }
+    if (config?.opt_out_capturing_cookie_prefix) {
+        return config.opt_out_capturing_cookie_prefix + apiKey;
+    }
+    return CONSENT_PREFIX + apiKey;
+}
+export function isOptedOut(cookies, apiKey, config) {
+    const cookieName = getConsentCookieName(apiKey, config);
+    const cookie = cookies.get(cookieName);
+    if (cookie) {
+        return isNoLike(cookie.value);
+    }
+    // No consent cookie means pending — defer to config
+    return config?.opt_out_capturing_by_default ?? false;
+}
+//# sourceMappingURL=cookie.js.map

package/dist/shared/cookie.js.map

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

package/dist/shared/identity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates a random anonymous distinct_id using UUIDv7.
+ * Used as a fallback when no PostHog cookie is available.
+ */
+export declare function generateAnonymousId(): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/shared/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/shared/identity.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/shared/identity.js

@@ -0,0 +1,9 @@
+import { uuidv7 } from '@posthog/core';
+/**
+ * Generates a random anonymous distinct_id using UUIDv7.
+ * Used as a fallback when no PostHog cookie is available.
+ */
+export function generateAnonymousId() {
+    return uuidv7();
+}
+//# sourceMappingURL=identity.js.map

package/dist/shared/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/shared/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEtC;;;GAGG;AACH,MAAM,UAAU,mBAAmB,GAAW;IAC1C,OAAO,MAAM,EAAE,CAAA;AAAA,CAClB"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@posthog/next",
+  "version": "0.1.0",
+  "description": "PostHog integration for Next.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PostHog/posthog-js.git",
+    "directory": "packages/next"
+  },
+  "author": {
+    "name": "PostHog",
+    "email": "hey@posthog.com",
+    "url": "https://posthog.com"
+  },
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "posthog",
+    "nextjs",
+    "analytics",
+    "feature-flags"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "edge-light": "./dist/index.edge.js",
+      "edge": "./dist/index.edge.js",
+      "worker": "./dist/index.edge.js",
+      "browser": "./dist/index.client.js",
+      "react-server": "./dist/index.js",
+      "default": "./dist/index.client.js"
+    },
+    "./pages": {
+      "types": "./dist/pages.d.ts",
+      "default": "./dist/pages.js"
+    }
+  },
+  "main": "./dist/index.client.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__"
+  ],
+  "dependencies": {
+    "server-only": "^0.0.1",
+    "@posthog/core": "1.23.2",
+    "posthog-js": "1.359.1",
+    "posthog-node": "5.28.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.0",
+    "@typescript/native-preview": "7.0.0-dev.20260216.1",
+    "@vercel/functions": "^3.4.3",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "5.8.2",
+    "@posthog-tooling/tsconfig-base": "1.1.1"
+  },
+  "peerDependencies": {
+    "@vercel/functions": ">=1.0.0",
+    "next": ">=13.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@vercel/functions": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsgo -p tsconfig.build.json",
+    "dev": "tsgo -p tsconfig.build.json --watch",
+    "test:unit": "jest",
+    "test": "pnpm test:unit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "package": "pnpm pack --out $PACKAGE_DEST/%s.tgz"
+  }
+}