@codefast/tracking 1.0.0-canary.6 → 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 (267) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +72 -17
  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.mts → browser-cookie.d.ts} +2 -4
  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} +3 -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.mts → gpc.d.ts} +2 -4
  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.mts → consent.d.ts} +49 -51
  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.mts → cookie.d.ts} +3 -5
  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.mts → event-id.d.ts} +2 -4
  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.mts → use-initial-consent.d.ts} +3 -6
  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.mts → region.d.ts} +5 -15
  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 +238 -59
  172. package/src/adapters/tanstack-start.ts +135 -0
  173. package/src/client/ad-framework-consent.ts +86 -0
  174. package/src/client/cookie-anonymous-id.ts +19 -0
  175. package/src/client/create-client-tracker.ts +81 -10
  176. package/src/client/server-persisted-anonymous-id.ts +4 -1
  177. package/src/core/consent-receipt.ts +115 -0
  178. package/src/core/consent.ts +2 -2
  179. package/src/core/destination.ts +7 -0
  180. package/src/core/event-catalog.ts +5 -4
  181. package/src/core/tracked-event.ts +5 -20
  182. package/src/destinations/ad-consent.ts +29 -0
  183. package/src/destinations/meta.ts +96 -0
  184. package/src/destinations/microsoft-uet.ts +86 -0
  185. package/src/destinations/tiktok.ts +85 -0
  186. package/src/index.ts +138 -19
  187. package/src/server/anonymous-id-cookie.ts +49 -22
  188. package/src/server/consent-receipt-store.ts +79 -0
  189. package/src/server/consent-receipt.ts +89 -0
  190. package/src/server/initial-consent.ts +0 -2
  191. package/src/server/measurement-protocol.ts +114 -0
  192. package/src/server/region.ts +0 -10
  193. package/src/server/user-deletion.ts +93 -0
  194. package/src/tooling/import-protection.ts +22 -0
  195. package/dist/client/browser-cookie.mjs +0 -15
  196. package/dist/client/consent-runtime.d.mts +0 -56
  197. package/dist/client/consent-runtime.mjs +0 -35
  198. package/dist/client/consent-storage.mjs +0 -82
  199. package/dist/client/consent-withdrawal.d.mts +0 -21
  200. package/dist/client/consent-withdrawal.mjs +0 -17
  201. package/dist/client/cookie-anonymous-id.d.mts +0 -37
  202. package/dist/client/cookie-anonymous-id.mjs +0 -46
  203. package/dist/client/create-client-tracker.d.mts +0 -32
  204. package/dist/client/create-client-tracker.mjs +0 -40
  205. package/dist/client/gpc.mjs +0 -14
  206. package/dist/client/index.d.mts +0 -10
  207. package/dist/client/index.mjs +0 -10
  208. package/dist/client/initial-consent-store.d.mts +0 -66
  209. package/dist/client/initial-consent-store.mjs +0 -119
  210. package/dist/client/is-analytics-allowed.d.mts +0 -29
  211. package/dist/client/is-analytics-allowed.mjs +0 -23
  212. package/dist/client/server-persisted-anonymous-id.d.mts +0 -33
  213. package/dist/client/server-persisted-anonymous-id.mjs +0 -50
  214. package/dist/core/consent-config.d.mts +0 -27
  215. package/dist/core/consent-config.mjs +0 -11
  216. package/dist/core/consent.mjs +0 -152
  217. package/dist/core/cookie.mjs +0 -23
  218. package/dist/core/destination.d.mts +0 -25
  219. package/dist/core/destination.mjs +0 -1
  220. package/dist/core/event-catalog.d.mts +0 -39
  221. package/dist/core/event-catalog.mjs +0 -30
  222. package/dist/core/event-id.mjs +0 -11
  223. package/dist/core/index.d.mts +0 -8
  224. package/dist/core/index.mjs +0 -6
  225. package/dist/core/tracked-event.d.mts +0 -30
  226. package/dist/core/tracked-event.mjs +0 -1
  227. package/dist/destinations/google-analytics.d.mts +0 -150
  228. package/dist/destinations/google-analytics.mjs +0 -130
  229. package/dist/destinations/google-consent.d.mts +0 -64
  230. package/dist/destinations/google-consent.mjs +0 -102
  231. package/dist/destinations/index.d.mts +0 -2
  232. package/dist/destinations/index.mjs +0 -2
  233. package/dist/destinations/shared.d.mts +0 -20
  234. package/dist/destinations/shared.mjs +0 -13
  235. package/dist/destinations/vercel-analytics.d.mts +0 -28
  236. package/dist/destinations/vercel-analytics.mjs +0 -23
  237. package/dist/import-protection.d.mts +0 -19
  238. package/dist/import-protection.mjs +0 -23
  239. package/dist/index.d.mts +0 -8
  240. package/dist/index.mjs +0 -6
  241. package/dist/react/consent-banner.d.mts +0 -180
  242. package/dist/react/consent-banner.mjs +0 -214
  243. package/dist/react/gtag-consent-bootstrap.d.mts +0 -27
  244. package/dist/react/gtag-consent-bootstrap.mjs +0 -29
  245. package/dist/react/index.d.mts +0 -6
  246. package/dist/react/index.mjs +0 -6
  247. package/dist/react/use-consent.d.mts +0 -45
  248. package/dist/react/use-consent.mjs +0 -71
  249. package/dist/react/use-google-consent-sync.d.mts +0 -23
  250. package/dist/react/use-google-consent-sync.mjs +0 -24
  251. package/dist/react/use-initial-consent.mjs +0 -19
  252. package/dist/server/anonymous-id-cookie.d.mts +0 -46
  253. package/dist/server/anonymous-id-cookie.mjs +0 -51
  254. package/dist/server/index.d.mts +0 -5
  255. package/dist/server/index.mjs +0 -4
  256. package/dist/server/initial-consent.d.mts +0 -29
  257. package/dist/server/initial-consent.mjs +0 -31
  258. package/dist/server/region.mjs +0 -77
  259. package/dist/tanstack-start/index.d.mts +0 -58
  260. package/dist/tanstack-start/index.mjs +0 -45
  261. package/src/client/index.ts +0 -28
  262. package/src/core/index.ts +0 -40
  263. package/src/destinations/index.ts +0 -19
  264. package/src/import-protection.ts +0 -20
  265. package/src/react/index.ts +0 -37
  266. package/src/server/index.ts +0 -16
  267. package/src/tanstack-start/index.ts +0 -83
@@ -0,0 +1,86 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { Destination } from "#/core/destination";
3
+ import { toAdConsentState } from "#/destinations/ad-consent";
4
+ import type { FlatPropertyValue } from "#/destinations/shared";
5
+ import { flattenEventProps } from "#/destinations/shared";
6
+
7
+ /**
8
+ * Microsoft UET consent. UET enforces **only** `ad_storage` — it has no `analytics_storage`,
9
+ * and its `ad_user_data`/`ad_personalization` fields have no documented behavior, so this
10
+ * models the one enforced signal (spec-destinations §5). Pushed via
11
+ * `uetq.push('consent','update', …)`.
12
+ *
13
+ * @since 1.0.0-canary.7
14
+ */
15
+ export interface MicrosoftUetConsent {
16
+ ad_storage: "denied" | "granted";
17
+ }
18
+
19
+ /**
20
+ * Maps a `ConsentDecision` to UET's enforced `ad_storage` signal via the shared ad lever, so
21
+ * it can't drift from Meta/TikTok — `ad_storage` is the inverse of Limited Data Use.
22
+ *
23
+ * @since 1.0.0-canary.7
24
+ */
25
+ export function toMicrosoftUetConsent(decision: ConsentDecision): MicrosoftUetConsent {
26
+ return { ad_storage: toAdConsentState(decision).limitedDataUse ? "denied" : "granted" };
27
+ }
28
+
29
+ /**
30
+ * The mapped per-event payload handed to a UET transport (`uetq.push`).
31
+ *
32
+ * @since 1.0.0-canary.7
33
+ */
34
+ export interface MicrosoftUetEventPayload {
35
+ consent: MicrosoftUetConsent;
36
+ name: string;
37
+ properties: Record<string, FlatPropertyValue>;
38
+ }
39
+
40
+ /**
41
+ * @since 1.0.0-canary.7
42
+ */
43
+ export interface MicrosoftUetDestinationOptions {
44
+ /** Erasure cookie-clear seam — UET exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
45
+ clearCookies?: (() => void) | undefined;
46
+ /** Read per event so an `ads` change updates `ad_storage` without recreating the destination. */
47
+ getDecision: () => ConsentDecision;
48
+ name?: string | undefined;
49
+ /**
50
+ * Delivers one mapped event — the transport seam. Wire it to `uetq.push(...)`; this package
51
+ * ships the consent mapping, never the tag id or network client.
52
+ */
53
+ transport: (payload: MicrosoftUetEventPayload) => Promise<void> | void;
54
+ }
55
+
56
+ /**
57
+ * Reference ad destination for Microsoft UET: maps each event and the live `ads` decision to
58
+ * UET's `ad_storage` signal, then hands it to an injected transport. Consent-restriction
59
+ * mapping only — the tag id and `uetq` transport are the integrator's. `consentRequirement`
60
+ * stays `"required"`.
61
+ *
62
+ * @since 1.0.0-canary.7
63
+ */
64
+ export function createMicrosoftUetDestination(options: MicrosoftUetDestinationOptions): Destination {
65
+ let stopped = false;
66
+
67
+ return {
68
+ consentRequirement: "required",
69
+ name: options.name ?? "microsoft-uet",
70
+ onErasure() {
71
+ stopped = true;
72
+ options.clearCookies?.();
73
+ },
74
+ async send(event) {
75
+ if (stopped) {
76
+ return;
77
+ }
78
+
79
+ await options.transport({
80
+ consent: toMicrosoftUetConsent(options.getDecision()),
81
+ name: event.name,
82
+ properties: flattenEventProps(event.properties),
83
+ });
84
+ },
85
+ };
86
+ }
@@ -0,0 +1,85 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { Destination } from "#/core/destination";
3
+ import { toAdConsentState } from "#/destinations/ad-consent";
4
+ import type { FlatPropertyValue } from "#/destinations/shared";
5
+ import { flattenEventProps } from "#/destinations/shared";
6
+
7
+ /**
8
+ * TikTok consent. TikTok uses a **single Limited Data Use boolean**, not Meta's
9
+ * `dataProcessingOptions` structure and no signal object (spec-destinations §5). Its
10
+ * transmission gate (`ttq.grantConsent()`/`revokeConsent()`) follows `analytics` and is the
11
+ * tracker's job; this models the `ads`-driven LDU lever.
12
+ *
13
+ * @since 1.0.0-canary.7
14
+ */
15
+ export interface TiktokConsent {
16
+ limited_data_use: boolean;
17
+ }
18
+
19
+ /**
20
+ * Maps a `ConsentDecision` to TikTok's LDU boolean — on when `ads` is denied.
21
+ *
22
+ * @since 1.0.0-canary.7
23
+ */
24
+ export function toTiktokConsent(decision: ConsentDecision): TiktokConsent {
25
+ return { limited_data_use: toAdConsentState(decision).limitedDataUse };
26
+ }
27
+
28
+ /**
29
+ * The mapped per-event payload handed to a TikTok transport (`ttq.track` / Events API).
30
+ *
31
+ * @since 1.0.0-canary.7
32
+ */
33
+ export interface TiktokEventPayload {
34
+ consent: TiktokConsent;
35
+ name: string;
36
+ properties: Record<string, FlatPropertyValue>;
37
+ }
38
+
39
+ /**
40
+ * @since 1.0.0-canary.7
41
+ */
42
+ export interface TiktokDestinationOptions {
43
+ /** Erasure cookie-clear seam — TikTok exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
44
+ clearCookies?: (() => void) | undefined;
45
+ /** Read per event so an `ads` change flips LDU without recreating the destination. */
46
+ getDecision: () => ConsentDecision;
47
+ name?: string | undefined;
48
+ /**
49
+ * Delivers one mapped event — the transport seam. Wire it to `ttq.track(...)` (Pixel) or the
50
+ * Events API; this package ships the consent mapping, never the pixel id or network client.
51
+ */
52
+ transport: (payload: TiktokEventPayload) => Promise<void> | void;
53
+ }
54
+
55
+ /**
56
+ * Reference ad destination for TikTok: maps each event and the live `ads` decision to
57
+ * TikTok's LDU boolean, then hands it to an injected transport. Consent-restriction mapping
58
+ * only — the pixel id and `ttq` transport are the integrator's. `consentRequirement` stays
59
+ * `"required"`.
60
+ *
61
+ * @since 1.0.0-canary.7
62
+ */
63
+ export function createTiktokDestination(options: TiktokDestinationOptions): Destination {
64
+ let stopped = false;
65
+
66
+ return {
67
+ consentRequirement: "required",
68
+ name: options.name ?? "tiktok",
69
+ onErasure() {
70
+ stopped = true;
71
+ options.clearCookies?.();
72
+ },
73
+ async send(event) {
74
+ if (stopped) {
75
+ return;
76
+ }
77
+
78
+ await options.transport({
79
+ consent: toTiktokConsent(options.getDecision()),
80
+ name: event.name,
81
+ properties: flattenEventProps(event.properties),
82
+ });
83
+ },
84
+ };
85
+ }
package/src/index.ts CHANGED
@@ -5,47 +5,166 @@
5
5
  * catalog over any Standard Schema library, wire a `ConsentConfig` + `createConsentRuntime`,
6
6
  * and fan tracked events out to gtag / Vercel Analytics destinations.
7
7
  *
8
- * - **Root** (this module): isomorphic catalog types, `Destination`, consent model + config — safe to import from both client and server code.
9
- * - **`@codefast/tracking/client`**: `createClientTracker`, `createConsentRuntime`, anonymous-id helpers.
10
- * - **`@codefast/tracking/server`**: region → initial-consent resolution, anonymous-id `Set-Cookie` builders. Server-only — never import from client code.
11
- * - **`@codefast/tracking/tanstack-start`**: request/response glue over TanStack Start's server context. Server-only — deny it in the client environment via Start's `importProtection`.
12
- * - **`@codefast/tracking/destinations`**: the gtag destination, script loader, and Consent Mode bootstrap; Vercel Analytics lives on its own subpath.
8
+ * This root is the client entry: it re-exports the isomorphic core plus the whole
9
+ * browser-side surface (tracker, consent runtime, React bindings, client destinations).
10
+ * Server-only lanes are their own subpaths and never belong here — `@codefast/tracking/server/*`
11
+ * and `@codefast/tracking/adapters/*` (deny them in the client environment via
12
+ * `SERVER_ONLY_SUBPATHS`). The Vercel destination stays on `@codefast/tracking/destinations/
13
+ * vercel-analytics` so its `@vercel/analytics` peer is only pulled in when used.
13
14
  */
15
+
16
+ // ── Core (isomorphic) ───────────────────────────────────────────────────────────────
14
17
  export type {
15
18
  ConsentCategory,
16
- ConsentConfig,
17
19
  ConsentDecision,
18
20
  ConsentMode,
19
21
  ConsentRecord,
20
22
  ConsentRegion,
21
23
  ConsentStorage,
22
- Destination,
23
- EventCatalog,
24
- EventDefinition,
25
24
  InitialConsent,
26
25
  ResolveDefaultConsentOptions,
27
26
  ResolveEffectiveConsentOptions,
28
- TrackedEvent,
29
- TrackedEventBase,
30
- TrackEvent,
31
- } from "#/core";
27
+ } from "#/core/consent";
32
28
  export {
33
- assertValidEventProperties,
34
29
  CONSENT_CATEGORIES,
35
30
  CONSENT_REGIONS,
36
31
  createConsentDecision,
37
- defineConsentConfig,
38
- defineEventCatalog,
39
- generateEventId,
40
32
  isConsentDecision,
41
33
  isConsentRecord,
42
34
  isConsentRegion,
43
35
  isInitialConsent,
44
36
  normalizeConsentDecision,
45
- readCookieValue,
46
37
  readStoredDecision,
47
38
  resolveConsentMode,
48
39
  resolveDefaultConsent,
49
40
  resolveEffectiveConsent,
50
41
  STRICTEST_INITIAL_CONSENT,
51
- } from "#/core";
42
+ } from "#/core/consent";
43
+
44
+ export type { ConsentConfig } from "#/core/consent-config";
45
+ export { defineConsentConfig } from "#/core/consent-config";
46
+
47
+ export type {
48
+ ConsentReceipt,
49
+ ConsentReceiptEventType,
50
+ ConsentReceiptInput,
51
+ ConsentReceiptMethod,
52
+ ConsentReceiptSubjectIdType,
53
+ } from "#/core/consent-receipt";
54
+ export { isConsentReceiptInput } from "#/core/consent-receipt";
55
+
56
+ export { readCookieValue } from "#/core/cookie";
57
+
58
+ export type { Destination } from "#/core/destination";
59
+
60
+ export type { EventCatalog, EventDefinition } from "#/core/event-catalog";
61
+ export { assertValidEventProperties, defineEventCatalog } from "#/core/event-catalog";
62
+
63
+ export { generateEventId } from "#/core/event-id";
64
+
65
+ export type { TrackedEvent } from "#/core/tracked-event";
66
+
67
+ // ── Client ──────────────────────────────────────────────────────────────────────────
68
+ export type { CmpConsentSignal, CmpStatus, ReconcileAdFrameworkConsentOptions } from "#/client/ad-framework-consent";
69
+ export { hasGppApi, hasTcfApi, reconcileAdFrameworkConsent } from "#/client/ad-framework-consent";
70
+
71
+ export type { ConsentRuntime, ConsentRuntimeOptions } from "#/client/consent-runtime";
72
+ export { createConsentRuntime } from "#/client/consent-runtime";
73
+
74
+ export { createLocalStorageConsentStorage } from "#/client/consent-storage";
75
+
76
+ export type { ConsentWithdrawalHandlerOptions } from "#/client/consent-withdrawal";
77
+ export { createConsentWithdrawalHandler } from "#/client/consent-withdrawal";
78
+
79
+ export type { CookieAnonymousId, CookieAnonymousIdOptions } from "#/client/cookie-anonymous-id";
80
+ export { createCookieAnonymousId } from "#/client/cookie-anonymous-id";
81
+
82
+ export type { ClientTracker, ClientTrackerOptions, DeliveryErrorContext } from "#/client/create-client-tracker";
83
+ export { createClientTracker } from "#/client/create-client-tracker";
84
+
85
+ export { hasGlobalPrivacyControlSignal } from "#/client/gpc";
86
+
87
+ export type {
88
+ InitialConsentSnapshot,
89
+ InitialConsentStore,
90
+ InitialConsentStoreOptions,
91
+ } from "#/client/initial-consent-store";
92
+ export { createInitialConsentStore } from "#/client/initial-consent-store";
93
+
94
+ export type { IsAnalyticsAllowedOptions } from "#/client/is-analytics-allowed";
95
+ export { createIsAnalyticsAllowed } from "#/client/is-analytics-allowed";
96
+
97
+ export type { ServerPersistedAnonymousIdOptions } from "#/client/server-persisted-anonymous-id";
98
+ export { createServerPersistedAnonymousId } from "#/client/server-persisted-anonymous-id";
99
+
100
+ // ── React ───────────────────────────────────────────────────────────────────────────
101
+ export type {
102
+ ConsentBannerAcceptProps,
103
+ ConsentBannerActionsProps,
104
+ ConsentBannerCategoryProps,
105
+ ConsentBannerCustomizeProps,
106
+ ConsentBannerDescriptionProps,
107
+ ConsentBannerPreferencesProps,
108
+ ConsentBannerProps,
109
+ ConsentBannerRejectProps,
110
+ ConsentBannerSaveProps,
111
+ ConsentBannerTitleProps,
112
+ ConsentToggleProps,
113
+ } from "#/react/consent-banner";
114
+ export {
115
+ ConsentBanner,
116
+ ConsentBannerAccept,
117
+ ConsentBannerActions,
118
+ ConsentBannerCategory,
119
+ ConsentBannerCustomize,
120
+ ConsentBannerDescription,
121
+ ConsentBannerPreferences,
122
+ ConsentBannerReject,
123
+ ConsentBannerSave,
124
+ ConsentBannerTitle,
125
+ ConsentToggle,
126
+ } from "#/react/consent-banner";
127
+
128
+ export type { GtagConsentBootstrapProps } from "#/react/gtag-consent-bootstrap";
129
+ export { GtagConsentBootstrap } from "#/react/gtag-consent-bootstrap";
130
+
131
+ export type { UseConsentOptions, UseConsentResult } from "#/react/use-consent";
132
+ export { useConsent } from "#/react/use-consent";
133
+
134
+ export type { UseGoogleConsentSyncOptions } from "#/react/use-google-consent-sync";
135
+ export { useGoogleConsentSync } from "#/react/use-google-consent-sync";
136
+
137
+ export { useInitialConsent } from "#/react/use-initial-consent";
138
+
139
+ // ── Destinations (client-lane; Vercel stays on its own subpath) ───────────────────────
140
+ export type { AdConsentState } from "#/destinations/ad-consent";
141
+ export { toAdConsentState } from "#/destinations/ad-consent";
142
+
143
+ export type {
144
+ EnsureGtagOptions,
145
+ GoogleAnalyticsDestinationOptions,
146
+ GtagConsentBootstrapOptions,
147
+ GtagFunction,
148
+ LoadGtagScriptOptions,
149
+ } from "#/destinations/google-analytics";
150
+ export {
151
+ buildGtagConsentBootstrapScript,
152
+ clearGoogleAnalyticsCookies,
153
+ createGoogleAnalyticsDestination,
154
+ ensureGtag,
155
+ loadGtagScript,
156
+ updateGoogleConsent,
157
+ } from "#/destinations/google-analytics";
158
+
159
+ export type { MetaDataProcessingOptions, MetaDestinationOptions, MetaEventPayload } from "#/destinations/meta";
160
+ export { createMetaDestination, toMetaDataProcessingOptions } from "#/destinations/meta";
161
+
162
+ export type {
163
+ MicrosoftUetConsent,
164
+ MicrosoftUetDestinationOptions,
165
+ MicrosoftUetEventPayload,
166
+ } from "#/destinations/microsoft-uet";
167
+ export { createMicrosoftUetDestination, toMicrosoftUetConsent } from "#/destinations/microsoft-uet";
168
+
169
+ export type { TiktokConsent, TiktokDestinationOptions, TiktokEventPayload } from "#/destinations/tiktok";
170
+ export { createTiktokDestination, toTiktokConsent } from "#/destinations/tiktok";
@@ -6,16 +6,23 @@ const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{
6
6
  // Conservative subset of the RFC 6265 cookie-name token.
7
7
  const COOKIE_NAME_PATTERN = /^[\w-]+$/;
8
8
 
9
- function assertCookieName(cookieName: string): void {
9
+ /**
10
+ * Guards the cookie name against anything outside the RFC 6265 token set.
11
+ *
12
+ * @throws Error when `cookieName` is not a valid token.
13
+ *
14
+ * @since 1.0.0-canary.7
15
+ */
16
+ export function assertValidAnonymousIdCookieName(cookieName: string): void {
10
17
  if (!COOKIE_NAME_PATTERN.test(cookieName)) {
11
18
  throw new Error(`Invalid anonymous-id cookie name: ${JSON.stringify(cookieName)}`);
12
19
  }
13
20
  }
14
21
 
15
22
  /**
16
- * Whether a value is safe to persist as an anonymous id. The persist endpoint is public
17
- * and echoes its input into a response header, so only an exactly-UUID-shaped value may
18
- * pass — anything else is a header-injection attempt or corruption, never a valid id.
23
+ * Whether a value is safe to persist as an anonymous id. The persist endpoint is public and
24
+ * writes its input into a `Set-Cookie`, so only an exactly-UUID-shaped value may pass —
25
+ * anything else is a header-injection attempt or corruption, never a valid id.
19
26
  *
20
27
  * @since 1.0.0-canary.6
21
28
  */
@@ -26,7 +33,7 @@ export function isValidAnonymousId(value: string): boolean {
26
33
  /**
27
34
  * @since 1.0.0-canary.6
28
35
  */
29
- export interface AnonymousIdSetCookieOptions {
36
+ export interface AnonymousIdCookieOptions {
30
37
  /** Cookie name — must match what the client tracker reads. */
31
38
  cookieName: string;
32
39
  /** The client-minted id to persist — throws unless it is exactly UUID-shaped. */
@@ -36,41 +43,61 @@ export interface AnonymousIdSetCookieOptions {
36
43
  }
37
44
 
38
45
  /**
39
- * `Set-Cookie` header value that persists (or prolongs) a client-minted anonymous id from
40
- * the server. A server-set cookie escapes Safari ITP's 7-day cap on `document.cookie`
41
- * writes, so the id actually lives its full max-age. The server only ever re-sets an id
42
- * the client hands it — minting stays client-side, after consent, by design.
46
+ * The validated name/value plus cookie attributes for persisting a client-minted anonymous
47
+ * id from the server — feed straight into the framework's cookie helper (`setCookie`).
43
48
  *
44
49
  * @remarks
45
50
  * Always `Secure` — on a plain-HTTP dev origin a browser may drop it, and the
46
51
  * client-written cookie (`createServerPersistedAnonymousId`'s optimistic write) still
47
- * covers that session. Not `HttpOnly`: the client tracker must read the id to stamp it
48
- * onto events.
52
+ * covers that session. Not `httpOnly`: the client tracker must read the id to stamp it onto
53
+ * events. A server-set cookie escapes Safari ITP's 7-day cap on `document.cookie` writes, so
54
+ * the id actually lives its full max-age. The server only ever re-sets an id the client
55
+ * hands it — minting stays client-side, after consent, by design.
49
56
  *
50
57
  * @throws Error when `id` is not UUID-shaped or `cookieName` is not a valid token.
51
58
  *
52
59
  * @since 1.0.0-canary.6
53
60
  */
54
- export function buildAnonymousIdSetCookie(options: AnonymousIdSetCookieOptions): string {
55
- const { cookieName, id, maxAgeSeconds = ONE_YEAR_IN_SECONDS } = options;
56
-
57
- assertCookieName(cookieName);
61
+ export function resolveAnonymousIdCookie(options: AnonymousIdCookieOptions): {
62
+ maxAge: number;
63
+ name: string;
64
+ path: string;
65
+ sameSite: "lax";
66
+ secure: true;
67
+ value: string;
68
+ } {
69
+ assertValidAnonymousIdCookieName(options.cookieName);
58
70
 
59
- if (!isValidAnonymousId(id)) {
71
+ if (!isValidAnonymousId(options.id)) {
60
72
  throw new Error("Invalid anonymous id: expected a UUID-shaped value");
61
73
  }
62
74
 
63
- return `${cookieName}=${id}; Path=/; Max-Age=${String(maxAgeSeconds)}; SameSite=Lax; Secure`;
75
+ return {
76
+ maxAge: options.maxAgeSeconds ?? ONE_YEAR_IN_SECONDS,
77
+ name: options.cookieName,
78
+ path: "/",
79
+ sameSite: "lax",
80
+ secure: true,
81
+ value: options.id,
82
+ };
64
83
  }
65
84
 
66
85
  /**
67
- * `Set-Cookie` header value that expires the anonymous-id cookie — the server half of a
68
- * consent withdrawal, alongside the client's own `document.cookie` expiry.
86
+ * Name plus attributes for expiring the anonymous-id cookie — the server half of a consent
87
+ * withdrawal. Attributes must match {@link resolveAnonymousIdCookie} so the browser targets
88
+ * the same cookie. Feed into the framework's `deleteCookie`.
89
+ *
90
+ * @throws Error when `cookieName` is not a valid token.
69
91
  *
70
92
  * @since 1.0.0-canary.6
71
93
  */
72
- export function buildClearAnonymousIdSetCookie(cookieName: string): string {
73
- assertCookieName(cookieName);
94
+ export function resolveClearAnonymousIdCookie(cookieName: string): {
95
+ name: string;
96
+ path: string;
97
+ sameSite: "lax";
98
+ secure: true;
99
+ } {
100
+ assertValidAnonymousIdCookieName(cookieName);
74
101
 
75
- return `${cookieName}=; Path=/; Max-Age=0; SameSite=Lax; Secure`;
102
+ return { name: cookieName, path: "/", sameSite: "lax", secure: true };
76
103
  }
@@ -0,0 +1,79 @@
1
+ import type { ConsentReceipt } from "#/core/consent-receipt";
2
+
3
+ /**
4
+ * Persistence backend for consent receipts — the durable store is the consumer's to supply
5
+ * (a database, an append-only log). The store is **append-only**: `append` never overwrites,
6
+ * and an update/withdrawal is a new receipt referencing the prior one (spec-consent-receipts §3).
7
+ * May be async so a real backend can await its write.
8
+ *
9
+ * @since 1.0.0-canary.7
10
+ */
11
+ export interface ReceiptStore {
12
+ append: (receipt: ConsentReceipt) => Promise<void> | void;
13
+ get: (receiptId: string) => ConsentReceipt | undefined | Promise<ConsentReceipt | undefined>;
14
+ }
15
+
16
+ /**
17
+ * An in-memory {@link ReceiptStore} for development and tests — **not** durable across a
18
+ * process restart, and not a lawful production store on its own. A real deployment supplies
19
+ * a database-backed implementation; this exists so the endpoint is runnable end-to-end
20
+ * without standing up storage first.
21
+ *
22
+ * @remarks
23
+ * Append is idempotent-by-id: re-appending the same `receiptId` is ignored, preserving the
24
+ * append-only guarantee even if a client retries.
25
+ *
26
+ * @since 1.0.0-canary.7
27
+ */
28
+ export function createInMemoryReceiptStore(): ReceiptStore {
29
+ const receipts = new Map<string, ConsentReceipt>();
30
+
31
+ return {
32
+ append(receipt: ConsentReceipt): void {
33
+ if (!receipts.has(receipt.receiptId)) {
34
+ receipts.set(receipt.receiptId, receipt);
35
+ }
36
+ },
37
+ get(receiptId: string): ConsentReceipt | undefined {
38
+ return receipts.get(receiptId);
39
+ },
40
+ };
41
+ }
42
+
43
+ /**
44
+ * The minimal id-keyed primitive a durable backend must expose for {@link createDurableReceiptStore}.
45
+ * Keeping it this small lets an integrator back receipts with any store (Vercel KV, Postgres,
46
+ * an append-only log) by implementing two methods rather than the full {@link ReceiptStore}.
47
+ *
48
+ * @since 1.0.0-canary.7
49
+ */
50
+ export interface ReceiptStoreBackend {
51
+ get: (receiptId: string) => Promise<ConsentReceipt | undefined>;
52
+ /**
53
+ * Persist one receipt under its id. MUST be idempotent-by-id and never overwrite — a
54
+ * duplicate `receiptId` is a no-op — so the append-only guarantee holds atomically even
55
+ * under a client retry or concurrent write (e.g. KV set-if-absent, Postgres
56
+ * `INSERT … ON CONFLICT DO NOTHING`). The frame delegates rather than doing a racy
57
+ * get-then-put itself.
58
+ */
59
+ put: (receiptId: string, receipt: ConsentReceipt) => Promise<void>;
60
+ }
61
+
62
+ /**
63
+ * A durable {@link ReceiptStore} over an injected {@link ReceiptStoreBackend} — the package
64
+ * supplies the append-only contract and adaptation, the deployment supplies the backend
65
+ * client (no database dependency is baked in). Pair it with a real backend in production,
66
+ * where {@link createInMemoryReceiptStore} is not a lawful store on its own.
67
+ *
68
+ * @since 1.0.0-canary.7
69
+ */
70
+ export function createDurableReceiptStore(options: { backend: ReceiptStoreBackend }): ReceiptStore {
71
+ return {
72
+ async append(receipt: ConsentReceipt): Promise<void> {
73
+ await options.backend.put(receipt.receiptId, receipt);
74
+ },
75
+ async get(receiptId: string): Promise<ConsentReceipt | undefined> {
76
+ return options.backend.get(receiptId);
77
+ },
78
+ };
79
+ }
@@ -0,0 +1,89 @@
1
+ import type { ConsentReceipt, ConsentReceiptInput } from "#/core/consent-receipt";
2
+
3
+ /**
4
+ * The receipt information-structure version this builder emits (ISO/IEC TS 27560-shaped).
5
+ * Bump when the receipt field set changes; stored receipts carry it so a reader can migrate.
6
+ *
7
+ * @since 1.0.0-canary.7
8
+ */
9
+ export const RECEIPT_SCHEMA_VERSION = "1.0.0";
10
+
11
+ const IPV4_PATTERN = /^(\d{1,3}\.){3}\d{1,3}$/;
12
+
13
+ /**
14
+ * Coarsens an IP for storage — a full address MUST never be persisted (spec-consent-receipts
15
+ * §4, R5). IPv4 drops the last two octets; IPv6 keeps only the first two hextets. This mirrors
16
+ * the Cookiebot-style anonymization cited in the spec and is the maximally-private default;
17
+ * a controller may widen it under counsel, but the builder never returns a full address.
18
+ * Returns `undefined` for a missing or malformed input rather than storing a bad value.
19
+ *
20
+ * @since 1.0.0-canary.7
21
+ */
22
+ export function coarsenIp(ip: string | null | undefined): string | undefined {
23
+ if (!ip) {
24
+ return undefined;
25
+ }
26
+
27
+ const trimmed = ip.trim();
28
+
29
+ if (IPV4_PATTERN.test(trimmed)) {
30
+ const octets = trimmed.split(".");
31
+
32
+ // Reject out-of-range octets (e.g. "999.1.1.1") rather than storing a malformed coarse value.
33
+ if (octets.some((octet) => Number(octet) > 255)) {
34
+ return undefined;
35
+ }
36
+
37
+ return `${octets[0]}.${octets[1]}.0.0`;
38
+ }
39
+
40
+ if (trimmed.includes(":")) {
41
+ const [first, second] = trimmed.split(":");
42
+
43
+ // Require two explicit leading hextets — a compressed-leading address ("::1", "fe80::1")
44
+ // can't be coarsened without full expansion, so degrade to no stored value.
45
+ if (!first || !second) {
46
+ return undefined;
47
+ }
48
+
49
+ return `${first}:${second}::`;
50
+ }
51
+
52
+ return undefined;
53
+ }
54
+
55
+ /**
56
+ * @remarks
57
+ * `sign` is optional so the package never bakes a crypto secret: supply an HMAC/signature
58
+ * function to stamp an `integrityKey`, letting a client prove its state matches the stored
59
+ * original (spec-consent-receipts §5). Omit it and receipts carry no integrity key.
60
+ *
61
+ * @since 1.0.0-canary.7
62
+ */
63
+ export interface BuildConsentReceiptOptions {
64
+ input: ConsentReceiptInput;
65
+ /** The connection IP, read server-side — never accepted from the request body. */
66
+ rawIp?: string | null | undefined;
67
+ sign?: ((receipt: Omit<ConsentReceipt, "integrityKey">) => string) | undefined;
68
+ }
69
+
70
+ /**
71
+ * Builds a stored consent receipt from caller input plus server-derived fields
72
+ * (`receiptId`, `timestamp`, coarsened IP, optional `integrityKey`). Pure except for the
73
+ * id/clock it stamps — pass those in via a seam if a deterministic build is needed.
74
+ *
75
+ * @since 1.0.0-canary.7
76
+ */
77
+ export function buildConsentReceipt(options: BuildConsentReceiptOptions): ConsentReceipt {
78
+ const base: Omit<ConsentReceipt, "integrityKey"> = {
79
+ ...options.input,
80
+ ipCoarse: coarsenIp(options.rawIp),
81
+ receiptId: crypto.randomUUID(),
82
+ schemaVersion: RECEIPT_SCHEMA_VERSION,
83
+ timestamp: Date.now(),
84
+ };
85
+
86
+ const integrityKey = options.sign?.(base);
87
+
88
+ return integrityKey === undefined ? base : { ...base, integrityKey };
89
+ }
@@ -2,8 +2,6 @@ import type { ConsentCategory, InitialConsent } from "#/core/consent";
2
2
  import { resolveConsentMode, resolveDefaultConsent, STRICTEST_INITIAL_CONSENT } from "#/core/consent";
3
3
  import { resolveRegionFromCountryCode } from "#/server/region";
4
4
 
5
- export type { InitialConsent };
6
-
7
5
  /**
8
6
  * @since 1.0.0-canary.6
9
7
  */