@codefast/tracking 0.6.2 → 0.7.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/CHANGELOG.md +10 -0
- package/README.md +1 -1
- package/dist/adapters/tanstack-start.d.ts +11 -7
- package/dist/adapters/tanstack-start.d.ts.map +1 -1
- package/dist/adapters/tanstack-start.js +4 -4
- package/dist/adapters/tanstack-start.js.map +1 -1
- package/dist/client/ad-framework-consent.d.ts +8 -6
- package/dist/client/ad-framework-consent.d.ts.map +1 -1
- package/dist/client/ad-framework-consent.js +3 -3
- package/dist/client/ad-framework-consent.js.map +1 -1
- package/dist/client/browser-cookie.d.ts +1 -1
- package/dist/client/browser-cookie.js +1 -1
- package/dist/client/consent-runtime.d.ts +5 -3
- package/dist/client/consent-runtime.d.ts.map +1 -1
- package/dist/client/consent-runtime.js +1 -1
- package/dist/client/consent-runtime.js.map +1 -1
- package/dist/client/consent-withdrawal.d.ts +4 -2
- package/dist/client/consent-withdrawal.d.ts.map +1 -1
- package/dist/client/consent-withdrawal.js +1 -1
- package/dist/client/consent-withdrawal.js.map +1 -1
- package/dist/client/cookie-anonymous-id.d.ts +7 -3
- package/dist/client/cookie-anonymous-id.d.ts.map +1 -1
- package/dist/client/cookie-anonymous-id.js +1 -1
- package/dist/client/cookie-anonymous-id.js.map +1 -1
- package/dist/client/create-client-tracker.d.ts +7 -1
- package/dist/client/create-client-tracker.d.ts.map +1 -1
- package/dist/client/create-client-tracker.js +2 -0
- package/dist/client/create-client-tracker.js.map +1 -1
- package/dist/client/initial-consent-store.d.ts +6 -4
- package/dist/client/initial-consent-store.d.ts.map +1 -1
- package/dist/client/initial-consent-store.js +1 -1
- package/dist/client/initial-consent-store.js.map +1 -1
- package/dist/client/is-analytics-allowed.d.ts +4 -2
- package/dist/client/is-analytics-allowed.d.ts.map +1 -1
- package/dist/client/is-analytics-allowed.js +1 -1
- package/dist/client/is-analytics-allowed.js.map +1 -1
- package/dist/client/server-persisted-anonymous-id.d.ts +4 -2
- package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -1
- package/dist/client/server-persisted-anonymous-id.js +1 -1
- package/dist/client/server-persisted-anonymous-id.js.map +1 -1
- package/dist/core/consent-config.d.ts +2 -2
- package/dist/core/consent-config.js +1 -1
- package/dist/core/consent-receipt.d.ts +6 -6
- package/dist/core/consent-receipt.js +1 -1
- package/dist/core/consent.d.ts +23 -11
- package/dist/core/consent.d.ts.map +1 -1
- package/dist/core/consent.js +12 -8
- package/dist/core/consent.js.map +1 -1
- package/dist/core/cookie.d.ts +2 -2
- package/dist/core/cookie.js +2 -2
- package/dist/core/event-catalog.d.ts +1 -1
- package/dist/core/event-catalog.js +1 -1
- package/dist/destinations/ad-consent.d.ts +2 -2
- package/dist/destinations/ad-consent.js +1 -1
- package/dist/destinations/google-analytics.d.ts +16 -8
- package/dist/destinations/google-analytics.d.ts.map +1 -1
- package/dist/destinations/google-analytics.js +4 -4
- package/dist/destinations/google-analytics.js.map +1 -1
- package/dist/destinations/google-consent.d.ts +9 -7
- package/dist/destinations/google-consent.d.ts.map +1 -1
- package/dist/destinations/google-consent.js +5 -5
- package/dist/destinations/google-consent.js.map +1 -1
- package/dist/destinations/meta.d.ts +7 -5
- package/dist/destinations/meta.d.ts.map +1 -1
- package/dist/destinations/meta.js +2 -2
- package/dist/destinations/meta.js.map +1 -1
- package/dist/destinations/microsoft-uet.d.ts +7 -5
- package/dist/destinations/microsoft-uet.d.ts.map +1 -1
- package/dist/destinations/microsoft-uet.js +2 -2
- package/dist/destinations/microsoft-uet.js.map +1 -1
- package/dist/destinations/shared.d.ts +7 -3
- package/dist/destinations/shared.d.ts.map +1 -1
- package/dist/destinations/shared.js +3 -1
- package/dist/destinations/shared.js.map +1 -1
- package/dist/destinations/tiktok.d.ts +7 -5
- package/dist/destinations/tiktok.d.ts.map +1 -1
- package/dist/destinations/tiktok.js +2 -2
- package/dist/destinations/tiktok.js.map +1 -1
- package/dist/destinations/vercel-analytics.d.ts +3 -1
- package/dist/destinations/vercel-analytics.d.ts.map +1 -1
- package/dist/destinations/vercel-analytics.js.map +1 -1
- package/dist/react/consent-banner.d.ts +28 -0
- package/dist/react/consent-banner.d.ts.map +1 -1
- package/dist/react/consent-banner.js +11 -7
- package/dist/react/consent-banner.js.map +1 -1
- package/dist/react/gtag-consent-bootstrap.d.ts +4 -2
- package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -1
- package/dist/react/gtag-consent-bootstrap.js +1 -1
- package/dist/react/gtag-consent-bootstrap.js.map +1 -1
- package/dist/react/use-consent.d.ts +4 -0
- package/dist/react/use-consent.d.ts.map +1 -1
- package/dist/react/use-consent.js.map +1 -1
- package/dist/react/use-google-consent-sync.d.ts +4 -2
- package/dist/react/use-google-consent-sync.d.ts.map +1 -1
- package/dist/react/use-google-consent-sync.js +1 -1
- package/dist/react/use-google-consent-sync.js.map +1 -1
- package/dist/react/use-initial-consent.d.ts +1 -1
- package/dist/react/use-initial-consent.js +1 -1
- package/dist/server/anonymous-id-cookie.d.ts +7 -5
- package/dist/server/anonymous-id-cookie.d.ts.map +1 -1
- package/dist/server/anonymous-id-cookie.js +4 -4
- package/dist/server/anonymous-id-cookie.js.map +1 -1
- package/dist/server/consent-receipt-store.d.ts +4 -4
- package/dist/server/consent-receipt-store.js +2 -2
- package/dist/server/consent-receipt.d.ts +4 -4
- package/dist/server/consent-receipt.js +3 -3
- package/dist/server/initial-consent.d.ts +4 -2
- package/dist/server/initial-consent.d.ts.map +1 -1
- package/dist/server/initial-consent.js +1 -1
- package/dist/server/initial-consent.js.map +1 -1
- package/dist/server/measurement-protocol.d.ts +9 -7
- package/dist/server/measurement-protocol.d.ts.map +1 -1
- package/dist/server/measurement-protocol.js +3 -3
- package/dist/server/measurement-protocol.js.map +1 -1
- package/dist/server/region.d.ts +2 -2
- package/dist/server/region.js +2 -2
- package/dist/server/user-deletion.d.ts +9 -5
- package/dist/server/user-deletion.d.ts.map +1 -1
- package/dist/server/user-deletion.js +2 -2
- package/dist/server/user-deletion.js.map +1 -1
- package/dist/tooling/import-protection.d.ts +1 -1
- package/dist/tooling/import-protection.js +1 -1
- package/package.json +7 -7
- package/src/adapters/tanstack-start.ts +11 -7
- package/src/client/ad-framework-consent.ts +8 -6
- package/src/client/browser-cookie.ts +1 -1
- package/src/client/consent-runtime.ts +5 -3
- package/src/client/consent-withdrawal.ts +4 -2
- package/src/client/cookie-anonymous-id.ts +7 -3
- package/src/client/create-client-tracker.ts +7 -1
- package/src/client/initial-consent-store.ts +6 -4
- package/src/client/is-analytics-allowed.ts +4 -2
- package/src/client/server-persisted-anonymous-id.ts +4 -2
- package/src/core/consent-config.ts +2 -2
- package/src/core/consent-receipt.ts +6 -6
- package/src/core/consent.ts +23 -11
- package/src/core/cookie.ts +2 -2
- package/src/core/event-catalog.ts +1 -1
- package/src/destinations/ad-consent.ts +2 -2
- package/src/destinations/google-analytics.ts +16 -8
- package/src/destinations/google-consent.ts +9 -7
- package/src/destinations/meta.ts +7 -5
- package/src/destinations/microsoft-uet.ts +7 -5
- package/src/destinations/shared.ts +10 -4
- package/src/destinations/tiktok.ts +7 -5
- package/src/destinations/vercel-analytics.ts +3 -1
- package/src/react/consent-banner.tsx +34 -8
- package/src/react/gtag-consent-bootstrap.tsx +4 -2
- package/src/react/use-consent.ts +4 -0
- package/src/react/use-google-consent-sync.ts +4 -2
- package/src/react/use-initial-consent.ts +1 -1
- package/src/server/anonymous-id-cookie.ts +7 -5
- package/src/server/consent-receipt-store.ts +4 -4
- package/src/server/consent-receipt.ts +4 -4
- package/src/server/initial-consent.ts +4 -2
- package/src/server/measurement-protocol.ts +9 -7
- package/src/server/region.ts +2 -2
- package/src/server/user-deletion.ts +9 -5
- package/src/tooling/import-protection.ts +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codefast/tracking",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"description": "Consent-gated, type-safe event tracking for TanStack Start — client tracker and server consent helpers over a per-app Standard Schema event catalog",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"analytics",
|
|
@@ -275,25 +275,25 @@
|
|
|
275
275
|
"@standard-schema/spec": "^1.1.0"
|
|
276
276
|
},
|
|
277
277
|
"devDependencies": {
|
|
278
|
-
"@tanstack/react-start": "^1.168.
|
|
278
|
+
"@tanstack/react-start": "^1.168.49",
|
|
279
279
|
"@testing-library/dom": "^10.4.1",
|
|
280
280
|
"@testing-library/jest-dom": "^7.0.1",
|
|
281
281
|
"@testing-library/react": "^16.3.2",
|
|
282
|
-
"@testing-library/user-event": "^14.6.
|
|
282
|
+
"@testing-library/user-event": "^14.6.6",
|
|
283
283
|
"@types/node": "^26.2.0",
|
|
284
284
|
"@types/react": "^19.2.18",
|
|
285
285
|
"@types/react-dom": "^19.2.4",
|
|
286
286
|
"@vercel/analytics": "^2.0.1",
|
|
287
|
-
"@vitejs/plugin-react": "^6.0
|
|
288
|
-
"@vitest/coverage-v8": "^4.1.
|
|
287
|
+
"@vitejs/plugin-react": "^6.1.0",
|
|
288
|
+
"@vitest/coverage-v8": "^4.1.11",
|
|
289
289
|
"expect-type": "^1.4.0",
|
|
290
290
|
"jsdom": "^30.0.1",
|
|
291
291
|
"react": "^19.2.8",
|
|
292
292
|
"react-dom": "^19.2.8",
|
|
293
293
|
"typescript": "^7.0.2",
|
|
294
|
-
"vitest": "^4.1.
|
|
294
|
+
"vitest": "^4.1.11",
|
|
295
295
|
"zod": "^4.4.3",
|
|
296
|
-
"@codefast/typescript-config": "0.
|
|
296
|
+
"@codefast/typescript-config": "0.8.0"
|
|
297
297
|
},
|
|
298
298
|
"peerDependencies": {
|
|
299
299
|
"@tanstack/react-start": ">=1.168.0",
|
|
@@ -16,7 +16,9 @@ import type { ReceiptStore } from "#/server/consent-receipt-store";
|
|
|
16
16
|
import { resolveInitialConsent } from "#/server/initial-consent";
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
|
-
*
|
|
19
|
+
* Options for `resolveInitialConsentFromRequest`.
|
|
20
|
+
*
|
|
21
|
+
* @since 0.5.0-canary.6
|
|
20
22
|
*/
|
|
21
23
|
export interface InitialConsentFromRequestOptions {
|
|
22
24
|
/**
|
|
@@ -38,7 +40,7 @@ export interface InitialConsentFromRequestOptions {
|
|
|
38
40
|
* Server-only: deny this subpath in the client environment via Start's `importProtection`
|
|
39
41
|
* — the compiler already strips it with stubbed handler bodies.
|
|
40
42
|
*
|
|
41
|
-
* @since
|
|
43
|
+
* @since 0.5.0-canary.6
|
|
42
44
|
*/
|
|
43
45
|
export function resolveInitialConsentFromRequest(options: InitialConsentFromRequestOptions): InitialConsent {
|
|
44
46
|
setResponseHeader("cache-control", "private, no-store");
|
|
@@ -57,7 +59,7 @@ export function resolveInitialConsentFromRequest(options: InitialConsentFromRequ
|
|
|
57
59
|
* `resolveAnonymousIdCookie`: a non-UUID id throws, so this can safely back a public server
|
|
58
60
|
* function without echoing attacker input into a header.
|
|
59
61
|
*
|
|
60
|
-
* @since
|
|
62
|
+
* @since 0.5.0-canary.6
|
|
61
63
|
*/
|
|
62
64
|
export function setAnonymousIdResponseCookie(options: AnonymousIdCookieOptions): void {
|
|
63
65
|
const { name, value, ...attributes } = resolveAnonymousIdCookie({
|
|
@@ -72,7 +74,7 @@ export function setAnonymousIdResponseCookie(options: AnonymousIdCookieOptions):
|
|
|
72
74
|
/**
|
|
73
75
|
* Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
|
|
74
76
|
*
|
|
75
|
-
* @since
|
|
77
|
+
* @since 0.5.0-canary.6
|
|
76
78
|
*/
|
|
77
79
|
export function clearAnonymousIdResponseCookie(cookieName: string): void {
|
|
78
80
|
const { name, ...attributes } = resolveClearAnonymousIdCookie(cookieName);
|
|
@@ -84,7 +86,7 @@ export function clearAnonymousIdResponseCookie(cookieName: string): void {
|
|
|
84
86
|
* The client-visible acknowledgement of a recorded receipt — deliberately minimal so the
|
|
85
87
|
* stored PII (`subjectId`, `ipCoarse`) is never echoed back over the wire.
|
|
86
88
|
*
|
|
87
|
-
* @since
|
|
89
|
+
* @since 0.5.0-canary.6
|
|
88
90
|
*/
|
|
89
91
|
export interface ConsentReceiptAck {
|
|
90
92
|
receiptId: string;
|
|
@@ -92,7 +94,9 @@ export interface ConsentReceiptAck {
|
|
|
92
94
|
}
|
|
93
95
|
|
|
94
96
|
/**
|
|
95
|
-
*
|
|
97
|
+
* Options for `recordConsentReceiptFromRequest`.
|
|
98
|
+
*
|
|
99
|
+
* @since 0.5.0-canary.6
|
|
96
100
|
*/
|
|
97
101
|
export interface RecordConsentReceiptFromRequestOptions {
|
|
98
102
|
input: ConsentReceiptInput;
|
|
@@ -113,7 +117,7 @@ export interface RecordConsentReceiptFromRequestOptions {
|
|
|
113
117
|
* @throws Error when `input` fails {@link isConsentReceiptInput} (including a body that
|
|
114
118
|
* carries an `ip`/`ipCoarse` field — the server owns IP derivation).
|
|
115
119
|
*
|
|
116
|
-
* @since
|
|
120
|
+
* @since 0.5.0-canary.6
|
|
117
121
|
*/
|
|
118
122
|
export async function recordConsentReceiptFromRequest(
|
|
119
123
|
options: RecordConsentReceiptFromRequestOptions,
|
|
@@ -11,14 +11,14 @@ import type { ConsentCategory, ConsentDecision } from "#/core/consent";
|
|
|
11
11
|
* Liveness of a detected CMP. `"out-of-scope"` is TCF `gdprApplies === false` / no applicable
|
|
12
12
|
* GPP section — the framework does not govern this user, so native consent stands.
|
|
13
13
|
*
|
|
14
|
-
* @since
|
|
14
|
+
* @since 0.5.0-canary.6
|
|
15
15
|
*/
|
|
16
16
|
export type CmpStatus = "loading" | "out-of-scope" | "ready";
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
19
|
* A CMP's governance over the native decision, already derived from TCData/GPP by ad-ops policy.
|
|
20
20
|
*
|
|
21
|
-
* @since
|
|
21
|
+
* @since 0.5.0-canary.6
|
|
22
22
|
*/
|
|
23
23
|
export interface CmpConsentSignal {
|
|
24
24
|
/** Per-governed-category grant, read once `status` is `"ready"`. */
|
|
@@ -29,7 +29,9 @@ export interface CmpConsentSignal {
|
|
|
29
29
|
}
|
|
30
30
|
|
|
31
31
|
/**
|
|
32
|
-
*
|
|
32
|
+
* Options for `reconcileAdFrameworkConsent`.
|
|
33
|
+
*
|
|
34
|
+
* @since 0.5.0-canary.6
|
|
33
35
|
*/
|
|
34
36
|
export interface ReconcileAdFrameworkConsentOptions {
|
|
35
37
|
/** The live CMP signal, or omitted when no CMP is present (the resolver is then inert). */
|
|
@@ -45,7 +47,7 @@ export interface ReconcileAdFrameworkConsentOptions {
|
|
|
45
47
|
* a governing CMP overrides its categories (fail-closed to denied while loading); a missing
|
|
46
48
|
* or out-of-scope CMP leaves native standing; GPC always tightens `ads` last.
|
|
47
49
|
*
|
|
48
|
-
* @since
|
|
50
|
+
* @since 0.5.0-canary.6
|
|
49
51
|
*/
|
|
50
52
|
export function reconcileAdFrameworkConsent(options: ReconcileAdFrameworkConsentOptions): ConsentDecision {
|
|
51
53
|
const result: ConsentDecision = { ...options.native };
|
|
@@ -70,7 +72,7 @@ export function reconcileAdFrameworkConsent(options: ReconcileAdFrameworkConsent
|
|
|
70
72
|
/**
|
|
71
73
|
* Detects a TCF CMP without reading it — `typeof __tcfapi === "function"` (spec §3).
|
|
72
74
|
*
|
|
73
|
-
* @since
|
|
75
|
+
* @since 0.5.0-canary.6
|
|
74
76
|
*/
|
|
75
77
|
export function hasTcfApi(scope: { __tcfapi?: unknown } = globalThis as { __tcfapi?: unknown }): boolean {
|
|
76
78
|
return typeof scope.__tcfapi === "function";
|
|
@@ -79,7 +81,7 @@ export function hasTcfApi(scope: { __tcfapi?: unknown } = globalThis as { __tcfa
|
|
|
79
81
|
/**
|
|
80
82
|
* Detects a GPP CMP without reading it — `typeof __gpp === "function"` (spec §3).
|
|
81
83
|
*
|
|
82
|
-
* @since
|
|
84
|
+
* @since 0.5.0-canary.6
|
|
83
85
|
*/
|
|
84
86
|
export function hasGppApi(scope: { __gpp?: unknown } = globalThis as { __gpp?: unknown }): boolean {
|
|
85
87
|
return typeof scope.__gpp === "function";
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* mirror): Secure on HTTPS so values never ride plain HTTP, SameSite=Lax, never HttpOnly —
|
|
4
4
|
* the client must read its own cookies back. A no-op without a `document` (SSR).
|
|
5
5
|
*
|
|
6
|
-
* @since
|
|
6
|
+
* @since 0.5.0-canary.6
|
|
7
7
|
*/
|
|
8
8
|
export function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void {
|
|
9
9
|
if (typeof document === "undefined") {
|
|
@@ -7,7 +7,9 @@ import type { ConsentStorage, InitialConsent } from "#/core/consent";
|
|
|
7
7
|
import type { ConsentConfig } from "#/core/consent-config";
|
|
8
8
|
|
|
9
9
|
/**
|
|
10
|
-
*
|
|
10
|
+
* Options for `createConsentRuntime`.
|
|
11
|
+
*
|
|
12
|
+
* @since 0.5.0-canary.6
|
|
11
13
|
*/
|
|
12
14
|
export interface ConsentRuntimeOptions {
|
|
13
15
|
config: ConsentConfig;
|
|
@@ -31,7 +33,7 @@ export interface ConsentRuntimeOptions {
|
|
|
31
33
|
* it once at module scope and every surface (banner hook, tracker gate, privacy page)
|
|
32
34
|
* shares the same storage and region resolution by construction.
|
|
33
35
|
*
|
|
34
|
-
* @since
|
|
36
|
+
* @since 0.5.0-canary.6
|
|
35
37
|
*/
|
|
36
38
|
export interface ConsentRuntime {
|
|
37
39
|
config: ConsentConfig;
|
|
@@ -54,7 +56,7 @@ export interface ConsentRuntime {
|
|
|
54
56
|
* `localStorage`-backed decision storage, the initial-consent store over the app's
|
|
55
57
|
* server lane, and the non-React analytics gate wired to that store's resolved mode.
|
|
56
58
|
*
|
|
57
|
-
* @since
|
|
59
|
+
* @since 0.5.0-canary.6
|
|
58
60
|
*/
|
|
59
61
|
export function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime {
|
|
60
62
|
const { config } = options;
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import type { ConsentDecision } from "#/core/consent";
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
*
|
|
4
|
+
* Options for `createConsentWithdrawalHandler`.
|
|
5
|
+
*
|
|
6
|
+
* @since 0.5.0-canary.6
|
|
5
7
|
*/
|
|
6
8
|
export interface ConsentWithdrawalHandlerOptions {
|
|
7
9
|
/** Forget the cookie-backed visitor id when analytics is denied. */
|
|
@@ -14,7 +16,7 @@ export interface ConsentWithdrawalHandlerOptions {
|
|
|
14
16
|
* `useConsent({ onDecision })` handler that clears first-party tracking state when the
|
|
15
17
|
* visitor denies (or withdraws) analytics. Grant paths are a no-op.
|
|
16
18
|
*
|
|
17
|
-
* @since
|
|
19
|
+
* @since 0.5.0-canary.6
|
|
18
20
|
*/
|
|
19
21
|
export function createConsentWithdrawalHandler(
|
|
20
22
|
options: ConsentWithdrawalHandlerOptions,
|
|
@@ -2,7 +2,9 @@ import { writeBrowserCookie } from "#/client/browser-cookie";
|
|
|
2
2
|
import { ONE_YEAR_IN_SECONDS, readCookieValue } from "#/core/cookie";
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
5
|
+
* Options for `createCookieAnonymousId`.
|
|
6
|
+
*
|
|
7
|
+
* @since 0.5.0-canary.6
|
|
6
8
|
*/
|
|
7
9
|
export interface CookieAnonymousIdOptions {
|
|
8
10
|
/** Cookie name — must not collide with another cookie on the domain. */
|
|
@@ -12,7 +14,9 @@ export interface CookieAnonymousIdOptions {
|
|
|
12
14
|
}
|
|
13
15
|
|
|
14
16
|
/**
|
|
15
|
-
*
|
|
17
|
+
* A cookie-backed anonymous id handle: lazy minting, expiry refresh, and clearing on withdrawal.
|
|
18
|
+
*
|
|
19
|
+
* @since 0.5.0-canary.6
|
|
16
20
|
*/
|
|
17
21
|
export interface CookieAnonymousId {
|
|
18
22
|
/** Expires the cookie — call when the visitor withdraws tracking consent. */
|
|
@@ -40,7 +44,7 @@ export interface CookieAnonymousId {
|
|
|
40
44
|
* it's invoked lazily, so the cookie is minted only once an event is actually allowed to
|
|
41
45
|
* send, never as an import-time side effect.
|
|
42
46
|
*
|
|
43
|
-
* @since
|
|
47
|
+
* @since 0.5.0-canary.6
|
|
44
48
|
*/
|
|
45
49
|
export function createCookieAnonymousId(options: CookieAnonymousIdOptions): CookieAnonymousId {
|
|
46
50
|
const { cookieName, maxAgeSeconds = ONE_YEAR_IN_SECONDS } = options;
|
|
@@ -9,7 +9,7 @@ import type { TrackedEvent } from "#/core/tracked-event";
|
|
|
9
9
|
/**
|
|
10
10
|
* Context handed to {@link ClientTrackerOptions.onDeliveryError} for one failed delivery.
|
|
11
11
|
*
|
|
12
|
-
* @since
|
|
12
|
+
* @since 0.5.0-canary.6
|
|
13
13
|
*/
|
|
14
14
|
export interface DeliveryErrorContext {
|
|
15
15
|
destination: Destination;
|
|
@@ -62,6 +62,8 @@ function eraseInDestination(destination: Destination, id: string): void {
|
|
|
62
62
|
}
|
|
63
63
|
|
|
64
64
|
/**
|
|
65
|
+
* Options for `createClientTracker`.
|
|
66
|
+
*
|
|
65
67
|
* @since 0.5.0-canary.4
|
|
66
68
|
*/
|
|
67
69
|
export interface ClientTrackerOptions<Catalog extends EventCatalog> {
|
|
@@ -92,6 +94,8 @@ export interface ClientTrackerOptions<Catalog extends EventCatalog> {
|
|
|
92
94
|
}
|
|
93
95
|
|
|
94
96
|
/**
|
|
97
|
+
* A client-side tracker delivering catalog-validated events to destinations, plus erasure on withdrawal.
|
|
98
|
+
*
|
|
95
99
|
* @since 0.5.0-canary.4
|
|
96
100
|
*/
|
|
97
101
|
export interface ClientTracker<Catalog extends EventCatalog> {
|
|
@@ -108,6 +112,8 @@ export interface ClientTracker<Catalog extends EventCatalog> {
|
|
|
108
112
|
}
|
|
109
113
|
|
|
110
114
|
/**
|
|
115
|
+
* Creates a consent-gated tracker that validates each event against the catalog and fans it out to destinations.
|
|
116
|
+
*
|
|
111
117
|
* @since 0.5.0-canary.4
|
|
112
118
|
*/
|
|
113
119
|
export function createClientTracker<Catalog extends EventCatalog>(
|
|
@@ -5,7 +5,7 @@ import { isInitialConsent, STRICTEST_INITIAL_CONSENT } from "#/core/consent";
|
|
|
5
5
|
* External-store view of the visitor's region default — the strictest value until the
|
|
6
6
|
* server lane answers, then the resolved one.
|
|
7
7
|
*
|
|
8
|
-
* @since
|
|
8
|
+
* @since 0.5.0-canary.6
|
|
9
9
|
*/
|
|
10
10
|
export interface InitialConsentSnapshot {
|
|
11
11
|
/** The region-correct default once resolved; {@link STRICTEST_INITIAL_CONSENT} until then. */
|
|
@@ -19,7 +19,9 @@ export interface InitialConsentSnapshot {
|
|
|
19
19
|
}
|
|
20
20
|
|
|
21
21
|
/**
|
|
22
|
-
*
|
|
22
|
+
* Options for `createInitialConsentStore`.
|
|
23
|
+
*
|
|
24
|
+
* @since 0.5.0-canary.6
|
|
23
25
|
*/
|
|
24
26
|
export interface InitialConsentStoreOptions {
|
|
25
27
|
/**
|
|
@@ -40,7 +42,7 @@ export interface InitialConsentStoreOptions {
|
|
|
40
42
|
* `useSyncExternalStore`-shaped — pass `subscribe`/`getSnapshot`/`getServerSnapshot`
|
|
41
43
|
* straight through, or use the `useInitialConsent` hook from `@codefast/tracking/react`.
|
|
42
44
|
*
|
|
43
|
-
* @since
|
|
45
|
+
* @since 0.5.0-canary.6
|
|
44
46
|
*/
|
|
45
47
|
export interface InitialConsentStore {
|
|
46
48
|
/**
|
|
@@ -67,7 +69,7 @@ const SERVER_SNAPSHOT: InitialConsentSnapshot = {
|
|
|
67
69
|
* (consent UI still renders, under the strictest default), and a retry the next time the
|
|
68
70
|
* tab becomes visible — so one failed request never locks the whole SPA session.
|
|
69
71
|
*
|
|
70
|
-
* @since
|
|
72
|
+
* @since 0.5.0-canary.6
|
|
71
73
|
*/
|
|
72
74
|
export function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore {
|
|
73
75
|
const listeners = new Set<() => void>();
|
|
@@ -3,7 +3,9 @@ import { resolveEffectiveConsent } from "#/core/consent";
|
|
|
3
3
|
import type { ConsentConfig } from "#/core/consent-config";
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
6
|
+
* Options for `createIsAnalyticsAllowed`.
|
|
7
|
+
*
|
|
8
|
+
* @since 0.5.0-canary.6
|
|
7
9
|
*/
|
|
8
10
|
export interface IsAnalyticsAllowedOptions {
|
|
9
11
|
/** Must be the same object `useConsent` receives — one config, every surface. */
|
|
@@ -23,7 +25,7 @@ export interface IsAnalyticsAllowedOptions {
|
|
|
23
25
|
* Non-React mirror of `useConsent`'s `isAnalyticsAllowed` — pass the returned function as
|
|
24
26
|
* `createClientTracker({ isAnalyticsAllowed })` so the pipeline and the banner share one rule.
|
|
25
27
|
*
|
|
26
|
-
* @since
|
|
28
|
+
* @since 0.5.0-canary.6
|
|
27
29
|
*/
|
|
28
30
|
export function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean {
|
|
29
31
|
const { config, getMode, storage } = options;
|
|
@@ -3,7 +3,9 @@ import { createCookieAnonymousId } from "#/client/cookie-anonymous-id";
|
|
|
3
3
|
import { readCookieValue } from "#/core/cookie";
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
6
|
+
* Options for `createServerPersistedAnonymousId`.
|
|
7
|
+
*
|
|
8
|
+
* @since 0.5.0-canary.6
|
|
7
9
|
*/
|
|
8
10
|
export interface ServerPersistedAnonymousIdOptions {
|
|
9
11
|
/** Server round-trip that expires the cookie via `Set-Cookie` — the server half of `clear()`. */
|
|
@@ -28,7 +30,7 @@ export interface ServerPersistedAnonymousIdOptions {
|
|
|
28
30
|
* its full max-age. Same optimistic `document.cookie` write first, so the current event
|
|
29
31
|
* never waits on the round-trip and a failed `persist` degrades to today's behavior.
|
|
30
32
|
*
|
|
31
|
-
* @since
|
|
33
|
+
* @since 0.5.0-canary.6
|
|
32
34
|
*/
|
|
33
35
|
export function createServerPersistedAnonymousId(options: ServerPersistedAnonymousIdOptions): CookieAnonymousId {
|
|
34
36
|
const { clearOnServer, cookieName, maxAgeSeconds, persist } = options;
|
|
@@ -6,7 +6,7 @@ import type { ConsentCategory } from "#/core/consent";
|
|
|
6
6
|
* cross-surface "must match" contracts hold by construction instead of by hand-threading
|
|
7
7
|
* the same strings through every call site.
|
|
8
8
|
*
|
|
9
|
-
* @since
|
|
9
|
+
* @since 0.5.0-canary.6
|
|
10
10
|
*/
|
|
11
11
|
export interface ConsentConfig {
|
|
12
12
|
/** Bumping re-prompts every visitor — a stored decision under any other version is ignored. */
|
|
@@ -20,7 +20,7 @@ export interface ConsentConfig {
|
|
|
20
20
|
/**
|
|
21
21
|
* Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
|
|
22
22
|
*
|
|
23
|
-
* @since
|
|
23
|
+
* @since 0.5.0-canary.6
|
|
24
24
|
*/
|
|
25
25
|
export function defineConsentConfig<Config extends ConsentConfig>(config: Config): Config {
|
|
26
26
|
return config;
|
|
@@ -5,7 +5,7 @@ import { isConsentDecision } from "#/core/consent";
|
|
|
5
5
|
* Which consent event a receipt records. Receipts are append-only: an `update` or
|
|
6
6
|
* `withdraw` is a new receipt referencing the prior one, never a mutation.
|
|
7
7
|
*
|
|
8
|
-
* @since
|
|
8
|
+
* @since 0.5.0-canary.6
|
|
9
9
|
*/
|
|
10
10
|
export type ConsentReceiptEventType = "give" | "update" | "withdraw";
|
|
11
11
|
|
|
@@ -13,7 +13,7 @@ export type ConsentReceiptEventType = "give" | "update" | "withdraw";
|
|
|
13
13
|
* How the decision was expressed — the "how" dimension a demonstrable-consent record must
|
|
14
14
|
* capture (GDPR Art. 7(1); EDPB 05/2020 §5.1).
|
|
15
15
|
*
|
|
16
|
-
* @since
|
|
16
|
+
* @since 0.5.0-canary.6
|
|
17
17
|
*/
|
|
18
18
|
export type ConsentReceiptMethod = "banner-accept" | "banner-reject" | "granular" | "gpc-signal" | "withdrawal";
|
|
19
19
|
|
|
@@ -21,7 +21,7 @@ export type ConsentReceiptMethod = "banner-accept" | "banner-reject" | "granular
|
|
|
21
21
|
* What kind of identifier links the receipt to a subject. A cookie-only visitor uses a
|
|
22
22
|
* pseudonymous `cookie` id — the receipt is still valid proof.
|
|
23
23
|
*
|
|
24
|
-
* @since
|
|
24
|
+
* @since 0.5.0-canary.6
|
|
25
25
|
*/
|
|
26
26
|
export type ConsentReceiptSubjectIdType = "cookie" | "email-hash" | "userId";
|
|
27
27
|
|
|
@@ -29,7 +29,7 @@ export type ConsentReceiptSubjectIdType = "cookie" | "email-hash" | "userId";
|
|
|
29
29
|
* The caller-supplied fields of a consent receipt. Deliberately carries **no IP** — the
|
|
30
30
|
* server derives a coarsened one from the connection so a full IP never transits the body.
|
|
31
31
|
*
|
|
32
|
-
* @since
|
|
32
|
+
* @since 0.5.0-canary.6
|
|
33
33
|
*/
|
|
34
34
|
export interface ConsentReceiptInput {
|
|
35
35
|
decision: ConsentDecision;
|
|
@@ -55,7 +55,7 @@ export interface ConsentReceiptInput {
|
|
|
55
55
|
* The record is append-only; never mutate a stored receipt. `ipCoarse` is truncated at
|
|
56
56
|
* write time and MUST NOT be a full IP.
|
|
57
57
|
*
|
|
58
|
-
* @since
|
|
58
|
+
* @since 0.5.0-canary.6
|
|
59
59
|
*/
|
|
60
60
|
export interface ConsentReceipt extends ConsentReceiptInput {
|
|
61
61
|
/** Coarsened/pseudonymized IP, or absent — never a full address. */
|
|
@@ -86,7 +86,7 @@ const RECEIPT_SUBJECT_ID_TYPES: ReadonlySet<ConsentReceiptSubjectIdType> = new S
|
|
|
86
86
|
* Guards a receipt input received from an untrusted client. Rejects a body carrying an
|
|
87
87
|
* `ip`/`ipCoarse` field so a full address can never be persisted from caller input.
|
|
88
88
|
*
|
|
89
|
-
* @since
|
|
89
|
+
* @since 0.5.0-canary.6
|
|
90
90
|
*/
|
|
91
91
|
export function isConsentReceiptInput(value: unknown): value is ConsentReceiptInput {
|
|
92
92
|
if (typeof value !== "object" || value === null) {
|
package/src/core/consent.ts
CHANGED
|
@@ -1,23 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
+
* The privacy-law region a visitor's consent defaults are resolved for.
|
|
3
|
+
*
|
|
2
4
|
* @since 0.5.0-canary.4
|
|
3
5
|
*/
|
|
4
6
|
export type ConsentRegion = "eu" | "other" | "us" | "vn";
|
|
5
7
|
|
|
6
8
|
/**
|
|
7
|
-
*
|
|
9
|
+
* Every consent region, in a stable order shared by guards and iteration.
|
|
10
|
+
*
|
|
11
|
+
* @since 0.5.0-canary.6
|
|
8
12
|
*/
|
|
9
13
|
export const CONSENT_REGIONS: ReadonlyArray<ConsentRegion> = ["eu", "other", "us", "vn"];
|
|
10
14
|
|
|
11
15
|
/**
|
|
12
16
|
* Guards a region read from untrusted storage (a cached `InitialConsent`, a cookie).
|
|
13
17
|
*
|
|
14
|
-
* @since
|
|
18
|
+
* @since 0.5.0-canary.6
|
|
15
19
|
*/
|
|
16
20
|
export function isConsentRegion(value: unknown): value is ConsentRegion {
|
|
17
21
|
return CONSENT_REGIONS.includes(value as ConsentRegion);
|
|
18
22
|
}
|
|
19
23
|
|
|
20
24
|
/**
|
|
25
|
+
* Whether a region requires explicit opt-in before tracking or defaults to opt-out.
|
|
26
|
+
*
|
|
21
27
|
* @since 0.5.0-canary.4
|
|
22
28
|
*/
|
|
23
29
|
export type ConsentMode = "opt-in" | "opt-out";
|
|
@@ -53,6 +59,8 @@ export function resolveConsentMode(region: ConsentRegion): ConsentMode {
|
|
|
53
59
|
export type ConsentCategory = "ads" | "analytics";
|
|
54
60
|
|
|
55
61
|
/**
|
|
62
|
+
* Every consent category, in a stable order shared by guards and iteration.
|
|
63
|
+
*
|
|
56
64
|
* @since 0.5.0-canary.4
|
|
57
65
|
*/
|
|
58
66
|
export const CONSENT_CATEGORIES: ReadonlyArray<ConsentCategory> = ["ads", "analytics"];
|
|
@@ -92,7 +100,7 @@ export function isConsentDecision(value: unknown): value is ConsentDecision {
|
|
|
92
100
|
* dropped, every category becomes an explicit boolean. The one normalization rule every
|
|
93
101
|
* reader of stored consent shares (e.g. `readStoredDecision`).
|
|
94
102
|
*
|
|
95
|
-
* @since
|
|
103
|
+
* @since 0.5.0-canary.6
|
|
96
104
|
*/
|
|
97
105
|
export function normalizeConsentDecision(decision: ConsentDecision): ConsentDecision {
|
|
98
106
|
return createConsentDecision(CONSENT_CATEGORIES.filter((category) => decision[category]));
|
|
@@ -101,7 +109,7 @@ export function normalizeConsentDecision(decision: ConsentDecision): ConsentDeci
|
|
|
101
109
|
/**
|
|
102
110
|
* Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
|
|
103
111
|
*
|
|
104
|
-
* @since
|
|
112
|
+
* @since 0.5.0-canary.6
|
|
105
113
|
*/
|
|
106
114
|
export function isConsentRecord(value: unknown): value is ConsentRecord {
|
|
107
115
|
return (
|
|
@@ -113,7 +121,9 @@ export function isConsentRecord(value: unknown): value is ConsentRecord {
|
|
|
113
121
|
}
|
|
114
122
|
|
|
115
123
|
/**
|
|
116
|
-
*
|
|
124
|
+
* Options for `resolveDefaultConsent`.
|
|
125
|
+
*
|
|
126
|
+
* @since 0.5.0-canary.6
|
|
117
127
|
*/
|
|
118
128
|
export interface ResolveDefaultConsentOptions {
|
|
119
129
|
/** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
|
|
@@ -157,7 +167,7 @@ export function resolveDefaultConsent(options: ResolveDefaultConsentOptions): Co
|
|
|
157
167
|
* `defaultConsent` is the server snapshot — useful when you need request-time `sec-gpc`
|
|
158
168
|
* as-is; analytics-only apps can ignore it because GPC only forces `ads` denied.
|
|
159
169
|
*
|
|
160
|
-
* @since
|
|
170
|
+
* @since 0.5.0-canary.6
|
|
161
171
|
*/
|
|
162
172
|
export interface InitialConsent {
|
|
163
173
|
defaultConsent: ConsentDecision;
|
|
@@ -171,7 +181,7 @@ export interface InitialConsent {
|
|
|
171
181
|
* Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
|
|
172
182
|
* header means "unknown visitor", never "known non-EU visitor".
|
|
173
183
|
*
|
|
174
|
-
* @since
|
|
184
|
+
* @since 0.5.0-canary.6
|
|
175
185
|
*/
|
|
176
186
|
export const STRICTEST_INITIAL_CONSENT: InitialConsent = Object.freeze({
|
|
177
187
|
defaultConsent: Object.freeze(createConsentDecision([])),
|
|
@@ -185,7 +195,7 @@ export const STRICTEST_INITIAL_CONSENT: InitialConsent = Object.freeze({
|
|
|
185
195
|
* {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
|
|
186
196
|
* mode, never looser.
|
|
187
197
|
*
|
|
188
|
-
* @since
|
|
198
|
+
* @since 0.5.0-canary.6
|
|
189
199
|
*/
|
|
190
200
|
export function isInitialConsent(value: unknown): value is InitialConsent {
|
|
191
201
|
if (!isPlainObject(value)) {
|
|
@@ -244,7 +254,7 @@ export interface ConsentStorage {
|
|
|
244
254
|
* any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
|
|
245
255
|
* it was recorded under a superseded policy version.
|
|
246
256
|
*
|
|
247
|
-
* @since
|
|
257
|
+
* @since 0.5.0-canary.6
|
|
248
258
|
*/
|
|
249
259
|
export function readStoredDecision(storage: ConsentStorage, policyVersion: string): ConsentDecision | undefined {
|
|
250
260
|
const record = storage.load();
|
|
@@ -257,7 +267,9 @@ export function readStoredDecision(storage: ConsentStorage, policyVersion: strin
|
|
|
257
267
|
}
|
|
258
268
|
|
|
259
269
|
/**
|
|
260
|
-
*
|
|
270
|
+
* Options for `resolveEffectiveConsent`.
|
|
271
|
+
*
|
|
272
|
+
* @since 0.5.0-canary.6
|
|
261
273
|
*/
|
|
262
274
|
export interface ResolveEffectiveConsentOptions {
|
|
263
275
|
/** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
|
|
@@ -274,7 +286,7 @@ export interface ResolveEffectiveConsentOptions {
|
|
|
274
286
|
* non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
|
|
275
287
|
* "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
|
|
276
288
|
*
|
|
277
|
-
* @since
|
|
289
|
+
* @since 0.5.0-canary.6
|
|
278
290
|
*/
|
|
279
291
|
export function resolveEffectiveConsent(options: ResolveEffectiveConsentOptions): ConsentDecision {
|
|
280
292
|
const { hasGlobalPrivacyControlSignal, mode, policyVersion, requestedCategories, storage } = options;
|
package/src/core/cookie.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Default lifetime shared by the anonymous-id and consent cookies — one year.
|
|
3
3
|
*
|
|
4
|
-
* @since
|
|
4
|
+
* @since 0.5.0-canary.6
|
|
5
5
|
*/
|
|
6
6
|
export const ONE_YEAR_IN_SECONDS: number = 60 * 60 * 24 * 365;
|
|
7
7
|
|
|
@@ -10,7 +10,7 @@ export const ONE_YEAR_IN_SECONDS: number = 60 * 60 * 24 * 365;
|
|
|
10
10
|
* `document.cookie`, which share the `name=value; name2=value2` wire format — or
|
|
11
11
|
* `undefined` when absent. The name must match exactly; a longer prefix sibling is ignored.
|
|
12
12
|
*
|
|
13
|
-
* @since
|
|
13
|
+
* @since 0.5.0-canary.6
|
|
14
14
|
*/
|
|
15
15
|
export function readCookieValue(cookieString: string | null | undefined, cookieName: string): string | undefined {
|
|
16
16
|
if (!cookieString) {
|
|
@@ -35,7 +35,7 @@ export function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalo
|
|
|
35
35
|
* @throws Error when validation reports issues, or when the schema validates asynchronously —
|
|
36
36
|
* tracking sits on synchronous call paths, so async schemas are unsupported by design.
|
|
37
37
|
*
|
|
38
|
-
* @since
|
|
38
|
+
* @since 0.5.0-canary.6
|
|
39
39
|
*/
|
|
40
40
|
export function assertValidEventProperties(schema: StandardSchemaV1, eventName: string, properties: unknown): unknown {
|
|
41
41
|
const result = schema["~standard"].validate(properties);
|
|
@@ -7,7 +7,7 @@ import type { ConsentDecision } from "#/core/consent";
|
|
|
7
7
|
* restricts to LDU but MUST NOT withhold first-party `analytics` (spec-consent §3). Every
|
|
8
8
|
* ad destination consumes this same shape so per-vendor mappings cannot drift.
|
|
9
9
|
*
|
|
10
|
-
* @since
|
|
10
|
+
* @since 0.5.0-canary.6
|
|
11
11
|
*/
|
|
12
12
|
export interface AdConsentState {
|
|
13
13
|
/** `ads` denied → the platform must restrict to Limited Data Use (Meta/TikTok LDU, UET `ad_storage` denied). */
|
|
@@ -19,7 +19,7 @@ export interface AdConsentState {
|
|
|
19
19
|
/**
|
|
20
20
|
* Normalizes a package `ConsentDecision` to the vendor-agnostic {@link AdConsentState}.
|
|
21
21
|
*
|
|
22
|
-
* @since
|
|
22
|
+
* @since 0.5.0-canary.6
|
|
23
23
|
*/
|
|
24
24
|
export function toAdConsentState(decision: ConsentDecision): AdConsentState {
|
|
25
25
|
return {
|