@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,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 };
|
package/dist/server/index.d.mts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
|
|
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 };
|
package/dist/server/index.mjs
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { resolveRegion, resolveRegionFromCountryCode } from "./region.mjs";
|
|
3
|
-
|
|
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 };
|
package/dist/server/region.d.mts
CHANGED
|
@@ -2,9 +2,26 @@ import { ConsentRegion } from "../core/consent.mjs";
|
|
|
2
2
|
|
|
3
3
|
//#region src/server/region.d.ts
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
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 };
|
package/dist/server/region.mjs
CHANGED
|
@@ -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
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
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.
|
|
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
|
-
"./
|
|
65
|
-
"source": "./src/
|
|
66
|
-
"types": "./dist/
|
|
67
|
-
"import": "./dist/
|
|
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
|
-
"./
|
|
120
|
-
"source": "./src/
|
|
121
|
-
"types": "./dist/
|
|
122
|
-
"import": "./dist/
|
|
74
|
+
"./react": {
|
|
75
|
+
"source": "./src/react/index.ts",
|
|
76
|
+
"types": "./dist/react/index.d.mts",
|
|
77
|
+
"import": "./dist/react/index.mjs"
|
|
123
78
|
},
|
|
124
|
-
"./
|
|
125
|
-
"source": "./src/
|
|
126
|
-
"types": "./dist/
|
|
127
|
-
"import": "./dist/
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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
|
+
}
|