@codefast/tracking 0.5.0-canary.4 → 0.5.0-canary.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (277) hide show
  1. package/CHANGELOG.md +473 -0
  2. package/README.md +177 -95
  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 +202 -107
  172. package/src/adapters/tanstack-start.ts +135 -0
  173. package/src/client/ad-framework-consent.ts +86 -0
  174. package/src/client/browser-cookie.ts +16 -0
  175. package/src/client/consent-runtime.ts +80 -0
  176. package/src/client/consent-storage.ts +31 -1
  177. package/src/client/consent-withdrawal.ts +32 -0
  178. package/src/client/cookie-anonymous-id.ts +112 -0
  179. package/src/client/create-client-tracker.ts +128 -86
  180. package/src/client/gpc.ts +4 -2
  181. package/src/client/initial-consent-store.ts +218 -0
  182. package/src/client/is-analytics-allowed.ts +43 -0
  183. package/src/client/server-persisted-anonymous-id.ts +102 -0
  184. package/src/core/consent-config.ts +27 -0
  185. package/src/core/consent-receipt.ts +115 -0
  186. package/src/core/consent.ts +164 -10
  187. package/src/core/cookie.ts +29 -0
  188. package/src/core/destination.ts +17 -8
  189. package/src/core/event-catalog.ts +29 -15
  190. package/src/core/event-id.ts +1 -2
  191. package/src/core/tracked-event.ts +4 -4
  192. package/src/css/consent.css +119 -0
  193. package/src/destinations/ad-consent.ts +29 -0
  194. package/src/destinations/google-analytics.ts +196 -133
  195. package/src/destinations/google-consent.ts +164 -0
  196. package/src/destinations/meta.ts +96 -0
  197. package/src/destinations/microsoft-uet.ts +86 -0
  198. package/src/destinations/shared.ts +45 -0
  199. package/src/destinations/tiktok.ts +85 -0
  200. package/src/destinations/vercel-analytics.ts +23 -24
  201. package/src/index.ts +165 -8
  202. package/src/react/consent-banner.tsx +308 -111
  203. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  204. package/src/react/use-consent.ts +53 -45
  205. package/src/react/use-google-consent-sync.ts +38 -0
  206. package/src/react/use-initial-consent.ts +22 -0
  207. package/src/server/anonymous-id-cookie.ts +103 -0
  208. package/src/server/consent-receipt-store.ts +79 -0
  209. package/src/server/consent-receipt.ts +89 -0
  210. package/src/server/initial-consent.ts +46 -0
  211. package/src/server/measurement-protocol.ts +114 -0
  212. package/src/server/region.ts +22 -15
  213. package/src/server/user-deletion.ts +93 -0
  214. package/src/tooling/import-protection.ts +22 -0
  215. package/dist/client/consent-storage.mjs +0 -63
  216. package/dist/client/create-client-tracker.d.mts +0 -37
  217. package/dist/client/create-client-tracker.mjs +0 -66
  218. package/dist/client/gpc.d.mts +0 -10
  219. package/dist/client/gpc.mjs +0 -12
  220. package/dist/client/index.d.mts +0 -8
  221. package/dist/client/index.mjs +0 -8
  222. package/dist/client/lifecycle.d.mts +0 -23
  223. package/dist/client/lifecycle.mjs +0 -30
  224. package/dist/client/local-storage.d.mts +0 -13
  225. package/dist/client/local-storage.mjs +0 -31
  226. package/dist/client/queue.d.mts +0 -49
  227. package/dist/client/queue.mjs +0 -71
  228. package/dist/client/router.d.mts +0 -30
  229. package/dist/client/router.mjs +0 -17
  230. package/dist/core/consent.d.mts +0 -89
  231. package/dist/core/consent.mjs +0 -57
  232. package/dist/core/destination.d.mts +0 -23
  233. package/dist/core/destination.mjs +0 -1
  234. package/dist/core/event-catalog.d.mts +0 -36
  235. package/dist/core/event-catalog.mjs +0 -12
  236. package/dist/core/event-id.d.mts +0 -10
  237. package/dist/core/event-id.mjs +0 -12
  238. package/dist/core/index.d.mts +0 -6
  239. package/dist/core/index.mjs +0 -4
  240. package/dist/core/tracked-event.d.mts +0 -17
  241. package/dist/core/tracked-event.mjs +0 -1
  242. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  243. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  244. package/dist/destinations/google-analytics.d.mts +0 -98
  245. package/dist/destinations/google-analytics.mjs +0 -126
  246. package/dist/destinations/http-destination.d.mts +0 -20
  247. package/dist/destinations/http-destination.mjs +0 -25
  248. package/dist/destinations/index.d.mts +0 -5
  249. package/dist/destinations/index.mjs +0 -5
  250. package/dist/destinations/vercel-analytics.d.mts +0 -13
  251. package/dist/destinations/vercel-analytics.mjs +0 -30
  252. package/dist/index.d.mts +0 -6
  253. package/dist/index.mjs +0 -4
  254. package/dist/react/consent-banner.d.mts +0 -75
  255. package/dist/react/consent-banner.mjs +0 -114
  256. package/dist/react/index.d.mts +0 -3
  257. package/dist/react/index.mjs +0 -3
  258. package/dist/react/use-consent.d.mts +0 -49
  259. package/dist/react/use-consent.mjs +0 -54
  260. package/dist/server/create-server-tracker.d.mts +0 -42
  261. package/dist/server/create-server-tracker.mjs +0 -67
  262. package/dist/server/index.d.mts +0 -3
  263. package/dist/server/index.mjs +0 -3
  264. package/dist/server/region.d.mts +0 -20
  265. package/dist/server/region.mjs +0 -56
  266. package/src/client/index.ts +0 -17
  267. package/src/client/lifecycle.ts +0 -50
  268. package/src/client/local-storage.ts +0 -44
  269. package/src/client/queue.ts +0 -117
  270. package/src/client/router.ts +0 -37
  271. package/src/core/index.ts +0 -24
  272. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  273. package/src/destinations/http-destination.ts +0 -33
  274. package/src/destinations/index.ts +0 -20
  275. package/src/react/index.ts +0 -5
  276. package/src/server/create-server-tracker.ts +0 -128
  277. package/src/server/index.ts +0 -4
@@ -0,0 +1,148 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { ConsentConfig } from "#/core/consent-config";
3
+ import type { Destination } from "#/core/destination";
4
+ import type { GoogleConsentParams } from "#/destinations/google-consent";
5
+ import type { FlatPropertyValue } from "#/destinations/shared";
6
+ type GtagPropertyValue = FlatPropertyValue;
7
+ /**
8
+ * All signatures share one `gtag` global, so they must live in a single overloaded type —
9
+ * two separate `declare global` augmentations with different signatures for the same
10
+ * property is a TS error, not a merge.
11
+ *
12
+ * @since 1.0.0-canary.6
13
+ */
14
+ export type GtagFunction = {
15
+ (command: "config", targetId: string, params?: Record<string, GtagPropertyValue>): void;
16
+ (command: "consent", action: "default" | "update", params: GoogleConsentParams): void;
17
+ (command: "event", eventName: string, params?: Record<string, GtagPropertyValue>): void;
18
+ (command: "js", startDate: Date): void;
19
+ (command: "set", params: Record<string, GtagPropertyValue>): void;
20
+ (command: "set", key: string, value: boolean): void;
21
+ };
22
+ declare global {
23
+ interface Window {
24
+ dataLayer?: Array<unknown>;
25
+ gtag?: GtagFunction;
26
+ }
27
+ }
28
+ /**
29
+ * @since 1.0.0-canary.6
30
+ */
31
+ export interface EnsureGtagOptions {
32
+ /**
33
+ * Name of the queue array on `window`. Defaults to `"dataLayer"`. Must match across
34
+ * `ensureGtag` / `loadGtagScript` / `buildGtagConsentBootstrapScript` for one page.
35
+ */
36
+ dataLayerName?: string | undefined;
37
+ }
38
+ /**
39
+ * Ensures the standard gtag.js queueing stub exists so consent commands can be issued
40
+ * before the tag itself loads — gtag.js replays the queue in order once it boots.
41
+ *
42
+ * @since 1.0.0-canary.6
43
+ */
44
+ export declare function ensureGtag(options?: EnsureGtagOptions): GtagFunction | undefined;
45
+ /**
46
+ * @since 1.0.0-canary.6
47
+ */
48
+ export interface LoadGtagScriptOptions {
49
+ /**
50
+ * Name of the queue array on `window`. Defaults to `"dataLayer"` — must match the
51
+ * bootstrap / `ensureGtag` call that already applied Consent Mode.
52
+ */
53
+ dataLayerName?: string | undefined;
54
+ /** Forwarded as `gtag('config', id, { debug_mode: true })` for GA4 DebugView. */
55
+ debugMode?: boolean | undefined;
56
+ /** Google Analytics 4 Measurement ID (e.g. `"G-XXXXXXX"`). */
57
+ gaMeasurementId: string;
58
+ /**
59
+ * CSP nonce applied to the injected gtag.js `<script>` element. The app must also put
60
+ * the same nonce on any inline bootstrap `<script>` that runs `buildGtagConsentBootstrapScript`.
61
+ */
62
+ nonce?: string | undefined;
63
+ }
64
+ /**
65
+ * Loads gtag.js on demand — idempotent (a second call is a no-op) and reuses any
66
+ * existing `dataLayer`/`gtag` stub instead of clobbering it. Queues `js`/`config` before
67
+ * appending the script tag, so gtag.js replays them under the caller's already-applied
68
+ * consent state once it boots. Prefer `buildGtagConsentBootstrapScript` for page load
69
+ * (advanced Consent Mode always injects the tag after the default); use this when the
70
+ * bootstrap did not run, or as an idempotent safety net after a runtime grant.
71
+ *
72
+ * @since 1.0.0-canary.6
73
+ */
74
+ export declare function loadGtagScript(options: LoadGtagScriptOptions): void;
75
+ /**
76
+ * Expires Google's `_ga` / `_ga_*` cookies on `path=/` and the current host's parent
77
+ * domain. Consent Mode stops using them once denied but never removes them — call from
78
+ * a consent-withdrawal handler so a revoke does not leave identifier cookies behind.
79
+ *
80
+ * @since 1.0.0-canary.6
81
+ */
82
+ export declare function clearGoogleAnalyticsCookies(): void;
83
+ /**
84
+ * Google Consent Mode v2's "update" signal — call whenever the visitor's effective
85
+ * consent changes (a banner decision, or one synced from another tab), so already-loaded
86
+ * GA4/Ads tags pick up the change without a page reload.
87
+ *
88
+ * @since 0.5.0-canary.4
89
+ */
90
+ export declare function updateGoogleConsent(decision: ConsentDecision, options?: EnsureGtagOptions): void;
91
+ /**
92
+ * @since 1.0.0-canary.6
93
+ */
94
+ export interface GtagConsentBootstrapOptions {
95
+ /** The same object `useConsent` receives — the bootstrap reads its `storageKey` and `policyVersion`. */
96
+ config: ConsentConfig;
97
+ /**
98
+ * Name of the queue array on `window`. Defaults to `"dataLayer"`. Must match
99
+ * `loadGtagScript` / `ensureGtag` if those run later on the same page.
100
+ */
101
+ dataLayerName?: string | undefined;
102
+ /**
103
+ * Consent to apply when nothing valid is stored yet. Embedded as a literal — bake the
104
+ * strictest default on cached/shared HTML; upgrade after hydration via the private
105
+ * server-fn lane + `updateGoogleConsent`.
106
+ */
107
+ defaultConsent: ConsentDecision;
108
+ /** Forwarded as `gtag('config', id, { debug_mode: true })` after the consent default. */
109
+ debugMode?: boolean | undefined;
110
+ /** Google Analytics 4 Measurement ID (e.g. `"G-XXXXXXX"`). */
111
+ gaMeasurementId: string;
112
+ /**
113
+ * CSP nonce written onto the *injected* gtag.js `<script>` element inside the generated
114
+ * source. The host `<script dangerouslySetInnerHTML={…}>` that embeds this string must
115
+ * receive the same nonce from the app (this helper only returns JS text, not a React node).
116
+ */
117
+ nonce?: string | undefined;
118
+ }
119
+ /**
120
+ * Builds the literal JS source for a `<script dangerouslySetInnerHTML>` mounted in
121
+ * `<head>`, before hydration: applies Consent Mode v2's default signal from the visitor's
122
+ * stored decision (falling back to literal `defaultConsent` when none is stored yet),
123
+ * then always loads gtag.js (advanced Consent Mode) so cookieless pings / modeling can
124
+ * run even when storage is denied. A runtime decision change needs `updateGoogleConsent`
125
+ * so the already-loaded tag picks up the grant/deny — this only covers the page-load
126
+ * default + script injection.
127
+ *
128
+ * @since 1.0.0-canary.6
129
+ */
130
+ export declare function buildGtagConsentBootstrapScript(options: GtagConsentBootstrapOptions): string;
131
+ /**
132
+ * @since 0.5.0-canary.4
133
+ */
134
+ export interface GoogleAnalyticsDestinationOptions {
135
+ name?: string | undefined;
136
+ }
137
+ /**
138
+ * Forwards catalog events to `window.gtag` as GA4 custom events. Page views are not this
139
+ * destination's job: `gtag('config', ...)` sends the initial page_view and GA4's Enhanced
140
+ * Measurement tracks SPA history changes. Requires the gtag.js snippet plus
141
+ * `gtag('config', measurementId)` mounted once by the app (see the consent bootstrap) —
142
+ * gtag.js owns its own batching and unload delivery.
143
+ *
144
+ * @since 0.5.0-canary.4
145
+ */
146
+ export declare function createGoogleAnalyticsDestination(options?: GoogleAnalyticsDestinationOptions): Destination;
147
+ export {};
148
+ //# sourceMappingURL=google-analytics.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-analytics.d.ts","sourceRoot":"","sources":["../../src/destinations/google-analytics.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,156 @@
1
+ import { buildGoogleConsentBootstrapPreamble, DEFAULT_DATA_LAYER_NAME, ensureDataLayer, toGoogleConsentParams, warnUnlessGa4EventName, } from "#/destinations/google-consent";
2
+ import { flattenEventProps } from "#/destinations/shared";
3
+ const GTAG_SCRIPT_BASE_URL = "https://www.googletagmanager.com/gtag/js";
4
+ function gtagScriptSrc(gaMeasurementId, dataLayerName) {
5
+ const url = new URL(GTAG_SCRIPT_BASE_URL);
6
+ url.searchParams.set("id", gaMeasurementId);
7
+ if (dataLayerName !== DEFAULT_DATA_LAYER_NAME) {
8
+ // gtag.js's `l` param names the queue array — must match the stub that pushes into it.
9
+ url.searchParams.set("l", dataLayerName);
10
+ }
11
+ return url.toString();
12
+ }
13
+ /**
14
+ * Ensures the standard gtag.js queueing stub exists so consent commands can be issued
15
+ * before the tag itself loads — gtag.js replays the queue in order once it boots.
16
+ *
17
+ * @since 1.0.0-canary.6
18
+ */
19
+ export function ensureGtag(options = {}) {
20
+ if (typeof window === "undefined") {
21
+ return undefined;
22
+ }
23
+ const dataLayerName = options.dataLayerName ?? DEFAULT_DATA_LAYER_NAME;
24
+ ensureDataLayer(dataLayerName);
25
+ // First stub wins — recreating would orphan commands already queued on another layer.
26
+ // Callers must pass the same dataLayerName for every helper on the page.
27
+ window.gtag ??= function gtag() {
28
+ ensureDataLayer(dataLayerName)?.push(arguments);
29
+ };
30
+ return window.gtag;
31
+ }
32
+ /**
33
+ * Loads gtag.js on demand — idempotent (a second call is a no-op) and reuses any
34
+ * existing `dataLayer`/`gtag` stub instead of clobbering it. Queues `js`/`config` before
35
+ * appending the script tag, so gtag.js replays them under the caller's already-applied
36
+ * consent state once it boots. Prefer `buildGtagConsentBootstrapScript` for page load
37
+ * (advanced Consent Mode always injects the tag after the default); use this when the
38
+ * bootstrap did not run, or as an idempotent safety net after a runtime grant.
39
+ *
40
+ * @since 1.0.0-canary.6
41
+ */
42
+ export function loadGtagScript(options) {
43
+ if (typeof document === "undefined" || document.querySelector(`script[src^="${GTAG_SCRIPT_BASE_URL}"]`) !== null) {
44
+ return;
45
+ }
46
+ const dataLayerName = options.dataLayerName ?? DEFAULT_DATA_LAYER_NAME;
47
+ const gtag = ensureGtag({ dataLayerName });
48
+ if (!gtag) {
49
+ return;
50
+ }
51
+ gtag("js", new Date());
52
+ if (options.debugMode === true) {
53
+ gtag("config", options.gaMeasurementId, { debug_mode: true });
54
+ }
55
+ else {
56
+ gtag("config", options.gaMeasurementId);
57
+ }
58
+ const script = document.createElement("script");
59
+ script.async = true;
60
+ script.src = gtagScriptSrc(options.gaMeasurementId, dataLayerName);
61
+ if (options.nonce !== undefined) {
62
+ script.nonce = options.nonce;
63
+ }
64
+ document.head.append(script);
65
+ }
66
+ /**
67
+ * Expires Google's `_ga` / `_ga_*` cookies on `path=/` and the current host's parent
68
+ * domain. Consent Mode stops using them once denied but never removes them — call from
69
+ * a consent-withdrawal handler so a revoke does not leave identifier cookies behind.
70
+ *
71
+ * @since 1.0.0-canary.6
72
+ */
73
+ export function clearGoogleAnalyticsCookies() {
74
+ if (typeof document === "undefined") {
75
+ return;
76
+ }
77
+ const { hostname } = globalThis.location;
78
+ for (const cookie of document.cookie.split("; ")) {
79
+ const name = cookie.split("=")[0];
80
+ if (name !== undefined && (name === "_ga" || name.startsWith("_ga_"))) {
81
+ // GA sets its cookies on the broadest domain it can reach — expire both variants.
82
+ document.cookie = `${name}=; path=/; max-age=0`;
83
+ document.cookie = `${name}=; path=/; max-age=0; domain=.${hostname}`;
84
+ }
85
+ }
86
+ }
87
+ /**
88
+ * Google Consent Mode v2's "update" signal — call whenever the visitor's effective
89
+ * consent changes (a banner decision, or one synced from another tab), so already-loaded
90
+ * GA4/Ads tags pick up the change without a page reload.
91
+ *
92
+ * @since 0.5.0-canary.4
93
+ */
94
+ export function updateGoogleConsent(decision, options = {}) {
95
+ ensureGtag(options)?.("consent", "update", toGoogleConsentParams(decision));
96
+ }
97
+ /**
98
+ * Builds the literal JS source for a `<script dangerouslySetInnerHTML>` mounted in
99
+ * `<head>`, before hydration: applies Consent Mode v2's default signal from the visitor's
100
+ * stored decision (falling back to literal `defaultConsent` when none is stored yet),
101
+ * then always loads gtag.js (advanced Consent Mode) so cookieless pings / modeling can
102
+ * run even when storage is denied. A runtime decision change needs `updateGoogleConsent`
103
+ * so the already-loaded tag picks up the grant/deny — this only covers the page-load
104
+ * default + script injection.
105
+ *
106
+ * @since 1.0.0-canary.6
107
+ */
108
+ export function buildGtagConsentBootstrapScript(options) {
109
+ const { config, dataLayerName = DEFAULT_DATA_LAYER_NAME, defaultConsent, debugMode, gaMeasurementId, nonce, } = options;
110
+ const gtagScriptUrl = gtagScriptSrc(gaMeasurementId, dataLayerName);
111
+ const configArgs = debugMode === true ? `${JSON.stringify(gaMeasurementId)}, { debug_mode: true }` : JSON.stringify(gaMeasurementId);
112
+ const nonceAssignment = nonce === undefined ? "" : `gtagScript.nonce = ${JSON.stringify(nonce)};`;
113
+ const preamble = buildGoogleConsentBootstrapPreamble({
114
+ consentStorageKey: config.storageKey,
115
+ dataLayerName,
116
+ defaultConsent,
117
+ policyVersion: config.policyVersion,
118
+ });
119
+ // Advanced Consent Mode: consent default first, then always load the tag (even when denied).
120
+ return `${preamble}
121
+ gtag("js", new Date());
122
+ gtag("config", ${configArgs});
123
+ var gtagScript = document.createElement("script");
124
+ gtagScript.async = true;
125
+ gtagScript.src = ${JSON.stringify(gtagScriptUrl)};
126
+ ${nonceAssignment}
127
+ document.head.appendChild(gtagScript);
128
+ `;
129
+ }
130
+ /**
131
+ * Forwards catalog events to `window.gtag` as GA4 custom events. Page views are not this
132
+ * destination's job: `gtag('config', ...)` sends the initial page_view and GA4's Enhanced
133
+ * Measurement tracks SPA history changes. Requires the gtag.js snippet plus
134
+ * `gtag('config', measurementId)` mounted once by the app (see the consent bootstrap) —
135
+ * gtag.js owns its own batching and unload delivery.
136
+ *
137
+ * @since 0.5.0-canary.4
138
+ */
139
+ export function createGoogleAnalyticsDestination(options = {}) {
140
+ const name = options.name ?? "google-analytics";
141
+ return {
142
+ name,
143
+ // Synchronous today, but declared async so a throw here rejects the returned Promise
144
+ // instead of escaping as a synchronous throw — matches Destination.send's contract.
145
+ async send(event) {
146
+ if (typeof window === "undefined" || typeof window.gtag !== "function") {
147
+ return;
148
+ }
149
+ if (!warnUnlessGa4EventName(name, event.name)) {
150
+ return;
151
+ }
152
+ window.gtag("event", event.name, flattenEventProps(event.properties));
153
+ },
154
+ };
155
+ }
156
+ //# sourceMappingURL=google-analytics.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-analytics.js","sourceRoot":"","sources":["../../src/destinations/google-analytics.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,62 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ /**
3
+ * gtag.js/gtm.js's default queue-array name — shared so the gtag and GTM helpers cannot disagree.
4
+ *
5
+ * @since 1.0.0-canary.6
6
+ */
7
+ export declare const DEFAULT_DATA_LAYER_NAME = "dataLayer";
8
+ type GoogleConsentState = "denied" | "granted";
9
+ /**
10
+ * Consent Mode v2 params issued via `gtag('consent', …)` — shared by the gtag and GTM
11
+ * bootstraps so signal mapping cannot drift between them.
12
+ *
13
+ * @since 1.0.0-canary.6
14
+ */
15
+ export interface GoogleConsentParams {
16
+ ad_personalization: GoogleConsentState;
17
+ ad_storage: GoogleConsentState;
18
+ ad_user_data: GoogleConsentState;
19
+ analytics_storage: GoogleConsentState;
20
+ region?: ReadonlyArray<string> | undefined;
21
+ wait_for_update?: number | undefined;
22
+ }
23
+ /**
24
+ * Maps a package `ConsentDecision` onto Consent Mode v2's four storage signals.
25
+ *
26
+ * @since 1.0.0-canary.6
27
+ */
28
+ export declare function toGoogleConsentParams(decision: ConsentDecision): GoogleConsentParams;
29
+ /**
30
+ * @since 1.0.0-canary.6
31
+ */
32
+ export interface GoogleConsentBootstrapPreambleOptions {
33
+ /** localStorage key holding the package's `ConsentRecord`. */
34
+ consentStorageKey: string;
35
+ dataLayerName: string;
36
+ /** Literal fallback when nothing valid is stored — baked into the script as JSON. */
37
+ defaultConsent: ConsentDecision;
38
+ policyVersion: string;
39
+ }
40
+ /**
41
+ * Shared head of the gtag and GTM consent bootstraps: dataLayer init, `gtag()` stub,
42
+ * stored-decision read (policy-version + shape checked), and the Consent Mode v2
43
+ * "default" signal. The builders append only their tag-specific tail, so the consent
44
+ * logic cannot drift between them.
45
+ *
46
+ * @since 1.0.0-canary.6
47
+ */
48
+ export declare function buildGoogleConsentBootstrapPreamble(options: GoogleConsentBootstrapPreambleOptions): string;
49
+ /**
50
+ * Reads or creates a named `window[dataLayerName]` queue array.
51
+ *
52
+ * @since 1.0.0-canary.6
53
+ */
54
+ export declare function ensureDataLayer(dataLayerName: string): Array<unknown> | undefined;
55
+ /**
56
+ * Warns and returns `false` when `eventName` would be rejected by GA4.
57
+ *
58
+ * @since 1.0.0-canary.6
59
+ */
60
+ export declare function warnUnlessGa4EventName(destinationName: string, eventName: string): boolean;
61
+ export {};
62
+ //# sourceMappingURL=google-consent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-consent.d.ts","sourceRoot":"","sources":["../../src/destinations/google-consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGvE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD,KAAK,kBAAkB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,iBAAiB,EAAE,kBAAkB,CAAC;IACtC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAkBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,mBAAmB,CASpF;AAuBD;;GAEG;AACH,MAAM,WAAW,qCAAqC;IACpD,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,cAAc,EAAE,eAAe,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,EAAE,qCAAqC,GAAG,MAAM,CAiB1G;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS,CAWjF;AAaD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU1F"}
@@ -0,0 +1,109 @@
1
+ import { CONSENT_CATEGORIES } from "#/core/consent";
2
+ /**
3
+ * gtag.js/gtm.js's default queue-array name — shared so the gtag and GTM helpers cannot disagree.
4
+ *
5
+ * @since 1.0.0-canary.6
6
+ */
7
+ export const DEFAULT_DATA_LAYER_NAME = "dataLayer";
8
+ /**
9
+ * Which per-category decision each Consent Mode v2 signal follows: `analytics` drives
10
+ * `analytics_storage`; `ads` drives all three ads signals together.
11
+ */
12
+ const GOOGLE_CONSENT_SIGNAL_CATEGORIES = {
13
+ ad_personalization: "ads",
14
+ ad_storage: "ads",
15
+ ad_user_data: "ads",
16
+ analytics_storage: "analytics",
17
+ };
18
+ /**
19
+ * Maps a package `ConsentDecision` onto Consent Mode v2's four storage signals.
20
+ *
21
+ * @since 1.0.0-canary.6
22
+ */
23
+ export function toGoogleConsentParams(decision) {
24
+ // Derived from the signal map (not hand-written per signal) so the runtime params and
25
+ // the bootstrap fragment below can never disagree.
26
+ return {
27
+ ad_personalization: decision[GOOGLE_CONSENT_SIGNAL_CATEGORIES.ad_personalization] ? "granted" : "denied",
28
+ ad_storage: decision[GOOGLE_CONSENT_SIGNAL_CATEGORIES.ad_storage] ? "granted" : "denied",
29
+ ad_user_data: decision[GOOGLE_CONSENT_SIGNAL_CATEGORIES.ad_user_data] ? "granted" : "denied",
30
+ analytics_storage: decision[GOOGLE_CONSENT_SIGNAL_CATEGORIES.analytics_storage] ? "granted" : "denied",
31
+ };
32
+ }
33
+ /** JS fragment that validates a stored `ConsentRecord.decision` shape inside a bootstrap. */
34
+ function consentDecisionShapeCheckExpression() {
35
+ return CONSENT_CATEGORIES.map((category) => `typeof record.decision[${JSON.stringify(category)}] === "boolean"`).join(" && ");
36
+ }
37
+ /**
38
+ * JS object-literal fragment for `gtag("consent", "default", { … })` — generated from
39
+ * {@link GOOGLE_CONSENT_SIGNAL_CATEGORIES} so runtime and bootstrap stay aligned.
40
+ */
41
+ function consentSignalAssignmentsExpression() {
42
+ return Object.keys(GOOGLE_CONSENT_SIGNAL_CATEGORIES)
43
+ .map((signal) => {
44
+ const category = GOOGLE_CONSENT_SIGNAL_CATEGORIES[signal];
45
+ return `${signal}: consent.${category} ? "granted" : "denied"`;
46
+ })
47
+ .join(",\n ");
48
+ }
49
+ /**
50
+ * Shared head of the gtag and GTM consent bootstraps: dataLayer init, `gtag()` stub,
51
+ * stored-decision read (policy-version + shape checked), and the Consent Mode v2
52
+ * "default" signal. The builders append only their tag-specific tail, so the consent
53
+ * logic cannot drift between them.
54
+ *
55
+ * @since 1.0.0-canary.6
56
+ */
57
+ export function buildGoogleConsentBootstrapPreamble(options) {
58
+ const dataLayerAccess = `window[${JSON.stringify(options.dataLayerName)}]`;
59
+ return `
60
+ ${dataLayerAccess} = ${dataLayerAccess} || [];
61
+ function gtag(){${dataLayerAccess}.push(arguments);}
62
+ var storedConsent = null;
63
+ try {
64
+ var record = JSON.parse(window.localStorage.getItem(${JSON.stringify(options.consentStorageKey)}));
65
+ if (record && record.policyVersion === ${JSON.stringify(options.policyVersion)} && record.decision && ${consentDecisionShapeCheckExpression()}) {
66
+ storedConsent = record.decision;
67
+ }
68
+ } catch (e) {}
69
+ var consent = storedConsent || (${JSON.stringify(options.defaultConsent)});
70
+ gtag("consent", "default", {
71
+ ${consentSignalAssignmentsExpression()}
72
+ });`;
73
+ }
74
+ /**
75
+ * Reads or creates a named `window[dataLayerName]` queue array.
76
+ *
77
+ * @since 1.0.0-canary.6
78
+ */
79
+ export function ensureDataLayer(dataLayerName) {
80
+ if (typeof window === "undefined") {
81
+ return undefined;
82
+ }
83
+ const existing = Reflect.get(window, dataLayerName);
84
+ const layer = Array.isArray(existing) ? existing : [];
85
+ Reflect.set(window, dataLayerName, layer);
86
+ return layer;
87
+ }
88
+ /**
89
+ * GA4's event-name rules (letter start, letters/digits/underscores only, ≤40 chars).
90
+ * Catalog `track` names that fail this are accepted by gtag/MP HTTP but dropped at GA4
91
+ * processing with no client error — destinations warn and skip instead of sending nowhere.
92
+ */
93
+ const GA4_EVENT_NAME_PATTERN = /^[A-Za-z][\w]{0,39}$/;
94
+ function isGa4EventName(name) {
95
+ return GA4_EVENT_NAME_PATTERN.test(name);
96
+ }
97
+ /**
98
+ * Warns and returns `false` when `eventName` would be rejected by GA4.
99
+ *
100
+ * @since 1.0.0-canary.6
101
+ */
102
+ export function warnUnlessGa4EventName(destinationName, eventName) {
103
+ if (isGa4EventName(eventName)) {
104
+ return true;
105
+ }
106
+ console.warn(`[tracking] "${destinationName}" dropped event "${eventName}" — GA4 event names must start with a letter and contain only letters, digits, or underscores (max 40 chars)`);
107
+ return false;
108
+ }
109
+ //# sourceMappingURL=google-consent.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"google-consent.js","sourceRoot":"","sources":["../../src/destinations/google-consent.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,63 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { Destination } from "#/core/destination";
3
+ import type { FlatPropertyValue } from "#/destinations/shared";
4
+ /**
5
+ * Meta's `dataProcessingOptions` restriction. `['LDU'], 0, 0` turns on Limited Data Use and
6
+ * lets Meta geolocate the user — the recommended default beyond California, where only
7
+ * country `1` (USA) / state `1000` (California) are documented codes (spec-destinations §5).
8
+ * `[]` applies no restriction.
9
+ *
10
+ * @since 1.0.0-canary.7
11
+ */
12
+ export interface MetaDataProcessingOptions {
13
+ country: number;
14
+ options: ReadonlyArray<string>;
15
+ state: number;
16
+ }
17
+ /**
18
+ * Maps a `ConsentDecision` to Meta's `dataProcessingOptions`: LDU when `ads` is denied.
19
+ *
20
+ * @since 1.0.0-canary.7
21
+ */
22
+ export declare function toMetaDataProcessingOptions(decision: ConsentDecision): MetaDataProcessingOptions;
23
+ /**
24
+ * The mapped per-event payload handed to a Meta transport (Pixel `fbq` or a CAPI request).
25
+ *
26
+ * @since 1.0.0-canary.7
27
+ */
28
+ export interface MetaEventPayload {
29
+ dataProcessingOptions: MetaDataProcessingOptions;
30
+ name: string;
31
+ properties: Record<string, FlatPropertyValue>;
32
+ }
33
+ /**
34
+ * @since 1.0.0-canary.7
35
+ */
36
+ export interface MetaDestinationOptions {
37
+ /**
38
+ * Erasure cookie-clear seam — invoked by `onErasure` to drop Meta's `_fbp`/`_fbc` cookies
39
+ * (spec-data-subject-rights DSR-V4). Meta exposes no per-visitor deletion API, so erasure
40
+ * is cookie-clear + stop-send only. Omit if the integrator clears cookies elsewhere.
41
+ */
42
+ clearCookies?: (() => void) | undefined;
43
+ /** Read per event so an `ads` change restricts data use without recreating the destination. */
44
+ getDecision: () => ConsentDecision;
45
+ name?: string | undefined;
46
+ /**
47
+ * Delivers one mapped event — the transport seam. Wire it to `fbq(...)` (Pixel) or a
48
+ * Conversions API request; this package ships the consent mapping, never the credentials
49
+ * or network client.
50
+ */
51
+ transport: (payload: MetaEventPayload) => Promise<void> | void;
52
+ }
53
+ /**
54
+ * Reference ad destination: maps each event to Meta's shape and applies Limited Data Use
55
+ * from the live `ads` decision (spec-destinations §5), then hands it to an injected
56
+ * transport. Consent-restriction mapping only — the Pixel/CAPI transport and credentials
57
+ * are the integrator's to supply. `consentRequirement` stays `"required"`: an ad sink is
58
+ * never exempt.
59
+ *
60
+ * @since 1.0.0-canary.7
61
+ */
62
+ export declare function createMetaDestination(options: MetaDestinationOptions): Destination;
63
+ //# sourceMappingURL=meta.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/destinations/meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,eAAe,GAAG,yBAAyB,CAIhG;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB,EAAE,yBAAyB,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACxC,+FAA+F;IAC/F,WAAW,EAAE,MAAM,eAAe,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;;OAIG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAChE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,WAAW,CAuBlF"}
@@ -0,0 +1,44 @@
1
+ import { toAdConsentState } from "#/destinations/ad-consent";
2
+ import { flattenEventProps } from "#/destinations/shared";
3
+ /**
4
+ * Maps a `ConsentDecision` to Meta's `dataProcessingOptions`: LDU when `ads` is denied.
5
+ *
6
+ * @since 1.0.0-canary.7
7
+ */
8
+ export function toMetaDataProcessingOptions(decision) {
9
+ return toAdConsentState(decision).limitedDataUse
10
+ ? { country: 0, options: ["LDU"], state: 0 }
11
+ : { country: 0, options: [], state: 0 };
12
+ }
13
+ /**
14
+ * Reference ad destination: maps each event to Meta's shape and applies Limited Data Use
15
+ * from the live `ads` decision (spec-destinations §5), then hands it to an injected
16
+ * transport. Consent-restriction mapping only — the Pixel/CAPI transport and credentials
17
+ * are the integrator's to supply. `consentRequirement` stays `"required"`: an ad sink is
18
+ * never exempt.
19
+ *
20
+ * @since 1.0.0-canary.7
21
+ */
22
+ export function createMetaDestination(options) {
23
+ // Erasure halts delivery for the rest of the session — Meta has no per-visitor deletion API.
24
+ let stopped = false;
25
+ return {
26
+ consentRequirement: "required",
27
+ name: options.name ?? "meta",
28
+ onErasure() {
29
+ stopped = true;
30
+ options.clearCookies?.();
31
+ },
32
+ async send(event) {
33
+ if (stopped) {
34
+ return;
35
+ }
36
+ await options.transport({
37
+ dataProcessingOptions: toMetaDataProcessingOptions(options.getDecision()),
38
+ name: event.name,
39
+ properties: flattenEventProps(event.properties),
40
+ });
41
+ },
42
+ };
43
+ }
44
+ //# sourceMappingURL=meta.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/destinations/meta.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAgB1D;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAyB;IACnE,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC,cAAc;QAC9C,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QAC5C,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAC5C,CAAC;AAkCD;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IACnE,6FAA6F;IAC7F,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,kBAAkB,EAAE,UAAU;QAC9B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM;QAC5B,SAAS;YACP,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK;YACd,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YAED,MAAM,OAAO,CAAC,SAAS,CAAC;gBACtB,qBAAqB,EAAE,2BAA2B,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;gBACzE,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,UAAU,EAAE,iBAAiB,CAAC,KAAK,CAAC,UAAU,CAAC;aAChD,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}