@easy-cookie/posthog 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -0
- package/dist/index.cjs +14 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +18 -3
- package/dist/index.d.ts +18 -3
- package/dist/index.js +14 -2
- package/dist/index.js.map +1 -1
- package/package.json +10 -2
package/README.md
CHANGED
|
@@ -92,3 +92,17 @@ The consent check works like this:
|
|
|
92
92
|
## License
|
|
93
93
|
|
|
94
94
|
MIT
|
|
95
|
+
|
|
96
|
+
## Options
|
|
97
|
+
|
|
98
|
+
`connectPostHog(posthog, api, options)`:
|
|
99
|
+
|
|
100
|
+
| Option | Default | Effect |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| `category` | `measurement` | Category that allows PostHog cookies and profiles |
|
|
103
|
+
| `service` | — | Decide on this service's consent instead of the category |
|
|
104
|
+
| `identify` | — | Returns the logged-in user id; called after opt-in |
|
|
105
|
+
| `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. |
|
|
106
|
+
| `sessionReplay` | `false` | Start session recording on opt-in and stop it on opt-out |
|
|
107
|
+
|
|
108
|
+
Opt-in does not send a `$opt_in` event: easy-cookie already records the consent.
|
package/dist/index.cjs
CHANGED
|
@@ -31,15 +31,27 @@ function connectPostHog(posthog, api, options = {}) {
|
|
|
31
31
|
const granted = () => options.service ? api.isServiceGranted(options.service) : api.isGranted(category);
|
|
32
32
|
let last = null;
|
|
33
33
|
const apply = () => {
|
|
34
|
-
if (!api.get())
|
|
34
|
+
if (!api.get()) {
|
|
35
|
+
if (options.beforeChoice === "cookieless") {
|
|
36
|
+
if (last !== "out") {
|
|
37
|
+
if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
|
|
38
|
+
last = "out";
|
|
39
|
+
}
|
|
40
|
+
} else if (posthog.has_opted_in_capturing?.()) {
|
|
41
|
+
posthog.clear_opt_in_out_capturing?.();
|
|
42
|
+
}
|
|
43
|
+
return;
|
|
44
|
+
}
|
|
35
45
|
if (granted()) {
|
|
36
46
|
if (last !== "in") {
|
|
37
|
-
if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing();
|
|
47
|
+
if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing({ captureEventName: false });
|
|
48
|
+
if (options.sessionReplay) posthog.startSessionRecording?.();
|
|
38
49
|
last = "in";
|
|
39
50
|
}
|
|
40
51
|
const id = options.identify?.();
|
|
41
52
|
if (id && posthog.identify && posthog.get_distinct_id?.() !== id) posthog.identify(id);
|
|
42
53
|
} else if (last !== "out") {
|
|
54
|
+
if (options.sessionReplay) posthog.stopSessionRecording?.();
|
|
43
55
|
if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
|
|
44
56
|
last = "out";
|
|
45
57
|
}
|
package/dist/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
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?: unknown): void;\n opt_out_capturing(): void;\n has_opted_in_capturing?(): boolean;\n has_opted_out_capturing?(): boolean;\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 properties?: Record<string,
|
|
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
CHANGED
|
@@ -5,18 +5,23 @@ import { EasyCookieApi } from '@easy-cookie/core/shared';
|
|
|
5
5
|
* `posthog-js` stays an optional peer dependency and any compatible client works.
|
|
6
6
|
*/
|
|
7
7
|
interface PostHogLike {
|
|
8
|
-
opt_in_capturing(options?:
|
|
8
|
+
opt_in_capturing(options?: {
|
|
9
|
+
captureEventName?: string | null | false;
|
|
10
|
+
[key: string]: unknown;
|
|
11
|
+
}): void;
|
|
9
12
|
opt_out_capturing(): void;
|
|
10
13
|
has_opted_in_capturing?(): boolean;
|
|
11
14
|
has_opted_out_capturing?(): boolean;
|
|
15
|
+
clear_opt_in_out_capturing?(): void;
|
|
16
|
+
startSessionRecording?(...args: unknown[]): void;
|
|
17
|
+
stopSessionRecording?(): void;
|
|
12
18
|
identify?(distinctId?: string, ...rest: unknown[]): void;
|
|
13
19
|
get_distinct_id?(): string;
|
|
14
20
|
}
|
|
15
21
|
/** Minimal shape of a PostHog event passed to `before_send`. */
|
|
16
22
|
interface PostHogEventLike {
|
|
17
23
|
event: string;
|
|
18
|
-
properties?: Record<string,
|
|
19
|
-
[key: string]: unknown;
|
|
24
|
+
properties?: Record<string, any>;
|
|
20
25
|
}
|
|
21
26
|
interface ConnectPostHogOptions {
|
|
22
27
|
/** Category that allows PostHog cookies/profiles. Default `measurement`. */
|
|
@@ -28,6 +33,16 @@ interface ConnectPostHogOptions {
|
|
|
28
33
|
* identified person profile is created only with consent.
|
|
29
34
|
*/
|
|
30
35
|
identify?: () => string | undefined | null;
|
|
36
|
+
/**
|
|
37
|
+
* Before the visitor's first choice:
|
|
38
|
+
* - `'pending'` (default): capture nothing. A stale opt-in left in storage by an
|
|
39
|
+
* earlier setup is cleared, so nothing is captured with cookies.
|
|
40
|
+
* - `'cookieless'`: count visits without cookies (same as after a rejection).
|
|
41
|
+
* Only if your privacy policy covers cookieless measurement without consent.
|
|
42
|
+
*/
|
|
43
|
+
beforeChoice?: 'pending' | 'cookieless';
|
|
44
|
+
/** Start session recording on opt-in and stop it on opt-out. Default false. */
|
|
45
|
+
sessionReplay?: boolean;
|
|
31
46
|
}
|
|
32
47
|
/**
|
|
33
48
|
* Keep PostHog's capture state in sync with the visitor's consent, without reloads.
|
package/dist/index.d.ts
CHANGED
|
@@ -5,18 +5,23 @@ import { EasyCookieApi } from '@easy-cookie/core/shared';
|
|
|
5
5
|
* `posthog-js` stays an optional peer dependency and any compatible client works.
|
|
6
6
|
*/
|
|
7
7
|
interface PostHogLike {
|
|
8
|
-
opt_in_capturing(options?:
|
|
8
|
+
opt_in_capturing(options?: {
|
|
9
|
+
captureEventName?: string | null | false;
|
|
10
|
+
[key: string]: unknown;
|
|
11
|
+
}): void;
|
|
9
12
|
opt_out_capturing(): void;
|
|
10
13
|
has_opted_in_capturing?(): boolean;
|
|
11
14
|
has_opted_out_capturing?(): boolean;
|
|
15
|
+
clear_opt_in_out_capturing?(): void;
|
|
16
|
+
startSessionRecording?(...args: unknown[]): void;
|
|
17
|
+
stopSessionRecording?(): void;
|
|
12
18
|
identify?(distinctId?: string, ...rest: unknown[]): void;
|
|
13
19
|
get_distinct_id?(): string;
|
|
14
20
|
}
|
|
15
21
|
/** Minimal shape of a PostHog event passed to `before_send`. */
|
|
16
22
|
interface PostHogEventLike {
|
|
17
23
|
event: string;
|
|
18
|
-
properties?: Record<string,
|
|
19
|
-
[key: string]: unknown;
|
|
24
|
+
properties?: Record<string, any>;
|
|
20
25
|
}
|
|
21
26
|
interface ConnectPostHogOptions {
|
|
22
27
|
/** Category that allows PostHog cookies/profiles. Default `measurement`. */
|
|
@@ -28,6 +33,16 @@ interface ConnectPostHogOptions {
|
|
|
28
33
|
* identified person profile is created only with consent.
|
|
29
34
|
*/
|
|
30
35
|
identify?: () => string | undefined | null;
|
|
36
|
+
/**
|
|
37
|
+
* Before the visitor's first choice:
|
|
38
|
+
* - `'pending'` (default): capture nothing. A stale opt-in left in storage by an
|
|
39
|
+
* earlier setup is cleared, so nothing is captured with cookies.
|
|
40
|
+
* - `'cookieless'`: count visits without cookies (same as after a rejection).
|
|
41
|
+
* Only if your privacy policy covers cookieless measurement without consent.
|
|
42
|
+
*/
|
|
43
|
+
beforeChoice?: 'pending' | 'cookieless';
|
|
44
|
+
/** Start session recording on opt-in and stop it on opt-out. Default false. */
|
|
45
|
+
sessionReplay?: boolean;
|
|
31
46
|
}
|
|
32
47
|
/**
|
|
33
48
|
* Keep PostHog's capture state in sync with the visitor's consent, without reloads.
|
package/dist/index.js
CHANGED
|
@@ -4,15 +4,27 @@ function connectPostHog(posthog, api, options = {}) {
|
|
|
4
4
|
const granted = () => options.service ? api.isServiceGranted(options.service) : api.isGranted(category);
|
|
5
5
|
let last = null;
|
|
6
6
|
const apply = () => {
|
|
7
|
-
if (!api.get())
|
|
7
|
+
if (!api.get()) {
|
|
8
|
+
if (options.beforeChoice === "cookieless") {
|
|
9
|
+
if (last !== "out") {
|
|
10
|
+
if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
|
|
11
|
+
last = "out";
|
|
12
|
+
}
|
|
13
|
+
} else if (posthog.has_opted_in_capturing?.()) {
|
|
14
|
+
posthog.clear_opt_in_out_capturing?.();
|
|
15
|
+
}
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
8
18
|
if (granted()) {
|
|
9
19
|
if (last !== "in") {
|
|
10
|
-
if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing();
|
|
20
|
+
if (!posthog.has_opted_in_capturing?.()) posthog.opt_in_capturing({ captureEventName: false });
|
|
21
|
+
if (options.sessionReplay) posthog.startSessionRecording?.();
|
|
11
22
|
last = "in";
|
|
12
23
|
}
|
|
13
24
|
const id = options.identify?.();
|
|
14
25
|
if (id && posthog.identify && posthog.get_distinct_id?.() !== id) posthog.identify(id);
|
|
15
26
|
} else if (last !== "out") {
|
|
27
|
+
if (options.sessionReplay) posthog.stopSessionRecording?.();
|
|
16
28
|
if (!posthog.has_opted_out_capturing?.()) posthog.opt_out_capturing();
|
|
17
29
|
last = "out";
|
|
18
30
|
}
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
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?: unknown): void;\n opt_out_capturing(): void;\n has_opted_in_capturing?(): boolean;\n has_opted_out_capturing?(): boolean;\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 properties?: Record<string,
|
|
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
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@easy-cookie/posthog",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "PostHog adapter for easy-cookie: cookieless on_reject mode and opt-in/out synced with consent.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/Aleloca/easy-cookie.git",
|
|
9
|
+
"directory": "packages/posthog"
|
|
10
|
+
},
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/Aleloca/easy-cookie/issues"
|
|
13
|
+
},
|
|
6
14
|
"type": "module",
|
|
7
15
|
"sideEffects": false,
|
|
8
16
|
"main": "./dist/index.cjs",
|
|
@@ -20,7 +28,7 @@
|
|
|
20
28
|
"dist"
|
|
21
29
|
],
|
|
22
30
|
"dependencies": {
|
|
23
|
-
"@easy-cookie/core": "^0.1.
|
|
31
|
+
"@easy-cookie/core": "^0.1.1"
|
|
24
32
|
},
|
|
25
33
|
"peerDependencies": {
|
|
26
34
|
"posthog-js": ">=1.200.0"
|