@easy-cookie/posthog 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 easy-cookie contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @easy-cookie/posthog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keeps [PostHog](https://posthog.com) in sync with easy-cookie consent, with no page reload. It follows the pattern MythicVoices uses in production:
+
+- **Before a choice:** PostHog captures nothing.
+- **After a rejection:** cookieless mode only. PostHog sets no cookies and no storage, and creates no person profiles. Autocapture, exceptions, web vitals and heatmaps are dropped.
+- **After an acceptance:** normal capture with cookies, then `identify()` for logged-in users.
+
+`posthog-js` is an optional peer dependency. The adapter types PostHog loosely, so any compatible client works.
+
+## Requirements
+
+- **posthog-js** with `cookieless_mode` support (≥ 1.200).
+- **Cookieless server hash mode** enabled in the PostHog project settings. Without it, cookieless events are discarded.
+- PostHog **must be initialised with `cookieless_mode: 'on_reject'`**. `posthogInitOptions()` does this for you.
+
+## Install
+
+```sh
+pnpm add @easy-cookie/posthog posthog-js
+```
+
+## Usage
+
+```ts
+import posthog from 'posthog-js';
+import easyCookie from '@easy-cookie/core';
+import { connectPostHog, posthogInitOptions } from '@easy-cookie/posthog';
+
+posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
+  ...posthogInitOptions({ api: easyCookie }), // cookieless_mode: 'on_reject', persistence, person_profiles, before_send
+  api_host: 'https://eu.i.posthog.com',
+});
+
+const disconnect = connectPostHog(posthog, easyCookie, {
+  category: 'measurement',                     // default
+  identify: () => session?.user?.id,           // optional, called after opt-in only
+});
+```
+
+With React, connect it in an effect inside the provider:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import posthog from 'posthog-js';
+import { useEasyCookie } from '@easy-cookie/react';
+import { connectPostHog } from '@easy-cookie/posthog';
+
+export function PostHogConsent({ userId }: { userId?: string }) {
+  const { api } = useEasyCookie();
+  useEffect(() => (api ? connectPostHog(posthog, api, { identify: () => userId }) : undefined), [api, userId]);
+  return null;
+}
+```
+
+## API
+
+### `connectPostHog(posthog, api, { category?, service?, identify? })`
+
+The adapter listens to `replay`, `consent` and `change`, and applies the current state immediately, in case the stored choice was replayed before you connected.
+
+- **Granted:** it calls `posthog.opt_in_capturing()`, skipped when already opted in. It then calls `posthog.identify(id)` when `identify()` returns an id that differs from the current one.
+- **Not granted (a choice exists):** it calls `posthog.opt_out_capturing()`. With `on_reject`, PostHog keeps counting anonymously without cookies.
+- **No choice yet:** it does nothing.
+
+It returns an unsubscribe function. Use `service: 'posthog'` to follow the service toggle instead of the category.
+
+### `posthogInitOptions(opts?)`
+
+Returns the recommended init options:
+
+```ts
+{
+  cookieless_mode: 'on_reject',
+  persistence: 'localStorage+cookie',   // used only after opt-in
+  person_profiles: 'identified_only',
+  before_send: consentBeforeSend(opts),
+}
+```
+
+### `consentBeforeSend({ category?, api?, isGranted?, drop? })`
+
+A `before_send` filter. Without consent it drops `$autocapture`, `$rageclick`, `$dead_click`, `$exception`, `$web_vitals` and `$$heatmap` (the list is `NON_ESSENTIAL_EVENTS`, and you can override it with `drop`). Pageviews and your own events are kept.
+
+The consent check works like this:
+
+1. `isGranted`, when you pass it.
+2. Otherwise the runtime, when you pass `api`.
+3. Otherwise the state published by the head snippet (`window.__easyCookieHead`). That state is available before the runtime loads.
+
+## License
+
+MIT
+
+## Options
+
+`connectPostHog(posthog, api, options)`:
+
+| Option | Default | Effect |
+|---|---|---|
+| `category` | `measurement` | Category that allows PostHog cookies and profiles |
+| `service` | — | Decide on this service's consent instead of the category |
+| `identify` | — | Returns the logged-in user id; called after opt-in |
+| `beforeChoice` | `'pending'` | `'pending'`: capture nothing until the visitor chooses (a stale stored opt-in is cleared). `'cookieless'`: count visits without cookies before the choice, as after a rejection. Use it only when your privacy policy covers cookieless measurement without consent. |
+| `sessionReplay` | `false` | Start session recording on opt-in and stop it on opt-out |
+
+Opt-in does not send a `$opt_in` event: easy-cookie already records the consent.

package/dist/index.cjs

@@ -0,0 +1,102 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  NON_ESSENTIAL_EVENTS: () => NON_ESSENTIAL_EVENTS,
+  connectPostHog: () => connectPostHog,
+  consentBeforeSend: () => consentBeforeSend,
+  posthogInitOptions: () => posthogInitOptions
+});
+module.exports = __toCommonJS(src_exports);
+function connectPostHog(posthog, api, options = {}) {
+  const category = options.category ?? "measurement";
+  const granted = () => options.service ? api.isServiceGranted(options.service) : api.isGranted(category);
+  let last = null;
+  const apply = () => {
+    if (!api.get()) {
+      if (options.beforeChoice === "cookieless") {
+        if (last !== "out") {
+          if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
+          last = "out";
+        }
+      } else if (posthog.has_opted_in_capturing?.()) {
+        posthog.clear_opt_in_out_capturing?.();
+      }
+      return;
+    }
+    if (granted()) {
+      if (last !== "in") {
+        if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing({ captureEventName: false });
+        if (options.sessionReplay) posthog.startSessionRecording?.();
+        last = "in";
+      }
+      const id = options.identify?.();
+      if (id && posthog.identify && posthog.get_distinct_id?.() !== id) posthog.identify(id);
+    } else if (last !== "out") {
+      if (options.sessionReplay) posthog.stopSessionRecording?.();
+      if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
+      last = "out";
+    }
+  };
+  const events = ["replay", "consent", "change"];
+  const unsubs = events.map((ev) => api.on(ev, apply));
+  apply();
+  return () => unsubs.forEach((u) => u());
+}
+var NON_ESSENTIAL_EVENTS = [
+  "$autocapture",
+  "$rageclick",
+  "$dead_click",
+  "$exception",
+  "$web_vitals",
+  "$$heatmap",
+  "$heatmap"
+];
+function headGranted(category) {
+  const head = globalThis.__easyCookieHead;
+  return !!head?.valid && !!head.granted?.includes(category);
+}
+function consentBeforeSend(options = {}) {
+  const category = options.category ?? "measurement";
+  const drop = new Set(options.drop ?? NON_ESSENTIAL_EVENTS);
+  const isGranted = options.isGranted ?? (() => options.api ? options.api.isGranted(category) : headGranted(category));
+  return (event) => {
+    if (!event) return event;
+    if (drop.has(event.event) && !isGranted()) return null;
+    return event;
+  };
+}
+function posthogInitOptions(options = {}) {
+  return {
+    cookieless_mode: "on_reject",
+    persistence: "localStorage+cookie",
+    person_profiles: "identified_only",
+    before_send: consentBeforeSend(options)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NON_ESSENTIAL_EVENTS,
+  connectPostHog,
+  consentBeforeSend,
+  posthogInitOptions
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { EasyCookieApi, EasyCookieEvent } from '@easy-cookie/core/shared';\n\n/**\n * The few posthog-js methods the adapter uses. Typed loosely on purpose, so\n * `posthog-js` stays an optional peer dependency and any compatible client works.\n */\nexport interface PostHogLike {\n  opt_in_capturing(options?: { captureEventName?: string | null | false; [key: string]: unknown }): void;\n  opt_out_capturing(): void;\n  has_opted_in_capturing?(): boolean;\n  has_opted_out_capturing?(): boolean;\n  clear_opt_in_out_capturing?(): void;\n  startSessionRecording?(...args: unknown[]): void;\n  stopSessionRecording?(): void;\n  identify?(distinctId?: string, ...rest: unknown[]): void;\n  get_distinct_id?(): string;\n}\n\n/** Minimal shape of a PostHog event passed to `before_send`. */\nexport interface PostHogEventLike {\n  event: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches posthog-js `Properties`\n  properties?: Record<string, any>;\n}\n\nexport interface ConnectPostHogOptions {\n  /** Category that allows PostHog cookies/profiles. Default `measurement`. */\n  category?: string;\n  /** Service id: when set, the service's own consent decides instead of the category. */\n  service?: string;\n  /**\n   * Return the logged-in user id (or undefined). Called after opt-in, so the\n   * identified person profile is created only with consent.\n   */\n  identify?: () => string | undefined | null;\n  /**\n   * Before the visitor's first choice:\n   * - `'pending'` (default): capture nothing. A stale opt-in left in storage by an\n   *   earlier setup is cleared, so nothing is captured with cookies.\n   * - `'cookieless'`: count visits without cookies (same as after a rejection).\n   *   Only if your privacy policy covers cookieless measurement without consent.\n   */\n  beforeChoice?: 'pending' | 'cookieless';\n  /** Start session recording on opt-in and stop it on opt-out. Default false. */\n  sessionReplay?: boolean;\n}\n\n/**\n * Keep PostHog's capture state in sync with the visitor's consent, without reloads.\n *\n * PostHog must be initialised by the host with `cookieless_mode: 'on_reject'`\n * (see {@link posthogInitOptions}): before a choice it captures nothing, after a\n * rejection it keeps counting anonymously with no cookies or storage, and after\n * an acceptance it switches to normal cookie-based capture.\n *\n * On `replay`, `consent` and `change` the adapter calls `opt_in_capturing()` or\n * `opt_out_capturing()`. Returns an unsubscribe function.\n */\nexport function connectPostHog(posthog: PostHogLike, api: EasyCookieApi, options: ConnectPostHogOptions = {}): () => void {\n  const category = options.category ?? 'measurement';\n  const granted = () => (options.service ? api.isServiceGranted(options.service) : api.isGranted(category));\n  let last: 'in' | 'out' | null = null;\n\n  const apply = () => {\n    if (!api.get()) {\n      if (options.beforeChoice === 'cookieless') {\n        if (last !== 'out') {\n          if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();\n          last = 'out';\n        }\n      } else if (posthog.has_opted_in_capturing?.()) {\n        // Pending: an opt-in stored by a previous banner must not keep capturing.\n        posthog.clear_opt_in_out_capturing?.();\n      }\n      return;\n    }\n    if (granted()) {\n      if (last !== 'in') {\n        // No `$opt_in` event: the consent itself is recorded by easy-cookie.\n        if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing({ captureEventName: false });\n        if (options.sessionReplay) posthog.startSessionRecording?.();\n        last = 'in';\n      }\n      const id = options.identify?.();\n      if (id && posthog.identify && posthog.get_distinct_id?.() !== id) posthog.identify(id);\n    } else if (last !== 'out') {\n      if (options.sessionReplay) posthog.stopSessionRecording?.();\n      if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();\n      last = 'out';\n    }\n  };\n\n  const events: EasyCookieEvent[] = ['replay', 'consent', 'change'];\n  const unsubs = events.map((ev) => api.on(ev, apply));\n  // The stored choice may have been replayed before we subscribed.\n  apply();\n  return () => unsubs.forEach((u) => u());\n}\n\n/** Events dropped by {@link consentBeforeSend} while consent is missing. */\nexport const NON_ESSENTIAL_EVENTS: readonly string[] = [\n  '$autocapture',\n  '$rageclick',\n  '$dead_click',\n  '$exception',\n  '$web_vitals',\n  '$$heatmap',\n  '$heatmap',\n];\n\nexport interface ConsentBeforeSendOptions {\n  /** Category checked by the default `isGranted`. Default `measurement`. */\n  category?: string;\n  /**\n   * Consent check. Defaults to the runtime when `api` is given, otherwise to the\n   * state published by the head script (`window.__easyCookieHead.granted`).\n   */\n  isGranted?: () => boolean;\n  api?: Pick<EasyCookieApi, 'isGranted'> | null;\n  /** Event names to drop without consent. Default {@link NON_ESSENTIAL_EVENTS}. */\n  drop?: readonly string[];\n}\n\nfunction headGranted(category: string): boolean {\n  const head = (globalThis as { __easyCookieHead?: { granted?: string[]; valid?: boolean } }).__easyCookieHead;\n  return !!head?.valid && !!head.granted?.includes(category);\n}\n\n/**\n * `before_send` filter: without consent, drop autocapture, exceptions, web vitals\n * and heatmap events, so cookieless mode only sends the essentials (pageviews,\n * explicit captures). Pass it as `before_send` or use {@link posthogInitOptions}.\n */\nexport function consentBeforeSend(options: ConsentBeforeSendOptions = {}) {\n  const category = options.category ?? 'measurement';\n  const drop = new Set(options.drop ?? NON_ESSENTIAL_EVENTS);\n  const isGranted =\n    options.isGranted ?? (() => (options.api ? options.api.isGranted(category) : headGranted(category)));\n  return <T extends PostHogEventLike | null>(event: T): T | null => {\n    if (!event) return event;\n    if (drop.has(event.event) && !isGranted()) return null;\n    return event;\n  };\n}\n\nexport interface PostHogInitOptions {\n  cookieless_mode: 'on_reject';\n  persistence: 'localStorage+cookie';\n  person_profiles: 'identified_only';\n  before_send: ReturnType<typeof consentBeforeSend>;\n  [key: string]: unknown;\n}\n\n/**\n * Recommended `posthog.init()` options for easy-cookie:\n * - `cookieless_mode: 'on_reject'` (requires \"Cookieless server hash mode\" enabled\n *   in the PostHog project settings);\n * - `persistence: 'localStorage+cookie'` (only used after opt-in);\n * - `person_profiles: 'identified_only'`;\n * - a consent-aware `before_send` filter.\n *\n * Spread your own options after it: `posthog.init(key, { ...posthogInitOptions(), api_host })`.\n */\nexport function posthogInitOptions(options: ConsentBeforeSendOptions = {}): PostHogInitOptions {\n  return {\n    cookieless_mode: 'on_reject',\n    persistence: 'localStorage+cookie',\n    person_profiles: 'identified_only',\n    before_send: consentBeforeSend(options),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA0DO,SAAS,eAAe,SAAsB,KAAoB,UAAiC,CAAC,GAAe;AACxH,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,UAAU,MAAO,QAAQ,UAAU,IAAI,iBAAiB,QAAQ,OAAO,IAAI,IAAI,UAAU,QAAQ;AACvG,MAAI,OAA4B;AAEhC,QAAM,QAAQ,MAAM;AAClB,QAAI,CAAC,IAAI,IAAI,GAAG;AACd,UAAI,QAAQ,iBAAiB,cAAc;AACzC,YAAI,SAAS,OAAO;AAClB,cAAI,CAAC,QAAQ,0BAA0B,EAAG,SAAQ,kBAAkB;AACpE,iBAAO;AAAA,QACT;AAAA,MACF,WAAW,QAAQ,yBAAyB,GAAG;AAE7C,gBAAQ,6BAA6B;AAAA,MACvC;AACA;AAAA,IACF;AACA,QAAI,QAAQ,GAAG;AACb,UAAI,SAAS,MAAM;AAEjB,YAAI,CAAC,QAAQ,yBAAyB,EAAG,SAAQ,iBAAiB,EAAE,kBAAkB,MAAM,CAAC;AAC7F,YAAI,QAAQ,cAAe,SAAQ,wBAAwB;AAC3D,eAAO;AAAA,MACT;AACA,YAAM,KAAK,QAAQ,WAAW;AAC9B,UAAI,MAAM,QAAQ,YAAY,QAAQ,kBAAkB,MAAM,GAAI,SAAQ,SAAS,EAAE;AAAA,IACvF,WAAW,SAAS,OAAO;AACzB,UAAI,QAAQ,cAAe,SAAQ,uBAAuB;AAC1D,UAAI,CAAC,QAAQ,0BAA0B,EAAG,SAAQ,kBAAkB;AACpE,aAAO;AAAA,IACT;AAAA,EACF;AAEA,QAAM,SAA4B,CAAC,UAAU,WAAW,QAAQ;AAChE,QAAM,SAAS,OAAO,IAAI,CAAC,OAAO,IAAI,GAAG,IAAI,KAAK,CAAC;AAEnD,QAAM;AACN,SAAO,MAAM,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AACxC;AAGO,IAAM,uBAA0C;AAAA,EACrD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAeA,SAAS,YAAY,UAA2B;AAC9C,QAAM,OAAQ,WAA8E;AAC5F,SAAO,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC,KAAK,SAAS,SAAS,QAAQ;AAC3D;AAOO,SAAS,kBAAkB,UAAoC,CAAC,GAAG;AACxE,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,OAAO,IAAI,IAAI,QAAQ,QAAQ,oBAAoB;AACzD,QAAM,YACJ,QAAQ,cAAc,MAAO,QAAQ,MAAM,QAAQ,IAAI,UAAU,QAAQ,IAAI,YAAY,QAAQ;AACnG,SAAO,CAAoC,UAAuB;AAChE,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,KAAK,IAAI,MAAM,KAAK,KAAK,CAAC,UAAU,EAAG,QAAO;AAClD,WAAO;AAAA,EACT;AACF;AAoBO,SAAS,mBAAmB,UAAoC,CAAC,GAAuB;AAC7F,SAAO;AAAA,IACL,iBAAiB;AAAA,IACjB,aAAa;AAAA,IACb,iBAAiB;AAAA,IACjB,aAAa,kBAAkB,OAAO;AAAA,EACxC;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,98 @@
+import { EasyCookieApi } from '@easy-cookie/core/shared';
+
+/**
+ * The few posthog-js methods the adapter uses. Typed loosely on purpose, so
+ * `posthog-js` stays an optional peer dependency and any compatible client works.
+ */
+interface PostHogLike {
+    opt_in_capturing(options?: {
+        captureEventName?: string | null | false;
+        [key: string]: unknown;
+    }): void;
+    opt_out_capturing(): void;
+    has_opted_in_capturing?(): boolean;
+    has_opted_out_capturing?(): boolean;
+    clear_opt_in_out_capturing?(): void;
+    startSessionRecording?(...args: unknown[]): void;
+    stopSessionRecording?(): void;
+    identify?(distinctId?: string, ...rest: unknown[]): void;
+    get_distinct_id?(): string;
+}
+/** Minimal shape of a PostHog event passed to `before_send`. */
+interface PostHogEventLike {
+    event: string;
+    properties?: Record<string, any>;
+}
+interface ConnectPostHogOptions {
+    /** Category that allows PostHog cookies/profiles. Default `measurement`. */
+    category?: string;
+    /** Service id: when set, the service's own consent decides instead of the category. */
+    service?: string;
+    /**
+     * Return the logged-in user id (or undefined). Called after opt-in, so the
+     * identified person profile is created only with consent.
+     */
+    identify?: () => string | undefined | null;
+    /**
+     * Before the visitor's first choice:
+     * - `'pending'` (default): capture nothing. A stale opt-in left in storage by an
+     *   earlier setup is cleared, so nothing is captured with cookies.
+     * - `'cookieless'`: count visits without cookies (same as after a rejection).
+     *   Only if your privacy policy covers cookieless measurement without consent.
+     */
+    beforeChoice?: 'pending' | 'cookieless';
+    /** Start session recording on opt-in and stop it on opt-out. Default false. */
+    sessionReplay?: boolean;
+}
+/**
+ * Keep PostHog's capture state in sync with the visitor's consent, without reloads.
+ *
+ * PostHog must be initialised by the host with `cookieless_mode: 'on_reject'`
+ * (see {@link posthogInitOptions}): before a choice it captures nothing, after a
+ * rejection it keeps counting anonymously with no cookies or storage, and after
+ * an acceptance it switches to normal cookie-based capture.
+ *
+ * On `replay`, `consent` and `change` the adapter calls `opt_in_capturing()` or
+ * `opt_out_capturing()`. Returns an unsubscribe function.
+ */
+declare function connectPostHog(posthog: PostHogLike, api: EasyCookieApi, options?: ConnectPostHogOptions): () => void;
+/** Events dropped by {@link consentBeforeSend} while consent is missing. */
+declare const NON_ESSENTIAL_EVENTS: readonly string[];
+interface ConsentBeforeSendOptions {
+    /** Category checked by the default `isGranted`. Default `measurement`. */
+    category?: string;
+    /**
+     * Consent check. Defaults to the runtime when `api` is given, otherwise to the
+     * state published by the head script (`window.__easyCookieHead.granted`).
+     */
+    isGranted?: () => boolean;
+    api?: Pick<EasyCookieApi, 'isGranted'> | null;
+    /** Event names to drop without consent. Default {@link NON_ESSENTIAL_EVENTS}. */
+    drop?: readonly string[];
+}
+/**
+ * `before_send` filter: without consent, drop autocapture, exceptions, web vitals
+ * and heatmap events, so cookieless mode only sends the essentials (pageviews,
+ * explicit captures). Pass it as `before_send` or use {@link posthogInitOptions}.
+ */
+declare function consentBeforeSend(options?: ConsentBeforeSendOptions): <T extends PostHogEventLike | null>(event: T) => T | null;
+interface PostHogInitOptions {
+    cookieless_mode: 'on_reject';
+    persistence: 'localStorage+cookie';
+    person_profiles: 'identified_only';
+    before_send: ReturnType<typeof consentBeforeSend>;
+    [key: string]: unknown;
+}
+/**
+ * Recommended `posthog.init()` options for easy-cookie:
+ * - `cookieless_mode: 'on_reject'` (requires "Cookieless server hash mode" enabled
+ *   in the PostHog project settings);
+ * - `persistence: 'localStorage+cookie'` (only used after opt-in);
+ * - `person_profiles: 'identified_only'`;
+ * - a consent-aware `before_send` filter.
+ *
+ * Spread your own options after it: `posthog.init(key, { ...posthogInitOptions(), api_host })`.
+ */
+declare function posthogInitOptions(options?: ConsentBeforeSendOptions): PostHogInitOptions;
+
+export { type ConnectPostHogOptions, type ConsentBeforeSendOptions, NON_ESSENTIAL_EVENTS, type PostHogEventLike, type PostHogInitOptions, type PostHogLike, connectPostHog, consentBeforeSend, posthogInitOptions };

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { EasyCookieApi } from '@easy-cookie/core/shared';
+
+/**
+ * The few posthog-js methods the adapter uses. Typed loosely on purpose, so
+ * `posthog-js` stays an optional peer dependency and any compatible client works.
+ */
+interface PostHogLike {
+    opt_in_capturing(options?: {
+        captureEventName?: string | null | false;
+        [key: string]: unknown;
+    }): void;
+    opt_out_capturing(): void;
+    has_opted_in_capturing?(): boolean;
+    has_opted_out_capturing?(): boolean;
+    clear_opt_in_out_capturing?(): void;
+    startSessionRecording?(...args: unknown[]): void;
+    stopSessionRecording?(): void;
+    identify?(distinctId?: string, ...rest: unknown[]): void;
+    get_distinct_id?(): string;
+}
+/** Minimal shape of a PostHog event passed to `before_send`. */
+interface PostHogEventLike {
+    event: string;
+    properties?: Record<string, any>;
+}
+interface ConnectPostHogOptions {
+    /** Category that allows PostHog cookies/profiles. Default `measurement`. */
+    category?: string;
+    /** Service id: when set, the service's own consent decides instead of the category. */
+    service?: string;
+    /**
+     * Return the logged-in user id (or undefined). Called after opt-in, so the
+     * identified person profile is created only with consent.
+     */
+    identify?: () => string | undefined | null;
+    /**
+     * Before the visitor's first choice:
+     * - `'pending'` (default): capture nothing. A stale opt-in left in storage by an
+     *   earlier setup is cleared, so nothing is captured with cookies.
+     * - `'cookieless'`: count visits without cookies (same as after a rejection).
+     *   Only if your privacy policy covers cookieless measurement without consent.
+     */
+    beforeChoice?: 'pending' | 'cookieless';
+    /** Start session recording on opt-in and stop it on opt-out. Default false. */
+    sessionReplay?: boolean;
+}
+/**
+ * Keep PostHog's capture state in sync with the visitor's consent, without reloads.
+ *
+ * PostHog must be initialised by the host with `cookieless_mode: 'on_reject'`
+ * (see {@link posthogInitOptions}): before a choice it captures nothing, after a
+ * rejection it keeps counting anonymously with no cookies or storage, and after
+ * an acceptance it switches to normal cookie-based capture.
+ *
+ * On `replay`, `consent` and `change` the adapter calls `opt_in_capturing()` or
+ * `opt_out_capturing()`. Returns an unsubscribe function.
+ */
+declare function connectPostHog(posthog: PostHogLike, api: EasyCookieApi, options?: ConnectPostHogOptions): () => void;
+/** Events dropped by {@link consentBeforeSend} while consent is missing. */
+declare const NON_ESSENTIAL_EVENTS: readonly string[];
+interface ConsentBeforeSendOptions {
+    /** Category checked by the default `isGranted`. Default `measurement`. */
+    category?: string;
+    /**
+     * Consent check. Defaults to the runtime when `api` is given, otherwise to the
+     * state published by the head script (`window.__easyCookieHead.granted`).
+     */
+    isGranted?: () => boolean;
+    api?: Pick<EasyCookieApi, 'isGranted'> | null;
+    /** Event names to drop without consent. Default {@link NON_ESSENTIAL_EVENTS}. */
+    drop?: readonly string[];
+}
+/**
+ * `before_send` filter: without consent, drop autocapture, exceptions, web vitals
+ * and heatmap events, so cookieless mode only sends the essentials (pageviews,
+ * explicit captures). Pass it as `before_send` or use {@link posthogInitOptions}.
+ */
+declare function consentBeforeSend(options?: ConsentBeforeSendOptions): <T extends PostHogEventLike | null>(event: T) => T | null;
+interface PostHogInitOptions {
+    cookieless_mode: 'on_reject';
+    persistence: 'localStorage+cookie';
+    person_profiles: 'identified_only';
+    before_send: ReturnType<typeof consentBeforeSend>;
+    [key: string]: unknown;
+}
+/**
+ * Recommended `posthog.init()` options for easy-cookie:
+ * - `cookieless_mode: 'on_reject'` (requires "Cookieless server hash mode" enabled
+ *   in the PostHog project settings);
+ * - `persistence: 'localStorage+cookie'` (only used after opt-in);
+ * - `person_profiles: 'identified_only'`;
+ * - a consent-aware `before_send` filter.
+ *
+ * Spread your own options after it: `posthog.init(key, { ...posthogInitOptions(), api_host })`.
+ */
+declare function posthogInitOptions(options?: ConsentBeforeSendOptions): PostHogInitOptions;
+
+export { type ConnectPostHogOptions, type ConsentBeforeSendOptions, NON_ESSENTIAL_EVENTS, type PostHogEventLike, type PostHogInitOptions, type PostHogLike, connectPostHog, consentBeforeSend, posthogInitOptions };

package/dist/index.js

@@ -0,0 +1,74 @@
+// src/index.ts
+function connectPostHog(posthog, api, options = {}) {
+  const category = options.category ?? "measurement";
+  const granted = () => options.service ? api.isServiceGranted(options.service) : api.isGranted(category);
+  let last = null;
+  const apply = () => {
+    if (!api.get()) {
+      if (options.beforeChoice === "cookieless") {
+        if (last !== "out") {
+          if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
+          last = "out";
+        }
+      } else if (posthog.has_opted_in_capturing?.()) {
+        posthog.clear_opt_in_out_capturing?.();
+      }
+      return;
+    }
+    if (granted()) {
+      if (last !== "in") {
+        if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing({ captureEventName: false });
+        if (options.sessionReplay) posthog.startSessionRecording?.();
+        last = "in";
+      }
+      const id = options.identify?.();
+      if (id && posthog.identify && posthog.get_distinct_id?.() !== id) posthog.identify(id);
+    } else if (last !== "out") {
+      if (options.sessionReplay) posthog.stopSessionRecording?.();
+      if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
+      last = "out";
+    }
+  };
+  const events = ["replay", "consent", "change"];
+  const unsubs = events.map((ev) => api.on(ev, apply));
+  apply();
+  return () => unsubs.forEach((u) => u());
+}
+var NON_ESSENTIAL_EVENTS = [
+  "$autocapture",
+  "$rageclick",
+  "$dead_click",
+  "$exception",
+  "$web_vitals",
+  "$$heatmap",
+  "$heatmap"
+];
+function headGranted(category) {
+  const head = globalThis.__easyCookieHead;
+  return !!head?.valid && !!head.granted?.includes(category);
+}
+function consentBeforeSend(options = {}) {
+  const category = options.category ?? "measurement";
+  const drop = new Set(options.drop ?? NON_ESSENTIAL_EVENTS);
+  const isGranted = options.isGranted ?? (() => options.api ? options.api.isGranted(category) : headGranted(category));
+  return (event) => {
+    if (!event) return event;
+    if (drop.has(event.event) && !isGranted()) return null;
+    return event;
+  };
+}
+function posthogInitOptions(options = {}) {
+  return {
+    cookieless_mode: "on_reject",
+    persistence: "localStorage+cookie",
+    person_profiles: "identified_only",
+    before_send: consentBeforeSend(options)
+  };
+}
+export {
+  NON_ESSENTIAL_EVENTS,
+  connectPostHog,
+  consentBeforeSend,
+  posthogInitOptions
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { EasyCookieApi, EasyCookieEvent } from '@easy-cookie/core/shared';\n\n/**\n * The few posthog-js methods the adapter uses. Typed loosely on purpose, so\n * `posthog-js` stays an optional peer dependency and any compatible client works.\n */\nexport interface PostHogLike {\n  opt_in_capturing(options?: { captureEventName?: string | null | false; [key: string]: unknown }): void;\n  opt_out_capturing(): void;\n  has_opted_in_capturing?(): boolean;\n  has_opted_out_capturing?(): boolean;\n  clear_opt_in_out_capturing?(): void;\n  startSessionRecording?(...args: unknown[]): void;\n  stopSessionRecording?(): void;\n  identify?(distinctId?: string, ...rest: unknown[]): void;\n  get_distinct_id?(): string;\n}\n\n/** Minimal shape of a PostHog event passed to `before_send`. */\nexport interface PostHogEventLike {\n  event: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches posthog-js `Properties`\n  properties?: Record<string, any>;\n}\n\nexport interface ConnectPostHogOptions {\n  /** Category that allows PostHog cookies/profiles. Default `measurement`. */\n  category?: string;\n  /** Service id: when set, the service's own consent decides instead of the category. */\n  service?: string;\n  /**\n   * Return the logged-in user id (or undefined). Called after opt-in, so the\n   * identified person profile is created only with consent.\n   */\n  identify?: () => string | undefined | null;\n  /**\n   * Before the visitor's first choice:\n   * - `'pending'` (default): capture nothing. A stale opt-in left in storage by an\n   *   earlier setup is cleared, so nothing is captured with cookies.\n   * - `'cookieless'`: count visits without cookies (same as after a rejection).\n   *   Only if your privacy policy covers cookieless measurement without consent.\n   */\n  beforeChoice?: 'pending' | 'cookieless';\n  /** Start session recording on opt-in and stop it on opt-out. Default false. */\n  sessionReplay?: boolean;\n}\n\n/**\n * Keep PostHog's capture state in sync with the visitor's consent, without reloads.\n *\n * PostHog must be initialised by the host with `cookieless_mode: 'on_reject'`\n * (see {@link posthogInitOptions}): before a choice it captures nothing, after a\n * rejection it keeps counting anonymously with no cookies or storage, and after\n * an acceptance it switches to normal cookie-based capture.\n *\n * On `replay`, `consent` and `change` the adapter calls `opt_in_capturing()` or\n * `opt_out_capturing()`. Returns an unsubscribe function.\n */\nexport function connectPostHog(posthog: PostHogLike, api: EasyCookieApi, options: ConnectPostHogOptions = {}): () => void {\n  const category = options.category ?? 'measurement';\n  const granted = () => (options.service ? api.isServiceGranted(options.service) : api.isGranted(category));\n  let last: 'in' | 'out' | null = null;\n\n  const apply = () => {\n    if (!api.get()) {\n      if (options.beforeChoice === 'cookieless') {\n        if (last !== 'out') {\n          if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();\n          last = 'out';\n        }\n      } else if (posthog.has_opted_in_capturing?.()) {\n        // Pending: an opt-in stored by a previous banner must not keep capturing.\n        posthog.clear_opt_in_out_capturing?.();\n      }\n      return;\n    }\n    if (granted()) {\n      if (last !== 'in') {\n        // No `$opt_in` event: the consent itself is recorded by easy-cookie.\n        if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing({ captureEventName: false });\n        if (options.sessionReplay) posthog.startSessionRecording?.();\n        last = 'in';\n      }\n      const id = options.identify?.();\n      if (id && posthog.identify && posthog.get_distinct_id?.() !== id) posthog.identify(id);\n    } else if (last !== 'out') {\n      if (options.sessionReplay) posthog.stopSessionRecording?.();\n      if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();\n      last = 'out';\n    }\n  };\n\n  const events: EasyCookieEvent[] = ['replay', 'consent', 'change'];\n  const unsubs = events.map((ev) => api.on(ev, apply));\n  // The stored choice may have been replayed before we subscribed.\n  apply();\n  return () => unsubs.forEach((u) => u());\n}\n\n/** Events dropped by {@link consentBeforeSend} while consent is missing. */\nexport const NON_ESSENTIAL_EVENTS: readonly string[] = [\n  '$autocapture',\n  '$rageclick',\n  '$dead_click',\n  '$exception',\n  '$web_vitals',\n  '$$heatmap',\n  '$heatmap',\n];\n\nexport interface ConsentBeforeSendOptions {\n  /** Category checked by the default `isGranted`. Default `measurement`. */\n  category?: string;\n  /**\n   * Consent check. Defaults to the runtime when `api` is given, otherwise to the\n   * state published by the head script (`window.__easyCookieHead.granted`).\n   */\n  isGranted?: () => boolean;\n  api?: Pick<EasyCookieApi, 'isGranted'> | null;\n  /** Event names to drop without consent. Default {@link NON_ESSENTIAL_EVENTS}. */\n  drop?: readonly string[];\n}\n\nfunction headGranted(category: string): boolean {\n  const head = (globalThis as { __easyCookieHead?: { granted?: string[]; valid?: boolean } }).__easyCookieHead;\n  return !!head?.valid && !!head.granted?.includes(category);\n}\n\n/**\n * `before_send` filter: without consent, drop autocapture, exceptions, web vitals\n * and heatmap events, so cookieless mode only sends the essentials (pageviews,\n * explicit captures). Pass it as `before_send` or use {@link posthogInitOptions}.\n */\nexport function consentBeforeSend(options: ConsentBeforeSendOptions = {}) {\n  const category = options.category ?? 'measurement';\n  const drop = new Set(options.drop ?? NON_ESSENTIAL_EVENTS);\n  const isGranted =\n    options.isGranted ?? (() => (options.api ? options.api.isGranted(category) : headGranted(category)));\n  return <T extends PostHogEventLike | null>(event: T): T | null => {\n    if (!event) return event;\n    if (drop.has(event.event) && !isGranted()) return null;\n    return event;\n  };\n}\n\nexport interface PostHogInitOptions {\n  cookieless_mode: 'on_reject';\n  persistence: 'localStorage+cookie';\n  person_profiles: 'identified_only';\n  before_send: ReturnType<typeof consentBeforeSend>;\n  [key: string]: unknown;\n}\n\n/**\n * Recommended `posthog.init()` options for easy-cookie:\n * - `cookieless_mode: 'on_reject'` (requires \"Cookieless server hash mode\" enabled\n *   in the PostHog project settings);\n * - `persistence: 'localStorage+cookie'` (only used after opt-in);\n * - `person_profiles: 'identified_only'`;\n * - a consent-aware `before_send` filter.\n *\n * Spread your own options after it: `posthog.init(key, { ...posthogInitOptions(), api_host })`.\n */\nexport function posthogInitOptions(options: ConsentBeforeSendOptions = {}): PostHogInitOptions {\n  return {\n    cookieless_mode: 'on_reject',\n    persistence: 'localStorage+cookie',\n    person_profiles: 'identified_only',\n    before_send: consentBeforeSend(options),\n  };\n}\n"],"mappings":";AA0DO,SAAS,eAAe,SAAsB,KAAoB,UAAiC,CAAC,GAAe;AACxH,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,UAAU,MAAO,QAAQ,UAAU,IAAI,iBAAiB,QAAQ,OAAO,IAAI,IAAI,UAAU,QAAQ;AACvG,MAAI,OAA4B;AAEhC,QAAM,QAAQ,MAAM;AAClB,QAAI,CAAC,IAAI,IAAI,GAAG;AACd,UAAI,QAAQ,iBAAiB,cAAc;AACzC,YAAI,SAAS,OAAO;AAClB,cAAI,CAAC,QAAQ,0BAA0B,EAAG,SAAQ,kBAAkB;AACpE,iBAAO;AAAA,QACT;AAAA,MACF,WAAW,QAAQ,yBAAyB,GAAG;AAE7C,gBAAQ,6BAA6B;AAAA,MACvC;AACA;AAAA,IACF;AACA,QAAI,QAAQ,GAAG;AACb,UAAI,SAAS,MAAM;AAEjB,YAAI,CAAC,QAAQ,yBAAyB,EAAG,SAAQ,iBAAiB,EAAE,kBAAkB,MAAM,CAAC;AAC7F,YAAI,QAAQ,cAAe,SAAQ,wBAAwB;AAC3D,eAAO;AAAA,MACT;AACA,YAAM,KAAK,QAAQ,WAAW;AAC9B,UAAI,MAAM,QAAQ,YAAY,QAAQ,kBAAkB,MAAM,GAAI,SAAQ,SAAS,EAAE;AAAA,IACvF,WAAW,SAAS,OAAO;AACzB,UAAI,QAAQ,cAAe,SAAQ,uBAAuB;AAC1D,UAAI,CAAC,QAAQ,0BAA0B,EAAG,SAAQ,kBAAkB;AACpE,aAAO;AAAA,IACT;AAAA,EACF;AAEA,QAAM,SAA4B,CAAC,UAAU,WAAW,QAAQ;AAChE,QAAM,SAAS,OAAO,IAAI,CAAC,OAAO,IAAI,GAAG,IAAI,KAAK,CAAC;AAEnD,QAAM;AACN,SAAO,MAAM,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC;AACxC;AAGO,IAAM,uBAA0C;AAAA,EACrD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAeA,SAAS,YAAY,UAA2B;AAC9C,QAAM,OAAQ,WAA8E;AAC5F,SAAO,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC,KAAK,SAAS,SAAS,QAAQ;AAC3D;AAOO,SAAS,kBAAkB,UAAoC,CAAC,GAAG;AACxE,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,OAAO,IAAI,IAAI,QAAQ,QAAQ,oBAAoB;AACzD,QAAM,YACJ,QAAQ,cAAc,MAAO,QAAQ,MAAM,QAAQ,IAAI,UAAU,QAAQ,IAAI,YAAY,QAAQ;AACnG,SAAO,CAAoC,UAAuB;AAChE,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI,KAAK,IAAI,MAAM,KAAK,KAAK,CAAC,UAAU,EAAG,QAAO;AAClD,WAAO;AAAA,EACT;AACF;AAoBO,SAAS,mBAAmB,UAAoC,CAAC,GAAuB;AAC7F,SAAO;AAAA,IACL,iBAAiB;AAAA,IACjB,aAAa;AAAA,IACb,iBAAiB;AAAA,IACjB,aAAa,kBAAkB,OAAO;AAAA,EACxC;AACF;","names":[]}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@easy-cookie/posthog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "PostHog adapter for easy-cookie: cookieless on_reject mode and opt-in/out synced with consent.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aleloca/easy-cookie.git",
+    "directory": "packages/posthog"
+  },
+  "bugs": {
+    "url": "https://github.com/Aleloca/easy-cookie/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@easy-cookie/core": "^0.1.1"
+  },
+  "peerDependencies": {
+    "posthog-js": ">=1.200.0"
+  },
+  "peerDependenciesMeta": {
+    "posthog-js": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://consent.aleloca.dev",
+  "keywords": [
+    "cookie",
+    "consent",
+    "gdpr",
+    "cookie-banner",
+    "consent-mode"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }