@posthog/core 1.28.7 → 1.29.1

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/gzip.d.ts

@@ -3,6 +3,8 @@
  * This API (as of 2025-05-07) is not available on React Native.
  */
 export declare function isGzipSupported(): boolean;
+export declare const isGzipData: (body: unknown) => boolean;
+export declare const isGzipRequest: (compression?: unknown, urlCompression?: unknown) => boolean;
 export declare const isNativeAsyncGzipReadError: (error: unknown) => boolean;
 export declare const isNativeAsyncGzipError: (error: unknown) => boolean;
 export type GzipCompressOptions = {

package/dist/gzip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gzip.d.ts","sourceRoot":"","sources":["../src/gzip.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAOzC;AAID,eAAO,MAAM,0BAA0B,GAAI,OAAO,OAAO,KAAG,OAQ3D,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,OAQvD,CAAA;AA0DD,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,UAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAgCrH"}
+{"version":3,"file":"gzip.d.ts","sourceRoot":"","sources":["../src/gzip.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAOzC;AAWD,eAAO,MAAM,UAAU,GAAI,MAAM,OAAO,KAAG,OAU1C,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,cAAc,OAAO,EAAE,iBAAiB,OAAO,KAAG,OAE/E,CAAA;AAED,eAAO,MAAM,0BAA0B,GAAI,OAAO,OAAO,KAAG,OAQ3D,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,OAQvD,CAAA;AA0DD,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,UAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAgCrH"}

package/dist/gzip.js

@@ -24,15 +24,28 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
-    gzipCompress: ()=>gzipCompress,
-    isGzipSupported: ()=>isGzipSupported,
     isNativeAsyncGzipError: ()=>isNativeAsyncGzipError,
-    isNativeAsyncGzipReadError: ()=>isNativeAsyncGzipReadError
+    isNativeAsyncGzipReadError: ()=>isNativeAsyncGzipReadError,
+    isGzipRequest: ()=>isGzipRequest,
+    isGzipSupported: ()=>isGzipSupported,
+    gzipCompress: ()=>gzipCompress,
+    isGzipData: ()=>isGzipData
 });
+const external_types_js_namespaceObject = require("./types.js");
 function isGzipSupported() {
     return 'CompressionStream' in globalThis && 'TextEncoder' in globalThis && 'Response' in globalThis && 'function' == typeof Response.prototype.blob;
 }
 const NATIVE_GZIP_VALIDATION_ERROR = 'NativeGzipValidationError';
+const GZIP_MAGIC_FIRST_BYTE = 0x1f;
+const GZIP_MAGIC_SECOND_BYTE = 0x8b;
+const GZIP_DEFLATE_METHOD = 0x08;
+const hasGzipMagic = (bytes)=>bytes.length >= 2 && bytes[0] === GZIP_MAGIC_FIRST_BYTE && bytes[1] === GZIP_MAGIC_SECOND_BYTE;
+const isGzipData = (body)=>{
+    if (body instanceof ArrayBuffer) return hasGzipMagic(new Uint8Array(body));
+    if (ArrayBuffer.isView(body)) return hasGzipMagic(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+    return false;
+};
+const isGzipRequest = (compression, urlCompression)=>compression === external_types_js_namespaceObject.Compression.GZipJS || urlCompression === external_types_js_namespaceObject.Compression.GZipJS || 'gzip' === urlCompression;
 const isNativeAsyncGzipReadError = (error)=>{
     if (!error || 'object' != typeof error) return false;
     const name = 'name' in error ? String(error.name) : '';
@@ -68,7 +81,7 @@ const throwNativeGzipValidationError = (reason)=>{
 const validateNativeGzip = async (compressed, inputBytes)=>{
     if (compressed.size < 18) throwNativeGzipValidationError('too-short');
     const header = new Uint8Array(await compressed.slice(0, 10).arrayBuffer());
-    if (0x1f !== header[0] || 0x8b !== header[1] || 0x08 !== header[2]) throwNativeGzipValidationError('invalid-header');
+    if (!hasGzipMagic(header) || header[2] !== GZIP_DEFLATE_METHOD) throwNativeGzipValidationError('invalid-header');
     const trailer = new DataView(await compressed.slice(compressed.size - 8).arrayBuffer());
     if (trailer.getUint32(0, true) !== crc32(inputBytes)) throwNativeGzipValidationError('invalid-crc');
     const inputSize = inputBytes.length >>> 0;
@@ -99,11 +112,15 @@ async function gzipCompress(input, isDebug = true, options) {
     }
 }
 exports.gzipCompress = __webpack_exports__.gzipCompress;
+exports.isGzipData = __webpack_exports__.isGzipData;
+exports.isGzipRequest = __webpack_exports__.isGzipRequest;
 exports.isGzipSupported = __webpack_exports__.isGzipSupported;
 exports.isNativeAsyncGzipError = __webpack_exports__.isNativeAsyncGzipError;
 exports.isNativeAsyncGzipReadError = __webpack_exports__.isNativeAsyncGzipReadError;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "gzipCompress",
+    "isGzipData",
+    "isGzipRequest",
     "isGzipSupported",
     "isNativeAsyncGzipError",
     "isNativeAsyncGzipReadError"

package/dist/gzip.mjs

@@ -1,7 +1,18 @@
+import { Compression } from "./types.mjs";
 function isGzipSupported() {
     return 'CompressionStream' in globalThis && 'TextEncoder' in globalThis && 'Response' in globalThis && 'function' == typeof Response.prototype.blob;
 }
 const NATIVE_GZIP_VALIDATION_ERROR = 'NativeGzipValidationError';
+const GZIP_MAGIC_FIRST_BYTE = 0x1f;
+const GZIP_MAGIC_SECOND_BYTE = 0x8b;
+const GZIP_DEFLATE_METHOD = 0x08;
+const hasGzipMagic = (bytes)=>bytes.length >= 2 && bytes[0] === GZIP_MAGIC_FIRST_BYTE && bytes[1] === GZIP_MAGIC_SECOND_BYTE;
+const isGzipData = (body)=>{
+    if (body instanceof ArrayBuffer) return hasGzipMagic(new Uint8Array(body));
+    if (ArrayBuffer.isView(body)) return hasGzipMagic(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
+    return false;
+};
+const isGzipRequest = (compression, urlCompression)=>compression === Compression.GZipJS || urlCompression === Compression.GZipJS || 'gzip' === urlCompression;
 const isNativeAsyncGzipReadError = (error)=>{
     if (!error || 'object' != typeof error) return false;
     const name = 'name' in error ? String(error.name) : '';
@@ -37,7 +48,7 @@ const throwNativeGzipValidationError = (reason)=>{
 const validateNativeGzip = async (compressed, inputBytes)=>{
     if (compressed.size < 18) throwNativeGzipValidationError('too-short');
     const header = new Uint8Array(await compressed.slice(0, 10).arrayBuffer());
-    if (0x1f !== header[0] || 0x8b !== header[1] || 0x08 !== header[2]) throwNativeGzipValidationError('invalid-header');
+    if (!hasGzipMagic(header) || header[2] !== GZIP_DEFLATE_METHOD) throwNativeGzipValidationError('invalid-header');
     const trailer = new DataView(await compressed.slice(compressed.size - 8).arrayBuffer());
     if (trailer.getUint32(0, true) !== crc32(inputBytes)) throwNativeGzipValidationError('invalid-crc');
     const inputSize = inputBytes.length >>> 0;
@@ -67,4 +78,4 @@ async function gzipCompress(input, isDebug = true, options) {
         return null;
     }
 }
-export { gzipCompress, isGzipSupported, isNativeAsyncGzipError, isNativeAsyncGzipReadError };
+export { gzipCompress, isGzipData, isGzipRequest, isGzipSupported, isNativeAsyncGzipError, isNativeAsyncGzipReadError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { getFeatureFlagValue } from './featureFlagUtils';
-export { gzipCompress, isNativeAsyncGzipError, isNativeAsyncGzipReadError } from './gzip';
+export { gzipCompress, isGzipData, isGzipRequest, isNativeAsyncGzipError, isNativeAsyncGzipReadError } from './gzip';
 export * from './utils';
 export * as ErrorTracking from './error-tracking';
 export { buildOtlpLogRecord, buildOtlpLogsPayload, getOtlpSeverityNumber, getOtlpSeverityText, toOtlpAnyValue, toOtlpKeyValueList, } from './logs/logs-utils';
@@ -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,UAAU,EAAE,aAAa,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,QAAQ,CAAA;AACpH,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,12 +89,14 @@ 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,
+        isGzipData: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.isGzipData,
+        isGzipRequest: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.isGzipRequest,
         isNativeAsyncGzipError: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.isNativeAsyncGzipError,
         isNativeAsyncGzipReadError: ()=>_gzip__WEBPACK_IMPORTED_MODULE_1__.isNativeAsyncGzipReadError,
         toOtlpAnyValue: ()=>_logs_logs_utils__WEBPACK_IMPORTED_MODULE_4__.toOtlpAnyValue,
@@ -109,12 +114,14 @@ var __webpack_exports__ = {};
         "getOtlpSeverityText",
         "isNativeAsyncGzipReadError",
         "getFeatureFlagValue",
+        "isGzipRequest",
+        "gzipCompress",
         "uuidv7",
-        "getValidationError",
         "ErrorTracking",
-        "gzipCompress",
+        "getValidationError",
         "default",
         "getRequirementsHint",
+        "isGzipData",
         "getOtlpSeverityNumber",
         "getLengthFromRules",
         "buildOtlpLogsPayload",
@@ -128,103 +135,137 @@ 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 _posthog_core__WEBPACK_IMPORTED_MODULE_7__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _cookie__WEBPACK_IMPORTED_MODULE_7__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
         "getOtlpSeverityText",
         "isNativeAsyncGzipReadError",
         "getFeatureFlagValue",
+        "isGzipRequest",
+        "gzipCompress",
         "uuidv7",
-        "getValidationError",
         "ErrorTracking",
-        "gzipCompress",
+        "getValidationError",
         "default",
         "getRequirementsHint",
+        "isGzipData",
         "getOtlpSeverityNumber",
         "getLengthFromRules",
         "buildOtlpLogsPayload",
         "buildOtlpLogRecord",
         "toOtlpAnyValue"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _posthog_core__WEBPACK_IMPORTED_MODULE_7__[key];
+        return _cookie__WEBPACK_IMPORTED_MODULE_7__[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__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__("./posthog-core");
     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__WEBPACK_IMPORTED_MODULE_8__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
         "getOtlpSeverityText",
         "isNativeAsyncGzipReadError",
         "getFeatureFlagValue",
+        "isGzipRequest",
+        "gzipCompress",
         "uuidv7",
-        "getValidationError",
         "ErrorTracking",
-        "gzipCompress",
+        "getValidationError",
         "default",
         "getRequirementsHint",
+        "isGzipData",
         "getOtlpSeverityNumber",
         "getLengthFromRules",
         "buildOtlpLogsPayload",
         "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__WEBPACK_IMPORTED_MODULE_8__[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 _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__("./posthog-core-stateless");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _tracing_headers__WEBPACK_IMPORTED_MODULE_9__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_9__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
         "getOtlpSeverityText",
         "isNativeAsyncGzipReadError",
         "getFeatureFlagValue",
+        "isGzipRequest",
+        "gzipCompress",
         "uuidv7",
-        "getValidationError",
         "ErrorTracking",
-        "gzipCompress",
+        "getValidationError",
         "default",
         "getRequirementsHint",
+        "isGzipData",
         "getOtlpSeverityNumber",
         "getLengthFromRules",
         "buildOtlpLogsPayload",
         "buildOtlpLogRecord",
         "toOtlpAnyValue"
     ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(key) {
-        return _tracing_headers__WEBPACK_IMPORTED_MODULE_9__[key];
+        return _posthog_core_stateless__WEBPACK_IMPORTED_MODULE_9__[key];
     }).bind(0, __WEBPACK_IMPORT_KEY__);
     __webpack_require__.d(__webpack_exports__, __WEBPACK_REEXPORT_OBJECT__);
-    var _types__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__("./types");
+    var _tracing_headers__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__("./tracing-headers");
     var __WEBPACK_REEXPORT_OBJECT__ = {};
-    for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_10__)if ([
+    for(var __WEBPACK_IMPORT_KEY__ in _tracing_headers__WEBPACK_IMPORTED_MODULE_10__)if ([
         "toOtlpKeyValueList",
         "PostHogLogs",
         "isNativeAsyncGzipError",
         "getOtlpSeverityText",
         "isNativeAsyncGzipReadError",
         "getFeatureFlagValue",
+        "isGzipRequest",
+        "gzipCompress",
         "uuidv7",
-        "getValidationError",
         "ErrorTracking",
+        "getValidationError",
+        "default",
+        "getRequirementsHint",
+        "isGzipData",
+        "getOtlpSeverityNumber",
+        "getLengthFromRules",
+        "buildOtlpLogsPayload",
+        "buildOtlpLogRecord",
+        "toOtlpAnyValue"
+    ].indexOf(__WEBPACK_IMPORT_KEY__) < 0) __WEBPACK_REEXPORT_OBJECT__[__WEBPACK_IMPORT_KEY__] = (function(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_11__ = __webpack_require__("./types");
+    var __WEBPACK_REEXPORT_OBJECT__ = {};
+    for(var __WEBPACK_IMPORT_KEY__ in _types__WEBPACK_IMPORTED_MODULE_11__)if ([
+        "toOtlpKeyValueList",
+        "PostHogLogs",
+        "isNativeAsyncGzipError",
+        "getOtlpSeverityText",
+        "isNativeAsyncGzipReadError",
+        "getFeatureFlagValue",
+        "isGzipRequest",
         "gzipCompress",
+        "uuidv7",
+        "ErrorTracking",
+        "getValidationError",
         "default",
         "getRequirementsHint",
+        "isGzipData",
         "getOtlpSeverityNumber",
         "getLengthFromRules",
         "buildOtlpLogsPayload",
         "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;
@@ -237,6 +278,8 @@ exports.getOtlpSeverityText = __webpack_exports__.getOtlpSeverityText;
 exports.getRequirementsHint = __webpack_exports__.getRequirementsHint;
 exports.getValidationError = __webpack_exports__.getValidationError;
 exports.gzipCompress = __webpack_exports__.gzipCompress;
+exports.isGzipData = __webpack_exports__.isGzipData;
+exports.isGzipRequest = __webpack_exports__.isGzipRequest;
 exports.isNativeAsyncGzipError = __webpack_exports__.isNativeAsyncGzipError;
 exports.isNativeAsyncGzipReadError = __webpack_exports__.isNativeAsyncGzipReadError;
 exports.toOtlpAnyValue = __webpack_exports__.toOtlpAnyValue;
@@ -254,6 +297,8 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "getRequirementsHint",
     "getValidationError",
     "gzipCompress",
+    "isGzipData",
+    "isGzipRequest",
     "isNativeAsyncGzipError",
     "isNativeAsyncGzipReadError",
     "toOtlpAnyValue",

package/dist/index.mjs

@@ -1,13 +1,14 @@
 import { getFeatureFlagValue } from "./featureFlagUtils.mjs";
-import { gzipCompress, isNativeAsyncGzipError, isNativeAsyncGzipReadError } from "./gzip.mjs";
+import { gzipCompress, isGzipData, isGzipRequest, isNativeAsyncGzipError, isNativeAsyncGzipReadError } from "./gzip.mjs";
 import { buildOtlpLogRecord, buildOtlpLogsPayload, getOtlpSeverityNumber, getOtlpSeverityText, toOtlpAnyValue, toOtlpKeyValueList } from "./logs/logs-utils.mjs";
 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";
 export * from "./types.mjs";
 import * as __WEBPACK_EXTERNAL_MODULE__error_tracking_index_mjs_b3406d6f__ from "./error-tracking/index.mjs";
-export { __WEBPACK_EXTERNAL_MODULE__error_tracking_index_mjs_b3406d6f__ as ErrorTracking, PostHogLogs, buildOtlpLogRecord, buildOtlpLogsPayload, getFeatureFlagValue, getLengthFromRules, getOtlpSeverityNumber, getOtlpSeverityText, getRequirementsHint, getValidationError, gzipCompress, isNativeAsyncGzipError, isNativeAsyncGzipReadError, toOtlpAnyValue, toOtlpKeyValueList, uuidv7 };
+export { __WEBPACK_EXTERNAL_MODULE__error_tracking_index_mjs_b3406d6f__ as ErrorTracking, PostHogLogs, buildOtlpLogRecord, buildOtlpLogsPayload, getFeatureFlagValue, getLengthFromRules, getOtlpSeverityNumber, getOtlpSeverityText, getRequirementsHint, getValidationError, gzipCompress, isGzipData, isGzipRequest, isNativeAsyncGzipError, isNativeAsyncGzipReadError, toOtlpAnyValue, toOtlpKeyValueList, uuidv7 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/core",
-  "version": "1.28.7",
+  "version": "1.29.1",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -67,7 +67,7 @@
     }
   },
   "dependencies": {
-    "@posthog/types": "1.373.2"
+    "@posthog/types": "1.373.4"
   },
   "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/gzip.ts

@@ -1,3 +1,5 @@
+import { Compression } from './types'
+
 /**
  * Older browsers and some runtimes don't support this yet
  * This API (as of 2025-05-07) is not available on React Native.
@@ -12,6 +14,29 @@ export function isGzipSupported(): boolean {
 }
 
 const NATIVE_GZIP_VALIDATION_ERROR = 'NativeGzipValidationError'
+const GZIP_MAGIC_FIRST_BYTE = 0x1f
+const GZIP_MAGIC_SECOND_BYTE = 0x8b
+const GZIP_DEFLATE_METHOD = 0x08
+
+const hasGzipMagic = (bytes: Uint8Array): boolean => {
+  return bytes.length >= 2 && bytes[0] === GZIP_MAGIC_FIRST_BYTE && bytes[1] === GZIP_MAGIC_SECOND_BYTE
+}
+
+export const isGzipData = (body: unknown): boolean => {
+  if (body instanceof ArrayBuffer) {
+    return hasGzipMagic(new Uint8Array(body))
+  }
+
+  if (ArrayBuffer.isView(body)) {
+    return hasGzipMagic(new Uint8Array(body.buffer, body.byteOffset, body.byteLength))
+  }
+
+  return false
+}
+
+export const isGzipRequest = (compression?: unknown, urlCompression?: unknown): boolean => {
+  return compression === Compression.GZipJS || urlCompression === Compression.GZipJS || urlCompression === 'gzip'
+}
 
 export const isNativeAsyncGzipReadError = (error: unknown): boolean => {
   if (!error || typeof error !== 'object') {
@@ -74,7 +99,7 @@ const validateNativeGzip = async (compressed: Blob, inputBytes: Uint8Array): Pro
   }
 
   const header = new Uint8Array(await compressed.slice(0, 10).arrayBuffer())
-  if (header[0] !== 0x1f || header[1] !== 0x8b || header[2] !== 0x08) {
+  if (!hasGzipMagic(header) || header[2] !== GZIP_DEFLATE_METHOD) {
     throwNativeGzipValidationError('invalid-header')
   }
 

package/src/index.ts

@@ -1,5 +1,5 @@
 export { getFeatureFlagValue } from './featureFlagUtils'
-export { gzipCompress, isNativeAsyncGzipError, isNativeAsyncGzipReadError } from './gzip'
+export { gzipCompress, isGzipData, isGzipRequest, isNativeAsyncGzipError, isNativeAsyncGzipReadError } from './gzip'
 export * from './utils'
 export * as ErrorTracking from './error-tracking'
 export {
@@ -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'