Initial Commit

packages/observability/monitor/analytics-browser/src/consent/consent.md

@@ -0,0 +1,53 @@
+# `consent.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Implements the `ConsentPolicy` SPI bundled with `@suaveplan/analytics-browser`. The tracker calls `policy.isAllowed(event)` before any sampling, scrubbing, or queueing decision, so a `false` return short-circuits the entire pipeline and emits a `drop` event with reason `consent`. Two built-in policies ship with the package: `AllowAllPolicy` (default) and `DoNotTrackPolicy` (honours `navigator.doNotTrack === "1"`). Downstream consumers can implement their own policy — e.g. one that consults a stored cookie-banner preference — by implementing the interface from `@suaveplan/analytics-browser/types`.
+
+## Features
+
+- Lazy navigator lookup — both policies are constructable in SSR / Node contexts where `navigator` is undefined; the policy simply permits the event in that case.
+- Zero state — both built-ins are stateless and reentrant.
+- Strict equality on `"1"` — matches the W3C Tracking Preference Expression spec; values `"0"` or `"unspecified"` permit tracking.
+
+## Usage: Basic
+
+```ts
+import { DoNotTrackPolicy } from "@suaveplan/analytics-browser/consent";
+import { AnalyticsTracker } from "@suaveplan/analytics-browser/tracker";
+
+const tracker = new AnalyticsTracker(transport, {
+    consentPolicy: new DoNotTrackPolicy(),
+});
+tracker.track("page_loaded"); // dropped if navigator.doNotTrack === "1"
+```
+
+## Usage: Advanced
+
+```ts
+import type {
+    AnalyticsEvent,
+    ConsentPolicy,
+} from "@suaveplan/analytics-browser/types";
+
+class CookieBannerPolicy implements ConsentPolicy {
+    public constructor(private readonly read: () => "granted" | "denied") {}
+
+    public isAllowed(_event: AnalyticsEvent): boolean {
+        return this.read() === "granted";
+    }
+}
+```
+
+## API Reference
+
+- `class AllowAllPolicy implements ConsentPolicy` — `isAllowed(event) → true`.
+- `class DoNotTrackPolicy implements ConsentPolicy` — returns `false` iff `typeof navigator !== "undefined" && navigator.doNotTrack === "1"`.
+
+## Implementation Notes
+
+`DoNotTrackPolicy` reads `navigator.doNotTrack` on every call rather than caching at construction time. This is deliberate: the spec lets the user toggle the preference at runtime in some browsers (notably in private windows), and caching would freeze the decision at construction. The cost is a single property read per event — negligible compared with the JSON serialisation that follows on the happy path. Both classes pass their `event` argument with a leading underscore name to signal it is intentionally unused; lint rules permit underscore-prefixed unused parameters.