@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
@@ -1,10 +0,0 @@
1
- import { createLocalStorageConsentStorage } from "./consent-storage.mjs";
2
- import { hasGlobalPrivacyControlSignal } from "./gpc.mjs";
3
- import { createInitialConsentStore } from "./initial-consent-store.mjs";
4
- import { createIsAnalyticsAllowed } from "./is-analytics-allowed.mjs";
5
- import { createConsentRuntime } from "./consent-runtime.mjs";
6
- import { createConsentWithdrawalHandler } from "./consent-withdrawal.mjs";
7
- import { createCookieAnonymousId } from "./cookie-anonymous-id.mjs";
8
- import { createClientTracker } from "./create-client-tracker.mjs";
9
- import { createServerPersistedAnonymousId } from "./server-persisted-anonymous-id.mjs";
10
- export { createClientTracker, createConsentRuntime, createConsentWithdrawalHandler, createCookieAnonymousId, createInitialConsentStore, createIsAnalyticsAllowed, createLocalStorageConsentStorage, createServerPersistedAnonymousId, hasGlobalPrivacyControlSignal };
@@ -1,66 +0,0 @@
1
- import { InitialConsent } from "../core/consent.mjs";
2
-
3
- //#region src/client/initial-consent-store.d.ts
4
- /**
5
- * External-store view of the visitor's region default — the strictest value until the
6
- * server lane answers, then the resolved one.
7
- *
8
- * @since 1.0.0-canary.6
9
- */
10
- interface InitialConsentSnapshot {
11
- /** The region-correct default once resolved; {@link STRICTEST_INITIAL_CONSENT} until then. */
12
- initialConsent: InitialConsent;
13
- /**
14
- * True once a usable default is published — either a successful server answer or a
15
- * fail-closed fallback. A failed fetch still sets this so consent UI can render, but
16
- * does not lock the session: resolution stays retryable.
17
- */
18
- isResolved: boolean;
19
- }
20
- /**
21
- * @since 1.0.0-canary.6
22
- */
23
- interface InitialConsentStoreOptions {
24
- /**
25
- * The per-visitor server lane — typically a server function wrapping
26
- * `resolveInitialConsentFromRequest`. Prerendered/CDN-cached HTML can carry nothing
27
- * region-specific, so this is the only place the region-correct default may come from.
28
- */
29
- resolve: () => Promise<InitialConsent>;
30
- /**
31
- * `sessionStorage` key caching the resolved value, so only the first page load of a
32
- * session pays the round trip — omit to resolve once per page load instead. Cached
33
- * values are re-validated with `isInitialConsent` before use.
34
- */
35
- sessionStorageKey?: string | undefined;
36
- }
37
- /**
38
- * `useSyncExternalStore`-shaped — pass `subscribe`/`getSnapshot`/`getServerSnapshot`
39
- * straight through, or use the `useInitialConsent` hook from `@codefast/tracking/react`.
40
- *
41
- * @since 1.0.0-canary.6
42
- */
43
- interface InitialConsentStore {
44
- /**
45
- * Kicks off region resolution (at most one in-flight request; a success is sticky for
46
- * the store's lifetime). Call it early — e.g. at router creation, window-guarded — so
47
- * the round trip overlaps hydration instead of waiting for the first effect.
48
- */
49
- ensureResolved: () => void;
50
- getServerSnapshot: () => InitialConsentSnapshot;
51
- getSnapshot: () => InitialConsentSnapshot;
52
- /** Test seam — clears resolved state, retry listeners, and the session cache. */
53
- reset: () => void;
54
- subscribe: (listener: () => void) => () => void;
55
- }
56
- /**
57
- * The client half of the server-resolved consent lane: single-flight resolution over the
58
- * given server function, an optional per-session cache, fail-closed publishing on error
59
- * (consent UI still renders, under the strictest default), and a retry the next time the
60
- * tab becomes visible — so one failed request never locks the whole SPA session.
61
- *
62
- * @since 1.0.0-canary.6
63
- */
64
- declare function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore;
65
- //#endregion
66
- export { InitialConsentSnapshot, InitialConsentStore, InitialConsentStoreOptions, createInitialConsentStore };
@@ -1,119 +0,0 @@
1
- import { STRICTEST_INITIAL_CONSENT, isInitialConsent } from "../core/consent.mjs";
2
- //#region src/client/initial-consent-store.ts
3
- const SERVER_SNAPSHOT = {
4
- initialConsent: STRICTEST_INITIAL_CONSENT,
5
- isResolved: false
6
- };
7
- /**
8
- * The client half of the server-resolved consent lane: single-flight resolution over the
9
- * given server function, an optional per-session cache, fail-closed publishing on error
10
- * (consent UI still renders, under the strictest default), and a retry the next time the
11
- * tab becomes visible — so one failed request never locks the whole SPA session.
12
- *
13
- * @since 1.0.0-canary.6
14
- */
15
- function createInitialConsentStore(options) {
16
- const listeners = /* @__PURE__ */ new Set();
17
- let snapshot = SERVER_SNAPSHOT;
18
- let isFetchInFlight = false;
19
- /** Sticky only after a successful resolve (or session-cache hit) — failures stay retryable. */
20
- let hasResolvedSuccessfully = false;
21
- function notify() {
22
- for (const listener of listeners) listener();
23
- }
24
- function stopResolveRetry() {
25
- if (typeof window === "undefined") return;
26
- document.removeEventListener("visibilitychange", onResolveRetryResume);
27
- window.removeEventListener("pageshow", onResolveRetryResume);
28
- window.removeEventListener("online", onResolveRetryResume);
29
- }
30
- function onResolveRetryResume() {
31
- if (hasResolvedSuccessfully) {
32
- stopResolveRetry();
33
- return;
34
- }
35
- if (document.visibilityState === "visible") ensureResolved();
36
- }
37
- /**
38
- * After a failed fetch, retry when the tab becomes visible again or connectivity
39
- * returns (coalesced by in-flight) — a visitor who never leaves the tab must not stay
40
- * fail-closed for the whole session over one network blip.
41
- */
42
- function scheduleResolveRetry() {
43
- if (typeof window === "undefined") return;
44
- document.addEventListener("visibilitychange", onResolveRetryResume);
45
- window.addEventListener("pageshow", onResolveRetryResume);
46
- window.addEventListener("online", onResolveRetryResume);
47
- }
48
- function publishResolved(initialConsent) {
49
- hasResolvedSuccessfully = true;
50
- snapshot = {
51
- initialConsent,
52
- isResolved: true
53
- };
54
- stopResolveRetry();
55
- notify();
56
- }
57
- /** Fail-closed UI without permanently locking the session against a later retry. */
58
- function publishFailClosed() {
59
- snapshot = {
60
- initialConsent: STRICTEST_INITIAL_CONSENT,
61
- isResolved: true
62
- };
63
- notify();
64
- }
65
- function readSessionCache() {
66
- if (options.sessionStorageKey === void 0) return;
67
- try {
68
- const raw = window.sessionStorage.getItem(options.sessionStorageKey);
69
- const parsed = raw === null ? void 0 : JSON.parse(raw);
70
- return isInitialConsent(parsed) ? parsed : void 0;
71
- } catch {
72
- return;
73
- }
74
- }
75
- function writeSessionCache(resolved) {
76
- if (options.sessionStorageKey === void 0) return;
77
- try {
78
- window.sessionStorage.setItem(options.sessionStorageKey, JSON.stringify(resolved));
79
- } catch {}
80
- }
81
- function ensureResolved() {
82
- if (hasResolvedSuccessfully || isFetchInFlight || typeof window === "undefined") return;
83
- const cached = readSessionCache();
84
- if (cached) {
85
- publishResolved(cached);
86
- return;
87
- }
88
- isFetchInFlight = true;
89
- Promise.resolve().then(() => options.resolve()).then((resolved) => {
90
- writeSessionCache(resolved);
91
- publishResolved(resolved);
92
- }).catch(() => {
93
- publishFailClosed();
94
- scheduleResolveRetry();
95
- }).finally(() => {
96
- isFetchInFlight = false;
97
- });
98
- }
99
- return {
100
- ensureResolved,
101
- getServerSnapshot: () => SERVER_SNAPSHOT,
102
- getSnapshot: () => snapshot,
103
- reset() {
104
- stopResolveRetry();
105
- snapshot = SERVER_SNAPSHOT;
106
- isFetchInFlight = false;
107
- hasResolvedSuccessfully = false;
108
- if (typeof window !== "undefined" && options.sessionStorageKey !== void 0) window.sessionStorage.removeItem(options.sessionStorageKey);
109
- },
110
- subscribe(listener) {
111
- listeners.add(listener);
112
- return () => {
113
- listeners.delete(listener);
114
- };
115
- }
116
- };
117
- }
118
- //#endregion
119
- export { createInitialConsentStore };
@@ -1,29 +0,0 @@
1
- import { ConsentMode, ConsentStorage } from "../core/consent.mjs";
2
- import { ConsentConfig } from "../core/consent-config.mjs";
3
-
4
- //#region src/client/is-analytics-allowed.d.ts
5
- /**
6
- * @since 1.0.0-canary.6
7
- */
8
- interface IsAnalyticsAllowedOptions {
9
- /** Must be the same object `useConsent` receives — one config, every surface. */
10
- config: ConsentConfig;
11
- /**
12
- * Re-read each call. Pass `hasGlobalPrivacyControlSignal` from `@codefast/tracking/client`
13
- * (or a wrapper) so GPC changes apply without recreating the gate.
14
- */
15
- hasGlobalPrivacyControlSignal?: (() => boolean) | undefined;
16
- /** Re-read each call so a post-hydration region resolve can win. */
17
- getMode: () => ConsentMode;
18
- /** Must be the same storage instance `useConsent` subscribes to. */
19
- storage: ConsentStorage;
20
- }
21
- /**
22
- * Non-React mirror of `useConsent`'s `isAnalyticsAllowed` — pass the returned function as
23
- * `createClientTracker({ isAnalyticsAllowed })` so the pipeline and the banner share one rule.
24
- *
25
- * @since 1.0.0-canary.6
26
- */
27
- declare function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean;
28
- //#endregion
29
- export { IsAnalyticsAllowedOptions, createIsAnalyticsAllowed };
@@ -1,23 +0,0 @@
1
- import { resolveEffectiveConsent } from "../core/consent.mjs";
2
- //#region src/client/is-analytics-allowed.ts
3
- /**
4
- * Non-React mirror of `useConsent`'s `isAnalyticsAllowed` — pass the returned function as
5
- * `createClientTracker({ isAnalyticsAllowed })` so the pipeline and the banner share one rule.
6
- *
7
- * @since 1.0.0-canary.6
8
- */
9
- function createIsAnalyticsAllowed(options) {
10
- const { config, getMode, storage } = options;
11
- const readGpc = options.hasGlobalPrivacyControlSignal ?? (() => false);
12
- return () => {
13
- return resolveEffectiveConsent({
14
- hasGlobalPrivacyControlSignal: readGpc(),
15
- mode: getMode(),
16
- policyVersion: config.policyVersion,
17
- requestedCategories: config.requestedCategories,
18
- storage
19
- }).analytics;
20
- };
21
- }
22
- //#endregion
23
- export { createIsAnalyticsAllowed };
@@ -1,33 +0,0 @@
1
- import { CookieAnonymousId } from "./cookie-anonymous-id.mjs";
2
-
3
- //#region src/client/server-persisted-anonymous-id.d.ts
4
- /**
5
- * @since 1.0.0-canary.6
6
- */
7
- interface ServerPersistedAnonymousIdOptions {
8
- /** Server round-trip that expires the cookie via `Set-Cookie` — the server half of `clear()`. */
9
- clearOnServer?: (() => Promise<void>) | undefined;
10
- /** Cookie name — must not collide with another cookie on the domain. */
11
- cookieName: string;
12
- /** How long the id survives a return visit. Defaults to one year. */
13
- maxAgeSeconds?: number | undefined;
14
- /**
15
- * Server round-trip that re-sets the cookie via `Set-Cookie` (e.g. a server function
16
- * calling `buildAnonymousIdSetCookie`). Fired at most once per page load, only after an
17
- * id exists client-side — the server persists and prolongs, it never mints.
18
- */
19
- persist: (id: string) => Promise<void>;
20
- }
21
- /**
22
- * `createCookieAnonymousId` plus server persistence: the client still mints the id
23
- * (lazily, only once an event is allowed to send — consent stays client-owned), then
24
- * delegates the durable write to the server. A script-written cookie is capped at 7 days
25
- * by Safari ITP; the server's `Set-Cookie` re-issue is what makes the id actually live
26
- * its full max-age. Same optimistic `document.cookie` write first, so the current event
27
- * never waits on the round-trip and a failed `persist` degrades to today's behavior.
28
- *
29
- * @since 1.0.0-canary.6
30
- */
31
- declare function createServerPersistedAnonymousId(options: ServerPersistedAnonymousIdOptions): CookieAnonymousId;
32
- //#endregion
33
- export { ServerPersistedAnonymousIdOptions, createServerPersistedAnonymousId };
@@ -1,50 +0,0 @@
1
- import { readCookieValue } from "../core/cookie.mjs";
2
- import { createCookieAnonymousId } from "./cookie-anonymous-id.mjs";
3
- //#region src/client/server-persisted-anonymous-id.ts
4
- /**
5
- * `createCookieAnonymousId` plus server persistence: the client still mints the id
6
- * (lazily, only once an event is allowed to send — consent stays client-owned), then
7
- * delegates the durable write to the server. A script-written cookie is capped at 7 days
8
- * by Safari ITP; the server's `Set-Cookie` re-issue is what makes the id actually live
9
- * its full max-age. Same optimistic `document.cookie` write first, so the current event
10
- * never waits on the round-trip and a failed `persist` degrades to today's behavior.
11
- *
12
- * @since 1.0.0-canary.6
13
- */
14
- function createServerPersistedAnonymousId(options) {
15
- const { clearOnServer, cookieName, maxAgeSeconds, persist } = options;
16
- const local = createCookieAnonymousId({
17
- cookieName,
18
- maxAgeSeconds
19
- });
20
- let hasRequestedPersist = false;
21
- return {
22
- clear() {
23
- const shouldClearServer = typeof document !== "undefined" && Boolean(readCookieValue(document.cookie, cookieName));
24
- local.clear();
25
- hasRequestedPersist = false;
26
- if (shouldClearServer) clearOnServer?.().catch(() => {});
27
- },
28
- getOrCreate() {
29
- if (typeof document !== "undefined" && !readCookieValue(document.cookie, cookieName)) hasRequestedPersist = false;
30
- const id = local.getOrCreate();
31
- if (!hasRequestedPersist && typeof document !== "undefined") {
32
- hasRequestedPersist = true;
33
- persist(id).catch(() => {});
34
- }
35
- return id;
36
- },
37
- refresh() {
38
- if (typeof document === "undefined") return;
39
- const existing = readCookieValue(document.cookie, cookieName);
40
- if (!existing) return;
41
- local.refresh();
42
- if (!hasRequestedPersist) {
43
- hasRequestedPersist = true;
44
- persist(existing).catch(() => {});
45
- }
46
- }
47
- };
48
- }
49
- //#endregion
50
- export { createServerPersistedAnonymousId };
@@ -1,27 +0,0 @@
1
- import { ConsentCategory } from "./consent.mjs";
2
-
3
- //#region src/core/consent-config.d.ts
4
- /**
5
- * The consent constants every surface must agree on. The React hooks, the client
6
- * tracker gate, and the pre-hydration tag bootstrap all accept this object, so the
7
- * cross-surface "must match" contracts hold by construction instead of by hand-threading
8
- * the same strings through every call site.
9
- *
10
- * @since 1.0.0-canary.6
11
- */
12
- interface ConsentConfig {
13
- /** Bumping re-prompts every visitor — a stored decision under any other version is ignored. */
14
- policyVersion: string;
15
- /** Purposes the app's prompt asks about — `grantAll` and opt-out defaults grant exactly these. */
16
- requestedCategories: ReadonlyArray<ConsentCategory>;
17
- /** `localStorage` key holding the visitor's `ConsentRecord`. */
18
- storageKey: string;
19
- }
20
- /**
21
- * Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
22
- *
23
- * @since 1.0.0-canary.6
24
- */
25
- declare function defineConsentConfig<Config extends ConsentConfig>(config: Config): Config;
26
- //#endregion
27
- export { ConsentConfig, defineConsentConfig };
@@ -1,11 +0,0 @@
1
- //#region src/core/consent-config.ts
2
- /**
3
- * Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
4
- *
5
- * @since 1.0.0-canary.6
6
- */
7
- function defineConsentConfig(config) {
8
- return config;
9
- }
10
- //#endregion
11
- export { defineConsentConfig };
@@ -1,152 +0,0 @@
1
- //#region src/core/consent.ts
2
- /**
3
- * @since 1.0.0-canary.6
4
- */
5
- const CONSENT_REGIONS = [
6
- "eu",
7
- "other",
8
- "us",
9
- "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
- function isConsentRegion(value) {
17
- return CONSENT_REGIONS.includes(value);
18
- }
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
- function resolveConsentMode(region) {
27
- switch (region) {
28
- case "eu":
29
- case "vn": return "opt-in";
30
- case "other":
31
- case "us": return "opt-out";
32
- }
33
- }
34
- /**
35
- * @since 0.5.0-canary.4
36
- */
37
- const CONSENT_CATEGORIES = ["ads", "analytics"];
38
- /**
39
- * A decision granting exactly the given categories and denying every other one.
40
- *
41
- * @since 0.5.0-canary.4
42
- */
43
- function createConsentDecision(grantedCategories) {
44
- return {
45
- ads: grantedCategories.includes("ads"),
46
- analytics: grantedCategories.includes("analytics")
47
- };
48
- }
49
- function isPlainObject(value) {
50
- return typeof value === "object" && value !== null && !Array.isArray(value);
51
- }
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
- function isConsentDecision(value) {
58
- return isPlainObject(value) && CONSENT_CATEGORIES.every((category) => typeof value[category] === "boolean");
59
- }
60
- /**
61
- * Re-derives a clean per-category decision from a tamperable record — extra keys are
62
- * dropped, every category becomes an explicit boolean. The one normalization rule shared
63
- * by the client (`readStoredDecision`) and server (`readConsentDecisionCookie`) mirrors.
64
- *
65
- * @since 1.0.0-canary.6
66
- */
67
- function normalizeConsentDecision(decision) {
68
- return createConsentDecision(CONSENT_CATEGORIES.filter((category) => decision[category]));
69
- }
70
- /**
71
- * Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
72
- *
73
- * @since 1.0.0-canary.6
74
- */
75
- function isConsentRecord(value) {
76
- return isPlainObject(value) && isConsentDecision(value.decision) && typeof value.policyVersion === "string" && typeof value.timestamp === "number";
77
- }
78
- /**
79
- * The effective consent before the visitor decides: opt-in regions start all-denied,
80
- * opt-out regions grant the categories the app asks for.
81
- *
82
- * @remarks
83
- * A Global Privacy Control signal is a "do not sell or share" opt-out (CCPA/CPRA), so it
84
- * forces `ads` denied — it does not withdraw first-party analytics measurement.
85
- *
86
- * @since 0.5.0-canary.4
87
- */
88
- function resolveDefaultConsent(options) {
89
- const { hasGlobalPrivacyControlSignal, mode, requestedCategories } = options;
90
- if (mode === "opt-in") return createConsentDecision([]);
91
- const decision = createConsentDecision(requestedCategories);
92
- if (hasGlobalPrivacyControlSignal) decision.ads = false;
93
- return decision;
94
- }
95
- /**
96
- * What shared HTML bakes and what an unknown-country request resolves to: all categories
97
- * denied under opt-in — the one default that is safe to show any visitor anywhere.
98
- * Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
99
- * header means "unknown visitor", never "known non-EU visitor".
100
- *
101
- * @since 1.0.0-canary.6
102
- */
103
- const STRICTEST_INITIAL_CONSENT = Object.freeze({
104
- defaultConsent: Object.freeze(createConsentDecision([])),
105
- mode: "opt-in",
106
- region: "other"
107
- });
108
- /**
109
- * Guards an `InitialConsent` read from untrusted storage (a session cache, a cookie).
110
- * Enforces the mode/region pairing rule; the one deliberate exception is
111
- * {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
112
- * mode, never looser.
113
- *
114
- * @since 1.0.0-canary.6
115
- */
116
- function isInitialConsent(value) {
117
- if (!isPlainObject(value)) return false;
118
- const mode = value.mode;
119
- const region = value.region;
120
- if (mode !== "opt-in" && mode !== "opt-out" || !isConsentRegion(region) || !isConsentDecision(value.defaultConsent)) return false;
121
- return mode === resolveConsentMode(region) || mode === STRICTEST_INITIAL_CONSENT.mode && region === STRICTEST_INITIAL_CONSENT.region;
122
- }
123
- /**
124
- * The stored decision if one exists under the current `policyVersion`, normalized to drop
125
- * any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
126
- * it was recorded under a superseded policy version.
127
- *
128
- * @since 1.0.0-canary.6
129
- */
130
- function readStoredDecision(storage, policyVersion) {
131
- const record = storage.load();
132
- if (record?.policyVersion !== policyVersion || !isConsentDecision(record.decision)) return;
133
- return normalizeConsentDecision(record.decision);
134
- }
135
- /**
136
- * The consent a tracker should honor right now: the stored decision if one exists, else
137
- * the region default — the same rule `useConsent` applies to its `effectiveConsent`, so a
138
- * non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
139
- * "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
140
- *
141
- * @since 1.0.0-canary.6
142
- */
143
- function resolveEffectiveConsent(options) {
144
- const { hasGlobalPrivacyControlSignal, mode, policyVersion, requestedCategories, storage } = options;
145
- return readStoredDecision(storage, policyVersion) ?? resolveDefaultConsent({
146
- hasGlobalPrivacyControlSignal,
147
- mode,
148
- requestedCategories
149
- });
150
- }
151
- //#endregion
152
- export { CONSENT_CATEGORIES, CONSENT_REGIONS, STRICTEST_INITIAL_CONSENT, createConsentDecision, isConsentDecision, isConsentRecord, isConsentRegion, isInitialConsent, normalizeConsentDecision, readStoredDecision, resolveConsentMode, resolveDefaultConsent, resolveEffectiveConsent };
@@ -1,23 +0,0 @@
1
- //#region src/core/cookie.ts
2
- /**
3
- * Default lifetime shared by the anonymous-id and consent cookies — one year.
4
- *
5
- * @since 1.0.0-canary.6
6
- */
7
- const ONE_YEAR_IN_SECONDS = 3600 * 24 * 365;
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
- function readCookieValue(cookieString, cookieName) {
16
- if (!cookieString) return;
17
- for (const part of cookieString.split(";")) {
18
- const separatorIndex = part.indexOf("=");
19
- if (separatorIndex !== -1 && part.slice(0, separatorIndex).trim() === cookieName) return part.slice(separatorIndex + 1).trim();
20
- }
21
- }
22
- //#endregion
23
- export { ONE_YEAR_IN_SECONDS, readCookieValue };
@@ -1,25 +0,0 @@
1
- import { TrackedEvent } from "./tracked-event.mjs";
2
-
3
- //#region src/core/destination.d.ts
4
- /**
5
- * Fan-out target for tracked events. The tracker depends only on this interface, never
6
- * on a specific provider SDK — destinations own their transport (gtag.js and Vercel both
7
- * queue and batch in-page), so `send` is fire-and-forget at track time.
8
- *
9
- * @since 0.5.0-canary.4
10
- */
11
- interface Destination {
12
- /**
13
- * "exempt" keeps this destination receiving events while the tracker's analytics gate
14
- * is closed — only for cookieless, identifier-free sinks: gated envelopes carry no
15
- * `anonymousId`, and nothing is persisted.
16
- *
17
- * @defaultValue "required"
18
- */
19
- consentRequirement?: "exempt" | "required" | undefined;
20
- name: string;
21
- /** Must always return a `Promise` — mark `send` `async` even if the body has no `await`. */
22
- send: (event: TrackedEvent) => Promise<void>;
23
- }
24
- //#endregion
25
- export { Destination };
@@ -1 +0,0 @@
1
- export {};
@@ -1,39 +0,0 @@
1
- import { StandardSchemaV1 } from "@standard-schema/spec";
2
-
3
- //#region src/core/event-catalog.d.ts
4
- /**
5
- * One event's schema. Any Standard Schema library works (zod, zod/mini, valibot, ...) —
6
- * the client bundle only pays for the one the app already ships.
7
- *
8
- * @since 0.5.0-canary.4
9
- */
10
- interface EventDefinition<Schema extends StandardSchemaV1 = StandardSchemaV1> {
11
- schema: Schema;
12
- }
13
- /**
14
- * An app-defined map of event name to its definition. `@codefast/tracking` ships no
15
- * events of its own — every consuming app builds and passes in its own catalog.
16
- *
17
- * @since 0.5.0-canary.4
18
- */
19
- type EventCatalog = Record<string, EventDefinition>;
20
- /**
21
- * Identity helper for declaring a catalog with inference — nicer call-site than
22
- * `satisfies EventCatalog` when the catalog is assembled across multiple files.
23
- *
24
- * @since 0.5.0-canary.4
25
- */
26
- declare function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalog): Catalog;
27
- /**
28
- * Validates event properties against the catalog schema and throws on mismatch. The
29
- * validated (possibly transformed) value is deliberately discarded — the tracker always
30
- * sends the caller's original properties, so a schema transform can never desync callers.
31
- *
32
- * @throws Error when validation reports issues, or when the schema validates asynchronously —
33
- * tracking sits on synchronous call paths, so async schemas are unsupported by design.
34
- *
35
- * @since 1.0.0-canary.6
36
- */
37
- declare function assertValidEventProperties(schema: StandardSchemaV1, eventName: string, properties: unknown): void;
38
- //#endregion
39
- export { EventCatalog, EventDefinition, assertValidEventProperties, defineEventCatalog };
@@ -1,30 +0,0 @@
1
- //#region src/core/event-catalog.ts
2
- /**
3
- * Identity helper for declaring a catalog with inference — nicer call-site than
4
- * `satisfies EventCatalog` when the catalog is assembled across multiple files.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- function defineEventCatalog(catalog) {
9
- return catalog;
10
- }
11
- /**
12
- * Validates event properties against the catalog schema and throws on mismatch. The
13
- * validated (possibly transformed) value is deliberately discarded — the tracker always
14
- * sends the caller's original properties, so a schema transform can never desync callers.
15
- *
16
- * @throws Error when validation reports issues, or when the schema validates asynchronously —
17
- * tracking sits on synchronous call paths, so async schemas are unsupported by design.
18
- *
19
- * @since 1.0.0-canary.6
20
- */
21
- function assertValidEventProperties(schema, eventName, properties) {
22
- const result = schema["~standard"].validate(properties);
23
- if (result instanceof Promise) throw new TypeError(`Event "${eventName}" uses an async schema — event properties must validate synchronously`);
24
- if (result.issues) {
25
- const detail = result.issues.map((issue) => issue.message).join("; ");
26
- throw new Error(`Invalid properties for event "${eventName}": ${detail}`);
27
- }
28
- }
29
- //#endregion
30
- export { assertValidEventProperties, defineEventCatalog };
@@ -1,11 +0,0 @@
1
- //#region src/core/event-id.ts
2
- /**
3
- * Stamped on every envelope at track time — destinations that dedupe can key on it.
4
- *
5
- * @since 0.5.0-canary.4
6
- */
7
- function generateEventId() {
8
- return crypto.randomUUID();
9
- }
10
- //#endregion
11
- export { generateEventId };