@owlmeans/consent 0.1.18-rc.10

package/src/store.ts

@@ -0,0 +1,126 @@
+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 type {
+  ConsentListener, ConsentOptions, ConsentReason, ConsentRecord, ConsentState, ConsentStore,
+} from './types.js'
+
+/**
+ * The consent state of this DOCUMENT.
+ *
+ * A module singleton rather than something hung off a context, because that is what consent
+ * actually is — a property of the browser and the page, not of one component tree. It also has to
+ * be reachable from places that are not React at all: the sign-in precondition runs inside a click
+ * handler, and a tag-manager helper runs before any component has mounted.
+ */
+export const makeConsentStore = (): ConsentStore => {
+  const listeners = new Set<ConsentListener>()
+  let state: ConsentState = { record: null, open: false, reason: null }
+  let options: ConsentOptions = {}
+
+  const publish = (next: Partial<ConsentState>): void => {
+    state = { ...state, ...next }
+    listeners.forEach(listener => listener(state))
+  }
+
+  const resolved = (): ConsentOptions & { categories: typeof DEFAULT_CONSENT_CATEGORIES, storageKey: string } => ({
+    ...options,
+    categories: options.categories ?? DEFAULT_CONSENT_CATEGORIES,
+    storageKey: options.storageKey ?? CONSENT_KEY,
+  })
+
+  const store: ConsentStore = {
+    get: () => state,
+
+    subscribe: listener => {
+      listeners.add(listener)
+
+      return () => { listeners.delete(listener) }
+    },
+
+    init: opts => {
+      options = { ...options, ...opts }
+      // Before anything is read, so a page with no stored answer still declares what is denied.
+      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)
+      }
+
+      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)
+        }
+      }
+      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)
+        if (carried != null) {
+          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)
+      }
+
+      if (record != null) {
+        applyConsent(record, options)
+        publish({ record, open: false, reason: null })
+
+        return
+      }
+      publish({ record: null, open: true, reason: 'initial' })
+    },
+
+    save: record => {
+      writeConsent(record, options)
+      applyConsent(record, options)
+      publish({ record, open: false, reason: null })
+    },
+
+    acceptAll: () => {
+      const record: ConsentRecord = Object.fromEntries(
+        resolved().categories.map(category => [category.key, true])
+      )
+      store.save(record)
+    },
+
+    open: (reason?: ConsentReason) => { publish({ open: true, reason: reason ?? 'reopen' }) },
+
+    close: () => { publish({ open: false, reason: null }) },
+
+    granted: key => {
+      const category = resolved().categories.find(candidate => candidate.key === key)
+      if (category?.required === true) {
+        return true
+      }
+
+      return state.record?.[key] === true
+    },
+
+    options: resolved,
+  }
+
+  return store
+}
+
+export const consentStore: ConsentStore = makeConsentStore()
+
+/** Open the preferences dialog from anywhere — a footer link, a policy page, a login gate. */
+export const openConsent = (reason?: ConsentReason): void => consentStore.open(reason)
+
+/** Whether a category is granted, for the callers that are not components. */
+export const isConsented = (key: string): boolean => consentStore.granted(key)

package/src/types.local.ts

@@ -0,0 +1,4 @@
+export interface ConsentWindow {
+  dataLayer?: unknown[]
+  [flag: string]: unknown
+}

package/src/types.ts

@@ -0,0 +1,218 @@
+/**
+ * Google Consent Mode v2 signals.
+ *
+ * Named here rather than left as free strings because a typo in a signal name is silent: the tag
+ * 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'
+import { CONSENT_LOCALES } from './consts.js'
+
+export type ConsentSignal =
+  | 'ad_storage' | 'ad_user_data' | 'ad_personalization'
+  | 'analytics_storage' | 'functionality_storage'
+  | 'personalization_storage' | 'security_storage'
+
+export interface ConsentCategory {
+  /** Stable storage key. `essential` is reserved and always required. */
+  key: string
+  /**
+   * Always granted, rendered locked and labelled as required.
+   *
+   * Strictly-necessary storage does not need consent, and a dialog that presents it as a choice is
+   * itself a dark pattern. A required category is disclosure, not a question.
+   */
+  required?: boolean
+  /** Resolved through `translate`; the built-in bundle supplies the default set in 8 languages. */
+  labelKey: string
+  descriptionKey: string
+  /**
+   * The window global this category yields to: `window[globalVar] = granted`, written on every
+   * apply and BEFORE the tag-manager push.
+   *
+   * This is the seam for anything that cannot subscribe — a custom-HTML tag reading a flag, a
+   * hand-placed pixel, a script that only ever runs once. Without it, integrating a tag that is
+   * not Consent-Mode-aware means reaching into this package.
+   */
+  globalVar?: string
+  /** Consent Mode v2 signals this category drives. */
+  signals?: ConsentSignal[]
+  /** dataLayer event pushed when this category transitions from denied to granted. */
+  event?: string
+}
+
+/**
+ * One third-party service the site runs under a consent category, as the cookie policy discloses
+ * it.
+ *
+ * A category says WHY something is stored; a service says WHO receives it. A regulator reading
+ * the policy wants the second — "analytics cookies" discloses nothing about which company learns
+ * what a visitor did — so a site that runs a tag lists it here, beside the category that gates
+ * it. Plain data rather than keys: the name, the provider and the purpose are whatever the party
+ * adding the tag knows about it, and `@owlmeans/web-gtm`'s `googleTagServices(id)` is the
+ * disclosure for a Google tag.
+ */
+export interface ConsentService {
+  /** Display name: "Google Analytics". */
+  name: string
+  /** Who receives the data: "Google LLC". */
+  provider: string
+  /**
+   * The `ConsentCategory.key` this service runs under: `'analytics'`, `'marketing'`,
+   * `'essential'`, or a custom key. A service whose category is not in force is still disclosed,
+   * in a trailing group of its own — hiding it would hide something that may still run.
+   */
+  category: string
+  /** One sentence on what it does with the data. */
+  purpose?: string
+  /** Cookie names it may set: `['_ga', '_ga_<ID>']`. */
+  cookies?: string[]
+  /** The provider's own privacy policy. */
+  privacyHref?: string
+}
+
+/** `v` is the schema version; every other key is a category key. */
+export interface ConsentRecord {
+  v?: number
+  [category: string]: boolean | number | undefined
+}
+
+export interface ConsentOptions {
+  categories?: ConsentCategory[]
+  storageKey?: string
+  cookieDays?: number
+  /**
+   * Left undefined by default, and that is deliberate: setting a domain orphans the existing
+   * host-only cookie, so every visitor who has already chosen would be asked again.
+   */
+  cookieDomain?: string
+  /** Skip every dataLayer and global write. For tests, and for an app that runs no tags. */
+  silent?: boolean
+  /**
+   * Cross-domain consent: share this decision, and adopt one, between the listed first-party
+   * domains — a visitor who already decided on one need not decide again on another. See
+   * `consentLinker`/`ConsentPlugin` in `./plugins.js` and `./linker.js`.
+   */
+  linker?: ConsentLinkerOptions
+}
+
+export interface ConsentLinkerOptions {
+  /**
+   * Every domain this decision is shared with, the current host included or not — either way, the
+   * current host is always part of the disclosed list (`consentDomains`), since a visitor reads
+   * "applies to" as the whole set, not just the others.
+   */
+  domains: string[]
+  /** The URL parameter a decorated link carries the decision in. Defaults to `owlcc`. */
+  param?: string
+  /** How old a decorated link's timestamp may be and still be trusted, in seconds. Defaults to 300. */
+  maxAge?: number
+  /**
+   * Carry the visitor's interface language along with the decision, so a visitor reading the site
+   * in Polish arrives on the next domain in Polish. Its PRESENCE turns the sending side on (a link
+   * to a listed domain carries this document's `<html lang>`); `supported` turns the receiving side
+   * on — which stores the carried language whatever the cookie decision says, because the interface
+   * language is strictly necessary. See `ConsentLinkerLanguage`.
+   */
+  language?: ConsentLinkerLanguage
+}
+
+export interface ConsentLinkerLanguage {
+  /**
+   * RECEIVING side: the languages this application can render. A carried language is adopted only
+   * when it is one of these, exactly or by its base tag (`de-DE` → `de`), and is then stored at
+   * once — the interface language is strictly necessary storage, so no cookie decision gates it;
+   * anything else is ignored and the application keeps choosing its own. Leave it out on a site
+   * that only SENDS its language.
+   */
+  supported?: string[]
+  /**
+   * RECEIVING side: the `localStorage` key an explicit language choice lives under. Defaults to
+   * `owlmeans-lng`, the key `@owlmeans/client-i18n` reads before it renders anything.
+   */
+  storageKey?: string
+}
+
+/** Why the dialog is open. `login` is what the sign-in precondition raises. */
+export type ConsentReason = 'initial' | 'reopen' | 'login' | string
+
+export interface ConsentState {
+  record: ConsentRecord | null
+  open: boolean
+  reason: ConsentReason | null
+}
+
+export type 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. */
+  init: (opts?: ConsentOptions) => void
+  save: (record: ConsentRecord) => void
+  acceptAll: () => void
+  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 }
+}
+
+export type ConsentLocale = (typeof CONSENT_LOCALES)[number]
+
+/** 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[]
+}

package/tests/consent.spec.ts

@@ -0,0 +1,256 @@
+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,
+} from '../src/consts.js'
+import { migrateConsent, readConsent, writeConsent, clearConsent } from '../src/storage.js'
+import { applyConsent, consentDefaults, consentUpdate, consentBootstrapScript } from '../src/gtm.js'
+import { makeConsentStore } from '../src/store.js'
+import {
+  DEFAULT_CONSENT_MESSAGES, defaultConsentTranslate, interpolate, normalizeLocale,
+} from '../src/i18n.js'
+import type { ConsentCategory } from '../src/types.js'
+
+/** A minimal browser: just the two stores this package writes to. */
+const browser = () => {
+  const store = new Map<string, string>()
+  let cookie = ''
+  ;(globalThis as any).localStorage = {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => { store.set(k, v) },
+    removeItem: (k: string) => { store.delete(k) },
+  }
+  ;(globalThis as any).document = {
+    get cookie() { return cookie },
+    set cookie(value: string) {
+      const [pair] = value.split(';')
+      cookie = cookie === '' ? pair : `${cookie}; ${pair}`
+    },
+  }
+  ;(globalThis as any).window = globalThis
+  return { store, raw: () => cookie, reset: () => { store.clear(); cookie = '' } }
+}
+
+const env = browser()
+
+beforeEach(() => {
+  env.reset()
+  delete (globalThis as any).dataLayer
+  delete (globalThis as any).cookieConsentSetup
+})
+
+describe('storage', () => {
+  test('a record round-trips through localStorage', () => {
+    writeConsent({ [CONSENT_ANALYTICS]: true, [CONSENT_MARKETING]: false })
+
+    expect(readConsent()?.[CONSENT_ANALYTICS]).toBe(true)
+    expect(readConsent()?.[CONSENT_MARKETING]).toBe(false)
+  })
+
+  test('the cookie answers when localStorage does not', () => {
+    writeConsent({ [CONSENT_ANALYTICS]: true })
+    env.store.clear()
+
+    expect(readConsent()?.[CONSENT_ANALYTICS]).toBe(true)
+  })
+
+  test('the cookie is path-wide, SameSite=Lax and long-lived', () => {
+    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()
+  })
+
+  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)
+
+    expect(migrated?.[CONSENT_ESSENTIAL]).toBe(true)
+    expect(migrated?.[CONSENT_ANALYTICS]).toBe(true)
+    expect(migrated?.v).toBe(CONSENT_SCHEMA_VERSION)
+  })
+
+  test('a current record is returned unchanged', () => {
+    const current = { essential: true, analytics: false, v: CONSENT_SCHEMA_VERSION }
+
+    expect(migrateConsent(current)).toBe(current)
+  })
+
+  test('nothing stored reads as null', () => {
+    clearConsent()
+
+    expect(readConsent()).toBeNull()
+  })
+})
+
+describe('consent mode signals', () => {
+  test('defaults deny everything except security storage', () => {
+    const defaults = consentDefaults()
+
+    expect(defaults.analytics_storage).toBe('denied')
+    expect(defaults.ad_storage).toBe('denied')
+    expect(defaults.ad_user_data).toBe('denied')
+    expect(defaults.ad_personalization).toBe('denied')
+    expect(defaults.security_storage).toBe('granted')
+  })
+
+  test('an update maps each category onto the signals it drives', () => {
+    const update = consentUpdate({ [CONSENT_ANALYTICS]: true, [CONSENT_MARKETING]: false })
+
+    expect(update.analytics_storage).toBe('granted')
+    expect(update.ad_storage).toBe('denied')
+    // Required categories are granted whether or not the record says so.
+    expect(update.security_storage).toBe('granted')
+  })
+
+  test('a custom category set drives only the signals it names', () => {
+    const categories: ConsentCategory[] = [
+      { 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' })
+  })
+})
+
+describe('applyConsent dispatches a DOM event', () => {
+  test('fires CONSENT_EVENT with the record after writing globals and pushing the update', () => {
+    const seen: unknown[] = []
+    const listener = (event: Event) => { seen.push((event as CustomEvent).detail) }
+    ;(globalThis as any).addEventListener(CONSENT_EVENT, listener)
+
+    try {
+      applyConsent({ [CONSENT_ANALYTICS]: true })
+
+      expect(seen).toEqual([{ record: { [CONSENT_ANALYTICS]: true } }])
+    } finally {
+      ;(globalThis as any).removeEventListener(CONSENT_EVENT, listener)
+    }
+  })
+
+  test('silent mode dispatches nothing', () => {
+    const seen: unknown[] = []
+    const listener = (event: Event) => { seen.push((event as CustomEvent).detail) }
+    ;(globalThis as any).addEventListener(CONSENT_EVENT, listener)
+
+    try {
+      applyConsent({ [CONSENT_ANALYTICS]: true }, { silent: true })
+
+      expect(seen).toEqual([])
+    } finally {
+      ;(globalThis as any).removeEventListener(CONSENT_EVENT, listener)
+    }
+  })
+})
+
+describe('the bootstrap script', () => {
+  const script = consentBootstrapScript()
+
+  test('declares the defaults before anything else can', () => {
+    expect(script).toContain("'consent','default'")
+    expect(script.indexOf("'consent','default'")).toBeLessThan(script.indexOf("'consent','update'"))
+  })
+
+  test('is idempotent through the setup flag', () => {
+    expect(script).toContain('cookieConsentSetup')
+  })
+
+  test('reads the same storage key the package writes', () => {
+    expect(script).toContain(JSON.stringify(CONSENT_KEY))
+  })
+
+  test('pushes arguments, the shape gtag.js itself emits', () => {
+    expect(script).toContain('w.dataLayer.push(arguments)')
+  })
+})
+
+describe('the store', () => {
+  test('opens when nothing is stored, and stays shut when something is', () => {
+    const first = makeConsentStore()
+    first.init({ silent: true })
+
+    expect(first.get().open).toBe(true)
+    expect(first.get().reason).toBe('initial')
+
+    first.save({ [CONSENT_ANALYTICS]: true })
+
+    const second = makeConsentStore()
+    second.init({ silent: true })
+
+    expect(second.get().open).toBe(false)
+  })
+
+  test('a required category is granted whether or not the record says so', () => {
+    const store = makeConsentStore()
+    store.init({ silent: true })
+    store.save({ [CONSENT_ANALYTICS]: false })
+
+    expect(store.granted(CONSENT_ESSENTIAL)).toBe(true)
+    expect(store.granted(CONSENT_ANALYTICS)).toBe(false)
+  })
+
+  test('accept-all grants every category', () => {
+    const store = makeConsentStore()
+    store.init({ silent: true })
+    store.acceptAll()
+
+    expect(DEFAULT_CONSENT_CATEGORIES.every(c => store.granted(c.key))).toBe(true)
+  })
+
+  test('subscribers see every transition', () => {
+    const store = makeConsentStore()
+    const seen: boolean[] = []
+    store.subscribe(state => seen.push(state.open))
+    store.init({ silent: true })
+    store.acceptAll()
+    store.open('reopen')
+
+    expect(seen).toEqual([true, false, true])
+  })
+})
+
+describe('the built-in translations', () => {
+  test('every locale carries every key of English', () => {
+    // Without this, a language added to the bundle ships with English strings in it and nothing
+    // reports it — the readers who cannot tell us are exactly the ones affected.
+    const keys = Object.keys(require('../src/i18n/en.json') as Record<string, string>)
+    // Driven by the shipped locale list, so a language added there is checked without anyone
+    // remembering to add it here — French was once in the list and missing from this loop.
+    for (const lng of CONSENT_LOCALES.filter(locale => locale !== 'en')) {
+      const bundle = require(`../src/i18n/${lng}.json`) as Record<string, string>
+      expect({ lng, missing: keys.filter(key => bundle[key] == null) })
+        .toEqual({ lng, missing: [] })
+    }
+  })
+
+  test('every locale keeps every placeholder English has', () => {
+    // A translation that drops `{{provider}}` still renders — just without the name of the company
+    // the link belongs to, which is the one word of that line a reader needed.
+    const en = DEFAULT_CONSENT_MESSAGES.en
+    const placeholders = (text: string) => (text.match(/\{\{[a-z]+\}\}/gi) ?? []).sort()
+    for (const lng of CONSENT_LOCALES) {
+      const bundle = DEFAULT_CONSENT_MESSAGES[lng]
+      const drifted = Object.keys(en).filter(key =>
+        typeof bundle[key] === 'string'
+        && placeholders(bundle[key]).join() !== placeholders(en[key]).join())
+      expect({ lng, drifted }).toEqual({ lng, drifted: [] })
+    }
+  })
+
+  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')
+  })
+
+  test('a key nobody translated returns the supplied default', () => {
+    expect(defaultConsentTranslate('en')('nope', 'the default')).toBe('the default')
+  })
+
+  test('placeholders interpolate', () => {
+    expect(interpolate('kept for {{days}} days', { days: 365 })).toBe('kept for 365 days')
+  })
+})