@codefast/tracking 0.5.0-canary.5 → 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 (276) hide show
  1. package/CHANGELOG.md +467 -0
  2. package/README.md +176 -126
  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 +201 -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/destinations/ad-consent.ts +29 -0
  193. package/src/destinations/google-analytics.ts +196 -133
  194. package/src/destinations/google-consent.ts +164 -0
  195. package/src/destinations/meta.ts +96 -0
  196. package/src/destinations/microsoft-uet.ts +86 -0
  197. package/src/destinations/shared.ts +45 -0
  198. package/src/destinations/tiktok.ts +85 -0
  199. package/src/destinations/vercel-analytics.ts +23 -24
  200. package/src/index.ts +165 -8
  201. package/src/react/consent-banner.tsx +40 -14
  202. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  203. package/src/react/use-consent.ts +53 -45
  204. package/src/react/use-google-consent-sync.ts +38 -0
  205. package/src/react/use-initial-consent.ts +22 -0
  206. package/src/server/anonymous-id-cookie.ts +103 -0
  207. package/src/server/consent-receipt-store.ts +79 -0
  208. package/src/server/consent-receipt.ts +89 -0
  209. package/src/server/initial-consent.ts +46 -0
  210. package/src/server/measurement-protocol.ts +114 -0
  211. package/src/server/region.ts +22 -15
  212. package/src/server/user-deletion.ts +93 -0
  213. package/src/tooling/import-protection.ts +22 -0
  214. package/dist/client/consent-storage.mjs +0 -63
  215. package/dist/client/create-client-tracker.d.mts +0 -37
  216. package/dist/client/create-client-tracker.mjs +0 -66
  217. package/dist/client/gpc.d.mts +0 -10
  218. package/dist/client/gpc.mjs +0 -12
  219. package/dist/client/index.d.mts +0 -8
  220. package/dist/client/index.mjs +0 -8
  221. package/dist/client/lifecycle.d.mts +0 -23
  222. package/dist/client/lifecycle.mjs +0 -30
  223. package/dist/client/local-storage.d.mts +0 -13
  224. package/dist/client/local-storage.mjs +0 -31
  225. package/dist/client/queue.d.mts +0 -49
  226. package/dist/client/queue.mjs +0 -71
  227. package/dist/client/router.d.mts +0 -30
  228. package/dist/client/router.mjs +0 -17
  229. package/dist/core/consent.d.mts +0 -89
  230. package/dist/core/consent.mjs +0 -57
  231. package/dist/core/destination.d.mts +0 -23
  232. package/dist/core/destination.mjs +0 -1
  233. package/dist/core/event-catalog.d.mts +0 -36
  234. package/dist/core/event-catalog.mjs +0 -12
  235. package/dist/core/event-id.d.mts +0 -10
  236. package/dist/core/event-id.mjs +0 -12
  237. package/dist/core/index.d.mts +0 -6
  238. package/dist/core/index.mjs +0 -4
  239. package/dist/core/tracked-event.d.mts +0 -17
  240. package/dist/core/tracked-event.mjs +0 -1
  241. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  242. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  243. package/dist/destinations/google-analytics.d.mts +0 -98
  244. package/dist/destinations/google-analytics.mjs +0 -126
  245. package/dist/destinations/http-destination.d.mts +0 -20
  246. package/dist/destinations/http-destination.mjs +0 -25
  247. package/dist/destinations/index.d.mts +0 -5
  248. package/dist/destinations/index.mjs +0 -5
  249. package/dist/destinations/vercel-analytics.d.mts +0 -13
  250. package/dist/destinations/vercel-analytics.mjs +0 -30
  251. package/dist/index.d.mts +0 -6
  252. package/dist/index.mjs +0 -4
  253. package/dist/react/consent-banner.d.mts +0 -163
  254. package/dist/react/consent-banner.mjs +0 -209
  255. package/dist/react/index.d.mts +0 -3
  256. package/dist/react/index.mjs +0 -3
  257. package/dist/react/use-consent.d.mts +0 -49
  258. package/dist/react/use-consent.mjs +0 -54
  259. package/dist/server/create-server-tracker.d.mts +0 -42
  260. package/dist/server/create-server-tracker.mjs +0 -67
  261. package/dist/server/index.d.mts +0 -3
  262. package/dist/server/index.mjs +0 -3
  263. package/dist/server/region.d.mts +0 -20
  264. package/dist/server/region.mjs +0 -56
  265. package/src/client/index.ts +0 -17
  266. package/src/client/lifecycle.ts +0 -50
  267. package/src/client/local-storage.ts +0 -44
  268. package/src/client/queue.ts +0 -117
  269. package/src/client/router.ts +0 -37
  270. package/src/core/index.ts +0 -24
  271. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  272. package/src/destinations/http-destination.ts +0 -33
  273. package/src/destinations/index.ts +0 -20
  274. package/src/react/index.ts +0 -29
  275. package/src/server/create-server-tracker.ts +0 -128
  276. package/src/server/index.ts +0 -4
@@ -3,13 +3,27 @@
3
3
  */
4
4
  export type ConsentRegion = "eu" | "other" | "us" | "vn";
5
5
 
6
+ /**
7
+ * @since 1.0.0-canary.6
8
+ */
9
+ export const CONSENT_REGIONS: ReadonlyArray<ConsentRegion> = ["eu", "other", "us", "vn"];
10
+
11
+ /**
12
+ * Guards a region read from untrusted storage (a cached `InitialConsent`, a cookie).
13
+ *
14
+ * @since 1.0.0-canary.6
15
+ */
16
+ export function isConsentRegion(value: unknown): value is ConsentRegion {
17
+ return CONSENT_REGIONS.includes(value as ConsentRegion);
18
+ }
19
+
6
20
  /**
7
21
  * @since 0.5.0-canary.4
8
22
  */
9
23
  export type ConsentMode = "opt-in" | "opt-out";
10
24
 
11
25
  /**
12
- * GDPR (EU) and Nghị định 13/2023 (VN) require explicit opt-in before any non-essential
26
+ * GDPR (EU) and the PDPL — Luật 91/2025/QH15 (VN) — require explicit opt-in before any non-essential
13
27
  * tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
14
28
  * that satisfies both, so the mode is resolved per region.
15
29
  *
@@ -60,19 +74,54 @@ export function createConsentDecision(grantedCategories: ReadonlyArray<ConsentCa
60
74
  return { ads: grantedCategories.includes("ads"), analytics: grantedCategories.includes("analytics") };
61
75
  }
62
76
 
77
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
78
+ return typeof value === "object" && value !== null && !Array.isArray(value);
79
+ }
80
+
63
81
  /**
64
82
  * Guards stored JSON — the record is tamperable, so every category must be an explicit boolean.
65
83
  *
66
84
  * @since 0.5.0-canary.4
67
85
  */
68
86
  export function isConsentDecision(value: unknown): value is ConsentDecision {
87
+ return isPlainObject(value) && CONSENT_CATEGORIES.every((category) => typeof value[category] === "boolean");
88
+ }
89
+
90
+ /**
91
+ * Re-derives a clean per-category decision from a tamperable record — extra keys are
92
+ * dropped, every category becomes an explicit boolean. The one normalization rule every
93
+ * reader of stored consent shares (e.g. `readStoredDecision`).
94
+ *
95
+ * @since 1.0.0-canary.6
96
+ */
97
+ export function normalizeConsentDecision(decision: ConsentDecision): ConsentDecision {
98
+ return createConsentDecision(CONSENT_CATEGORIES.filter((category) => decision[category]));
99
+ }
100
+
101
+ /**
102
+ * Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
103
+ *
104
+ * @since 1.0.0-canary.6
105
+ */
106
+ export function isConsentRecord(value: unknown): value is ConsentRecord {
69
107
  return (
70
- typeof value === "object" &&
71
- value !== null &&
72
- CONSENT_CATEGORIES.every((category) => typeof (value as Record<string, unknown>)[category] === "boolean")
108
+ isPlainObject(value) &&
109
+ isConsentDecision(value.decision) &&
110
+ typeof value.policyVersion === "string" &&
111
+ typeof value.timestamp === "number"
73
112
  );
74
113
  }
75
114
 
115
+ /**
116
+ * @since 1.0.0-canary.6
117
+ */
118
+ export interface ResolveDefaultConsentOptions {
119
+ /** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
120
+ hasGlobalPrivacyControlSignal: boolean;
121
+ mode: ConsentMode;
122
+ requestedCategories: ReadonlyArray<ConsentCategory>;
123
+ }
124
+
76
125
  /**
77
126
  * The effective consent before the visitor decides: opt-in regions start all-denied,
78
127
  * opt-out regions grant the categories the app asks for.
@@ -83,11 +132,9 @@ export function isConsentDecision(value: unknown): value is ConsentDecision {
83
132
  *
84
133
  * @since 0.5.0-canary.4
85
134
  */
86
- export function resolveDefaultConsent(
87
- mode: ConsentMode,
88
- requestedCategories: ReadonlyArray<ConsentCategory>,
89
- hasGlobalPrivacyControlSignal: boolean,
90
- ): ConsentDecision {
135
+ export function resolveDefaultConsent(options: ResolveDefaultConsentOptions): ConsentDecision {
136
+ const { hasGlobalPrivacyControlSignal, mode, requestedCategories } = options;
137
+
91
138
  if (mode === "opt-in") {
92
139
  return createConsentDecision([]);
93
140
  }
@@ -102,7 +149,68 @@ export function resolveDefaultConsent(
102
149
  }
103
150
 
104
151
  /**
105
- * NĐ 13/2023 and GDPR both expect a record of *when* and *under what policy* consent
152
+ * Region-resolved consent defaults — typically from `resolveInitialConsent` on a
153
+ * per-request server lane, then handed to the client so it never re-guesses the mode.
154
+ *
155
+ * @remarks
156
+ * Drive UI and gates from `mode` (recompute `effectiveConsent` with live navigator GPC).
157
+ * `defaultConsent` is the server snapshot — useful when you need request-time `sec-gpc`
158
+ * as-is; analytics-only apps can ignore it because GPC only forces `ads` denied.
159
+ *
160
+ * @since 1.0.0-canary.6
161
+ */
162
+ export interface InitialConsent {
163
+ defaultConsent: ConsentDecision;
164
+ mode: ConsentMode;
165
+ region: ConsentRegion;
166
+ }
167
+
168
+ /**
169
+ * What shared HTML bakes and what an unknown-country request resolves to: all categories
170
+ * denied under opt-in — the one default that is safe to show any visitor anywhere.
171
+ * Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
172
+ * header means "unknown visitor", never "known non-EU visitor".
173
+ *
174
+ * @since 1.0.0-canary.6
175
+ */
176
+ export const STRICTEST_INITIAL_CONSENT: InitialConsent = Object.freeze({
177
+ defaultConsent: Object.freeze(createConsentDecision([])),
178
+ mode: "opt-in",
179
+ region: "other",
180
+ });
181
+
182
+ /**
183
+ * Guards an `InitialConsent` read from untrusted storage (a session cache, a cookie).
184
+ * Enforces the mode/region pairing rule; the one deliberate exception is
185
+ * {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
186
+ * mode, never looser.
187
+ *
188
+ * @since 1.0.0-canary.6
189
+ */
190
+ export function isInitialConsent(value: unknown): value is InitialConsent {
191
+ if (!isPlainObject(value)) {
192
+ return false;
193
+ }
194
+
195
+ const mode = value.mode;
196
+ const region = value.region;
197
+
198
+ if (
199
+ (mode !== "opt-in" && mode !== "opt-out") ||
200
+ !isConsentRegion(region) ||
201
+ !isConsentDecision(value.defaultConsent)
202
+ ) {
203
+ return false;
204
+ }
205
+
206
+ return (
207
+ mode === resolveConsentMode(region) ||
208
+ (mode === STRICTEST_INITIAL_CONSENT.mode && region === STRICTEST_INITIAL_CONSENT.region)
209
+ );
210
+ }
211
+
212
+ /**
213
+ * Vietnam's PDPL and GDPR both expect a record of *when* and *under what policy* consent
106
214
  * was given, not just per-category flags — `policyVersion` lets a later policy change
107
215
  * invalidate stale consent.
108
216
  *
@@ -130,3 +238,49 @@ export interface ConsentStorage {
130
238
  */
131
239
  subscribe: (listener: () => void) => () => void;
132
240
  }
241
+
242
+ /**
243
+ * The stored decision if one exists under the current `policyVersion`, normalized to drop
244
+ * any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
245
+ * it was recorded under a superseded policy version.
246
+ *
247
+ * @since 1.0.0-canary.6
248
+ */
249
+ export function readStoredDecision(storage: ConsentStorage, policyVersion: string): ConsentDecision | undefined {
250
+ const record = storage.load();
251
+
252
+ if (record?.policyVersion !== policyVersion || !isConsentDecision(record.decision)) {
253
+ return undefined;
254
+ }
255
+
256
+ return normalizeConsentDecision(record.decision);
257
+ }
258
+
259
+ /**
260
+ * @since 1.0.0-canary.6
261
+ */
262
+ export interface ResolveEffectiveConsentOptions {
263
+ /** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
264
+ hasGlobalPrivacyControlSignal: boolean;
265
+ mode: ConsentMode;
266
+ policyVersion: string;
267
+ requestedCategories: ReadonlyArray<ConsentCategory>;
268
+ storage: ConsentStorage;
269
+ }
270
+
271
+ /**
272
+ * The consent a tracker should honor right now: the stored decision if one exists, else
273
+ * the region default — the same rule `useConsent` applies to its `effectiveConsent`, so a
274
+ * non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
275
+ * "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
276
+ *
277
+ * @since 1.0.0-canary.6
278
+ */
279
+ export function resolveEffectiveConsent(options: ResolveEffectiveConsentOptions): ConsentDecision {
280
+ const { hasGlobalPrivacyControlSignal, mode, policyVersion, requestedCategories, storage } = options;
281
+
282
+ return (
283
+ readStoredDecision(storage, policyVersion) ??
284
+ resolveDefaultConsent({ hasGlobalPrivacyControlSignal, mode, requestedCategories })
285
+ );
286
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Default lifetime shared by the anonymous-id and consent cookies — one year.
3
+ *
4
+ * @since 1.0.0-canary.6
5
+ */
6
+ export const ONE_YEAR_IN_SECONDS = 60 * 60 * 24 * 365;
7
+
8
+ /**
9
+ * The value of `cookieName` inside a cookie string — a request `Cookie` header or
10
+ * `document.cookie`, which share the `name=value; name2=value2` wire format — or
11
+ * `undefined` when absent. The name must match exactly; a longer prefix sibling is ignored.
12
+ *
13
+ * @since 1.0.0-canary.6
14
+ */
15
+ export function readCookieValue(cookieString: string | null | undefined, cookieName: string): string | undefined {
16
+ if (!cookieString) {
17
+ return undefined;
18
+ }
19
+
20
+ for (const part of cookieString.split(";")) {
21
+ const separatorIndex = part.indexOf("=");
22
+
23
+ if (separatorIndex !== -1 && part.slice(0, separatorIndex).trim() === cookieName) {
24
+ return part.slice(separatorIndex + 1).trim();
25
+ }
26
+ }
27
+
28
+ return undefined;
29
+ }
@@ -1,20 +1,29 @@
1
1
  import type { TrackedEvent } from "#/core/tracked-event";
2
2
 
3
3
  /**
4
- * Fan-out target for tracked events (PostHog, GA4, a self-hosted store, ...).
5
- * Trackers depend only on this interface, never on a specific provider SDK.
4
+ * Fan-out target for tracked events. The tracker depends only on this interface, never
5
+ * on a specific provider SDK — destinations own their transport (gtag.js and Vercel both
6
+ * queue and batch in-page), so `send` is fire-and-forget at track time.
6
7
  *
7
8
  * @since 0.5.0-canary.4
8
9
  */
9
10
  export interface Destination {
10
11
  /**
11
- * "immediate" for SDK-backed destinations that own their transport (gtag.js, Vercel's
12
- * in-page queue) — the client tracker calls `send` at track time and never queues,
13
- * persists, or retries for them.
12
+ * "exempt" keeps this destination receiving events while the tracker's analytics gate
13
+ * is closed — only for cookieless, identifier-free sinks: gated envelopes carry no
14
+ * `anonymousId`, and nothing is persisted.
14
15
  *
15
- * @defaultValue "queued"
16
+ * @defaultValue "required"
16
17
  */
17
- delivery?: "immediate" | "queued";
18
+ consentRequirement?: "exempt" | "required" | undefined;
18
19
  name: string;
19
- send: (event: TrackedEvent) => Promise<void> | void;
20
+ /**
21
+ * Erase this destination's trace of the subject on withdrawal (spec-data-subject-rights
22
+ * §3): clear the destination's cookies and stop sending, and — where the platform offers
23
+ * one — request per-visitor deletion. Optional: a sink with nothing to erase omits it.
24
+ * Invoked at most once per withdrawal; the tracker swallows its failures.
25
+ */
26
+ onErasure?: ((id: string) => Promise<void> | void) | undefined;
27
+ /** Must always return a `Promise` — mark `send` `async` even if the body has no `await`. */
28
+ send: (event: TrackedEvent) => Promise<void>;
20
29
  }
@@ -1,12 +1,12 @@
1
- import type { z } from "zod";
1
+ import type { StandardSchemaV1 } from "@standard-schema/spec";
2
2
 
3
3
  /**
4
- * One event's Zod schema plus which side of the app is allowed to fire it.
4
+ * One event's schema. Any Standard Schema library works (zod, zod/mini, valibot, ...) —
5
+ * the client bundle only pays for the one the app already ships.
5
6
  *
6
7
  * @since 0.5.0-canary.4
7
8
  */
8
- export interface EventDefinition<Schema extends z.ZodType = z.ZodType> {
9
- owner: "client" | "server";
9
+ export interface EventDefinition<Schema extends StandardSchemaV1 = StandardSchemaV1> {
10
10
  schema: Schema;
11
11
  }
12
12
 
@@ -18,17 +18,6 @@ export interface EventDefinition<Schema extends z.ZodType = z.ZodType> {
18
18
  */
19
19
  export type EventCatalog = Record<string, EventDefinition>;
20
20
 
21
- /**
22
- * Filters a catalog down to the events a given owner may fire. Client and server
23
- * trackers are built from this, so calling a server-owned event from client code
24
- * (or vice versa) is a compile-time error, not a runtime surprise.
25
- *
26
- * @since 0.5.0-canary.4
27
- */
28
- export type EventsOf<Catalog extends EventCatalog, Owner extends "client" | "server"> = {
29
- [Key in keyof Catalog as Catalog[Key]["owner"] extends Owner ? Key : never]: Catalog[Key];
30
- };
31
-
32
21
  /**
33
22
  * Identity helper for declaring a catalog with inference — nicer call-site than
34
23
  * `satisfies EventCatalog` when the catalog is assembled across multiple files.
@@ -38,3 +27,28 @@ export type EventsOf<Catalog extends EventCatalog, Owner extends "client" | "ser
38
27
  export function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalog): Catalog {
39
28
  return catalog;
40
29
  }
30
+
31
+ /**
32
+ * Validates event properties against the catalog schema and returns the parsed output
33
+ * (unknown keys stripped / transforms applied) so destinations never see raw input.
34
+ *
35
+ * @throws Error when validation reports issues, or when the schema validates asynchronously —
36
+ * tracking sits on synchronous call paths, so async schemas are unsupported by design.
37
+ *
38
+ * @since 1.0.0-canary.6
39
+ */
40
+ export function assertValidEventProperties(schema: StandardSchemaV1, eventName: string, properties: unknown): unknown {
41
+ const result = schema["~standard"].validate(properties);
42
+
43
+ if (result instanceof Promise) {
44
+ throw new TypeError(`Event "${eventName}" uses an async schema — event properties must validate synchronously`);
45
+ }
46
+
47
+ if (result.issues) {
48
+ const detail = result.issues.map((issue) => issue.message).join("; ");
49
+
50
+ throw new Error(`Invalid properties for event "${eventName}": ${detail}`);
51
+ }
52
+
53
+ return result.value;
54
+ }
@@ -1,6 +1,5 @@
1
1
  /**
2
- * Client-owned events use this at enqueue time; server-owned events derive an ID
3
- * from the request instead so retries of the same request don't double-count.
2
+ * Stamped on every envelope at track time — destinations that dedupe can key on it.
4
3
  *
5
4
  * @since 0.5.0-canary.4
6
5
  */
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Envelope every tracker (client/server) builds before handing an event to a destination.
2
+ * The event envelope destinations receive. `type` stays a discriminant so a future envelope
3
+ * kind is an additive union member, not a wire-format break.
3
4
  *
4
5
  * @since 0.5.0-canary.4
5
6
  */
@@ -7,8 +8,7 @@ export interface TrackedEvent {
7
8
  anonymousId: string;
8
9
  eventId: string;
9
10
  name: string;
10
- owner: "client" | "server";
11
- props: Record<string, unknown>;
11
+ properties: Record<string, unknown>;
12
12
  timestamp: number;
13
- userId?: string | undefined;
13
+ type: "track";
14
14
  }
@@ -0,0 +1,29 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+
3
+ /**
4
+ * The normalized two-lever ad-platform consent state derived from one `{ ads, analytics }`
5
+ * decision (spec-destinations §5): `analytics` drives whether events transmit at all, and
6
+ * `ads` drives Limited Data Use. The levers are independent — a US opt-out (`ads: false`)
7
+ * restricts to LDU but MUST NOT withhold first-party `analytics` (spec-consent §3). Every
8
+ * ad destination consumes this same shape so per-vendor mappings cannot drift.
9
+ *
10
+ * @since 1.0.0-canary.7
11
+ */
12
+ export interface AdConsentState {
13
+ /** `ads` denied → the platform must restrict to Limited Data Use (Meta/TikTok LDU, UET `ad_storage` denied). */
14
+ limitedDataUse: boolean;
15
+ /** `analytics` granted → events may transmit; denied → hold/revoke and send nothing. */
16
+ transmissionAllowed: boolean;
17
+ }
18
+
19
+ /**
20
+ * Normalizes a package `ConsentDecision` to the vendor-agnostic {@link AdConsentState}.
21
+ *
22
+ * @since 1.0.0-canary.7
23
+ */
24
+ export function toAdConsentState(decision: ConsentDecision): AdConsentState {
25
+ return {
26
+ limitedDataUse: !decision.ads,
27
+ transmissionAllowed: decision.analytics,
28
+ };
29
+ }