@owlmeans/consent 0.1.18-rc.8 → 0.1.18

package/src/store.ts

@@ -1,15 +1,16 @@
 import {
-  CONSENT_FUNCTIONAL, CONSENT_KEY, CONSENT_LANGUAGE_EVENT, CONSENT_PENDING_LANGUAGE,
-  DEFAULT_CONSENT_CATEGORIES,
+  CONSENT_IDLE_STATE, CONSENT_KEY, CONSENT_STATE_ATTRIBUTE, DEFAULT_CONSENT_CATEGORIES,
 } from './consts.js'
-import { purgeFunctionalStorage } from './functional.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 { 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.
@@ -21,49 +22,73 @@ 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 = {}
-  // A language that arrived with a link (or was chosen) before the visitor granted functional
-  // storage. Memory only — it is never written until the grant, and it dies with the page.
-  let pendingLanguage: string | null = null
+  /** 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 } => ({
+    ...options,
+    categories: options.categories ?? DEFAULT_CONSENT_CATEGORIES,
+    storageKey: options.storageKey ?? CONSENT_KEY,
+  })
+
+  const ask = (): void => {
+    publish({ record: null, open: true, reason: 'initial', locating: null })
   }
 
   /**
-   * Bring functional storage in line with the record, now.
-   *
-   * Granted: a language that was waiting is written, and the application is told (`CONSENT_LANGUAGE_EVENT`)
-   * so it can switch this very page instead of the next load. Not granted — a refusal, a withdrawal,
-   * or a record that never answered the question — every functional key is REMOVED: a preference
-   * must not outlive the consent to remember it. What was waiting stays waiting; the visitor may
-   * still grant it later in this page's life.
+   * 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 settleFunctional = (): void => {
-    if (state.record?.[CONSENT_FUNCTIONAL] !== true) {
-      purgeFunctionalStorage(options)
+  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 (pendingLanguage == null) {
+    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
     }
-    const language = pendingLanguage
-    pendingLanguage = null
-    if (writeConsentLanguage(language, options) && typeof window !== 'undefined'
-      && typeof window.dispatchEvent === 'function' && typeof CustomEvent === 'function') {
-      window.dispatchEvent(new CustomEvent(CONSENT_LANGUAGE_EVENT, { detail: { language } }))
+    if (pending != null) {
+      // A grant derived somewhere nobody had to be asked does not survive arriving where they must.
+      consentStorageHelper.clearConsent(options)
     }
+    ask()
   }
 
-  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,
 
@@ -76,58 +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) {
-        // What the link carried, or what the inline head fragment already took off it and left on
-        // `window` (it strips the parameter, so this is the only place that still knows). Held, not
-        // written: whether it may be stored is settled below, against the record.
-        const win = typeof window !== 'undefined' ? window as unknown as Record<string, unknown> : null
-        const inline = win?.[CONSENT_PENDING_LANGUAGE]
-        pendingLanguage = adoptConsentLanguage(options) ?? (typeof inline === 'string' ? inline : pendingLanguage)
-        if (win != null && inline !== undefined) {
-          delete win[CONSENT_PENDING_LANGUAGE]
+        // 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 = consentPluginHelper.adoptConsentLanguage(options)
+        if (carried != null) {
+          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 })
-        settleFunctional()
+        consentModeHelper.applyConsent(record, options)
+        publish({ record, open: false, reason: null, locating: null })
 
         return
       }
-      publish({ record: null, open: true, reason: 'initial' })
-      settleFunctional()
+      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 })
-      // After the record is stored: `writeConsentLanguage` reads it back to decide.
-      settleFunctional()
+      const { auto: _auto, ...explicit } = record
+      consentStorageHelper.writeConsent(explicit, options)
+      consentModeHelper.applyConsent(explicit, options)
+      publish({ record: explicit, open: false, reason: null, locating: null })
     },
 
     acceptAll: () => {
@@ -137,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 }) },
 
@@ -152,7 +203,9 @@ export const makeConsentStore = (): ConsentStore => {
 
     options: resolved,
 
-    pendingLanguage: () => pendingLanguage,
+    settled: () => state.locating == null && lookup == null
+      ? Promise.resolve(state)
+      : new Promise(resolve => { waiting.add(resolve) }),
   }
 
   return store
@@ -160,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'
@@ -20,7 +22,7 @@ export interface ConsentCategory {
    * 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. */
+  /** Resolved through `translate`; the built-in bundle supplies the default set in 8 languages. */
   labelKey: string
   descriptionKey: string
   /**
@@ -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
@@ -85,19 +135,14 @@ export interface ConsentOptions {
   cookieDomain?: string
   /** Skip every dataLayer and global write. For tests, and for an app that runs no tags. */
   silent?: boolean
-  /**
-   * The `localStorage` keys that hold this application's functional preferences (the interface
-   * language, today). They may exist only while the visitor has granted `functional`: `init` and
-   * `save` remove every one of them the moment it is not granted. Defaults to the language key
-   * (`owlmeans-lng`); `linker.language.storageKey` is always included.
-   */
-  functionalKeys?: string[]
   /**
    * 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
+  /** Ask only in consent-requiring countries — see `ConsentGeoOptions`. Off when absent. */
+  geo?: ConsentGeoOptions
 }
 
 export interface ConsentLinkerOptions {
@@ -115,8 +160,8 @@ export interface ConsentLinkerOptions {
    * 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 still stores nothing until functional storage is granted there. See
-   * `ConsentLinkerLanguage`.
+   * on — which stores the carried language whatever the cookie decision says, because the interface
+   * language is strictly necessary. See `ConsentLinkerLanguage`.
    */
   language?: ConsentLinkerLanguage
 }
@@ -124,48 +169,131 @@ export interface ConsentLinkerOptions {
 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`). It is stored only while
-   * the visitor has granted `functional` on this document — until then it is held in memory, and
-   * stored if they grant it later in this page's life (`CONSENT_LANGUAGE_EVENT` tells the app);
+   * 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. It is a
-   * functional key: written only while `functional` is granted, removed when it is not.
+   * `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
+/**
+ * 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
   /**
-   * A language that arrived with a link and is waiting for the visitor to grant `functional`
-   * storage — memory only, or `null`. It is written (and `CONSENT_LANGUAGE_EVENT` dispatched) the
-   * moment the grant is saved.
+   * 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.
    */
-  pendingLanguage: () => string | null
-  options: () => ConsentOptions & { categories: ConsentCategory[], storageKey: string }
+  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>
 }