@owlmeans/consent 0.1.18-rc.2

package/src/i18n/pl.json

@@ -0,0 +1,25 @@
+{
+  "title": "Preferencje dotyczące plików cookie",
+  "description": "Używamy plików cookie w celu ulepszenia Twojego doświadczenia podczas przeglądania, wyświetlania spersonalizowanych reklam lub treści oraz analizowania naszego ruchu. Klikając „Akceptuj wszystkie\", wyrażasz zgodę na używanie przez nas plików cookie.",
+  "essential": "Niezbędne pliki cookie",
+  "essentialDesc": "Wymagane do działania witryny — logowanie, bezpieczeństwo i zapamiętanie tych ustawień. Nie można ich wyłączyć.",
+  "analytics": "Analityczne pliki cookie",
+  "analyticsDesc": "Pomagają nam ulepszać naszą witrynę internetową, zbierając i raportując informacje o jej użytkowaniu.",
+  "marketing": "Marketingowe pliki cookie",
+  "marketingDesc": "Służą do śledzenia odwiedzających na różnych stronach internetowych w celu wyświetlania trafnych reklam, dostosowanych do konkretnego użytkownika.",
+  "required": "Wymagane",
+  "acceptAll": "Akceptuj wszystkie",
+  "acceptAndContinue": "Akceptuj i kontynuuj",
+  "savePreferences": "Zapisz preferencje",
+  "policyLink": "Polityka plików cookie",
+  "openPreferences": "Preferencje plików cookie",
+  "close": "Zamknij",
+  "loginReason": "Logowanie zapisuje plik cookie sesji. Zaakceptuj niezbędne pliki cookie, aby kontynuować.",
+  "manage": "Zarządzaj preferencjami",
+  "policyTitle": "Polityka plików cookie",
+  "policyIntro": "Ta strona opisuje pliki cookie i podobne mechanizmy przechowywania używane przez tę aplikację oraz sposób ich kontrolowania.",
+  "policyStorage": "Twój wybór jest zapisywany w tej przeglądarce pod kluczem „{{key}}\" — zarówno w pamięci lokalnej, jak i w pliku cookie.",
+  "policyRetention": "Zapis jest przechowywany przez {{days}} dni, po czym zapytamy ponownie.",
+  "policyOperator": "Tę aplikację prowadzi {{operator}}.",
+  "policyContact": "Zapoznaj się z ich polityką prywatności i regulaminem, aby dowiedzieć się, jak przetwarzają Twoje dane."
+}

package/src/i18n/ru.json

@@ -0,0 +1,25 @@
+{
+  "title": "Настройки файлов cookie",
+  "description": "Мы используем файлы cookie, чтобы улучшить ваш опыт просмотра, показывать персонализированную рекламу или контент и анализировать наш трафик. Нажимая «Принять все», вы соглашаетесь на использование файлов cookie.",
+  "essential": "Необходимые файлы cookie",
+  "essentialDesc": "Нужны для работы сайта — вход, безопасность и сохранение этих настроек. Их нельзя отключить.",
+  "analytics": "Аналитические файлы cookie",
+  "analyticsDesc": "Помогают нам улучшать наш сайт, собирая и предоставляя информацию о его использовании.",
+  "marketing": "Маркетинговые файлы cookie",
+  "marketingDesc": "Используются для отслеживания посетителей на разных сайтах для показа релевантной и интересной рекламы.",
+  "required": "Обязательно",
+  "acceptAll": "Принять все",
+  "acceptAndContinue": "Принять и продолжить",
+  "savePreferences": "Сохранить настройки",
+  "policyLink": "Политика использования файлов cookie",
+  "openPreferences": "Настройки файлов cookie",
+  "close": "Закрыть",
+  "loginReason": "Вход сохраняет сессионный файл cookie. Примите необходимые файлы cookie, чтобы продолжить.",
+  "manage": "Изменить настройки",
+  "policyTitle": "Политика использования файлов cookie",
+  "policyIntro": "На этой странице описаны файлы cookie и подобные хранилища, которые использует это приложение, и как ими управлять.",
+  "policyStorage": "Ваш выбор сохраняется в этом браузере под ключом «{{key}}» — и в локальном хранилище, и в файле cookie.",
+  "policyRetention": "Запись хранится {{days}} дней, после чего мы спросим снова.",
+  "policyOperator": "Это приложение принадлежит {{operator}}.",
+  "policyContact": "Ознакомьтесь с их политикой конфиденциальности и условиями использования, чтобы узнать, как они обрабатывают ваши данные."
+}

package/src/i18n/uk.json

@@ -0,0 +1,25 @@
+{
+  "title": "Налаштування файлів cookie",
+  "description": "Ми використовуємо файли cookie, щоб покращити ваш досвід перегляду, показувати персоналізовану рекламу чи вміст і аналізувати наш трафік. Натискаючи «Прийняти всі», ви погоджуєтеся на використання файлів cookie.",
+  "essential": "Необхідні файли cookie",
+  "essentialDesc": "Потрібні для роботи сайту — вхід, безпека та збереження цих налаштувань. Їх не можна вимкнути.",
+  "analytics": "Аналітичні файли cookie",
+  "analyticsDesc": "Допомагають нам покращувати наш вебсайт, збираючи та надаючи інформацію про його використання.",
+  "marketing": "Маркетингові файли cookie",
+  "marketingDesc": "Використовуються для відстеження відвідувачів на різних вебсайтах для показу релевантної та цікавої реклами.",
+  "required": "Обов'язково",
+  "acceptAll": "Прийняти всі",
+  "acceptAndContinue": "Прийняти й продовжити",
+  "savePreferences": "Зберегти налаштування",
+  "policyLink": "Політика щодо файлів cookie",
+  "openPreferences": "Налаштування файлів cookie",
+  "close": "Закрити",
+  "loginReason": "Вхід зберігає сеансовий файл cookie. Прийміть необхідні файли cookie, щоб продовжити.",
+  "manage": "Змінити налаштування",
+  "policyTitle": "Політика щодо файлів cookie",
+  "policyIntro": "Ця сторінка описує файли cookie та подібні сховища, які використовує цей застосунок, і як ними керувати.",
+  "policyStorage": "Ваш вибір зберігається в цьому браузері під ключем «{{key}}» — і в локальному сховищі, і у файлі cookie.",
+  "policyRetention": "Запис зберігається {{days}} днів, після чого ми запитаємо знову.",
+  "policyOperator": "Цей застосунок належить {{operator}}.",
+  "policyContact": "Ознайомтеся з їхньою політикою конфіденційності та умовами користування, щоб дізнатися, як вони обробляють ваші дані."
+}

package/src/i18n.ts

@@ -0,0 +1,38 @@
+import { CONSENT_LOCALES } from './consts.js'
+import type { ConsentLocale } from './consts.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' }
+
+/**
+ * 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,
+}
+
+export const normalizeLocale = (locale?: string): ConsentLocale => {
+  const base = (locale ?? 'en').toLowerCase().split('-')[0]
+
+  return CONSENT_LOCALES.includes(base as ConsentLocale) ? base as ConsentLocale : 'en'
+}
+
+/** `(key, defaultValue) => string`, the house shape, backed by the built-in bundle. */
+export const defaultConsentTranslate = (locale?: string) =>
+  (key: string, defaultValue: string): string =>
+    DEFAULT_CONSENT_MESSAGES[normalizeLocale(locale)]?.[key] ?? defaultValue
+
+/** Substitute `{{name}}` placeholders. Enough for the two the policy page needs. */
+export const interpolate = (text: string, values: Record<string, string | number>): string =>
+  text.replace(/\{\{([a-z]+)\}\}/gi, (whole, name: string) =>
+    values[name] != null ? String(values[name]) : whole)

package/src/index.ts

@@ -0,0 +1,6 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './storage.js'
+export * from './gtm.js'
+export * from './store.js'
+export * from './i18n.js'

package/src/storage.ts

@@ -0,0 +1,96 @@
+import {
+  CONSENT_COOKIE_DAYS, CONSENT_ESSENTIAL, CONSENT_KEY, CONSENT_SCHEMA_VERSION,
+} from './consts.js'
+import type { ConsentOptions, ConsentRecord } from './types.js'
+
+const key = (opts?: ConsentOptions): string => opts?.storageKey ?? CONSENT_KEY
+
+const parse = (raw: string | null | undefined): ConsentRecord | null => {
+  if (raw == null || raw === '') {
+    return null
+  }
+  try {
+    const value = JSON.parse(raw) as unknown
+
+    return value != null && typeof value === 'object' ? value as ConsentRecord : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Bring a stored record up to the current shape.
+ *
+ * A record with no `v` was written before the essential category existed, when it was implicitly
+ * always granted. The visitor DID choose; upgrading in place honours that choice, where treating
+ * the record as unusable would re-prompt everyone who has ever visited.
+ */
+export const migrateConsent = (raw: ConsentRecord | null): ConsentRecord | null =>
+  raw == null ? null
+    : raw.v === CONSENT_SCHEMA_VERSION ? raw
+      : { ...raw, [CONSENT_ESSENTIAL]: true, v: CONSENT_SCHEMA_VERSION }
+
+const fromCookie = (name: string): string | null => {
+  if (typeof document === 'undefined') {
+    return null
+  }
+  const parts = `; ${document.cookie}`.split(`; ${name}=`)
+
+  return parts.length === 2 ? parts.pop()?.split(';').shift() ?? null : null
+}
+
+/**
+ * What this browser has already chosen, or null.
+ *
+ * localStorage first and the cookie second, because that is the order the widget this generalises
+ * used and the two can disagree: a visitor who cleared site data but kept cookies still has an
+ * answer, and asking them again would be wrong.
+ */
+export const readConsent = (opts?: ConsentOptions): ConsentRecord | null => {
+  const name = key(opts)
+  let raw: string | null = null
+  try {
+    raw = typeof localStorage !== 'undefined' ? localStorage.getItem(name) : null
+  } catch { /* private modes and blocked storage both throw; the cookie may still answer */ }
+
+  return migrateConsent(parse(raw) ?? parse(fromCookie(name)))
+}
+
+/**
+ * Record the choice in both places.
+ *
+ * Two stores rather than one because neither is reliable alone: localStorage is cleared by "clear
+ * site data" while the cookie survives it, and the cookie is refused where third-party storage is
+ * blocked while localStorage may not be.
+ */
+export const writeConsent = (record: ConsentRecord, opts?: ConsentOptions): void => {
+  const name = key(opts)
+  const value = JSON.stringify({ ...record, v: CONSENT_SCHEMA_VERSION })
+  try {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(name, value)
+    }
+  } catch { /* the cookie below is the fallback */ }
+
+  if (typeof document === 'undefined') {
+    return
+  }
+  const days = opts?.cookieDays ?? CONSENT_COOKIE_DAYS
+  const expires = new Date(Date.now() + days * 24 * 60 * 60 * 1000).toUTCString()
+  const domain = opts?.cookieDomain != null ? `;domain=${opts.cookieDomain}` : ''
+  // `SameSite=Lax` is stated rather than left to the browser default, which differs between them.
+  // This cookie is never sent cross-site on purpose — it records a preference, not a session.
+  document.cookie = `${name}=${value};expires=${expires};path=/;SameSite=Lax${domain}`
+}
+
+export const clearConsent = (opts?: ConsentOptions): void => {
+  const name = key(opts)
+  try {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.removeItem(name)
+    }
+  } catch { /* nothing to remove if storage was never available */ }
+  if (typeof document !== 'undefined') {
+    document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`
+  }
+}

package/src/store.ts

@@ -0,0 +1,94 @@
+import { CONSENT_KEY, DEFAULT_CONSENT_CATEGORIES } from './consts.js'
+import { applyConsent, pushConsentDefaults } from './gtm.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)
+
+      const record = readConsent(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.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+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 7 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
+}
+
+/** `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
+}
+
+/** 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 }
+}

package/tests/consent.spec.ts

@@ -0,0 +1,208 @@
+import { describe, test, expect, beforeEach } from 'bun:test'
+import {
+  CONSENT_ANALYTICS, CONSENT_ESSENTIAL, CONSENT_KEY, CONSENT_MARKETING, CONSENT_SCHEMA_VERSION,
+  DEFAULT_CONSENT_CATEGORIES,
+} from '../src/consts.js'
+import { migrateConsent, readConsent, writeConsent, clearConsent } from '../src/storage.js'
+import { consentDefaults, consentUpdate, consentBootstrapScript } from '../src/gtm.js'
+import { makeConsentStore } from '../src/store.js'
+import { 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('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>)
+    for (const lng of ['pl', 'ru', 'be', 'uk', 'es', 'de']) {
+      const bundle = require(`../src/i18n/${lng}.json`) as Record<string, string>
+      expect({ lng, missing: keys.filter(key => bundle[key] == null) })
+        .toEqual({ lng, missing: [] })
+    }
+  })
+
+  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')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json"
+  ],
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}