@codefast/tracking 0.5.0-canary.4 → 0.5.0-canary.6

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.
Files changed (277) hide show
  1. package/CHANGELOG.md +473 -0
  2. package/README.md +177 -95
  3. package/dist/adapters/tanstack-start.d.ts +80 -0
  4. package/dist/adapters/tanstack-start.d.ts.map +1 -0
  5. package/dist/adapters/tanstack-start.js +74 -0
  6. package/dist/adapters/tanstack-start.js.map +1 -0
  7. package/dist/client/ad-framework-consent.d.ts +62 -0
  8. package/dist/client/ad-framework-consent.d.ts.map +1 -0
  9. package/dist/client/ad-framework-consent.js +40 -0
  10. package/dist/client/ad-framework-consent.js.map +1 -0
  11. package/dist/client/browser-cookie.d.ts +9 -0
  12. package/dist/client/browser-cookie.d.ts.map +1 -0
  13. package/dist/client/browser-cookie.js +15 -0
  14. package/dist/client/browser-cookie.js.map +1 -0
  15. package/dist/client/consent-runtime.d.ts +53 -0
  16. package/dist/client/consent-runtime.d.ts.map +1 -0
  17. package/dist/client/consent-runtime.js +33 -0
  18. package/dist/client/consent-runtime.js.map +1 -0
  19. package/dist/client/{consent-storage.d.mts → consent-storage.d.ts} +8 -6
  20. package/dist/client/consent-storage.d.ts.map +1 -0
  21. package/dist/client/consent-storage.js +109 -0
  22. package/dist/client/consent-storage.js.map +1 -0
  23. package/dist/client/consent-withdrawal.d.ts +18 -0
  24. package/dist/client/consent-withdrawal.d.ts.map +1 -0
  25. package/dist/client/consent-withdrawal.js +17 -0
  26. package/dist/client/consent-withdrawal.js.map +1 -0
  27. package/dist/client/cookie-anonymous-id.d.ts +41 -0
  28. package/dist/client/cookie-anonymous-id.d.ts.map +1 -0
  29. package/dist/client/cookie-anonymous-id.js +65 -0
  30. package/dist/client/cookie-anonymous-id.js.map +1 -0
  31. package/dist/client/create-client-tracker.d.ts +60 -0
  32. package/dist/client/create-client-tracker.d.ts.map +1 -0
  33. package/dist/client/create-client-tracker.js +91 -0
  34. package/dist/client/create-client-tracker.js.map +1 -0
  35. package/dist/client/gpc.d.ts +10 -0
  36. package/dist/client/gpc.d.ts.map +1 -0
  37. package/dist/client/gpc.js +12 -0
  38. package/dist/client/gpc.js.map +1 -0
  39. package/dist/client/initial-consent-store.d.ts +63 -0
  40. package/dist/client/initial-consent-store.d.ts.map +1 -0
  41. package/dist/client/initial-consent-store.js +138 -0
  42. package/dist/client/initial-consent-store.js.map +1 -0
  43. package/dist/client/is-analytics-allowed.d.ts +26 -0
  44. package/dist/client/is-analytics-allowed.d.ts.map +1 -0
  45. package/dist/client/is-analytics-allowed.js +22 -0
  46. package/dist/client/is-analytics-allowed.js.map +1 -0
  47. package/dist/client/server-persisted-anonymous-id.d.ts +30 -0
  48. package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -0
  49. package/dist/client/server-persisted-anonymous-id.js +72 -0
  50. package/dist/client/server-persisted-anonymous-id.js.map +1 -0
  51. package/dist/core/consent-config.d.ts +24 -0
  52. package/dist/core/consent-config.d.ts.map +1 -0
  53. package/dist/core/consent-config.js +9 -0
  54. package/dist/core/consent-config.js.map +1 -0
  55. package/dist/core/consent-receipt.d.ts +71 -0
  56. package/dist/core/consent-receipt.d.ts.map +1 -0
  57. package/dist/core/consent-receipt.js +39 -0
  58. package/dist/core/consent-receipt.js.map +1 -0
  59. package/dist/core/consent.d.ts +182 -0
  60. package/dist/core/consent.d.ts.map +1 -0
  61. package/dist/core/consent.js +159 -0
  62. package/dist/core/consent.js.map +1 -0
  63. package/dist/core/cookie.d.ts +15 -0
  64. package/dist/core/cookie.d.ts.map +1 -0
  65. package/dist/core/cookie.js +26 -0
  66. package/dist/core/cookie.js.map +1 -0
  67. package/dist/core/destination.d.ts +29 -0
  68. package/dist/core/destination.d.ts.map +1 -0
  69. package/dist/core/destination.js +2 -0
  70. package/dist/core/destination.js.map +1 -0
  71. package/dist/core/event-catalog.d.ts +35 -0
  72. package/dist/core/event-catalog.d.ts.map +1 -0
  73. package/dist/core/event-catalog.js +30 -0
  74. package/dist/core/event-catalog.js.map +1 -0
  75. package/dist/core/event-id.d.ts +7 -0
  76. package/dist/core/event-id.d.ts.map +1 -0
  77. package/dist/core/event-id.js +9 -0
  78. package/dist/core/event-id.js.map +1 -0
  79. package/dist/core/tracked-event.d.ts +15 -0
  80. package/dist/core/tracked-event.d.ts.map +1 -0
  81. package/dist/core/tracked-event.js +2 -0
  82. package/dist/core/tracked-event.js.map +1 -0
  83. package/dist/destinations/ad-consent.d.ts +23 -0
  84. package/dist/destinations/ad-consent.d.ts.map +1 -0
  85. package/dist/destinations/ad-consent.js +12 -0
  86. package/dist/destinations/ad-consent.js.map +1 -0
  87. package/dist/destinations/google-analytics.d.ts +148 -0
  88. package/dist/destinations/google-analytics.d.ts.map +1 -0
  89. package/dist/destinations/google-analytics.js +156 -0
  90. package/dist/destinations/google-analytics.js.map +1 -0
  91. package/dist/destinations/google-consent.d.ts +62 -0
  92. package/dist/destinations/google-consent.d.ts.map +1 -0
  93. package/dist/destinations/google-consent.js +109 -0
  94. package/dist/destinations/google-consent.js.map +1 -0
  95. package/dist/destinations/meta.d.ts +63 -0
  96. package/dist/destinations/meta.d.ts.map +1 -0
  97. package/dist/destinations/meta.js +44 -0
  98. package/dist/destinations/meta.js.map +1 -0
  99. package/dist/destinations/microsoft-uet.d.ts +56 -0
  100. package/dist/destinations/microsoft-uet.d.ts.map +1 -0
  101. package/dist/destinations/microsoft-uet.js +41 -0
  102. package/dist/destinations/microsoft-uet.js.map +1 -0
  103. package/dist/destinations/shared.d.ts +18 -0
  104. package/dist/destinations/shared.d.ts.map +1 -0
  105. package/dist/destinations/shared.js +19 -0
  106. package/dist/destinations/shared.js.map +1 -0
  107. package/dist/destinations/tiktok.d.ts +55 -0
  108. package/dist/destinations/tiktok.d.ts.map +1 -0
  109. package/dist/destinations/tiktok.js +40 -0
  110. package/dist/destinations/tiktok.js.map +1 -0
  111. package/dist/destinations/vercel-analytics.d.ts +25 -0
  112. package/dist/destinations/vercel-analytics.d.ts.map +1 -0
  113. package/dist/destinations/vercel-analytics.js +23 -0
  114. package/dist/destinations/vercel-analytics.js.map +1 -0
  115. package/dist/index.d.ts +64 -0
  116. package/dist/index.d.ts.map +1 -0
  117. package/dist/index.js +41 -0
  118. package/dist/index.js.map +1 -0
  119. package/dist/react/consent-banner.d.ts +155 -0
  120. package/dist/react/consent-banner.d.ts.map +1 -0
  121. package/dist/react/consent-banner.js +171 -0
  122. package/dist/react/consent-banner.js.map +1 -0
  123. package/dist/react/gtag-consent-bootstrap.d.ts +17 -0
  124. package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -0
  125. package/dist/react/gtag-consent-bootstrap.js +22 -0
  126. package/dist/react/gtag-consent-bootstrap.js.map +1 -0
  127. package/dist/react/use-consent.d.ts +42 -0
  128. package/dist/react/use-consent.d.ts.map +1 -0
  129. package/dist/react/use-consent.js +60 -0
  130. package/dist/react/use-consent.js.map +1 -0
  131. package/dist/react/use-google-consent-sync.d.ts +20 -0
  132. package/dist/react/use-google-consent-sync.d.ts.map +1 -0
  133. package/dist/react/use-google-consent-sync.js +22 -0
  134. package/dist/react/use-google-consent-sync.js.map +1 -0
  135. package/dist/react/use-initial-consent.d.ts +11 -0
  136. package/dist/react/use-initial-consent.d.ts.map +1 -0
  137. package/dist/react/use-initial-consent.js +18 -0
  138. package/dist/react/use-initial-consent.js.map +1 -0
  139. package/dist/server/anonymous-id-cookie.d.ts +67 -0
  140. package/dist/server/anonymous-id-cookie.d.ts.map +1 -0
  141. package/dist/server/anonymous-id-cookie.js +71 -0
  142. package/dist/server/anonymous-id-cookie.js.map +1 -0
  143. package/dist/server/consent-receipt-store.d.ts +56 -0
  144. package/dist/server/consent-receipt-store.d.ts.map +1 -0
  145. package/dist/server/consent-receipt-store.js +44 -0
  146. package/dist/server/consent-receipt-store.js.map +1 -0
  147. package/dist/server/consent-receipt.d.ts +41 -0
  148. package/dist/server/consent-receipt.d.ts.map +1 -0
  149. package/dist/server/consent-receipt.js +60 -0
  150. package/dist/server/consent-receipt.js.map +1 -0
  151. package/dist/server/initial-consent.d.ts +26 -0
  152. package/dist/server/initial-consent.d.ts.map +1 -0
  153. package/dist/server/initial-consent.js +31 -0
  154. package/dist/server/initial-consent.js.map +1 -0
  155. package/dist/server/measurement-protocol.d.ts +69 -0
  156. package/dist/server/measurement-protocol.d.ts.map +1 -0
  157. package/dist/server/measurement-protocol.js +61 -0
  158. package/dist/server/measurement-protocol.js.map +1 -0
  159. package/dist/server/region.d.ts +27 -0
  160. package/dist/server/region.d.ts.map +1 -0
  161. package/dist/server/region.js +69 -0
  162. package/dist/server/region.js.map +1 -0
  163. package/dist/server/user-deletion.d.ts +64 -0
  164. package/dist/server/user-deletion.d.ts.map +1 -0
  165. package/dist/server/user-deletion.js +54 -0
  166. package/dist/server/user-deletion.js.map +1 -0
  167. package/dist/tooling/import-protection.d.ts +19 -0
  168. package/dist/tooling/import-protection.d.ts.map +1 -0
  169. package/dist/tooling/import-protection.js +23 -0
  170. package/dist/tooling/import-protection.js.map +1 -0
  171. package/package.json +202 -107
  172. package/src/adapters/tanstack-start.ts +135 -0
  173. package/src/client/ad-framework-consent.ts +86 -0
  174. package/src/client/browser-cookie.ts +16 -0
  175. package/src/client/consent-runtime.ts +80 -0
  176. package/src/client/consent-storage.ts +31 -1
  177. package/src/client/consent-withdrawal.ts +32 -0
  178. package/src/client/cookie-anonymous-id.ts +112 -0
  179. package/src/client/create-client-tracker.ts +128 -86
  180. package/src/client/gpc.ts +4 -2
  181. package/src/client/initial-consent-store.ts +218 -0
  182. package/src/client/is-analytics-allowed.ts +43 -0
  183. package/src/client/server-persisted-anonymous-id.ts +102 -0
  184. package/src/core/consent-config.ts +27 -0
  185. package/src/core/consent-receipt.ts +115 -0
  186. package/src/core/consent.ts +164 -10
  187. package/src/core/cookie.ts +29 -0
  188. package/src/core/destination.ts +17 -8
  189. package/src/core/event-catalog.ts +29 -15
  190. package/src/core/event-id.ts +1 -2
  191. package/src/core/tracked-event.ts +4 -4
  192. package/src/css/consent.css +119 -0
  193. package/src/destinations/ad-consent.ts +29 -0
  194. package/src/destinations/google-analytics.ts +196 -133
  195. package/src/destinations/google-consent.ts +164 -0
  196. package/src/destinations/meta.ts +96 -0
  197. package/src/destinations/microsoft-uet.ts +86 -0
  198. package/src/destinations/shared.ts +45 -0
  199. package/src/destinations/tiktok.ts +85 -0
  200. package/src/destinations/vercel-analytics.ts +23 -24
  201. package/src/index.ts +165 -8
  202. package/src/react/consent-banner.tsx +308 -111
  203. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  204. package/src/react/use-consent.ts +53 -45
  205. package/src/react/use-google-consent-sync.ts +38 -0
  206. package/src/react/use-initial-consent.ts +22 -0
  207. package/src/server/anonymous-id-cookie.ts +103 -0
  208. package/src/server/consent-receipt-store.ts +79 -0
  209. package/src/server/consent-receipt.ts +89 -0
  210. package/src/server/initial-consent.ts +46 -0
  211. package/src/server/measurement-protocol.ts +114 -0
  212. package/src/server/region.ts +22 -15
  213. package/src/server/user-deletion.ts +93 -0
  214. package/src/tooling/import-protection.ts +22 -0
  215. package/dist/client/consent-storage.mjs +0 -63
  216. package/dist/client/create-client-tracker.d.mts +0 -37
  217. package/dist/client/create-client-tracker.mjs +0 -66
  218. package/dist/client/gpc.d.mts +0 -10
  219. package/dist/client/gpc.mjs +0 -12
  220. package/dist/client/index.d.mts +0 -8
  221. package/dist/client/index.mjs +0 -8
  222. package/dist/client/lifecycle.d.mts +0 -23
  223. package/dist/client/lifecycle.mjs +0 -30
  224. package/dist/client/local-storage.d.mts +0 -13
  225. package/dist/client/local-storage.mjs +0 -31
  226. package/dist/client/queue.d.mts +0 -49
  227. package/dist/client/queue.mjs +0 -71
  228. package/dist/client/router.d.mts +0 -30
  229. package/dist/client/router.mjs +0 -17
  230. package/dist/core/consent.d.mts +0 -89
  231. package/dist/core/consent.mjs +0 -57
  232. package/dist/core/destination.d.mts +0 -23
  233. package/dist/core/destination.mjs +0 -1
  234. package/dist/core/event-catalog.d.mts +0 -36
  235. package/dist/core/event-catalog.mjs +0 -12
  236. package/dist/core/event-id.d.mts +0 -10
  237. package/dist/core/event-id.mjs +0 -12
  238. package/dist/core/index.d.mts +0 -6
  239. package/dist/core/index.mjs +0 -4
  240. package/dist/core/tracked-event.d.mts +0 -17
  241. package/dist/core/tracked-event.mjs +0 -1
  242. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  243. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  244. package/dist/destinations/google-analytics.d.mts +0 -98
  245. package/dist/destinations/google-analytics.mjs +0 -126
  246. package/dist/destinations/http-destination.d.mts +0 -20
  247. package/dist/destinations/http-destination.mjs +0 -25
  248. package/dist/destinations/index.d.mts +0 -5
  249. package/dist/destinations/index.mjs +0 -5
  250. package/dist/destinations/vercel-analytics.d.mts +0 -13
  251. package/dist/destinations/vercel-analytics.mjs +0 -30
  252. package/dist/index.d.mts +0 -6
  253. package/dist/index.mjs +0 -4
  254. package/dist/react/consent-banner.d.mts +0 -75
  255. package/dist/react/consent-banner.mjs +0 -114
  256. package/dist/react/index.d.mts +0 -3
  257. package/dist/react/index.mjs +0 -3
  258. package/dist/react/use-consent.d.mts +0 -49
  259. package/dist/react/use-consent.mjs +0 -54
  260. package/dist/server/create-server-tracker.d.mts +0 -42
  261. package/dist/server/create-server-tracker.mjs +0 -67
  262. package/dist/server/index.d.mts +0 -3
  263. package/dist/server/index.mjs +0 -3
  264. package/dist/server/region.d.mts +0 -20
  265. package/dist/server/region.mjs +0 -56
  266. package/src/client/index.ts +0 -17
  267. package/src/client/lifecycle.ts +0 -50
  268. package/src/client/local-storage.ts +0 -44
  269. package/src/client/queue.ts +0 -117
  270. package/src/client/router.ts +0 -37
  271. package/src/core/index.ts +0 -24
  272. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  273. package/src/destinations/http-destination.ts +0 -33
  274. package/src/destinations/index.ts +0 -20
  275. package/src/react/index.ts +0 -5
  276. package/src/server/create-server-tracker.ts +0 -128
  277. package/src/server/index.ts +0 -4
package/README.md CHANGED
@@ -1,128 +1,210 @@
1
1
  # @codefast/tracking
2
2
 
3
- Fullstack, type-safe event tracking for TanStack Start apps. Each app defines its own Zod
4
- event catalog tagged with an owner (`"client"` or `"server"`); trackers built from that
5
- catalog only allow firing events owned by that side — enforced at compile time.
3
+ Consent-gated, type-safe event tracking for TanStack Start apps.
6
4
 
7
- See [SPEC.md](./SPEC.md) for the full design (identity correlation, offline queue/retry,
8
- multi-destination fan-out, region-based consent).
5
+ [![npm version](https://img.shields.io/npm/v/@codefast/tracking)](https://www.npmjs.com/package/@codefast/tracking)
6
+ [![license](https://img.shields.io/npm/l/@codefast/tracking)](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
7
+
8
+ - **One catalog, typed end to end** — apps define their events over any
9
+ [Standard Schema](https://standardschema.dev) library (zod, `zod/mini`, valibot, ...);
10
+ `track()` validates properties at the call site and at runtime, and the client bundle
11
+ only pays for the schema library the app already ships.
12
+ - **One consent config, every surface** — `ConsentConfig` is the single bag for the
13
+ storage key, policy version, and requested purposes; the React hooks, the tracker gate,
14
+ and the pre-hydration gtag bootstrap all take the same object, so nothing drifts.
15
+ - **ISR-safe by design** — shared/CDN-cached HTML bakes the strictest consent default;
16
+ the region-correct default arrives per visitor over a private server-function lane.
9
17
 
10
18
  ## Status
11
19
 
12
- Early scaffold. `core`, `client`, `server`, and `react` (headless consent) implement the
13
- shapes described in the spec. `createVercelAnalyticsDestination`,
14
- `createGoogleAnalyticsDestination`, and `createGa4MeasurementProtocolDestination` are
15
- implemented; PostHog is not built yet — use `createHttpDestination` or implement the
16
- `Destination` interface directly.
20
+ Pre-1.0 (canary). The surface is deliberately small: it covers exactly what a consented
21
+ gtag + Vercel Analytics setup on TanStack Start needs, and nothing speculative. Lanes
22
+ that shipped here before (offline queue, beacon relay, server-side tracker, GTM,
23
+ Segment-style `identify`/`group`/`alias`/`page`) were removed because no consumer called
24
+ them — git history has them if a real need returns.
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pnpm add @codefast/tracking
30
+ ```
31
+
32
+ Every peer is optional and only needed by the surface that uses it: `react`/`react-dom`
33
+ (>= 19) for `/react`, `@tanstack/react-start` (>= 1.168) for `/adapters/tanstack-start`, and
34
+ `@vercel/analytics` for the Vercel destination.
17
35
 
18
- ## Quick start
36
+ ## Quick Start
19
37
 
20
38
  ```ts
21
- import { defineEventCatalog } from "@codefast/tracking";
22
- import { createClientTracker, createLocalStorageQueueStorage } from "@codefast/tracking/client";
23
- import { createHttpDestination } from "@codefast/tracking/destinations";
24
- import { z } from "zod";
39
+ // consent.ts — the one consent contract every surface shares
40
+ import { defineConsentConfig } from "@codefast/tracking";
25
41
 
26
- export const catalog = defineEventCatalog({
27
- button_clicked: { owner: "client", schema: z.object({ id: z.string() }) },
28
- order_completed: { owner: "server", schema: z.object({ orderId: z.string(), amount: z.number() }) },
42
+ export const consentConfig = defineConsentConfig({
43
+ policyVersion: "2026-01", // bump to re-prompt everyone
44
+ requestedCategories: ["analytics"],
45
+ storageKey: "my-app-consent",
29
46
  });
47
+ ```
30
48
 
31
- const tracker = createClientTracker({
32
- anonymousId: crypto.randomUUID(),
33
- catalog,
34
- destinations: [createHttpDestination({ name: "internal", endpoint: "/api/events" })],
35
- storage: createLocalStorageQueueStorage("tracking-queue"),
36
- });
49
+ ```ts
50
+ // consent-runtime.ts — live client instances derived from the config
51
+ import { createConsentRuntime } from "@codefast/tracking/client/consent-runtime";
52
+
53
+ import { consentConfig } from "./consent";
54
+ import { resolveVisitorConsent } from "./resolve-visitor-consent"; // server fn, see below
37
55
 
38
- tracker.track("button_clicked", { id: "cta" });
39
- // tracker.track("order_completed", { orderId: "o1", amount: 10 }); // compile error — server-owned
56
+ export const consentRuntime = createConsentRuntime({
57
+ config: consentConfig,
58
+ initialConsentSessionStorageKey: "my-app-initial-consent",
59
+ resolveInitialConsent: () => resolveVisitorConsent(),
60
+ });
40
61
  ```
41
62
 
42
63
  ```ts
43
- import { createServerTracker } from "@codefast/tracking/server";
64
+ // tracking.ts — catalog + tracker
65
+ import { defineEventCatalog } from "@codefast/tracking";
66
+ import { createClientTracker } from "@codefast/tracking/client/create-client-tracker";
67
+ import { createGoogleAnalyticsDestination } from "@codefast/tracking/destinations/google-analytics";
68
+ import { createVercelAnalyticsDestination } from "@codefast/tracking/destinations/vercel-analytics";
69
+ import * as z from "zod/mini";
70
+
71
+ import { consentRuntime } from "./consent-runtime";
72
+
73
+ export const catalog = defineEventCatalog({
74
+ copy_code: { schema: z.object({ name: z.string() }) },
75
+ });
44
76
 
45
- const serverTracker = createServerTracker({
77
+ export const tracker = createClientTracker({
78
+ anonymousId: () => "...", // see the durable anonymous id section
46
79
  catalog,
47
80
  destinations: [
48
- /* ... */
81
+ // Vercel is cookieless and receives no identifier — it may keep counting pre-consent.
82
+ createVercelAnalyticsDestination({ consentRequirement: "exempt" }),
83
+ createGoogleAnalyticsDestination(),
49
84
  ],
85
+ isAnalyticsAllowed: consentRuntime.isAnalyticsAllowed,
50
86
  });
51
87
 
52
- await serverTracker.track("order_completed", { orderId: "o1", amount: 10 }, { anonymousId, userId });
88
+ tracker.track("copy_code", { name: "button" }); // typed + runtime-validated
53
89
  ```
54
90
 
55
- ## Router page views + unload flush
91
+ Destinations own their transport (gtag.js and Vercel both batch in-page), so `track()`
92
+ is fire-and-forget — a failing destination can never break the interaction.
93
+
94
+ ## Event catalog
95
+
96
+ The package ships no events and no schema library — every app builds its own catalog
97
+ with `defineEventCatalog` over whatever Standard Schema validator it already uses.
98
+ `track()` infers both the event name and its properties from the catalog, then validates
99
+ the properties at runtime; a mismatch throws at the call site. Async schemas are rejected
100
+ by design — tracking sits on synchronous call paths.
101
+
102
+ ## Subpaths
103
+
104
+ The root `@codefast/tracking` is the **client entry**: it re-exports the isomorphic core
105
+ (catalog types, `Destination`, consent model + config) plus the whole browser-side surface
106
+ (tracker, consent runtime, React bindings, and the client destinations). Server-only lanes
107
+ are their own subpaths and are never re-exported from the root:
108
+
109
+ - `@codefast/tracking` — client entry: core + `createClientTracker`, `createConsentRuntime`,
110
+ the `useConsent`/`ConsentBanner`/`GtagConsentBootstrap` React bindings, the gtag +
111
+ ad-network destinations.
112
+ - `@codefast/tracking/destinations/vercel-analytics` — its own subpath so its
113
+ `@vercel/analytics` peer is only pulled in when used.
114
+ - `@codefast/tracking/server/*` — request-scoped, **server-only**: `server/initial-consent`,
115
+ `server/consent-receipt-store`, `server/measurement-protocol`, … (server code imports the
116
+ core it needs from `@codefast/tracking/core/*`, never from the client root).
117
+ - `@codefast/tracking/adapters/tanstack-start` — request/response glue over Start's server
118
+ context, **server-only**.
119
+ - `@codefast/tracking/tooling/import-protection` — `SERVER_ONLY_SUBPATHS` deny-list for
120
+ client bundles.
121
+ - `@codefast/tracking/css/consent.css` — optional plain-CSS theme for the consent banner.
122
+
123
+ Every built module is also its own subpath (e.g. `@codefast/tracking/client/gpc`) for
124
+ granular imports. Server-only lanes (`server/*`, `adapters/*`) must never enter a client
125
+ bundle — feed `SERVER_ONLY_SUBPATHS` to the framework's import-protection (see below). There
126
+ is deliberately no server-side tracker: destinations batch in-page, and the server half of
127
+ the package is consent resolution plus cookie persistence.
56
128
 
57
- `attachRouterPageTracking` is duck-typed against `Router["subscribe"]`, so it takes a real
58
- `@tanstack/react-router` instance without this package depending on it. `attachClientLifecycle`
59
- wires the periodic flush and the `sendBeacon` unload flush — `EventQueue` itself already
60
- auto-flushes once a batch hits its size threshold.
129
+ ## Consent (region-based, per-category)
130
+
131
+ `ConsentDecision` is per-purpose (`{ ads, analytics }`), mirroring Google Consent Mode
132
+ v2. Region resolves the mode: GDPR (EU, plus UK/EEA-EFTA equivalents) and Vietnam's PDPL
133
+ get **opt-in**; the US (CCPA/CPRA) and unrecognized regions get **opt-out**, with GPC
134
+ honored as an ads-only opt-out. Stored records are policy-versioned and shape-checked —
135
+ a malformed or legacy-shaped record re-prompts instead of silently deciding.
136
+
137
+ - `useConsent({ config, mode, storage })` — `useSyncExternalStore` bridge over the stored
138
+ decision; cross-tab saves sync through the `storage` event.
139
+ - `ConsentBanner` + parts (`Title`/`Description`/`Actions`/`Accept`/`Reject`/`Customize`/
140
+ `Preferences`/`Category`/`Save`) — headless, `data-slot`-styleable; optional plain-CSS
141
+ theme at `@codefast/tracking/css/consent.css`. `ConsentToggle` is the persistent
142
+ opt-out control CCPA requires.
143
+ - `useGoogleConsentSync(consent, { loadGtagScript? })` — pushes Consent Mode `update`
144
+ signals, including privacy-page and cross-tab decisions.
145
+ - `createConsentWithdrawalHandler({ clearAnonymousId?, clearGoogleAnalyticsCookies? })` —
146
+ wire to `onDecision` so a denial clears first-party identifiers.
147
+
148
+ ### The ISR lane
149
+
150
+ ISR/CDN-cached HTML is shared across visitors, so no render may read geo. Bake
151
+ `STRICTEST_INITIAL_CONSENT` into the shared render (and into `<GtagConsentBootstrap />`),
152
+ then resolve the region-correct default per visitor after hydration:
153
+
154
+ 1. **Server function** — `resolveInitialConsentFromRequest({ requestedCategories })`
155
+ (`@codefast/tracking/adapters/tanstack-start`) reads the geo header and `sec-gpc`, stamps
156
+ `cache-control: private, no-store`, and fails closed when geo is missing.
157
+ 2. **Client** — `createConsentRuntime` owns the rest: strictest default until the server
158
+ answers, single-flight resolve, per-session cache, fail-closed-but-retryable errors.
159
+ Kick `runtime.ensureInitialConsentResolved()` at router creation (window-guarded) so
160
+ the round trip overlaps hydration; read it reactively via
161
+ `useInitialConsent(runtime.initialConsentStore)` (`@codefast/tracking/react/use-initial-consent`).
162
+
163
+ ## Durable anonymous id ("client mints, server persists")
164
+
165
+ `createServerPersistedAnonymousId` (`@codefast/tracking/client/server-persisted-anonymous-id`) mints a UUID cookie
166
+ lazily — only once an event is actually allowed to send — and asks the server to re-issue
167
+ it via `Set-Cookie`, which escapes Safari ITP's 7-day cap on script-written cookies. The
168
+ server half is one line per endpoint with `setAnonymousIdResponseCookie` /
169
+ `clearAnonymousIdResponseCookie` (`@codefast/tracking/adapters/tanstack-start`); both validate the
170
+ id is exactly UUID-shaped, so a public endpoint can never echo attacker input into a
171
+ response header.
172
+
173
+ ## Google tag (advanced Consent Mode)
174
+
175
+ `<GtagConsentBootstrap config={consentConfig} defaultConsent={...} gaMeasurementId="G-…" />`
176
+ (`@codefast/tracking/react/use-initial-consent`) renders the pre-hydration inline script: Consent Mode v2
177
+ `default` first (stored decision wins over the baked fallback), then gtag.js always loads
178
+ so cookieless pings and consent modeling can run even when storage is denied. Page views
179
+ are gtag's own job (`config` + Enhanced Measurement) — the destination only forwards
180
+ catalog events. Runtime changes go through `useGoogleConsentSync`/`updateGoogleConsent`.
181
+
182
+ ## Keeping server-only subpaths out of client bundles
183
+
184
+ `./server` and `./adapters/tanstack-start` must never enter a client bundle. On TanStack Start,
185
+ spread the package's own deny-list into the plugin's import-protection so it versions
186
+ with the package instead of going stale in your config:
61
187
 
62
188
  ```ts
63
- import { attachClientLifecycle, attachRouterPageTracking } from "@codefast/tracking/client";
189
+ import { SERVER_ONLY_SUBPATHS } from "@codefast/tracking/tooling/import-protection";
64
190
 
65
- attachRouterPageTracking(tracker, router); // router: your app's TanStack Router instance
66
- attachClientLifecycle(tracker, { beaconEndpoint: "/api/events", flushIntervalMs: 10_000 });
191
+ tanstackStart({
192
+ importProtection: {
193
+ client: { specifiers: [...SERVER_ONLY_SUBPATHS] },
194
+ },
195
+ });
67
196
  ```
68
197
 
69
- ## Consent (region-based, per-category)
198
+ A violation is mocked with a console diagnostic in dev and fails the build in prod, with
199
+ a trace of the offending import chain.
70
200
 
71
- Consent is granular per purpose, mirroring Google Consent Mode v2's split: a
72
- `ConsentDecision` is `{ ads: boolean, analytics: boolean }`, never a single yes/no —
73
- GDPR requires purpose-level consent, and the ads signals (`ad_storage`/`ad_user_data`/
74
- `ad_personalization`) must be able to differ from `analytics_storage`.
75
-
76
- Resolve the region/mode server-side (`resolveRegion` + `resolveConsentMode` from
77
- `@codefast/tracking/server` and `@codefast/tracking`) and pass `mode` down to the client.
78
- `ConsentBanner`/`ConsentToggle` are headless — no `@codefast/ui` dependency. Style the
79
- root via `className` and the inner parts via their `data-slot` attributes
80
- (`consent-message`, `consent-actions`, `consent-action`, `consent-preferences`,
81
- `consent-category`), e.g. Tailwind's `**:data-[slot=consent-action]:rounded-md`.
82
-
83
- ```tsx
84
- import { createLocalStorageConsentStorage } from "@codefast/tracking/client";
85
- import { updateGoogleConsent } from "@codefast/tracking/destinations";
86
- import { ConsentBanner, ConsentToggle, useConsent } from "@codefast/tracking/react";
87
-
88
- // Module scope — useConsent subscribes to the storage, so it must be a stable reference.
89
- const consentStorage = createLocalStorageConsentStorage("tracking-consent");
90
-
91
- function ConsentGate({ mode }: { mode: "opt-in" | "opt-out" }) {
92
- const consent = useConsent({
93
- categories: ["analytics"], // the purposes your prompt asks about — Accept grants exactly these
94
- mode,
95
- onDecision: (decision) => {
96
- updateGoogleConsent(decision); // per-category Consent Mode v2 update
97
- if (!decision.analytics) tracker.clear(); // stop tracking + drop the pending queue
98
- },
99
- policyVersion: "2026-01",
100
- storage: consentStorage,
101
- });
102
-
103
- return mode === "opt-in" ? (
104
- <ConsentBanner
105
- // optional second layer: per-category checkboxes ("Customize" → "Save preferences")
106
- categories={[{ category: "analytics", label: "Analytics" }]}
107
- consent={consent}
108
- message={
109
- <>
110
- We use cookies to understand how you use this site. <a href="/privacy">Privacy policy</a>
111
- </>
112
- }
113
- />
114
- ) : (
115
- <ConsentToggle consent={consent} />
116
- );
117
- }
118
- ```
201
+ ## Reference consumer
202
+
203
+ [`apps/ui` (`src/features/tracking/`)](https://github.com/codefastlabs/codefast/tree/main/apps/ui/src/features/tracking)
204
+ in this repo wires everything above on a real ISR-deployed TanStack Start site — consent
205
+ config + runtime, banner + persistent toggle, gtag bootstrap, durable anonymous id, and
206
+ the private server-function consent lane.
119
207
 
120
- The stored decision is the single source of truth (`useSyncExternalStore` under the
121
- hood): hydration-safe on prerendered pages, and a decision made in one tab dismisses the
122
- banner in every other tab via the `storage` event.
208
+ ## License
123
209
 
124
- For Consent Mode v2, `setGoogleConsentDefault(decision, { waitForUpdateMs, region })`
125
- issues the pre-tag default (it defines the gtag queueing stub itself), and
126
- `setGoogleAdsDataRedaction`/`setGoogleUrlPassthrough` cover the denied-ads flags. A GPC
127
- signal is honored as a do-not-sell-or-share opt-out: it forces `ads` denied without
128
- withdrawing first-party `analytics`.
210
+ [MIT](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
@@ -0,0 +1,80 @@
1
+ import type { ConsentCategory, InitialConsent } from "#/core/consent";
2
+ import type { ConsentReceipt, ConsentReceiptInput } from "#/core/consent-receipt";
3
+ import type { AnonymousIdCookieOptions } from "#/server/anonymous-id-cookie";
4
+ import type { ReceiptStore } from "#/server/consent-receipt-store";
5
+ /**
6
+ * @since 1.0.0-canary.7
7
+ */
8
+ export interface InitialConsentFromRequestOptions {
9
+ /**
10
+ * Header carrying the ISO 3166-1 alpha-2 country code.
11
+ *
12
+ * @defaultValue "x-vercel-ip-country"
13
+ */
14
+ countryHeaderName?: string | undefined;
15
+ /** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
16
+ requestedCategories: ReadonlyArray<ConsentCategory>;
17
+ }
18
+ /**
19
+ * Region-correct `InitialConsent` for the current request: reads the platform geo header
20
+ * and `sec-gpc`, fails closed when geo is missing, and stamps
21
+ * `cache-control: private, no-store` — the value is per-visitor by definition, so no
22
+ * shared cache may ever store the response carrying it.
23
+ *
24
+ * Server-only: deny this subpath in the client environment via Start's `importProtection`
25
+ * — the compiler already strips it with stubbed handler bodies.
26
+ *
27
+ * @since 1.0.0-canary.6
28
+ */
29
+ export declare function resolveInitialConsentFromRequest(options: InitialConsentFromRequestOptions): InitialConsent;
30
+ /**
31
+ * Persists (or prolongs) a client-minted anonymous id via the framework's `setCookie` (which
32
+ * appends, so it never clobbers another `Set-Cookie` on the response) — the server re-issue
33
+ * that escapes Safari ITP's 7-day cap on script-written cookies. Validation lives in
34
+ * `resolveAnonymousIdCookie`: a non-UUID id throws, so this can safely back a public server
35
+ * function without echoing attacker input into a header.
36
+ *
37
+ * @since 1.0.0-canary.6
38
+ */
39
+ export declare function setAnonymousIdResponseCookie(options: AnonymousIdCookieOptions): void;
40
+ /**
41
+ * Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
42
+ *
43
+ * @since 1.0.0-canary.6
44
+ */
45
+ export declare function clearAnonymousIdResponseCookie(cookieName: string): void;
46
+ /**
47
+ * The client-visible acknowledgement of a recorded receipt — deliberately minimal so the
48
+ * stored PII (`subjectId`, `ipCoarse`) is never echoed back over the wire.
49
+ *
50
+ * @since 1.0.0-canary.7
51
+ */
52
+ export interface ConsentReceiptAck {
53
+ receiptId: string;
54
+ timestamp: number;
55
+ }
56
+ /**
57
+ * @since 1.0.0-canary.7
58
+ */
59
+ export interface RecordConsentReceiptFromRequestOptions {
60
+ input: ConsentReceiptInput;
61
+ /**
62
+ * Optional tamper-evidence signer — supply an HMAC/signature over the receipt to stamp an
63
+ * `integrityKey`. Omit it and the stored receipt carries none.
64
+ */
65
+ sign?: ((receipt: Omit<ConsentReceipt, "integrityKey">) => string) | undefined;
66
+ store: ReceiptStore;
67
+ }
68
+ /**
69
+ * Records a consent receipt for the current request: rejects a body-supplied IP, derives a
70
+ * coarsened one from the connection, builds the server-stamped receipt, appends it to the
71
+ * store, and stamps `cache-control: no-store` — the response carries PII, so no cache
72
+ * (shared or private) may store it. Returns a minimal ack, never the stored record.
73
+ *
74
+ * @throws Error when `input` fails {@link isConsentReceiptInput} (including a body that
75
+ * carries an `ip`/`ipCoarse` field — the server owns IP derivation).
76
+ *
77
+ * @since 1.0.0-canary.7
78
+ */
79
+ export declare function recordConsentReceiptFromRequest(options: RecordConsentReceiptFromRequestOptions): Promise<ConsentReceiptAck>;
80
+ //# sourceMappingURL=tanstack-start.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tanstack-start.d.ts","sourceRoot":"","sources":["../../src/adapters/tanstack-start.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAGnE;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,+FAA+F;IAC/F,mBAAmB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,gCAAgC,GAAG,cAAc,CAQ1G;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAQpF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sCAAsC;IACrD,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IAC/E,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,sCAAsC,GAC9C,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}
@@ -0,0 +1,74 @@
1
+ import { deleteCookie, getRequestHeader, getRequestIP, setCookie, setResponseHeader, } from "@tanstack/react-start/server";
2
+ import { isConsentReceiptInput } from "#/core/consent-receipt";
3
+ import { resolveAnonymousIdCookie, resolveClearAnonymousIdCookie } from "#/server/anonymous-id-cookie";
4
+ import { buildConsentReceipt } from "#/server/consent-receipt";
5
+ import { resolveInitialConsent } from "#/server/initial-consent";
6
+ /**
7
+ * Region-correct `InitialConsent` for the current request: reads the platform geo header
8
+ * and `sec-gpc`, fails closed when geo is missing, and stamps
9
+ * `cache-control: private, no-store` — the value is per-visitor by definition, so no
10
+ * shared cache may ever store the response carrying it.
11
+ *
12
+ * Server-only: deny this subpath in the client environment via Start's `importProtection`
13
+ * — the compiler already strips it with stubbed handler bodies.
14
+ *
15
+ * @since 1.0.0-canary.6
16
+ */
17
+ export function resolveInitialConsentFromRequest(options) {
18
+ setResponseHeader("cache-control", "private, no-store");
19
+ return resolveInitialConsent({
20
+ countryCode: getRequestHeader(options.countryHeaderName ?? "x-vercel-ip-country"),
21
+ hasGlobalPrivacyControlSignal: getRequestHeader("sec-gpc") === "1",
22
+ requestedCategories: options.requestedCategories,
23
+ });
24
+ }
25
+ /**
26
+ * Persists (or prolongs) a client-minted anonymous id via the framework's `setCookie` (which
27
+ * appends, so it never clobbers another `Set-Cookie` on the response) — the server re-issue
28
+ * that escapes Safari ITP's 7-day cap on script-written cookies. Validation lives in
29
+ * `resolveAnonymousIdCookie`: a non-UUID id throws, so this can safely back a public server
30
+ * function without echoing attacker input into a header.
31
+ *
32
+ * @since 1.0.0-canary.6
33
+ */
34
+ export function setAnonymousIdResponseCookie(options) {
35
+ const { name, value, ...attributes } = resolveAnonymousIdCookie({
36
+ cookieName: options.cookieName,
37
+ id: options.id,
38
+ maxAgeSeconds: options.maxAgeSeconds,
39
+ });
40
+ setCookie(name, value, attributes);
41
+ }
42
+ /**
43
+ * Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
44
+ *
45
+ * @since 1.0.0-canary.6
46
+ */
47
+ export function clearAnonymousIdResponseCookie(cookieName) {
48
+ const { name, ...attributes } = resolveClearAnonymousIdCookie(cookieName);
49
+ deleteCookie(name, attributes);
50
+ }
51
+ /**
52
+ * Records a consent receipt for the current request: rejects a body-supplied IP, derives a
53
+ * coarsened one from the connection, builds the server-stamped receipt, appends it to the
54
+ * store, and stamps `cache-control: no-store` — the response carries PII, so no cache
55
+ * (shared or private) may store it. Returns a minimal ack, never the stored record.
56
+ *
57
+ * @throws Error when `input` fails {@link isConsentReceiptInput} (including a body that
58
+ * carries an `ip`/`ipCoarse` field — the server owns IP derivation).
59
+ *
60
+ * @since 1.0.0-canary.7
61
+ */
62
+ export async function recordConsentReceiptFromRequest(options) {
63
+ setResponseHeader("cache-control", "no-store");
64
+ if (!isConsentReceiptInput(options.input)) {
65
+ throw new Error("Invalid consent receipt input");
66
+ }
67
+ // getRequestIP reads the platform/socket IP, trusting X-Forwarded-For's first hop — safe
68
+ // behind the CDN/proxy this app deploys to, and the maintained path over hand-parsing headers.
69
+ const rawIp = getRequestIP({ xForwardedFor: true });
70
+ const receipt = buildConsentReceipt({ input: options.input, rawIp, sign: options.sign });
71
+ await options.store.append(receipt);
72
+ return { receiptId: receipt.receiptId, timestamp: receipt.timestamp };
73
+ }
74
+ //# sourceMappingURL=tanstack-start.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tanstack-start.js","sourceRoot":"","sources":["../../src/adapters/tanstack-start.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AACvG,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAgBjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAAC,OAAyC;IACxF,iBAAiB,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAExD,OAAO,qBAAqB,CAAC;QAC3B,WAAW,EAAE,gBAAgB,CAAC,OAAO,CAAC,iBAAiB,IAAI,qBAAqB,CAAC;QACjF,6BAA6B,EAAE,gBAAgB,CAAC,SAAS,CAAC,KAAK,GAAG;QAClE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;KACjD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAiC;IAC5E,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,UAAU,EAAE,GAAG,wBAAwB,CAAC;QAC9D,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;IAEH,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,UAAkB;IAC/D,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,EAAE,GAAG,6BAA6B,CAAC,UAAU,CAAC,CAAC;IAE1E,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC;AA0BD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,OAA+C;IAE/C,iBAAiB,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IAE/C,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,yFAAyF;IACzF,+FAA+F;IAC/F,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEzF,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEpC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;AACxE,CAAC"}
@@ -0,0 +1,62 @@
1
+ import type { ConsentCategory, ConsentDecision } from "#/core/consent";
2
+ /**
3
+ * TCF/GPP interop reconciler (spec-ad-consent-frameworks): the system **reads** an external
4
+ * CMP and reconciles it with the native `{ ads, analytics }` decision — it never becomes a
5
+ * CMP, mints TC/GPP strings, or hard-codes TCF purpose ids or the Google vendor id (that
6
+ * mapping is ad-ops policy, so the caller derives `CmpConsentSignal` and passes it in).
7
+ */
8
+ /**
9
+ * Liveness of a detected CMP. `"out-of-scope"` is TCF `gdprApplies === false` / no applicable
10
+ * GPP section — the framework does not govern this user, so native consent stands.
11
+ *
12
+ * @since 1.0.0-canary.7
13
+ */
14
+ export type CmpStatus = "loading" | "out-of-scope" | "ready";
15
+ /**
16
+ * A CMP's governance over the native decision, already derived from TCData/GPP by ad-ops policy.
17
+ *
18
+ * @since 1.0.0-canary.7
19
+ */
20
+ export interface CmpConsentSignal {
21
+ /** Per-governed-category grant, read once `status` is `"ready"`. */
22
+ decision?: Partial<ConsentDecision> | undefined;
23
+ /** Categories this CMP governs in the current scope — the resolver overrides only these. */
24
+ governs: ReadonlyArray<ConsentCategory>;
25
+ status: CmpStatus;
26
+ }
27
+ /**
28
+ * @since 1.0.0-canary.7
29
+ */
30
+ export interface ReconcileAdFrameworkConsentOptions {
31
+ /** The live CMP signal, or omitted when no CMP is present (the resolver is then inert). */
32
+ cmp?: CmpConsentSignal | undefined;
33
+ /** Native GPC — can only tighten `ads`, never loosen a CMP grant. */
34
+ hasGlobalPrivacyControlSignal: boolean;
35
+ /** The stored/default decision that stands wherever no CMP governs. */
36
+ native: ConsentDecision;
37
+ }
38
+ /**
39
+ * Reconciles native consent with a CMP source of truth per spec-ad-consent-frameworks §3:
40
+ * a governing CMP overrides its categories (fail-closed to denied while loading); a missing
41
+ * or out-of-scope CMP leaves native standing; GPC always tightens `ads` last.
42
+ *
43
+ * @since 1.0.0-canary.7
44
+ */
45
+ export declare function reconcileAdFrameworkConsent(options: ReconcileAdFrameworkConsentOptions): ConsentDecision;
46
+ /**
47
+ * Detects a TCF CMP without reading it — `typeof __tcfapi === "function"` (spec §3).
48
+ *
49
+ * @since 1.0.0-canary.7
50
+ */
51
+ export declare function hasTcfApi(scope?: {
52
+ __tcfapi?: unknown;
53
+ }): boolean;
54
+ /**
55
+ * Detects a GPP CMP without reading it — `typeof __gpp === "function"` (spec §3).
56
+ *
57
+ * @since 1.0.0-canary.7
58
+ */
59
+ export declare function hasGppApi(scope?: {
60
+ __gpp?: unknown;
61
+ }): boolean;
62
+ //# sourceMappingURL=ad-framework-consent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ad-framework-consent.d.ts","sourceRoot":"","sources":["../../src/client/ad-framework-consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvE;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,OAAO,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;IAChD,4FAA4F;IAC5F,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,2FAA2F;IAC3F,GAAG,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACnC,qEAAqE;IACrE,6BAA6B,EAAE,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kCAAkC,GAAG,eAAe,CAkBxG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAyC,GAAG,OAAO,CAEvG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAsC,GAAG,OAAO,CAEjG"}
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Reconciles native consent with a CMP source of truth per spec-ad-consent-frameworks §3:
3
+ * a governing CMP overrides its categories (fail-closed to denied while loading); a missing
4
+ * or out-of-scope CMP leaves native standing; GPC always tightens `ads` last.
5
+ *
6
+ * @since 1.0.0-canary.7
7
+ */
8
+ export function reconcileAdFrameworkConsent(options) {
9
+ const result = { ...options.native };
10
+ const { cmp } = options;
11
+ // A governing CMP overrides only the categories it governs; no CMP / out-of-scope leaves native.
12
+ if (cmp && cmp.status !== "out-of-scope") {
13
+ for (const category of cmp.governs) {
14
+ // Fail closed until the CMP resolves; otherwise the CMP value wins for its categories.
15
+ result[category] = cmp.status === "loading" ? false : (cmp.decision?.[category] ?? false);
16
+ }
17
+ }
18
+ // GPC can only tighten `ads` — applied last so it wins over any CMP grant.
19
+ if (options.hasGlobalPrivacyControlSignal) {
20
+ result.ads = false;
21
+ }
22
+ return result;
23
+ }
24
+ /**
25
+ * Detects a TCF CMP without reading it — `typeof __tcfapi === "function"` (spec §3).
26
+ *
27
+ * @since 1.0.0-canary.7
28
+ */
29
+ export function hasTcfApi(scope = globalThis) {
30
+ return typeof scope.__tcfapi === "function";
31
+ }
32
+ /**
33
+ * Detects a GPP CMP without reading it — `typeof __gpp === "function"` (spec §3).
34
+ *
35
+ * @since 1.0.0-canary.7
36
+ */
37
+ export function hasGppApi(scope = globalThis) {
38
+ return typeof scope.__gpp === "function";
39
+ }
40
+ //# sourceMappingURL=ad-framework-consent.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ad-framework-consent.js","sourceRoot":"","sources":["../../src/client/ad-framework-consent.ts"],"names":[],"mappings":"AA0CA;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAA2C;IACrF,MAAM,MAAM,GAAoB,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IACtD,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAExB,iGAAiG;IACjG,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACzC,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YACnC,uFAAuF;YACvF,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,OAAO,CAAC,6BAA6B,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAK,GAA2B,UAAoC;IAC5F,OAAO,OAAO,KAAK,CAAC,QAAQ,KAAK,UAAU,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAK,GAAwB,UAAiC;IACtF,OAAO,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,CAAC;AAC3C,CAAC"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Shared `document.cookie` writer for the client-side cookie lanes (anonymous id, consent
3
+ * mirror): Secure on HTTPS so values never ride plain HTTP, SameSite=Lax, never HttpOnly —
4
+ * the client must read its own cookies back. A no-op without a `document` (SSR).
5
+ *
6
+ * @since 1.0.0-canary.6
7
+ */
8
+ export declare function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void;
9
+ //# sourceMappingURL=browser-cookie.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser-cookie.d.ts","sourceRoot":"","sources":["../../src/client/browser-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAQjG"}
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Shared `document.cookie` writer for the client-side cookie lanes (anonymous id, consent
3
+ * mirror): Secure on HTTPS so values never ride plain HTTP, SameSite=Lax, never HttpOnly —
4
+ * the client must read its own cookies back. A no-op without a `document` (SSR).
5
+ *
6
+ * @since 1.0.0-canary.6
7
+ */
8
+ export function writeBrowserCookie(cookieName, value, maxAgeSeconds) {
9
+ if (typeof document === "undefined") {
10
+ return;
11
+ }
12
+ const secure = globalThis.location.protocol === "https:" ? "; secure" : "";
13
+ document.cookie = `${cookieName}=${value}; path=/; max-age=${String(maxAgeSeconds)}; samesite=lax${secure}`;
14
+ }
15
+ //# sourceMappingURL=browser-cookie.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser-cookie.js","sourceRoot":"","sources":["../../src/client/browser-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,KAAa,EAAE,aAAqB;IACzF,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAE3E,QAAQ,CAAC,MAAM,GAAG,GAAG,UAAU,IAAI,KAAK,qBAAqB,MAAM,CAAC,aAAa,CAAC,iBAAiB,MAAM,EAAE,CAAC;AAC9G,CAAC"}