@businessdash/sdk 0.9.60 → 0.9.80

package/src/consent-core/index.ts

@@ -0,0 +1,213 @@
+/**
+ * `@businessdash/sdk/consent` — tracking consent, per org.
+ *
+ * ## The rule that shapes everything here
+ *
+ * Consent is given to a **controller**, and each org is a separate controller.
+ * It does not travel between them in either direction:
+ *
+ * - A visitor who refuses at org 2 has said nothing to org 1. Org 1 keeps
+ *   collecting.
+ * - A visitor who consents at org 1 has NOT consented at org 2. Org 2 may not
+ *   start collecting on the strength of it.
+ *
+ * The second half is the one that gets skipped, and it is the one with legal
+ * teeth: acting on another controller's consent is processing without a lawful
+ * basis.
+ *
+ * That is why the visitor key lives in a **first-party cookie on the org's own
+ * domain**, and why every call carries the org's own API key. Two sites cannot
+ * see each other's cookies, so the isolation is enforced by the browser rather
+ * than by us remembering to scope a query.
+ *
+ * ## Gate analytics on it
+ *
+ * ```ts
+ * const consent = await loadConsent({ client });
+ * if (consent.allows('analytics')) {
+ *   initBiabAnalytics({ siteId, baseUrl, apiKey });
+ * }
+ * if (consent.mustAsk) showYourBanner(consent);
+ * ```
+ *
+ * `initBiabAnalytics` is deliberately NOT made to call this itself. A gate that
+ * fires implicitly is one nobody can see in review, and the decision of what
+ * happens before consent — render nothing, render a placeholder, collect
+ * essential-only — belongs to the site, not to us.
+ *
+ * @module
+ */
+
+export type ConsentCategory = "analytics" | "marketing" | "personalisation";
+
+/** Why consent resolved the way it did. Useful in an org's audit view. */
+export type ConsentReason =
+	| "browser_signal"
+	| "explicit"
+	| "stale_notice"
+	| "default_allow"
+	| "default_deny";
+
+export type ConsentState = {
+	/** Categories this org uses at all. Render one banner row per entry. */
+	categories: ConsentCategory[];
+	noticeText: string | null;
+	noticeVersion: number;
+	/** What may be used right now. */
+	allowed: ConsentCategory[];
+	/** True when the visitor has not answered and a banner should show. */
+	mustAsk: boolean;
+	reason: ConsentReason;
+	/** `allowed.includes(category)`, spelled as a question. */
+	allows(category: ConsentCategory): boolean;
+};
+
+/** The subset of the SDK client this needs. */
+export type ConsentClientLike = {
+	request(input: {
+		method?: string;
+		path: string;
+		body?: unknown;
+		headers?: Record<string, string>;
+		responseSchema: unknown;
+	}): Promise<unknown>;
+};
+
+const VISITOR_COOKIE = "biab_visitor";
+const VISITOR_HEADER = "x-biab-visitor";
+
+/**
+ * The visitor's id for THIS site, minted on first need.
+ *
+ * A first-party cookie on the org's own domain, which is what makes the
+ * per-org isolation structural: the same person visiting two orgs gets two
+ * unrelated keys, because two domains cannot read each other's cookies. There
+ * is no cross-site identifier here and deliberately no way to add one.
+ *
+ * Returns null on the server, where there is no visitor to identify.
+ */
+export function visitorKey(): string | null {
+	if (typeof document === "undefined") return null;
+
+	const found = document.cookie
+		.split(";")
+		.map((part) => part.trim())
+		.find((part) => part.startsWith(`${VISITOR_COOKIE}=`));
+	if (found) return decodeURIComponent(found.slice(VISITOR_COOKIE.length + 1));
+
+	const key =
+		typeof crypto !== "undefined" && "randomUUID" in crypto
+			? crypto.randomUUID()
+			: `v${Date.now()}${Math.floor(Math.random() * 1e9)}`;
+
+	// SameSite=Lax and no Secure flag would leak on http; Secure is set unless
+	// we are plainly on localhost, where it would stop the cookie working at all.
+	const secure = location.protocol === "https:" ? "; Secure" : "";
+	// biome-ignore lint/suspicious/noDocumentCookie: the suggested CookieStore
+	// API has no Safari or Firefox support. A consent banner has to work in
+	// every browser a visitor might arrive in — that is the entire point of it —
+	// so the universally supported API is the correct one here.
+	document.cookie = `${VISITOR_COOKIE}=${encodeURIComponent(key)}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`;
+	return key;
+}
+
+/** True when the browser is signalling a global opt-out (DNT or GPC). */
+export function browserOptOut(): boolean {
+	if (typeof navigator === "undefined") return false;
+	const nav = navigator as Navigator & {
+		doNotTrack?: string;
+		globalPrivacyControl?: boolean;
+	};
+	if (nav.globalPrivacyControl === true) return true;
+	const dnt =
+		nav.doNotTrack ??
+		(typeof window === "undefined"
+			? undefined
+			: (window as Window & { doNotTrack?: string }).doNotTrack);
+	return dnt === "1" || dnt === "yes";
+}
+
+function toState(raw: {
+	categories?: string[];
+	noticeText?: string | null;
+	noticeVersion?: number;
+	allowed?: string[];
+	mustAsk?: boolean;
+	reason?: string;
+}): ConsentState {
+	const categories = (raw.categories ?? []) as ConsentCategory[];
+	const allowed = (raw.allowed ?? []) as ConsentCategory[];
+	return {
+		categories,
+		noticeText: raw.noticeText ?? null,
+		noticeVersion: raw.noticeVersion ?? 1,
+		allowed,
+		mustAsk: raw.mustAsk ?? true,
+		reason: (raw.reason ?? "default_deny") as ConsentReason,
+		allows: (category) => allowed.includes(category),
+	};
+}
+
+/**
+ * What this visitor currently allows, at this org.
+ *
+ * On any failure this returns a **deny-everything** state rather than throwing.
+ * A consent gate that fails open collects data nobody agreed to; one that fails
+ * closed loses some analytics. Only one of those is a compliance incident.
+ */
+export async function loadConsent(options: {
+	client: ConsentClientLike;
+}): Promise<ConsentState> {
+	const key = visitorKey();
+	try {
+		const raw = (await options.client.request({
+			path: "consent",
+			...(key ? { headers: { [VISITOR_HEADER]: key } } : {}),
+			responseSchema: { parse: (v: unknown) => v },
+		})) as Parameters<typeof toState>[0];
+		return toState(raw);
+	} catch {
+		return {
+			categories: [],
+			noticeText: null,
+			noticeVersion: 1,
+			allowed: [],
+			mustAsk: false,
+			reason: "default_deny",
+			allows: () => false,
+		};
+	}
+}
+
+/**
+ * Record the visitor's answer.
+ *
+ * `granted: []` is a real answer — "asked, refused everything" — and is stored
+ * as one, so the banner does not reappear on the next page.
+ */
+export async function recordConsent(options: {
+	client: ConsentClientLike;
+	granted: ConsentCategory[];
+	noticeVersion: number;
+	source?: "banner" | "settings";
+}): Promise<{ ok: boolean }> {
+	const key = visitorKey();
+	if (!key) return { ok: false };
+
+	try {
+		await options.client.request({
+			method: "POST",
+			path: "consent",
+			body: {
+				granted: options.granted,
+				noticeVersion: options.noticeVersion,
+				source: options.source ?? "banner",
+			},
+			headers: { [VISITOR_HEADER]: key },
+			responseSchema: { parse: (v: unknown) => v },
+		});
+		return { ok: true };
+	} catch {
+		return { ok: false };
+	}
+}