@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.
- package/CHANGELOG.md +165 -0
- package/README.md +122 -127
- package/dist/client/browser-cookie.d.mts +11 -0
- package/dist/client/browser-cookie.mjs +15 -0
- package/dist/client/consent-runtime.d.mts +56 -0
- package/dist/client/consent-runtime.mjs +35 -0
- package/dist/client/consent-storage.d.mts +5 -0
- package/dist/client/consent-storage.mjs +20 -1
- package/dist/client/consent-withdrawal.d.mts +21 -0
- package/dist/client/consent-withdrawal.mjs +17 -0
- package/dist/client/cookie-anonymous-id.d.mts +37 -0
- package/dist/client/cookie-anonymous-id.mjs +46 -0
- package/dist/client/create-client-tracker.d.mts +11 -16
- package/dist/client/create-client-tracker.mjs +27 -53
- package/dist/client/gpc.d.mts +2 -0
- package/dist/client/gpc.mjs +3 -1
- package/dist/client/index.d.mts +7 -5
- package/dist/client/index.mjs +8 -6
- package/dist/client/initial-consent-store.d.mts +66 -0
- package/dist/client/initial-consent-store.mjs +119 -0
- package/dist/client/is-analytics-allowed.d.mts +29 -0
- package/dist/client/is-analytics-allowed.mjs +23 -0
- package/dist/client/server-persisted-anonymous-id.d.mts +33 -0
- package/dist/client/server-persisted-anonymous-id.mjs +50 -0
- package/dist/core/consent-config.d.mts +27 -0
- package/dist/core/consent-config.mjs +11 -0
- package/dist/core/consent.d.mts +99 -4
- package/dist/core/consent.mjs +99 -4
- package/dist/core/cookie.d.mts +17 -0
- package/dist/core/cookie.mjs +23 -0
- package/dist/core/destination.d.mts +10 -8
- package/dist/core/event-catalog.d.mts +16 -13
- package/dist/core/event-catalog.mjs +19 -1
- package/dist/core/event-id.d.mts +1 -2
- package/dist/core/event-id.mjs +1 -2
- package/dist/core/index.d.mts +6 -4
- package/dist/core/index.mjs +5 -3
- package/dist/core/tracked-event.d.mts +21 -8
- package/dist/destinations/google-analytics.d.mts +100 -48
- package/dist/destinations/google-analytics.mjs +89 -85
- package/dist/destinations/google-consent.d.mts +64 -0
- package/dist/destinations/google-consent.mjs +102 -0
- package/dist/destinations/index.d.mts +2 -5
- package/dist/destinations/index.mjs +2 -5
- package/dist/destinations/shared.d.mts +20 -0
- package/dist/destinations/shared.mjs +13 -0
- package/dist/destinations/vercel-analytics.d.mts +19 -4
- package/dist/destinations/vercel-analytics.mjs +11 -18
- package/dist/import-protection.d.mts +19 -0
- package/dist/import-protection.mjs +23 -0
- package/dist/index.d.mts +6 -4
- package/dist/index.mjs +5 -3
- package/dist/react/consent-banner.d.mts +24 -7
- package/dist/react/consent-banner.mjs +16 -11
- package/dist/react/gtag-consent-bootstrap.d.mts +27 -0
- package/dist/react/gtag-consent-bootstrap.mjs +29 -0
- package/dist/react/index.d.mts +4 -1
- package/dist/react/index.mjs +4 -1
- package/dist/react/use-consent.d.mts +9 -13
- package/dist/react/use-consent.mjs +42 -25
- package/dist/react/use-google-consent-sync.d.mts +23 -0
- package/dist/react/use-google-consent-sync.mjs +24 -0
- package/dist/react/use-initial-consent.d.mts +14 -0
- package/dist/react/use-initial-consent.mjs +19 -0
- package/dist/server/anonymous-id-cookie.d.mts +46 -0
- package/dist/server/anonymous-id-cookie.mjs +51 -0
- package/dist/server/index.d.mts +5 -3
- package/dist/server/index.mjs +4 -3
- package/dist/server/initial-consent.d.mts +29 -0
- package/dist/server/initial-consent.mjs +31 -0
- package/dist/server/region.d.mts +21 -4
- package/dist/server/region.mjs +26 -5
- package/dist/tanstack-start/index.d.mts +58 -0
- package/dist/tanstack-start/index.mjs +45 -0
- package/package.json +26 -110
- 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 +93 -0
- package/src/client/create-client-tracker.ts +56 -85
- package/src/client/gpc.ts +4 -2
- package/src/client/index.ts +19 -8
- 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 +99 -0
- package/src/core/consent-config.ts +27 -0
- package/src/core/consent.ts +164 -10
- package/src/core/cookie.ts +29 -0
- package/src/core/destination.ts +10 -8
- package/src/core/event-catalog.ts +28 -15
- package/src/core/event-id.ts +1 -2
- package/src/core/index.ts +19 -3
- package/src/core/tracked-event.ts +22 -7
- package/src/destinations/google-analytics.ts +196 -133
- package/src/destinations/google-consent.ts +164 -0
- package/src/destinations/index.ts +14 -15
- package/src/destinations/shared.ts +45 -0
- package/src/destinations/vercel-analytics.ts +23 -24
- package/src/import-protection.ts +20 -0
- package/src/index.ts +46 -8
- package/src/react/consent-banner.tsx +40 -14
- package/src/react/gtag-consent-bootstrap.tsx +48 -0
- package/src/react/index.ts +8 -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 +76 -0
- package/src/server/index.ts +15 -3
- package/src/server/initial-consent.ts +48 -0
- package/src/server/region.ts +22 -5
- package/src/tanstack-start/index.ts +83 -0
- 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/destinations/ga4-measurement-protocol.d.mts +0 -54
- package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
- package/dist/destinations/http-destination.d.mts +0 -20
- package/dist/destinations/http-destination.mjs +0 -25
- package/dist/server/create-server-tracker.d.mts +0 -42
- package/dist/server/create-server-tracker.mjs +0 -67
- 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/destinations/ga4-measurement-protocol.ts +0 -166
- package/src/destinations/http-destination.ts +0 -33
- package/src/server/create-server-tracker.ts +0 -128
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { ConsentMode, ConsentStorage } from "#/core/consent";
|
|
2
|
+
import { resolveEffectiveConsent } from "#/core/consent";
|
|
3
|
+
import type { ConsentConfig } from "#/core/consent-config";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* @since 1.0.0-canary.6
|
|
7
|
+
*/
|
|
8
|
+
export interface IsAnalyticsAllowedOptions {
|
|
9
|
+
/** Must be the same object `useConsent` receives — one config, every surface. */
|
|
10
|
+
config: ConsentConfig;
|
|
11
|
+
/**
|
|
12
|
+
* Re-read each call. Pass `hasGlobalPrivacyControlSignal` from `@codefast/tracking/client`
|
|
13
|
+
* (or a wrapper) so GPC changes apply without recreating the gate.
|
|
14
|
+
*/
|
|
15
|
+
hasGlobalPrivacyControlSignal?: (() => boolean) | undefined;
|
|
16
|
+
/** Re-read each call so a post-hydration region resolve can win. */
|
|
17
|
+
getMode: () => ConsentMode;
|
|
18
|
+
/** Must be the same storage instance `useConsent` subscribes to. */
|
|
19
|
+
storage: ConsentStorage;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Non-React mirror of `useConsent`'s `isAnalyticsAllowed` — pass the returned function as
|
|
24
|
+
* `createClientTracker({ isAnalyticsAllowed })` so the pipeline and the banner share one rule.
|
|
25
|
+
*
|
|
26
|
+
* @since 1.0.0-canary.6
|
|
27
|
+
*/
|
|
28
|
+
export function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean {
|
|
29
|
+
const { config, getMode, storage } = options;
|
|
30
|
+
const readGpc = options.hasGlobalPrivacyControlSignal ?? (() => false);
|
|
31
|
+
|
|
32
|
+
return (): boolean => {
|
|
33
|
+
const effectiveConsent = resolveEffectiveConsent({
|
|
34
|
+
hasGlobalPrivacyControlSignal: readGpc(),
|
|
35
|
+
mode: getMode(),
|
|
36
|
+
policyVersion: config.policyVersion,
|
|
37
|
+
requestedCategories: config.requestedCategories,
|
|
38
|
+
storage,
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
return effectiveConsent.analytics;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import type { CookieAnonymousId } from "#/client/cookie-anonymous-id";
|
|
2
|
+
import { createCookieAnonymousId } from "#/client/cookie-anonymous-id";
|
|
3
|
+
import { readCookieValue } from "#/core/cookie";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* @since 1.0.0-canary.6
|
|
7
|
+
*/
|
|
8
|
+
export interface ServerPersistedAnonymousIdOptions {
|
|
9
|
+
/** Server round-trip that expires the cookie via `Set-Cookie` — the server half of `clear()`. */
|
|
10
|
+
clearOnServer?: (() => Promise<void>) | undefined;
|
|
11
|
+
/** Cookie name — must not collide with another cookie on the domain. */
|
|
12
|
+
cookieName: string;
|
|
13
|
+
/** How long the id survives a return visit. Defaults to one year. */
|
|
14
|
+
maxAgeSeconds?: number | undefined;
|
|
15
|
+
/**
|
|
16
|
+
* Server round-trip that re-sets the cookie via `Set-Cookie` (e.g. a server function
|
|
17
|
+
* calling `buildAnonymousIdSetCookie`). Fired at most once per page load, only after an
|
|
18
|
+
* id exists client-side — the server persists and prolongs, it never mints.
|
|
19
|
+
*/
|
|
20
|
+
persist: (id: string) => Promise<void>;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* `createCookieAnonymousId` plus server persistence: the client still mints the id
|
|
25
|
+
* (lazily, only once an event is allowed to send — consent stays client-owned), then
|
|
26
|
+
* delegates the durable write to the server. A script-written cookie is capped at 7 days
|
|
27
|
+
* by Safari ITP; the server's `Set-Cookie` re-issue is what makes the id actually live
|
|
28
|
+
* its full max-age. Same optimistic `document.cookie` write first, so the current event
|
|
29
|
+
* never waits on the round-trip and a failed `persist` degrades to today's behavior.
|
|
30
|
+
*
|
|
31
|
+
* @since 1.0.0-canary.6
|
|
32
|
+
*/
|
|
33
|
+
export function createServerPersistedAnonymousId(options: ServerPersistedAnonymousIdOptions): CookieAnonymousId {
|
|
34
|
+
const { clearOnServer, cookieName, maxAgeSeconds, persist } = options;
|
|
35
|
+
const local = createCookieAnonymousId({ cookieName, maxAgeSeconds });
|
|
36
|
+
// One attempt per page load — a failure is not retried until the next load, so a down
|
|
37
|
+
// endpoint costs one request, not one per event. Tracking must never break the app.
|
|
38
|
+
let hasRequestedPersist = false;
|
|
39
|
+
|
|
40
|
+
return {
|
|
41
|
+
clear(): void {
|
|
42
|
+
// Skip the server round-trip when the cookie is already gone (e.g. a second
|
|
43
|
+
// withdrawal clear from another mounted consent surface in the same tick).
|
|
44
|
+
const shouldClearServer =
|
|
45
|
+
typeof document !== "undefined" && Boolean(readCookieValue(document.cookie, cookieName));
|
|
46
|
+
|
|
47
|
+
local.clear();
|
|
48
|
+
// A fresh id after a re-grant must be persisted again.
|
|
49
|
+
hasRequestedPersist = false;
|
|
50
|
+
|
|
51
|
+
if (shouldClearServer) {
|
|
52
|
+
void clearOnServer?.().catch(() => {
|
|
53
|
+
/* the client-side expiry above already took effect */
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
},
|
|
57
|
+
getOrCreate(): string {
|
|
58
|
+
// Cross-tab withdrawal expires the cookie without this instance's `clear()` — reset
|
|
59
|
+
// so the next minted id is server-persisted (ITP re-issue) again.
|
|
60
|
+
if (typeof document !== "undefined" && !readCookieValue(document.cookie, cookieName)) {
|
|
61
|
+
hasRequestedPersist = false;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const id = local.getOrCreate();
|
|
65
|
+
|
|
66
|
+
// Also fires when the cookie already existed: the re-issue upgrades a script-written
|
|
67
|
+
// cookie to a server-set one and rolls its expiry forward on every visit.
|
|
68
|
+
if (!hasRequestedPersist && typeof document !== "undefined") {
|
|
69
|
+
hasRequestedPersist = true;
|
|
70
|
+
void persist(id).catch(() => {
|
|
71
|
+
/* optimistic client-side cookie still covers this session */
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
return id;
|
|
76
|
+
},
|
|
77
|
+
refresh(): void {
|
|
78
|
+
if (typeof document === "undefined") {
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
const existing = readCookieValue(document.cookie, cookieName);
|
|
83
|
+
|
|
84
|
+
if (!existing) {
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
local.refresh();
|
|
89
|
+
|
|
90
|
+
// Same once-per-load budget as getOrCreate — refresh must not add a second request.
|
|
91
|
+
if (!hasRequestedPersist) {
|
|
92
|
+
hasRequestedPersist = true;
|
|
93
|
+
void persist(existing).catch(() => {
|
|
94
|
+
/* optimistic client-side prolong above still covers this session */
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { ConsentCategory } from "#/core/consent";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The consent constants every surface must agree on. The React hooks, the client
|
|
5
|
+
* tracker gate, and the pre-hydration tag bootstrap all accept this object, so the
|
|
6
|
+
* cross-surface "must match" contracts hold by construction instead of by hand-threading
|
|
7
|
+
* the same strings through every call site.
|
|
8
|
+
*
|
|
9
|
+
* @since 1.0.0-canary.6
|
|
10
|
+
*/
|
|
11
|
+
export interface ConsentConfig {
|
|
12
|
+
/** Bumping re-prompts every visitor — a stored decision under any other version is ignored. */
|
|
13
|
+
policyVersion: string;
|
|
14
|
+
/** Purposes the app's prompt asks about — `grantAll` and opt-out defaults grant exactly these. */
|
|
15
|
+
requestedCategories: ReadonlyArray<ConsentCategory>;
|
|
16
|
+
/** `localStorage` key holding the visitor's `ConsentRecord`. */
|
|
17
|
+
storageKey: string;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Identity helper for declaring the config with inference — `defineEventCatalog`'s consent twin.
|
|
22
|
+
*
|
|
23
|
+
* @since 1.0.0-canary.6
|
|
24
|
+
*/
|
|
25
|
+
export function defineConsentConfig<Config extends ConsentConfig>(config: Config): Config {
|
|
26
|
+
return config;
|
|
27
|
+
}
|
package/src/core/consent.ts
CHANGED
|
@@ -3,13 +3,27 @@
|
|
|
3
3
|
*/
|
|
4
4
|
export type ConsentRegion = "eu" | "other" | "us" | "vn";
|
|
5
5
|
|
|
6
|
+
/**
|
|
7
|
+
* @since 1.0.0-canary.6
|
|
8
|
+
*/
|
|
9
|
+
export const CONSENT_REGIONS: ReadonlyArray<ConsentRegion> = ["eu", "other", "us", "vn"];
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Guards a region read from untrusted storage (a cached `InitialConsent`, a cookie).
|
|
13
|
+
*
|
|
14
|
+
* @since 1.0.0-canary.6
|
|
15
|
+
*/
|
|
16
|
+
export function isConsentRegion(value: unknown): value is ConsentRegion {
|
|
17
|
+
return CONSENT_REGIONS.includes(value as ConsentRegion);
|
|
18
|
+
}
|
|
19
|
+
|
|
6
20
|
/**
|
|
7
21
|
* @since 0.5.0-canary.4
|
|
8
22
|
*/
|
|
9
23
|
export type ConsentMode = "opt-in" | "opt-out";
|
|
10
24
|
|
|
11
25
|
/**
|
|
12
|
-
* GDPR (EU) and
|
|
26
|
+
* GDPR (EU) and the PDPL — Luật 91/2025/QH15 (VN) — require explicit opt-in before any non-essential
|
|
13
27
|
* tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
|
|
14
28
|
* that satisfies both, so the mode is resolved per region.
|
|
15
29
|
*
|
|
@@ -60,19 +74,54 @@ export function createConsentDecision(grantedCategories: ReadonlyArray<ConsentCa
|
|
|
60
74
|
return { ads: grantedCategories.includes("ads"), analytics: grantedCategories.includes("analytics") };
|
|
61
75
|
}
|
|
62
76
|
|
|
77
|
+
function isPlainObject(value: unknown): value is Record<string, unknown> {
|
|
78
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
79
|
+
}
|
|
80
|
+
|
|
63
81
|
/**
|
|
64
82
|
* Guards stored JSON — the record is tamperable, so every category must be an explicit boolean.
|
|
65
83
|
*
|
|
66
84
|
* @since 0.5.0-canary.4
|
|
67
85
|
*/
|
|
68
86
|
export function isConsentDecision(value: unknown): value is ConsentDecision {
|
|
87
|
+
return isPlainObject(value) && CONSENT_CATEGORIES.every((category) => typeof value[category] === "boolean");
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Re-derives a clean per-category decision from a tamperable record — extra keys are
|
|
92
|
+
* dropped, every category becomes an explicit boolean. The one normalization rule shared
|
|
93
|
+
* by the client (`readStoredDecision`) and server (`readConsentDecisionCookie`) mirrors.
|
|
94
|
+
*
|
|
95
|
+
* @since 1.0.0-canary.6
|
|
96
|
+
*/
|
|
97
|
+
export function normalizeConsentDecision(decision: ConsentDecision): ConsentDecision {
|
|
98
|
+
return createConsentDecision(CONSENT_CATEGORIES.filter((category) => decision[category]));
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Guards a persisted consent record read from untrusted storage (e.g. `localStorage`).
|
|
103
|
+
*
|
|
104
|
+
* @since 1.0.0-canary.6
|
|
105
|
+
*/
|
|
106
|
+
export function isConsentRecord(value: unknown): value is ConsentRecord {
|
|
69
107
|
return (
|
|
70
|
-
|
|
71
|
-
value
|
|
72
|
-
|
|
108
|
+
isPlainObject(value) &&
|
|
109
|
+
isConsentDecision(value.decision) &&
|
|
110
|
+
typeof value.policyVersion === "string" &&
|
|
111
|
+
typeof value.timestamp === "number"
|
|
73
112
|
);
|
|
74
113
|
}
|
|
75
114
|
|
|
115
|
+
/**
|
|
116
|
+
* @since 1.0.0-canary.6
|
|
117
|
+
*/
|
|
118
|
+
export interface ResolveDefaultConsentOptions {
|
|
119
|
+
/** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
|
|
120
|
+
hasGlobalPrivacyControlSignal: boolean;
|
|
121
|
+
mode: ConsentMode;
|
|
122
|
+
requestedCategories: ReadonlyArray<ConsentCategory>;
|
|
123
|
+
}
|
|
124
|
+
|
|
76
125
|
/**
|
|
77
126
|
* The effective consent before the visitor decides: opt-in regions start all-denied,
|
|
78
127
|
* opt-out regions grant the categories the app asks for.
|
|
@@ -83,11 +132,9 @@ export function isConsentDecision(value: unknown): value is ConsentDecision {
|
|
|
83
132
|
*
|
|
84
133
|
* @since 0.5.0-canary.4
|
|
85
134
|
*/
|
|
86
|
-
export function resolveDefaultConsent(
|
|
87
|
-
mode
|
|
88
|
-
|
|
89
|
-
hasGlobalPrivacyControlSignal: boolean,
|
|
90
|
-
): ConsentDecision {
|
|
135
|
+
export function resolveDefaultConsent(options: ResolveDefaultConsentOptions): ConsentDecision {
|
|
136
|
+
const { hasGlobalPrivacyControlSignal, mode, requestedCategories } = options;
|
|
137
|
+
|
|
91
138
|
if (mode === "opt-in") {
|
|
92
139
|
return createConsentDecision([]);
|
|
93
140
|
}
|
|
@@ -102,7 +149,68 @@ export function resolveDefaultConsent(
|
|
|
102
149
|
}
|
|
103
150
|
|
|
104
151
|
/**
|
|
105
|
-
*
|
|
152
|
+
* Region-resolved consent defaults — typically from `resolveInitialConsent` on a
|
|
153
|
+
* per-request server lane, then handed to the client so it never re-guesses the mode.
|
|
154
|
+
*
|
|
155
|
+
* @remarks
|
|
156
|
+
* Drive UI and gates from `mode` (recompute `effectiveConsent` with live navigator GPC).
|
|
157
|
+
* `defaultConsent` is the server snapshot — useful when you need request-time `sec-gpc`
|
|
158
|
+
* as-is; analytics-only apps can ignore it because GPC only forces `ads` denied.
|
|
159
|
+
*
|
|
160
|
+
* @since 1.0.0-canary.6
|
|
161
|
+
*/
|
|
162
|
+
export interface InitialConsent {
|
|
163
|
+
defaultConsent: ConsentDecision;
|
|
164
|
+
mode: ConsentMode;
|
|
165
|
+
region: ConsentRegion;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* What shared HTML bakes and what an unknown-country request resolves to: all categories
|
|
170
|
+
* denied under opt-in — the one default that is safe to show any visitor anywhere.
|
|
171
|
+
* Prerendered/CDN-cached markup must carry nothing region-specific, and a missing geo
|
|
172
|
+
* header means "unknown visitor", never "known non-EU visitor".
|
|
173
|
+
*
|
|
174
|
+
* @since 1.0.0-canary.6
|
|
175
|
+
*/
|
|
176
|
+
export const STRICTEST_INITIAL_CONSENT: InitialConsent = Object.freeze({
|
|
177
|
+
defaultConsent: Object.freeze(createConsentDecision([])),
|
|
178
|
+
mode: "opt-in",
|
|
179
|
+
region: "other",
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Guards an `InitialConsent` read from untrusted storage (a session cache, a cookie).
|
|
184
|
+
* Enforces the mode/region pairing rule; the one deliberate exception is
|
|
185
|
+
* {@link STRICTEST_INITIAL_CONSENT}'s own pairing — stricter than the region's usual
|
|
186
|
+
* mode, never looser.
|
|
187
|
+
*
|
|
188
|
+
* @since 1.0.0-canary.6
|
|
189
|
+
*/
|
|
190
|
+
export function isInitialConsent(value: unknown): value is InitialConsent {
|
|
191
|
+
if (!isPlainObject(value)) {
|
|
192
|
+
return false;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
const mode = value.mode;
|
|
196
|
+
const region = value.region;
|
|
197
|
+
|
|
198
|
+
if (
|
|
199
|
+
(mode !== "opt-in" && mode !== "opt-out") ||
|
|
200
|
+
!isConsentRegion(region) ||
|
|
201
|
+
!isConsentDecision(value.defaultConsent)
|
|
202
|
+
) {
|
|
203
|
+
return false;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
return (
|
|
207
|
+
mode === resolveConsentMode(region) ||
|
|
208
|
+
(mode === STRICTEST_INITIAL_CONSENT.mode && region === STRICTEST_INITIAL_CONSENT.region)
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Vietnam's PDPL and GDPR both expect a record of *when* and *under what policy* consent
|
|
106
214
|
* was given, not just per-category flags — `policyVersion` lets a later policy change
|
|
107
215
|
* invalidate stale consent.
|
|
108
216
|
*
|
|
@@ -130,3 +238,49 @@ export interface ConsentStorage {
|
|
|
130
238
|
*/
|
|
131
239
|
subscribe: (listener: () => void) => () => void;
|
|
132
240
|
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* The stored decision if one exists under the current `policyVersion`, normalized to drop
|
|
244
|
+
* any tampered extra keys — `undefined` if there is none yet, the record is malformed, or
|
|
245
|
+
* it was recorded under a superseded policy version.
|
|
246
|
+
*
|
|
247
|
+
* @since 1.0.0-canary.6
|
|
248
|
+
*/
|
|
249
|
+
export function readStoredDecision(storage: ConsentStorage, policyVersion: string): ConsentDecision | undefined {
|
|
250
|
+
const record = storage.load();
|
|
251
|
+
|
|
252
|
+
if (record?.policyVersion !== policyVersion || !isConsentDecision(record.decision)) {
|
|
253
|
+
return undefined;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
return normalizeConsentDecision(record.decision);
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* @since 1.0.0-canary.6
|
|
261
|
+
*/
|
|
262
|
+
export interface ResolveEffectiveConsentOptions {
|
|
263
|
+
/** A "do not sell or share" opt-out — forces `ads` denied under opt-out regions. */
|
|
264
|
+
hasGlobalPrivacyControlSignal: boolean;
|
|
265
|
+
mode: ConsentMode;
|
|
266
|
+
policyVersion: string;
|
|
267
|
+
requestedCategories: ReadonlyArray<ConsentCategory>;
|
|
268
|
+
storage: ConsentStorage;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* The consent a tracker should honor right now: the stored decision if one exists, else
|
|
273
|
+
* the region default — the same rule `useConsent` applies to its `effectiveConsent`, so a
|
|
274
|
+
* non-React gate (e.g. a tracker's `isAnalyticsAllowed` option) doesn't have to reimplement
|
|
275
|
+
* "read storage, validate the policy version, fall back to `resolveDefaultConsent`" itself.
|
|
276
|
+
*
|
|
277
|
+
* @since 1.0.0-canary.6
|
|
278
|
+
*/
|
|
279
|
+
export function resolveEffectiveConsent(options: ResolveEffectiveConsentOptions): ConsentDecision {
|
|
280
|
+
const { hasGlobalPrivacyControlSignal, mode, policyVersion, requestedCategories, storage } = options;
|
|
281
|
+
|
|
282
|
+
return (
|
|
283
|
+
readStoredDecision(storage, policyVersion) ??
|
|
284
|
+
resolveDefaultConsent({ hasGlobalPrivacyControlSignal, mode, requestedCategories })
|
|
285
|
+
);
|
|
286
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Default lifetime shared by the anonymous-id and consent cookies — one year.
|
|
3
|
+
*
|
|
4
|
+
* @since 1.0.0-canary.6
|
|
5
|
+
*/
|
|
6
|
+
export const ONE_YEAR_IN_SECONDS = 60 * 60 * 24 * 365;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* The value of `cookieName` inside a cookie string — a request `Cookie` header or
|
|
10
|
+
* `document.cookie`, which share the `name=value; name2=value2` wire format — or
|
|
11
|
+
* `undefined` when absent. The name must match exactly; a longer prefix sibling is ignored.
|
|
12
|
+
*
|
|
13
|
+
* @since 1.0.0-canary.6
|
|
14
|
+
*/
|
|
15
|
+
export function readCookieValue(cookieString: string | null | undefined, cookieName: string): string | undefined {
|
|
16
|
+
if (!cookieString) {
|
|
17
|
+
return undefined;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
for (const part of cookieString.split(";")) {
|
|
21
|
+
const separatorIndex = part.indexOf("=");
|
|
22
|
+
|
|
23
|
+
if (separatorIndex !== -1 && part.slice(0, separatorIndex).trim() === cookieName) {
|
|
24
|
+
return part.slice(separatorIndex + 1).trim();
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
return undefined;
|
|
29
|
+
}
|
package/src/core/destination.ts
CHANGED
|
@@ -1,20 +1,22 @@
|
|
|
1
1
|
import type { TrackedEvent } from "#/core/tracked-event";
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* Fan-out target for tracked events
|
|
5
|
-
*
|
|
4
|
+
* Fan-out target for tracked events. The tracker depends only on this interface, never
|
|
5
|
+
* on a specific provider SDK — destinations own their transport (gtag.js and Vercel both
|
|
6
|
+
* queue and batch in-page), so `send` is fire-and-forget at track time.
|
|
6
7
|
*
|
|
7
8
|
* @since 0.5.0-canary.4
|
|
8
9
|
*/
|
|
9
10
|
export interface Destination {
|
|
10
11
|
/**
|
|
11
|
-
* "
|
|
12
|
-
*
|
|
13
|
-
*
|
|
12
|
+
* "exempt" keeps this destination receiving events while the tracker's analytics gate
|
|
13
|
+
* is closed — only for cookieless, identifier-free sinks: gated envelopes carry no
|
|
14
|
+
* `anonymousId`, and nothing is persisted.
|
|
14
15
|
*
|
|
15
|
-
* @defaultValue "
|
|
16
|
+
* @defaultValue "required"
|
|
16
17
|
*/
|
|
17
|
-
|
|
18
|
+
consentRequirement?: "exempt" | "required" | undefined;
|
|
18
19
|
name: string;
|
|
19
|
-
|
|
20
|
+
/** Must always return a `Promise` — mark `send` `async` even if the body has no `await`. */
|
|
21
|
+
send: (event: TrackedEvent) => Promise<void>;
|
|
20
22
|
}
|
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { StandardSchemaV1 } from "@standard-schema/spec";
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* One event's
|
|
4
|
+
* One event's schema. Any Standard Schema library works (zod, zod/mini, valibot, ...) —
|
|
5
|
+
* the client bundle only pays for the one the app already ships.
|
|
5
6
|
*
|
|
6
7
|
* @since 0.5.0-canary.4
|
|
7
8
|
*/
|
|
8
|
-
export interface EventDefinition<Schema extends
|
|
9
|
-
owner: "client" | "server";
|
|
9
|
+
export interface EventDefinition<Schema extends StandardSchemaV1 = StandardSchemaV1> {
|
|
10
10
|
schema: Schema;
|
|
11
11
|
}
|
|
12
12
|
|
|
@@ -18,17 +18,6 @@ export interface EventDefinition<Schema extends z.ZodType = z.ZodType> {
|
|
|
18
18
|
*/
|
|
19
19
|
export type EventCatalog = Record<string, EventDefinition>;
|
|
20
20
|
|
|
21
|
-
/**
|
|
22
|
-
* Filters a catalog down to the events a given owner may fire. Client and server
|
|
23
|
-
* trackers are built from this, so calling a server-owned event from client code
|
|
24
|
-
* (or vice versa) is a compile-time error, not a runtime surprise.
|
|
25
|
-
*
|
|
26
|
-
* @since 0.5.0-canary.4
|
|
27
|
-
*/
|
|
28
|
-
export type EventsOf<Catalog extends EventCatalog, Owner extends "client" | "server"> = {
|
|
29
|
-
[Key in keyof Catalog as Catalog[Key]["owner"] extends Owner ? Key : never]: Catalog[Key];
|
|
30
|
-
};
|
|
31
|
-
|
|
32
21
|
/**
|
|
33
22
|
* Identity helper for declaring a catalog with inference — nicer call-site than
|
|
34
23
|
* `satisfies EventCatalog` when the catalog is assembled across multiple files.
|
|
@@ -38,3 +27,27 @@ export type EventsOf<Catalog extends EventCatalog, Owner extends "client" | "ser
|
|
|
38
27
|
export function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalog): Catalog {
|
|
39
28
|
return catalog;
|
|
40
29
|
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Validates event properties against the catalog schema and throws on mismatch. The
|
|
33
|
+
* validated (possibly transformed) value is deliberately discarded — the tracker always
|
|
34
|
+
* sends the caller's original properties, so a schema transform can never desync callers.
|
|
35
|
+
*
|
|
36
|
+
* @throws Error when validation reports issues, or when the schema validates asynchronously —
|
|
37
|
+
* tracking sits on synchronous call paths, so async schemas are unsupported by design.
|
|
38
|
+
*
|
|
39
|
+
* @since 1.0.0-canary.6
|
|
40
|
+
*/
|
|
41
|
+
export function assertValidEventProperties(schema: StandardSchemaV1, eventName: string, properties: unknown): void {
|
|
42
|
+
const result = schema["~standard"].validate(properties);
|
|
43
|
+
|
|
44
|
+
if (result instanceof Promise) {
|
|
45
|
+
throw new TypeError(`Event "${eventName}" uses an async schema — event properties must validate synchronously`);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
if (result.issues) {
|
|
49
|
+
const detail = result.issues.map((issue) => issue.message).join("; ");
|
|
50
|
+
|
|
51
|
+
throw new Error(`Invalid properties for event "${eventName}": ${detail}`);
|
|
52
|
+
}
|
|
53
|
+
}
|
package/src/core/event-id.ts
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* from the request instead so retries of the same request don't double-count.
|
|
2
|
+
* Stamped on every envelope at track time — destinations that dedupe can key on it.
|
|
4
3
|
*
|
|
5
4
|
* @since 0.5.0-canary.4
|
|
6
5
|
*/
|
package/src/core/index.ts
CHANGED
|
@@ -5,20 +5,36 @@ export type {
|
|
|
5
5
|
ConsentRecord,
|
|
6
6
|
ConsentRegion,
|
|
7
7
|
ConsentStorage,
|
|
8
|
+
InitialConsent,
|
|
9
|
+
ResolveDefaultConsentOptions,
|
|
10
|
+
ResolveEffectiveConsentOptions,
|
|
8
11
|
} from "#/core/consent";
|
|
9
12
|
export {
|
|
10
13
|
CONSENT_CATEGORIES,
|
|
14
|
+
CONSENT_REGIONS,
|
|
11
15
|
createConsentDecision,
|
|
12
16
|
isConsentDecision,
|
|
17
|
+
isConsentRecord,
|
|
18
|
+
isConsentRegion,
|
|
19
|
+
isInitialConsent,
|
|
20
|
+
normalizeConsentDecision,
|
|
21
|
+
readStoredDecision,
|
|
13
22
|
resolveConsentMode,
|
|
14
23
|
resolveDefaultConsent,
|
|
24
|
+
resolveEffectiveConsent,
|
|
25
|
+
STRICTEST_INITIAL_CONSENT,
|
|
15
26
|
} from "#/core/consent";
|
|
16
27
|
|
|
28
|
+
export type { ConsentConfig } from "#/core/consent-config";
|
|
29
|
+
export { defineConsentConfig } from "#/core/consent-config";
|
|
30
|
+
|
|
31
|
+
export { readCookieValue } from "#/core/cookie";
|
|
32
|
+
|
|
17
33
|
export type { Destination } from "#/core/destination";
|
|
18
34
|
|
|
19
|
-
export type { EventCatalog, EventDefinition
|
|
20
|
-
export { defineEventCatalog } from "#/core/event-catalog";
|
|
35
|
+
export type { EventCatalog, EventDefinition } from "#/core/event-catalog";
|
|
36
|
+
export { assertValidEventProperties, defineEventCatalog } from "#/core/event-catalog";
|
|
21
37
|
|
|
22
38
|
export { generateEventId } from "#/core/event-id";
|
|
23
39
|
|
|
24
|
-
export type { TrackedEvent } from "#/core/tracked-event";
|
|
40
|
+
export type { TrackedEvent, TrackedEventBase, TrackEvent } from "#/core/tracked-event";
|
|
@@ -1,14 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Fields shared by every envelope the tracker builds.
|
|
3
3
|
*
|
|
4
|
-
* @since 0.
|
|
4
|
+
* @since 1.0.0-canary.6
|
|
5
5
|
*/
|
|
6
|
-
export interface
|
|
6
|
+
export interface TrackedEventBase {
|
|
7
7
|
anonymousId: string;
|
|
8
8
|
eventId: string;
|
|
9
|
-
name: string;
|
|
10
|
-
owner: "client" | "server";
|
|
11
|
-
props: Record<string, unknown>;
|
|
12
9
|
timestamp: number;
|
|
13
|
-
userId?: string | undefined;
|
|
14
10
|
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A catalog-defined event envelope, as handed to destinations.
|
|
14
|
+
*
|
|
15
|
+
* @since 1.0.0-canary.6
|
|
16
|
+
*/
|
|
17
|
+
export interface TrackEvent extends TrackedEventBase {
|
|
18
|
+
name: string;
|
|
19
|
+
properties: Record<string, unknown>;
|
|
20
|
+
type: "track";
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The envelope destinations receive. `type` stays a discriminant so a future kind is an
|
|
25
|
+
* additive union member, not a wire-format break.
|
|
26
|
+
*
|
|
27
|
+
* @since 0.5.0-canary.4
|
|
28
|
+
*/
|
|
29
|
+
export type TrackedEvent = TrackEvent;
|