@codefast/tracking 0.7.1 → 0.7.2

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 (214) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +235 -105
  3. package/dist/adapters/tanstack-start.d.ts +1 -2
  4. package/dist/adapters/tanstack-start.js +1 -2
  5. package/dist/client/ad-framework-consent.d.ts +1 -2
  6. package/dist/client/ad-framework-consent.js +1 -2
  7. package/dist/client/browser-cookie.d.ts +1 -2
  8. package/dist/client/browser-cookie.js +1 -2
  9. package/dist/client/consent-runtime.d.ts +1 -2
  10. package/dist/client/consent-runtime.js +1 -2
  11. package/dist/client/consent-storage.d.ts +1 -2
  12. package/dist/client/consent-storage.js +1 -2
  13. package/dist/client/consent-withdrawal.d.ts +1 -2
  14. package/dist/client/consent-withdrawal.js +1 -2
  15. package/dist/client/cookie-anonymous-id.d.ts +1 -2
  16. package/dist/client/cookie-anonymous-id.js +1 -2
  17. package/dist/client/create-client-tracker.d.ts +1 -2
  18. package/dist/client/create-client-tracker.js +1 -2
  19. package/dist/client/gpc.d.ts +1 -2
  20. package/dist/client/gpc.js +1 -2
  21. package/dist/client/initial-consent-store.d.ts +1 -2
  22. package/dist/client/initial-consent-store.js +1 -2
  23. package/dist/client/is-analytics-allowed.d.ts +1 -2
  24. package/dist/client/is-analytics-allowed.js +1 -2
  25. package/dist/client/server-persisted-anonymous-id.d.ts +1 -2
  26. package/dist/client/server-persisted-anonymous-id.js +1 -2
  27. package/dist/core/consent-config.d.ts +1 -2
  28. package/dist/core/consent-config.js +1 -2
  29. package/dist/core/consent-receipt.d.ts +1 -2
  30. package/dist/core/consent-receipt.js +1 -2
  31. package/dist/core/consent.d.ts +1 -2
  32. package/dist/core/consent.js +1 -2
  33. package/dist/core/cookie.d.ts +1 -2
  34. package/dist/core/cookie.js +1 -2
  35. package/dist/core/destination.d.ts +1 -2
  36. package/dist/core/destination.js +1 -2
  37. package/dist/core/event-catalog.d.ts +1 -2
  38. package/dist/core/event-catalog.js +1 -2
  39. package/dist/core/event-id.d.ts +1 -2
  40. package/dist/core/event-id.js +1 -2
  41. package/dist/core/tracked-event.d.ts +1 -2
  42. package/dist/core/tracked-event.js +1 -2
  43. package/dist/destinations/ad-consent.d.ts +1 -2
  44. package/dist/destinations/ad-consent.js +1 -2
  45. package/dist/destinations/google-analytics.d.ts +1 -2
  46. package/dist/destinations/google-analytics.js +1 -2
  47. package/dist/destinations/google-consent.d.ts +1 -2
  48. package/dist/destinations/google-consent.js +1 -2
  49. package/dist/destinations/meta.d.ts +1 -2
  50. package/dist/destinations/meta.js +1 -2
  51. package/dist/destinations/microsoft-uet.d.ts +1 -2
  52. package/dist/destinations/microsoft-uet.js +1 -2
  53. package/dist/destinations/shared.d.ts +1 -2
  54. package/dist/destinations/shared.js +1 -2
  55. package/dist/destinations/tiktok.d.ts +1 -2
  56. package/dist/destinations/tiktok.js +1 -2
  57. package/dist/destinations/vercel-analytics.d.ts +1 -2
  58. package/dist/destinations/vercel-analytics.js +1 -2
  59. package/dist/index.d.ts +1 -2
  60. package/dist/index.js +1 -2
  61. package/dist/react/consent-banner.d.ts +1 -2
  62. package/dist/react/consent-banner.js +1 -2
  63. package/dist/react/gtag-consent-bootstrap.d.ts +1 -2
  64. package/dist/react/gtag-consent-bootstrap.js +1 -2
  65. package/dist/react/use-consent.d.ts +1 -2
  66. package/dist/react/use-consent.js +1 -2
  67. package/dist/react/use-google-consent-sync.d.ts +1 -2
  68. package/dist/react/use-google-consent-sync.js +1 -2
  69. package/dist/react/use-initial-consent.d.ts +1 -2
  70. package/dist/react/use-initial-consent.js +1 -2
  71. package/dist/server/anonymous-id-cookie.d.ts +1 -2
  72. package/dist/server/anonymous-id-cookie.js +1 -2
  73. package/dist/server/consent-receipt-store.d.ts +1 -2
  74. package/dist/server/consent-receipt-store.js +1 -2
  75. package/dist/server/consent-receipt.d.ts +1 -2
  76. package/dist/server/consent-receipt.js +1 -2
  77. package/dist/server/initial-consent.d.ts +1 -2
  78. package/dist/server/initial-consent.js +1 -2
  79. package/dist/server/measurement-protocol.d.ts +1 -2
  80. package/dist/server/measurement-protocol.js +1 -2
  81. package/dist/server/region.d.ts +1 -2
  82. package/dist/server/region.js +1 -2
  83. package/dist/server/user-deletion.d.ts +1 -2
  84. package/dist/server/user-deletion.js +1 -2
  85. package/dist/tooling/import-protection.d.ts +1 -2
  86. package/dist/tooling/import-protection.js +1 -2
  87. package/package.json +10 -61
  88. package/dist/adapters/tanstack-start.d.ts.map +0 -1
  89. package/dist/adapters/tanstack-start.js.map +0 -1
  90. package/dist/client/ad-framework-consent.d.ts.map +0 -1
  91. package/dist/client/ad-framework-consent.js.map +0 -1
  92. package/dist/client/browser-cookie.d.ts.map +0 -1
  93. package/dist/client/browser-cookie.js.map +0 -1
  94. package/dist/client/consent-runtime.d.ts.map +0 -1
  95. package/dist/client/consent-runtime.js.map +0 -1
  96. package/dist/client/consent-storage.d.ts.map +0 -1
  97. package/dist/client/consent-storage.js.map +0 -1
  98. package/dist/client/consent-withdrawal.d.ts.map +0 -1
  99. package/dist/client/consent-withdrawal.js.map +0 -1
  100. package/dist/client/cookie-anonymous-id.d.ts.map +0 -1
  101. package/dist/client/cookie-anonymous-id.js.map +0 -1
  102. package/dist/client/create-client-tracker.d.ts.map +0 -1
  103. package/dist/client/create-client-tracker.js.map +0 -1
  104. package/dist/client/gpc.d.ts.map +0 -1
  105. package/dist/client/gpc.js.map +0 -1
  106. package/dist/client/initial-consent-store.d.ts.map +0 -1
  107. package/dist/client/initial-consent-store.js.map +0 -1
  108. package/dist/client/is-analytics-allowed.d.ts.map +0 -1
  109. package/dist/client/is-analytics-allowed.js.map +0 -1
  110. package/dist/client/server-persisted-anonymous-id.d.ts.map +0 -1
  111. package/dist/client/server-persisted-anonymous-id.js.map +0 -1
  112. package/dist/core/consent-config.d.ts.map +0 -1
  113. package/dist/core/consent-config.js.map +0 -1
  114. package/dist/core/consent-receipt.d.ts.map +0 -1
  115. package/dist/core/consent-receipt.js.map +0 -1
  116. package/dist/core/consent.d.ts.map +0 -1
  117. package/dist/core/consent.js.map +0 -1
  118. package/dist/core/cookie.d.ts.map +0 -1
  119. package/dist/core/cookie.js.map +0 -1
  120. package/dist/core/destination.d.ts.map +0 -1
  121. package/dist/core/destination.js.map +0 -1
  122. package/dist/core/event-catalog.d.ts.map +0 -1
  123. package/dist/core/event-catalog.js.map +0 -1
  124. package/dist/core/event-id.d.ts.map +0 -1
  125. package/dist/core/event-id.js.map +0 -1
  126. package/dist/core/tracked-event.d.ts.map +0 -1
  127. package/dist/core/tracked-event.js.map +0 -1
  128. package/dist/destinations/ad-consent.d.ts.map +0 -1
  129. package/dist/destinations/ad-consent.js.map +0 -1
  130. package/dist/destinations/google-analytics.d.ts.map +0 -1
  131. package/dist/destinations/google-analytics.js.map +0 -1
  132. package/dist/destinations/google-consent.d.ts.map +0 -1
  133. package/dist/destinations/google-consent.js.map +0 -1
  134. package/dist/destinations/meta.d.ts.map +0 -1
  135. package/dist/destinations/meta.js.map +0 -1
  136. package/dist/destinations/microsoft-uet.d.ts.map +0 -1
  137. package/dist/destinations/microsoft-uet.js.map +0 -1
  138. package/dist/destinations/shared.d.ts.map +0 -1
  139. package/dist/destinations/shared.js.map +0 -1
  140. package/dist/destinations/tiktok.d.ts.map +0 -1
  141. package/dist/destinations/tiktok.js.map +0 -1
  142. package/dist/destinations/vercel-analytics.d.ts.map +0 -1
  143. package/dist/destinations/vercel-analytics.js.map +0 -1
  144. package/dist/index.d.ts.map +0 -1
  145. package/dist/index.js.map +0 -1
  146. package/dist/react/consent-banner.d.ts.map +0 -1
  147. package/dist/react/consent-banner.js.map +0 -1
  148. package/dist/react/gtag-consent-bootstrap.d.ts.map +0 -1
  149. package/dist/react/gtag-consent-bootstrap.js.map +0 -1
  150. package/dist/react/use-consent.d.ts.map +0 -1
  151. package/dist/react/use-consent.js.map +0 -1
  152. package/dist/react/use-google-consent-sync.d.ts.map +0 -1
  153. package/dist/react/use-google-consent-sync.js.map +0 -1
  154. package/dist/react/use-initial-consent.d.ts.map +0 -1
  155. package/dist/react/use-initial-consent.js.map +0 -1
  156. package/dist/server/anonymous-id-cookie.d.ts.map +0 -1
  157. package/dist/server/anonymous-id-cookie.js.map +0 -1
  158. package/dist/server/consent-receipt-store.d.ts.map +0 -1
  159. package/dist/server/consent-receipt-store.js.map +0 -1
  160. package/dist/server/consent-receipt.d.ts.map +0 -1
  161. package/dist/server/consent-receipt.js.map +0 -1
  162. package/dist/server/initial-consent.d.ts.map +0 -1
  163. package/dist/server/initial-consent.js.map +0 -1
  164. package/dist/server/measurement-protocol.d.ts.map +0 -1
  165. package/dist/server/measurement-protocol.js.map +0 -1
  166. package/dist/server/region.d.ts.map +0 -1
  167. package/dist/server/region.js.map +0 -1
  168. package/dist/server/user-deletion.d.ts.map +0 -1
  169. package/dist/server/user-deletion.js.map +0 -1
  170. package/dist/tooling/import-protection.d.ts.map +0 -1
  171. package/dist/tooling/import-protection.js.map +0 -1
  172. package/src/adapters/tanstack-start.ts +0 -139
  173. package/src/client/ad-framework-consent.ts +0 -88
  174. package/src/client/browser-cookie.ts +0 -16
  175. package/src/client/consent-runtime.ts +0 -82
  176. package/src/client/consent-storage.ts +0 -125
  177. package/src/client/consent-withdrawal.ts +0 -34
  178. package/src/client/cookie-anonymous-id.ts +0 -116
  179. package/src/client/create-client-tracker.ts +0 -174
  180. package/src/client/gpc.ts +0 -15
  181. package/src/client/initial-consent-store.ts +0 -220
  182. package/src/client/is-analytics-allowed.ts +0 -45
  183. package/src/client/server-persisted-anonymous-id.ts +0 -104
  184. package/src/core/consent-config.ts +0 -27
  185. package/src/core/consent-receipt.ts +0 -115
  186. package/src/core/consent.ts +0 -298
  187. package/src/core/cookie.ts +0 -29
  188. package/src/core/destination.ts +0 -29
  189. package/src/core/event-catalog.ts +0 -54
  190. package/src/core/event-id.ts +0 -8
  191. package/src/core/tracked-event.ts +0 -14
  192. package/src/css/consent.css +0 -119
  193. package/src/destinations/ad-consent.ts +0 -29
  194. package/src/destinations/google-analytics.ts +0 -304
  195. package/src/destinations/google-consent.ts +0 -166
  196. package/src/destinations/meta.ts +0 -98
  197. package/src/destinations/microsoft-uet.ts +0 -88
  198. package/src/destinations/shared.ts +0 -51
  199. package/src/destinations/tiktok.ts +0 -87
  200. package/src/destinations/vercel-analytics.ts +0 -41
  201. package/src/index.ts +0 -171
  202. package/src/react/consent-banner.tsx +0 -386
  203. package/src/react/gtag-consent-bootstrap.tsx +0 -50
  204. package/src/react/use-consent.ts +0 -123
  205. package/src/react/use-google-consent-sync.ts +0 -40
  206. package/src/react/use-initial-consent.ts +0 -22
  207. package/src/server/anonymous-id-cookie.ts +0 -105
  208. package/src/server/consent-receipt-store.ts +0 -79
  209. package/src/server/consent-receipt.ts +0 -89
  210. package/src/server/initial-consent.ts +0 -48
  211. package/src/server/measurement-protocol.ts +0 -116
  212. package/src/server/region.ts +0 -77
  213. package/src/server/user-deletion.ts +0 -97
  214. package/src/tooling/import-protection.ts +0 -22
package/CHANGELOG.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # @codefast/tracking
2
2
 
3
+ ## 0.7.2
4
+
5
+ ### Patch Changes
6
+
7
+ - [#791](https://github.com/codefastlabs/codefast/pull/791) [`37a212b`](https://github.com/codefastlabs/codefast/commit/37a212b4d805588413159e11e872b98db82326bf) Thanks [@thevuong](https://github.com/thevuong)! - Point the README's license badge and "License" section at the package's own `LICENSE` file instead of the monorepo root.
8
+
9
+ - [#796](https://github.com/codefastlabs/codefast/pull/796) [`ba04d27`](https://github.com/codefastlabs/codefast/commit/ba04d2703c59a1677f52e6a9fffd0ec202328218) Thanks [@thevuong](https://github.com/thevuong)! - Rewrite the README around one structure — what the package is, installation and requirements, a complete quick start,
10
+ the concepts in learning order, then the documents and the license — with every API claim checked against the current
11
+ code and no figures that go stale.
12
+
13
+ - [#784](https://github.com/codefastlabs/codefast/pull/784) [`ad2f93a`](https://github.com/codefastlabs/codefast/commit/ad2f93a688e99c3ed8be6ceeae9d6cdd6be861bc) Thanks [@thevuong](https://github.com/thevuong)! - Ship the MIT `LICENSE` file in the published package. `files` already listed it, but the file was missing from the
14
+ package directory, so the tarball had none.
15
+
3
16
  ## 0.7.1
4
17
 
5
18
  ### Patch Changes
package/README.md CHANGED
@@ -1,25 +1,31 @@
1
1
  # @codefast/tracking
2
2
 
3
- Consent-gated, type-safe event tracking for TanStack Start apps.
3
+ Consent-gated, type-safe event tracking for TanStack Start apps that ship to a CDN-cached (ISR) deployment.
4
4
 
5
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 [Standard Schema](https://standardschema.dev)
9
- library (zod, `zod/mini`, valibot, ...); `track()` validates properties at the call site and at runtime, and the
10
- client bundle only pays for the schema library the app already ships.
11
- - **One consent config, every surface** — `ConsentConfig` is the single bag for the storage key, policy version, and
12
- requested purposes; the React hooks, the tracker gate, and the pre-hydration gtag bootstrap all take the same object,
13
- so nothing drifts.
14
- - **ISR-safe by design** — shared/CDN-cached HTML bakes the strictest consent default; the region-correct default
15
- arrives per visitor over a private server-function lane.
16
-
17
- ## Status
18
-
19
- Pre-1.0 (canary). The surface is deliberately small: it covers exactly what a consented gtag + Vercel Analytics setup on
20
- TanStack Start needs, and nothing speculative. Lanes that shipped here before (offline queue, beacon relay, server-side
21
- tracker, GTM, Segment-style `identify`/`group`/`alias`/`page`) were removed because no consumer called them — git
22
- history has them if a real need returns.
6
+ [![license](https://img.shields.io/npm/l/@codefast/tracking)](./LICENSE)
7
+
8
+ ## Overview
9
+
10
+ `@codefast/tracking` is consent-gated, type-safe event tracking for TanStack Start apps deployed to a CDN cache (ISR).
11
+ You define your events over a Standard Schema catalog, and `track()` infers each event's name and properties, validates
12
+ them at runtime, and forwards them to your destinations — but only when consent allows.
13
+
14
+ Because ISR HTML is shared across visitors, the package bakes the strictest consent default into the cached render, then
15
+ resolves the region-correct default per visitor over a private server-function lane.
16
+
17
+ - **One catalog, typed end to end.** The app defines its events over any [Standard Schema](https://standardschema.dev)
18
+ library (zod, `zod/mini`, valibot, and so on). `track()` infers the event name and its properties from the catalog and
19
+ validates them at runtime, and the client bundle pays only for the schema library the app already ships.
20
+ - **One consent config, every surface.** `ConsentConfig` holds the storage key, the policy version, and the requested
21
+ purposes. The React hooks, the tracker gate, and the pre-hydration Google tag bootstrap all take the same object, so
22
+ nothing drifts.
23
+ - **ISR-safe by design.** Shared HTML bakes the strictest consent default; the region-correct default arrives per
24
+ visitor over a private server-function lane.
25
+ - **Per-category decisions.** Consent is `{ ads, analytics }`, mirroring Google Consent Mode v2, with region-resolved
26
+ opt-in or opt-out modes, and Global Privacy Control honored as an ads opt-out.
27
+ - **Destinations own their transport.** gtag.js and Vercel Analytics batch in-page, so `track()` is fire-and-forget, and
28
+ a failing destination never breaks the interaction.
23
29
 
24
30
  ## Installation
25
31
 
@@ -27,10 +33,17 @@ history has them if a real need returns.
27
33
  pnpm add @codefast/tracking
28
34
  ```
29
35
 
30
- Every peer is optional and only needed by the surface that uses it: `react`/`react-dom` (>= 19) for `/react`,
31
- `@tanstack/react-start` (>= 1.168) for `/adapters/tanstack-start`, and `@vercel/analytics` for the Vercel destination.
36
+ `@codefast/tracking` requires Node.js 24 or later. Its one runtime dependency is `@standard-schema/spec`. Every peer is
37
+ optional, needed only by the surface that uses it: `react` and `react-dom` (19 or later) for the `react/*` subpaths,
38
+ `@tanstack/react-start` (1.168 or later) for `adapters/tanstack-start`, and `@vercel/analytics` for
39
+ `destinations/vercel-analytics`.
40
+
41
+ The package is published on 0.x and versioned on its own track: breaking changes ship as minor versions, so pin the
42
+ minor version when you need stability.
32
43
 
33
- ## Quick Start
44
+ ## Quick start
45
+
46
+ Three modules: the consent contract, the live consent runtime derived from it, and the catalog plus tracker.
34
47
 
35
48
  ```ts
36
49
  // consent.ts — the one consent contract every surface shares
@@ -48,7 +61,7 @@ export const consentConfig = defineConsentConfig({
48
61
  import { createConsentRuntime } from "@codefast/tracking/client/consent-runtime";
49
62
 
50
63
  import { consentConfig } from "./consent";
51
- import { resolveVisitorConsent } from "./resolve-visitor-consent"; // server fn, see below
64
+ import { resolveVisitorConsent } from "./resolve-visitor-consent"; // server function, see "The ISR lane"
52
65
 
53
66
  export const consentRuntime = createConsentRuntime({
54
67
  config: consentConfig,
@@ -72,10 +85,10 @@ export const catalog = defineEventCatalog({
72
85
  });
73
86
 
74
87
  export const tracker = createClientTracker({
75
- anonymousId: () => "...", // see the durable anonymous id section
88
+ anonymousId: () => "...", // see "Durable anonymous id"
76
89
  catalog,
77
90
  destinations: [
78
- // Vercel is cookieless and receives no identifier — it may keep counting pre-consent.
91
+ // Vercel is cookieless and receives no identifier, so it may keep counting before consent.
79
92
  createVercelAnalyticsDestination({ consentRequirement: "exempt" }),
80
93
  createGoogleAnalyticsDestination(),
81
94
  ],
@@ -85,92 +98,200 @@ export const tracker = createClientTracker({
85
98
  tracker.track("copy_code", { name: "button" }); // typed + runtime-validated
86
99
  ```
87
100
 
88
- Destinations own their transport (gtag.js and Vercel both batch in-page), so `track()` is fire-and-forget — a failing
89
- destination can never break the interaction.
101
+ `anonymousId` is a callback, not a value: the tracker calls it per allowed event, so the id is only minted once an event
102
+ is actually permitted to send. `isAnalyticsAllowed` is consulted before every event; while it returns `false`, only
103
+ `consentRequirement: "exempt"` destinations still receive events, stripped of identifiers. Pass `isExemptionAllowed` to
104
+ gate even that lane per region, and `onDeliveryError` to meter a destination that throws or rejects.
90
105
 
91
106
  ## Event catalog
92
107
 
93
- The package ships no events and no schema library — every app builds its own catalog with `defineEventCatalog` over
94
- whatever Standard Schema validator it already uses. `track()` infers both the event name and its properties from the
95
- catalog, then validates the properties at runtime; a mismatch throws at the call site. Async schemas are rejected by
96
- design — tracking sits on synchronous call paths.
108
+ The package ships no events and no schema library. Every app builds its own catalog with `defineEventCatalog` over the
109
+ Standard Schema validator it already uses. `track()` infers both the event name and its properties from the catalog,
110
+ then validates the properties at runtime and hands destinations the parsed output (unknown keys stripped, transforms
111
+ applied). A validation failure throws at the call site. Schemas that validate asynchronously are rejected, because
112
+ tracking sits on synchronous call paths.
97
113
 
98
114
  ## Subpaths
99
115
 
100
- The root `@codefast/tracking` is the **client entry**: it re-exports the isomorphic core (catalog types, `Destination`,
101
- consent model + config) plus the whole browser-side surface (tracker, consent runtime, React bindings, and the client
102
- destinations). Server-only lanes are their own subpaths and are never re-exported from the root:
103
-
104
- - `@codefast/tracking` — client entry: core + `createClientTracker`, `createConsentRuntime`, the
105
- `useConsent`/`ConsentBanner`/`GtagConsentBootstrap` React bindings, the gtag + ad-network destinations.
106
- - `@codefast/tracking/destinations/vercel-analytics` — its own subpath so its `@vercel/analytics` peer is only pulled in
107
- when used.
108
- - `@codefast/tracking/server/*` — request-scoped, **server-only**: `server/initial-consent`,
109
- `server/consent-receipt-store`, `server/measurement-protocol`, … (server code imports the core it needs from
110
- `@codefast/tracking/core/*`, never from the client root).
111
- - `@codefast/tracking/adapters/tanstack-start` — request/response glue over Start's server context, **server-only**.
112
- - `@codefast/tracking/tooling/import-protection` — `SERVER_ONLY_SUBPATHS` deny-list for client bundles.
113
- - `@codefast/tracking/css/consent.css` — optional plain-CSS theme for the consent banner.
114
-
115
- Every built module is also its own subpath (e.g. `@codefast/tracking/client/gpc`) for granular imports. Server-only
116
- lanes (`server/*`, `adapters/*`) must never enter a client bundle — feed `SERVER_ONLY_SUBPATHS` to the framework's
117
- import-protection (see below). There is deliberately no server-side tracker: destinations batch in-page, and the server
118
- half of the package is consent resolution plus cookie persistence.
119
-
120
- ## Consent (region-based, per-category)
121
-
122
- `ConsentDecision` is per-purpose (`{ ads, analytics }`), mirroring Google Consent Mode v2. Region resolves the mode:
123
- GDPR (EU, plus UK/EEA-EFTA equivalents) and Vietnam's PDPL get **opt-in**; the US (CCPA/CPRA) and unrecognized regions
124
- get **opt-out**, with GPC honored as an ads-only opt-out. Stored records are policy-versioned and shape-checked — a
125
- malformed or legacy-shaped record re-prompts instead of silently deciding.
126
-
127
- - `useConsent({ config, mode, storage })` — `useSyncExternalStore` bridge over the stored decision; cross-tab saves sync
128
- through the `storage` event.
129
- - `ConsentBanner` + parts (`Title`/`Description`/`Actions`/`Accept`/`Reject`/`Customize`/
130
- `Preferences`/`Category`/`Save`) — headless, `data-slot`-styleable; optional plain-CSS theme at
131
- `@codefast/tracking/css/consent.css`. `ConsentToggle` is the persistent opt-out control CCPA requires.
132
- - `useGoogleConsentSync(consent, { loadGtagScript? })` — pushes Consent Mode `update` signals, including privacy-page
133
- and cross-tab decisions.
134
- - `createConsentWithdrawalHandler({ clearAnonymousId?, clearGoogleAnalyticsCookies? })` — wire to `onDecision` so a
135
- denial clears first-party identifiers.
136
-
137
- ### The ISR lane
138
-
139
- ISR/CDN-cached HTML is shared across visitors, so no render may read geo. Bake `STRICTEST_INITIAL_CONSENT` into the
140
- shared render (and into `<GtagConsentBootstrap />`), then resolve the region-correct default per visitor after
141
- hydration:
142
-
143
- 1. **Server function** — `resolveInitialConsentFromRequest({ requestedCategories })`
144
- (`@codefast/tracking/adapters/tanstack-start`) reads the geo header and `sec-gpc`, stamps
145
- `cache-control: private, no-store`, and fails closed when geo is missing.
146
- 2. **Client** — `createConsentRuntime` owns the rest: strictest default until the server answers, single-flight resolve,
147
- per-session cache, fail-closed-but-retryable errors. Kick `runtime.ensureInitialConsentResolved()` at router creation
148
- (window-guarded) so the round trip overlaps hydration; read it reactively via
149
- `useInitialConsent(runtime.initialConsentStore)` (`@codefast/tracking/react/use-initial-consent`).
150
-
151
- ## Durable anonymous id ("client mints, server persists")
152
-
153
- `createServerPersistedAnonymousId` (`@codefast/tracking/client/server-persisted-anonymous-id`) mints a UUID cookie
154
- lazily — only once an event is actually allowed to send — and asks the server to re-issue it via `Set-Cookie`, which
155
- escapes Safari ITP's 7-day cap on script-written cookies. The server half is one line per endpoint with
156
- `setAnonymousIdResponseCookie` / `clearAnonymousIdResponseCookie` (`@codefast/tracking/adapters/tanstack-start`); both
157
- validate the id is exactly UUID-shaped, so a public endpoint can never echo attacker input into a response header.
158
-
159
- ## Google tag (advanced Consent Mode)
160
-
161
- `<GtagConsentBootstrap config={consentConfig} defaultConsent={...} gaMeasurementId="G-…" />`
162
- (`@codefast/tracking/react/gtag-consent-bootstrap`) renders the pre-hydration inline script: Consent Mode v2 `default`
163
- first (stored decision wins over the baked fallback), then gtag.js always loads so cookieless pings and consent modeling
164
- can run even when storage is denied. Page views are gtag's own job (`config` + Enhanced Measurement) — the destination
165
- only forwards catalog events. Runtime changes go through `useGoogleConsentSync`/`updateGoogleConsent`.
116
+ The root `@codefast/tracking` is the **client entry**. It re-exports the isomorphic core (catalog types, `Destination`,
117
+ the consent model and `ConsentConfig`) plus the whole browser-side surface: `createClientTracker`,
118
+ `createConsentRuntime`, the `useConsent`/`ConsentBanner`/`GtagConsentBootstrap` React bindings, and the client-lane
119
+ destinations (Google Analytics, Meta, TikTok, Microsoft UET). Server-only lanes are never re-exported from the root.
120
+
121
+ | Subpath | Lane | Contents |
122
+ | -------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
123
+ | `@codefast/tracking` | client | Core + tracker + consent runtime + React bindings + gtag/ad-network destinations |
124
+ | `@codefast/tracking/destinations/vercel-analytics` | client | Its own subpath so the `@vercel/analytics` peer is only pulled in when used |
125
+ | `@codefast/tracking/core/*` | isomorphic | `consent`, `consent-config`, `consent-receipt`, `cookie`, `destination`, `event-catalog`, `event-id` |
126
+ | `@codefast/tracking/server/*` | server-only | `initial-consent`, `region`, `anonymous-id-cookie`, `consent-receipt`, `consent-receipt-store`, ... |
127
+ | `@codefast/tracking/adapters/tanstack-start` | server-only | Request/response glue over `@tanstack/react-start/server` |
128
+ | `@codefast/tracking/tooling/import-protection` | build | `SERVER_ONLY_SUBPATHS`, the deny-list for client bundles |
129
+ | `@codefast/tracking/css/consent.css` | client | Optional plain-CSS theme for the consent banner |
130
+
131
+ Every built module is also its own subpath (for example `@codefast/tracking/client/gpc`) for granular imports. Server
132
+ code imports the core it needs from `@codefast/tracking/core/*`, never from the client root. There is no server-side
133
+ tracker: destinations batch in-page, and the server half of the package is consent resolution plus cookie persistence.
134
+
135
+ ## Consent
136
+
137
+ `ConsentDecision` is per purpose (`{ ads, analytics }`). The region resolves the mode: the EU (plus the UK, Iceland,
138
+ Liechtenstein, and Norway) and Vietnam are **opt-in**; the US and unrecognized countries are **opt-out**. Under opt-out,
139
+ a Global Privacy Control signal forces `ads` denied and leaves first-party analytics alone. Stored records carry a
140
+ `policyVersion`; a malformed record, or one saved under another version, counts as no decision and re-prompts.
141
+
142
+ ```tsx
143
+ import { useConsent } from "@codefast/tracking/react/use-consent";
144
+ import { useInitialConsent } from "@codefast/tracking/react/use-initial-consent";
145
+
146
+ import { consentConfig } from "./consent";
147
+ import { consentRuntime } from "./consent-runtime";
148
+
149
+ export function useAppConsent() {
150
+ // Strictest default until the server lane answers — see "The ISR lane".
151
+ const { initialConsent, isResolved } = useInitialConsent(consentRuntime.initialConsentStore);
152
+ const consent = useConsent({
153
+ config: consentConfig,
154
+ mode: initialConsent.mode,
155
+ storage: consentRuntime.storage, // one shared instance — must be a stable reference
156
+ });
157
+
158
+ return { consent, isResolved };
159
+ }
160
+ ```
161
+
162
+ - `useConsent({ config, mode, storage, hasGlobalPrivacyControlSignal?, onDecision? })` bridges the stored decision to
163
+ React through `useSyncExternalStore`. It returns `decision`, `effectiveConsent`, `isAnalyticsAllowed`,
164
+ `isPromptNeeded`, and the `grantAll`/`denyAll`/`saveDecision` actions. A decision saved in another tab syncs through
165
+ the storage subscription.
166
+ - `ConsentBanner` is headless and composable: `ConsentBannerTitle`, `ConsentBannerDescription`, `ConsentBannerActions`,
167
+ `ConsentBannerAccept`, `ConsentBannerReject`, `ConsentBannerCustomize`, `ConsentBannerPreferences`,
168
+ `ConsentBannerCategory`, and `ConsentBannerSave`. The root takes `consent` (the `useConsent` result) and an optional
169
+ `open` override, renders nothing unless `consent.isPromptNeeded`, and flips `data-state` between `prompt` and
170
+ `preferences`. Style the `data-slot` attributes yourself or import `@codefast/tracking/css/consent.css`.
171
+ - `ConsentToggle` is the always-visible control opt-out regions need. By default it flips only `ads`; pass
172
+ `toggledCategories={["analytics"]}` (or both) for a broader opt-out.
173
+ - `createConsentWithdrawalHandler({ clearAnonymousId?, clearGoogleAnalyticsCookies? })` returns an `onDecision` handler
174
+ that clears first-party identifiers when analytics is denied.
175
+
176
+ ## The ISR lane
177
+
178
+ CDN-cached HTML is shared across visitors, so no render may read geo. Bake `STRICTEST_INITIAL_CONSENT` into the shared
179
+ render (and into `GtagConsentBootstrap`), then resolve the region-correct default per visitor after hydration.
180
+
181
+ ```ts
182
+ // initial-consent-from-request.server.ts — server-only module
183
+ import { resolveInitialConsentFromRequest } from "@codefast/tracking/adapters/tanstack-start";
184
+
185
+ import { consentConfig } from "./consent";
186
+
187
+ export function initialConsentFromRequest() {
188
+ return resolveInitialConsentFromRequest({ requestedCategories: consentConfig.requestedCategories });
189
+ }
190
+ ```
191
+
192
+ ```ts
193
+ // resolve-visitor-consent.ts — the server function the client calls
194
+ import { createServerFn } from "@tanstack/react-start";
195
+
196
+ import { initialConsentFromRequest } from "./initial-consent-from-request.server";
197
+
198
+ export const resolveVisitorConsent = createServerFn({ method: "GET" }).handler(() => initialConsentFromRequest());
199
+ ```
200
+
201
+ `resolveInitialConsentFromRequest` reads the country header (`x-vercel-ip-country` by default; override with
202
+ `countryHeaderName`) and `sec-gpc`, stamps `cache-control: private, no-store`, and fails closed to the strictest default
203
+ when the header is missing — an unknown visitor is never treated as a known non-EU visitor.
204
+
205
+ `createConsentRuntime` owns the client half: the strictest default until the server answers, a single in-flight request,
206
+ a per-session cache under `initialConsentSessionStorageKey`, and a fail-closed but retryable error path. Call
207
+ `consentRuntime.ensureInitialConsentResolved()` at router creation (window-guarded) so the round trip overlaps
208
+ hydration, then read the result reactively with `useInitialConsent(consentRuntime.initialConsentStore)`, as in the
209
+ Consent section: `initialConsent.mode` feeds `useConsent`, and `isResolved` gates region-dependent UI so an opt-in
210
+ banner never flashes at an opt-out visitor. The hook also kicks resolution on mount, so the early call is an
211
+ optimization, not a requirement.
212
+
213
+ ## Durable anonymous id
214
+
215
+ The client mints, the server persists. `createServerPersistedAnonymousId` mints a UUID cookie lazily — only once an
216
+ event is allowed to send — and asks the server to re-issue it via `Set-Cookie`, which is what lets the id outlive the
217
+ cap browsers put on script-written cookies. The server half is one line per endpoint.
218
+
219
+ ```ts
220
+ // anonymous-id.ts
221
+ import {
222
+ clearAnonymousIdResponseCookie,
223
+ setAnonymousIdResponseCookie,
224
+ } from "@codefast/tracking/adapters/tanstack-start";
225
+ import { createServerFn } from "@tanstack/react-start";
226
+
227
+ export const ANONYMOUS_ID_COOKIE_NAME = "my-app-anon-id";
228
+
229
+ export const persistAnonymousIdCookie = createServerFn({ method: "POST" })
230
+ .validator((data: { id: string }) => data)
231
+ .handler(({ data }) => {
232
+ setAnonymousIdResponseCookie({ cookieName: ANONYMOUS_ID_COOKIE_NAME, id: data.id });
233
+ });
234
+
235
+ export const clearAnonymousIdCookie = createServerFn({ method: "POST" }).handler(() => {
236
+ clearAnonymousIdResponseCookie(ANONYMOUS_ID_COOKIE_NAME);
237
+ });
238
+ ```
239
+
240
+ ```ts
241
+ import { createServerPersistedAnonymousId } from "@codefast/tracking/client/server-persisted-anonymous-id";
242
+
243
+ import { ANONYMOUS_ID_COOKIE_NAME, clearAnonymousIdCookie, persistAnonymousIdCookie } from "./anonymous-id";
244
+
245
+ export const anonymousId = createServerPersistedAnonymousId({
246
+ clearOnServer: () => clearAnonymousIdCookie(),
247
+ cookieName: ANONYMOUS_ID_COOKIE_NAME,
248
+ persist: (id) => persistAnonymousIdCookie({ data: { id } }),
249
+ });
250
+
251
+ // createClientTracker({ anonymousId: anonymousId.getOrCreate, ... })
252
+ ```
253
+
254
+ `setAnonymousIdResponseCookie` throws unless the id is exactly UUID-shaped, so a public server function can never echo
255
+ attacker input into a response header. Wire `anonymousId.clear` into `createConsentWithdrawalHandler` so a withdrawal
256
+ expires the cookie on both sides.
257
+
258
+ ## Google tag
259
+
260
+ `GtagConsentBootstrap` renders the pre-hydration inline script for advanced Consent Mode: it applies the Consent Mode v2
261
+ `default` signal (a stored decision wins over the baked `defaultConsent`), then always loads gtag.js so cookieless pings
262
+ and consent modeling can run even when storage is denied.
263
+
264
+ ```tsx
265
+ import { STRICTEST_INITIAL_CONSENT } from "@codefast/tracking";
266
+ import { GtagConsentBootstrap } from "@codefast/tracking/react/gtag-consent-bootstrap";
267
+
268
+ import { consentConfig } from "./consent";
269
+
270
+ export function GoogleTag() {
271
+ return (
272
+ <GtagConsentBootstrap
273
+ config={consentConfig}
274
+ defaultConsent={STRICTEST_INITIAL_CONSENT.defaultConsent}
275
+ gaMeasurementId="G-XXXXXXX"
276
+ />
277
+ );
278
+ }
279
+ ```
280
+
281
+ Optional props: `dataLayerName`, `debugMode`, and a CSP `nonce` that is stamped on both the host script and the injected
282
+ gtag.js tag. Page views are gtag's own job (`config` plus Enhanced Measurement); `createGoogleAnalyticsDestination` only
283
+ forwards catalog events. Runtime decision changes go through `useGoogleConsentSync(consent, { loadGtagScript? })`, which
284
+ emits `update` whenever a stored decision exists (including cross-tab saves), or through `updateGoogleConsent` directly.
166
285
 
167
286
  ## Keeping server-only subpaths out of client bundles
168
287
 
169
- `./server` and `./adapters/tanstack-start` must never enter a client bundle. On TanStack Start, spread the package's own
170
- deny-list into the plugin's import-protection so it versions with the package instead of going stale in your config:
288
+ `server/*` and `adapters/*` must never enter a client bundle. `SERVER_ONLY_SUBPATHS` is the package's own deny-list as
289
+ picomatch patterns; spread it into TanStack Start's import protection so the list versions with the package instead of
290
+ going stale in your config.
171
291
 
172
292
  ```ts
173
293
  import { SERVER_ONLY_SUBPATHS } from "@codefast/tracking/tooling/import-protection";
294
+ import { tanstackStart } from "@tanstack/react-start/plugin/vite";
174
295
 
175
296
  tanstackStart({
176
297
  importProtection: {
@@ -179,15 +300,24 @@ tanstackStart({
179
300
  });
180
301
  ```
181
302
 
182
- A violation is mocked with a console diagnostic in dev and fails the build in prod, with a trace of the offending import
183
- chain.
184
-
185
303
  ## Reference consumer
186
304
 
187
- [`apps/ui` (`src/features/tracking/`)](https://github.com/codefastlabs/codefast/tree/main/apps/ui/src/features/tracking)
188
- in this repo wires everything above on a real ISR-deployed TanStack Start site — consent config + runtime, banner +
189
- persistent toggle, gtag bootstrap, durable anonymous id, and the private server-function consent lane.
305
+ [`apps/ui/src/features/tracking`](../../apps/ui/src/features/tracking/) wires everything above on a real ISR-deployed
306
+ TanStack Start site: the consent config and runtime, the banner and the persistent toggle, the gtag bootstrap, the
307
+ durable anonymous id, and the private server-function consent lane.
308
+
309
+ ## Documentation
310
+
311
+ - [codefastlabs.com/docs/tracking](https://codefastlabs.com/docs/tracking) — the rendered docs.
312
+ - [`spec/`](./spec/README.md) — the behavioural contract as language-neutral documents, one per concern (event model,
313
+ consent, identity, tracker, destinations, server lane, security, plus the commercial-scope extensions), each ending in
314
+ conformance vectors.
315
+ - [`CHANGELOG.md`](./CHANGELOG.md) — release notes per version.
316
+
317
+ ## Contributing
318
+
319
+ See the repository [contributing guide](../../CONTRIBUTING.md) for the toolchain, test taxonomy, and release flow.
190
320
 
191
321
  ## License
192
322
 
193
- [MIT](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
323
+ Released under the [MIT License](./LICENSE).
@@ -80,5 +80,4 @@ export interface RecordConsentReceiptFromRequestOptions {
80
80
  *
81
81
  * @since 0.5.0-canary.6
82
82
  */
83
- export declare function recordConsentReceiptFromRequest(options: RecordConsentReceiptFromRequestOptions): Promise<ConsentReceiptAck>;
84
- //# sourceMappingURL=tanstack-start.d.ts.map
83
+ export declare function recordConsentReceiptFromRequest(options: RecordConsentReceiptFromRequestOptions): Promise<ConsentReceiptAck>;
@@ -70,5 +70,4 @@ export async function recordConsentReceiptFromRequest(options) {
70
70
  const receipt = buildConsentReceipt({ input: options.input, rawIp, sign: options.sign });
71
71
  await options.store.append(receipt);
72
72
  return { receiptId: receipt.receiptId, timestamp: receipt.timestamp };
73
- }
74
- //# sourceMappingURL=tanstack-start.js.map
73
+ }
@@ -60,5 +60,4 @@ export declare function hasTcfApi(scope?: {
60
60
  */
61
61
  export declare function hasGppApi(scope?: {
62
62
  __gpp?: unknown;
63
- }): boolean;
64
- //# sourceMappingURL=ad-framework-consent.d.ts.map
63
+ }): boolean;
@@ -36,5 +36,4 @@ export function hasTcfApi(scope = globalThis) {
36
36
  */
37
37
  export function hasGppApi(scope = globalThis) {
38
38
  return typeof scope.__gpp === "function";
39
- }
40
- //# sourceMappingURL=ad-framework-consent.js.map
39
+ }
@@ -5,5 +5,4 @@
5
5
  *
6
6
  * @since 0.5.0-canary.6
7
7
  */
8
- export declare function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void;
9
- //# sourceMappingURL=browser-cookie.d.ts.map
8
+ export declare function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void;
@@ -11,5 +11,4 @@ export function writeBrowserCookie(cookieName, value, maxAgeSeconds) {
11
11
  }
12
12
  const secure = globalThis.location.protocol === "https:" ? "; secure" : "";
13
13
  document.cookie = `${cookieName}=${value}; path=/; max-age=${String(maxAgeSeconds)}; samesite=lax${secure}`;
14
- }
15
- //# sourceMappingURL=browser-cookie.js.map
14
+ }
@@ -51,5 +51,4 @@ export interface ConsentRuntime {
51
51
  *
52
52
  * @since 0.5.0-canary.6
53
53
  */
54
- export declare function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime;
55
- //# sourceMappingURL=consent-runtime.d.ts.map
54
+ export declare function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime;
@@ -29,5 +29,4 @@ export function createConsentRuntime(options) {
29
29
  isAnalyticsAllowed,
30
30
  storage,
31
31
  };
32
- }
33
- //# sourceMappingURL=consent-runtime.js.map
32
+ }
@@ -17,5 +17,4 @@ import type { ConsentStorage } from "#/core/consent";
17
17
  *
18
18
  * @since 0.5.0-canary.4
19
19
  */
20
- export declare function createLocalStorageConsentStorage(storageKey: string): ConsentStorage;
21
- //# sourceMappingURL=consent-storage.d.ts.map
20
+ export declare function createLocalStorageConsentStorage(storageKey: string): ConsentStorage;
@@ -105,5 +105,4 @@ export function createLocalStorageConsentStorage(storageKey) {
105
105
  };
106
106
  },
107
107
  };
108
- }
109
- //# sourceMappingURL=consent-storage.js.map
108
+ }
@@ -16,5 +16,4 @@ export interface ConsentWithdrawalHandlerOptions {
16
16
  *
17
17
  * @since 0.5.0-canary.6
18
18
  */
19
- export declare function createConsentWithdrawalHandler(options: ConsentWithdrawalHandlerOptions): (decision: ConsentDecision) => void;
20
- //# sourceMappingURL=consent-withdrawal.d.ts.map
19
+ export declare function createConsentWithdrawalHandler(options: ConsentWithdrawalHandlerOptions): (decision: ConsentDecision) => void;
@@ -13,5 +13,4 @@ export function createConsentWithdrawalHandler(options) {
13
13
  clearAnonymousId?.();
14
14
  clearGoogleAnalyticsCookies?.();
15
15
  };
16
- }
17
- //# sourceMappingURL=consent-withdrawal.js.map
16
+ }
@@ -41,5 +41,4 @@ export interface CookieAnonymousId {
41
41
  *
42
42
  * @since 0.5.0-canary.6
43
43
  */
44
- export declare function createCookieAnonymousId(options: CookieAnonymousIdOptions): CookieAnonymousId;
45
- //# sourceMappingURL=cookie-anonymous-id.d.ts.map
44
+ export declare function createCookieAnonymousId(options: CookieAnonymousIdOptions): CookieAnonymousId;
@@ -61,5 +61,4 @@ export function createCookieAnonymousId(options) {
61
61
  }
62
62
  },
63
63
  };
64
- }
65
- //# sourceMappingURL=cookie-anonymous-id.js.map
64
+ }
@@ -62,5 +62,4 @@ export interface ClientTracker<Catalog extends EventCatalog> {
62
62
  *
63
63
  * @since 0.5.0-canary.4
64
64
  */
65
- export declare function createClientTracker<Catalog extends EventCatalog>(options: ClientTrackerOptions<Catalog>): ClientTracker<Catalog>;
66
- //# sourceMappingURL=create-client-tracker.d.ts.map
65
+ export declare function createClientTracker<Catalog extends EventCatalog>(options: ClientTrackerOptions<Catalog>): ClientTracker<Catalog>;
@@ -89,5 +89,4 @@ export function createClientTracker(options) {
89
89
  }
90
90
  },
91
91
  };
92
- }
93
- //# sourceMappingURL=create-client-tracker.js.map
92
+ }
@@ -6,5 +6,4 @@
6
6
  *
7
7
  * @since 0.5.0-canary.4
8
8
  */
9
- export declare function hasGlobalPrivacyControlSignal(): boolean;
10
- //# sourceMappingURL=gpc.d.ts.map
9
+ export declare function hasGlobalPrivacyControlSignal(): boolean;
@@ -8,5 +8,4 @@
8
8
  */
9
9
  export function hasGlobalPrivacyControlSignal() {
10
10
  return typeof navigator !== "undefined" && navigator.globalPrivacyControl === true;
11
- }
12
- //# sourceMappingURL=gpc.js.map
11
+ }
@@ -61,5 +61,4 @@ export interface InitialConsentStore {
61
61
  *
62
62
  * @since 0.5.0-canary.6
63
63
  */
64
- export declare function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore;
65
- //# sourceMappingURL=initial-consent-store.d.ts.map
64
+ export declare function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore;
@@ -134,5 +134,4 @@ export function createInitialConsentStore(options) {
134
134
  };
135
135
  },
136
136
  };
137
- }
138
- //# sourceMappingURL=initial-consent-store.js.map
137
+ }
@@ -24,5 +24,4 @@ export interface IsAnalyticsAllowedOptions {
24
24
  *
25
25
  * @since 0.5.0-canary.6
26
26
  */
27
- export declare function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean;
28
- //# sourceMappingURL=is-analytics-allowed.d.ts.map
27
+ export declare function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean;
@@ -18,5 +18,4 @@ export function createIsAnalyticsAllowed(options) {
18
18
  });
19
19
  return effectiveConsent.analytics;
20
20
  };
21
- }
22
- //# sourceMappingURL=is-analytics-allowed.js.map
21
+ }