@owlmeans/consent 0.1.18-rc.9 → 0.1.18

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.
@@ -46,9 +55,19 @@ export const CONSENT_MARKETING = 'marketing'
  */
 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.
@@ -94,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)

package/src/i18n/be.json

@@ -32,5 +32,12 @@
   "privacy": "Палітыка прыватнасці",
   "terms": "Умовы карыстання",
   "domains": "Гэты выбар распаўсюджваецца на {{domains}}.",
-  "policyDomains": "Гэты выбар распаўсюджваецца на наступныя дамены:"
+  "policyDomains": "Гэты выбар распаўсюджваецца на наступныя дамены:",
+  "barTitle": "Файлы cookie на гэтым сайце",
+  "barDescription": "Мы выкарыстоўваем неабходныя файлы cookie для працы сайта — для ўваходу, забеспячэння бяспекі і запамінання вашага выбару. З вашай згоды мы таксама выкарыстоўвалі б наступныя неабавязковыя файлы cookie: {{categories}}. Яны застаюцца выключанымі, пакуль вы іх не дазволіце, а свой выбар вы можаце ў любы момант змяніць або адклікаць у наладах файлаў cookie.",
+  "barDescriptionEssential": "Гэты сайт выкарыстоўвае толькі неабходныя файлы cookie — для ўваходу, забеспячэння бяспекі і запамінання вашага выбару. Яны не патрабуюць згоды і не могуць быць адключаны.",
+  "acceptMandatory": "Прыняць толькі неабходныя",
+  "locating": "Вызначаем ваш рэгіён…",
+  "autoReason": "Гэтыя налады ўжыты аўтаматычна, бо там, адкуль вы праглядаеце сайт, згода на файлы cookie не патрабуецца. Вы можаце змяніць іх у любы момант.",
+  "policyRegional": "Там, дзе закон месца знаходжання наведвальніка патрабуе папярэдняй згоды, — у ЕС і ЕЭЗ, Вялікабрытаніі, Швейцарыі і іншых краінах з падобнымі правіламі — неабавязковыя файлы cookie застаюцца выключанымі, пакуль наведвальнік іх не дазволіць. У астатніх краінах яны ўключаны па змаўчанні, акрамя выпадкаў, калі браўзер перадае сігнал Global Privacy Control, які ўлічваецца як адмова; іх можна адключыць у любы момант кнопкай ніжэй."
 }

package/src/i18n/de.json

@@ -32,5 +32,12 @@
   "privacy": "Datenschutzerklärung",
   "terms": "Nutzungsbedingungen",
   "domains": "Diese Wahl gilt für {{domains}}.",
-  "policyDomains": "Diese Wahl gilt für die folgenden Domains:"
+  "policyDomains": "Diese Wahl gilt für die folgenden Domains:",
+  "barTitle": "Cookies auf dieser Website",
+  "barDescription": "Wir verwenden notwendige Cookies, damit diese Website funktioniert – für die Anmeldung, die Sicherheit und um Ihre Auswahl zu speichern. Mit Ihrer Einwilligung würden wir außerdem diese optionalen Cookies verwenden: {{categories}}. Sie bleiben deaktiviert, bis Sie sie erlauben, und Sie können Ihre Auswahl jederzeit in den Cookie-Einstellungen ändern oder widerrufen.",
+  "barDescriptionEssential": "Diese Website verwendet nur notwendige Cookies – für die Anmeldung, die Sicherheit und um Ihre Auswahl zu speichern. Sie erfordern keine Einwilligung und können nicht deaktiviert werden.",
+  "acceptMandatory": "Nur notwendige akzeptieren",
+  "locating": "Ihre Region wird ermittelt …",
+  "autoReason": "Diese Einstellungen wurden automatisch angewendet, weil dort, von wo aus Sie die Website aufrufen, keine Cookie-Einwilligung erforderlich ist. Sie können sie jederzeit ändern.",
+  "policyRegional": "Wo das Recht am Aufenthaltsort der Besucher eine vorherige Einwilligung verlangt – in der EU und im EWR, im Vereinigten Königreich, in der Schweiz und in weiteren Ländern mit ähnlichen Regeln –, bleiben optionale Cookies deaktiviert, bis sie erlaubt werden. Anderswo sind sie standardmäßig aktiviert, außer wenn der Browser ein Global-Privacy-Control-Signal sendet, das als Ablehnung beachtet wird; sie lassen sich jederzeit über die Schaltfläche unten deaktivieren."
 }

package/src/i18n/en.json

@@ -32,5 +32,12 @@
   "privacy": "Privacy Policy",
   "terms": "Terms & Conditions",
   "domains": "This choice applies to {{domains}}.",
-  "policyDomains": "This choice applies across these domains:"
+  "policyDomains": "This choice applies across these domains:",
+  "barTitle": "Cookies on this site",
+  "barDescription": "We use essential cookies to make this site work — for signing in, security and remembering your choices. With your consent we would also use these optional cookies: {{categories}}. They stay off until you allow them, and you can change or withdraw your choice at any time in the cookie preferences.",
+  "barDescriptionEssential": "This site uses only essential cookies — for signing in, security and remembering your choices. They need no consent and cannot be switched off.",
+  "acceptMandatory": "Accept only mandatory",
+  "locating": "Checking your region…",
+  "autoReason": "These settings were applied automatically, because cookie consent is not required where you are browsing from. You can change them at any time.",
+  "policyRegional": "Where the law of the visitor's location requires prior consent — the EU and EEA, the United Kingdom, Switzerland and other countries with similar rules — optional cookies stay off until the visitor allows them. Elsewhere they are switched on by default, except when the browser sends a Global Privacy Control signal, which is honoured as a refusal; they can be switched off at any time with the button below."
 }

package/src/i18n/es.json

@@ -32,5 +32,12 @@
   "privacy": "Política de privacidad",
   "terms": "Términos y condiciones",
   "domains": "Esta elección se aplica a {{domains}}.",
-  "policyDomains": "Esta elección se aplica a los siguientes dominios:"
+  "policyDomains": "Esta elección se aplica a los siguientes dominios:",
+  "barTitle": "Cookies en este sitio",
+  "barDescription": "Usamos cookies esenciales para que este sitio funcione: para iniciar sesión, por seguridad y para recordar tus elecciones. Con tu consentimiento también usaríamos estas cookies opcionales: {{categories}}. Permanecen desactivadas hasta que las permitas, y puedes cambiar o retirar tu elección en cualquier momento en las preferencias de cookies.",
+  "barDescriptionEssential": "Este sitio solo usa cookies esenciales: para iniciar sesión, por seguridad y para recordar tus elecciones. No requieren consentimiento y no se pueden desactivar.",
+  "acceptMandatory": "Aceptar solo las esenciales",
+  "locating": "Comprobando tu región…",
+  "autoReason": "Esta configuración se aplicó automáticamente porque, desde donde navegas, no se requiere consentimiento para las cookies. Puedes cambiarla en cualquier momento.",
+  "policyRegional": "Donde la ley del lugar en que se encuentra el visitante exige consentimiento previo —la UE y el EEE, el Reino Unido, Suiza y otros países con normas similares—, las cookies opcionales permanecen desactivadas hasta que el visitante las permita. En el resto están activadas por defecto, salvo cuando el navegador envía una señal Global Privacy Control, que se respeta como rechazo; pueden desactivarse en cualquier momento con el botón de abajo."
 }

package/src/i18n/fr.json

@@ -32,5 +32,12 @@
   "privacy": "Politique de confidentialité",
   "terms": "Conditions générales",
   "domains": "Ce choix s'applique à {{domains}}.",
-  "policyDomains": "Ce choix s'applique aux domaines suivants :"
+  "policyDomains": "Ce choix s'applique aux domaines suivants :",
+  "barTitle": "Cookies sur ce site",
+  "barDescription": "Nous utilisons des cookies essentiels au fonctionnement de ce site : pour la connexion, la sécurité et la mémorisation de vos choix. Avec votre consentement, nous utiliserions également ces cookies facultatifs : {{categories}}. Ils restent désactivés tant que vous ne les autorisez pas, et vous pouvez modifier ou retirer votre choix à tout moment dans les préférences de cookies.",
+  "barDescriptionEssential": "Ce site n'utilise que des cookies essentiels : pour la connexion, la sécurité et la mémorisation de vos choix. Ils ne nécessitent pas de consentement et ne peuvent pas être désactivés.",
+  "acceptMandatory": "Accepter uniquement les essentiels",
+  "locating": "Vérification de votre région…",
+  "autoReason": "Ces paramètres ont été appliqués automatiquement, car le consentement aux cookies n'est pas requis là où vous naviguez. Vous pouvez les modifier à tout moment.",
+  "policyRegional": "Là où la loi du lieu où se trouve le visiteur exige un consentement préalable — l'UE et l'EEE, le Royaume-Uni, la Suisse et d'autres pays aux règles similaires —, les cookies facultatifs restent désactivés tant que le visiteur ne les autorise pas. Ailleurs, ils sont activés par défaut, sauf lorsque le navigateur envoie un signal Global Privacy Control, respecté comme un refus ; ils peuvent être désactivés à tout moment avec le bouton ci-dessous."
 }