@owlmeans/consent 0.1.18-rc.8 → 0.1.18

package/src/plugins/types.ts

@@ -0,0 +1,42 @@
+import type { ConsentGeoLocation, ConsentOptions, ConsentPlugin, ConsentRecord } from '../types.js'
+
+/** The document's consent-plugin registry and the hooks run over every registered plugin. */
+export interface ConsentPluginHelper {
+  /** Register a plugin. Replace-by-alias; sorted by priority (higher first) on every read. */
+  registerConsentPlugin: (plugin: ConsentPlugin) => void
+  /** Remove a plugin by alias — for a test, or an application tearing a locator down. */
+  unregisterConsentPlugin: (alias: string) => void
+  /** Every registered plugin, priority-sorted (higher first, ties keep insertion order). */
+  consentPlugins: () => ConsentPlugin[]
+  /**
+   * Ask every registered plugin to decorate `url` with this document's decision, in priority order,
+   * stopping at the first one that actually changes it. A plugin whose own rules refuse (a foreign
+   * host, a `noreferrer` link, no local decision yet) returns `null` and is skipped, not an error.
+   */
+  decorateConsentUrl: (url: string | URL, record: ConsentRecord | null, opts: ConsentOptions) => URL
+  /**
+   * Every domain this document's decision is disclosed to, current host first, deduplicated — what a
+   * dialog or a policy page lists. A plugin that runs on this host but names no domains of its own
+   * (nothing registered, or `domains` not implemented) leaves the list at just the current host,
+   * which is always correct to show even with no plugin at all.
+   */
+  consentDomains: (opts: ConsentOptions) => string[]
+  /** Try every registered plugin's `adopt`, in priority order, and use the first decision offered. */
+  adoptConsent: (opts: ConsentOptions) => ConsentRecord | null
+  /**
+   * Try every registered plugin's `adoptLanguage`, in priority order, and use the first language
+   * offered. The caller persists it (`writeConsentLanguage`) — and has to do that BEFORE its i18n
+   * layer reads storage, which is why the inline `<head>` fragment (`consentLinkerScript`) is the
+   * one that normally does.
+   */
+  adoptConsentLanguage: (opts: ConsentOptions) => string | null
+  /** Run every registered plugin's `start`, in priority order. `consentStore.init` calls this once. */
+  startConsentPlugins: (opts: ConsentOptions) => void
+  /**
+   * Ask every registered plugin's `locate`, in priority order, for the visitor's country: the first
+   * usable ISO alpha-2 code wins (upper-cased). A throw, or a code that names no country
+   * (`CONSENT_GEO_UNKNOWN`, anything malformed), hands over to the next locator; with none left it
+   * rejects with the last failure. Timeouts are the caller's (`consentGeoHelper.decide`).
+   */
+  locateConsent: (opts: ConsentOptions) => Promise<ConsentGeoLocation>
+}

package/src/plugins.ts

@@ -1,46 +1,7 @@
-import type { ConsentOptions, ConsentRecord } from './types.js'
-
-/**
- * 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 persisting it is
-   * `writeConsentLanguage`'s call, which refuses until `functional` is granted on this document.
-   */
-  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[]
-}
+import { CONSENT_GEO_UNKNOWN } from './consts.js'
+import { COUNTRY_CODE } from './consts.local.js'
+import type { ConsentGeoLocation, ConsentOptions, ConsentRecord, ConsentPlugin } from './types.js'
+import type { ConsentPluginHelper } from './plugins/types.js'
 
 /**
  * Module-global by design, like `@owlmeans/client-auth/login`'s method/step registries: consent is
@@ -49,83 +10,98 @@ export interface ConsentPlugin {
  */
 const plugins = new Map<string, ConsentPlugin>()
 
-/** Register a plugin. Replace-by-alias; sorted by priority (higher first) on every read. */
-export const registerConsentPlugin = (plugin: ConsentPlugin): void => {
-  plugins.set(plugin.alias, plugin)
-}
+export const createConsentPluginHelper = (): ConsentPluginHelper => {
+  const registerConsentPlugin = (plugin: ConsentPlugin): void => {
+    plugins.set(plugin.alias, plugin)
+  }
 
-/** Every registered plugin, priority-sorted (higher first, ties keep insertion order). */
-export const consentPlugins = (): ConsentPlugin[] =>
-  [...plugins.values()].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+  const unregisterConsentPlugin = (alias: string): void => {
+    plugins.delete(alias)
+  }
 
-/**
- * Ask every registered plugin to decorate `url` with this document's decision, in priority order,
- * stopping at the first one that actually changes it. A plugin whose own rules refuse (a foreign
- * host, a `noreferrer` link, no local decision yet) returns `null` and is skipped, not an error.
- */
-export const decorateConsentUrl = (
-  url: string | URL, record: ConsentRecord | null, opts: ConsentOptions
-): URL => {
-  let result = url instanceof URL ? url : new URL(url)
-  for (const plugin of consentPlugins()) {
-    if (plugin.decorate == null) {
-      continue
-    }
-    const decorated = plugin.decorate(result, record, opts)
-    if (decorated != null) {
-      result = decorated
+  const consentPlugins = (): ConsentPlugin[] =>
+    [...plugins.values()].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+
+  const decorateConsentUrl = (
+    url: string | URL, record: ConsentRecord | null, opts: ConsentOptions
+  ): URL => {
+    let result = url instanceof URL ? url : new URL(url)
+    for (const plugin of consentPlugins()) {
+      if (plugin.decorate == null) {
+        continue
+      }
+      const decorated = plugin.decorate(result, record, opts)
+      if (decorated != null) {
+        result = decorated
+      }
     }
-  }
 
-  return result
-}
+    return result
+  }
 
-/**
- * Every domain this document's decision is disclosed to, current host first, deduplicated — what a
- * dialog or a policy page lists. A plugin that runs on this host but names no domains of its own
- * (nothing registered, or `domains` not implemented) leaves the list at just the current host,
- * which is always correct to show even with no plugin at all.
- */
-export const consentDomains = (opts: ConsentOptions): string[] => {
-  const host = typeof location !== 'undefined' ? location.hostname : ''
-  const named = consentPlugins().flatMap(plugin => plugin.domains?.(opts) ?? [])
+  const consentDomains = (opts: ConsentOptions): string[] => {
+    const host = typeof location !== 'undefined' ? location.hostname : ''
+    const named = consentPlugins().flatMap(plugin => plugin.domains?.(opts) ?? [])
 
-  return [...new Set([host, ...named].filter(domain => domain !== ''))]
-}
+    return [...new Set([host, ...named].filter(domain => domain !== ''))]
+  }
 
-/** Try every registered plugin's `adopt`, in priority order, and use the first decision offered. */
-export const adoptConsent = (opts: ConsentOptions): ConsentRecord | null => {
-  for (const plugin of consentPlugins()) {
-    const adopted = plugin.adopt?.(opts)
-    if (adopted != null) {
-      return adopted
+  const adoptConsent = (opts: ConsentOptions): ConsentRecord | null => {
+    for (const plugin of consentPlugins()) {
+      const adopted = plugin.adopt?.(opts)
+      if (adopted != null) {
+        return adopted
+      }
     }
+
+    return null
   }
 
-  return null
-}
+  const adoptConsentLanguage = (opts: ConsentOptions): string | null => {
+    for (const plugin of consentPlugins()) {
+      const adopted = plugin.adoptLanguage?.(opts)
+      if (adopted != null) {
+        return adopted
+      }
+    }
 
-/**
- * Try every registered plugin's `adoptLanguage`, in priority order, and use the first language
- * offered. The caller persists it (`writeConsentLanguage`, which refuses until `functional` is
- * granted) — and has to do that BEFORE its i18n
- * layer reads storage, which is why the inline `<head>` fragment (`consentLinkerScript`) is the
- * one that normally does.
- */
-export const adoptConsentLanguage = (opts: ConsentOptions): string | null => {
-  for (const plugin of consentPlugins()) {
-    const adopted = plugin.adoptLanguage?.(opts)
-    if (adopted != null) {
-      return adopted
+    return null
+  }
+
+  const startConsentPlugins = (opts: ConsentOptions): void => {
+    for (const plugin of consentPlugins()) {
+      plugin.start?.(opts)
     }
   }
 
-  return null
-}
+  const locateConsent = async (opts: ConsentOptions): Promise<ConsentGeoLocation> => {
+    let failure: unknown = new Error('consent:geo:no-locator')
+    for (const plugin of consentPlugins()) {
+      if (plugin.locate == null) {
+        continue
+      }
+      try {
+        const country = (await plugin.locate(opts))?.country?.trim().toUpperCase() ?? ''
+        if (COUNTRY_CODE.test(country) && !CONSENT_GEO_UNKNOWN.includes(country)) {
+          return { country }
+        }
+        failure = new Error(`consent:geo:unusable-country:${plugin.alias}`)
+      } catch (error) {
+        failure = error
+      }
+    }
 
-/** Run every registered plugin's `start`, in priority order. `consentStore.init` calls this once. */
-export const startConsentPlugins = (opts: ConsentOptions): void => {
-  for (const plugin of consentPlugins()) {
-    plugin.start?.(opts)
+    throw failure
+  }
+
+  return {
+    registerConsentPlugin, unregisterConsentPlugin, consentPlugins, decorateConsentUrl,
+    consentDomains, adoptConsent, adoptConsentLanguage, startConsentPlugins, locateConsent,
   }
 }
+
+export const consentPluginHelper = createConsentPluginHelper()
+
+/** @deprecated compat:factory-refactor — use `consentPluginHelper.decorateConsentUrl(…)` */
+export const decorateConsentUrl = (url: string | URL, record: ConsentRecord | null, opts: ConsentOptions): URL =>
+  consentPluginHelper.decorateConsentUrl(url, record, opts)

package/src/storage/types.ts

@@ -0,0 +1,31 @@
+import type { ConsentOptions, ConsentRecord } from '../types.js'
+
+/** Where a visitor's choice is kept: localStorage first, the cookie second. */
+export interface ConsentStorageHelper {
+  /**
+   * 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.
+   */
+  migrateConsent: (raw: ConsentRecord | null) => ConsentRecord | 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.
+   */
+  readConsent: (opts?: ConsentOptions) => ConsentRecord | null
+  /**
+   * 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.
+   */
+  writeConsent: (record: ConsentRecord, opts?: ConsentOptions) => void
+  /** Forget the choice in both places. */
+  clearConsent: (opts?: ConsentOptions) => void
+}

package/src/storage.ts

@@ -2,95 +2,93 @@ import {
   CONSENT_COOKIE_DAYS, CONSENT_ESSENTIAL, CONSENT_KEY, CONSENT_SCHEMA_VERSION,
 } from './consts.js'
 import type { ConsentOptions, ConsentRecord } from './types.js'
+import type { ConsentStorageHelper } from './storage/types.js'
 
-const key = (opts?: ConsentOptions): string => opts?.storageKey ?? CONSENT_KEY
+export const createConsentStorageHelper = (): ConsentStorageHelper => {
+  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
+  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
+      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 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
   }
-  const parts = `; ${document.cookie}`.split(`; ${name}=`)
 
-  return parts.length === 2 ? parts.pop()?.split(';').shift() ?? null : null
-}
+  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 */ }
 
-/**
- * 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)))
-}
+    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 */ }
+  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
+    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}`
   }
-  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)
+  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') {
+      // The same `domain` the write used — a cookie is only replaced by one that names its domain.
+      const domain = opts?.cookieDomain != null ? `;domain=${opts.cookieDomain}` : ''
+      document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/${domain}`
     }
-  } 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=/`
   }
+
+  return { migrateConsent, readConsent, writeConsent, clearConsent }
 }
+
+export const consentStorageHelper = createConsentStorageHelper()
+
+/** @deprecated compat:factory-refactor — use `consentStorageHelper.readConsent(…)` */
+export const readConsent = (opts?: ConsentOptions): ConsentRecord | null => consentStorageHelper.readConsent(opts)
+
+/** @deprecated compat:factory-refactor — use `consentStorageHelper.writeConsent(…)` */
+export const writeConsent = (record: ConsentRecord, opts?: ConsentOptions): void =>
+  consentStorageHelper.writeConsent(record, opts)
+
+/** @deprecated compat:factory-refactor — use `consentStorageHelper.clearConsent(…)` */
+export const clearConsent = (opts?: ConsentOptions): void => consentStorageHelper.clearConsent(opts)