@posthog/core 1.28.7 → 1.29.0

package/dist/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/cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../src/cookie.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CACjD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAmBvE;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;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;IAClC,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,+BAA+B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD;AAID,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAQzF;AAED,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACxD,4BAA4B,CAAC,EAAE,OAAO,CAAA;CACvC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAUhG"}

package/dist/cookie.js

@@ -0,0 +1,137 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    getConsentCookieName: ()=>getConsentCookieName,
+    parsePostHogCookie: ()=>parsePostHogCookie,
+    isOptedOut: ()=>isOptedOut,
+    readPostHogCookie: ()=>readPostHogCookie,
+    serializePostHogCookie: ()=>serializePostHogCookie,
+    cookieStateToProperties: ()=>cookieStateToProperties,
+    getPostHogCookieName: ()=>getPostHogCookieName,
+    cookieStoreFromHeader: ()=>cookieStoreFromHeader
+});
+const index_js_namespaceObject = require("./utils/index.js");
+const uuidv7_js_namespaceObject = require("./vendor/uuidv7.js");
+const COOKIE_PREFIX = 'ph_';
+const COOKIE_SUFFIX = '_posthog';
+function cookieStoreFromHeader(cookieHeader) {
+    const cookies = {};
+    if (cookieHeader) for (const pair of cookieHeader.split(';')){
+        const [key, ...valueParts] = pair.trim().split('=');
+        if (key) {
+            const raw = valueParts.join('=').trim();
+            try {
+                cookies[key.trim()] = decodeURIComponent(raw);
+            } catch  {
+                cookies[key.trim()] = raw;
+            }
+        }
+    }
+    return {
+        get: (name)=>name in cookies ? {
+                value: cookies[name]
+            } : void 0
+    };
+}
+function getPostHogCookieName(apiKey) {
+    const sanitized = apiKey.replace(/\+/g, 'PL').replace(/\//g, 'SL').replace(/=/g, 'EQ');
+    return `${COOKIE_PREFIX}${sanitized}${COOKIE_SUFFIX}`;
+}
+function serializePostHogCookie(anonymousId) {
+    const now = Date.now();
+    const sessionId = (0, uuidv7_js_namespaceObject.uuidv7)();
+    return JSON.stringify({
+        distinct_id: anonymousId,
+        $device_id: anonymousId,
+        $user_state: 'anonymous',
+        $sesid: [
+            now,
+            sessionId,
+            now
+        ]
+    });
+}
+function readPostHogCookie(cookies, apiKey) {
+    const cookieName = getPostHogCookieName(apiKey);
+    const cookie = cookies.get(cookieName);
+    return cookie ? parsePostHogCookie(cookie.value) : null;
+}
+function cookieStateToProperties(state) {
+    if (!state) return;
+    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 : void 0;
+}
+function parsePostHogCookie(cookieValue) {
+    if (!cookieValue) return null;
+    try {
+        const parsed = JSON.parse(cookieValue);
+        if (!parsed || 'object' != typeof parsed || !parsed.distinct_id) return null;
+        const sesid = (0, index_js_namespaceObject.isArray)(parsed.$sesid) ? parsed.$sesid[1] : void 0;
+        return {
+            distinctId: String(parsed.distinct_id),
+            isIdentified: 'identified' === parsed.$user_state,
+            sessionId: 'string' == typeof sesid ? sesid : void 0,
+            deviceId: 'string' == typeof parsed.$device_id ? parsed.$device_id : void 0
+        };
+    } catch  {
+        return null;
+    }
+}
+const CONSENT_PREFIX = '__ph_opt_in_out_';
+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;
+}
+function isOptedOut(cookies, apiKey, config) {
+    const cookieName = getConsentCookieName(apiKey, config);
+    const cookie = cookies.get(cookieName);
+    if (cookie) return (0, index_js_namespaceObject.isNoLike)(cookie.value);
+    return config?.opt_out_capturing_by_default ?? false;
+}
+exports.cookieStateToProperties = __webpack_exports__.cookieStateToProperties;
+exports.cookieStoreFromHeader = __webpack_exports__.cookieStoreFromHeader;
+exports.getConsentCookieName = __webpack_exports__.getConsentCookieName;
+exports.getPostHogCookieName = __webpack_exports__.getPostHogCookieName;
+exports.isOptedOut = __webpack_exports__.isOptedOut;
+exports.parsePostHogCookie = __webpack_exports__.parsePostHogCookie;
+exports.readPostHogCookie = __webpack_exports__.readPostHogCookie;
+exports.serializePostHogCookie = __webpack_exports__.serializePostHogCookie;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "cookieStateToProperties",
+    "cookieStoreFromHeader",
+    "getConsentCookieName",
+    "getPostHogCookieName",
+    "isOptedOut",
+    "parsePostHogCookie",
+    "readPostHogCookie",
+    "serializePostHogCookie"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cookie.mjs

@@ -0,0 +1,82 @@
+import { isArray, isNoLike } from "./utils/index.mjs";
+import { uuidv7 } from "./vendor/uuidv7.mjs";
+const COOKIE_PREFIX = 'ph_';
+const COOKIE_SUFFIX = '_posthog';
+function cookieStoreFromHeader(cookieHeader) {
+    const cookies = {};
+    if (cookieHeader) for (const pair of cookieHeader.split(';')){
+        const [key, ...valueParts] = pair.trim().split('=');
+        if (key) {
+            const raw = valueParts.join('=').trim();
+            try {
+                cookies[key.trim()] = decodeURIComponent(raw);
+            } catch  {
+                cookies[key.trim()] = raw;
+            }
+        }
+    }
+    return {
+        get: (name)=>name in cookies ? {
+                value: cookies[name]
+            } : void 0
+    };
+}
+function getPostHogCookieName(apiKey) {
+    const sanitized = apiKey.replace(/\+/g, 'PL').replace(/\//g, 'SL').replace(/=/g, 'EQ');
+    return `${COOKIE_PREFIX}${sanitized}${COOKIE_SUFFIX}`;
+}
+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
+        ]
+    });
+}
+function readPostHogCookie(cookies, apiKey) {
+    const cookieName = getPostHogCookieName(apiKey);
+    const cookie = cookies.get(cookieName);
+    return cookie ? parsePostHogCookie(cookie.value) : null;
+}
+function cookieStateToProperties(state) {
+    if (!state) return;
+    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 : void 0;
+}
+function parsePostHogCookie(cookieValue) {
+    if (!cookieValue) return null;
+    try {
+        const parsed = JSON.parse(cookieValue);
+        if (!parsed || 'object' != typeof parsed || !parsed.distinct_id) return null;
+        const sesid = isArray(parsed.$sesid) ? parsed.$sesid[1] : void 0;
+        return {
+            distinctId: String(parsed.distinct_id),
+            isIdentified: 'identified' === parsed.$user_state,
+            sessionId: 'string' == typeof sesid ? sesid : void 0,
+            deviceId: 'string' == typeof parsed.$device_id ? parsed.$device_id : void 0
+        };
+    } catch  {
+        return null;
+    }
+}
+const CONSENT_PREFIX = '__ph_opt_in_out_';
+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;
+}
+function isOptedOut(cookies, apiKey, config) {
+    const cookieName = getConsentCookieName(apiKey, config);
+    const cookie = cookies.get(cookieName);
+    if (cookie) return isNoLike(cookie.value);
+    return config?.opt_out_capturing_by_default ?? false;
+}
+export { cookieStateToProperties, cookieStoreFromHeader, getConsentCookieName, getPostHogCookieName, isOptedOut, parsePostHogCookie, readPostHogCookie, serializePostHogCookie };

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { PostHogLogs } from './logs';
 export type { BeforeSendLogFn, BufferedLogEntry, CaptureLogger, LogSdkContext, PostHogLogsConfig, ResolvedPostHogLogsConfig, } from './logs/types';
 export type { CaptureLogOptions, LogAttributeValue, LogAttributes, LogSeverityLevel } from './logs/types';
 export { uuidv7 } from './vendor/uuidv7';
+export * from './cookie';
 export * from './posthog-core';
 export * from './posthog-core-stateless';
 export * from './tracing-headers';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,QAAQ,CAAA;AACzF,cAAc,SAAS,CAAA;AACvB,OAAO,KAAK,aAAa,MAAM,kBAAkB,CAAA;AACjD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,GACnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AACpC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,cAAc,CAAA;AAIrB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACzG,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,QAAQ,CAAA;AACzF,cAAc,SAAS,CAAA;AACvB,OAAO,KAAK,aAAa,MAAM,kBAAkB,CAAA;AACjD,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,GACnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AACpC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,cAAc,CAAA;AAIrB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACzG,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -1,5 +1,8 @@
 "use strict";
 var __webpack_modules__ = {
+    "./cookie": function(module) {
+        module.exports = require("./cookie.js");
+    },
     "./error-tracking": function(module) {
         module.exports = require("./error-tracking/index.js");
     },
@@ -86,11 +89,11 @@ var __webpack_exports__ = {};
         buildOtlpLogRecord: ()=>_logs_logs_utils__WEBPACK_IMPORTED_MODULE_4__.buildOtlpLogRecord,
         buildOtlpLogsPayload: ()=>_logs_logs_utils__WEBPACK_IMPORTED_MODULE_4__.buildOtlpLogsPayload,
         getFeatureFlagValue: ()=>_featureFlagUtils__WEBPACK_IMPORTED_MODULE_0__.getFeatureFlagValue,
-        getLengthFromRules: ()=>_surveys_validation__WEBPACK_IMPORTED_MODULE_11__.getLengthFromRules,
+        getLengthFromRules: ()=>_surveys_validation__WEBPACK_IMPORTED_MODULE_12__.getLengthFromRules,
         getOtlpSeverityNumber: ()=>_logs_logs_utils__WEBPACK_IMPORTED_MODULE_4__.getOtlpSeverityNumber,
         getOtlpSeverityText: ()=>_logs_logs_utils__WEBPACK_IMPORTED_MODULE_4__.getOtlpSeverityText,
-        getRequirementsHint: ()=>_surveys_validation__WEBPACK_IMPORTED_MODULE_11__.getRequirementsHint,
-        getValidationError: ()=>_surveys_validation__WEBPACK_IMPORTED_MODULE_11__.getValidationError,
+        getRequirementsHint: ()=>_surveys_validation__WEBPACK_IMPORTED_MODULE_12__.getRequirementsHint,
+        getValidationError: ()=>_surveys_validation__WEBPACK_IMPORTED_MODULE_12__.getValidationError,
         gzipCompress: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.gzipCompress,
         isNativeAsyncGzipError: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.isNativeAsyncGzipError,
         isNativeAsyncGzipReadError: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.isNativeAsyncGzipReadError,
@@ -128,9 +131,33 @@ var __webpack_exports__ = {};
     var _logs_logs_utils__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__("./logs/logs-utils");
     var _logs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__("./logs");
     var _vendor_uuidv7__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__("./vendor/uuidv7");
-    var _posthog_core__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__("./posthog-core");
+    var _cookie__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__("./cookie");
+    var __WEBPACK_REEXPORT_OBJECT__ = {};
+    for(var __WEBPACK_IMPORT_KEY__ in _cookie__WEBPACK_IMPORTED_MODULE_7__)if ([
+        "toOtlpKeyValueList",
+        "PostHogLogs",
+        "isNativeAsyncGzipError",
+        "getOtlpSeverityText",
+        "isNativeAsyncGzipReadError",
+        "getFeatureFlagValue",
+        "uuidv7",
+        "getValidationError",
+        "ErrorTracking",
+        "gzipCompress",
+        "default",
+        "getRequirementsHint",
+        "getOtlpSeverityNumber",
+        "getLengthFromRules",
+        "buildOtlpLogsPayload",
+        "buildOtlpLogRecord",
+        "toOtlpAnyValue"
+    ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
+        return _cookie__WEBPACK_IMPORTED_MODULE_7__[key];
+    }).bind(0, __WEBPACK_IMPORT_KEY__);
+    __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
+    var _posthog_core__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__("./posthog-core");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _posthog_core__WEBPACK_IMPORTED_MODULE_7__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _posthog_core__WEBPACK_IMPORTED_MODULE_8__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
@@ -149,12 +176,12 @@ var __webpack_exports__ = {};
         "buildOtlpLogRecord",
         "toOtlpAnyValue"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _posthog_core__WEBPACK_IMPORTED_MODULE_7__[key];
+        return _posthog_core__WEBPACK_IMPORTED_MODULE_8__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__("./posthog-core-stateless");
+    var _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__("./posthog-core-stateless");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_8__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_9__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
@@ -173,12 +200,12 @@ var __webpack_exports__ = {};
         "buildOtlpLogRecord",
         "toOtlpAnyValue"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_8__[key];
+        return _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_9__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _tracing_headers__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__("./tracing-headers");
+    var _tracing_headers__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__("./tracing-headers");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _tracing_headers__WEBPACK_IMPORTED_MODULE_9__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _tracing_headers__WEBPACK_IMPORTED_MODULE_10__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
@@ -197,12 +224,12 @@ var __webpack_exports__ = {};
         "buildOtlpLogRecord",
         "toOtlpAnyValue"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _tracing_headers__WEBPACK_IMPORTED_MODULE_9__[key];
+        return _tracing_headers__WEBPACK_IMPORTED_MODULE_10__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _types__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__("./types");
+    var _types__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__("./types");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_10__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_11__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
@@ -221,10 +248,10 @@ var __webpack_exports__ = {};
         "buildOtlpLogRecord",
         "toOtlpAnyValue"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _types__WEBPACK_IMPORTED_MODULE_10__[key];
+        return _types__WEBPACK_IMPORTED_MODULE_11__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _surveys_validation__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__("./surveys/validation");
+    var _surveys_validation__WEBPACK_IMPORTED_MODULE_12__ = __webpack_require__("./surveys/validation");
 })();
 exports.ErrorTracking = __webpack_exports__.ErrorTracking;
 exports.PostHogLogs = __webpack_exports__.PostHogLogs;

package/dist/index.mjs

@@ -5,6 +5,7 @@ import { PostHogLogs } from "./logs/index.mjs";
 import { uuidv7 } from "./vendor/uuidv7.mjs";
 import { getLengthFromRules, getRequirementsHint, getValidationError } from "./surveys/validation.mjs";
 export * from "./utils/index.mjs";
+export * from "./cookie.mjs";
 export * from "./posthog-core.mjs";
 export * from "./posthog-core-stateless.mjs";
 export * from "./tracing-headers.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/core",
-  "version": "1.28.7",
+  "version": "1.29.0",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -67,7 +67,7 @@
     }
   },
   "dependencies": {
-    "@posthog/types": "1.373.2"
+    "@posthog/types": "1.373.3"
   },
   "devDependencies": {
     "@rslib/core": "0.10.6",

package/src/cookie.ts

@@ -0,0 +1,173 @@
+import { isArray, isNoLike } from './utils'
+import { uuidv7 } from './vendor/uuidv7'
+
+const COOKIE_PREFIX = 'ph_'
+const COOKIE_SUFFIX = '_posthog'
+
+/**
+ * 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 function cookieStoreFromHeader(cookieHeader: string): CookieStore {
+  const cookies: Record<string, string> = {}
+  if (cookieHeader) {
+    for (const pair of cookieHeader.split(';')) {
+      const [key, ...valueParts] = pair.trim().split('=')
+      if (key) {
+        const raw = valueParts.join('=').trim()
+        // `decodeURIComponent` throws `URIError` on malformed sequences (e.g. `%gg`).
+        // The Cookie header is externally controlled, so fall back to the raw value
+        // rather than crashing the request handler.
+        try {
+          cookies[key.trim()] = decodeURIComponent(raw)
+        } catch {
+          cookies[key.trim()] = raw
+        }
+      }
+    }
+  }
+  return { get: (name: string) => (name in cookies ? { value: cookies[name] } : undefined) }
+}
+
+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 function getPostHogCookieName(apiKey: string): string {
+  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: string): string {
+  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: CookieStore, apiKey: string): PostHogCookieState | null {
+  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: PostHogCookieState | null): Record<string, string> | undefined {
+  if (!state) {
+    return undefined
+  }
+  const props: Record<string, string> = {}
+  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: string): PostHogCookieState | null {
+  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
+  }
+}
+
+export interface ConsentCookieConfig {
+  consent_persistence_name?: string | null
+  opt_out_capturing_cookie_prefix?: string | null
+}
+
+const CONSENT_PREFIX = '__ph_opt_in_out_'
+
+export function getConsentCookieName(apiKey: string, config?: ConsentCookieConfig): string {
+  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 interface ConsentConfig extends ConsentCookieConfig {
+  opt_out_capturing_by_default?: boolean
+}
+
+export function isOptedOut(cookies: CookieStore, apiKey: string, config?: ConsentConfig): boolean {
+  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
+}

package/src/index.ts

@@ -24,6 +24,7 @@ export type {
 // packages to type their `captureLog` calls.
 export type { CaptureLogOptions, LogAttributeValue, LogAttributes, LogSeverityLevel } from './logs/types'
 export { uuidv7 } from './vendor/uuidv7'
+export * from './cookie'
 export * from './posthog-core'
 export * from './posthog-core-stateless'
 export * from './tracing-headers'