@codefast/tracking 0.5.0-canary.5 → 1.0.0-canary.7

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 +220 -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 +203 -108
  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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server-persisted-anonymous-id.js","sourceRoot":"","sources":["../../src/client/server-persisted-anonymous-id.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAoBhD;;;;;;;;;GASG;AACH,MAAM,UAAU,gCAAgC,CAAC,OAA0C;IACzF,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACtE,MAAM,KAAK,GAAG,uBAAuB,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC;IACrE,sFAAsF;IACtF,oFAAoF;IACpF,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,OAAO;QACL,KAAK;YACH,4EAA4E;YAC5E,2EAA2E;YAC3E,MAAM,iBAAiB,GACrB,OAAO,QAAQ,KAAK,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;YAE3F,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,uDAAuD;YACvD,mBAAmB,GAAG,KAAK,CAAC;YAE5B,IAAI,iBAAiB,EAAE,CAAC;gBACtB,KAAK,aAAa,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;oBAChC,sDAAsD;gBACxD,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO;YACL,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC;QACD,WAAW;YACT,oFAAoF;YACpF,kEAAkE;YAClE,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;gBACrF,mBAAmB,GAAG,KAAK,CAAC;YAC9B,CAAC;YAED,MAAM,EAAE,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;YAE/B,qFAAqF;YACrF,0EAA0E;YAC1E,IAAI,CAAC,mBAAmB,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;gBAC5D,mBAAmB,GAAG,IAAI,CAAC;gBAC3B,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBAC1B,6DAA6D;gBAC/D,CAAC,CAAC,CAAC;YACL,CAAC;YAED,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO;YACL,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;gBACpC,OAAO;YACT,CAAC;YAED,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAE9D,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YAED,KAAK,CAAC,OAAO,EAAE,CAAC;YAEhB,oFAAoF;YACpF,IAAI,CAAC,mBAAmB,EAAE,CAAC;gBACzB,mBAAmB,GAAG,IAAI,CAAC;gBAC3B,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBAChC,oEAAoE;gBACtE,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
@@ -0,0 +1,24 @@
1
+ import type { ConsentCategory } from "#/core/consent";
2
+ /**
3
+ * The consent constants every surface must agree on. The React hooks, the client
4
+ * tracker gate, and the pre-hydration tag bootstrap all accept this object, so the
5
+ * cross-surface "must match" contracts hold by construction instead of by hand-threading
6
+ * the same strings through every call site.
7
+ *
8
+ * @since 1.0.0-canary.6
9
+ */
10
+ export interface ConsentConfig {
11
+ /** Bumping re-prompts every visitor — a stored decision under any other version is ignored. */
12
+ policyVersion: string;
13
+ /** Purposes the app's prompt asks about — `grantAll` and opt-out defaults grant exactly these. */
14
+ requestedCategories: ReadonlyArray<ConsentCategory>;
15
+ /** `localStorage` key holding the visitor's `ConsentRecord`. */
16
+ storageKey: string;
17
+ }
18
+ /**
19
+ * Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
20
+ *
21
+ * @since 1.0.0-canary.6
22
+ */
23
+ export declare function defineConsentConfig<Config extends ConsentConfig>(config: Config): Config;
24
+ //# sourceMappingURL=consent-config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent-config.d.ts","sourceRoot":"","sources":["../../src/core/consent-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,aAAa,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,mBAAmB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACpD,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExF"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
3
+ *
4
+ * @since 1.0.0-canary.6
5
+ */
6
+ export function defineConsentConfig(config) {
7
+ return config;
8
+ }
9
+ //# sourceMappingURL=consent-config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent-config.js","sourceRoot":"","sources":["../../src/core/consent-config.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAA+B,MAAc;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC"}
@@ -0,0 +1,71 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ /**
3
+ * Which consent event a receipt records. Receipts are append-only: an `update` or
4
+ * `withdraw` is a new receipt referencing the prior one, never a mutation.
5
+ *
6
+ * @since 1.0.0-canary.7
7
+ */
8
+ export type ConsentReceiptEventType = "give" | "update" | "withdraw";
9
+ /**
10
+ * How the decision was expressed — the "how" dimension a demonstrable-consent record must
11
+ * capture (GDPR Art. 7(1); EDPB 05/2020 §5.1). See spec/spec-consent-receipts.md.
12
+ *
13
+ * @since 1.0.0-canary.7
14
+ */
15
+ export type ConsentReceiptMethod = "banner-accept" | "banner-reject" | "granular" | "gpc-signal" | "withdrawal";
16
+ /**
17
+ * What kind of identifier links the receipt to a subject. A cookie-only visitor uses a
18
+ * pseudonymous `cookie` id — the receipt is still valid proof.
19
+ *
20
+ * @since 1.0.0-canary.7
21
+ */
22
+ export type ConsentReceiptSubjectIdType = "cookie" | "email-hash" | "userId";
23
+ /**
24
+ * The caller-supplied fields of a consent receipt. Deliberately carries **no IP** — the
25
+ * server derives a coarsened one from the connection so a full IP never transits the body.
26
+ *
27
+ * @since 1.0.0-canary.7
28
+ */
29
+ export interface ConsentReceiptInput {
30
+ decision: ConsentDecision;
31
+ eventType: ConsentReceiptEventType;
32
+ method: ConsentReceiptMethod;
33
+ /** BCP-47 language of the notice the subject was shown. */
34
+ noticeLanguage: string;
35
+ /** Version the stored notice snapshot resolves to — EDPB para 108's "copy of the information presented". */
36
+ noticeVersion: string;
37
+ policyVersion: string;
38
+ subjectId: string;
39
+ subjectIdType: ConsentReceiptSubjectIdType;
40
+ /** The prior receipt this update/withdrawal supersedes — the append-only chain link. */
41
+ supersedesReceiptId?: string | undefined;
42
+ }
43
+ /**
44
+ * A stored consent receipt: the caller input plus server-derived fields. This is the
45
+ * legally-authoritative record of proof — the client `ConsentRecord` is only a runtime
46
+ * cache (spec-consent-receipts §5).
47
+ *
48
+ * @remarks
49
+ * The record is append-only; never mutate a stored receipt. `ipCoarse` is truncated at
50
+ * write time and MUST NOT be a full IP.
51
+ *
52
+ * @since 1.0.0-canary.7
53
+ */
54
+ export interface ConsentReceipt extends ConsentReceiptInput {
55
+ /** Coarsened/pseudonymized IP, or absent — never a full address. */
56
+ ipCoarse?: string | undefined;
57
+ /** Optional tamper-evidence signature, present only when a signer was supplied. */
58
+ integrityKey?: string | undefined;
59
+ receiptId: string;
60
+ schemaVersion: string;
61
+ /** Milliseconds since the Unix epoch, from the server clock. */
62
+ timestamp: number;
63
+ }
64
+ /**
65
+ * Guards a receipt input received from an untrusted client. Rejects a body carrying an
66
+ * `ip`/`ipCoarse` field so a full address can never be persisted from caller input.
67
+ *
68
+ * @since 1.0.0-canary.7
69
+ */
70
+ export declare function isConsentReceiptInput(value: unknown): value is ConsentReceiptInput;
71
+ //# sourceMappingURL=consent-receipt.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent-receipt.d.ts","sourceRoot":"","sources":["../../src/core/consent-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,eAAe,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC;AAEhH;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,4GAA4G;IAC5G,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,2BAA2B,CAAC;IAC3C,wFAAwF;IACxF,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IACzD,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAgBD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAwBlF"}
@@ -0,0 +1,39 @@
1
+ import { isConsentDecision } from "#/core/consent";
2
+ function isString(value) {
3
+ return typeof value === "string";
4
+ }
5
+ const RECEIPT_METHODS = new Set([
6
+ "banner-accept",
7
+ "banner-reject",
8
+ "granular",
9
+ "gpc-signal",
10
+ "withdrawal",
11
+ ]);
12
+ const RECEIPT_SUBJECT_ID_TYPES = new Set(["cookie", "email-hash", "userId"]);
13
+ /**
14
+ * Guards a receipt input received from an untrusted client. Rejects a body carrying an
15
+ * `ip`/`ipCoarse` field so a full address can never be persisted from caller input.
16
+ *
17
+ * @since 1.0.0-canary.7
18
+ */
19
+ export function isConsentReceiptInput(value) {
20
+ if (typeof value !== "object" || value === null) {
21
+ return false;
22
+ }
23
+ const input = value;
24
+ // A client MUST NOT supply IP — the server derives it. Presence is an integrity red flag.
25
+ if ("ip" in input || "ipCoarse" in input) {
26
+ return false;
27
+ }
28
+ return (isConsentDecision(input.decision) &&
29
+ (input.eventType === "give" || input.eventType === "update" || input.eventType === "withdraw") &&
30
+ isString(input.method) &&
31
+ RECEIPT_METHODS.has(input.method) &&
32
+ isString(input.noticeLanguage) &&
33
+ isString(input.noticeVersion) &&
34
+ isString(input.policyVersion) &&
35
+ isString(input.subjectId) &&
36
+ isString(input.subjectIdType) &&
37
+ RECEIPT_SUBJECT_ID_TYPES.has(input.subjectIdType));
38
+ }
39
+ //# sourceMappingURL=consent-receipt.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent-receipt.js","sourceRoot":"","sources":["../../src/core/consent-receipt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAqEnD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED,MAAM,eAAe,GAAsC,IAAI,GAAG,CAAC;IACjE,eAAe;IACf,eAAe;IACf,UAAU;IACV,YAAY;IACZ,YAAY;CACb,CAAC,CAAC;AAEH,MAAM,wBAAwB,GAA6C,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEvH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,KAAgC,CAAC;IAE/C,0FAA0F;IAC1F,IAAI,IAAI,IAAI,KAAK,IAAI,UAAU,IAAI,KAAK,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC;QACjC,CAAC,KAAK,CAAC,SAAS,KAAK,MAAM,IAAI,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,KAAK,UAAU,CAAC;QAC9F,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QACtB,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,MAA8B,CAAC;QACzD,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC;QAC9B,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;QACzB,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;QAC7B,wBAAwB,CAAC,GAAG,CAAC,KAAK,CAAC,aAA4C,CAAC,CACjF,CAAC;AACJ,CAAC"}
@@ -0,0 +1,182 @@
1
+ /**
2
+ * @since 0.5.0-canary.4
3
+ */
4
+ export type ConsentRegion = "eu" | "other" | "us" | "vn";
5
+ /**
6
+ * @since 1.0.0-canary.6
7
+ */
8
+ export declare const CONSENT_REGIONS: ReadonlyArray<ConsentRegion>;
9
+ /**
10
+ * Guards a region read from untrusted storage (a cached `InitialConsent`, a cookie).
11
+ *
12
+ * @since 1.0.0-canary.6
13
+ */
14
+ export declare function isConsentRegion(value: unknown): value is ConsentRegion;
15
+ /**
16
+ * @since 0.5.0-canary.4
17
+ */
18
+ export type ConsentMode = "opt-in" | "opt-out";
19
+ /**
20
+ * GDPR (EU) and the PDPL — Luật 91/2025/QH15 (VN) — require explicit opt-in before any non-essential
21
+ * tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
22
+ * that satisfies both, so the mode is resolved per region.
23
+ *
24
+ * @since 0.5.0-canary.4
25
+ */
26
+ export declare function resolveConsentMode(region: ConsentRegion): ConsentMode;
27
+ /**
28
+ * Consent purposes, mirroring Google Consent Mode v2's split: `analytics` gates
29
+ * measurement (`analytics_storage`), `ads` gates advertising storage and data sharing
30
+ * (`ad_storage`/`ad_user_data`/`ad_personalization`).
31
+ *
32
+ * @since 0.5.0-canary.4
33
+ */
34
+ export type ConsentCategory = "ads" | "analytics";
35
+ /**
36
+ * @since 0.5.0-canary.4
37
+ */
38
+ export declare const CONSENT_CATEGORIES: ReadonlyArray<ConsentCategory>;
39
+ /**
40
+ * Per-category consent — GDPR consent must be granular per purpose, so a single
41
+ * granted/denied flag can't represent it. `true` means the visitor granted that purpose.
42
+ *
43
+ * @since 0.5.0-canary.4
44
+ */
45
+ export type ConsentDecision = Record<ConsentCategory, boolean>;
46
+ /**
47
+ * A decision granting exactly the given categories and denying every other one.
48
+ *
49
+ * @since 0.5.0-canary.4
50
+ */
51
+ export declare function createConsentDecision(grantedCategories: ReadonlyArray<ConsentCategory>): ConsentDecision;
52
+ /**
53
+ * Guards stored JSON — the record is tamperable, so every category must be an explicit boolean.
54
+ *
55
+ * @since 0.5.0-canary.4
56
+ */
57
+ export declare function isConsentDecision(value: unknown): value is ConsentDecision;
58
+ /**
59
+ * Re-derives a clean per-category decision from a tamperable record — extra keys are
60
+ * dropped, every category becomes an explicit boolean. The one normalization rule every
61
+ * reader of stored consent shares (e.g. `readStoredDecision`).
62
+ *
63
+ * @since 1.0.0-canary.6
64
+ */
65
+ export declare function normalizeConsentDecision(decision: ConsentDecision): ConsentDecision;
66
+ /**
67
+ * Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
68
+ *
69
+ * @since 1.0.0-canary.6
70
+ */
71
+ export declare function isConsentRecord(value: unknown): value is ConsentRecord;
72
+ /**
73
+ * @since 1.0.0-canary.6
74
+ */
75
+ export interface ResolveDefaultConsentOptions {
76
+ /** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
77
+ hasGlobalPrivacyControlSignal: boolean;
78
+ mode: ConsentMode;
79
+ requestedCategories: ReadonlyArray<ConsentCategory>;
80
+ }
81
+ /**
82
+ * The effective consent before the visitor decides: opt-in regions start all-denied,
83
+ * opt-out regions grant the categories the app asks for.
84
+ *
85
+ * @remarks
86
+ * A Global Privacy Control signal is a "do not sell or share" opt-out (CCPA/CPRA), so it
87
+ * forces `ads` denied — it does not withdraw first-party analytics measurement.
88
+ *
89
+ * @since 0.5.0-canary.4
90
+ */
91
+ export declare function resolveDefaultConsent(options: ResolveDefaultConsentOptions): ConsentDecision;
92
+ /**
93
+ * Region-resolved consent defaults — typically from `resolveInitialConsent` on a
94
+ * per-request server lane, then handed to the client so it never re-guesses the mode.
95
+ *
96
+ * @remarks
97
+ * Drive UI and gates from `mode` (recompute `effectiveConsent` with live navigator GPC).
98
+ * `defaultConsent` is the server snapshot — useful when you need request-time `sec-gpc`
99
+ * as-is; analytics-only apps can ignore it because GPC only forces `ads` denied.
100
+ *
101
+ * @since 1.0.0-canary.6
102
+ */
103
+ export interface InitialConsent {
104
+ defaultConsent: ConsentDecision;
105
+ mode: ConsentMode;
106
+ region: ConsentRegion;
107
+ }
108
+ /**
109
+ * What shared HTML bakes and what an unknown-country request resolves to: all categories
110
+ * denied under opt-in — the one default that is safe to show any visitor anywhere.
111
+ * Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
112
+ * header means "unknown visitor", never "known non-EU visitor".
113
+ *
114
+ * @since 1.0.0-canary.6
115
+ */
116
+ export declare const STRICTEST_INITIAL_CONSENT: InitialConsent;
117
+ /**
118
+ * Guards an `InitialConsent` read from untrusted storage (a session cache, a cookie).
119
+ * Enforces the mode/region pairing rule; the one deliberate exception is
120
+ * {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
121
+ * mode, never looser.
122
+ *
123
+ * @since 1.0.0-canary.6
124
+ */
125
+ export declare function isInitialConsent(value: unknown): value is InitialConsent;
126
+ /**
127
+ * Vietnam's PDPL and GDPR both expect a record of *when* and *under what policy* consent
128
+ * was given, not just per-category flags — `policyVersion` lets a later policy change
129
+ * invalidate stale consent.
130
+ *
131
+ * @since 0.5.0-canary.4
132
+ */
133
+ export interface ConsentRecord {
134
+ decision: ConsentDecision;
135
+ policyVersion: string;
136
+ timestamp: number;
137
+ }
138
+ /**
139
+ * Persistence backend for the visitor's consent decision — swap in your own
140
+ * implementation for non-browser environments or a different persistence layer.
141
+ *
142
+ * @since 0.5.0-canary.4
143
+ */
144
+ export interface ConsentStorage {
145
+ clear: () => void;
146
+ load: () => ConsentRecord | undefined;
147
+ save: (record: ConsentRecord) => void;
148
+ /**
149
+ * Notify on any change to the stored record, including writes from other tabs — this
150
+ * is what drives `useConsent`'s external-store subscription. Returns an unsubscribe.
151
+ */
152
+ subscribe: (listener: () => void) => () => void;
153
+ }
154
+ /**
155
+ * The stored decision if one exists under the current `policyVersion`, normalized to drop
156
+ * any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
157
+ * it was recorded under a superseded policy version.
158
+ *
159
+ * @since 1.0.0-canary.6
160
+ */
161
+ export declare function readStoredDecision(storage: ConsentStorage, policyVersion: string): ConsentDecision | undefined;
162
+ /**
163
+ * @since 1.0.0-canary.6
164
+ */
165
+ export interface ResolveEffectiveConsentOptions {
166
+ /** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
167
+ hasGlobalPrivacyControlSignal: boolean;
168
+ mode: ConsentMode;
169
+ policyVersion: string;
170
+ requestedCategories: ReadonlyArray<ConsentCategory>;
171
+ storage: ConsentStorage;
172
+ }
173
+ /**
174
+ * The consent a tracker should honor right now: the stored decision if one exists, else
175
+ * the region default — the same rule `useConsent` applies to its `effectiveConsent`, so a
176
+ * non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
177
+ * "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
178
+ *
179
+ * @since 1.0.0-canary.6
180
+ */
181
+ export declare function resolveEffectiveConsent(options: ResolveEffectiveConsentOptions): ConsentDecision;
182
+ //# sourceMappingURL=consent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/core/consent.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,159 @@
1
+ /**
2
+ * @since 1.0.0-canary.6
3
+ */
4
+ export const CONSENT_REGIONS = ["eu", "other", "us", "vn"];
5
+ /**
6
+ * Guards a region read from untrusted storage (a cached `InitialConsent`, a cookie).
7
+ *
8
+ * @since 1.0.0-canary.6
9
+ */
10
+ export function isConsentRegion(value) {
11
+ return CONSENT_REGIONS.includes(value);
12
+ }
13
+ /**
14
+ * GDPR (EU) and the PDPL — Luật 91/2025/QH15 (VN) — require explicit opt-in before any non-essential
15
+ * tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
16
+ * that satisfies both, so the mode is resolved per region.
17
+ *
18
+ * @since 0.5.0-canary.4
19
+ */
20
+ export function resolveConsentMode(region) {
21
+ switch (region) {
22
+ case "eu":
23
+ case "vn": {
24
+ return "opt-in";
25
+ }
26
+ case "other":
27
+ case "us": {
28
+ return "opt-out";
29
+ }
30
+ }
31
+ }
32
+ /**
33
+ * @since 0.5.0-canary.4
34
+ */
35
+ export const CONSENT_CATEGORIES = ["ads", "analytics"];
36
+ /**
37
+ * A decision granting exactly the given categories and denying every other one.
38
+ *
39
+ * @since 0.5.0-canary.4
40
+ */
41
+ export function createConsentDecision(grantedCategories) {
42
+ return { ads: grantedCategories.includes("ads"), analytics: grantedCategories.includes("analytics") };
43
+ }
44
+ function isPlainObject(value) {
45
+ return typeof value === "object" && value !== null && !Array.isArray(value);
46
+ }
47
+ /**
48
+ * Guards stored JSON — the record is tamperable, so every category must be an explicit boolean.
49
+ *
50
+ * @since 0.5.0-canary.4
51
+ */
52
+ export function isConsentDecision(value) {
53
+ return isPlainObject(value) && CONSENT_CATEGORIES.every((category) => typeof value[category] === "boolean");
54
+ }
55
+ /**
56
+ * Re-derives a clean per-category decision from a tamperable record — extra keys are
57
+ * dropped, every category becomes an explicit boolean. The one normalization rule every
58
+ * reader of stored consent shares (e.g. `readStoredDecision`).
59
+ *
60
+ * @since 1.0.0-canary.6
61
+ */
62
+ export function normalizeConsentDecision(decision) {
63
+ return createConsentDecision(CONSENT_CATEGORIES.filter((category) => decision[category]));
64
+ }
65
+ /**
66
+ * Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
67
+ *
68
+ * @since 1.0.0-canary.6
69
+ */
70
+ export function isConsentRecord(value) {
71
+ return (isPlainObject(value) &&
72
+ isConsentDecision(value.decision) &&
73
+ typeof value.policyVersion === "string" &&
74
+ typeof value.timestamp === "number");
75
+ }
76
+ /**
77
+ * The effective consent before the visitor decides: opt-in regions start all-denied,
78
+ * opt-out regions grant the categories the app asks for.
79
+ *
80
+ * @remarks
81
+ * A Global Privacy Control signal is a "do not sell or share" opt-out (CCPA/CPRA), so it
82
+ * forces `ads` denied — it does not withdraw first-party analytics measurement.
83
+ *
84
+ * @since 0.5.0-canary.4
85
+ */
86
+ export function resolveDefaultConsent(options) {
87
+ const { hasGlobalPrivacyControlSignal, mode, requestedCategories } = options;
88
+ if (mode === "opt-in") {
89
+ return createConsentDecision([]);
90
+ }
91
+ const decision = createConsentDecision(requestedCategories);
92
+ if (hasGlobalPrivacyControlSignal) {
93
+ decision.ads = false;
94
+ }
95
+ return decision;
96
+ }
97
+ /**
98
+ * What shared HTML bakes and what an unknown-country request resolves to: all categories
99
+ * denied under opt-in — the one default that is safe to show any visitor anywhere.
100
+ * Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
101
+ * header means "unknown visitor", never "known non-EU visitor".
102
+ *
103
+ * @since 1.0.0-canary.6
104
+ */
105
+ export const STRICTEST_INITIAL_CONSENT = Object.freeze({
106
+ defaultConsent: Object.freeze(createConsentDecision([])),
107
+ mode: "opt-in",
108
+ region: "other",
109
+ });
110
+ /**
111
+ * Guards an `InitialConsent` read from untrusted storage (a session cache, a cookie).
112
+ * Enforces the mode/region pairing rule; the one deliberate exception is
113
+ * {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
114
+ * mode, never looser.
115
+ *
116
+ * @since 1.0.0-canary.6
117
+ */
118
+ export function isInitialConsent(value) {
119
+ if (!isPlainObject(value)) {
120
+ return false;
121
+ }
122
+ const mode = value.mode;
123
+ const region = value.region;
124
+ if ((mode !== "opt-in" && mode !== "opt-out") ||
125
+ !isConsentRegion(region) ||
126
+ !isConsentDecision(value.defaultConsent)) {
127
+ return false;
128
+ }
129
+ return (mode === resolveConsentMode(region) ||
130
+ (mode === STRICTEST_INITIAL_CONSENT.mode && region === STRICTEST_INITIAL_CONSENT.region));
131
+ }
132
+ /**
133
+ * The stored decision if one exists under the current `policyVersion`, normalized to drop
134
+ * any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
135
+ * it was recorded under a superseded policy version.
136
+ *
137
+ * @since 1.0.0-canary.6
138
+ */
139
+ export function readStoredDecision(storage, policyVersion) {
140
+ const record = storage.load();
141
+ if (record?.policyVersion !== policyVersion || !isConsentDecision(record.decision)) {
142
+ return undefined;
143
+ }
144
+ return normalizeConsentDecision(record.decision);
145
+ }
146
+ /**
147
+ * The consent a tracker should honor right now: the stored decision if one exists, else
148
+ * the region default — the same rule `useConsent` applies to its `effectiveConsent`, so a
149
+ * non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
150
+ * "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
151
+ *
152
+ * @since 1.0.0-canary.6
153
+ */
154
+ export function resolveEffectiveConsent(options) {
155
+ const { hasGlobalPrivacyControlSignal, mode, policyVersion, requestedCategories, storage } = options;
156
+ return (readStoredDecision(storage, policyVersion) ??
157
+ resolveDefaultConsent({ hasGlobalPrivacyControlSignal, mode, requestedCategories }));
158
+ }
159
+ //# sourceMappingURL=consent.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"consent.js","sourceRoot":"","sources":["../../src/core/consent.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
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 declare const ONE_YEAR_IN_SECONDS: number;
7
+ /**
8
+ * The value of `cookieName` inside a cookie string — a request `Cookie` header or
9
+ * `document.cookie`, which share the `name=value; name2=value2` wire format — or
10
+ * `undefined` when absent. The name must match exactly; a longer prefix sibling is ignored.
11
+ *
12
+ * @since 1.0.0-canary.6
13
+ */
14
+ export declare function readCookieValue(cookieString: string | null | undefined, cookieName: string): string | undefined;
15
+ //# sourceMappingURL=cookie.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/core/cookie.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAqB,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAc/G"}
@@ -0,0 +1,26 @@
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
+ * The value of `cookieName` inside a cookie string — a request `Cookie` header or
9
+ * `document.cookie`, which share the `name=value; name2=value2` wire format — or
10
+ * `undefined` when absent. The name must match exactly; a longer prefix sibling is ignored.
11
+ *
12
+ * @since 1.0.0-canary.6
13
+ */
14
+ export function readCookieValue(cookieString, cookieName) {
15
+ if (!cookieString) {
16
+ return undefined;
17
+ }
18
+ for (const part of cookieString.split(";")) {
19
+ const separatorIndex = part.indexOf("=");
20
+ if (separatorIndex !== -1 && part.slice(0, separatorIndex).trim() === cookieName) {
21
+ return part.slice(separatorIndex + 1).trim();
22
+ }
23
+ }
24
+ return undefined;
25
+ }
26
+ //# sourceMappingURL=cookie.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cookie.js","sourceRoot":"","sources":["../../src/core/cookie.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,YAAuC,EAAE,UAAkB;IACzF,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAEzC,IAAI,cAAc,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,KAAK,UAAU,EAAE,CAAC;YACjF,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}
@@ -0,0 +1,29 @@
1
+ import type { TrackedEvent } from "#/core/tracked-event";
2
+ /**
3
+ * Fan-out target for tracked events. The tracker depends only on this interface, never
4
+ * on a specific provider SDK — destinations own their transport (gtag.js and Vercel both
5
+ * queue and batch in-page), so `send` is fire-and-forget at track time.
6
+ *
7
+ * @since 0.5.0-canary.4
8
+ */
9
+ export interface Destination {
10
+ /**
11
+ * "exempt" keeps this destination receiving events while the tracker's analytics gate
12
+ * is closed — only for cookieless, identifier-free sinks: gated envelopes carry no
13
+ * `anonymousId`, and nothing is persisted.
14
+ *
15
+ * @defaultValue "required"
16
+ */
17
+ consentRequirement?: "exempt" | "required" | undefined;
18
+ name: string;
19
+ /**
20
+ * Erase this destination's trace of the subject on withdrawal (spec-data-subject-rights
21
+ * §3): clear the destination's cookies and stop sending, and — where the platform offers
22
+ * one — request per-visitor deletion. Optional: a sink with nothing to erase omits it.
23
+ * Invoked at most once per withdrawal; the tracker swallows its failures.
24
+ */
25
+ onErasure?: ((id: string) => Promise<void> | void) | undefined;
26
+ /** Must always return a `Promise` — mark `send` `async` even if the body has no `await`. */
27
+ send: (event: TrackedEvent) => Promise<void>;
28
+ }
29
+ //# sourceMappingURL=destination.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"destination.d.ts","sourceRoot":"","sources":["../../src/core/destination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IACvD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IAC/D,4FAA4F;IAC5F,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=destination.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"destination.js","sourceRoot":"","sources":["../../src/core/destination.ts"],"names":[],"mappings":""}
@@ -0,0 +1,35 @@
1
+ import type { StandardSchemaV1 } from "@standard-schema/spec";
2
+ /**
3
+ * One event's schema. Any Standard Schema library works (zod, zod/mini, valibot, ...) —
4
+ * the client bundle only pays for the one the app already ships.
5
+ *
6
+ * @since 0.5.0-canary.4
7
+ */
8
+ export interface EventDefinition<Schema extends StandardSchemaV1 = StandardSchemaV1> {
9
+ schema: Schema;
10
+ }
11
+ /**
12
+ * An app-defined map of event name to its definition. `@codefast/tracking` ships no
13
+ * events of its own — every consuming app builds and passes in its own catalog.
14
+ *
15
+ * @since 0.5.0-canary.4
16
+ */
17
+ export type EventCatalog = Record<string, EventDefinition>;
18
+ /**
19
+ * Identity helper for declaring a catalog with inference — nicer call-site than
20
+ * `satisfies EventCatalog` when the catalog is assembled across multiple files.
21
+ *
22
+ * @since 0.5.0-canary.4
23
+ */
24
+ export declare function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalog): Catalog;
25
+ /**
26
+ * Validates event properties against the catalog schema and returns the parsed output
27
+ * (unknown keys stripped / transforms applied) so destinations never see raw input.
28
+ *
29
+ * @throws Error when validation reports issues, or when the schema validates asynchronously —
30
+ * tracking sits on synchronous call paths, so async schemas are unsupported by design.
31
+ *
32
+ * @since 1.0.0-canary.6
33
+ */
34
+ export declare function assertValidEventProperties(schema: StandardSchemaV1, eventName: string, properties: unknown): unknown;
35
+ //# sourceMappingURL=event-catalog.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"event-catalog.d.ts","sourceRoot":"","sources":["../../src/core/event-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,SAAS,gBAAgB,GAAG,gBAAgB;IACjF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAcpH"}