@owlmeans/consent 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -0,0 +1,229 @@
+# @owlmeans/consent
+
+The framework-free core of OwlMeans cookie consent: the category model, dual localStorage/cookie
+storage with in-place migration, the observable document-level `consentStore`, Google Consent Mode
+v2 signalling with the inline head scripts that must run before a tag manager loads, the built-in
+dialog copy in eight languages, and cross-domain consent through decorated links. It has **zero
+runtime dependencies**, so an Astro island or a plain script can load it. An app uses it directly
+to stamp the head snippet, read a decision outside React, or gate a loader. It renders nothing — the
+dialog, the re-open button and the cookie-policy page are `@owlmeans/web-consent` (or
+`@owlmeans/web-panel/consent` bound to OwlMeans i18n), and the Google tag snippet itself is
+`@owlmeans/web-gtm`. Per-person marketing preferences on the server are `@owlmeans/marketing-consent`,
+not this package.
+
+## Installation
+
+```bash
+bun add @owlmeans/consent@^0.1.18
+```
+
+## Concepts
+
+- **Category** — a `ConsentCategory`: a stable `key`, label/description keys, an optional
+  `globalVar` written on `window`, the Consent Mode `signals` it drives and an optional `dataLayer`
+  `event`. The defaults are `essential` (required), `analytics` and `marketing`.
+- **Required category** — always granted and rendered locked: disclosure, not a question.
+- **Record** — a `ConsentRecord` `{ v?, [categoryKey]: boolean }`, stored under
+  `site_cookie_consent` in both localStorage and a 365-day `SameSite=Lax` cookie, localStorage read
+  first. A record without `v` is migrated in place (`essential: true`, `v: 2`), never discarded.
+- **Store** — `consentStore`, a module singleton: consent belongs to the document, not to a
+  component tree, and is reachable from click handlers and non-React code.
+- **Ordering rule** — `consent/default` must be on `window.dataLayer` before the tag manager loads,
+  so it is pushed by an inline script stamped above the snippet, not by a bundle.
+- **Plugin** — a `ConsentPlugin` that can `adopt` a decision or a language from outside storage,
+  `decorate` outgoing URLs and disclose `domains`. `consentLinkHelper.consentLinker()` is the one
+  built-in plugin.
+- **Interface language** — strictly necessary storage (`owlmeans-lng`); no category governs it.
+
+## Usage
+
+### Start the store and read the decision
+
+```typescript
+import { consentStore, CONSENT_ANALYTICS } from '@owlmeans/consent'
+
+consentStore.init()   // push defaults, read + migrate, apply, open when nothing is stored
+
+const unsubscribe = consentStore.subscribe(state => {
+  if (state.open) {
+    showDialog(state.reason)   // 'initial' | 'reopen' | 'login' | custom
+  }
+})
+
+if (consentStore.granted(CONSENT_ANALYTICS)) {
+  startAnalytics()
+}
+
+consentStore.save({ essential: true, analytics: true, marketing: false })
+consentStore.acceptAll()
+consentStore.open('reopen')   // e.g. from a footer link
+```
+
+`useConsent()` in `@owlmeans/web-consent` calls `init` on mount; a host that mounts neither the
+dialog nor a tag loader calls it once itself, with the same options everything else receives.
+
+### Stamp the head snippet above the tag manager
+
+```typescript
+import { consentModeHelper } from '@owlmeans/consent'
+
+const bootstrap = consentModeHelper.consentBootstrapScript()   // defaults + the stored record
+
+// Withhold a loader until tracking is granted (now or by a later CONSENT_EVENT)
+const gated = consentModeHelper.consentGateScript(loaderIife)
+
+// Escaping `</script` / `<!--` in the composed inline script is the caller's job
+const head = `<script>${bootstrap};${gated}</script>`
+```
+
+### Custom categories
+
+```typescript
+import { DEFAULT_CONSENT_CATEGORIES, consentStore } from '@owlmeans/consent'
+import type { ConsentCategory } from '@owlmeans/consent'
+
+const categories: ConsentCategory[] = [
+  ...DEFAULT_CONSENT_CATEGORIES.filter(category => category.key !== 'marketing'),
+  { key: 'chat', labelKey: 'chat', descriptionKey: 'chatDesc', globalVar: 'owlConsentChat' },
+]
+
+consentStore.init({ categories })
+```
+
+### Share a decision across first-party domains
+
+```typescript
+import { consentLinkHelper, consentStore } from '@owlmeans/consent'
+
+const linker = {
+  domains: ['owlmeans.com', 'app.example.com'],
+  language: { supported: ['en', 'pl', 'de'] },   // omit `supported` on a send-only site
+}
+
+consentStore.init({ linker })   // registers consentLinker, adopts, writes the language, strips `owlcc`
+
+// For a page that must adopt before any bundle (and before its i18n reads storage)
+const fragment = consentLinkHelper.consentLinkerScript({ linker })
+```
+
+### Ask only where the law requires it
+
+```typescript
+import { consentPluginHelper, consentStore } from '@owlmeans/consent'
+
+// Cloudflare mode: a same-origin GET of /cdn-cgi/trace, `loc=` decides
+consentStore.init({ geo: { cloudflare: true } })
+
+// …or a locator of your own — one async method that resolves the country or throws
+consentPluginHelper.registerConsentPlugin({
+  alias: 'my-geo', locate: async () => ({ country: await myCountryLookup() }),
+})
+consentStore.init({ geo: {} })
+
+await consentStore.settled()   // the state once the lookup is over
+```
+
+A visitor located in `CONSENT_REQUIRED_COUNTRIES` (or `geo.countries`) is asked; anyone else gets an
+automatic decision (`auto: <unix s>` on the record) — every category, or only the required ones
+under Global Privacy Control; a visitor nobody can locate is asked. An automatic decision is trusted
+for `CONSENT_AUTO_MAX_AGE` (one hour) and then re-checked silently; an explicit decision always wins.
+
+### Built-in copy
+
+```typescript
+import { consentI18nHelper } from '@owlmeans/consent'
+
+const t = consentI18nHelper.defaultConsentTranslate('pl-PL')   // falls back to 'en'
+t('analytics', 'Analytics')
+```
+
+## API
+
+### Store and helpers
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `consentStore`, `makeConsentStore()` | store | `get`, `subscribe`, `init(opts?)`, `save(record)`, `acceptAll`, `open(reason?)`, `close`, `granted(key)`, `options()`, `settled()` |
+| `consentStorageHelper`, `createConsentStorageHelper()` | helper | `migrateConsent`, `readConsent`, `writeConsent`, `clearConsent` |
+| `consentModeHelper`, `createConsentModeHelper()` | helper | `gtagConsent`, `consentDefaults`, `consentUpdate`, `pushConsentDefaults`, `applyConsent`, `trackingGranted`, `consentBootstrapScript`, `consentGateScript` |
+| `consentLinkHelper`, `createConsentLinkHelper()` | helper | `encodeConsentLink`, `decodeConsentLink`, `writeConsentLanguage`, `consentLinker`, `stripConsentLinkParam`, `consentLinkerScript` |
+| `consentPluginHelper`, `createConsentPluginHelper()` | helper | `registerConsentPlugin`, `unregisterConsentPlugin`, `consentPlugins`, `decorateConsentUrl`, `consentDomains`, `adoptConsent`, `adoptConsentLanguage`, `startConsentPlugins`, `locateConsent` |
+| `consentGeoHelper`, `createConsentGeoHelper()` | helper | `enabled`, `parseTrace`, `cloudflareLocator`, `requiresConsent`, `decide`, `privacySignal`, `automaticRecord`, `autoState` |
+| `consentI18nHelper`, `createConsentI18nHelper()` | helper | `normalizeLocale`, `defaultConsentTranslate`, `interpolate` |
+
+Deprecated top-level wrappers (`compat:factory-refactor`) remain exported: `readConsent`,
+`writeConsent`, `clearConsent`, `openConsent`, `isConsented`, `consentBootstrapScript`,
+`defaultConsentTranslate`, `decorateConsentUrl`, `encodeConsentLink`, `consentLinkerScript`. New code
+calls the helper members.
+
+### Constants
+
+| Symbol | Value / purpose |
+|---|---|
+| `CONSENT_KEY` | `'site_cookie_consent'` — storage key, must not change |
+| `CONSENT_COOKIE_DAYS` | `365` |
+| `CONSENT_SCHEMA_VERSION` | `2` — stored record shape |
+| `CONSENT_SETUP_FLAG` | `'cookieConsentSetup'` — window flag making `pushConsentDefaults` idempotent |
+| `CONSENT_EVENT` | `'owlmeans:consent'` — dispatched by `applyConsent`, `detail.record` |
+| `CONSENT_ESSENTIAL`, `CONSENT_ANALYTICS`, `CONSENT_MARKETING` | default category keys |
+| `CONSENT_LANGUAGE_KEY` | `'owlmeans-lng'` — the interface-language storage key |
+| `CONSENT_LOCALES` | `en pl ru be uk es de fr` |
+| `DEFAULT_CONSENT_MESSAGES` | built-in dialog copy per locale |
+| `DEFAULT_CONSENT_CATEGORIES` | `essential` (required), `analytics`, `marketing` |
+| `CONSENT_SIGNAL_DEFAULTS` | every Consent Mode v2 signal `denied`, except `security_storage` `granted` |
+| `CONSENT_LINK_PARAM`, `CONSENT_LINK_MAX_AGE`, `CONSENT_LINK_SKEW` | `'owlcc'`, `300` s, `60` s |
+| `CONSENT_REQUIRED_COUNTRIES` | where a located visitor is asked — the union of `CONSENT_COUNTRIES_GDPR`, `CONSENT_COUNTRIES_ALIGNED`, `CONSENT_COUNTRIES_OPT_IN` |
+| `CONSENT_GEO_UNKNOWN` | codes that name no country (`XX`, `T1`, …) — asked |
+| `CONSENT_TRACE_PATH`, `CONSENT_GEO_TIMEOUT` | `'/cdn-cgi/trace'`, `2500` ms |
+| `CONSENT_AUTO_MAX_AGE` | `3600` s — how long an automatic decision is trusted |
+| `CONSENT_IDLE_STATE` | the frozen pre-init state and server snapshot |
+| `CONSENT_STATE_ATTRIBUTE` | `'data-consent'` on `<html>`: `locating`, `open`, `decided`, `idle` |
+
+### Types
+
+| Symbol | Purpose |
+|---|---|
+| `ConsentSignal` | the Consent Mode v2 signal names |
+| `ConsentCategory`, `ConsentRecord`, `ConsentService` | category, stored decision, disclosed third-party service |
+| `ConsentOptions` | `categories?`, `storageKey?`, `cookieDays?`, `cookieDomain?`, `silent?`, `linker?`, `geo?` |
+| `ConsentGeoOptions`, `ConsentCloudflareOptions`, `ConsentGeoPlugin`, `ConsentGeoLocation`, `ConsentLocating` | the geo gate: `cloudflare?`, `countries?`, `timeout?`; a locator plugin; its answer; the lookup phase |
+| `ConsentGeoHelper`, `ConsentGeoVerdict`, `ConsentAutoState` | the geo helper's interface, `'ask' \| 'auto'`, `'fresh' \| 'stale'` |
+| `ConsentLinkerOptions`, `ConsentLinkerLanguage` | `domains`, `param?`, `maxAge?`, `language?`; `supported?`, `storageKey?` |
+| `ConsentState`, `ConsentReason`, `ConsentListener`, `ConsentStore` | store state and contract |
+| `ConsentLocale`, `ConsentLinkPayload`, `ConsentPlugin` | locale union, decoded `owlcc` payload, plugin seam |
+| `ConsentModeHelper`, `ConsentStorageHelper`, `ConsentLinkHelper`, `ConsentPluginHelper`, `ConsentI18nHelper` | helper interfaces |
+
+## Cross-domain linking rules
+
+`consentLinker().adopt` accepts a decorated link only when the payload decodes with the current
+version, the referrer host is a listed domain, the timestamp is within `maxAge` (and at most 60 s in
+the future), and every local optional category is present. It runs only when the document has no
+stored record. The parameter is stripped from the visible URL whether or not it was adopted. Links
+with `rel="noreferrer"` are never decorated.
+
+## Common pitfalls
+
+- Stamp `consentBootstrapScript()` inline above the tag-manager snippet; pushing defaults from a
+  React bundle is too late.
+- `silent: true` suppresses runtime pushes only — the stamped bootstrap string still pushes.
+- Do not set `cookieDomain` on an existing site: it orphans the host-only cookie and re-asks every
+  visitor. Do not change `CONSENT_KEY` for the same reason.
+- Never present the required category as a choice, and never word a login gate as consent to
+  essential cookies.
+- Consent Mode speaks on `window.dataLayer` only; a tag on another queue never hears it.
+- Neither `consentBootstrapScript`, `consentGateScript` nor the composed result is HTML-escaped by
+  this package beyond JSON-encoding its own values.
+- Release both ends of a linked domain pair together: a receiver that asks about a category the
+  sender dropped refuses the link.
+
+The `consent` skill covers the category model, storage migration, the ordering rule, gated loading,
+the plugin seam and language linking in depth.
+
+## Related packages
+
+- [`@owlmeans/web-consent`](../web-consent) — the React dialog, re-open button, `CookiePolicy` and `useConsent`
+- [`@owlmeans/web-gtm`](../web-gtm) — Google tag head snippet, CSP hosts and Google service disclosure
+- [`@owlmeans/web-panel`](../web-panel) — `/consent` subpath bound to OwlMeans i18n and the panel menu
+- [`@owlmeans/astro`](../astro) — `owlHeadScripts` for Astro sites, legal-page suppression
+- [`@owlmeans/web-marketing-consent`](../web-marketing-consent) — bridges marketing preferences into `consentStore.save`
+- [`@owlmeans/client-i18n`](../client-i18n) — reads the `owlmeans-lng` language choice this package may write

package/build/consts.d.ts

@@ -1,4 +1,4 @@
-import type { ConsentCategory } from './types.js';
+import type { ConsentCategory, ConsentLocale, ConsentState } from './types.js';
 /**
  * Where a visitor's choice is stored.
  *
@@ -38,8 +38,16 @@ export declare const CONSENT_MARKETING = "marketing";
  * language part has to run in an inline `<head>` script, before any bundle exists.
  */
 export declare const CONSENT_LANGUAGE_KEY = "owlmeans-lng";
-export declare const CONSENT_LOCALES: readonly ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'];
-export type ConsentLocale = (typeof CONSENT_LOCALES)[number];
+export declare const CONSENT_LOCALES: readonly ["en", "pl", "ru", "be", "uk", "es", "de", "fr"];
+/**
+ * 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 declare const DEFAULT_CONSENT_MESSAGES: Record<ConsentLocale, Record<string, string>>;
 /**
  * The categories every OwlMeans surface starts with.
  *
@@ -56,4 +64,71 @@ export declare const DEFAULT_CONSENT_CATEGORIES: ConsentCategory[];
  * fraud prevention, which are strictly necessary. Everything else starts denied.
  */
 export declare const CONSENT_SIGNAL_DEFAULTS: Record<string, 'granted' | 'denied'>;
+/** The URL parameter a decorated link carries the decision in, absent an override. */
+export declare const CONSENT_LINK_PARAM = "owlcc";
+/** How old a decorated link's timestamp may be and still be trusted, in seconds, absent an override. */
+export declare const CONSENT_LINK_MAX_AGE = 300;
+/** Clock skew allowed the OTHER way — a timestamp up to this far in the future is still trusted. */
+export declare const CONSENT_LINK_SKEW = 60;
+/**
+ * Where prior consent for non-essential cookies is the law: the EU and EEA (ePrivacy Art. 5(3) with
+ * the GDPR), including the parts of member states that carry an ISO code of their own — Åland and
+ * the French outermost regions (French Guiana, Guadeloupe, Martinique, Réunion, Mayotte,
+ * Saint-Martin). The Canary Islands, Azores, Madeira, Ceuta and Melilla report their state's code.
+ * Greece is `GR`, as Cloudflare and every ISO feed spell it.
+ */
+export declare const CONSENT_COUNTRIES_GDPR: readonly string[];
+/**
+ * Jurisdictions outside the EEA whose rule for cookies is the same prior opt-in, by statute or by
+ * the regulator's guidance (2026):
+ *
+ * - the United Kingdom (PECR — the 2025 Data (Use and Access) Act exempts some first-party
+ *   analytics, advertising still needs consent), the Crown Dependencies and Gibraltar;
+ * - Switzerland (FDPIC guidelines, 2025: explicit consent for tracking and profiling);
+ * - Andorra, Monaco, San Marino and the Vatican; Türkiye (KVKK cookie guide); Serbia (ZZPL and the
+ *   electronic-communications law); Albania, Bosnia and Herzegovina, Montenegro, North Macedonia,
+ *   Kosovo, Moldova, Georgia and Ukraine (GDPR-modelled laws);
+ * - territories under a member state's regulator but outside the EU: the Faroe Islands and
+ *   Greenland (Denmark); Saint-Barthélemy, Saint-Pierre-et-Miquelon, New Caledonia, French
+ *   Polynesia, Wallis and Futuna (France); the Caribbean Netherlands.
+ */
+export declare const CONSENT_COUNTRIES_ALIGNED: readonly string[];
+/**
+ * Prior opt-in regimes elsewhere (2026): Brazil (LGPD, ANPD cookie guide), Canada (Québec's Law 25
+ * — the country is the finest grain a CDN reports, so all of Canada), China (PIPL), South Korea
+ * (PIPA), Nigeria (NDPA), Saudi Arabia (PDPL), Thailand (PDPA), Vietnam (PDPL 2026).
+ *
+ * Deliberately absent: India (the DPDP Act's consent rules apply from mid-2027 — add `IN` then),
+ * and the notice-or-opt-out regimes — the United States, Japan, Australia, Singapore. South
+ * Africa's POPIA is read both ways by the guides and is left out until its regulator says more.
+ */
+export declare const CONSENT_COUNTRIES_OPT_IN: readonly string[];
+/**
+ * Every country where a located visitor is ASKED (`ConsentGeoOptions.countries` replaces it). A
+ * visitor located anywhere else gets an automatic decision; one who cannot be located is asked.
+ */
+export declare const CONSENT_REQUIRED_COUNTRIES: readonly string[];
+/**
+ * Codes that name no country: Cloudflare's `XX` (no data) and `T1` (Tor), the retired MaxMind
+ * pseudo-codes (`A1` anonymous proxy, `A2` satellite, `O1` other) and the continent buckets some
+ * feeds fall back to (`EU`, `AP`), plus `ZZ` (unknown). A visitor reported with one is asked.
+ */
+export declare const CONSENT_GEO_UNKNOWN: readonly string[];
+/** Cloudflare's trace endpoint — served by the edge on every proxied host, `loc=` among its lines. */
+export declare const CONSENT_TRACE_PATH = "/cdn-cgi/trace";
+/** How long locating may take before the visitor is asked anyway, in ms. */
+export declare const CONSENT_GEO_TIMEOUT = 2500;
+/**
+ * How long an automatic decision is trusted, in seconds. Older, it counts as undecided — in the
+ * head scripts as much as in the store — until the visitor is located again, so a grant derived in
+ * one country never reaches a page opened an hour later in another.
+ */
+export declare const CONSENT_AUTO_MAX_AGE = 3600;
+/** The state of a store nobody has initialised — and the only server-side snapshot. */
+export declare const CONSENT_IDLE_STATE: ConsentState;
+/**
+ * The attribute on `<html>` that mirrors the consent phase: `locating`, `open`, `decided` or `idle`.
+ * Absent until the store first runs. A test waits on it, and a stylesheet may key on it.
+ */
+export declare const CONSENT_STATE_ATTRIBUTE = "data-consent";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAA;AAEhD,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,uBAAuB,CAAA;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,qBAAqB,CAAA;AAE/C,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAC5C,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAC5C,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAA;AAElD,eAAO,MAAM,eAAe,YAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAExF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,eAAe,EAmBvD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAQxE,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAW9E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAA;AAEhD,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,uBAAuB,CAAA;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,qBAAqB,CAAA;AAE/C,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAC5C,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAC5C,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAA;AAElD,eAAO,MAAM,eAAe,2DAA+F,CAAA;AAE3H;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAElF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,eAAe,EAmBvD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAQxE,CAAA;AAED,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAEzC,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAEvC,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAKlD,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAKrD,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAEpD,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAEtD,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAE/C,CAAA;AAEF,sGAAsG;AACtG,eAAO,MAAM,kBAAkB,mBAAmB,CAAA;AAElD,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,OAAO,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAA;AAExC,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,EAAE,YAE/B,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAA"}

package/build/consts.js

@@ -1,3 +1,11 @@
+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' };
+import fr from './i18n/fr.json' with { type: 'json' };
 /**
  * Where a visitor's choice is stored.
  *
@@ -38,6 +46,17 @@ export const CONSENT_MARKETING = 'marketing';
  */
 export const CONSENT_LANGUAGE_KEY = 'owlmeans-lng';
 export const CONSENT_LOCALES = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'];
+/**
+ * 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 = {
+    en, pl, ru, be, uk, es, de, fr,
+};
 /**
  * The categories every OwlMeans surface starts with.
  *
@@ -81,4 +100,89 @@ export const CONSENT_SIGNAL_DEFAULTS = {
     personalization_storage: 'denied',
     security_storage: 'granted',
 };
+/** The URL parameter a decorated link carries the decision in, absent an override. */
+export const CONSENT_LINK_PARAM = 'owlcc';
+/** How old a decorated link's timestamp may be and still be trusted, in seconds, absent an override. */
+export const CONSENT_LINK_MAX_AGE = 300;
+/** Clock skew allowed the OTHER way — a timestamp up to this far in the future is still trusted. */
+export const CONSENT_LINK_SKEW = 60;
+/**
+ * Where prior consent for non-essential cookies is the law: the EU and EEA (ePrivacy Art. 5(3) with
+ * the GDPR), including the parts of member states that carry an ISO code of their own — Åland and
+ * the French outermost regions (French Guiana, Guadeloupe, Martinique, Réunion, Mayotte,
+ * Saint-Martin). The Canary Islands, Azores, Madeira, Ceuta and Melilla report their state's code.
+ * Greece is `GR`, as Cloudflare and every ISO feed spell it.
+ */
+export const CONSENT_COUNTRIES_GDPR = Object.freeze([
+    'AT', 'BE', 'BG', 'CY', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR', 'GR', 'HR', 'HU',
+    'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL', 'PT', 'RO', 'SE', 'SI', 'SK',
+    'AX', 'GF', 'GP', 'MQ', 'RE', 'YT', 'MF',
+    'IS', 'LI', 'NO',
+]);
+/**
+ * Jurisdictions outside the EEA whose rule for cookies is the same prior opt-in, by statute or by
+ * the regulator's guidance (2026):
+ *
+ * - the United Kingdom (PECR — the 2025 Data (Use and Access) Act exempts some first-party
+ *   analytics, advertising still needs consent), the Crown Dependencies and Gibraltar;
+ * - Switzerland (FDPIC guidelines, 2025: explicit consent for tracking and profiling);
+ * - Andorra, Monaco, San Marino and the Vatican; Türkiye (KVKK cookie guide); Serbia (ZZPL and the
+ *   electronic-communications law); Albania, Bosnia and Herzegovina, Montenegro, North Macedonia,
+ *   Kosovo, Moldova, Georgia and Ukraine (GDPR-modelled laws);
+ * - territories under a member state's regulator but outside the EU: the Faroe Islands and
+ *   Greenland (Denmark); Saint-Barthélemy, Saint-Pierre-et-Miquelon, New Caledonia, French
+ *   Polynesia, Wallis and Futuna (France); the Caribbean Netherlands.
+ */
+export const CONSENT_COUNTRIES_ALIGNED = Object.freeze([
+    'GB', 'GG', 'JE', 'IM', 'GI',
+    'CH',
+    'AD', 'MC', 'SM', 'VA', 'TR', 'RS', 'AL', 'BA', 'ME', 'MK', 'XK', 'MD', 'GE', 'UA',
+    'FO', 'GL', 'BL', 'PM', 'NC', 'PF', 'WF', 'BQ',
+]);
+/**
+ * Prior opt-in regimes elsewhere (2026): Brazil (LGPD, ANPD cookie guide), Canada (Québec's Law 25
+ * — the country is the finest grain a CDN reports, so all of Canada), China (PIPL), South Korea
+ * (PIPA), Nigeria (NDPA), Saudi Arabia (PDPL), Thailand (PDPA), Vietnam (PDPL 2026).
+ *
+ * Deliberately absent: India (the DPDP Act's consent rules apply from mid-2027 — add `IN` then),
+ * and the notice-or-opt-out regimes — the United States, Japan, Australia, Singapore. South
+ * Africa's POPIA is read both ways by the guides and is left out until its regulator says more.
+ */
+export const CONSENT_COUNTRIES_OPT_IN = Object.freeze([
+    'BR', 'CA', 'CN', 'KR', 'NG', 'SA', 'TH', 'VN',
+]);
+/**
+ * Every country where a located visitor is ASKED (`ConsentGeoOptions.countries` replaces it). A
+ * visitor located anywhere else gets an automatic decision; one who cannot be located is asked.
+ */
+export const CONSENT_REQUIRED_COUNTRIES = Object.freeze([
+    ...CONSENT_COUNTRIES_GDPR, ...CONSENT_COUNTRIES_ALIGNED, ...CONSENT_COUNTRIES_OPT_IN,
+]);
+/**
+ * Codes that name no country: Cloudflare's `XX` (no data) and `T1` (Tor), the retired MaxMind
+ * pseudo-codes (`A1` anonymous proxy, `A2` satellite, `O1` other) and the continent buckets some
+ * feeds fall back to (`EU`, `AP`), plus `ZZ` (unknown). A visitor reported with one is asked.
+ */
+export const CONSENT_GEO_UNKNOWN = Object.freeze([
+    'XX', 'T1', 'A1', 'A2', 'O1', 'EU', 'AP', 'ZZ',
+]);
+/** Cloudflare's trace endpoint — served by the edge on every proxied host, `loc=` among its lines. */
+export const CONSENT_TRACE_PATH = '/cdn-cgi/trace';
+/** How long locating may take before the visitor is asked anyway, in ms. */
+export const CONSENT_GEO_TIMEOUT = 2500;
+/**
+ * How long an automatic decision is trusted, in seconds. Older, it counts as undecided — in the
+ * head scripts as much as in the store — until the visitor is located again, so a grant derived in
+ * one country never reaches a page opened an hour later in another.
+ */
+export const CONSENT_AUTO_MAX_AGE = 3600;
+/** The state of a store nobody has initialised — and the only server-side snapshot. */
+export const CONSENT_IDLE_STATE = Object.freeze({
+    record: null, open: false, reason: null, locating: null,
+});
+/**
+ * The attribute on `<html>` that mirrors the consent phase: `locating`, `open`, `decided` or `idle`.
+ * Absent until the store first runs. A test waits on it, and a stylesheet may key on it.
+ */
+export const CONSENT_STATE_ATTRIBUTE = 'data-consent';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,qBAAqB,CAAA;AAEhD,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA;AAEvC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAA;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAA;AAElD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAIxF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D;QACE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI;QACtC,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe;QACtD,SAAS,EAAE,qBAAqB;QAChC,OAAO,EAAE,CAAC,kBAAkB,EAAE,uBAAuB,CAAC;KACvD;IACD;QACE,GAAG,EAAE,iBAAiB;QACtB,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe;QACtD,SAAS,EAAE,qBAAqB;QAChC,OAAO,EAAE,CAAC,mBAAmB,CAAC;KAC/B;IACD;QACE,GAAG,EAAE,iBAAiB;QACtB,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe;QACtD,SAAS,EAAE,qBAAqB;QAChC,OAAO,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,oBAAoB,CAAC;KAC9D;CACF,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAyC;IAC3E,UAAU,EAAE,QAAQ;IACpB,YAAY,EAAE,QAAQ;IACtB,kBAAkB,EAAE,QAAQ;IAC5B,iBAAiB,EAAE,QAAQ;IAC3B,qBAAqB,EAAE,QAAQ;IAC/B,uBAAuB,EAAE,QAAQ;IACjC,gBAAgB,EAAE,SAAS;CAC5B,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AACrD,OAAO,EAAE,MAAM,gBAAgB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAErD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,qBAAqB,CAAA;AAEhD,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA;AAEvC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAA;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAA;AAElD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAA6C,CAAA;AAE3H;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAkD;IACrF,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D;QACE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI;QACtC,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe;QACtD,SAAS,EAAE,qBAAqB;QAChC,OAAO,EAAE,CAAC,kBAAkB,EAAE,uBAAuB,CAAC;KACvD;IACD;QACE,GAAG,EAAE,iBAAiB;QACtB,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe;QACtD,SAAS,EAAE,qBAAqB;QAChC,OAAO,EAAE,CAAC,mBAAmB,CAAC;KAC/B;IACD;QACE,GAAG,EAAE,iBAAiB;QACtB,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe;QACtD,SAAS,EAAE,qBAAqB;QAChC,OAAO,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,oBAAoB,CAAC;KAC9D;CACF,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAyC;IAC3E,UAAU,EAAE,QAAQ;IACpB,YAAY,EAAE,QAAQ;IACtB,kBAAkB,EAAE,QAAQ;IAC5B,iBAAiB,EAAE,QAAQ;IAC3B,qBAAqB,EAAE,QAAQ;IAC/B,uBAAuB,EAAE,QAAQ;IACjC,gBAAgB,EAAE,SAAS;CAC5B,CAAA;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAA;AAEzC,wGAAwG;AACxG,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAA;AAEvC,oGAAoG;AACpG,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACrE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAClF,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC5E,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IACxC,IAAI,EAAE,IAAI,EAAE,IAAI;CACjB,CAAC,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACxE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC5B,IAAI;IACJ,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAClF,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CAC/C,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACvE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CAC/C,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB,MAAM,CAAC,MAAM,CAAC;IACzE,GAAG,sBAAsB,EAAE,GAAG,yBAAyB,EAAE,GAAG,wBAAwB;CACrF,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAClE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CAC/C,CAAC,CAAA;AAEF,sGAAsG;AACtG,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAA;AAElD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAA;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAA;AAExC,uFAAuF;AACvF,MAAM,CAAC,MAAM,kBAAkB,GAAiB,MAAM,CAAC,MAAM,CAAC;IAC5D,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI;CACxD,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,cAAc,CAAA"}

package/build/consts.local.d.ts

@@ -0,0 +1,12 @@
+export declare const CONSENT_LINK_VERSION = 2;
+/** A BCP 47-shaped tag: a 2–3 letter language and up to three subtags (`pl`, `pt-BR`, `zh-Hant-TW`). */
+export declare const LANGUAGE_TAG: RegExp;
+/** The built-in Cloudflare locator's registry alias. */
+export declare const CLOUDFLARE_LOCATOR_ALIAS = "cloudflare";
+/** Below anything an application registers: an application's own locator always asks first. */
+export declare const CLOUDFLARE_LOCATOR_PRIORITY = -100;
+/** An ISO 3166-1 alpha-2 code, upper case. */
+export declare const COUNTRY_CODE: RegExp;
+/** Clock skew tolerated on an automatic decision's timestamp, in seconds. */
+export declare const AUTO_SKEW = 60;
+//# sourceMappingURL=consts.local.d.ts.map

package/build/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,wGAAwG;AACxG,eAAO,MAAM,YAAY,QAA4C,CAAA;AAErE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,eAAe,CAAA;AAEpD,+FAA+F;AAC/F,eAAO,MAAM,2BAA2B,OAAO,CAAA;AAE/C,8CAA8C;AAC9C,eAAO,MAAM,YAAY,QAAe,CAAA;AAExC,6EAA6E;AAC7E,eAAO,MAAM,SAAS,KAAK,CAAA"}

package/build/consts.local.js

@@ -0,0 +1,12 @@
+export const CONSENT_LINK_VERSION = 2;
+/** A BCP 47-shaped tag: a 2–3 letter language and up to three subtags (`pl`, `pt-BR`, `zh-Hant-TW`). */
+export const LANGUAGE_TAG = /^[a-z]{2,3}(?:[-_][a-z0-9]{1,8}){0,3}$/i;
+/** The built-in Cloudflare locator's registry alias. */
+export const CLOUDFLARE_LOCATOR_ALIAS = 'cloudflare';
+/** Below anything an application registers: an application's own locator always asks first. */
+export const CLOUDFLARE_LOCATOR_PRIORITY = -100;
+/** An ISO 3166-1 alpha-2 code, upper case. */
+export const COUNTRY_CODE = /^[A-Z]{2}$/;
+/** Clock skew tolerated on an automatic decision's timestamp, in seconds. */
+export const AUTO_SKEW = 60;
+//# sourceMappingURL=consts.local.js.map

package/build/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAA;AAErC,wGAAwG;AACxG,MAAM,CAAC,MAAM,YAAY,GAAG,yCAAyC,CAAA;AAErE,wDAAwD;AACxD,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAA;AAEpD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,CAAA;AAE/C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAA;AAExC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAA"}

package/build/geo/types.d.ts

@@ -0,0 +1,47 @@
+import type { ConsentGeoPlugin, ConsentOptions, ConsentRecord } from '../types.js';
+/** What locating the visitor decided: ask them, or decide for them automatically. */
+export type ConsentGeoVerdict = 'ask' | 'auto';
+/** Whether a record is an automatic decision, and whether it is still trusted. */
+export type ConsentAutoState = 'fresh' | 'stale';
+/**
+ * Asking only where the law requires it: locating the visitor, the decision that follows, and the
+ * automatic record written where nobody needs to be asked.
+ */
+export interface ConsentGeoHelper {
+    /** Whether `opts.geo` turns the gate on AND something can answer — the Cloudflare locator or a plugin. */
+    enabled: (opts?: ConsentOptions) => boolean;
+    /** Every `key=value` line of a Cloudflare trace body. Never throws; anything else parses to `{}`. */
+    parseTrace: (text: string) => Record<string, string>;
+    /**
+     * The built-in locator: a same-origin GET of the trace endpoint, cookies left out, never cached.
+     * Rejects when `opts.geo.cloudflare` is off, the request fails or answers non-2xx, or the body is
+     * not a trace (an SPA serving its `index.html` for every path answers 200 here).
+     */
+    cloudflareLocator: () => ConsentGeoPlugin;
+    /**
+     * Whether a visitor located in `country` must be asked: yes inside `opts.geo.countries`
+     * (`CONSENT_REQUIRED_COUNTRIES`), and yes for anything that names no country.
+     */
+    requiresConsent: (country: string | null, opts?: ConsentOptions) => boolean;
+    /**
+     * Locate and decide, bounded by `opts.geo.timeout`. Never rejects: a visitor nobody could locate
+     * resolves `'ask'`.
+     */
+    decide: (opts: ConsentOptions) => Promise<ConsentGeoVerdict>;
+    /**
+     * Whether the browser sends Global Privacy Control — a legally binding opt-out in several US
+     * states, so an automatic decision honours it.
+     */
+    privacySignal: () => boolean;
+    /**
+     * The automatic decision for a visitor nobody needs to ask: every category on — or, under Global
+     * Privacy Control, only the required ones — stamped `auto` with the current time.
+     */
+    automaticRecord: (opts?: ConsentOptions) => ConsentRecord;
+    /**
+     * `fresh` for an automatic decision younger than `CONSENT_AUTO_MAX_AGE`, `stale` for an older one
+     * (or one stamped in the future beyond the skew), `null` for an explicit record or none.
+     */
+    autoState: (record: ConsentRecord | null) => ConsentAutoState | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/geo/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/geo/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAElF,qFAAqF;AACrF,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,MAAM,CAAA;AAE9C,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAA;AAEhD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0GAA0G;IAC1G,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,cAAc,KAAK,OAAO,CAAA;IAC3C,qGAAqG;IACrG,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpD;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;IACzC;;;OAGG;IACH,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,cAAc,KAAK,OAAO,CAAA;IAC3E;;;OAGG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC5D;;;OAGG;IACH,aAAa,EAAE,MAAM,OAAO,CAAA;IAC5B;;;OAGG;IACH,eAAe,EAAE,CAAC,IAAI,CAAC,EAAE,cAAc,KAAK,aAAa,CAAA;IACzD;;;OAGG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,KAAK,gBAAgB,GAAG,IAAI,CAAA;CACrE"}

package/build/geo/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/geo/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/geo/types.ts"],"names":[],"mappings":""}

package/build/geo.d.ts

@@ -0,0 +1,4 @@
+import type { ConsentGeoHelper } from './geo/types.js';
+export declare const createConsentGeoHelper: () => ConsentGeoHelper;
+export declare const consentGeoHelper: ConsentGeoHelper;
+//# sourceMappingURL=geo.d.ts.map

package/build/geo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../src/geo.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAoB,gBAAgB,EAAqB,MAAM,gBAAgB,CAAA;AAE3F,eAAO,MAAM,sBAAsB,QAAO,gBA2GzC,CAAA;AAED,eAAO,MAAM,gBAAgB,kBAA2B,CAAA"}