@codefast/tracking 0.6.2 → 0.7.1

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 (159) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +1 -1
  3. package/dist/adapters/tanstack-start.d.ts +11 -7
  4. package/dist/adapters/tanstack-start.d.ts.map +1 -1
  5. package/dist/adapters/tanstack-start.js +4 -4
  6. package/dist/adapters/tanstack-start.js.map +1 -1
  7. package/dist/client/ad-framework-consent.d.ts +8 -6
  8. package/dist/client/ad-framework-consent.d.ts.map +1 -1
  9. package/dist/client/ad-framework-consent.js +3 -3
  10. package/dist/client/ad-framework-consent.js.map +1 -1
  11. package/dist/client/browser-cookie.d.ts +1 -1
  12. package/dist/client/browser-cookie.js +1 -1
  13. package/dist/client/consent-runtime.d.ts +5 -3
  14. package/dist/client/consent-runtime.d.ts.map +1 -1
  15. package/dist/client/consent-runtime.js +1 -1
  16. package/dist/client/consent-runtime.js.map +1 -1
  17. package/dist/client/consent-withdrawal.d.ts +4 -2
  18. package/dist/client/consent-withdrawal.d.ts.map +1 -1
  19. package/dist/client/consent-withdrawal.js +1 -1
  20. package/dist/client/consent-withdrawal.js.map +1 -1
  21. package/dist/client/cookie-anonymous-id.d.ts +7 -3
  22. package/dist/client/cookie-anonymous-id.d.ts.map +1 -1
  23. package/dist/client/cookie-anonymous-id.js +1 -1
  24. package/dist/client/cookie-anonymous-id.js.map +1 -1
  25. package/dist/client/create-client-tracker.d.ts +7 -1
  26. package/dist/client/create-client-tracker.d.ts.map +1 -1
  27. package/dist/client/create-client-tracker.js +2 -0
  28. package/dist/client/create-client-tracker.js.map +1 -1
  29. package/dist/client/initial-consent-store.d.ts +6 -4
  30. package/dist/client/initial-consent-store.d.ts.map +1 -1
  31. package/dist/client/initial-consent-store.js +1 -1
  32. package/dist/client/initial-consent-store.js.map +1 -1
  33. package/dist/client/is-analytics-allowed.d.ts +4 -2
  34. package/dist/client/is-analytics-allowed.d.ts.map +1 -1
  35. package/dist/client/is-analytics-allowed.js +1 -1
  36. package/dist/client/is-analytics-allowed.js.map +1 -1
  37. package/dist/client/server-persisted-anonymous-id.d.ts +4 -2
  38. package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -1
  39. package/dist/client/server-persisted-anonymous-id.js +1 -1
  40. package/dist/client/server-persisted-anonymous-id.js.map +1 -1
  41. package/dist/core/consent-config.d.ts +2 -2
  42. package/dist/core/consent-config.js +1 -1
  43. package/dist/core/consent-receipt.d.ts +6 -6
  44. package/dist/core/consent-receipt.js +1 -1
  45. package/dist/core/consent.d.ts +23 -11
  46. package/dist/core/consent.d.ts.map +1 -1
  47. package/dist/core/consent.js +12 -8
  48. package/dist/core/consent.js.map +1 -1
  49. package/dist/core/cookie.d.ts +2 -2
  50. package/dist/core/cookie.js +2 -2
  51. package/dist/core/event-catalog.d.ts +1 -1
  52. package/dist/core/event-catalog.js +1 -1
  53. package/dist/destinations/ad-consent.d.ts +2 -2
  54. package/dist/destinations/ad-consent.js +1 -1
  55. package/dist/destinations/google-analytics.d.ts +16 -8
  56. package/dist/destinations/google-analytics.d.ts.map +1 -1
  57. package/dist/destinations/google-analytics.js +4 -4
  58. package/dist/destinations/google-analytics.js.map +1 -1
  59. package/dist/destinations/google-consent.d.ts +9 -7
  60. package/dist/destinations/google-consent.d.ts.map +1 -1
  61. package/dist/destinations/google-consent.js +5 -5
  62. package/dist/destinations/google-consent.js.map +1 -1
  63. package/dist/destinations/meta.d.ts +7 -5
  64. package/dist/destinations/meta.d.ts.map +1 -1
  65. package/dist/destinations/meta.js +2 -2
  66. package/dist/destinations/meta.js.map +1 -1
  67. package/dist/destinations/microsoft-uet.d.ts +7 -5
  68. package/dist/destinations/microsoft-uet.d.ts.map +1 -1
  69. package/dist/destinations/microsoft-uet.js +2 -2
  70. package/dist/destinations/microsoft-uet.js.map +1 -1
  71. package/dist/destinations/shared.d.ts +7 -3
  72. package/dist/destinations/shared.d.ts.map +1 -1
  73. package/dist/destinations/shared.js +3 -1
  74. package/dist/destinations/shared.js.map +1 -1
  75. package/dist/destinations/tiktok.d.ts +7 -5
  76. package/dist/destinations/tiktok.d.ts.map +1 -1
  77. package/dist/destinations/tiktok.js +2 -2
  78. package/dist/destinations/tiktok.js.map +1 -1
  79. package/dist/destinations/vercel-analytics.d.ts +3 -1
  80. package/dist/destinations/vercel-analytics.d.ts.map +1 -1
  81. package/dist/destinations/vercel-analytics.js.map +1 -1
  82. package/dist/react/consent-banner.d.ts +28 -0
  83. package/dist/react/consent-banner.d.ts.map +1 -1
  84. package/dist/react/consent-banner.js +11 -7
  85. package/dist/react/consent-banner.js.map +1 -1
  86. package/dist/react/gtag-consent-bootstrap.d.ts +4 -2
  87. package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -1
  88. package/dist/react/gtag-consent-bootstrap.js +1 -1
  89. package/dist/react/gtag-consent-bootstrap.js.map +1 -1
  90. package/dist/react/use-consent.d.ts +4 -0
  91. package/dist/react/use-consent.d.ts.map +1 -1
  92. package/dist/react/use-consent.js.map +1 -1
  93. package/dist/react/use-google-consent-sync.d.ts +4 -2
  94. package/dist/react/use-google-consent-sync.d.ts.map +1 -1
  95. package/dist/react/use-google-consent-sync.js +1 -1
  96. package/dist/react/use-google-consent-sync.js.map +1 -1
  97. package/dist/react/use-initial-consent.d.ts +1 -1
  98. package/dist/react/use-initial-consent.js +1 -1
  99. package/dist/server/anonymous-id-cookie.d.ts +7 -5
  100. package/dist/server/anonymous-id-cookie.d.ts.map +1 -1
  101. package/dist/server/anonymous-id-cookie.js +4 -4
  102. package/dist/server/anonymous-id-cookie.js.map +1 -1
  103. package/dist/server/consent-receipt-store.d.ts +4 -4
  104. package/dist/server/consent-receipt-store.js +2 -2
  105. package/dist/server/consent-receipt.d.ts +4 -4
  106. package/dist/server/consent-receipt.js +3 -3
  107. package/dist/server/initial-consent.d.ts +4 -2
  108. package/dist/server/initial-consent.d.ts.map +1 -1
  109. package/dist/server/initial-consent.js +1 -1
  110. package/dist/server/initial-consent.js.map +1 -1
  111. package/dist/server/measurement-protocol.d.ts +9 -7
  112. package/dist/server/measurement-protocol.d.ts.map +1 -1
  113. package/dist/server/measurement-protocol.js +3 -3
  114. package/dist/server/measurement-protocol.js.map +1 -1
  115. package/dist/server/region.d.ts +2 -2
  116. package/dist/server/region.js +2 -2
  117. package/dist/server/user-deletion.d.ts +9 -5
  118. package/dist/server/user-deletion.d.ts.map +1 -1
  119. package/dist/server/user-deletion.js +2 -2
  120. package/dist/server/user-deletion.js.map +1 -1
  121. package/dist/tooling/import-protection.d.ts +1 -1
  122. package/dist/tooling/import-protection.js +1 -1
  123. package/package.json +7 -7
  124. package/src/adapters/tanstack-start.ts +11 -7
  125. package/src/client/ad-framework-consent.ts +8 -6
  126. package/src/client/browser-cookie.ts +1 -1
  127. package/src/client/consent-runtime.ts +5 -3
  128. package/src/client/consent-withdrawal.ts +4 -2
  129. package/src/client/cookie-anonymous-id.ts +7 -3
  130. package/src/client/create-client-tracker.ts +7 -1
  131. package/src/client/initial-consent-store.ts +6 -4
  132. package/src/client/is-analytics-allowed.ts +4 -2
  133. package/src/client/server-persisted-anonymous-id.ts +4 -2
  134. package/src/core/consent-config.ts +2 -2
  135. package/src/core/consent-receipt.ts +6 -6
  136. package/src/core/consent.ts +23 -11
  137. package/src/core/cookie.ts +2 -2
  138. package/src/core/event-catalog.ts +1 -1
  139. package/src/destinations/ad-consent.ts +2 -2
  140. package/src/destinations/google-analytics.ts +16 -8
  141. package/src/destinations/google-consent.ts +9 -7
  142. package/src/destinations/meta.ts +7 -5
  143. package/src/destinations/microsoft-uet.ts +7 -5
  144. package/src/destinations/shared.ts +10 -4
  145. package/src/destinations/tiktok.ts +7 -5
  146. package/src/destinations/vercel-analytics.ts +3 -1
  147. package/src/react/consent-banner.tsx +34 -8
  148. package/src/react/gtag-consent-bootstrap.tsx +4 -2
  149. package/src/react/use-consent.ts +4 -0
  150. package/src/react/use-google-consent-sync.ts +4 -2
  151. package/src/react/use-initial-consent.ts +1 -1
  152. package/src/server/anonymous-id-cookie.ts +7 -5
  153. package/src/server/consent-receipt-store.ts +4 -4
  154. package/src/server/consent-receipt.ts +4 -4
  155. package/src/server/initial-consent.ts +4 -2
  156. package/src/server/measurement-protocol.ts +9 -7
  157. package/src/server/region.ts +2 -2
  158. package/src/server/user-deletion.ts +9 -5
  159. package/src/tooling/import-protection.ts +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/tracking",
3
- "version": "0.6.2",
3
+ "version": "0.7.1",
4
4
  "description": "Consent-gated, type-safe event tracking for TanStack Start — client tracker and server consent helpers over a per-app Standard Schema event catalog",
5
5
  "keywords": [
6
6
  "analytics",
@@ -275,25 +275,25 @@
275
275
  "@standard-schema/spec": "^1.1.0"
276
276
  },
277
277
  "devDependencies": {
278
- "@tanstack/react-start": "^1.168.44",
278
+ "@tanstack/react-start": "^1.168.49",
279
279
  "@testing-library/dom": "^10.4.1",
280
280
  "@testing-library/jest-dom": "^7.0.1",
281
281
  "@testing-library/react": "^16.3.2",
282
- "@testing-library/user-event": "^14.6.4",
282
+ "@testing-library/user-event": "^14.6.6",
283
283
  "@types/node": "^26.2.0",
284
284
  "@types/react": "^19.2.18",
285
285
  "@types/react-dom": "^19.2.4",
286
286
  "@vercel/analytics": "^2.0.1",
287
- "@vitejs/plugin-react": "^6.0.5",
288
- "@vitest/coverage-v8": "^4.1.10",
287
+ "@vitejs/plugin-react": "^6.1.0",
288
+ "@vitest/coverage-v8": "^4.1.11",
289
289
  "expect-type": "^1.4.0",
290
290
  "jsdom": "^30.0.1",
291
291
  "react": "^19.2.8",
292
292
  "react-dom": "^19.2.8",
293
293
  "typescript": "^7.0.2",
294
- "vitest": "^4.1.10",
294
+ "vitest": "^4.1.11",
295
295
  "zod": "^4.4.3",
296
- "@codefast/typescript-config": "0.6.2"
296
+ "@codefast/typescript-config": "0.8.0"
297
297
  },
298
298
  "peerDependencies": {
299
299
  "@tanstack/react-start": ">=1.168.0",
@@ -16,7 +16,9 @@ import type { ReceiptStore } from "#/server/consent-receipt-store";
16
16
  import { resolveInitialConsent } from "#/server/initial-consent";
17
17
 
18
18
  /**
19
- * @since 1.0.0-canary.7
19
+ * Options for `resolveInitialConsentFromRequest`.
20
+ *
21
+ * @since 0.5.0-canary.6
20
22
  */
21
23
  export interface InitialConsentFromRequestOptions {
22
24
  /**
@@ -38,7 +40,7 @@ export interface InitialConsentFromRequestOptions {
38
40
  * Server-only: deny this subpath in the client environment via Start's `importProtection`
39
41
  * — the compiler already strips it with stubbed handler bodies.
40
42
  *
41
- * @since 1.0.0-canary.6
43
+ * @since 0.5.0-canary.6
42
44
  */
43
45
  export function resolveInitialConsentFromRequest(options: InitialConsentFromRequestOptions): InitialConsent {
44
46
  setResponseHeader("cache-control", "private, no-store");
@@ -57,7 +59,7 @@ export function resolveInitialConsentFromRequest(options: InitialConsentFromRequ
57
59
  * `resolveAnonymousIdCookie`: a non-UUID id throws, so this can safely back a public server
58
60
  * function without echoing attacker input into a header.
59
61
  *
60
- * @since 1.0.0-canary.6
62
+ * @since 0.5.0-canary.6
61
63
  */
62
64
  export function setAnonymousIdResponseCookie(options: AnonymousIdCookieOptions): void {
63
65
  const { name, value, ...attributes } = resolveAnonymousIdCookie({
@@ -72,7 +74,7 @@ export function setAnonymousIdResponseCookie(options: AnonymousIdCookieOptions):
72
74
  /**
73
75
  * Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
74
76
  *
75
- * @since 1.0.0-canary.6
77
+ * @since 0.5.0-canary.6
76
78
  */
77
79
  export function clearAnonymousIdResponseCookie(cookieName: string): void {
78
80
  const { name, ...attributes } = resolveClearAnonymousIdCookie(cookieName);
@@ -84,7 +86,7 @@ export function clearAnonymousIdResponseCookie(cookieName: string): void {
84
86
  * The client-visible acknowledgement of a recorded receipt — deliberately minimal so the
85
87
  * stored PII (`subjectId`, `ipCoarse`) is never echoed back over the wire.
86
88
  *
87
- * @since 1.0.0-canary.7
89
+ * @since 0.5.0-canary.6
88
90
  */
89
91
  export interface ConsentReceiptAck {
90
92
  receiptId: string;
@@ -92,7 +94,9 @@ export interface ConsentReceiptAck {
92
94
  }
93
95
 
94
96
  /**
95
- * @since 1.0.0-canary.7
97
+ * Options for `recordConsentReceiptFromRequest`.
98
+ *
99
+ * @since 0.5.0-canary.6
96
100
  */
97
101
  export interface RecordConsentReceiptFromRequestOptions {
98
102
  input: ConsentReceiptInput;
@@ -113,7 +117,7 @@ export interface RecordConsentReceiptFromRequestOptions {
113
117
  * @throws Error when `input` fails {@link isConsentReceiptInput} (including a body that
114
118
  * carries an `ip`/`ipCoarse` field — the server owns IP derivation).
115
119
  *
116
- * @since 1.0.0-canary.7
120
+ * @since 0.5.0-canary.6
117
121
  */
118
122
  export async function recordConsentReceiptFromRequest(
119
123
  options: RecordConsentReceiptFromRequestOptions,
@@ -11,14 +11,14 @@ import type { ConsentCategory, ConsentDecision } from "#/core/consent";
11
11
  * Liveness of a detected CMP. `"out-of-scope"` is TCF `gdprApplies === false` / no applicable
12
12
  * GPP section — the framework does not govern this user, so native consent stands.
13
13
  *
14
- * @since 1.0.0-canary.7
14
+ * @since 0.5.0-canary.6
15
15
  */
16
16
  export type CmpStatus = "loading" | "out-of-scope" | "ready";
17
17
 
18
18
  /**
19
19
  * A CMP's governance over the native decision, already derived from TCData/GPP by ad-ops policy.
20
20
  *
21
- * @since 1.0.0-canary.7
21
+ * @since 0.5.0-canary.6
22
22
  */
23
23
  export interface CmpConsentSignal {
24
24
  /** Per-governed-category grant, read once `status` is `"ready"`. */
@@ -29,7 +29,9 @@ export interface CmpConsentSignal {
29
29
  }
30
30
 
31
31
  /**
32
- * @since 1.0.0-canary.7
32
+ * Options for `reconcileAdFrameworkConsent`.
33
+ *
34
+ * @since 0.5.0-canary.6
33
35
  */
34
36
  export interface ReconcileAdFrameworkConsentOptions {
35
37
  /** The live CMP signal, or omitted when no CMP is present (the resolver is then inert). */
@@ -45,7 +47,7 @@ export interface ReconcileAdFrameworkConsentOptions {
45
47
  * a governing CMP overrides its categories (fail-closed to denied while loading); a missing
46
48
  * or out-of-scope CMP leaves native standing; GPC always tightens `ads` last.
47
49
  *
48
- * @since 1.0.0-canary.7
50
+ * @since 0.5.0-canary.6
49
51
  */
50
52
  export function reconcileAdFrameworkConsent(options: ReconcileAdFrameworkConsentOptions): ConsentDecision {
51
53
  const result: ConsentDecision = { ...options.native };
@@ -70,7 +72,7 @@ export function reconcileAdFrameworkConsent(options: ReconcileAdFrameworkConsent
70
72
  /**
71
73
  * Detects a TCF CMP without reading it — `typeof __tcfapi === "function"` (spec §3).
72
74
  *
73
- * @since 1.0.0-canary.7
75
+ * @since 0.5.0-canary.6
74
76
  */
75
77
  export function hasTcfApi(scope: { __tcfapi?: unknown } = globalThis as { __tcfapi?: unknown }): boolean {
76
78
  return typeof scope.__tcfapi === "function";
@@ -79,7 +81,7 @@ export function hasTcfApi(scope: { __tcfapi?: unknown } = globalThis as { __tcfa
79
81
  /**
80
82
  * Detects a GPP CMP without reading it — `typeof __gpp === "function"` (spec §3).
81
83
  *
82
- * @since 1.0.0-canary.7
84
+ * @since 0.5.0-canary.6
83
85
  */
84
86
  export function hasGppApi(scope: { __gpp?: unknown } = globalThis as { __gpp?: unknown }): boolean {
85
87
  return typeof scope.__gpp === "function";
@@ -3,7 +3,7 @@
3
3
  * mirror): Secure on HTTPS so values never ride plain HTTP, SameSite=Lax, never HttpOnly —
4
4
  * the client must read its own cookies back. A no-op without a `document` (SSR).
5
5
  *
6
- * @since 1.0.0-canary.6
6
+ * @since 0.5.0-canary.6
7
7
  */
8
8
  export function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void {
9
9
  if (typeof document === "undefined") {
@@ -7,7 +7,9 @@ import type { ConsentStorage, InitialConsent } from "#/core/consent";
7
7
  import type { ConsentConfig } from "#/core/consent-config";
8
8
 
9
9
  /**
10
- * @since 1.0.0-canary.6
10
+ * Options for `createConsentRuntime`.
11
+ *
12
+ * @since 0.5.0-canary.6
11
13
  */
12
14
  export interface ConsentRuntimeOptions {
13
15
  config: ConsentConfig;
@@ -31,7 +33,7 @@ export interface ConsentRuntimeOptions {
31
33
  * it once at module scope and every surface (banner hook, tracker gate, privacy page)
32
34
  * shares the same storage and region resolution by construction.
33
35
  *
34
- * @since 1.0.0-canary.6
36
+ * @since 0.5.0-canary.6
35
37
  */
36
38
  export interface ConsentRuntime {
37
39
  config: ConsentConfig;
@@ -54,7 +56,7 @@ export interface ConsentRuntime {
54
56
  * `localStorage`-backed decision storage, the initial-consent store over the app's
55
57
  * server lane, and the non-React analytics gate wired to that store's resolved mode.
56
58
  *
57
- * @since 1.0.0-canary.6
59
+ * @since 0.5.0-canary.6
58
60
  */
59
61
  export function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime {
60
62
  const { config } = options;
@@ -1,7 +1,9 @@
1
1
  import type { ConsentDecision } from "#/core/consent";
2
2
 
3
3
  /**
4
- * @since 1.0.0-canary.6
4
+ * Options for `createConsentWithdrawalHandler`.
5
+ *
6
+ * @since 0.5.0-canary.6
5
7
  */
6
8
  export interface ConsentWithdrawalHandlerOptions {
7
9
  /** Forget the cookie-backed visitor id when analytics is denied. */
@@ -14,7 +16,7 @@ export interface ConsentWithdrawalHandlerOptions {
14
16
  * `useConsent({ onDecision })` handler that clears first-party tracking state when the
15
17
  * visitor denies (or withdraws) analytics. Grant paths are a no-op.
16
18
  *
17
- * @since 1.0.0-canary.6
19
+ * @since 0.5.0-canary.6
18
20
  */
19
21
  export function createConsentWithdrawalHandler(
20
22
  options: ConsentWithdrawalHandlerOptions,
@@ -2,7 +2,9 @@ import { writeBrowserCookie } from "#/client/browser-cookie";
2
2
  import { ONE_YEAR_IN_SECONDS, readCookieValue } from "#/core/cookie";
3
3
 
4
4
  /**
5
- * @since 1.0.0-canary.6
5
+ * Options for `createCookieAnonymousId`.
6
+ *
7
+ * @since 0.5.0-canary.6
6
8
  */
7
9
  export interface CookieAnonymousIdOptions {
8
10
  /** Cookie name — must not collide with another cookie on the domain. */
@@ -12,7 +14,9 @@ export interface CookieAnonymousIdOptions {
12
14
  }
13
15
 
14
16
  /**
15
- * @since 1.0.0-canary.6
17
+ * A cookie-backed anonymous id handle: lazy minting, expiry refresh, and clearing on withdrawal.
18
+ *
19
+ * @since 0.5.0-canary.6
16
20
  */
17
21
  export interface CookieAnonymousId {
18
22
  /** Expires the cookie — call when the visitor withdraws tracking consent. */
@@ -40,7 +44,7 @@ export interface CookieAnonymousId {
40
44
  * it's invoked lazily, so the cookie is minted only once an event is actually allowed to
41
45
  * send, never as an import-time side effect.
42
46
  *
43
- * @since 1.0.0-canary.6
47
+ * @since 0.5.0-canary.6
44
48
  */
45
49
  export function createCookieAnonymousId(options: CookieAnonymousIdOptions): CookieAnonymousId {
46
50
  const { cookieName, maxAgeSeconds = ONE_YEAR_IN_SECONDS } = options;
@@ -9,7 +9,7 @@ import type { TrackedEvent } from "#/core/tracked-event";
9
9
  /**
10
10
  * Context handed to {@link ClientTrackerOptions.onDeliveryError} for one failed delivery.
11
11
  *
12
- * @since 1.0.0-canary.7
12
+ * @since 0.5.0-canary.6
13
13
  */
14
14
  export interface DeliveryErrorContext {
15
15
  destination: Destination;
@@ -62,6 +62,8 @@ function eraseInDestination(destination: Destination, id: string): void {
62
62
  }
63
63
 
64
64
  /**
65
+ * Options for `createClientTracker`.
66
+ *
65
67
  * @since 0.5.0-canary.4
66
68
  */
67
69
  export interface ClientTrackerOptions<Catalog extends EventCatalog> {
@@ -92,6 +94,8 @@ export interface ClientTrackerOptions<Catalog extends EventCatalog> {
92
94
  }
93
95
 
94
96
  /**
97
+ * A client-side tracker delivering catalog-validated events to destinations, plus erasure on withdrawal.
98
+ *
95
99
  * @since 0.5.0-canary.4
96
100
  */
97
101
  export interface ClientTracker<Catalog extends EventCatalog> {
@@ -108,6 +112,8 @@ export interface ClientTracker<Catalog extends EventCatalog> {
108
112
  }
109
113
 
110
114
  /**
115
+ * Creates a consent-gated tracker that validates each event against the catalog and fans it out to destinations.
116
+ *
111
117
  * @since 0.5.0-canary.4
112
118
  */
113
119
  export function createClientTracker<Catalog extends EventCatalog>(
@@ -5,7 +5,7 @@ import { isInitialConsent, STRICTEST_INITIAL_CONSENT } from "#/core/consent";
5
5
  * External-store view of the visitor's region default — the strictest value until the
6
6
  * server lane answers, then the resolved one.
7
7
  *
8
- * @since 1.0.0-canary.6
8
+ * @since 0.5.0-canary.6
9
9
  */
10
10
  export interface InitialConsentSnapshot {
11
11
  /** The region-correct default once resolved; {@link STRICTEST_INITIAL_CONSENT} until then. */
@@ -19,7 +19,9 @@ export interface InitialConsentSnapshot {
19
19
  }
20
20
 
21
21
  /**
22
- * @since 1.0.0-canary.6
22
+ * Options for `createInitialConsentStore`.
23
+ *
24
+ * @since 0.5.0-canary.6
23
25
  */
24
26
  export interface InitialConsentStoreOptions {
25
27
  /**
@@ -40,7 +42,7 @@ export interface InitialConsentStoreOptions {
40
42
  * `useSyncExternalStore`-shaped — pass `subscribe`/`getSnapshot`/`getServerSnapshot`
41
43
  * straight through, or use the `useInitialConsent` hook from `@codefast/tracking/react`.
42
44
  *
43
- * @since 1.0.0-canary.6
45
+ * @since 0.5.0-canary.6
44
46
  */
45
47
  export interface InitialConsentStore {
46
48
  /**
@@ -67,7 +69,7 @@ const SERVER_SNAPSHOT: InitialConsentSnapshot = {
67
69
  * (consent UI still renders, under the strictest default), and a retry the next time the
68
70
  * tab becomes visible — so one failed request never locks the whole SPA session.
69
71
  *
70
- * @since 1.0.0-canary.6
72
+ * @since 0.5.0-canary.6
71
73
  */
72
74
  export function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore {
73
75
  const listeners = new Set<() => void>();
@@ -3,7 +3,9 @@ import { resolveEffectiveConsent } from "#/core/consent";
3
3
  import type { ConsentConfig } from "#/core/consent-config";
4
4
 
5
5
  /**
6
- * @since 1.0.0-canary.6
6
+ * Options for `createIsAnalyticsAllowed`.
7
+ *
8
+ * @since 0.5.0-canary.6
7
9
  */
8
10
  export interface IsAnalyticsAllowedOptions {
9
11
  /** Must be the same object `useConsent` receives — one config, every surface. */
@@ -23,7 +25,7 @@ export interface IsAnalyticsAllowedOptions {
23
25
  * Non-React mirror of `useConsent`'s `isAnalyticsAllowed` — pass the returned function as
24
26
  * `createClientTracker({ isAnalyticsAllowed })` so the pipeline and the banner share one rule.
25
27
  *
26
- * @since 1.0.0-canary.6
28
+ * @since 0.5.0-canary.6
27
29
  */
28
30
  export function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean {
29
31
  const { config, getMode, storage } = options;
@@ -3,7 +3,9 @@ import { createCookieAnonymousId } from "#/client/cookie-anonymous-id";
3
3
  import { readCookieValue } from "#/core/cookie";
4
4
 
5
5
  /**
6
- * @since 1.0.0-canary.6
6
+ * Options for `createServerPersistedAnonymousId`.
7
+ *
8
+ * @since 0.5.0-canary.6
7
9
  */
8
10
  export interface ServerPersistedAnonymousIdOptions {
9
11
  /** Server round-trip that expires the cookie via `Set-Cookie` — the server half of `clear()`. */
@@ -28,7 +30,7 @@ export interface ServerPersistedAnonymousIdOptions {
28
30
  * its full max-age. Same optimistic `document.cookie` write first, so the current event
29
31
  * never waits on the round-trip and a failed `persist` degrades to today's behavior.
30
32
  *
31
- * @since 1.0.0-canary.6
33
+ * @since 0.5.0-canary.6
32
34
  */
33
35
  export function createServerPersistedAnonymousId(options: ServerPersistedAnonymousIdOptions): CookieAnonymousId {
34
36
  const { clearOnServer, cookieName, maxAgeSeconds, persist } = options;
@@ -6,7 +6,7 @@ import type { ConsentCategory } from "#/core/consent";
6
6
  * cross-surface "must match" contracts hold by construction instead of by hand-threading
7
7
  * the same strings through every call site.
8
8
  *
9
- * @since 1.0.0-canary.6
9
+ * @since 0.5.0-canary.6
10
10
  */
11
11
  export interface ConsentConfig {
12
12
  /** Bumping re-prompts every visitor — a stored decision under any other version is ignored. */
@@ -20,7 +20,7 @@ export interface ConsentConfig {
20
20
  /**
21
21
  * Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
22
22
  *
23
- * @since 1.0.0-canary.6
23
+ * @since 0.5.0-canary.6
24
24
  */
25
25
  export function defineConsentConfig<Config extends ConsentConfig>(config: Config): Config {
26
26
  return config;
@@ -5,7 +5,7 @@ import { isConsentDecision } from "#/core/consent";
5
5
  * Which consent event a receipt records. Receipts are append-only: an `update` or
6
6
  * `withdraw` is a new receipt referencing the prior one, never a mutation.
7
7
  *
8
- * @since 1.0.0-canary.7
8
+ * @since 0.5.0-canary.6
9
9
  */
10
10
  export type ConsentReceiptEventType = "give" | "update" | "withdraw";
11
11
 
@@ -13,7 +13,7 @@ export type ConsentReceiptEventType = "give" | "update" | "withdraw";
13
13
  * How the decision was expressed — the "how" dimension a demonstrable-consent record must
14
14
  * capture (GDPR Art. 7(1); EDPB 05/2020 §5.1).
15
15
  *
16
- * @since 1.0.0-canary.7
16
+ * @since 0.5.0-canary.6
17
17
  */
18
18
  export type ConsentReceiptMethod = "banner-accept" | "banner-reject" | "granular" | "gpc-signal" | "withdrawal";
19
19
 
@@ -21,7 +21,7 @@ export type ConsentReceiptMethod = "banner-accept" | "banner-reject" | "granular
21
21
  * What kind of identifier links the receipt to a subject. A cookie-only visitor uses a
22
22
  * pseudonymous `cookie` id — the receipt is still valid proof.
23
23
  *
24
- * @since 1.0.0-canary.7
24
+ * @since 0.5.0-canary.6
25
25
  */
26
26
  export type ConsentReceiptSubjectIdType = "cookie" | "email-hash" | "userId";
27
27
 
@@ -29,7 +29,7 @@ export type ConsentReceiptSubjectIdType = "cookie" | "email-hash" | "userId";
29
29
  * The caller-supplied fields of a consent receipt. Deliberately carries **no IP** — the
30
30
  * server derives a coarsened one from the connection so a full IP never transits the body.
31
31
  *
32
- * @since 1.0.0-canary.7
32
+ * @since 0.5.0-canary.6
33
33
  */
34
34
  export interface ConsentReceiptInput {
35
35
  decision: ConsentDecision;
@@ -55,7 +55,7 @@ export interface ConsentReceiptInput {
55
55
  * The record is append-only; never mutate a stored receipt. `ipCoarse` is truncated at
56
56
  * write time and MUST NOT be a full IP.
57
57
  *
58
- * @since 1.0.0-canary.7
58
+ * @since 0.5.0-canary.6
59
59
  */
60
60
  export interface ConsentReceipt extends ConsentReceiptInput {
61
61
  /** Coarsened/pseudonymized IP, or absent — never a full address. */
@@ -86,7 +86,7 @@ const RECEIPT_SUBJECT_ID_TYPES: ReadonlySet<ConsentReceiptSubjectIdType> = new S
86
86
  * Guards a receipt input received from an untrusted client. Rejects a body carrying an
87
87
  * `ip`/`ipCoarse` field so a full address can never be persisted from caller input.
88
88
  *
89
- * @since 1.0.0-canary.7
89
+ * @since 0.5.0-canary.6
90
90
  */
91
91
  export function isConsentReceiptInput(value: unknown): value is ConsentReceiptInput {
92
92
  if (typeof value !== "object" || value === null) {
@@ -1,23 +1,29 @@
1
1
  /**
2
+ * The privacy-law region a visitor's consent defaults are resolved for.
3
+ *
2
4
  * @since 0.5.0-canary.4
3
5
  */
4
6
  export type ConsentRegion = "eu" | "other" | "us" | "vn";
5
7
 
6
8
  /**
7
- * @since 1.0.0-canary.6
9
+ * Every consent region, in a stable order shared by guards and iteration.
10
+ *
11
+ * @since 0.5.0-canary.6
8
12
  */
9
13
  export const CONSENT_REGIONS: ReadonlyArray<ConsentRegion> = ["eu", "other", "us", "vn"];
10
14
 
11
15
  /**
12
16
  * Guards a region read from untrusted storage (a cached `InitialConsent`, a cookie).
13
17
  *
14
- * @since 1.0.0-canary.6
18
+ * @since 0.5.0-canary.6
15
19
  */
16
20
  export function isConsentRegion(value: unknown): value is ConsentRegion {
17
21
  return CONSENT_REGIONS.includes(value as ConsentRegion);
18
22
  }
19
23
 
20
24
  /**
25
+ * Whether a region requires explicit opt-in before tracking or defaults to opt-out.
26
+ *
21
27
  * @since 0.5.0-canary.4
22
28
  */
23
29
  export type ConsentMode = "opt-in" | "opt-out";
@@ -53,6 +59,8 @@ export function resolveConsentMode(region: ConsentRegion): ConsentMode {
53
59
  export type ConsentCategory = "ads" | "analytics";
54
60
 
55
61
  /**
62
+ * Every consent category, in a stable order shared by guards and iteration.
63
+ *
56
64
  * @since 0.5.0-canary.4
57
65
  */
58
66
  export const CONSENT_CATEGORIES: ReadonlyArray<ConsentCategory> = ["ads", "analytics"];
@@ -92,7 +100,7 @@ export function isConsentDecision(value: unknown): value is ConsentDecision {
92
100
  * dropped, every category becomes an explicit boolean. The one normalization rule every
93
101
  * reader of stored consent shares (e.g. `readStoredDecision`).
94
102
  *
95
- * @since 1.0.0-canary.6
103
+ * @since 0.5.0-canary.6
96
104
  */
97
105
  export function normalizeConsentDecision(decision: ConsentDecision): ConsentDecision {
98
106
  return createConsentDecision(CONSENT_CATEGORIES.filter((category) => decision[category]));
@@ -101,7 +109,7 @@ export function normalizeConsentDecision(decision: ConsentDecision): ConsentDeci
101
109
  /**
102
110
  * Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
103
111
  *
104
- * @since 1.0.0-canary.6
112
+ * @since 0.5.0-canary.6
105
113
  */
106
114
  export function isConsentRecord(value: unknown): value is ConsentRecord {
107
115
  return (
@@ -113,7 +121,9 @@ export function isConsentRecord(value: unknown): value is ConsentRecord {
113
121
  }
114
122
 
115
123
  /**
116
- * @since 1.0.0-canary.6
124
+ * Options for `resolveDefaultConsent`.
125
+ *
126
+ * @since 0.5.0-canary.6
117
127
  */
118
128
  export interface ResolveDefaultConsentOptions {
119
129
  /** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
@@ -157,7 +167,7 @@ export function resolveDefaultConsent(options: ResolveDefaultConsentOptions): Co
157
167
  * `defaultConsent` is the server snapshot — useful when you need request-time `sec-gpc`
158
168
  * as-is; analytics-only apps can ignore it because GPC only forces `ads` denied.
159
169
  *
160
- * @since 1.0.0-canary.6
170
+ * @since 0.5.0-canary.6
161
171
  */
162
172
  export interface InitialConsent {
163
173
  defaultConsent: ConsentDecision;
@@ -171,7 +181,7 @@ export interface InitialConsent {
171
181
  * Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
172
182
  * header means "unknown visitor", never "known non-EU visitor".
173
183
  *
174
- * @since 1.0.0-canary.6
184
+ * @since 0.5.0-canary.6
175
185
  */
176
186
  export const STRICTEST_INITIAL_CONSENT: InitialConsent = Object.freeze({
177
187
  defaultConsent: Object.freeze(createConsentDecision([])),
@@ -185,7 +195,7 @@ export const STRICTEST_INITIAL_CONSENT: InitialConsent = Object.freeze({
185
195
  * {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
186
196
  * mode, never looser.
187
197
  *
188
- * @since 1.0.0-canary.6
198
+ * @since 0.5.0-canary.6
189
199
  */
190
200
  export function isInitialConsent(value: unknown): value is InitialConsent {
191
201
  if (!isPlainObject(value)) {
@@ -244,7 +254,7 @@ export interface ConsentStorage {
244
254
  * any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
245
255
  * it was recorded under a superseded policy version.
246
256
  *
247
- * @since 1.0.0-canary.6
257
+ * @since 0.5.0-canary.6
248
258
  */
249
259
  export function readStoredDecision(storage: ConsentStorage, policyVersion: string): ConsentDecision | undefined {
250
260
  const record = storage.load();
@@ -257,7 +267,9 @@ export function readStoredDecision(storage: ConsentStorage, policyVersion: strin
257
267
  }
258
268
 
259
269
  /**
260
- * @since 1.0.0-canary.6
270
+ * Options for `resolveEffectiveConsent`.
271
+ *
272
+ * @since 0.5.0-canary.6
261
273
  */
262
274
  export interface ResolveEffectiveConsentOptions {
263
275
  /** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
@@ -274,7 +286,7 @@ export interface ResolveEffectiveConsentOptions {
274
286
  * non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
275
287
  * "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
276
288
  *
277
- * @since 1.0.0-canary.6
289
+ * @since 0.5.0-canary.6
278
290
  */
279
291
  export function resolveEffectiveConsent(options: ResolveEffectiveConsentOptions): ConsentDecision {
280
292
  const { hasGlobalPrivacyControlSignal, mode, policyVersion, requestedCategories, storage } = options;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Default lifetime shared by the anonymous-id and consent cookies — one year.
3
3
  *
4
- * @since 1.0.0-canary.6
4
+ * @since 0.5.0-canary.6
5
5
  */
6
6
  export const ONE_YEAR_IN_SECONDS: number = 60 * 60 * 24 * 365;
7
7
 
@@ -10,7 +10,7 @@ export const ONE_YEAR_IN_SECONDS: number = 60 * 60 * 24 * 365;
10
10
  * `document.cookie`, which share the `name=value; name2=value2` wire format — or
11
11
  * `undefined` when absent. The name must match exactly; a longer prefix sibling is ignored.
12
12
  *
13
- * @since 1.0.0-canary.6
13
+ * @since 0.5.0-canary.6
14
14
  */
15
15
  export function readCookieValue(cookieString: string | null | undefined, cookieName: string): string | undefined {
16
16
  if (!cookieString) {
@@ -35,7 +35,7 @@ export function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalo
35
35
  * @throws Error when validation reports issues, or when the schema validates asynchronously —
36
36
  * tracking sits on synchronous call paths, so async schemas are unsupported by design.
37
37
  *
38
- * @since 1.0.0-canary.6
38
+ * @since 0.5.0-canary.6
39
39
  */
40
40
  export function assertValidEventProperties(schema: StandardSchemaV1, eventName: string, properties: unknown): unknown {
41
41
  const result = schema["~standard"].validate(properties);
@@ -7,7 +7,7 @@ import type { ConsentDecision } from "#/core/consent";
7
7
  * restricts to LDU but MUST NOT withhold first-party `analytics` (spec-consent §3). Every
8
8
  * ad destination consumes this same shape so per-vendor mappings cannot drift.
9
9
  *
10
- * @since 1.0.0-canary.7
10
+ * @since 0.5.0-canary.6
11
11
  */
12
12
  export interface AdConsentState {
13
13
  /** `ads` denied → the platform must restrict to Limited Data Use (Meta/TikTok LDU, UET `ad_storage` denied). */
@@ -19,7 +19,7 @@ export interface AdConsentState {
19
19
  /**
20
20
  * Normalizes a package `ConsentDecision` to the vendor-agnostic {@link AdConsentState}.
21
21
  *
22
- * @since 1.0.0-canary.7
22
+ * @since 0.5.0-canary.6
23
23
  */
24
24
  export function toAdConsentState(decision: ConsentDecision): AdConsentState {
25
25
  return {