@owlmeans/consent 0.1.18-rc.8 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/consent",
-  "version": "0.1.18-rc.8",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,8 +22,8 @@
     }
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.4.0",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/bun": "^1.4.2",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.local.ts

@@ -0,0 +1,16 @@
+export const CONSENT_LINK_VERSION = 2
+
+/** A BCP 47-shaped tag: a 2–3 letter language and up to three subtags (`pl`, `pt-BR`, `zh-Hant-TW`). */
+export const LANGUAGE_TAG = /^[a-z]{2,3}(?:[-_][a-z0-9]{1,8}){0,3}$/i
+
+/** The built-in Cloudflare locator's registry alias. */
+export const CLOUDFLARE_LOCATOR_ALIAS = 'cloudflare'
+
+/** Below anything an application registers: an application's own locator always asks first. */
+export const CLOUDFLARE_LOCATOR_PRIORITY = -100
+
+/** An ISO 3166-1 alpha-2 code, upper case. */
+export const COUNTRY_CODE = /^[A-Z]{2}$/
+
+/** Clock skew tolerated on an automatic decision's timestamp, in seconds. */
+export const AUTO_SKEW = 60

package/src/consts.ts

@@ -1,4 +1,13 @@
-import type { ConsentCategory } from './types.js'
+import type { ConsentCategory, ConsentLocale, ConsentState } from './types.js'
+
+import en from './i18n/en.json' with { type: 'json' }
+import pl from './i18n/pl.json' with { type: 'json' }
+import ru from './i18n/ru.json' with { type: 'json' }
+import be from './i18n/be.json' with { type: 'json' }
+import uk from './i18n/uk.json' with { type: 'json' }
+import es from './i18n/es.json' with { type: 'json' }
+import de from './i18n/de.json' with { type: 'json' }
+import fr from './i18n/fr.json' with { type: 'json' }
 
 /**
  * Where a visitor's choice is stored.
@@ -34,45 +43,39 @@ export const CONSENT_SETUP_FLAG = 'cookieConsentSetup'
 export const CONSENT_EVENT = 'owlmeans:consent'
 
 export const CONSENT_ESSENTIAL = 'essential'
-export const CONSENT_FUNCTIONAL = 'functional'
 export const CONSENT_ANALYTICS = 'analytics'
 export const CONSENT_MARKETING = 'marketing'
 
-/**
- * The DOM event the store dispatches on `window` when a language that arrived with a link (or an
- * explicit choice made before the visitor answered the dialog) has just become storable — the
- * visitor granted functional storage — so the application can switch to it now instead of at the
- * next load. `detail: { language }`. An application that resolves its language from storage at
- * start-up (`@owlmeans/client-i18n`) listens for it.
- */
-export const CONSENT_LANGUAGE_EVENT = 'owlmeans:language'
-
-/**
- * The `window` property the inline `<head>` fragment leaves a carried language on when it may not
- * store it yet (no decision, or functional not granted): memory only, never storage. The store
- * picks it up at `init` and writes it if — and only if — the visitor later grants functional storage
- * in this page's life. Fixed for the same reason `CONSENT_SETUP_FLAG` is: two bundles, one page.
- */
-export const CONSENT_PENDING_LANGUAGE = 'cookieConsentPendingLanguage'
-
 /**
  * Where an application persists an explicit interface-language choice — `@owlmeans/client-i18n`'s
- * `owlmeans-lng`. Repeated here rather than imported: this package has no runtime dependencies, and
- * the linker's language part has to run in an inline `<head>` script, before any bundle exists.
+ * `owlmeans-lng`. The interface language is strictly necessary storage (the visitor asked for it by
+ * choosing it), so it is written whatever the cookie decision says and no category governs it.
+ * Repeated here rather than imported: this package has no runtime dependencies, and the linker's
+ * language part has to run in an inline `<head>` script, before any bundle exists.
  */
 export const CONSENT_LANGUAGE_KEY = 'owlmeans-lng'
 
-export const CONSENT_LOCALES = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'] as const
+export const CONSENT_LOCALES = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'] as const satisfies readonly ConsentLocale[]
 
-export type ConsentLocale = (typeof CONSENT_LOCALES)[number]
+/**
+ * The dialog's copy, in the box.
+ *
+ * Carried here rather than registered into an i18n framework because one of the three consumers is
+ * an Astro site with React islands and no OwlMeans i18n at all — and a consent dialog that renders
+ * raw keys is worse than no dialog. An application that HAS translations passes `translate` and
+ * overrides every one of these.
+ */
+export const DEFAULT_CONSENT_MESSAGES: Record<ConsentLocale, Record<string, string>> = {
+  en, pl, ru, be, uk, es, de, fr,
+}
 
 /**
  * The categories every OwlMeans surface starts with.
  *
  * What owlmeans.com already asked (analytics, marketing) plus the essential row, which the original
  * widget left implicit — making it explicit is what lets a flow require an acknowledgement before
- * it sets a session cookie, and what tells a visitor what is being stored regardless — plus
- * functional, the visitor's own remembered preferences.
+ * it sets a session cookie, and what tells a visitor what is being stored regardless: the consent
+ * record itself and the interface language the visitor picked.
  */
 export const DEFAULT_CONSENT_CATEGORIES: ConsentCategory[] = [
   {
@@ -81,15 +84,6 @@ export const DEFAULT_CONSENT_CATEGORIES: ConsentCategory[] = [
     globalVar: 'owlConsentEssential',
     signals: ['security_storage', 'functionality_storage'],
   },
-  // A preference the visitor set — today the interface language — remembered on their device. Not
-  // essential (nothing breaks without it) and not tracking, so it drives NO Consent Mode signal:
-  // a signal would make `trackingGranted` count it, and a visitor who only allowed their language
-  // to be remembered would load the tag container.
-  {
-    key: CONSENT_FUNCTIONAL,
-    labelKey: 'functional', descriptionKey: 'functionalDesc',
-    globalVar: 'owlConsentFunctional',
-  },
   {
     key: CONSENT_ANALYTICS,
     labelKey: 'analytics', descriptionKey: 'analyticsDesc',
@@ -119,3 +113,101 @@ export const CONSENT_SIGNAL_DEFAULTS: Record<string, 'granted' | 'denied'> = {
   personalization_storage: 'denied',
   security_storage: 'granted',
 }
+
+/** The URL parameter a decorated link carries the decision in, absent an override. */
+export const CONSENT_LINK_PARAM = 'owlcc'
+
+/** How old a decorated link's timestamp may be and still be trusted, in seconds, absent an override. */
+export const CONSENT_LINK_MAX_AGE = 300
+
+/** Clock skew allowed the OTHER way — a timestamp up to this far in the future is still trusted. */
+export const CONSENT_LINK_SKEW = 60
+
+/**
+ * Where prior consent for non-essential cookies is the law: the EU and EEA (ePrivacy Art. 5(3) with
+ * the GDPR), including the parts of member states that carry an ISO code of their own — Åland and
+ * the French outermost regions (French Guiana, Guadeloupe, Martinique, Réunion, Mayotte,
+ * Saint-Martin). The Canary Islands, Azores, Madeira, Ceuta and Melilla report their state's code.
+ * Greece is `GR`, as Cloudflare and every ISO feed spell it.
+ */
+export const CONSENT_COUNTRIES_GDPR: readonly string[] = Object.freeze([
+  'AT', 'BE', 'BG', 'CY', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR', 'GR', 'HR', 'HU',
+  'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL', 'PT', 'RO', 'SE', 'SI', 'SK',
+  'AX', 'GF', 'GP', 'MQ', 'RE', 'YT', 'MF',
+  'IS', 'LI', 'NO',
+])
+
+/**
+ * Jurisdictions outside the EEA whose rule for cookies is the same prior opt-in, by statute or by
+ * the regulator's guidance (2026):
+ *
+ * - the United Kingdom (PECR — the 2025 Data (Use and Access) Act exempts some first-party
+ *   analytics, advertising still needs consent), the Crown Dependencies and Gibraltar;
+ * - Switzerland (FDPIC guidelines, 2025: explicit consent for tracking and profiling);
+ * - Andorra, Monaco, San Marino and the Vatican; Türkiye (KVKK cookie guide); Serbia (ZZPL and the
+ *   electronic-communications law); Albania, Bosnia and Herzegovina, Montenegro, North Macedonia,
+ *   Kosovo, Moldova, Georgia and Ukraine (GDPR-modelled laws);
+ * - territories under a member state's regulator but outside the EU: the Faroe Islands and
+ *   Greenland (Denmark); Saint-Barthélemy, Saint-Pierre-et-Miquelon, New Caledonia, French
+ *   Polynesia, Wallis and Futuna (France); the Caribbean Netherlands.
+ */
+export const CONSENT_COUNTRIES_ALIGNED: readonly string[] = Object.freeze([
+  'GB', 'GG', 'JE', 'IM', 'GI',
+  'CH',
+  'AD', 'MC', 'SM', 'VA', 'TR', 'RS', 'AL', 'BA', 'ME', 'MK', 'XK', 'MD', 'GE', 'UA',
+  'FO', 'GL', 'BL', 'PM', 'NC', 'PF', 'WF', 'BQ',
+])
+
+/**
+ * Prior opt-in regimes elsewhere (2026): Brazil (LGPD, ANPD cookie guide), Canada (Québec's Law 25
+ * — the country is the finest grain a CDN reports, so all of Canada), China (PIPL), South Korea
+ * (PIPA), Nigeria (NDPA), Saudi Arabia (PDPL), Thailand (PDPA), Vietnam (PDPL 2026).
+ *
+ * Deliberately absent: India (the DPDP Act's consent rules apply from mid-2027 — add `IN` then),
+ * and the notice-or-opt-out regimes — the United States, Japan, Australia, Singapore. South
+ * Africa's POPIA is read both ways by the guides and is left out until its regulator says more.
+ */
+export const CONSENT_COUNTRIES_OPT_IN: readonly string[] = Object.freeze([
+  'BR', 'CA', 'CN', 'KR', 'NG', 'SA', 'TH', 'VN',
+])
+
+/**
+ * Every country where a located visitor is ASKED (`ConsentGeoOptions.countries` replaces it). A
+ * visitor located anywhere else gets an automatic decision; one who cannot be located is asked.
+ */
+export const CONSENT_REQUIRED_COUNTRIES: readonly string[] = Object.freeze([
+  ...CONSENT_COUNTRIES_GDPR, ...CONSENT_COUNTRIES_ALIGNED, ...CONSENT_COUNTRIES_OPT_IN,
+])
+
+/**
+ * Codes that name no country: Cloudflare's `XX` (no data) and `T1` (Tor), the retired MaxMind
+ * pseudo-codes (`A1` anonymous proxy, `A2` satellite, `O1` other) and the continent buckets some
+ * feeds fall back to (`EU`, `AP`), plus `ZZ` (unknown). A visitor reported with one is asked.
+ */
+export const CONSENT_GEO_UNKNOWN: readonly string[] = Object.freeze([
+  'XX', 'T1', 'A1', 'A2', 'O1', 'EU', 'AP', 'ZZ',
+])
+
+/** Cloudflare's trace endpoint — served by the edge on every proxied host, `loc=` among its lines. */
+export const CONSENT_TRACE_PATH = '/cdn-cgi/trace'
+
+/** How long locating may take before the visitor is asked anyway, in ms. */
+export const CONSENT_GEO_TIMEOUT = 2500
+
+/**
+ * How long an automatic decision is trusted, in seconds. Older, it counts as undecided — in the
+ * head scripts as much as in the store — until the visitor is located again, so a grant derived in
+ * one country never reaches a page opened an hour later in another.
+ */
+export const CONSENT_AUTO_MAX_AGE = 3600
+
+/** The state of a store nobody has initialised — and the only server-side snapshot. */
+export const CONSENT_IDLE_STATE: ConsentState = Object.freeze({
+  record: null, open: false, reason: null, locating: null,
+})
+
+/**
+ * The attribute on `<html>` that mirrors the consent phase: `locating`, `open`, `decided` or `idle`.
+ * Absent until the store first runs. A test waits on it, and a stylesheet may key on it.
+ */
+export const CONSENT_STATE_ATTRIBUTE = 'data-consent'

package/src/geo/types.ts

@@ -0,0 +1,49 @@
+import type { ConsentGeoPlugin, ConsentOptions, ConsentRecord } from '../types.js'
+
+/** What locating the visitor decided: ask them, or decide for them automatically. */
+export type ConsentGeoVerdict = 'ask' | 'auto'
+
+/** Whether a record is an automatic decision, and whether it is still trusted. */
+export type ConsentAutoState = 'fresh' | 'stale'
+
+/**
+ * Asking only where the law requires it: locating the visitor, the decision that follows, and the
+ * automatic record written where nobody needs to be asked.
+ */
+export interface ConsentGeoHelper {
+  /** Whether `opts.geo` turns the gate on AND something can answer — the Cloudflare locator or a plugin. */
+  enabled: (opts?: ConsentOptions) => boolean
+  /** Every `key=value` line of a Cloudflare trace body. Never throws; anything else parses to `{}`. */
+  parseTrace: (text: string) => Record<string, string>
+  /**
+   * The built-in locator: a same-origin GET of the trace endpoint, cookies left out, never cached.
+   * Rejects when `opts.geo.cloudflare` is off, the request fails or answers non-2xx, or the body is
+   * not a trace (an SPA serving its `index.html` for every path answers 200 here).
+   */
+  cloudflareLocator: () => ConsentGeoPlugin
+  /**
+   * Whether a visitor located in `country` must be asked: yes inside `opts.geo.countries`
+   * (`CONSENT_REQUIRED_COUNTRIES`), and yes for anything that names no country.
+   */
+  requiresConsent: (country: string | null, opts?: ConsentOptions) => boolean
+  /**
+   * Locate and decide, bounded by `opts.geo.timeout`. Never rejects: a visitor nobody could locate
+   * resolves `'ask'`.
+   */
+  decide: (opts: ConsentOptions) => Promise<ConsentGeoVerdict>
+  /**
+   * Whether the browser sends Global Privacy Control — a legally binding opt-out in several US
+   * states, so an automatic decision honours it.
+   */
+  privacySignal: () => boolean
+  /**
+   * The automatic decision for a visitor nobody needs to ask: every category on — or, under Global
+   * Privacy Control, only the required ones — stamped `auto` with the current time.
+   */
+  automaticRecord: (opts?: ConsentOptions) => ConsentRecord
+  /**
+   * `fresh` for an automatic decision younger than `CONSENT_AUTO_MAX_AGE`, `stale` for an older one
+   * (or one stamped in the future beyond the skew), `null` for an explicit record or none.
+   */
+  autoState: (record: ConsentRecord | null) => ConsentAutoState | null
+}

package/src/geo.ts

@@ -0,0 +1,122 @@
+import {
+  CONSENT_AUTO_MAX_AGE, CONSENT_GEO_TIMEOUT, CONSENT_GEO_UNKNOWN, CONSENT_REQUIRED_COUNTRIES,
+  CONSENT_SCHEMA_VERSION, CONSENT_TRACE_PATH, DEFAULT_CONSENT_CATEGORIES,
+} from './consts.js'
+import {
+  AUTO_SKEW, CLOUDFLARE_LOCATOR_ALIAS, CLOUDFLARE_LOCATOR_PRIORITY, COUNTRY_CODE,
+} from './consts.local.js'
+import { consentPluginHelper } from './plugins.js'
+import type { ConsentGeoPlugin, ConsentOptions, ConsentRecord } from './types.js'
+import type { ConsentNavigator } from './types.local.js'
+import type { ConsentAutoState, ConsentGeoHelper, ConsentGeoVerdict } from './geo/types.js'
+
+export const createConsentGeoHelper = (): ConsentGeoHelper => {
+  const now = (): number => Math.floor(Date.now() / 1000)
+
+  const enabled = (opts?: ConsentOptions): boolean => {
+    const geo = opts?.geo
+    if (geo == null) {
+      return false
+    }
+
+    return (geo.cloudflare != null && geo.cloudflare !== false)
+      || consentPluginHelper.consentPlugins().some(plugin => plugin.locate != null
+        && plugin.alias !== CLOUDFLARE_LOCATOR_ALIAS)
+  }
+
+  const parseTrace = (text: string): Record<string, string> => {
+    const trace: Record<string, string> = {}
+    for (const line of text.split(/\r?\n/)) {
+      const at = line.indexOf('=')
+      if (at > 0 && /^[a-z_]+$/.test(line.slice(0, at))) {
+        trace[line.slice(0, at)] = line.slice(at + 1).trim()
+      }
+    }
+
+    return trace
+  }
+
+  const cloudflareLocator = (): ConsentGeoPlugin => ({
+    alias: CLOUDFLARE_LOCATOR_ALIAS,
+    priority: CLOUDFLARE_LOCATOR_PRIORITY,
+    locate: async opts => {
+      const setting = opts.geo?.cloudflare
+      if (setting == null || setting === false) {
+        throw new Error('consent:geo:cloudflare:off')
+      }
+      if (typeof fetch !== 'function') {
+        throw new Error('consent:geo:cloudflare:no-fetch')
+      }
+      const path = typeof setting === 'object' ? setting.path ?? CONSENT_TRACE_PATH : CONSENT_TRACE_PATH
+      const response = await fetch(path, { credentials: 'omit', cache: 'no-store' })
+      if (!response.ok) {
+        throw new Error(`consent:geo:cloudflare:status:${response.status}`)
+      }
+      const trace = parseTrace(await response.text())
+      // Every trace names the edge that answered; an HTML fallback page names nothing at all.
+      if (trace.loc == null || (trace.colo == null && trace.fl == null)) {
+        throw new Error('consent:geo:cloudflare:not-a-trace')
+      }
+
+      return { country: trace.loc }
+    },
+  })
+
+  const requiresConsent = (country: string | null, opts?: ConsentOptions): boolean => {
+    const code = country?.trim().toUpperCase() ?? ''
+    if (!COUNTRY_CODE.test(code) || CONSENT_GEO_UNKNOWN.includes(code)) {
+      return true
+    }
+
+    return (opts?.geo?.countries ?? CONSENT_REQUIRED_COUNTRIES)
+      .some(candidate => candidate.toUpperCase() === code)
+  }
+
+  const decide = async (opts: ConsentOptions): Promise<ConsentGeoVerdict> => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error('consent:geo:timeout')), opts.geo?.timeout ?? CONSENT_GEO_TIMEOUT
+      )
+    })
+    try {
+      const location = await Promise.race([consentPluginHelper.locateConsent(opts), timeout])
+
+      return requiresConsent(location.country, opts) ? 'ask' : 'auto'
+    } catch {
+      return 'ask'
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  const privacySignal = (): boolean =>
+    typeof navigator !== 'undefined'
+      && (navigator as unknown as ConsentNavigator).globalPrivacyControl === true
+
+  const automaticRecord = (opts?: ConsentOptions): ConsentRecord => {
+    const optOut = privacySignal()
+    const record: ConsentRecord = { v: CONSENT_SCHEMA_VERSION, auto: now() }
+    for (const category of opts?.categories ?? DEFAULT_CONSENT_CATEGORIES) {
+      record[category.key] = category.required === true || !optOut
+    }
+
+    return record
+  }
+
+  const autoState = (record: ConsentRecord | null): ConsentAutoState | null => {
+    if (record == null || typeof record.auto !== 'number') {
+      return null
+    }
+    const age = now() - record.auto
+
+    return age <= CONSENT_AUTO_MAX_AGE && age >= -AUTO_SKEW ? 'fresh' : 'stale'
+  }
+
+  return {
+    enabled, parseTrace, cloudflareLocator, requiresConsent, decide, privacySignal, automaticRecord,
+    autoState,
+  }
+}
+
+export const consentGeoHelper = createConsentGeoHelper()

package/src/gtobserver/types.ts

@@ -0,0 +1,73 @@
+import type { ConsentCategory, ConsentOptions, ConsentRecord } from '../types.js'
+
+/** Google Consent Mode: the queue, the signals a decision implies, and the inline scripts. */
+export interface ConsentModeHelper {
+  /**
+   * Push onto the tag-manager queue in the shape Google's own snippet uses.
+   *
+   * `arguments`, not an array literal. Both work with today's Consent API, but `arguments` is what
+   * `gtag.js` itself emits, and a page that carries both this and Google's snippet should not have
+   * two shapes in one queue.
+   */
+  gtagConsent: (..._args: unknown[]) => void
+  /** Every signal the configured categories drive, at its pre-consent value. */
+  consentDefaults: (categories?: ConsentCategory[]) => Record<string, 'granted' | 'denied'>
+  /** Every signal, at the value this record implies. */
+  consentUpdate: (record: ConsentRecord, categories?: ConsentCategory[]) => Record<string, 'granted' | 'denied'>
+  /**
+   * Declare what is denied, before any tag can act.
+   *
+   * Idempotent through a window flag, because the page may carry this call twice — once inline in
+   * the document head, once from whatever bundle mounts the dialog — and a second `default` after a
+   * tag has loaded is worse than none: it can widen what was already narrowed.
+   */
+  pushConsentDefaults: (opts?: ConsentOptions) => void
+  /**
+   * Apply a decision: globals first, then the signal update, then any per-category events.
+   *
+   * The order is load-bearing. A tag that fires on the update event reads the globals in the same
+   * turn, so writing them afterwards would let the first firing see the previous answer.
+   */
+  applyConsent: (record: ConsentRecord, opts?: ConsentOptions) => void
+  /**
+   * Whether a stored decision grants tracking at all — a signal-bearing category, not merely the
+   * required essential one.
+   *
+   * "Signal-bearing" is what a required category can never be: it exists to gate whether a LOADER
+   * runs, and a required category is disclosure, not a question — everyone gets it. Only a category
+   * that both is optional and drives at least one Consent Mode signal counts, which is exactly what
+   * `googleTagHeadScript`'s `'basic'` mode gates a Google tag behind.
+   */
+  trackingGranted: (record: ConsentRecord | null, categories?: ConsentCategory[]) => boolean
+  /**
+   * The inline script a document stamps ABOVE its tag-manager snippet.
+   *
+   * It exists because the defaults have to be on the queue before `gtm.js` loads, and a React bundle
+   * cannot be: by the time an island mounts, the container has been running for hundreds of
+   * milliseconds and has already decided what it may do. Emitting it from the HTML is the only
+   * ordering that holds — and it reads the stored record too, so a returning visitor's tags are not
+   * denied for the first paint of every page.
+   */
+  consentBootstrapScript: (opts?: ConsentOptions) => string
+  /**
+   * Withhold a loader until a stored or later decision grants tracking.
+   *
+   * The counterpart to `consentBootstrapScript` for the `'basic'` gated loading mode
+   * (`@owlmeans/web-gtm`'s `GOOGLE_TAG_DEFAULT_MODE`): where the bootstrap always declares Consent
+   * Mode's defaults so a tag may load cookieless, this withholds the tag itself — the loader string
+   * is only ever reached once `trackingGranted` is true, either because a returning visitor's stored
+   * record already says so, or because `applyConsent` later dispatches {@link CONSENT_EVENT} with
+   * one that does. The listener removes itself on the first passing event, so the loader — which
+   * marks its own element and refuses to run twice — is asked to run at most once from here.
+   *
+   * `loaderExpr` is a complete statement or expression that runs the loader when reached — the
+   * self-invoking IIFE string `googleTagHeadScript`'s `gtagScript`/`gtmContainerScript` already
+   * produce, embedded here verbatim rather than called. It is placed inline exactly as
+   * `consentBootstrapScript`'s own output is: dynamic values (the storage key, the category shape,
+   * the event name) are JSON-encoded so nothing configured can break out of a string literal, and
+   * escaping the RESULT for HTML (`</script`, `<!--`) is left to whoever composes the final inline
+   * script — the same discipline `consentBootstrapScript` follows, and `googleTagHeadScript` already
+   * applies to the whole script it stamps.
+   */
+  consentGateScript: (loaderExpr: string, opts?: ConsentOptions & { categories?: ConsentCategory[] }) => string
+}

package/src/gtobserver.ts

@@ -0,0 +1,182 @@
+import {
+  CONSENT_AUTO_MAX_AGE, CONSENT_EVENT, CONSENT_KEY, CONSENT_SETUP_FLAG, CONSENT_SIGNAL_DEFAULTS,
+  DEFAULT_CONSENT_CATEGORIES,
+} from './consts.js'
+import { AUTO_SKEW } from './consts.local.js'
+import { consentLinkHelper } from './linker.js'
+import type { ConsentCategory, ConsentOptions, ConsentRecord } from './types.js'
+import type { ConsentWindow } from './types.local.js'
+import type { ConsentModeHelper } from './gtobserver/types.js'
+
+export const createConsentModeHelper = (): ConsentModeHelper => {
+  const global = (): ConsentWindow | null =>
+    typeof window !== 'undefined' ? window as unknown as ConsentWindow : null
+
+  // A `function`, not an arrow: what goes on the queue is its own `arguments` object.
+  function gtagConsent(..._args: unknown[]): void {
+    const win = global()
+    if (win == null) {
+      return
+    }
+    win.dataLayer = win.dataLayer ?? []
+    // `arguments`, not `_args`. The rest parameter is only here to type the call sites; what goes on
+    // the queue must be the arguments object itself.
+    // eslint-disable-next-line prefer-rest-params
+    win.dataLayer.push(arguments)
+  }
+
+  const categoriesOf = (opts?: ConsentOptions): ConsentCategory[] =>
+    opts?.categories ?? DEFAULT_CONSENT_CATEGORIES
+
+  /**
+   * Inline: treat an automatic decision past `CONSENT_AUTO_MAX_AGE` as no decision at all — run
+   * `onStale` on the parsed record `r`. The store holds such a record back until the visitor is
+   * located again, and the head scripts must not apply what the store will not.
+   */
+  const staleAutoScript = (onStale: string): string =>
+    `if(r&&typeof r.auto==='number'){var a=Math.floor(Date.now()/1000)-r.auto;` +
+    `if(a>${CONSENT_AUTO_MAX_AGE}||a<-${AUTO_SKEW}){${onStale}}}`
+
+  const consentDefaults = (
+    categories?: ConsentCategory[]
+  ): Record<string, 'granted' | 'denied'> => {
+    const used = new Set((categories ?? DEFAULT_CONSENT_CATEGORIES)
+      .flatMap(category => category.signals ?? []))
+
+    return Object.fromEntries(Object.entries(CONSENT_SIGNAL_DEFAULTS)
+      .filter(([signal]) => used.has(signal as never)))
+  }
+
+  const consentUpdate = (
+    record: ConsentRecord, categories?: ConsentCategory[]
+  ): Record<string, 'granted' | 'denied'> => {
+    const update: Record<string, 'granted' | 'denied'> = {}
+    for (const category of categories ?? DEFAULT_CONSENT_CATEGORIES) {
+      const granted = category.required === true || record[category.key] === true
+      for (const signal of category.signals ?? []) {
+        // A signal named by two categories is granted only when every one of them is.
+        update[signal] = granted && update[signal] !== 'denied' ? 'granted' : 'denied'
+      }
+    }
+
+    return update
+  }
+
+  const pushConsentDefaults = (opts?: ConsentOptions): void => {
+    const win = global()
+    if (win == null || opts?.silent === true || win[CONSENT_SETUP_FLAG] === true) {
+      return
+    }
+    gtagConsent('consent', 'default', consentDefaults(categoriesOf(opts)))
+    win[CONSENT_SETUP_FLAG] = true
+  }
+
+  const applyConsent = (record: ConsentRecord, opts?: ConsentOptions): void => {
+    const win = global()
+    if (win == null || opts?.silent === true) {
+      return
+    }
+    const categories = categoriesOf(opts)
+
+    for (const category of categories) {
+      if (category.globalVar != null) {
+        win[category.globalVar] = category.required === true || record[category.key] === true
+      }
+    }
+
+    gtagConsent('consent', 'update', consentUpdate(record, categories))
+
+    for (const category of categories) {
+      if (category.event != null && (category.required === true || record[category.key] === true)) {
+        win.dataLayer = win.dataLayer ?? []
+        win.dataLayer.push({ event: category.event })
+      }
+    }
+
+    // A gate script (`consentGateScript`) that already decided NOT to load, because nothing was
+    // granted at the time it ran, has no other way to hear this. Consent Mode itself speaks only on
+    // `dataLayer`, which a tag that never loaded is not listening to.
+    if (typeof window !== 'undefined' && typeof window.dispatchEvent === 'function'
+      && typeof CustomEvent === 'function') {
+      window.dispatchEvent(new CustomEvent(CONSENT_EVENT, { detail: { record } }))
+    }
+  }
+
+  const trackingGranted = (
+    record: ConsentRecord | null, categories: ConsentCategory[] = DEFAULT_CONSENT_CATEGORIES
+  ): boolean => record != null && categories.some(
+    category => !category.required && (category.signals?.length ?? 0) > 0 && record[category.key] === true
+  )
+
+  const consentBootstrapScript = (opts?: ConsentOptions): string => {
+    const defaults = JSON.stringify(consentDefaults(categoriesOf(opts)))
+    const categories = JSON.stringify(categoriesOf(opts).map(category => ({
+      key: category.key,
+      required: category.required === true,
+      signals: category.signals ?? [],
+      globalVar: category.globalVar ?? null,
+    })))
+    const storageKey = JSON.stringify(opts?.storageKey ?? CONSENT_KEY)
+    const flag = JSON.stringify(CONSENT_SETUP_FLAG)
+    // Right after the default is pushed and before EITHER storage read below (this one, and the
+    // `consentGateScript` that is concatenated after this whole IIFE) — an adopted decision must
+    // already be in storage by the time anything reads it, so `gtm.js`'s own `page_view` never sees
+    // the parameter and a granted decision loads the tag on arrival. A page with no `opts.linker`
+    // gets an empty string here, unchanged from before this existed.
+    const linker = opts?.linker != null ? `${consentLinkHelper.consentLinkerScript(opts)};` : ''
+
+    return `(function(w,d){` +
+      `w.dataLayer=w.dataLayer||[];function g(){w.dataLayer.push(arguments)}` +
+      `if(w[${flag}])return;g('consent','default',${defaults});w[${flag}]=true;` +
+      linker +
+      `var raw=null;try{raw=w.localStorage.getItem(${storageKey})}catch(e){}` +
+      `if(!raw){var p=('; '+d.cookie).split('; '+${storageKey}+'=');` +
+      `if(p.length===2){raw=p.pop().split(';').shift()}}` +
+      `if(!raw)return;var r;try{r=JSON.parse(raw)}catch(e){return}` +
+      staleAutoScript('return') +
+      `var cs=${categories},u={};` +
+      `for(var i=0;i<cs.length;i++){var c=cs[i];var ok=c.required||r[c.key]===true;` +
+      `if(c.globalVar){w[c.globalVar]=ok}` +
+      `for(var j=0;j<c.signals.length;j++){var s=c.signals[j];` +
+      `u[s]=ok&&u[s]!=='denied'?'granted':'denied'}}` +
+      `g('consent','update',u)})(window,document)`
+  }
+
+  const consentGateScript = (
+    loaderExpr: string, opts?: ConsentOptions & { categories?: ConsentCategory[] }
+  ): string => {
+    const gate = JSON.stringify(categoriesOf(opts).map(category => ({
+      key: category.key,
+      required: category.required === true,
+      hasSignal: (category.signals ?? []).length > 0,
+    })))
+    const storageKey = JSON.stringify(opts?.storageKey ?? CONSENT_KEY)
+    const event = JSON.stringify(CONSENT_EVENT)
+
+    return `(function(w,d){` +
+      `function ok(r){if(!r)return false;var cs=${gate};` +
+      `for(var i=0;i<cs.length;i++){var c=cs[i];` +
+      `if(!c.required&&c.hasSignal&&r[c.key]===true)return true}return false}` +
+      `function load(){${loaderExpr}}` +
+      `var raw=null;try{raw=w.localStorage.getItem(${storageKey})}catch(e){}` +
+      `if(!raw){var p=('; '+d.cookie).split('; '+${storageKey}+'=');` +
+      `if(p.length===2){raw=p.pop().split(';').shift()}}` +
+      `var r=null;if(raw){try{r=JSON.parse(raw)}catch(e){r=null}}` +
+      staleAutoScript('r=null') +
+      `if(ok(r)){load();return}` +
+      `function h(ev){if(ok(ev&&ev.detail&&ev.detail.record)){` +
+      `w.removeEventListener(${event},h);load()}}` +
+      `w.addEventListener(${event},h)` +
+      `})(window,document)`
+  }
+
+  return {
+    gtagConsent, consentDefaults, consentUpdate, pushConsentDefaults, applyConsent, trackingGranted,
+    consentBootstrapScript, consentGateScript,
+  }
+}
+
+export const consentModeHelper = createConsentModeHelper()
+
+/** @deprecated compat:factory-refactor — use `consentModeHelper.consentBootstrapScript(…)` */
+export const consentBootstrapScript = (opts?: ConsentOptions): string => consentModeHelper.consentBootstrapScript(opts)