@owlmeans/consent 0.1.18-rc.9 → 0.1.18

package/src/store.ts

@@ -1,11 +1,16 @@
-import { CONSENT_KEY, DEFAULT_CONSENT_CATEGORIES } from './consts.js'
-import { applyConsent, pushConsentDefaults } from './gtm.js'
-import { consentLinker, stripConsentLinkParam, writeConsentLanguage } from './linker.js'
-import { adoptConsent, adoptConsentLanguage, registerConsentPlugin, startConsentPlugins } from './plugins.js'
-import { readConsent, writeConsent } from './storage.js'
+import {
+  CONSENT_IDLE_STATE, CONSENT_KEY, CONSENT_STATE_ATTRIBUTE, DEFAULT_CONSENT_CATEGORIES,
+} from './consts.js'
+import { CLOUDFLARE_LOCATOR_ALIAS } from './consts.local.js'
+import { consentModeHelper } from './gtobserver.js'
+import { consentGeoHelper } from './geo.js'
+import { consentLinkHelper } from './linker.js'
+import { consentPluginHelper } from './plugins.js'
+import { consentStorageHelper } from './storage.js'
 import type {
   ConsentListener, ConsentOptions, ConsentReason, ConsentRecord, ConsentState, ConsentStore,
 } from './types.js'
+import type { ConsentGeoVerdict } from './geo/types.js'
 
 /**
  * The consent state of this DOCUMENT.
@@ -17,12 +22,34 @@ import type {
  */
 export const makeConsentStore = (): ConsentStore => {
   const listeners = new Set<ConsentListener>()
-  let state: ConsentState = { record: null, open: false, reason: null }
+  const waiting = new Set<(state: ConsentState) => void>()
+  let state: ConsentState = CONSENT_IDLE_STATE
   let options: ConsentOptions = {}
+  /** The one country lookup of this document, while it runs. */
+  let lookup: Promise<void> | null = null
+  /** What the last lookup decided — a later `init` never locates the same visitor twice. */
+  let verdict: ConsentGeoVerdict | null = null
+
+  /** `<html data-consent>`: what a test waits on and a stylesheet may key on. */
+  const mark = (): void => {
+    const root = typeof document !== 'undefined' ? document.documentElement : undefined
+    if (root == null || typeof root.setAttribute !== 'function') {
+      return
+    }
+    root.setAttribute(CONSENT_STATE_ATTRIBUTE, state.open ? 'open'
+      : state.locating != null ? 'locating'
+        : state.record != null ? 'decided' : 'idle')
+  }
 
   const publish = (next: Partial<ConsentState>): void => {
     state = { ...state, ...next }
+    mark()
     listeners.forEach(listener => listener(state))
+    if (state.locating == null && lookup == null && waiting.size > 0) {
+      const settled = [...waiting]
+      waiting.clear()
+      settled.forEach(resolve => resolve(state))
+    }
   }
 
   const resolved = (): ConsentOptions & { categories: typeof DEFAULT_CONSENT_CATEGORIES, storageKey: string } => ({
@@ -31,6 +58,37 @@ export const makeConsentStore = (): ConsentStore => {
     storageKey: options.storageKey ?? CONSENT_KEY,
   })
 
+  const ask = (): void => {
+    publish({ record: null, open: true, reason: 'initial', locating: null })
+  }
+
+  /**
+   * What a finished lookup does — unless the visitor got there first: a decision saved meanwhile, or
+   * the window opened for a reason of its own (signing in), always wins over the location.
+   */
+  const settle = (result: ConsentGeoVerdict, pending: ConsentRecord | null): void => {
+    verdict = result
+    lookup = null
+    if (state.record != null || (state.open && state.reason !== 'initial')) {
+      publish({ locating: null })
+
+      return
+    }
+    if (result === 'auto') {
+      const record = consentGeoHelper.automaticRecord(resolved())
+      consentStorageHelper.writeConsent(record, options)
+      consentModeHelper.applyConsent(record, options)
+      publish({ record, open: false, reason: null, locating: null })
+
+      return
+    }
+    if (pending != null) {
+      // A grant derived somewhere nobody had to be asked does not survive arriving where they must.
+      consentStorageHelper.clearConsent(options)
+    }
+    ask()
+  }
+
   const store: ConsentStore = {
     get: () => state,
 
@@ -43,52 +101,82 @@ export const makeConsentStore = (): ConsentStore => {
     init: opts => {
       options = { ...options, ...opts }
       // Before anything is read, so a page with no stored answer still declares what is denied.
-      pushConsentDefaults(options)
+      consentModeHelper.pushConsentDefaults(options)
 
       if (options.linker != null) {
-        // Replace-by-alias (`registerConsentPlugin`), so a second `init` (a re-mounted provider,
-        // StrictMode) never double-installs the click listener — `consentLinker().start` also
-        // guards itself with its own closured flag, belt and braces.
-        registerConsentPlugin(consentLinker())
-        startConsentPlugins(options)
+        // Registered once: `start` installs the click listener of THAT instance, and a second
+        // instance (a second `init` — a re-mounted provider, StrictMode, `loadGtm`) would install
+        // its own beside it.
+        if (!consentPluginHelper.consentPlugins().some(plugin => plugin.alias === 'linker')) {
+          consentPluginHelper.registerConsentPlugin(consentLinkHelper.consentLinker())
+        }
+        consentPluginHelper.startConsentPlugins(options)
+      }
+      if (options.geo?.cloudflare != null && options.geo.cloudflare !== false
+        && !consentPluginHelper.consentPlugins().some(plugin => plugin.alias === CLOUDFLARE_LOCATOR_ALIAS)) {
+        consentPluginHelper.registerConsentPlugin(consentGeoHelper.cloudflareLocator())
       }
 
-      let record = readConsent(options)
-      // Only when THIS document has no decision yet — an existing one always wins, exactly as the
-      // ordinary "ask" path would never overwrite a stored record either.
-      if (record == null && options.linker != null) {
-        record = adoptConsent(options)
-        if (record != null) {
-          writeConsent(record, options)
+      let record = consentStorageHelper.readConsent(options)
+      const automatic = consentGeoHelper.autoState(record)
+      // An automatic decision past its age is held back — applied nowhere — until the visitor is
+      // located again, exactly as the head scripts already skipped it.
+      const pending = automatic === 'stale' ? record : null
+      if (pending != null) {
+        record = null
+      }
+      // An explicit decision carried from another domain always beats none — and beats an automatic
+      // one, which nobody chose. An explicit stored one always wins, as the ordinary "ask" path
+      // would never overwrite it either.
+      if ((record == null || automatic != null) && options.linker != null) {
+        const adopted = consentPluginHelper.adoptConsent(options)
+        if (adopted != null) {
+          consentStorageHelper.writeConsent(adopted, options)
+          record = adopted
         }
       }
       if (options.linker != null) {
         // The language the link carried, stored at once — the interface language is strictly
         // necessary storage, so no decision is consulted. A page that stamped the inline head
         // fragment has already done this and stripped the parameter, which leaves nothing here.
-        const carried = adoptConsentLanguage(options)
+        const carried = consentPluginHelper.adoptConsentLanguage(options)
         if (carried != null) {
-          writeConsentLanguage(carried, options)
+          consentLinkHelper.writeConsentLanguage(carried, options)
         }
         // Always, whether or not anything was adopted — a stale or foreign parameter is exactly as
         // much noise in the visible URL as an adopted one, and a page that already had its own
         // decision may still have arrived with one attached.
-        stripConsentLinkParam(options)
+        consentLinkHelper.stripConsentLinkParam(options)
       }
 
       if (record != null) {
-        applyConsent(record, options)
-        publish({ record, open: false, reason: null })
+        consentModeHelper.applyConsent(record, options)
+        publish({ record, open: false, reason: null, locating: null })
 
         return
       }
-      publish({ record: null, open: true, reason: 'initial' })
+      if (lookup != null) {
+        return
+      }
+      // The window is already open for a reason of its own (signing in): the visitor is answering.
+      if (state.open && state.reason !== 'initial') {
+        return
+      }
+      if (verdict === 'ask' || !consentGeoHelper.enabled(options)) {
+        ask()
+
+        return
+      }
+      // A first visit waits behind the spinner; a re-check runs silently, nothing applied meanwhile.
+      publish({ record: null, open: false, reason: null, locating: pending != null ? 'recheck' : 'first' })
+      lookup = consentGeoHelper.decide(options).then(result => settle(result, pending))
     },
 
     save: record => {
-      writeConsent(record, options)
-      applyConsent(record, options)
-      publish({ record, open: false, reason: null })
+      const { auto: _auto, ...explicit } = record
+      consentStorageHelper.writeConsent(explicit, options)
+      consentModeHelper.applyConsent(explicit, options)
+      publish({ record: explicit, open: false, reason: null, locating: null })
     },
 
     acceptAll: () => {
@@ -98,7 +186,9 @@ export const makeConsentStore = (): ConsentStore => {
       store.save(record)
     },
 
-    open: (reason?: ConsentReason) => { publish({ open: true, reason: reason ?? 'reopen' }) },
+    open: (reason?: ConsentReason) => {
+      publish({ open: true, reason: reason ?? 'reopen', locating: null })
+    },
 
     close: () => { publish({ open: false, reason: null }) },
 
@@ -112,6 +202,10 @@ export const makeConsentStore = (): ConsentStore => {
     },
 
     options: resolved,
+
+    settled: () => state.locating == null && lookup == null
+      ? Promise.resolve(state)
+      : new Promise(resolve => { waiting.add(resolve) }),
   }
 
   return store
@@ -119,8 +213,8 @@ export const makeConsentStore = (): ConsentStore => {
 
 export const consentStore: ConsentStore = makeConsentStore()
 
-/** Open the preferences dialog from anywhere — a footer link, a policy page, a login gate. */
+/** @deprecated compat:factory-refactor — use `consentStore.open(…)` */
 export const openConsent = (reason?: ConsentReason): void => consentStore.open(reason)
 
-/** Whether a category is granted, for the callers that are not components. */
+/** @deprecated compat:factory-refactor — use `consentStore.granted(…)` */
 export const isConsented = (key: string): boolean => consentStore.granted(key)

package/src/types.local.ts

@@ -0,0 +1,9 @@
+export interface ConsentWindow {
+  dataLayer?: unknown[]
+  [flag: string]: unknown
+}
+
+/** The one navigator field the automatic decision reads: Global Privacy Control. */
+export interface ConsentNavigator {
+  globalPrivacyControl?: boolean
+}

package/src/types.ts

@@ -5,6 +5,8 @@
  * manager simply never sees the update, and the only symptom is analytics that stay switched off
  * for everyone who agreed to them.
  */
+import { CONSENT_LINK_VERSION } from './consts.local.js'
+
 export type ConsentSignal =
   | 'ad_storage' | 'ad_user_data' | 'ad_personalization'
   | 'analytics_storage' | 'functionality_storage'
@@ -68,12 +70,60 @@ export interface ConsentService {
   privacyHref?: string
 }
 
-/** `v` is the schema version; every other key is a category key. */
+/**
+ * `v` is the schema version and `auto` marks an automatic decision; every other key is a category
+ * key — so neither `v` nor `auto` may ever name a category.
+ */
 export interface ConsentRecord {
   v?: number
+  /**
+   * Unix seconds at which this record was DERIVED rather than chosen: the visitor was located
+   * outside every consent-requiring country (`ConsentGeoOptions`) and nobody asked them. Present
+   * only on an automatic decision — an explicit save drops it. An automatic decision is trusted for
+   * `CONSENT_AUTO_MAX_AGE` seconds and then counts as undecided until the visitor is located again,
+   * so a traveller who crosses into a consent country is asked there instead of carrying a grant
+   * nobody gave. It never travels on a linker link as the visitor's own choice.
+   */
+  auto?: number
   [category: string]: boolean | number | undefined
 }
 
+/** Where a locator places the visitor. */
+export interface ConsentGeoLocation {
+  /** ISO 3166-1 alpha-2, upper case — `PL`, `US`. Anything else counts as "not located". */
+  country: string
+}
+
+export interface ConsentCloudflareOptions {
+  /** The same-origin path of Cloudflare's trace endpoint. Defaults to `CONSENT_TRACE_PATH`. */
+  path?: string
+}
+
+/**
+ * Ask only where the law requires it: locate the visitor first, and decide automatically wherever
+ * no consent is required.
+ *
+ * Its presence turns the gate on. The country comes from the registered locators
+ * (`ConsentGeoPlugin`, highest priority first, the first usable answer wins); `cloudflare` adds the
+ * built-in one. A visitor nobody can locate — no locator, every one of them failing, an unusable
+ * code, `timeout` passing — is asked, exactly as without the gate.
+ */
+export interface ConsentGeoOptions {
+  /**
+   * The built-in locator: a same-origin GET of Cloudflare's `/cdn-cgi/trace`, reading `loc=`. It
+   * answers only where the host is proxied by Cloudflare — anywhere else (a local dev server, a
+   * self-hosted export) it fails, and the visitor is asked.
+   */
+  cloudflare?: boolean | ConsentCloudflareOptions
+  /** The countries where consent is asked. Defaults to `CONSENT_REQUIRED_COUNTRIES`. */
+  countries?: readonly string[]
+  /** How long locating may take before the visitor is asked anyway, in ms. `CONSENT_GEO_TIMEOUT`. */
+  timeout?: number
+}
+
+/** Which lookup is running: the first one (the page waits behind a spinner) or a silent re-check. */
+export type ConsentLocating = 'first' | 'recheck'
+
 export interface ConsentOptions {
   categories?: ConsentCategory[]
   storageKey?: string
@@ -91,6 +141,8 @@ export interface ConsentOptions {
    * `consentLinker`/`ConsentPlugin` in `./plugins.js` and `./linker.js`.
    */
   linker?: ConsentLinkerOptions
+  /** Ask only in consent-requiring countries — see `ConsentGeoOptions`. Off when absent. */
+  geo?: ConsentGeoOptions
 }
 
 export interface ConsentLinkerOptions {
@@ -130,27 +182,118 @@ export interface ConsentLinkerLanguage {
   storageKey?: string
 }
 
-/** Why the dialog is open. `login` is what the sign-in precondition raises. */
-export type ConsentReason = 'initial' | 'reopen' | 'login' | string
+/**
+ * Why the consent UI is open. `initial` is the first ask (the bar, in bar mode); `preferences` is the
+ * bar's own "Cookie preferences"; `reopen` a footer link or the corner button; `login` what the
+ * sign-in precondition raises. Every reason but `initial` opens the preferences window.
+ */
+export type ConsentReason = 'initial' | 'reopen' | 'login' | 'preferences' | string
 
 export interface ConsentState {
   record: ConsentRecord | null
   open: boolean
   reason: ConsentReason | null
+  /** A country lookup is running (`ConsentGeoOptions`); `null` once it settled, or when there is none. */
+  locating: ConsentLocating | null
 }
 
-export type ConsentListener = (state: ConsentState) => void
+export interface ConsentListener { (state: ConsentState): void }
 
 export interface ConsentStore {
   get: () => ConsentState
   subscribe: (listener: ConsentListener) => () => void
-  /** Push the defaults, load and migrate any stored record, apply it, and open when there is none. */
+  /**
+   * Push the defaults, load and migrate any stored record, apply it — and, when there is none,
+   * either ask at once or, with `geo` set, locate the visitor first and ask or decide automatically.
+   * Synchronous: a lookup runs in the background, `locating` says so, and `settled()` waits for it.
+   */
   init: (opts?: ConsentOptions) => void
+  /** Record an explicit decision. Always explicit: an `auto` key on `record` is dropped. */
   save: (record: ConsentRecord) => void
   acceptAll: () => void
+  /** Open the consent UI from anywhere — a footer link, a policy page, a login gate. */
   open: (reason?: ConsentReason) => void
   close: () => void
   /** Imperative reader, for the callers that are not React. */
   granted: (key: string) => boolean
   options: () => ConsentOptions & { categories: ConsentCategory[], storageKey: string }
+  /** The state once no country lookup is running — at once when none is. */
+  settled: () => Promise<ConsentState>
+}
+
+/** A language the dialog's built-in copy is carried in (`CONSENT_LOCALES`). */
+export type ConsentLocale = 'en' | 'pl' | 'ru' | 'be' | 'uk' | 'es' | 'de' | 'fr'
+
+/** The decoded, not-yet-validated payload a decorated link's parameter carries. */
+export interface ConsentLinkPayload {
+  v: typeof CONSENT_LINK_VERSION
+  /** One entry per OPTIONAL category this site knows, `1` granted / `0` denied. */
+  c: Record<string, 0 | 1>
+  /** Unix seconds the link was decorated at. */
+  t: number
+  /**
+   * The interface language of the page the link was on (a BCP 47 tag, lower-cased) — present only
+   * when the sender has `linker.language` set and its `<html lang>` names one. Optional on the
+   * wire, so a receiver that predates it reads the same `v: 2` payload and ignores the field.
+   */
+  l?: string
+}
+
+/**
+ * An extension seam for `@owlmeans/consent`: something that reacts to this document's consent
+ * decision, or supplies one from elsewhere, without the core store knowing anything about where
+ * that decision came from.
+ *
+ * `consentLinker` (`./linker.js`) is the one built-in plugin — cross-domain consent through
+ * decorated links — but nothing here is specific to it. A registry rather than a fixed option on
+ * `ConsentOptions` because the store has zero dependencies today and stays that way: a plugin is
+ * opt-in code an application imports for its own reason, never a bundled feature this package
+ * pulls in whether or not anything uses it.
+ */
+export interface ConsentPlugin {
+  /** Stable identity. Registering the same alias again REPLACES the earlier plugin. */
+  alias: string
+  /** Run order when more than one plugin implements the same hook. Higher first. Defaults to 0. */
+  priority?: number
+  /** Installed once, the first time `consentStore.init` runs with this plugin registered. */
+  start?: (opts: ConsentOptions) => void
+  /**
+   * Offer a decision from outside this document's own storage — e.g. one carried on the URL that
+   * led here. Returns a full record to adopt, or `null` to defer to the next plugin / the ordinary
+   * "ask" path. Never called once a stored record already exists.
+   */
+  adopt?: (opts: ConsentOptions) => ConsentRecord | null
+  /**
+   * Offer an interface language from outside this document's own storage — e.g. the one the page
+   * that led here was read in. Returns a language the application supports, or `null` to keep
+   * choosing its own. Only a CANDIDATE: it says what the link carried, and `writeConsentLanguage`
+   * stores it — unconditionally, since the interface language is strictly necessary storage.
+   */
+  adoptLanguage?: (opts: ConsentOptions) => string | null
+  /**
+   * Rewrite an outgoing URL to carry this document's current decision — and its language — or
+   * `null` to leave it untouched (a foreign host, a link that opts out, nothing to carry yet).
+   * `record` is `null` while the visitor has not decided: a plugin that also carries something
+   * else (the language) still has a reason to decorate then.
+   */
+  decorate?: (url: URL, record: ConsentRecord | null, opts: ConsentOptions) => URL | null
+  /** Extra domains this decision is understood to apply to, for disclosure — never deduplicated here. */
+  domains?: (opts: ConsentOptions) => string[]
+  /**
+   * Find the visitor's country, or throw when it cannot tell. Asked only while `opts.geo` is set
+   * and nothing is stored; locators run highest priority first and the first usable country wins,
+   * so a throw (or an unusable code) hands over to the next one — the built-in Cloudflare locator
+   * sits at the very bottom.
+   */
+  locate?: (opts: ConsentOptions) => Promise<ConsentGeoLocation>
+}
+
+/**
+ * The country-detection plugin: one async method that resolves the visitor's country or throws.
+ * Register it with `consentPluginHelper.registerConsentPlugin` — or, in an OwlMeans application,
+ * with `@owlmeans/web-panel/consent`'s `appendConsentGeoPlugin(context, plugin)` while the context is
+ * configured.
+ */
+export interface ConsentGeoPlugin extends ConsentPlugin {
+  locate: (opts: ConsentOptions) => Promise<ConsentGeoLocation>
 }

package/tests/consent.spec.ts

@@ -1,14 +1,12 @@
 import { describe, test, expect, beforeEach } from 'bun:test'
 import {
   CONSENT_ANALYTICS, CONSENT_ESSENTIAL, CONSENT_EVENT, CONSENT_KEY, CONSENT_LOCALES,
-  CONSENT_MARKETING, CONSENT_SCHEMA_VERSION, DEFAULT_CONSENT_CATEGORIES,
+  CONSENT_MARKETING, CONSENT_SCHEMA_VERSION, DEFAULT_CONSENT_CATEGORIES, DEFAULT_CONSENT_MESSAGES,
 } from '../src/consts.js'
-import { migrateConsent, readConsent, writeConsent, clearConsent } from '../src/storage.js'
-import { applyConsent, consentDefaults, consentUpdate, consentBootstrapScript } from '../src/gtm.js'
+import { consentStorageHelper } from '../src/storage.js'
+import { consentModeHelper } from '../src/gtobserver.js'
 import { makeConsentStore } from '../src/store.js'
-import {
-  DEFAULT_CONSENT_MESSAGES, defaultConsentTranslate, interpolate, normalizeLocale,
-} from '../src/i18n.js'
+import { consentI18nHelper } from '../src/i18n.js'
 import type { ConsentCategory } from '../src/types.js'
 
 /** A minimal browser: just the two stores this package writes to. */
@@ -41,33 +39,33 @@ beforeEach(() => {
 
 describe('storage', () => {
   test('a record round-trips through localStorage', () => {
-    writeConsent({ [CONSENT_ANALYTICS]: true, [CONSENT_MARKETING]: false })
+    consentStorageHelper.writeConsent({ [CONSENT_ANALYTICS]: true, [CONSENT_MARKETING]: false })
 
-    expect(readConsent()?.[CONSENT_ANALYTICS]).toBe(true)
-    expect(readConsent()?.[CONSENT_MARKETING]).toBe(false)
+    expect(consentStorageHelper.readConsent()?.[CONSENT_ANALYTICS]).toBe(true)
+    expect(consentStorageHelper.readConsent()?.[CONSENT_MARKETING]).toBe(false)
   })
 
   test('the cookie answers when localStorage does not', () => {
-    writeConsent({ [CONSENT_ANALYTICS]: true })
+    consentStorageHelper.writeConsent({ [CONSENT_ANALYTICS]: true })
     env.store.clear()
 
-    expect(readConsent()?.[CONSENT_ANALYTICS]).toBe(true)
+    expect(consentStorageHelper.readConsent()?.[CONSENT_ANALYTICS]).toBe(true)
   })
 
   test('the cookie is path-wide, SameSite=Lax and long-lived', () => {
-    writeConsent({ [CONSENT_ANALYTICS]: true })
+    consentStorageHelper.writeConsent({ [CONSENT_ANALYTICS]: true })
 
     expect(env.raw()).toContain(`${CONSENT_KEY}=`)
     // The cookie fragment the browser stub keeps is just the pair, so the attributes are asserted
     // on what `writeConsent` produced rather than on what a real browser would retain.
-    expect(readConsent()).not.toBeNull()
+    expect(consentStorageHelper.readConsent()).not.toBeNull()
   })
 
   test('a legacy record — the owlmeans.com visitor — migrates instead of being discarded', () => {
     // Exactly what the previous widget wrote: two categories, no version, essential implicit.
     const legacy = { analytics: true, marketing: false }
 
-    const migrated = migrateConsent(legacy)
+    const migrated = consentStorageHelper.migrateConsent(legacy)
 
     expect(migrated?.[CONSENT_ESSENTIAL]).toBe(true)
     expect(migrated?.[CONSENT_ANALYTICS]).toBe(true)
@@ -77,19 +75,19 @@ describe('storage', () => {
   test('a current record is returned unchanged', () => {
     const current = { essential: true, analytics: false, v: CONSENT_SCHEMA_VERSION }
 
-    expect(migrateConsent(current)).toBe(current)
+    expect(consentStorageHelper.migrateConsent(current)).toBe(current)
   })
 
   test('nothing stored reads as null', () => {
-    clearConsent()
+    consentStorageHelper.clearConsent()
 
-    expect(readConsent()).toBeNull()
+    expect(consentStorageHelper.readConsent()).toBeNull()
   })
 })
 
 describe('consent mode signals', () => {
   test('defaults deny everything except security storage', () => {
-    const defaults = consentDefaults()
+    const defaults = consentModeHelper.consentDefaults()
 
     expect(defaults.analytics_storage).toBe('denied')
     expect(defaults.ad_storage).toBe('denied')
@@ -99,7 +97,7 @@ describe('consent mode signals', () => {
   })
 
   test('an update maps each category onto the signals it drives', () => {
-    const update = consentUpdate({ [CONSENT_ANALYTICS]: true, [CONSENT_MARKETING]: false })
+    const update = consentModeHelper.consentUpdate({ [CONSENT_ANALYTICS]: true, [CONSENT_MARKETING]: false })
 
     expect(update.analytics_storage).toBe('granted')
     expect(update.ad_storage).toBe('denied')
@@ -112,8 +110,8 @@ describe('consent mode signals', () => {
       { key: 'ads', labelKey: 'a', descriptionKey: 'b', signals: ['ad_storage'] },
     ]
 
-    expect(Object.keys(consentDefaults(categories))).toEqual(['ad_storage'])
-    expect(consentUpdate({ ads: true }, categories)).toEqual({ ad_storage: 'granted' })
+    expect(Object.keys(consentModeHelper.consentDefaults(categories))).toEqual(['ad_storage'])
+    expect(consentModeHelper.consentUpdate({ ads: true }, categories)).toEqual({ ad_storage: 'granted' })
   })
 })
 
@@ -124,7 +122,7 @@ describe('applyConsent dispatches a DOM event', () => {
     ;(globalThis as any).addEventListener(CONSENT_EVENT, listener)
 
     try {
-      applyConsent({ [CONSENT_ANALYTICS]: true })
+      consentModeHelper.applyConsent({ [CONSENT_ANALYTICS]: true })
 
       expect(seen).toEqual([{ record: { [CONSENT_ANALYTICS]: true } }])
     } finally {
@@ -138,7 +136,7 @@ describe('applyConsent dispatches a DOM event', () => {
     ;(globalThis as any).addEventListener(CONSENT_EVENT, listener)
 
     try {
-      applyConsent({ [CONSENT_ANALYTICS]: true }, { silent: true })
+      consentModeHelper.applyConsent({ [CONSENT_ANALYTICS]: true }, { silent: true })
 
       expect(seen).toEqual([])
     } finally {
@@ -148,7 +146,7 @@ describe('applyConsent dispatches a DOM event', () => {
 })
 
 describe('the bootstrap script', () => {
-  const script = consentBootstrapScript()
+  const script = consentModeHelper.consentBootstrapScript()
 
   test('declares the defaults before anything else can', () => {
     expect(script).toContain("'consent','default'")
@@ -242,15 +240,15 @@ describe('the built-in translations', () => {
   })
 
   test('an unknown locale falls back to English rather than to a raw key', () => {
-    expect(normalizeLocale('kl')).toBe('en')
-    expect(defaultConsentTranslate('kl')('title', 'fallback')).toBe('Cookie Preferences')
+    expect(consentI18nHelper.normalizeLocale('kl')).toBe('en')
+    expect(consentI18nHelper.defaultConsentTranslate('kl')('title', 'fallback')).toBe('Cookie Preferences')
   })
 
   test('a key nobody translated returns the supplied default', () => {
-    expect(defaultConsentTranslate('en')('nope', 'the default')).toBe('the default')
+    expect(consentI18nHelper.defaultConsentTranslate('en')('nope', 'the default')).toBe('the default')
   })
 
   test('placeholders interpolate', () => {
-    expect(interpolate('kept for {{days}} days', { days: 365 })).toBe('kept for 365 days')
+    expect(consentI18nHelper.interpolate('kept for {{days}} days', { days: 365 })).toBe('kept for 365 days')
   })
 })