@codefast/tracking 0.5.0-canary.5 → 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 (133) hide show
  1. package/CHANGELOG.md +165 -0
  2. package/README.md +122 -127
  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 +24 -7
  54. package/dist/react/consent-banner.mjs +16 -11
  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 +4 -1
  58. package/dist/react/index.mjs +4 -1
  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 +26 -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/destinations/google-analytics.ts +196 -133
  96. package/src/destinations/google-consent.ts +164 -0
  97. package/src/destinations/index.ts +14 -15
  98. package/src/destinations/shared.ts +45 -0
  99. package/src/destinations/vercel-analytics.ts +23 -24
  100. package/src/import-protection.ts +20 -0
  101. package/src/index.ts +46 -8
  102. package/src/react/consent-banner.tsx +40 -14
  103. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  104. package/src/react/index.ts +8 -0
  105. package/src/react/use-consent.ts +53 -45
  106. package/src/react/use-google-consent-sync.ts +38 -0
  107. package/src/react/use-initial-consent.ts +22 -0
  108. package/src/server/anonymous-id-cookie.ts +76 -0
  109. package/src/server/index.ts +15 -3
  110. package/src/server/initial-consent.ts +48 -0
  111. package/src/server/region.ts +22 -5
  112. package/src/tanstack-start/index.ts +83 -0
  113. package/dist/client/lifecycle.d.mts +0 -23
  114. package/dist/client/lifecycle.mjs +0 -30
  115. package/dist/client/local-storage.d.mts +0 -13
  116. package/dist/client/local-storage.mjs +0 -31
  117. package/dist/client/queue.d.mts +0 -49
  118. package/dist/client/queue.mjs +0 -71
  119. package/dist/client/router.d.mts +0 -30
  120. package/dist/client/router.mjs +0 -17
  121. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  122. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  123. package/dist/destinations/http-destination.d.mts +0 -20
  124. package/dist/destinations/http-destination.mjs +0 -25
  125. package/dist/server/create-server-tracker.d.mts +0 -42
  126. package/dist/server/create-server-tracker.mjs +0 -67
  127. package/src/client/lifecycle.ts +0 -50
  128. package/src/client/local-storage.ts +0 -44
  129. package/src/client/queue.ts +0 -117
  130. package/src/client/router.ts +0 -37
  131. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  132. package/src/destinations/http-destination.ts +0 -33
  133. package/src/server/create-server-tracker.ts +0 -128
@@ -0,0 +1,51 @@
1
+ import { ONE_YEAR_IN_SECONDS } from "../core/cookie.mjs";
2
+ //#region src/server/anonymous-id-cookie.ts
3
+ const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
4
+ const COOKIE_NAME_PATTERN = /^[\w-]+$/;
5
+ function assertCookieName(cookieName) {
6
+ if (!COOKIE_NAME_PATTERN.test(cookieName)) throw new Error(`Invalid anonymous-id cookie name: ${JSON.stringify(cookieName)}`);
7
+ }
8
+ /**
9
+ * Whether a value is safe to persist as an anonymous id. The persist endpoint is public
10
+ * and echoes its input into a response header, so only an exactly-UUID-shaped value may
11
+ * pass — anything else is a header-injection attempt or corruption, never a valid id.
12
+ *
13
+ * @since 1.0.0-canary.6
14
+ */
15
+ function isValidAnonymousId(value) {
16
+ return UUID_PATTERN.test(value);
17
+ }
18
+ /**
19
+ * `Set-Cookie` header value that persists (or prolongs) a client-minted anonymous id from
20
+ * the server. A server-set cookie escapes Safari ITP's 7-day cap on `document.cookie`
21
+ * writes, so the id actually lives its full max-age. The server only ever re-sets an id
22
+ * the client hands it — minting stays client-side, after consent, by design.
23
+ *
24
+ * @remarks
25
+ * Always `Secure` — on a plain-HTTP dev origin a browser may drop it, and the
26
+ * client-written cookie (`createServerPersistedAnonymousId`'s optimistic write) still
27
+ * covers that session. Not `HttpOnly`: the client tracker must read the id to stamp it
28
+ * onto events.
29
+ *
30
+ * @throws Error when `id` is not UUID-shaped or `cookieName` is not a valid token.
31
+ *
32
+ * @since 1.0.0-canary.6
33
+ */
34
+ function buildAnonymousIdSetCookie(options) {
35
+ const { cookieName, id, maxAgeSeconds = ONE_YEAR_IN_SECONDS } = options;
36
+ assertCookieName(cookieName);
37
+ if (!isValidAnonymousId(id)) throw new Error("Invalid anonymous id: expected a UUID-shaped value");
38
+ return `${cookieName}=${id}; Path=/; Max-Age=${String(maxAgeSeconds)}; SameSite=Lax; Secure`;
39
+ }
40
+ /**
41
+ * `Set-Cookie` header value that expires the anonymous-id cookie — the server half of a
42
+ * consent withdrawal, alongside the client's own `document.cookie` expiry.
43
+ *
44
+ * @since 1.0.0-canary.6
45
+ */
46
+ function buildClearAnonymousIdSetCookie(cookieName) {
47
+ assertCookieName(cookieName);
48
+ return `${cookieName}=; Path=/; Max-Age=0; SameSite=Lax; Secure`;
49
+ }
50
+ //#endregion
51
+ export { buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie, isValidAnonymousId };
@@ -1,3 +1,5 @@
1
- import { ServerTrackContext, ServerTracker, ServerTrackerOptions, createServerTracker } from "./create-server-tracker.mjs";
2
- import { resolveRegion, resolveRegionFromCountryCode } from "./region.mjs";
3
- export { type ServerTrackContext, type ServerTracker, type ServerTrackerOptions, createServerTracker, resolveRegion, resolveRegionFromCountryCode };
1
+ import { InitialConsent } from "../core/consent.mjs";
2
+ import { AnonymousIdSetCookieOptions, buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie, isValidAnonymousId } from "./anonymous-id-cookie.mjs";
3
+ import { InitialConsentOptions, resolveInitialConsent } from "./initial-consent.mjs";
4
+ import { EU_COUNTRY_CODES, OPT_IN_EQUIVALENT_COUNTRY_CODES, resolveRegion, resolveRegionFromCountryCode } from "./region.mjs";
5
+ export { type AnonymousIdSetCookieOptions, EU_COUNTRY_CODES, type InitialConsent, type InitialConsentOptions, OPT_IN_EQUIVALENT_COUNTRY_CODES, buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie, isValidAnonymousId, resolveInitialConsent, resolveRegion, resolveRegionFromCountryCode };
@@ -1,3 +1,4 @@
1
- import { createServerTracker } from "./create-server-tracker.mjs";
2
- import { resolveRegion, resolveRegionFromCountryCode } from "./region.mjs";
3
- export { createServerTracker, resolveRegion, resolveRegionFromCountryCode };
1
+ import { buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie, isValidAnonymousId } from "./anonymous-id-cookie.mjs";
2
+ import { EU_COUNTRY_CODES, OPT_IN_EQUIVALENT_COUNTRY_CODES, resolveRegion, resolveRegionFromCountryCode } from "./region.mjs";
3
+ import { resolveInitialConsent } from "./initial-consent.mjs";
4
+ export { EU_COUNTRY_CODES, OPT_IN_EQUIVALENT_COUNTRY_CODES, buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie, isValidAnonymousId, resolveInitialConsent, resolveRegion, resolveRegionFromCountryCode };
@@ -0,0 +1,29 @@
1
+ import { ConsentCategory, InitialConsent } from "../core/consent.mjs";
2
+
3
+ //#region src/server/initial-consent.d.ts
4
+ /**
5
+ * @since 1.0.0-canary.6
6
+ */
7
+ interface InitialConsentOptions {
8
+ /** ISO 3166-1 alpha-2 from the geo header; missing → the strictest opt-in default. */
9
+ countryCode: string | undefined;
10
+ /** Honored as an ads-only opt-out on the default decision. */
11
+ hasGlobalPrivacyControlSignal?: boolean | undefined;
12
+ /** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
13
+ requestedCategories: ReadonlyArray<ConsentCategory>;
14
+ }
15
+ /**
16
+ * Pure region → mode → default-consent resolution for server functions (or a fail-closed
17
+ * bake when country is unknown). Named with the `resolve*` family it composes.
18
+ *
19
+ * @remarks
20
+ * A missing country code means an unknown visitor (a prerender crawl, a host without a
21
+ * geo header) — not a known non-EU visitor — so it fails closed to
22
+ * {@link STRICTEST_INITIAL_CONSENT} instead of `"other"`'s opt-out. Conflating the two
23
+ * would grant analytics by default to every visitor, EU included, on a geo-less host.
24
+ *
25
+ * @since 1.0.0-canary.6
26
+ */
27
+ declare function resolveInitialConsent(options: InitialConsentOptions): InitialConsent;
28
+ //#endregion
29
+ export { type InitialConsent, InitialConsentOptions, resolveInitialConsent };
@@ -0,0 +1,31 @@
1
+ import { STRICTEST_INITIAL_CONSENT, resolveConsentMode, resolveDefaultConsent } from "../core/consent.mjs";
2
+ import { resolveRegionFromCountryCode } from "./region.mjs";
3
+ //#region src/server/initial-consent.ts
4
+ /**
5
+ * Pure region → mode → default-consent resolution for server functions (or a fail-closed
6
+ * bake when country is unknown). Named with the `resolve*` family it composes.
7
+ *
8
+ * @remarks
9
+ * A missing country code means an unknown visitor (a prerender crawl, a host without a
10
+ * geo header) — not a known non-EU visitor — so it fails closed to
11
+ * {@link STRICTEST_INITIAL_CONSENT} instead of `"other"`'s opt-out. Conflating the two
12
+ * would grant analytics by default to every visitor, EU included, on a geo-less host.
13
+ *
14
+ * @since 1.0.0-canary.6
15
+ */
16
+ function resolveInitialConsent(options) {
17
+ if (!options.countryCode) return STRICTEST_INITIAL_CONSENT;
18
+ const region = resolveRegionFromCountryCode(options.countryCode);
19
+ const mode = resolveConsentMode(region);
20
+ return {
21
+ defaultConsent: resolveDefaultConsent({
22
+ hasGlobalPrivacyControlSignal: options.hasGlobalPrivacyControlSignal ?? false,
23
+ mode,
24
+ requestedCategories: options.requestedCategories
25
+ }),
26
+ mode,
27
+ region
28
+ };
29
+ }
30
+ //#endregion
31
+ export { resolveInitialConsent };
@@ -2,9 +2,26 @@ import { ConsentRegion } from "../core/consent.mjs";
2
2
 
3
3
  //#region src/server/region.d.ts
4
4
  /**
5
- * Missing/unrecognized codes fall back to "other", which `resolveConsentMode` treats
6
- * as opt-out — the least restrictive default, safe only because opt-in regions (EU/VN)
7
- * are matched explicitly above it.
5
+ * EU member states — GDPR opt-in via `resolveConsentMode("eu")`.
6
+ *
7
+ * @since 1.0.0-canary.6
8
+ */
9
+ declare const EU_COUNTRY_CODES: ReadonlySet<string>;
10
+ /**
11
+ * UK GDPR (post-Brexit) and EEA/EFTA states that apply GDPR-equivalent rules — mapped to
12
+ * the same `"eu"` consent region so they get opt-in, not the `"other"` opt-out default.
13
+ *
14
+ * Restricted edge runtimes that cannot import this package should duplicate these codes
15
+ * and keep a sync test against this export.
16
+ *
17
+ * @since 1.0.0-canary.6
18
+ */
19
+ declare const OPT_IN_EQUIVALENT_COUNTRY_CODES: ReadonlySet<string>;
20
+ /**
21
+ * Unrecognized codes fall back to "other", which `resolveConsentMode` treats as
22
+ * opt-out — safe only because opt-in regions (EU/VN plus UK/EEA/EFTA above) are matched
23
+ * explicitly. A *missing* code also maps to "other" here, but `resolveInitialConsent`
24
+ * intercepts that case first and fails closed — unknown is not known-elsewhere.
8
25
  *
9
26
  * @since 0.5.0-canary.4
10
27
  */
@@ -17,4 +34,4 @@ declare function resolveRegionFromCountryCode(countryCode: string | undefined):
17
34
  */
18
35
  declare function resolveRegion(headers: Headers, headerName?: string): ConsentRegion;
19
36
  //#endregion
20
- export { resolveRegion, resolveRegionFromCountryCode };
37
+ export { EU_COUNTRY_CODES, OPT_IN_EQUIVALENT_COUNTRY_CODES, resolveRegion, resolveRegionFromCountryCode };
@@ -1,4 +1,9 @@
1
1
  //#region src/server/region.ts
2
+ /**
3
+ * EU member states — GDPR opt-in via `resolveConsentMode("eu")`.
4
+ *
5
+ * @since 1.0.0-canary.6
6
+ */
2
7
  const EU_COUNTRY_CODES = /* @__PURE__ */ new Set([
3
8
  "AT",
4
9
  "BE",
@@ -29,16 +34,32 @@ const EU_COUNTRY_CODES = /* @__PURE__ */ new Set([
29
34
  "SE"
30
35
  ]);
31
36
  /**
32
- * Missing/unrecognized codes fall back to "other", which `resolveConsentMode` treats
33
- * as opt-out — the least restrictive default, safe only because opt-in regions (EU/VN)
34
- * are matched explicitly above it.
37
+ * UK GDPR (post-Brexit) and EEA/EFTA states that apply GDPR-equivalent rules — mapped to
38
+ * the same `"eu"` consent region so they get opt-in, not the `"other"` opt-out default.
39
+ *
40
+ * Restricted edge runtimes that cannot import this package should duplicate these codes
41
+ * and keep a sync test against this export.
42
+ *
43
+ * @since 1.0.0-canary.6
44
+ */
45
+ const OPT_IN_EQUIVALENT_COUNTRY_CODES = /* @__PURE__ */ new Set([
46
+ "GB",
47
+ "IS",
48
+ "LI",
49
+ "NO"
50
+ ]);
51
+ /**
52
+ * Unrecognized codes fall back to "other", which `resolveConsentMode` treats as
53
+ * opt-out — safe only because opt-in regions (EU/VN plus UK/EEA/EFTA above) are matched
54
+ * explicitly. A *missing* code also maps to "other" here, but `resolveInitialConsent`
55
+ * intercepts that case first and fails closed — unknown is not known-elsewhere.
35
56
  *
36
57
  * @since 0.5.0-canary.4
37
58
  */
38
59
  function resolveRegionFromCountryCode(countryCode) {
39
60
  if (!countryCode) return "other";
40
61
  const normalized = countryCode.toUpperCase();
41
- if (EU_COUNTRY_CODES.has(normalized)) return "eu";
62
+ if (EU_COUNTRY_CODES.has(normalized) || OPT_IN_EQUIVALENT_COUNTRY_CODES.has(normalized)) return "eu";
42
63
  if (normalized === "VN") return "vn";
43
64
  if (normalized === "US") return "us";
44
65
  return "other";
@@ -53,4 +74,4 @@ function resolveRegion(headers, headerName = "x-vercel-ip-country") {
53
74
  return resolveRegionFromCountryCode(headers.get(headerName) ?? void 0);
54
75
  }
55
76
  //#endregion
56
- export { resolveRegion, resolveRegionFromCountryCode };
77
+ export { EU_COUNTRY_CODES, OPT_IN_EQUIVALENT_COUNTRY_CODES, resolveRegion, resolveRegionFromCountryCode };
@@ -0,0 +1,58 @@
1
+ import { ConsentCategory, InitialConsent } from "../core/consent.mjs";
2
+
3
+ //#region src/tanstack-start/index.d.ts
4
+ /**
5
+ * Request/response glue for TanStack Start — each helper reads or writes the framework's
6
+ * ambient request context (AsyncLocalStorage), so a consumer's server functions shrink to
7
+ * one-line handlers around them. Server-only: deny this subpath in the client environment
8
+ * via Start's `importProtection` — the compiler already strips it with stubbed handler bodies.
9
+ *
10
+ * @since 1.0.0-canary.6
11
+ */
12
+ interface InitialConsentFromRequestOptions {
13
+ /**
14
+ * Header carrying the ISO 3166-1 alpha-2 country code.
15
+ *
16
+ * @defaultValue "x-vercel-ip-country"
17
+ */
18
+ countryHeaderName?: string | undefined;
19
+ /** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
20
+ requestedCategories: ReadonlyArray<ConsentCategory>;
21
+ }
22
+ /**
23
+ * Region-correct `InitialConsent` for the current request: reads the platform geo header
24
+ * and `sec-gpc`, fails closed when geo is missing, and stamps
25
+ * `cache-control: private, no-store` — the value is per-visitor by definition, so no
26
+ * shared cache may ever store the response carrying it.
27
+ *
28
+ * @since 1.0.0-canary.6
29
+ */
30
+ declare function resolveInitialConsentFromRequest(options: InitialConsentFromRequestOptions): InitialConsent;
31
+ /**
32
+ * @since 1.0.0-canary.6
33
+ */
34
+ interface AnonymousIdResponseCookieOptions {
35
+ /** Cookie name — must match what the client tracker reads. */
36
+ cookieName: string;
37
+ /** The client-minted id to persist — throws unless it is exactly UUID-shaped. */
38
+ id: string;
39
+ /** How long the id survives a return visit. Defaults to one year. */
40
+ maxAgeSeconds?: number | undefined;
41
+ }
42
+ /**
43
+ * Persists (or prolongs) a client-minted anonymous id via `Set-Cookie` on the current
44
+ * response — the server re-issue that escapes Safari ITP's 7-day cap on script-written
45
+ * cookies. Validation lives in `buildAnonymousIdSetCookie`: a non-UUID id throws, so this
46
+ * can safely back a public server function without echoing attacker input into a header.
47
+ *
48
+ * @since 1.0.0-canary.6
49
+ */
50
+ declare function setAnonymousIdResponseCookie(options: AnonymousIdResponseCookieOptions): void;
51
+ /**
52
+ * Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
53
+ *
54
+ * @since 1.0.0-canary.6
55
+ */
56
+ declare function clearAnonymousIdResponseCookie(cookieName: string): void;
57
+ //#endregion
58
+ export { AnonymousIdResponseCookieOptions, InitialConsentFromRequestOptions, clearAnonymousIdResponseCookie, resolveInitialConsentFromRequest, setAnonymousIdResponseCookie };
@@ -0,0 +1,45 @@
1
+ import { buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie } from "../server/anonymous-id-cookie.mjs";
2
+ import { resolveInitialConsent } from "../server/initial-consent.mjs";
3
+ import { getRequestHeader, setResponseHeader } from "@tanstack/react-start/server";
4
+ //#region src/tanstack-start/index.ts
5
+ /**
6
+ * Region-correct `InitialConsent` for the current request: reads the platform geo header
7
+ * and `sec-gpc`, fails closed when geo is missing, and stamps
8
+ * `cache-control: private, no-store` — the value is per-visitor by definition, so no
9
+ * shared cache may ever store the response carrying it.
10
+ *
11
+ * @since 1.0.0-canary.6
12
+ */
13
+ function resolveInitialConsentFromRequest(options) {
14
+ setResponseHeader("cache-control", "private, no-store");
15
+ return resolveInitialConsent({
16
+ countryCode: getRequestHeader(options.countryHeaderName ?? "x-vercel-ip-country"),
17
+ hasGlobalPrivacyControlSignal: getRequestHeader("sec-gpc") === "1",
18
+ requestedCategories: options.requestedCategories
19
+ });
20
+ }
21
+ /**
22
+ * Persists (or prolongs) a client-minted anonymous id via `Set-Cookie` on the current
23
+ * response — the server re-issue that escapes Safari ITP's 7-day cap on script-written
24
+ * cookies. Validation lives in `buildAnonymousIdSetCookie`: a non-UUID id throws, so this
25
+ * can safely back a public server function without echoing attacker input into a header.
26
+ *
27
+ * @since 1.0.0-canary.6
28
+ */
29
+ function setAnonymousIdResponseCookie(options) {
30
+ setResponseHeader("set-cookie", buildAnonymousIdSetCookie({
31
+ cookieName: options.cookieName,
32
+ id: options.id,
33
+ maxAgeSeconds: options.maxAgeSeconds
34
+ }));
35
+ }
36
+ /**
37
+ * Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
38
+ *
39
+ * @since 1.0.0-canary.6
40
+ */
41
+ function clearAnonymousIdResponseCookie(cookieName) {
42
+ setResponseHeader("set-cookie", buildClearAnonymousIdSetCookie(cookieName));
43
+ }
44
+ //#endregion
45
+ export { clearAnonymousIdResponseCookie, resolveInitialConsentFromRequest, setAnonymousIdResponseCookie };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codefast/tracking",
3
- "version": "0.5.0-canary.5",
3
+ "version": "1.0.0-canary.6",
4
4
  "description": "Fullstack, type-safe event tracking for TanStack Start — isomorphic client/server trackers over a per-app Zod event catalog",
5
5
  "keywords": [
6
6
  "analytics",
@@ -56,131 +56,41 @@
56
56
  "types": "./dist/index.d.mts",
57
57
  "import": "./dist/index.mjs"
58
58
  },
59
+ "./import-protection": {
60
+ "source": "./src/import-protection.ts",
61
+ "types": "./dist/import-protection.d.mts",
62
+ "import": "./dist/import-protection.mjs"
63
+ },
59
64
  "./client": {
60
65
  "source": "./src/client/index.ts",
61
66
  "types": "./dist/client/index.d.mts",
62
67
  "import": "./dist/client/index.mjs"
63
68
  },
64
- "./client/consent-storage": {
65
- "source": "./src/client/consent-storage.ts",
66
- "types": "./dist/client/consent-storage.d.mts",
67
- "import": "./dist/client/consent-storage.mjs"
68
- },
69
- "./client/create-client-tracker": {
70
- "source": "./src/client/create-client-tracker.ts",
71
- "types": "./dist/client/create-client-tracker.d.mts",
72
- "import": "./dist/client/create-client-tracker.mjs"
73
- },
74
- "./client/gpc": {
75
- "source": "./src/client/gpc.ts",
76
- "types": "./dist/client/gpc.d.mts",
77
- "import": "./dist/client/gpc.mjs"
78
- },
79
- "./client/lifecycle": {
80
- "source": "./src/client/lifecycle.ts",
81
- "types": "./dist/client/lifecycle.d.mts",
82
- "import": "./dist/client/lifecycle.mjs"
83
- },
84
- "./client/local-storage": {
85
- "source": "./src/client/local-storage.ts",
86
- "types": "./dist/client/local-storage.d.mts",
87
- "import": "./dist/client/local-storage.mjs"
88
- },
89
- "./client/queue": {
90
- "source": "./src/client/queue.ts",
91
- "types": "./dist/client/queue.d.mts",
92
- "import": "./dist/client/queue.mjs"
93
- },
94
- "./client/router": {
95
- "source": "./src/client/router.ts",
96
- "types": "./dist/client/router.d.mts",
97
- "import": "./dist/client/router.mjs"
98
- },
99
- "./core": {
100
- "source": "./src/core/index.ts",
101
- "types": "./dist/core/index.d.mts",
102
- "import": "./dist/core/index.mjs"
103
- },
104
- "./core/consent": {
105
- "source": "./src/core/consent.ts",
106
- "types": "./dist/core/consent.d.mts",
107
- "import": "./dist/core/consent.mjs"
108
- },
109
- "./core/destination": {
110
- "source": "./src/core/destination.ts",
111
- "types": "./dist/core/destination.d.mts",
112
- "import": "./dist/core/destination.mjs"
113
- },
114
- "./core/event-catalog": {
115
- "source": "./src/core/event-catalog.ts",
116
- "types": "./dist/core/event-catalog.d.mts",
117
- "import": "./dist/core/event-catalog.mjs"
69
+ "./server": {
70
+ "source": "./src/server/index.ts",
71
+ "types": "./dist/server/index.d.mts",
72
+ "import": "./dist/server/index.mjs"
118
73
  },
119
- "./core/event-id": {
120
- "source": "./src/core/event-id.ts",
121
- "types": "./dist/core/event-id.d.mts",
122
- "import": "./dist/core/event-id.mjs"
74
+ "./react": {
75
+ "source": "./src/react/index.ts",
76
+ "types": "./dist/react/index.d.mts",
77
+ "import": "./dist/react/index.mjs"
123
78
  },
124
- "./core/tracked-event": {
125
- "source": "./src/core/tracked-event.ts",
126
- "types": "./dist/core/tracked-event.d.mts",
127
- "import": "./dist/core/tracked-event.mjs"
79
+ "./tanstack-start": {
80
+ "source": "./src/tanstack-start/index.ts",
81
+ "types": "./dist/tanstack-start/index.d.mts",
82
+ "import": "./dist/tanstack-start/index.mjs"
128
83
  },
129
84
  "./destinations": {
130
85
  "source": "./src/destinations/index.ts",
131
86
  "types": "./dist/destinations/index.d.mts",
132
87
  "import": "./dist/destinations/index.mjs"
133
88
  },
134
- "./destinations/ga4-measurement-protocol": {
135
- "source": "./src/destinations/ga4-measurement-protocol.ts",
136
- "types": "./dist/destinations/ga4-measurement-protocol.d.mts",
137
- "import": "./dist/destinations/ga4-measurement-protocol.mjs"
138
- },
139
- "./destinations/google-analytics": {
140
- "source": "./src/destinations/google-analytics.ts",
141
- "types": "./dist/destinations/google-analytics.d.mts",
142
- "import": "./dist/destinations/google-analytics.mjs"
143
- },
144
- "./destinations/http-destination": {
145
- "source": "./src/destinations/http-destination.ts",
146
- "types": "./dist/destinations/http-destination.d.mts",
147
- "import": "./dist/destinations/http-destination.mjs"
148
- },
149
89
  "./destinations/vercel-analytics": {
150
90
  "source": "./src/destinations/vercel-analytics.ts",
151
91
  "types": "./dist/destinations/vercel-analytics.d.mts",
152
92
  "import": "./dist/destinations/vercel-analytics.mjs"
153
93
  },
154
- "./react": {
155
- "source": "./src/react/index.ts",
156
- "types": "./dist/react/index.d.mts",
157
- "import": "./dist/react/index.mjs"
158
- },
159
- "./react/consent-banner": {
160
- "source": "./src/react/consent-banner.tsx",
161
- "types": "./dist/react/consent-banner.d.mts",
162
- "import": "./dist/react/consent-banner.mjs"
163
- },
164
- "./react/use-consent": {
165
- "source": "./src/react/use-consent.ts",
166
- "types": "./dist/react/use-consent.d.mts",
167
- "import": "./dist/react/use-consent.mjs"
168
- },
169
- "./server": {
170
- "source": "./src/server/index.ts",
171
- "types": "./dist/server/index.d.mts",
172
- "import": "./dist/server/index.mjs"
173
- },
174
- "./server/create-server-tracker": {
175
- "source": "./src/server/create-server-tracker.ts",
176
- "types": "./dist/server/create-server-tracker.d.mts",
177
- "import": "./dist/server/create-server-tracker.mjs"
178
- },
179
- "./server/region": {
180
- "source": "./src/server/region.ts",
181
- "types": "./dist/server/region.d.mts",
182
- "import": "./dist/server/region.mjs"
183
- },
184
94
  "./css/*": "./src/css/*",
185
95
  "./package.json": "./package.json"
186
96
  },
@@ -188,9 +98,10 @@
188
98
  "access": "public"
189
99
  },
190
100
  "dependencies": {
191
- "zod": "^4.4.3"
101
+ "@standard-schema/spec": "^1.1.0"
192
102
  },
193
103
  "devDependencies": {
104
+ "@tanstack/react-start": "^1.168.27",
194
105
  "@testing-library/dom": "^10.4.1",
195
106
  "@testing-library/jest-dom": "^6.9.1",
196
107
  "@testing-library/react": "^16.3.2",
@@ -209,9 +120,11 @@
209
120
  "tsdown": "^0.22.3",
210
121
  "typescript": "^6.0.3",
211
122
  "vitest": "^4.1.9",
212
- "@codefast/typescript-config": "0.5.0-canary.5"
123
+ "zod": "^4.4.3",
124
+ "@codefast/typescript-config": "1.0.0-canary.6"
213
125
  },
214
126
  "peerDependencies": {
127
+ "@tanstack/react-start": ">=1.168.0",
215
128
  "@types/react": ">=19.0.0",
216
129
  "@types/react-dom": ">=19.0.0",
217
130
  "@vercel/analytics": ">=1.0.0",
@@ -219,6 +132,9 @@
219
132
  "react-dom": ">=19.0.0"
220
133
  },
221
134
  "peerDependenciesMeta": {
135
+ "@tanstack/react-start": {
136
+ "optional": true
137
+ },
222
138
  "@types/react": {
223
139
  "optional": true
224
140
  },
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Shared `document.cookie` writer for the client-side cookie lanes (anonymous id, consent
3
+ * mirror): Secure on HTTPS so values never ride plain HTTP, SameSite=Lax, never HttpOnly —
4
+ * the client must read its own cookies back. A no-op without a `document` (SSR).
5
+ *
6
+ * @since 1.0.0-canary.6
7
+ */
8
+ export function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void {
9
+ if (typeof document === "undefined") {
10
+ return;
11
+ }
12
+
13
+ const secure = globalThis.location.protocol === "https:" ? "; secure" : "";
14
+
15
+ document.cookie = `${cookieName}=${value}; path=/; max-age=${String(maxAgeSeconds)}; samesite=lax${secure}`;
16
+ }
@@ -0,0 +1,80 @@
1
+ import { createLocalStorageConsentStorage } from "#/client/consent-storage";
2
+ import { hasGlobalPrivacyControlSignal } from "#/client/gpc";
3
+ import type { InitialConsentStore } from "#/client/initial-consent-store";
4
+ import { createInitialConsentStore } from "#/client/initial-consent-store";
5
+ import { createIsAnalyticsAllowed } from "#/client/is-analytics-allowed";
6
+ import type { ConsentStorage, InitialConsent } from "#/core/consent";
7
+ import type { ConsentConfig } from "#/core/consent-config";
8
+
9
+ /**
10
+ * @since 1.0.0-canary.6
11
+ */
12
+ export interface ConsentRuntimeOptions {
13
+ config: ConsentConfig;
14
+ /** Re-read per event so a GPC change applies without recreating the runtime. Defaults to the real navigator signal. */
15
+ hasGlobalPrivacyControlSignal?: (() => boolean) | undefined;
16
+ /**
17
+ * `sessionStorage` key caching the resolved region default, so only the first page
18
+ * load of a session pays the round trip — omit to resolve once per page load instead.
19
+ */
20
+ initialConsentSessionStorageKey?: string | undefined;
21
+ /**
22
+ * The per-visitor server lane — typically a server function wrapping
23
+ * `resolveInitialConsentFromRequest`. Shared/CDN-cached HTML can carry nothing
24
+ * region-specific, so this is the only place the region-correct default may come from.
25
+ */
26
+ resolveInitialConsent: () => Promise<InitialConsent>;
27
+ }
28
+
29
+ /**
30
+ * The live client-side consent instances, all derived from one `ConsentConfig` — create
31
+ * it once at module scope and every surface (banner hook, tracker gate, privacy page)
32
+ * shares the same storage and region resolution by construction.
33
+ *
34
+ * @since 1.0.0-canary.6
35
+ */
36
+ export interface ConsentRuntime {
37
+ config: ConsentConfig;
38
+ /**
39
+ * Kicks off region resolution — single-flight and idempotent. Call it early (e.g. at
40
+ * router creation, window-guarded) so the round trip overlaps hydration instead of
41
+ * waiting for the first mount effect.
42
+ */
43
+ ensureInitialConsentResolved: () => void;
44
+ /** Feed to `useInitialConsent` for the reactive region default. */
45
+ initialConsentStore: InitialConsentStore;
46
+ /** Non-React gate for `createClientTracker` — the same rule `useConsent` applies. */
47
+ isAnalyticsAllowed: () => boolean;
48
+ /** The one `ConsentStorage` instance every surface must share. */
49
+ storage: ConsentStorage;
50
+ }
51
+
52
+ /**
53
+ * Composes the client half of the consent lane from a single `ConsentConfig`:
54
+ * `localStorage`-backed decision storage, the initial-consent store over the app's
55
+ * server lane, and the non-React analytics gate wired to that store's resolved mode.
56
+ *
57
+ * @since 1.0.0-canary.6
58
+ */
59
+ export function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime {
60
+ const { config } = options;
61
+ const storage = createLocalStorageConsentStorage(config.storageKey);
62
+ const initialConsentStore = createInitialConsentStore({
63
+ resolve: options.resolveInitialConsent,
64
+ sessionStorageKey: options.initialConsentSessionStorageKey,
65
+ });
66
+ const isAnalyticsAllowed = createIsAnalyticsAllowed({
67
+ config,
68
+ getMode: () => initialConsentStore.getSnapshot().initialConsent.mode,
69
+ hasGlobalPrivacyControlSignal: options.hasGlobalPrivacyControlSignal ?? hasGlobalPrivacyControlSignal,
70
+ storage,
71
+ });
72
+
73
+ return {
74
+ config,
75
+ ensureInitialConsentResolved: initialConsentStore.ensureResolved,
76
+ initialConsentStore,
77
+ isAnalyticsAllowed,
78
+ storage,
79
+ };
80
+ }