@codefast/tracking 0.5.0-canary.4 → 1.0.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 (134) hide show
  1. package/CHANGELOG.md +171 -0
  2. package/README.md +123 -96
  3. package/dist/client/browser-cookie.d.mts +11 -0
  4. package/dist/client/browser-cookie.mjs +15 -0
  5. package/dist/client/consent-runtime.d.mts +56 -0
  6. package/dist/client/consent-runtime.mjs +35 -0
  7. package/dist/client/consent-storage.d.mts +5 -0
  8. package/dist/client/consent-storage.mjs +20 -1
  9. package/dist/client/consent-withdrawal.d.mts +21 -0
  10. package/dist/client/consent-withdrawal.mjs +17 -0
  11. package/dist/client/cookie-anonymous-id.d.mts +37 -0
  12. package/dist/client/cookie-anonymous-id.mjs +46 -0
  13. package/dist/client/create-client-tracker.d.mts +11 -16
  14. package/dist/client/create-client-tracker.mjs +27 -53
  15. package/dist/client/gpc.d.mts +2 -0
  16. package/dist/client/gpc.mjs +3 -1
  17. package/dist/client/index.d.mts +7 -5
  18. package/dist/client/index.mjs +8 -6
  19. package/dist/client/initial-consent-store.d.mts +66 -0
  20. package/dist/client/initial-consent-store.mjs +119 -0
  21. package/dist/client/is-analytics-allowed.d.mts +29 -0
  22. package/dist/client/is-analytics-allowed.mjs +23 -0
  23. package/dist/client/server-persisted-anonymous-id.d.mts +33 -0
  24. package/dist/client/server-persisted-anonymous-id.mjs +50 -0
  25. package/dist/core/consent-config.d.mts +27 -0
  26. package/dist/core/consent-config.mjs +11 -0
  27. package/dist/core/consent.d.mts +99 -4
  28. package/dist/core/consent.mjs +99 -4
  29. package/dist/core/cookie.d.mts +17 -0
  30. package/dist/core/cookie.mjs +23 -0
  31. package/dist/core/destination.d.mts +10 -8
  32. package/dist/core/event-catalog.d.mts +16 -13
  33. package/dist/core/event-catalog.mjs +19 -1
  34. package/dist/core/event-id.d.mts +1 -2
  35. package/dist/core/event-id.mjs +1 -2
  36. package/dist/core/index.d.mts +6 -4
  37. package/dist/core/index.mjs +5 -3
  38. package/dist/core/tracked-event.d.mts +21 -8
  39. package/dist/destinations/google-analytics.d.mts +100 -48
  40. package/dist/destinations/google-analytics.mjs +89 -85
  41. package/dist/destinations/google-consent.d.mts +64 -0
  42. package/dist/destinations/google-consent.mjs +102 -0
  43. package/dist/destinations/index.d.mts +2 -5
  44. package/dist/destinations/index.mjs +2 -5
  45. package/dist/destinations/shared.d.mts +20 -0
  46. package/dist/destinations/shared.mjs +13 -0
  47. package/dist/destinations/vercel-analytics.d.mts +19 -4
  48. package/dist/destinations/vercel-analytics.mjs +11 -18
  49. package/dist/import-protection.d.mts +19 -0
  50. package/dist/import-protection.mjs +23 -0
  51. package/dist/index.d.mts +6 -4
  52. package/dist/index.mjs +5 -3
  53. package/dist/react/consent-banner.d.mts +143 -38
  54. package/dist/react/consent-banner.mjs +192 -92
  55. package/dist/react/gtag-consent-bootstrap.d.mts +27 -0
  56. package/dist/react/gtag-consent-bootstrap.mjs +29 -0
  57. package/dist/react/index.d.mts +5 -2
  58. package/dist/react/index.mjs +5 -2
  59. package/dist/react/use-consent.d.mts +9 -13
  60. package/dist/react/use-consent.mjs +42 -25
  61. package/dist/react/use-google-consent-sync.d.mts +23 -0
  62. package/dist/react/use-google-consent-sync.mjs +24 -0
  63. package/dist/react/use-initial-consent.d.mts +14 -0
  64. package/dist/react/use-initial-consent.mjs +19 -0
  65. package/dist/server/anonymous-id-cookie.d.mts +46 -0
  66. package/dist/server/anonymous-id-cookie.mjs +51 -0
  67. package/dist/server/index.d.mts +5 -3
  68. package/dist/server/index.mjs +4 -3
  69. package/dist/server/initial-consent.d.mts +29 -0
  70. package/dist/server/initial-consent.mjs +31 -0
  71. package/dist/server/region.d.mts +21 -4
  72. package/dist/server/region.mjs +26 -5
  73. package/dist/tanstack-start/index.d.mts +58 -0
  74. package/dist/tanstack-start/index.mjs +45 -0
  75. package/package.json +27 -110
  76. package/src/client/browser-cookie.ts +16 -0
  77. package/src/client/consent-runtime.ts +80 -0
  78. package/src/client/consent-storage.ts +31 -1
  79. package/src/client/consent-withdrawal.ts +32 -0
  80. package/src/client/cookie-anonymous-id.ts +93 -0
  81. package/src/client/create-client-tracker.ts +56 -85
  82. package/src/client/gpc.ts +4 -2
  83. package/src/client/index.ts +19 -8
  84. package/src/client/initial-consent-store.ts +218 -0
  85. package/src/client/is-analytics-allowed.ts +43 -0
  86. package/src/client/server-persisted-anonymous-id.ts +99 -0
  87. package/src/core/consent-config.ts +27 -0
  88. package/src/core/consent.ts +164 -10
  89. package/src/core/cookie.ts +29 -0
  90. package/src/core/destination.ts +10 -8
  91. package/src/core/event-catalog.ts +28 -15
  92. package/src/core/event-id.ts +1 -2
  93. package/src/core/index.ts +19 -3
  94. package/src/core/tracked-event.ts +22 -7
  95. package/src/css/consent.css +119 -0
  96. package/src/destinations/google-analytics.ts +196 -133
  97. package/src/destinations/google-consent.ts +164 -0
  98. package/src/destinations/index.ts +14 -15
  99. package/src/destinations/shared.ts +45 -0
  100. package/src/destinations/vercel-analytics.ts +23 -24
  101. package/src/import-protection.ts +20 -0
  102. package/src/index.ts +46 -8
  103. package/src/react/consent-banner.tsx +308 -111
  104. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  105. package/src/react/index.ts +34 -2
  106. package/src/react/use-consent.ts +53 -45
  107. package/src/react/use-google-consent-sync.ts +38 -0
  108. package/src/react/use-initial-consent.ts +22 -0
  109. package/src/server/anonymous-id-cookie.ts +76 -0
  110. package/src/server/index.ts +15 -3
  111. package/src/server/initial-consent.ts +48 -0
  112. package/src/server/region.ts +22 -5
  113. package/src/tanstack-start/index.ts +83 -0
  114. package/dist/client/lifecycle.d.mts +0 -23
  115. package/dist/client/lifecycle.mjs +0 -30
  116. package/dist/client/local-storage.d.mts +0 -13
  117. package/dist/client/local-storage.mjs +0 -31
  118. package/dist/client/queue.d.mts +0 -49
  119. package/dist/client/queue.mjs +0 -71
  120. package/dist/client/router.d.mts +0 -30
  121. package/dist/client/router.mjs +0 -17
  122. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  123. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  124. package/dist/destinations/http-destination.d.mts +0 -20
  125. package/dist/destinations/http-destination.mjs +0 -25
  126. package/dist/server/create-server-tracker.d.mts +0 -42
  127. package/dist/server/create-server-tracker.mjs +0 -67
  128. package/src/client/lifecycle.ts +0 -50
  129. package/src/client/local-storage.ts +0 -44
  130. package/src/client/queue.ts +0 -117
  131. package/src/client/router.ts +0 -37
  132. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  133. package/src/destinations/http-destination.ts +0 -33
  134. package/src/server/create-server-tracker.ts +0 -128
@@ -1,22 +1,20 @@
1
- import { useRef, useSyncExternalStore } from "react";
1
+ "use client";
2
2
 
3
- import type { ConsentCategory, ConsentDecision, ConsentMode, ConsentStorage } from "#/core/consent";
4
- import { CONSENT_CATEGORIES, createConsentDecision, isConsentDecision, resolveDefaultConsent } from "#/core/consent";
3
+ import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
4
+
5
+ import type { ConsentDecision, ConsentMode, ConsentStorage } from "#/core/consent";
6
+ import { CONSENT_CATEGORIES, createConsentDecision, readStoredDecision, resolveDefaultConsent } from "#/core/consent";
7
+ import type { ConsentConfig } from "#/core/consent-config";
5
8
 
6
9
  /**
7
10
  * @since 0.5.0-canary.4
8
11
  */
9
12
  export interface UseConsentOptions {
10
- /**
11
- * Categories the app's prompt actually asks about — `grantAll` grants exactly these,
12
- * so an analytics-only banner can never grant ads consent it never asked for.
13
- * Defaults to `["analytics"]`.
14
- */
15
- categories?: ReadonlyArray<ConsentCategory>;
16
- hasGlobalPrivacyControlSignal?: boolean;
13
+ /** Must be the same object the tracker gate and the tag bootstraps receive — one config, every surface. */
14
+ config: ConsentConfig;
15
+ hasGlobalPrivacyControlSignal?: boolean | undefined;
17
16
  mode: ConsentMode;
18
- onDecision?: (decision: ConsentDecision) => void;
19
- policyVersion: string;
17
+ onDecision?: ((decision: ConsentDecision) => void) | undefined;
20
18
  /** Must be a stable reference (module-level or memoized) — a new object per render resubscribes every render. */
21
19
  storage: ConsentStorage;
22
20
  }
@@ -32,15 +30,13 @@ export interface UseConsentResult {
32
30
  effectiveConsent: ConsentDecision;
33
31
  grantAll: () => void;
34
32
  /** Effective `analytics` consent — gates this package's own tracker pipeline. */
35
- isTrackingAllowed: boolean;
33
+ isAnalyticsAllowed: boolean;
36
34
  /** True only for opt-in regions with no stored decision yet — drives whether to render the banner. */
37
- needsPrompt: boolean;
35
+ isPromptNeeded: boolean;
38
36
  /** Persist a granular per-category choice, e.g. from a preferences panel. */
39
- save: (decision: ConsentDecision) => void;
37
+ saveDecision: (decision: ConsentDecision) => void;
40
38
  }
41
39
 
42
- const DEFAULT_CATEGORIES: ReadonlyArray<ConsentCategory> = ["analytics"];
43
-
44
40
  /**
45
41
  * Bridges `resolveConsentMode`/`resolveDefaultConsent` (core, region-aware) to React via
46
42
  * `useSyncExternalStore`: the stored record is the single source of truth, hydration is
@@ -51,8 +47,9 @@ const DEFAULT_CATEGORIES: ReadonlyArray<ConsentCategory> = ["analytics"];
51
47
  * @since 0.5.0-canary.4
52
48
  */
53
49
  export function useConsent(options: UseConsentOptions): UseConsentResult {
54
- const { storage } = options;
55
- const categories = options.categories ?? DEFAULT_CATEGORIES;
50
+ const { mode, onDecision, storage } = options;
51
+ const { policyVersion, requestedCategories } = options.config;
52
+ const hasGlobalPrivacyControlSignal = options.hasGlobalPrivacyControlSignal ?? false;
56
53
 
57
54
  // useSyncExternalStore needs a referentially stable snapshot, but JSON-backed storages
58
55
  // parse a fresh record per load — so the last valid decision is cached by value.
@@ -61,51 +58,62 @@ export function useConsent(options: UseConsentOptions): UseConsentResult {
61
58
  const decision = useSyncExternalStore(
62
59
  storage.subscribe,
63
60
  (): ConsentDecision | undefined => {
64
- const record = storage.load();
65
-
66
61
  // Only a well-formed decision under the current policy version counts — the store
67
62
  // is tamperable plain JSON, and a garbage value must re-prompt, not silently deny.
68
- if (record?.policyVersion !== options.policyVersion || !isConsentDecision(record.decision)) {
63
+ const stored = readStoredDecision(storage, policyVersion);
64
+
65
+ if (stored === undefined) {
69
66
  cachedDecision.current = undefined;
70
67
 
71
68
  return undefined;
72
69
  }
73
70
 
74
- const stored = record.decision;
75
71
  const cached = cachedDecision.current;
76
72
 
77
73
  if (cached !== undefined && CONSENT_CATEGORIES.every((category) => cached[category] === stored[category])) {
78
74
  return cached;
79
75
  }
80
76
 
81
- // A normalized copy, so tampered extra keys never leak past the hook.
82
- cachedDecision.current = createConsentDecision(CONSENT_CATEGORIES.filter((category) => stored[category]));
77
+ cachedDecision.current = stored;
83
78
 
84
79
  return cachedDecision.current;
85
80
  },
86
81
  () => undefined,
87
82
  );
88
83
 
89
- function save(next: ConsentDecision): void {
90
- // No local state — the save notifies the subscription, which re-renders with the new snapshot.
91
- storage.save({ decision: next, policyVersion: options.policyVersion, timestamp: Date.now() });
92
- options.onDecision?.(next);
93
- }
84
+ // Kept stable across renders (when their own inputs don't change) so a consumer that
85
+ // passes this hook's result down as a prop/effect-dep doesn't get a fresh identity —
86
+ // and therefore an unnecessary re-render/effect-rerun — every render.
87
+ const saveDecision = useCallback(
88
+ (next: ConsentDecision): void => {
89
+ // No local state — the save notifies the subscription, which re-renders with the new snapshot.
90
+ storage.save({ decision: next, policyVersion, timestamp: Date.now() });
91
+ onDecision?.(next);
92
+ },
93
+ [onDecision, policyVersion, storage],
94
+ );
95
+
96
+ const denyAll = useCallback(() => {
97
+ saveDecision(createConsentDecision([]));
98
+ }, [saveDecision]);
94
99
 
95
- const effectiveConsent =
96
- decision ?? resolveDefaultConsent(options.mode, categories, options.hasGlobalPrivacyControlSignal ?? false);
100
+ const grantAll = useCallback(() => {
101
+ saveDecision(createConsentDecision(requestedCategories));
102
+ }, [requestedCategories, saveDecision]);
97
103
 
98
- return {
99
- decision,
100
- denyAll: () => {
101
- save(createConsentDecision([]));
102
- },
103
- effectiveConsent,
104
- grantAll: () => {
105
- save(createConsentDecision(categories));
106
- },
107
- isTrackingAllowed: effectiveConsent.analytics,
108
- needsPrompt: options.mode === "opt-in" && decision === undefined,
109
- save,
110
- };
104
+ const effectiveConsent =
105
+ decision ?? resolveDefaultConsent({ hasGlobalPrivacyControlSignal, mode, requestedCategories });
106
+
107
+ return useMemo(
108
+ () => ({
109
+ decision,
110
+ denyAll,
111
+ effectiveConsent,
112
+ grantAll,
113
+ isAnalyticsAllowed: effectiveConsent.analytics,
114
+ isPromptNeeded: mode === "opt-in" && decision === undefined,
115
+ saveDecision,
116
+ }),
117
+ [decision, denyAll, effectiveConsent, grantAll, mode, saveDecision],
118
+ );
111
119
  }
@@ -0,0 +1,38 @@
1
+ "use client";
2
+
3
+ import { useEffect } from "react";
4
+
5
+ import { updateGoogleConsent } from "#/destinations/google-analytics";
6
+ import type { UseConsentResult } from "#/react/use-consent";
7
+
8
+ /**
9
+ * @since 1.0.0-canary.6
10
+ */
11
+ export interface UseGoogleConsentSyncOptions {
12
+ /**
13
+ * Idempotent gtag.js load — advanced Consent Mode already injects the tag from a
14
+ * bootstrap; pass a loader as a safety net after a runtime grant.
15
+ */
16
+ loadGtagScript?: (() => void) | undefined;
17
+ }
18
+
19
+ /**
20
+ * Keeps Google Consent Mode v2 in sync with `useConsent`: emits `update` when a stored
21
+ * decision exists (including cross-tab / privacy-page saves), and optionally loads gtag
22
+ * when analytics is effective. Mount once on a page-wide surface (e.g. the footer gate).
23
+ *
24
+ * @since 1.0.0-canary.6
25
+ */
26
+ export function useGoogleConsentSync(consent: UseConsentResult, options: UseGoogleConsentSyncOptions = {}): void {
27
+ const { loadGtagScript } = options;
28
+
29
+ useEffect(() => {
30
+ if (consent.decision !== undefined) {
31
+ updateGoogleConsent(consent.decision);
32
+ }
33
+
34
+ if (consent.effectiveConsent.analytics) {
35
+ loadGtagScript?.();
36
+ }
37
+ }, [consent.decision, consent.effectiveConsent.analytics, loadGtagScript]);
38
+ }
@@ -0,0 +1,22 @@
1
+ "use client";
2
+
3
+ import { useEffect, useSyncExternalStore } from "react";
4
+
5
+ import type { InitialConsentSnapshot, InitialConsentStore } from "#/client/initial-consent-store";
6
+
7
+ /**
8
+ * Reactive view of a `createInitialConsentStore` — kicks off resolution on mount (a no-op
9
+ * when the app already did so at router creation) and re-renders once the server lane
10
+ * answers. SSR and the first client render read the strictest snapshot, so hydration can
11
+ * never mismatch on region.
12
+ *
13
+ * @since 1.0.0-canary.6
14
+ */
15
+ export function useInitialConsent(store: InitialConsentStore): InitialConsentSnapshot {
16
+ // Post-hydration safety net — idempotent with an earlier, pre-hydration kick.
17
+ useEffect(() => {
18
+ store.ensureResolved();
19
+ }, [store]);
20
+
21
+ return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
22
+ }
@@ -0,0 +1,76 @@
1
+ import { ONE_YEAR_IN_SECONDS } from "#/core/cookie";
2
+
3
+ // The only shape the client ever mints (crypto.randomUUID) — anything else is rejected.
4
+ const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
5
+
6
+ // Conservative subset of the RFC 6265 cookie-name token.
7
+ const COOKIE_NAME_PATTERN = /^[\w-]+$/;
8
+
9
+ function assertCookieName(cookieName: string): void {
10
+ if (!COOKIE_NAME_PATTERN.test(cookieName)) {
11
+ throw new Error(`Invalid anonymous-id cookie name: ${JSON.stringify(cookieName)}`);
12
+ }
13
+ }
14
+
15
+ /**
16
+ * Whether a value is safe to persist as an anonymous id. The persist endpoint is public
17
+ * and echoes its input into a response header, so only an exactly-UUID-shaped value may
18
+ * pass — anything else is a header-injection attempt or corruption, never a valid id.
19
+ *
20
+ * @since 1.0.0-canary.6
21
+ */
22
+ export function isValidAnonymousId(value: string): boolean {
23
+ return UUID_PATTERN.test(value);
24
+ }
25
+
26
+ /**
27
+ * @since 1.0.0-canary.6
28
+ */
29
+ export interface AnonymousIdSetCookieOptions {
30
+ /** Cookie name — must match what the client tracker reads. */
31
+ cookieName: string;
32
+ /** The client-minted id to persist — throws unless it is exactly UUID-shaped. */
33
+ id: string;
34
+ /** How long the id survives a return visit. Defaults to one year. */
35
+ maxAgeSeconds?: number | undefined;
36
+ }
37
+
38
+ /**
39
+ * `Set-Cookie` header value that persists (or prolongs) a client-minted anonymous id from
40
+ * the server. A server-set cookie escapes Safari ITP's 7-day cap on `document.cookie`
41
+ * writes, so the id actually lives its full max-age. The server only ever re-sets an id
42
+ * the client hands it — minting stays client-side, after consent, by design.
43
+ *
44
+ * @remarks
45
+ * Always `Secure` — on a plain-HTTP dev origin a browser may drop it, and the
46
+ * client-written cookie (`createServerPersistedAnonymousId`'s optimistic write) still
47
+ * covers that session. Not `HttpOnly`: the client tracker must read the id to stamp it
48
+ * onto events.
49
+ *
50
+ * @throws Error when `id` is not UUID-shaped or `cookieName` is not a valid token.
51
+ *
52
+ * @since 1.0.0-canary.6
53
+ */
54
+ export function buildAnonymousIdSetCookie(options: AnonymousIdSetCookieOptions): string {
55
+ const { cookieName, id, maxAgeSeconds = ONE_YEAR_IN_SECONDS } = options;
56
+
57
+ assertCookieName(cookieName);
58
+
59
+ if (!isValidAnonymousId(id)) {
60
+ throw new Error("Invalid anonymous id: expected a UUID-shaped value");
61
+ }
62
+
63
+ return `${cookieName}=${id}; Path=/; Max-Age=${String(maxAgeSeconds)}; SameSite=Lax; Secure`;
64
+ }
65
+
66
+ /**
67
+ * `Set-Cookie` header value that expires the anonymous-id cookie — the server half of a
68
+ * consent withdrawal, alongside the client's own `document.cookie` expiry.
69
+ *
70
+ * @since 1.0.0-canary.6
71
+ */
72
+ export function buildClearAnonymousIdSetCookie(cookieName: string): string {
73
+ assertCookieName(cookieName);
74
+
75
+ return `${cookieName}=; Path=/; Max-Age=0; SameSite=Lax; Secure`;
76
+ }
@@ -1,4 +1,16 @@
1
- export type { ServerTrackContext, ServerTracker, ServerTrackerOptions } from "#/server/create-server-tracker";
2
- export { createServerTracker } from "#/server/create-server-tracker";
1
+ export type { AnonymousIdSetCookieOptions } from "#/server/anonymous-id-cookie";
2
+ export {
3
+ buildAnonymousIdSetCookie,
4
+ buildClearAnonymousIdSetCookie,
5
+ isValidAnonymousId,
6
+ } from "#/server/anonymous-id-cookie";
3
7
 
4
- export { resolveRegion, resolveRegionFromCountryCode } from "#/server/region";
8
+ export type { InitialConsent, InitialConsentOptions } from "#/server/initial-consent";
9
+ export { resolveInitialConsent } from "#/server/initial-consent";
10
+
11
+ export {
12
+ EU_COUNTRY_CODES,
13
+ OPT_IN_EQUIVALENT_COUNTRY_CODES,
14
+ resolveRegion,
15
+ resolveRegionFromCountryCode,
16
+ } from "#/server/region";
@@ -0,0 +1,48 @@
1
+ import type { ConsentCategory, InitialConsent } from "#/core/consent";
2
+ import { resolveConsentMode, resolveDefaultConsent, STRICTEST_INITIAL_CONSENT } from "#/core/consent";
3
+ import { resolveRegionFromCountryCode } from "#/server/region";
4
+
5
+ export type { InitialConsent };
6
+
7
+ /**
8
+ * @since 1.0.0-canary.6
9
+ */
10
+ export interface InitialConsentOptions {
11
+ /** ISO 3166-1 alpha-2 from the geo header; missing → the strictest opt-in default. */
12
+ countryCode: string | undefined;
13
+ /** Honored as an ads-only opt-out on the default decision. */
14
+ hasGlobalPrivacyControlSignal?: boolean | undefined;
15
+ /** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
16
+ requestedCategories: ReadonlyArray<ConsentCategory>;
17
+ }
18
+
19
+ /**
20
+ * Pure region → mode → default-consent resolution for server functions (or a fail-closed
21
+ * bake when country is unknown). Named with the `resolve*` family it composes.
22
+ *
23
+ * @remarks
24
+ * A missing country code means an unknown visitor (a prerender crawl, a host without a
25
+ * geo header) — not a known non-EU visitor — so it fails closed to
26
+ * {@link STRICTEST_INITIAL_CONSENT} instead of `"other"`'s opt-out. Conflating the two
27
+ * would grant analytics by default to every visitor, EU included, on a geo-less host.
28
+ *
29
+ * @since 1.0.0-canary.6
30
+ */
31
+ export function resolveInitialConsent(options: InitialConsentOptions): InitialConsent {
32
+ if (!options.countryCode) {
33
+ return STRICTEST_INITIAL_CONSENT;
34
+ }
35
+
36
+ const region = resolveRegionFromCountryCode(options.countryCode);
37
+ const mode = resolveConsentMode(region);
38
+
39
+ return {
40
+ defaultConsent: resolveDefaultConsent({
41
+ hasGlobalPrivacyControlSignal: options.hasGlobalPrivacyControlSignal ?? false,
42
+ mode,
43
+ requestedCategories: options.requestedCategories,
44
+ }),
45
+ mode,
46
+ region,
47
+ };
48
+ }
@@ -1,6 +1,11 @@
1
1
  import type { ConsentRegion } from "#/core/consent";
2
2
 
3
- const EU_COUNTRY_CODES = new Set([
3
+ /**
4
+ * EU member states — GDPR opt-in via `resolveConsentMode("eu")`.
5
+ *
6
+ * @since 1.0.0-canary.6
7
+ */
8
+ export const EU_COUNTRY_CODES: ReadonlySet<string> = new Set([
4
9
  "AT",
5
10
  "BE",
6
11
  "BG",
@@ -31,9 +36,21 @@ const EU_COUNTRY_CODES = new Set([
31
36
  ]);
32
37
 
33
38
  /**
34
- * Missing/unrecognized codes fall back to "other", which `resolveConsentMode` treats
35
- * as opt-out — the least restrictive default, safe only because opt-in regions (EU/VN)
36
- * are matched explicitly above it.
39
+ * UK GDPR (post-Brexit) and EEA/EFTA states that apply GDPR-equivalent rules — mapped to
40
+ * the same `"eu"` consent region so they get opt-in, not the `"other"` opt-out default.
41
+ *
42
+ * Restricted edge runtimes that cannot import this package should duplicate these codes
43
+ * and keep a sync test against this export.
44
+ *
45
+ * @since 1.0.0-canary.6
46
+ */
47
+ export const OPT_IN_EQUIVALENT_COUNTRY_CODES: ReadonlySet<string> = new Set(["GB", "IS", "LI", "NO"]);
48
+
49
+ /**
50
+ * Unrecognized codes fall back to "other", which `resolveConsentMode` treats as
51
+ * opt-out — safe only because opt-in regions (EU/VN plus UK/EEA/EFTA above) are matched
52
+ * explicitly. A *missing* code also maps to "other" here, but `resolveInitialConsent`
53
+ * intercepts that case first and fails closed — unknown is not known-elsewhere.
37
54
  *
38
55
  * @since 0.5.0-canary.4
39
56
  */
@@ -44,7 +61,7 @@ export function resolveRegionFromCountryCode(countryCode: string | undefined): C
44
61
 
45
62
  const normalized = countryCode.toUpperCase();
46
63
 
47
- if (EU_COUNTRY_CODES.has(normalized)) {
64
+ if (EU_COUNTRY_CODES.has(normalized) || OPT_IN_EQUIVALENT_COUNTRY_CODES.has(normalized)) {
48
65
  return "eu";
49
66
  }
50
67
 
@@ -0,0 +1,83 @@
1
+ import { getRequestHeader, setResponseHeader } from "@tanstack/react-start/server";
2
+
3
+ import type { ConsentCategory, InitialConsent } from "#/core/consent";
4
+ import { buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie } from "#/server/anonymous-id-cookie";
5
+ import { resolveInitialConsent } from "#/server/initial-consent";
6
+
7
+ /**
8
+ * Request/response glue for TanStack Start — each helper reads or writes the framework's
9
+ * ambient request context (AsyncLocalStorage), so a consumer's server functions shrink to
10
+ * one-line handlers around them. Server-only: deny this subpath in the client environment
11
+ * via Start's `importProtection` — the compiler already strips it with stubbed handler bodies.
12
+ *
13
+ * @since 1.0.0-canary.6
14
+ */
15
+
16
+ export interface InitialConsentFromRequestOptions {
17
+ /**
18
+ * Header carrying the ISO 3166-1 alpha-2 country code.
19
+ *
20
+ * @defaultValue "x-vercel-ip-country"
21
+ */
22
+ countryHeaderName?: string | undefined;
23
+ /** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
24
+ requestedCategories: ReadonlyArray<ConsentCategory>;
25
+ }
26
+
27
+ /**
28
+ * Region-correct `InitialConsent` for the current request: reads the platform geo header
29
+ * and `sec-gpc`, fails closed when geo is missing, and stamps
30
+ * `cache-control: private, no-store` — the value is per-visitor by definition, so no
31
+ * shared cache may ever store the response carrying it.
32
+ *
33
+ * @since 1.0.0-canary.6
34
+ */
35
+ export function resolveInitialConsentFromRequest(options: InitialConsentFromRequestOptions): InitialConsent {
36
+ setResponseHeader("cache-control", "private, no-store");
37
+
38
+ return resolveInitialConsent({
39
+ countryCode: getRequestHeader(options.countryHeaderName ?? "x-vercel-ip-country"),
40
+ hasGlobalPrivacyControlSignal: getRequestHeader("sec-gpc") === "1",
41
+ requestedCategories: options.requestedCategories,
42
+ });
43
+ }
44
+
45
+ /**
46
+ * @since 1.0.0-canary.6
47
+ */
48
+ export interface AnonymousIdResponseCookieOptions {
49
+ /** Cookie name — must match what the client tracker reads. */
50
+ cookieName: string;
51
+ /** The client-minted id to persist — throws unless it is exactly UUID-shaped. */
52
+ id: string;
53
+ /** How long the id survives a return visit. Defaults to one year. */
54
+ maxAgeSeconds?: number | undefined;
55
+ }
56
+
57
+ /**
58
+ * Persists (or prolongs) a client-minted anonymous id via `Set-Cookie` on the current
59
+ * response — the server re-issue that escapes Safari ITP's 7-day cap on script-written
60
+ * cookies. Validation lives in `buildAnonymousIdSetCookie`: a non-UUID id throws, so this
61
+ * can safely back a public server function without echoing attacker input into a header.
62
+ *
63
+ * @since 1.0.0-canary.6
64
+ */
65
+ export function setAnonymousIdResponseCookie(options: AnonymousIdResponseCookieOptions): void {
66
+ setResponseHeader(
67
+ "set-cookie",
68
+ buildAnonymousIdSetCookie({
69
+ cookieName: options.cookieName,
70
+ id: options.id,
71
+ maxAgeSeconds: options.maxAgeSeconds,
72
+ }),
73
+ );
74
+ }
75
+
76
+ /**
77
+ * Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
78
+ *
79
+ * @since 1.0.0-canary.6
80
+ */
81
+ export function clearAnonymousIdResponseCookie(cookieName: string): void {
82
+ setResponseHeader("set-cookie", buildClearAnonymousIdSetCookie(cookieName));
83
+ }
@@ -1,23 +0,0 @@
1
- import { EventCatalog } from "../core/event-catalog.mjs";
2
- import { ClientTracker } from "./create-client-tracker.mjs";
3
-
4
- //#region src/client/lifecycle.d.ts
5
- /**
6
- * @since 0.5.0-canary.4
7
- */
8
- interface ClientLifecycleOptions {
9
- /** `sendBeacon` target used on unload — omit to skip the unload flush entirely. */
10
- beaconEndpoint?: string;
11
- flushIntervalMs?: number;
12
- }
13
- /**
14
- * Wires the two flush triggers the queue itself can't own (batch-size is handled inside
15
- * `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
16
- * unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
17
- * Returns a cleanup function to remove all listeners/timers.
18
- *
19
- * @since 0.5.0-canary.4
20
- */
21
- declare function attachClientLifecycle<Catalog extends EventCatalog>(tracker: Pick<ClientTracker<Catalog>, "flush" | "flushWithBeacon">, options?: ClientLifecycleOptions): () => void;
22
- //#endregion
23
- export { ClientLifecycleOptions, attachClientLifecycle };
@@ -1,30 +0,0 @@
1
- //#region src/client/lifecycle.ts
2
- /**
3
- * Wires the two flush triggers the queue itself can't own (batch-size is handled inside
4
- * `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
5
- * unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
6
- * Returns a cleanup function to remove all listeners/timers.
7
- *
8
- * @since 0.5.0-canary.4
9
- */
10
- function attachClientLifecycle(tracker, options = {}) {
11
- const flushIntervalMs = options.flushIntervalMs ?? 1e4;
12
- const intervalId = setInterval(() => {
13
- tracker.flush();
14
- }, flushIntervalMs);
15
- function flushOnUnload() {
16
- if (options.beaconEndpoint !== void 0) tracker.flushWithBeacon(options.beaconEndpoint);
17
- }
18
- function handleVisibilityChange() {
19
- if (document.visibilityState === "hidden") flushOnUnload();
20
- }
21
- document.addEventListener("visibilitychange", handleVisibilityChange);
22
- window.addEventListener("pagehide", flushOnUnload);
23
- return () => {
24
- clearInterval(intervalId);
25
- document.removeEventListener("visibilitychange", handleVisibilityChange);
26
- window.removeEventListener("pagehide", flushOnUnload);
27
- };
28
- }
29
- //#endregion
30
- export { attachClientLifecycle };
@@ -1,13 +0,0 @@
1
- import { EventQueueStorage } from "./queue.mjs";
2
-
3
- //#region src/client/local-storage.d.ts
4
- /**
5
- * `localStorage`-backed queue storage — corrupt/missing state, a private-mode/quota
6
- * error, or no `window` (SSR) are all treated as empty rather than thrown, since a lost
7
- * offline queue is preferable to a crashing app.
8
- *
9
- * @since 0.5.0-canary.4
10
- */
11
- declare function createLocalStorageQueueStorage(storageKey: string): EventQueueStorage;
12
- //#endregion
13
- export { createLocalStorageQueueStorage };
@@ -1,31 +0,0 @@
1
- //#region src/client/local-storage.ts
2
- /**
3
- * `localStorage`-backed queue storage — corrupt/missing state, a private-mode/quota
4
- * error, or no `window` (SSR) are all treated as empty rather than thrown, since a lost
5
- * offline queue is preferable to a crashing app.
6
- *
7
- * @since 0.5.0-canary.4
8
- */
9
- function createLocalStorageQueueStorage(storageKey) {
10
- return {
11
- load() {
12
- if (typeof globalThis.window === "undefined") return [];
13
- try {
14
- const raw = globalThis.window.localStorage.getItem(storageKey);
15
- if (!raw) return [];
16
- const parsed = JSON.parse(raw);
17
- return Array.isArray(parsed) ? parsed : [];
18
- } catch {
19
- return [];
20
- }
21
- },
22
- save(events) {
23
- if (typeof globalThis.window === "undefined") return;
24
- try {
25
- globalThis.window.localStorage.setItem(storageKey, JSON.stringify(events));
26
- } catch {}
27
- }
28
- };
29
- }
30
- //#endregion
31
- export { createLocalStorageQueueStorage };
@@ -1,49 +0,0 @@
1
- import { TrackedEvent } from "../core/tracked-event.mjs";
2
- import { Destination } from "../core/destination.mjs";
3
-
4
- //#region src/client/queue.d.ts
5
- /**
6
- * Persistence backend for the offline queue — a thin wrapper so tests and non-browser
7
- * environments can swap in an in-memory implementation instead of real `localStorage`.
8
- *
9
- * @since 0.5.0-canary.4
10
- */
11
- interface EventQueueStorage {
12
- load: () => Array<TrackedEvent>;
13
- save: (events: Array<TrackedEvent>) => void;
14
- }
15
- /**
16
- * @since 0.5.0-canary.4
17
- */
18
- interface EventQueueOptions {
19
- destinations: Array<Destination>;
20
- flushBatchSize?: number | undefined;
21
- maxQueueSize?: number | undefined;
22
- maxRetries?: number | undefined;
23
- storage: EventQueueStorage;
24
- }
25
- /**
26
- * Client-side batching/offline queue: persists across reloads, caps its size
27
- * (drop-oldest), and retries a failed batch up to `maxRetries` times.
28
- *
29
- * @since 0.5.0-canary.4
30
- */
31
- declare class EventQueue {
32
- private readonly destinations;
33
- private readonly flushBatchSize;
34
- private readonly maxQueueSize;
35
- private readonly maxRetries;
36
- private pending;
37
- private readonly storage;
38
- constructor(options: EventQueueOptions);
39
- get size(): number;
40
- /** Drops every pending event without sending it — used on consent revoke. */
41
- clear(): void;
42
- /** Empties the queue synchronously for `navigator.sendBeacon`, which can't be awaited. */
43
- drain(): Array<TrackedEvent>;
44
- enqueue(event: TrackedEvent): void;
45
- flush(): Promise<void>;
46
- private persist;
47
- }
48
- //#endregion
49
- export { EventQueue, EventQueueOptions, EventQueueStorage };