@codefast/tracking 0.5.0-canary.5 → 0.5.0-canary.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +469 -0
- package/README.md +176 -126
- package/dist/adapters/tanstack-start.d.ts +80 -0
- package/dist/adapters/tanstack-start.d.ts.map +1 -0
- package/dist/adapters/tanstack-start.js +74 -0
- package/dist/adapters/tanstack-start.js.map +1 -0
- package/dist/client/ad-framework-consent.d.ts +62 -0
- package/dist/client/ad-framework-consent.d.ts.map +1 -0
- package/dist/client/ad-framework-consent.js +40 -0
- package/dist/client/ad-framework-consent.js.map +1 -0
- package/dist/client/browser-cookie.d.ts +9 -0
- package/dist/client/browser-cookie.d.ts.map +1 -0
- package/dist/client/browser-cookie.js +15 -0
- package/dist/client/browser-cookie.js.map +1 -0
- package/dist/client/consent-runtime.d.ts +53 -0
- package/dist/client/consent-runtime.d.ts.map +1 -0
- package/dist/client/consent-runtime.js +33 -0
- package/dist/client/consent-runtime.js.map +1 -0
- package/dist/client/{consent-storage.d.mts → consent-storage.d.ts} +8 -6
- package/dist/client/consent-storage.d.ts.map +1 -0
- package/dist/client/consent-storage.js +109 -0
- package/dist/client/consent-storage.js.map +1 -0
- package/dist/client/consent-withdrawal.d.ts +18 -0
- package/dist/client/consent-withdrawal.d.ts.map +1 -0
- package/dist/client/consent-withdrawal.js +17 -0
- package/dist/client/consent-withdrawal.js.map +1 -0
- package/dist/client/cookie-anonymous-id.d.ts +41 -0
- package/dist/client/cookie-anonymous-id.d.ts.map +1 -0
- package/dist/client/cookie-anonymous-id.js +65 -0
- package/dist/client/cookie-anonymous-id.js.map +1 -0
- package/dist/client/create-client-tracker.d.ts +60 -0
- package/dist/client/create-client-tracker.d.ts.map +1 -0
- package/dist/client/create-client-tracker.js +91 -0
- package/dist/client/create-client-tracker.js.map +1 -0
- package/dist/client/gpc.d.ts +10 -0
- package/dist/client/gpc.d.ts.map +1 -0
- package/dist/client/gpc.js +12 -0
- package/dist/client/gpc.js.map +1 -0
- package/dist/client/initial-consent-store.d.ts +63 -0
- package/dist/client/initial-consent-store.d.ts.map +1 -0
- package/dist/client/initial-consent-store.js +138 -0
- package/dist/client/initial-consent-store.js.map +1 -0
- package/dist/client/is-analytics-allowed.d.ts +26 -0
- package/dist/client/is-analytics-allowed.d.ts.map +1 -0
- package/dist/client/is-analytics-allowed.js +22 -0
- package/dist/client/is-analytics-allowed.js.map +1 -0
- package/dist/client/server-persisted-anonymous-id.d.ts +30 -0
- package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -0
- package/dist/client/server-persisted-anonymous-id.js +72 -0
- package/dist/client/server-persisted-anonymous-id.js.map +1 -0
- package/dist/core/consent-config.d.ts +24 -0
- package/dist/core/consent-config.d.ts.map +1 -0
- package/dist/core/consent-config.js +9 -0
- package/dist/core/consent-config.js.map +1 -0
- package/dist/core/consent-receipt.d.ts +71 -0
- package/dist/core/consent-receipt.d.ts.map +1 -0
- package/dist/core/consent-receipt.js +39 -0
- package/dist/core/consent-receipt.js.map +1 -0
- package/dist/core/consent.d.ts +182 -0
- package/dist/core/consent.d.ts.map +1 -0
- package/dist/core/consent.js +159 -0
- package/dist/core/consent.js.map +1 -0
- package/dist/core/cookie.d.ts +15 -0
- package/dist/core/cookie.d.ts.map +1 -0
- package/dist/core/cookie.js +26 -0
- package/dist/core/cookie.js.map +1 -0
- package/dist/core/destination.d.ts +29 -0
- package/dist/core/destination.d.ts.map +1 -0
- package/dist/core/destination.js +2 -0
- package/dist/core/destination.js.map +1 -0
- package/dist/core/event-catalog.d.ts +35 -0
- package/dist/core/event-catalog.d.ts.map +1 -0
- package/dist/core/event-catalog.js +30 -0
- package/dist/core/event-catalog.js.map +1 -0
- package/dist/core/event-id.d.ts +7 -0
- package/dist/core/event-id.d.ts.map +1 -0
- package/dist/core/event-id.js +9 -0
- package/dist/core/event-id.js.map +1 -0
- package/dist/core/tracked-event.d.ts +15 -0
- package/dist/core/tracked-event.d.ts.map +1 -0
- package/dist/core/tracked-event.js +2 -0
- package/dist/core/tracked-event.js.map +1 -0
- package/dist/destinations/ad-consent.d.ts +23 -0
- package/dist/destinations/ad-consent.d.ts.map +1 -0
- package/dist/destinations/ad-consent.js +12 -0
- package/dist/destinations/ad-consent.js.map +1 -0
- package/dist/destinations/google-analytics.d.ts +148 -0
- package/dist/destinations/google-analytics.d.ts.map +1 -0
- package/dist/destinations/google-analytics.js +156 -0
- package/dist/destinations/google-analytics.js.map +1 -0
- package/dist/destinations/google-consent.d.ts +62 -0
- package/dist/destinations/google-consent.d.ts.map +1 -0
- package/dist/destinations/google-consent.js +109 -0
- package/dist/destinations/google-consent.js.map +1 -0
- package/dist/destinations/meta.d.ts +63 -0
- package/dist/destinations/meta.d.ts.map +1 -0
- package/dist/destinations/meta.js +44 -0
- package/dist/destinations/meta.js.map +1 -0
- package/dist/destinations/microsoft-uet.d.ts +56 -0
- package/dist/destinations/microsoft-uet.d.ts.map +1 -0
- package/dist/destinations/microsoft-uet.js +41 -0
- package/dist/destinations/microsoft-uet.js.map +1 -0
- package/dist/destinations/shared.d.ts +18 -0
- package/dist/destinations/shared.d.ts.map +1 -0
- package/dist/destinations/shared.js +19 -0
- package/dist/destinations/shared.js.map +1 -0
- package/dist/destinations/tiktok.d.ts +55 -0
- package/dist/destinations/tiktok.d.ts.map +1 -0
- package/dist/destinations/tiktok.js +40 -0
- package/dist/destinations/tiktok.js.map +1 -0
- package/dist/destinations/vercel-analytics.d.ts +25 -0
- package/dist/destinations/vercel-analytics.d.ts.map +1 -0
- package/dist/destinations/vercel-analytics.js +23 -0
- package/dist/destinations/vercel-analytics.js.map +1 -0
- package/dist/index.d.ts +64 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -0
- package/dist/react/consent-banner.d.ts +155 -0
- package/dist/react/consent-banner.d.ts.map +1 -0
- package/dist/react/consent-banner.js +171 -0
- package/dist/react/consent-banner.js.map +1 -0
- package/dist/react/gtag-consent-bootstrap.d.ts +17 -0
- package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -0
- package/dist/react/gtag-consent-bootstrap.js +22 -0
- package/dist/react/gtag-consent-bootstrap.js.map +1 -0
- package/dist/react/use-consent.d.ts +42 -0
- package/dist/react/use-consent.d.ts.map +1 -0
- package/dist/react/use-consent.js +60 -0
- package/dist/react/use-consent.js.map +1 -0
- package/dist/react/use-google-consent-sync.d.ts +20 -0
- package/dist/react/use-google-consent-sync.d.ts.map +1 -0
- package/dist/react/use-google-consent-sync.js +22 -0
- package/dist/react/use-google-consent-sync.js.map +1 -0
- package/dist/react/use-initial-consent.d.ts +11 -0
- package/dist/react/use-initial-consent.d.ts.map +1 -0
- package/dist/react/use-initial-consent.js +18 -0
- package/dist/react/use-initial-consent.js.map +1 -0
- package/dist/server/anonymous-id-cookie.d.ts +67 -0
- package/dist/server/anonymous-id-cookie.d.ts.map +1 -0
- package/dist/server/anonymous-id-cookie.js +71 -0
- package/dist/server/anonymous-id-cookie.js.map +1 -0
- package/dist/server/consent-receipt-store.d.ts +56 -0
- package/dist/server/consent-receipt-store.d.ts.map +1 -0
- package/dist/server/consent-receipt-store.js +44 -0
- package/dist/server/consent-receipt-store.js.map +1 -0
- package/dist/server/consent-receipt.d.ts +41 -0
- package/dist/server/consent-receipt.d.ts.map +1 -0
- package/dist/server/consent-receipt.js +60 -0
- package/dist/server/consent-receipt.js.map +1 -0
- package/dist/server/initial-consent.d.ts +26 -0
- package/dist/server/initial-consent.d.ts.map +1 -0
- package/dist/server/initial-consent.js +31 -0
- package/dist/server/initial-consent.js.map +1 -0
- package/dist/server/measurement-protocol.d.ts +69 -0
- package/dist/server/measurement-protocol.d.ts.map +1 -0
- package/dist/server/measurement-protocol.js +61 -0
- package/dist/server/measurement-protocol.js.map +1 -0
- package/dist/server/region.d.ts +27 -0
- package/dist/server/region.d.ts.map +1 -0
- package/dist/server/region.js +69 -0
- package/dist/server/region.js.map +1 -0
- package/dist/server/user-deletion.d.ts +64 -0
- package/dist/server/user-deletion.d.ts.map +1 -0
- package/dist/server/user-deletion.js +54 -0
- package/dist/server/user-deletion.js.map +1 -0
- package/dist/tooling/import-protection.d.ts +19 -0
- package/dist/tooling/import-protection.d.ts.map +1 -0
- package/dist/tooling/import-protection.js +23 -0
- package/dist/tooling/import-protection.js.map +1 -0
- package/package.json +205 -111
- package/src/adapters/tanstack-start.ts +135 -0
- package/src/client/ad-framework-consent.ts +86 -0
- package/src/client/browser-cookie.ts +16 -0
- package/src/client/consent-runtime.ts +80 -0
- package/src/client/consent-storage.ts +31 -1
- package/src/client/consent-withdrawal.ts +32 -0
- package/src/client/cookie-anonymous-id.ts +112 -0
- package/src/client/create-client-tracker.ts +128 -86
- package/src/client/gpc.ts +4 -2
- package/src/client/initial-consent-store.ts +218 -0
- package/src/client/is-analytics-allowed.ts +43 -0
- package/src/client/server-persisted-anonymous-id.ts +102 -0
- package/src/core/consent-config.ts +27 -0
- package/src/core/consent-receipt.ts +115 -0
- package/src/core/consent.ts +164 -10
- package/src/core/cookie.ts +29 -0
- package/src/core/destination.ts +17 -8
- package/src/core/event-catalog.ts +29 -15
- package/src/core/event-id.ts +1 -2
- package/src/core/tracked-event.ts +4 -4
- package/src/destinations/ad-consent.ts +29 -0
- package/src/destinations/google-analytics.ts +196 -133
- package/src/destinations/google-consent.ts +164 -0
- package/src/destinations/meta.ts +96 -0
- package/src/destinations/microsoft-uet.ts +86 -0
- package/src/destinations/shared.ts +45 -0
- package/src/destinations/tiktok.ts +85 -0
- package/src/destinations/vercel-analytics.ts +23 -24
- package/src/index.ts +165 -8
- package/src/react/consent-banner.tsx +40 -14
- package/src/react/gtag-consent-bootstrap.tsx +48 -0
- package/src/react/use-consent.ts +53 -45
- package/src/react/use-google-consent-sync.ts +38 -0
- package/src/react/use-initial-consent.ts +22 -0
- package/src/server/anonymous-id-cookie.ts +103 -0
- package/src/server/consent-receipt-store.ts +79 -0
- package/src/server/consent-receipt.ts +89 -0
- package/src/server/initial-consent.ts +46 -0
- package/src/server/measurement-protocol.ts +114 -0
- package/src/server/region.ts +22 -15
- package/src/server/user-deletion.ts +93 -0
- package/src/tooling/import-protection.ts +22 -0
- package/dist/client/consent-storage.mjs +0 -63
- package/dist/client/create-client-tracker.d.mts +0 -37
- package/dist/client/create-client-tracker.mjs +0 -66
- package/dist/client/gpc.d.mts +0 -10
- package/dist/client/gpc.mjs +0 -12
- package/dist/client/index.d.mts +0 -8
- package/dist/client/index.mjs +0 -8
- package/dist/client/lifecycle.d.mts +0 -23
- package/dist/client/lifecycle.mjs +0 -30
- package/dist/client/local-storage.d.mts +0 -13
- package/dist/client/local-storage.mjs +0 -31
- package/dist/client/queue.d.mts +0 -49
- package/dist/client/queue.mjs +0 -71
- package/dist/client/router.d.mts +0 -30
- package/dist/client/router.mjs +0 -17
- package/dist/core/consent.d.mts +0 -89
- package/dist/core/consent.mjs +0 -57
- package/dist/core/destination.d.mts +0 -23
- package/dist/core/destination.mjs +0 -1
- package/dist/core/event-catalog.d.mts +0 -36
- package/dist/core/event-catalog.mjs +0 -12
- package/dist/core/event-id.d.mts +0 -10
- package/dist/core/event-id.mjs +0 -12
- package/dist/core/index.d.mts +0 -6
- package/dist/core/index.mjs +0 -4
- package/dist/core/tracked-event.d.mts +0 -17
- package/dist/core/tracked-event.mjs +0 -1
- package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
- package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
- package/dist/destinations/google-analytics.d.mts +0 -98
- package/dist/destinations/google-analytics.mjs +0 -126
- package/dist/destinations/http-destination.d.mts +0 -20
- package/dist/destinations/http-destination.mjs +0 -25
- package/dist/destinations/index.d.mts +0 -5
- package/dist/destinations/index.mjs +0 -5
- package/dist/destinations/vercel-analytics.d.mts +0 -13
- package/dist/destinations/vercel-analytics.mjs +0 -30
- package/dist/index.d.mts +0 -6
- package/dist/index.mjs +0 -4
- package/dist/react/consent-banner.d.mts +0 -163
- package/dist/react/consent-banner.mjs +0 -209
- package/dist/react/index.d.mts +0 -3
- package/dist/react/index.mjs +0 -3
- package/dist/react/use-consent.d.mts +0 -49
- package/dist/react/use-consent.mjs +0 -54
- package/dist/server/create-server-tracker.d.mts +0 -42
- package/dist/server/create-server-tracker.mjs +0 -67
- package/dist/server/index.d.mts +0 -3
- package/dist/server/index.mjs +0 -3
- package/dist/server/region.d.mts +0 -20
- package/dist/server/region.mjs +0 -56
- package/src/client/index.ts +0 -17
- package/src/client/lifecycle.ts +0 -50
- package/src/client/local-storage.ts +0 -44
- package/src/client/queue.ts +0 -117
- package/src/client/router.ts +0 -37
- package/src/core/index.ts +0 -24
- package/src/destinations/ga4-measurement-protocol.ts +0 -166
- package/src/destinations/http-destination.ts +0 -33
- package/src/destinations/index.ts +0 -20
- package/src/react/index.ts +0 -29
- package/src/server/create-server-tracker.ts +0 -128
- package/src/server/index.ts +0 -4
package/README.md
CHANGED
|
@@ -1,160 +1,210 @@
|
|
|
1
1
|
# @codefast/tracking
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
event catalog tagged with an owner (`"client"` or `"server"`); trackers built from that
|
|
5
|
-
catalog only allow firing events owned by that side — enforced at compile time.
|
|
3
|
+
Consent-gated, type-safe event tracking for TanStack Start apps.
|
|
6
4
|
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@codefast/tracking)
|
|
6
|
+
[](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
- **One catalog, typed end to end** — apps define their events over any
|
|
9
|
+
[Standard Schema](https://standardschema.dev) library (zod, `zod/mini`, valibot, ...);
|
|
10
|
+
`track()` validates properties at the call site and at runtime, and the client bundle
|
|
11
|
+
only pays for the schema library the app already ships.
|
|
12
|
+
- **One consent config, every surface** — `ConsentConfig` is the single bag for the
|
|
13
|
+
storage key, policy version, and requested purposes; the React hooks, the tracker gate,
|
|
14
|
+
and the pre-hydration gtag bootstrap all take the same object, so nothing drifts.
|
|
15
|
+
- **ISR-safe by design** — shared/CDN-cached HTML bakes the strictest consent default;
|
|
16
|
+
the region-correct default arrives per visitor over a private server-function lane.
|
|
9
17
|
|
|
10
18
|
## Status
|
|
11
19
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
20
|
+
Pre-1.0 (canary). The surface is deliberately small: it covers exactly what a consented
|
|
21
|
+
gtag + Vercel Analytics setup on TanStack Start needs, and nothing speculative. Lanes
|
|
22
|
+
that shipped here before (offline queue, beacon relay, server-side tracker, GTM,
|
|
23
|
+
Segment-style `identify`/`group`/`alias`/`page`) were removed because no consumer called
|
|
24
|
+
them — git history has them if a real need returns.
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pnpm add @codefast/tracking
|
|
30
|
+
```
|
|
17
31
|
|
|
18
|
-
|
|
32
|
+
Every peer is optional and only needed by the surface that uses it: `react`/`react-dom`
|
|
33
|
+
(>= 19) for `/react`, `@tanstack/react-start` (>= 1.168) for `/adapters/tanstack-start`, and
|
|
34
|
+
`@vercel/analytics` for the Vercel destination.
|
|
35
|
+
|
|
36
|
+
## Quick Start
|
|
19
37
|
|
|
20
38
|
```ts
|
|
21
|
-
|
|
22
|
-
import {
|
|
23
|
-
import { createHttpDestination } from "@codefast/tracking/destinations";
|
|
24
|
-
import { z } from "zod";
|
|
39
|
+
// consent.ts — the one consent contract every surface shares
|
|
40
|
+
import { defineConsentConfig } from "@codefast/tracking";
|
|
25
41
|
|
|
26
|
-
export const
|
|
27
|
-
|
|
28
|
-
|
|
42
|
+
export const consentConfig = defineConsentConfig({
|
|
43
|
+
policyVersion: "2026-01", // bump to re-prompt everyone
|
|
44
|
+
requestedCategories: ["analytics"],
|
|
45
|
+
storageKey: "my-app-consent",
|
|
29
46
|
});
|
|
47
|
+
```
|
|
30
48
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
destinations: [createHttpDestination({ name: "internal", endpoint: "/api/events" })],
|
|
35
|
-
storage: createLocalStorageQueueStorage("tracking-queue"),
|
|
36
|
-
});
|
|
49
|
+
```ts
|
|
50
|
+
// consent-runtime.ts — live client instances derived from the config
|
|
51
|
+
import { createConsentRuntime } from "@codefast/tracking/client/consent-runtime";
|
|
37
52
|
|
|
38
|
-
|
|
39
|
-
|
|
53
|
+
import { consentConfig } from "./consent";
|
|
54
|
+
import { resolveVisitorConsent } from "./resolve-visitor-consent"; // server fn, see below
|
|
55
|
+
|
|
56
|
+
export const consentRuntime = createConsentRuntime({
|
|
57
|
+
config: consentConfig,
|
|
58
|
+
initialConsentSessionStorageKey: "my-app-initial-consent",
|
|
59
|
+
resolveInitialConsent: () => resolveVisitorConsent(),
|
|
60
|
+
});
|
|
40
61
|
```
|
|
41
62
|
|
|
42
63
|
```ts
|
|
43
|
-
|
|
64
|
+
// tracking.ts — catalog + tracker
|
|
65
|
+
import { defineEventCatalog } from "@codefast/tracking";
|
|
66
|
+
import { createClientTracker } from "@codefast/tracking/client/create-client-tracker";
|
|
67
|
+
import { createGoogleAnalyticsDestination } from "@codefast/tracking/destinations/google-analytics";
|
|
68
|
+
import { createVercelAnalyticsDestination } from "@codefast/tracking/destinations/vercel-analytics";
|
|
69
|
+
import * as z from "zod/mini";
|
|
44
70
|
|
|
45
|
-
|
|
71
|
+
import { consentRuntime } from "./consent-runtime";
|
|
72
|
+
|
|
73
|
+
export const catalog = defineEventCatalog({
|
|
74
|
+
copy_code: { schema: z.object({ name: z.string() }) },
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
export const tracker = createClientTracker({
|
|
78
|
+
anonymousId: () => "...", // see the durable anonymous id section
|
|
46
79
|
catalog,
|
|
47
80
|
destinations: [
|
|
48
|
-
|
|
81
|
+
// Vercel is cookieless and receives no identifier — it may keep counting pre-consent.
|
|
82
|
+
createVercelAnalyticsDestination({ consentRequirement: "exempt" }),
|
|
83
|
+
createGoogleAnalyticsDestination(),
|
|
49
84
|
],
|
|
85
|
+
isAnalyticsAllowed: consentRuntime.isAnalyticsAllowed,
|
|
50
86
|
});
|
|
51
87
|
|
|
52
|
-
|
|
88
|
+
tracker.track("copy_code", { name: "button" }); // typed + runtime-validated
|
|
53
89
|
```
|
|
54
90
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
91
|
+
Destinations own their transport (gtag.js and Vercel both batch in-page), so `track()`
|
|
92
|
+
is fire-and-forget — a failing destination can never break the interaction.
|
|
93
|
+
|
|
94
|
+
## Event catalog
|
|
95
|
+
|
|
96
|
+
The package ships no events and no schema library — every app builds its own catalog
|
|
97
|
+
with `defineEventCatalog` over whatever Standard Schema validator it already uses.
|
|
98
|
+
`track()` infers both the event name and its properties from the catalog, then validates
|
|
99
|
+
the properties at runtime; a mismatch throws at the call site. Async schemas are rejected
|
|
100
|
+
by design — tracking sits on synchronous call paths.
|
|
101
|
+
|
|
102
|
+
## Subpaths
|
|
103
|
+
|
|
104
|
+
The root `@codefast/tracking` is the **client entry**: it re-exports the isomorphic core
|
|
105
|
+
(catalog types, `Destination`, consent model + config) plus the whole browser-side surface
|
|
106
|
+
(tracker, consent runtime, React bindings, and the client destinations). Server-only lanes
|
|
107
|
+
are their own subpaths and are never re-exported from the root:
|
|
108
|
+
|
|
109
|
+
- `@codefast/tracking` — client entry: core + `createClientTracker`, `createConsentRuntime`,
|
|
110
|
+
the `useConsent`/`ConsentBanner`/`GtagConsentBootstrap` React bindings, the gtag +
|
|
111
|
+
ad-network destinations.
|
|
112
|
+
- `@codefast/tracking/destinations/vercel-analytics` — its own subpath so its
|
|
113
|
+
`@vercel/analytics` peer is only pulled in when used.
|
|
114
|
+
- `@codefast/tracking/server/*` — request-scoped, **server-only**: `server/initial-consent`,
|
|
115
|
+
`server/consent-receipt-store`, `server/measurement-protocol`, … (server code imports the
|
|
116
|
+
core it needs from `@codefast/tracking/core/*`, never from the client root).
|
|
117
|
+
- `@codefast/tracking/adapters/tanstack-start` — request/response glue over Start's server
|
|
118
|
+
context, **server-only**.
|
|
119
|
+
- `@codefast/tracking/tooling/import-protection` — `SERVER_ONLY_SUBPATHS` deny-list for
|
|
120
|
+
client bundles.
|
|
121
|
+
- `@codefast/tracking/css/consent.css` — optional plain-CSS theme for the consent banner.
|
|
122
|
+
|
|
123
|
+
Every built module is also its own subpath (e.g. `@codefast/tracking/client/gpc`) for
|
|
124
|
+
granular imports. Server-only lanes (`server/*`, `adapters/*`) must never enter a client
|
|
125
|
+
bundle — feed `SERVER_ONLY_SUBPATHS` to the framework's import-protection (see below). There
|
|
126
|
+
is deliberately no server-side tracker: destinations batch in-page, and the server half of
|
|
127
|
+
the package is consent resolution plus cookie persistence.
|
|
68
128
|
|
|
69
129
|
## Consent (region-based, per-category)
|
|
70
130
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
131
|
+
`ConsentDecision` is per-purpose (`{ ads, analytics }`), mirroring Google Consent Mode
|
|
132
|
+
v2. Region resolves the mode: GDPR (EU, plus UK/EEA-EFTA equivalents) and Vietnam's PDPL
|
|
133
|
+
get **opt-in**; the US (CCPA/CPRA) and unrecognized regions get **opt-out**, with GPC
|
|
134
|
+
honored as an ads-only opt-out. Stored records are policy-versioned and shape-checked —
|
|
135
|
+
a malformed or legacy-shaped record re-prompts instead of silently deciding.
|
|
136
|
+
|
|
137
|
+
- `useConsent({ config, mode, storage })` — `useSyncExternalStore` bridge over the stored
|
|
138
|
+
decision; cross-tab saves sync through the `storage` event.
|
|
139
|
+
- `ConsentBanner` + parts (`Title`/`Description`/`Actions`/`Accept`/`Reject`/`Customize`/
|
|
140
|
+
`Preferences`/`Category`/`Save`) — headless, `data-slot`-styleable; optional plain-CSS
|
|
141
|
+
theme at `@codefast/tracking/css/consent.css`. `ConsentToggle` is the persistent
|
|
142
|
+
opt-out control CCPA requires.
|
|
143
|
+
- `useGoogleConsentSync(consent, { loadGtagScript? })` — pushes Consent Mode `update`
|
|
144
|
+
signals, including privacy-page and cross-tab decisions.
|
|
145
|
+
- `createConsentWithdrawalHandler({ clearAnonymousId?, clearGoogleAnalyticsCookies? })` —
|
|
146
|
+
wire to `onDecision` so a denial clears first-party identifiers.
|
|
147
|
+
|
|
148
|
+
### The ISR lane
|
|
149
|
+
|
|
150
|
+
ISR/CDN-cached HTML is shared across visitors, so no render may read geo. Bake
|
|
151
|
+
`STRICTEST_INITIAL_CONSENT` into the shared render (and into `<GtagConsentBootstrap />`),
|
|
152
|
+
then resolve the region-correct default per visitor after hydration:
|
|
153
|
+
|
|
154
|
+
1. **Server function** — `resolveInitialConsentFromRequest({ requestedCategories })`
|
|
155
|
+
(`@codefast/tracking/adapters/tanstack-start`) reads the geo header and `sec-gpc`, stamps
|
|
156
|
+
`cache-control: private, no-store`, and fails closed when geo is missing.
|
|
157
|
+
2. **Client** — `createConsentRuntime` owns the rest: strictest default until the server
|
|
158
|
+
answers, single-flight resolve, per-session cache, fail-closed-but-retryable errors.
|
|
159
|
+
Kick `runtime.ensureInitialConsentResolved()` at router creation (window-guarded) so
|
|
160
|
+
the round trip overlaps hydration; read it reactively via
|
|
161
|
+
`useInitialConsent(runtime.initialConsentStore)` (`@codefast/tracking/react/use-initial-consent`).
|
|
162
|
+
|
|
163
|
+
## Durable anonymous id ("client mints, server persists")
|
|
164
|
+
|
|
165
|
+
`createServerPersistedAnonymousId` (`@codefast/tracking/client/server-persisted-anonymous-id`) mints a UUID cookie
|
|
166
|
+
lazily — only once an event is actually allowed to send — and asks the server to re-issue
|
|
167
|
+
it via `Set-Cookie`, which escapes Safari ITP's 7-day cap on script-written cookies. The
|
|
168
|
+
server half is one line per endpoint with `setAnonymousIdResponseCookie` /
|
|
169
|
+
`clearAnonymousIdResponseCookie` (`@codefast/tracking/adapters/tanstack-start`); both validate the
|
|
170
|
+
id is exactly UUID-shaped, so a public endpoint can never echo attacker input into a
|
|
171
|
+
response header.
|
|
172
|
+
|
|
173
|
+
## Google tag (advanced Consent Mode)
|
|
174
|
+
|
|
175
|
+
`<GtagConsentBootstrap config={consentConfig} defaultConsent={...} gaMeasurementId="G-…" />`
|
|
176
|
+
(`@codefast/tracking/react/use-initial-consent`) renders the pre-hydration inline script: Consent Mode v2
|
|
177
|
+
`default` first (stored decision wins over the baked fallback), then gtag.js always loads
|
|
178
|
+
so cookieless pings and consent modeling can run even when storage is denied. Page views
|
|
179
|
+
are gtag's own job (`config` + Enhanced Measurement) — the destination only forwards
|
|
180
|
+
catalog events. Runtime changes go through `useGoogleConsentSync`/`updateGoogleConsent`.
|
|
181
|
+
|
|
182
|
+
## Keeping server-only subpaths out of client bundles
|
|
183
|
+
|
|
184
|
+
`./server` and `./adapters/tanstack-start` must never enter a client bundle. On TanStack Start,
|
|
185
|
+
spread the package's own deny-list into the plugin's import-protection so it versions
|
|
186
|
+
with the package instead of going stale in your config:
|
|
75
187
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
The banner ships as composable, headless parts — no `@codefast/ui` dependency, any
|
|
79
|
-
markup (including a design system's button styles via `className`) slots in. For a
|
|
80
|
-
default look without writing CSS, import the optional plain-CSS theme:
|
|
188
|
+
```ts
|
|
189
|
+
import { SERVER_ONLY_SUBPATHS } from "@codefast/tracking/tooling/import-protection";
|
|
81
190
|
|
|
82
|
-
|
|
83
|
-
|
|
191
|
+
tanstackStart({
|
|
192
|
+
importProtection: {
|
|
193
|
+
client: { specifiers: [...SERVER_ONLY_SUBPATHS] },
|
|
194
|
+
},
|
|
195
|
+
});
|
|
84
196
|
```
|
|
85
197
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
`prompt` and `preferences`.
|
|
91
|
-
|
|
92
|
-
```tsx
|
|
93
|
-
import { createLocalStorageConsentStorage } from "@codefast/tracking/client";
|
|
94
|
-
import { updateGoogleConsent } from "@codefast/tracking/destinations";
|
|
95
|
-
import {
|
|
96
|
-
ConsentBanner,
|
|
97
|
-
ConsentBannerAccept,
|
|
98
|
-
ConsentBannerActions,
|
|
99
|
-
ConsentBannerCategory,
|
|
100
|
-
ConsentBannerCustomize,
|
|
101
|
-
ConsentBannerDescription,
|
|
102
|
-
ConsentBannerPreferences,
|
|
103
|
-
ConsentBannerReject,
|
|
104
|
-
ConsentBannerSave,
|
|
105
|
-
ConsentBannerTitle,
|
|
106
|
-
ConsentToggle,
|
|
107
|
-
useConsent,
|
|
108
|
-
} from "@codefast/tracking/react";
|
|
109
|
-
|
|
110
|
-
// Module scope — useConsent subscribes to the storage, so it must be a stable reference.
|
|
111
|
-
const consentStorage = createLocalStorageConsentStorage("tracking-consent");
|
|
112
|
-
|
|
113
|
-
function ConsentGate({ mode }: { mode: "opt-in" | "opt-out" }) {
|
|
114
|
-
const consent = useConsent({
|
|
115
|
-
categories: ["analytics"], // the purposes your prompt asks about — Accept grants exactly these
|
|
116
|
-
mode,
|
|
117
|
-
onDecision: (decision) => {
|
|
118
|
-
updateGoogleConsent(decision); // per-category Consent Mode v2 update
|
|
119
|
-
if (!decision.analytics) tracker.clear(); // stop tracking + drop the pending queue
|
|
120
|
-
},
|
|
121
|
-
policyVersion: "2026-01",
|
|
122
|
-
storage: consentStorage,
|
|
123
|
-
});
|
|
124
|
-
|
|
125
|
-
return mode === "opt-in" ? (
|
|
126
|
-
<ConsentBanner consent={consent}>
|
|
127
|
-
<ConsentBannerTitle>Cookies & analytics</ConsentBannerTitle>
|
|
128
|
-
<ConsentBannerDescription>
|
|
129
|
-
We use cookies to understand how you use this site. <a href="/privacy">Privacy policy</a>
|
|
130
|
-
</ConsentBannerDescription>
|
|
131
|
-
{/* optional second layer: per-category checkboxes ("Customize" → "Save preferences") */}
|
|
132
|
-
<ConsentBannerPreferences>
|
|
133
|
-
<ConsentBannerCategory category="analytics">Analytics</ConsentBannerCategory>
|
|
134
|
-
<ConsentBannerSave>Save preferences</ConsentBannerSave>
|
|
135
|
-
</ConsentBannerPreferences>
|
|
136
|
-
<ConsentBannerActions>
|
|
137
|
-
<ConsentBannerAccept>Accept</ConsentBannerAccept>
|
|
138
|
-
<ConsentBannerReject>Reject</ConsentBannerReject>
|
|
139
|
-
<ConsentBannerCustomize>Customize</ConsentBannerCustomize>
|
|
140
|
-
</ConsentBannerActions>
|
|
141
|
-
</ConsentBanner>
|
|
142
|
-
) : (
|
|
143
|
-
<ConsentToggle consent={consent} />
|
|
144
|
-
);
|
|
145
|
-
}
|
|
146
|
-
```
|
|
198
|
+
A violation is mocked with a console diagnostic in dev and fails the build in prod, with
|
|
199
|
+
a trace of the offending import chain.
|
|
200
|
+
|
|
201
|
+
## Reference consumer
|
|
147
202
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
203
|
+
[`apps/ui` (`src/features/tracking/`)](https://github.com/codefastlabs/codefast/tree/main/apps/ui/src/features/tracking)
|
|
204
|
+
in this repo wires everything above on a real ISR-deployed TanStack Start site — consent
|
|
205
|
+
config + runtime, banner + persistent toggle, gtag bootstrap, durable anonymous id, and
|
|
206
|
+
the private server-function consent lane.
|
|
151
207
|
|
|
152
|
-
|
|
153
|
-
hood): hydration-safe on prerendered pages, and a decision made in one tab dismisses the
|
|
154
|
-
banner in every other tab via the `storage` event.
|
|
208
|
+
## License
|
|
155
209
|
|
|
156
|
-
|
|
157
|
-
issues the pre-tag default (it defines the gtag queueing stub itself), and
|
|
158
|
-
`setGoogleAdsDataRedaction`/`setGoogleUrlPassthrough` cover the denied-ads flags. A GPC
|
|
159
|
-
signal is honored as a do-not-sell-or-share opt-out: it forces `ads` denied without
|
|
160
|
-
withdrawing first-party `analytics`.
|
|
210
|
+
[MIT](https://github.com/codefastlabs/codefast/blob/main/LICENSE)
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { ConsentCategory, InitialConsent } from "#/core/consent";
|
|
2
|
+
import type { ConsentReceipt, ConsentReceiptInput } from "#/core/consent-receipt";
|
|
3
|
+
import type { AnonymousIdCookieOptions } from "#/server/anonymous-id-cookie";
|
|
4
|
+
import type { ReceiptStore } from "#/server/consent-receipt-store";
|
|
5
|
+
/**
|
|
6
|
+
* @since 1.0.0-canary.7
|
|
7
|
+
*/
|
|
8
|
+
export interface InitialConsentFromRequestOptions {
|
|
9
|
+
/**
|
|
10
|
+
* Header carrying the ISO 3166-1 alpha-2 country code.
|
|
11
|
+
*
|
|
12
|
+
* @defaultValue "x-vercel-ip-country"
|
|
13
|
+
*/
|
|
14
|
+
countryHeaderName?: string | undefined;
|
|
15
|
+
/** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
|
|
16
|
+
requestedCategories: ReadonlyArray<ConsentCategory>;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Region-correct `InitialConsent` for the current request: reads the platform geo header
|
|
20
|
+
* and `sec-gpc`, fails closed when geo is missing, and stamps
|
|
21
|
+
* `cache-control: private, no-store` — the value is per-visitor by definition, so no
|
|
22
|
+
* shared cache may ever store the response carrying it.
|
|
23
|
+
*
|
|
24
|
+
* Server-only: deny this subpath in the client environment via Start's `importProtection`
|
|
25
|
+
* — the compiler already strips it with stubbed handler bodies.
|
|
26
|
+
*
|
|
27
|
+
* @since 1.0.0-canary.6
|
|
28
|
+
*/
|
|
29
|
+
export declare function resolveInitialConsentFromRequest(options: InitialConsentFromRequestOptions): InitialConsent;
|
|
30
|
+
/**
|
|
31
|
+
* Persists (or prolongs) a client-minted anonymous id via the framework's `setCookie` (which
|
|
32
|
+
* appends, so it never clobbers another `Set-Cookie` on the response) — the server re-issue
|
|
33
|
+
* that escapes Safari ITP's 7-day cap on script-written cookies. Validation lives in
|
|
34
|
+
* `resolveAnonymousIdCookie`: a non-UUID id throws, so this can safely back a public server
|
|
35
|
+
* function without echoing attacker input into a header.
|
|
36
|
+
*
|
|
37
|
+
* @since 1.0.0-canary.6
|
|
38
|
+
*/
|
|
39
|
+
export declare function setAnonymousIdResponseCookie(options: AnonymousIdCookieOptions): void;
|
|
40
|
+
/**
|
|
41
|
+
* Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
|
|
42
|
+
*
|
|
43
|
+
* @since 1.0.0-canary.6
|
|
44
|
+
*/
|
|
45
|
+
export declare function clearAnonymousIdResponseCookie(cookieName: string): void;
|
|
46
|
+
/**
|
|
47
|
+
* The client-visible acknowledgement of a recorded receipt — deliberately minimal so the
|
|
48
|
+
* stored PII (`subjectId`, `ipCoarse`) is never echoed back over the wire.
|
|
49
|
+
*
|
|
50
|
+
* @since 1.0.0-canary.7
|
|
51
|
+
*/
|
|
52
|
+
export interface ConsentReceiptAck {
|
|
53
|
+
receiptId: string;
|
|
54
|
+
timestamp: number;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* @since 1.0.0-canary.7
|
|
58
|
+
*/
|
|
59
|
+
export interface RecordConsentReceiptFromRequestOptions {
|
|
60
|
+
input: ConsentReceiptInput;
|
|
61
|
+
/**
|
|
62
|
+
* Optional tamper-evidence signer — supply an HMAC/signature over the receipt to stamp an
|
|
63
|
+
* `integrityKey`. Omit it and the stored receipt carries none.
|
|
64
|
+
*/
|
|
65
|
+
sign?: ((receipt: Omit<ConsentReceipt, "integrityKey">) => string) | undefined;
|
|
66
|
+
store: ReceiptStore;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Records a consent receipt for the current request: rejects a body-supplied IP, derives a
|
|
70
|
+
* coarsened one from the connection, builds the server-stamped receipt, appends it to the
|
|
71
|
+
* store, and stamps `cache-control: no-store` — the response carries PII, so no cache
|
|
72
|
+
* (shared or private) may store it. Returns a minimal ack, never the stored record.
|
|
73
|
+
*
|
|
74
|
+
* @throws Error when `input` fails {@link isConsentReceiptInput} (including a body that
|
|
75
|
+
* carries an `ip`/`ipCoarse` field — the server owns IP derivation).
|
|
76
|
+
*
|
|
77
|
+
* @since 1.0.0-canary.7
|
|
78
|
+
*/
|
|
79
|
+
export declare function recordConsentReceiptFromRequest(options: RecordConsentReceiptFromRequestOptions): Promise<ConsentReceiptAck>;
|
|
80
|
+
//# sourceMappingURL=tanstack-start.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tanstack-start.d.ts","sourceRoot":"","sources":["../../src/adapters/tanstack-start.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAGnE;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,+FAA+F;IAC/F,mBAAmB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,gCAAgC,GAAG,cAAc,CAQ1G;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAQpF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sCAAsC;IACrD,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IAC/E,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,sCAAsC,GAC9C,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { deleteCookie, getRequestHeader, getRequestIP, setCookie, setResponseHeader, } from "@tanstack/react-start/server";
|
|
2
|
+
import { isConsentReceiptInput } from "#/core/consent-receipt";
|
|
3
|
+
import { resolveAnonymousIdCookie, resolveClearAnonymousIdCookie } from "#/server/anonymous-id-cookie";
|
|
4
|
+
import { buildConsentReceipt } from "#/server/consent-receipt";
|
|
5
|
+
import { resolveInitialConsent } from "#/server/initial-consent";
|
|
6
|
+
/**
|
|
7
|
+
* Region-correct `InitialConsent` for the current request: reads the platform geo header
|
|
8
|
+
* and `sec-gpc`, fails closed when geo is missing, and stamps
|
|
9
|
+
* `cache-control: private, no-store` — the value is per-visitor by definition, so no
|
|
10
|
+
* shared cache may ever store the response carrying it.
|
|
11
|
+
*
|
|
12
|
+
* Server-only: deny this subpath in the client environment via Start's `importProtection`
|
|
13
|
+
* — the compiler already strips it with stubbed handler bodies.
|
|
14
|
+
*
|
|
15
|
+
* @since 1.0.0-canary.6
|
|
16
|
+
*/
|
|
17
|
+
export function resolveInitialConsentFromRequest(options) {
|
|
18
|
+
setResponseHeader("cache-control", "private, no-store");
|
|
19
|
+
return resolveInitialConsent({
|
|
20
|
+
countryCode: getRequestHeader(options.countryHeaderName ?? "x-vercel-ip-country"),
|
|
21
|
+
hasGlobalPrivacyControlSignal: getRequestHeader("sec-gpc") === "1",
|
|
22
|
+
requestedCategories: options.requestedCategories,
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Persists (or prolongs) a client-minted anonymous id via the framework's `setCookie` (which
|
|
27
|
+
* appends, so it never clobbers another `Set-Cookie` on the response) — the server re-issue
|
|
28
|
+
* that escapes Safari ITP's 7-day cap on script-written cookies. Validation lives in
|
|
29
|
+
* `resolveAnonymousIdCookie`: a non-UUID id throws, so this can safely back a public server
|
|
30
|
+
* function without echoing attacker input into a header.
|
|
31
|
+
*
|
|
32
|
+
* @since 1.0.0-canary.6
|
|
33
|
+
*/
|
|
34
|
+
export function setAnonymousIdResponseCookie(options) {
|
|
35
|
+
const { name, value, ...attributes } = resolveAnonymousIdCookie({
|
|
36
|
+
cookieName: options.cookieName,
|
|
37
|
+
id: options.id,
|
|
38
|
+
maxAgeSeconds: options.maxAgeSeconds,
|
|
39
|
+
});
|
|
40
|
+
setCookie(name, value, attributes);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Expires the anonymous-id cookie on the current response — the server half of a consent withdrawal.
|
|
44
|
+
*
|
|
45
|
+
* @since 1.0.0-canary.6
|
|
46
|
+
*/
|
|
47
|
+
export function clearAnonymousIdResponseCookie(cookieName) {
|
|
48
|
+
const { name, ...attributes } = resolveClearAnonymousIdCookie(cookieName);
|
|
49
|
+
deleteCookie(name, attributes);
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Records a consent receipt for the current request: rejects a body-supplied IP, derives a
|
|
53
|
+
* coarsened one from the connection, builds the server-stamped receipt, appends it to the
|
|
54
|
+
* store, and stamps `cache-control: no-store` — the response carries PII, so no cache
|
|
55
|
+
* (shared or private) may store it. Returns a minimal ack, never the stored record.
|
|
56
|
+
*
|
|
57
|
+
* @throws Error when `input` fails {@link isConsentReceiptInput} (including a body that
|
|
58
|
+
* carries an `ip`/`ipCoarse` field — the server owns IP derivation).
|
|
59
|
+
*
|
|
60
|
+
* @since 1.0.0-canary.7
|
|
61
|
+
*/
|
|
62
|
+
export async function recordConsentReceiptFromRequest(options) {
|
|
63
|
+
setResponseHeader("cache-control", "no-store");
|
|
64
|
+
if (!isConsentReceiptInput(options.input)) {
|
|
65
|
+
throw new Error("Invalid consent receipt input");
|
|
66
|
+
}
|
|
67
|
+
// getRequestIP reads the platform/socket IP, trusting X-Forwarded-For's first hop — safe
|
|
68
|
+
// behind the CDN/proxy this app deploys to, and the maintained path over hand-parsing headers.
|
|
69
|
+
const rawIp = getRequestIP({ xForwardedFor: true });
|
|
70
|
+
const receipt = buildConsentReceipt({ input: options.input, rawIp, sign: options.sign });
|
|
71
|
+
await options.store.append(receipt);
|
|
72
|
+
return { receiptId: receipt.receiptId, timestamp: receipt.timestamp };
|
|
73
|
+
}
|
|
74
|
+
//# sourceMappingURL=tanstack-start.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tanstack-start.js","sourceRoot":"","sources":["../../src/adapters/tanstack-start.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AACvG,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAgBjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAAC,OAAyC;IACxF,iBAAiB,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAExD,OAAO,qBAAqB,CAAC;QAC3B,WAAW,EAAE,gBAAgB,CAAC,OAAO,CAAC,iBAAiB,IAAI,qBAAqB,CAAC;QACjF,6BAA6B,EAAE,gBAAgB,CAAC,SAAS,CAAC,KAAK,GAAG;QAClE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;KACjD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAiC;IAC5E,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,UAAU,EAAE,GAAG,wBAAwB,CAAC;QAC9D,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;IAEH,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,UAAkB;IAC/D,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,EAAE,GAAG,6BAA6B,CAAC,UAAU,CAAC,CAAC;IAE1E,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC;AA0BD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,OAA+C;IAE/C,iBAAiB,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IAE/C,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,yFAAyF;IACzF,+FAA+F;IAC/F,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEzF,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEpC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;AACxE,CAAC"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { ConsentCategory, ConsentDecision } from "#/core/consent";
|
|
2
|
+
/**
|
|
3
|
+
* TCF/GPP interop reconciler (spec-ad-consent-frameworks): the system **reads** an external
|
|
4
|
+
* CMP and reconciles it with the native `{ ads, analytics }` decision — it never becomes a
|
|
5
|
+
* CMP, mints TC/GPP strings, or hard-codes TCF purpose ids or the Google vendor id (that
|
|
6
|
+
* mapping is ad-ops policy, so the caller derives `CmpConsentSignal` and passes it in).
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Liveness of a detected CMP. `"out-of-scope"` is TCF `gdprApplies === false` / no applicable
|
|
10
|
+
* GPP section — the framework does not govern this user, so native consent stands.
|
|
11
|
+
*
|
|
12
|
+
* @since 1.0.0-canary.7
|
|
13
|
+
*/
|
|
14
|
+
export type CmpStatus = "loading" | "out-of-scope" | "ready";
|
|
15
|
+
/**
|
|
16
|
+
* A CMP's governance over the native decision, already derived from TCData/GPP by ad-ops policy.
|
|
17
|
+
*
|
|
18
|
+
* @since 1.0.0-canary.7
|
|
19
|
+
*/
|
|
20
|
+
export interface CmpConsentSignal {
|
|
21
|
+
/** Per-governed-category grant, read once `status` is `"ready"`. */
|
|
22
|
+
decision?: Partial<ConsentDecision> | undefined;
|
|
23
|
+
/** Categories this CMP governs in the current scope — the resolver overrides only these. */
|
|
24
|
+
governs: ReadonlyArray<ConsentCategory>;
|
|
25
|
+
status: CmpStatus;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* @since 1.0.0-canary.7
|
|
29
|
+
*/
|
|
30
|
+
export interface ReconcileAdFrameworkConsentOptions {
|
|
31
|
+
/** The live CMP signal, or omitted when no CMP is present (the resolver is then inert). */
|
|
32
|
+
cmp?: CmpConsentSignal | undefined;
|
|
33
|
+
/** Native GPC — can only tighten `ads`, never loosen a CMP grant. */
|
|
34
|
+
hasGlobalPrivacyControlSignal: boolean;
|
|
35
|
+
/** The stored/default decision that stands wherever no CMP governs. */
|
|
36
|
+
native: ConsentDecision;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Reconciles native consent with a CMP source of truth per spec-ad-consent-frameworks §3:
|
|
40
|
+
* a governing CMP overrides its categories (fail-closed to denied while loading); a missing
|
|
41
|
+
* or out-of-scope CMP leaves native standing; GPC always tightens `ads` last.
|
|
42
|
+
*
|
|
43
|
+
* @since 1.0.0-canary.7
|
|
44
|
+
*/
|
|
45
|
+
export declare function reconcileAdFrameworkConsent(options: ReconcileAdFrameworkConsentOptions): ConsentDecision;
|
|
46
|
+
/**
|
|
47
|
+
* Detects a TCF CMP without reading it — `typeof __tcfapi === "function"` (spec §3).
|
|
48
|
+
*
|
|
49
|
+
* @since 1.0.0-canary.7
|
|
50
|
+
*/
|
|
51
|
+
export declare function hasTcfApi(scope?: {
|
|
52
|
+
__tcfapi?: unknown;
|
|
53
|
+
}): boolean;
|
|
54
|
+
/**
|
|
55
|
+
* Detects a GPP CMP without reading it — `typeof __gpp === "function"` (spec §3).
|
|
56
|
+
*
|
|
57
|
+
* @since 1.0.0-canary.7
|
|
58
|
+
*/
|
|
59
|
+
export declare function hasGppApi(scope?: {
|
|
60
|
+
__gpp?: unknown;
|
|
61
|
+
}): boolean;
|
|
62
|
+
//# sourceMappingURL=ad-framework-consent.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ad-framework-consent.d.ts","sourceRoot":"","sources":["../../src/client/ad-framework-consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvE;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,OAAO,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;IAChD,4FAA4F;IAC5F,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,2FAA2F;IAC3F,GAAG,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACnC,qEAAqE;IACrE,6BAA6B,EAAE,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kCAAkC,GAAG,eAAe,CAkBxG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAyC,GAAG,OAAO,CAEvG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAsC,GAAG,OAAO,CAEjG"}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reconciles native consent with a CMP source of truth per spec-ad-consent-frameworks §3:
|
|
3
|
+
* a governing CMP overrides its categories (fail-closed to denied while loading); a missing
|
|
4
|
+
* or out-of-scope CMP leaves native standing; GPC always tightens `ads` last.
|
|
5
|
+
*
|
|
6
|
+
* @since 1.0.0-canary.7
|
|
7
|
+
*/
|
|
8
|
+
export function reconcileAdFrameworkConsent(options) {
|
|
9
|
+
const result = { ...options.native };
|
|
10
|
+
const { cmp } = options;
|
|
11
|
+
// A governing CMP overrides only the categories it governs; no CMP / out-of-scope leaves native.
|
|
12
|
+
if (cmp && cmp.status !== "out-of-scope") {
|
|
13
|
+
for (const category of cmp.governs) {
|
|
14
|
+
// Fail closed until the CMP resolves; otherwise the CMP value wins for its categories.
|
|
15
|
+
result[category] = cmp.status === "loading" ? false : (cmp.decision?.[category] ?? false);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
// GPC can only tighten `ads` — applied last so it wins over any CMP grant.
|
|
19
|
+
if (options.hasGlobalPrivacyControlSignal) {
|
|
20
|
+
result.ads = false;
|
|
21
|
+
}
|
|
22
|
+
return result;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Detects a TCF CMP without reading it — `typeof __tcfapi === "function"` (spec §3).
|
|
26
|
+
*
|
|
27
|
+
* @since 1.0.0-canary.7
|
|
28
|
+
*/
|
|
29
|
+
export function hasTcfApi(scope = globalThis) {
|
|
30
|
+
return typeof scope.__tcfapi === "function";
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Detects a GPP CMP without reading it — `typeof __gpp === "function"` (spec §3).
|
|
34
|
+
*
|
|
35
|
+
* @since 1.0.0-canary.7
|
|
36
|
+
*/
|
|
37
|
+
export function hasGppApi(scope = globalThis) {
|
|
38
|
+
return typeof scope.__gpp === "function";
|
|
39
|
+
}
|
|
40
|
+
//# sourceMappingURL=ad-framework-consent.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ad-framework-consent.js","sourceRoot":"","sources":["../../src/client/ad-framework-consent.ts"],"names":[],"mappings":"AA0CA;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAA2C;IACrF,MAAM,MAAM,GAAoB,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IACtD,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAExB,iGAAiG;IACjG,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACzC,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YACnC,uFAAuF;YACvF,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,OAAO,CAAC,6BAA6B,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAK,GAA2B,UAAoC;IAC5F,OAAO,OAAO,KAAK,CAAC,QAAQ,KAAK,UAAU,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAK,GAAwB,UAAiC;IACtF,OAAO,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU,CAAC;AAC3C,CAAC"}
|
|
@@ -0,0 +1,9 @@
|
|
|
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 declare function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void;
|
|
9
|
+
//# sourceMappingURL=browser-cookie.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser-cookie.d.ts","sourceRoot":"","sources":["../../src/client/browser-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAQjG"}
|
|
@@ -0,0 +1,15 @@
|
|
|
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, value, maxAgeSeconds) {
|
|
9
|
+
if (typeof document === "undefined") {
|
|
10
|
+
return;
|
|
11
|
+
}
|
|
12
|
+
const secure = globalThis.location.protocol === "https:" ? "; secure" : "";
|
|
13
|
+
document.cookie = `${cookieName}=${value}; path=/; max-age=${String(maxAgeSeconds)}; samesite=lax${secure}`;
|
|
14
|
+
}
|
|
15
|
+
//# sourceMappingURL=browser-cookie.js.map
|