@consenti/ui 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -11,6 +11,32 @@ type DeepPartial<T> = T extends Function ? T : T extends Array<infer InferredArr
     [Key in keyof T]?: DeepPartial<T[Key]> | null;
 } : T;
 
+/**
+ * Single source of truth for all compliance groups, regulations, and country mappings.
+ *
+ * This is DATA, not types. The `Compliance` and `ComplianceGroupId` literal types
+ * derived from the ID arrays below live in @consenti/types (packages/types/src/compliance.ts),
+ * via a type-only import — that keeps @consenti/types free of runtime code.
+ *
+ * ─── HOW TO UPDATE ────────────────────────────────────────────────────────────
+ *
+ * ADD A NEW REGULATION:
+ *   1. Add regulation ID string to `COMPLIANCE_REGULATION_IDS` below
+ *      (the `Compliance` type in @consenti/types auto-updates from it).
+ *   2. Add it to the appropriate group's `compliances` array below.
+ *   3. Add / update the country entry in `EMBEDDED_COMPLIANCE_MAP` below.
+ *   That is all — no other files need touching.
+ *
+ * ADD A NEW COMPLIANCE GROUP:
+ *   1. Add the kebab-case ID to `COMPLIANCE_GROUP_IDS` below.
+ *   2. Add a full group entry to `COMPLIANCE_GROUPS` below (label, compliances, flags).
+ *   3. Add a validation rule set to `COMPLIANCE_VALIDATION_RULES` below.
+ *   4. Map affected countries in `EMBEDDED_COMPLIANCE_MAP` to the new group.
+ *
+ * ADD OR UPDATE A COUNTRY:
+ *   Edit the entry in `EMBEDDED_COMPLIANCE_MAP.countries` below. That is the ONLY
+ *   place that needs changing for country-level jurisdiction updates.
+ */
 declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-strict", "opt-in-dpdpa", "opt-in-china", "opt-in-brazil", "general-privacy-consent", "notice-only"];
 declare const COOKIE_PURPOSE_IDS: readonly ["necessary", "functional", "preferences", "analytics", "marketing"];
 
@@ -42,11 +68,14 @@ interface ComplianceMapData {
 }
 interface CountryComplianceEntry {
     complianceGroup: ComplianceGroupId;
-    default: ComplianceGroupId;
-    description: string;
+    /** Fallback group used when only the country (not the region) is known. Defaults to
+     * `complianceGroup` when omitted — only set this explicitly when a region within this
+     * country can be stricter than the country-wide baseline (see `overriddenRegions`). */
+    default?: ComplianceGroupId;
+    description?: string;
     overriddenRegions?: Record<string, {
         complianceGroup: ComplianceGroupId;
-        description: string;
+        description?: string;
     }>;
 }
 interface ConsentDbRecord {
@@ -61,9 +90,10 @@ interface ConsentDbRecord {
     ageVerified?: boolean;
     parentalConsentToken?: string;
     tcfString?: string;
-    /** HMAC-SHA256 signature over the record's core fields, hex-encoded. Only present when
-     * `consentSigningKey` is configured — opt-in tamper-evidence for server-stored records,
-     * independent of the widget's own cookie-signing (`core.cookieSigningKey`). */
+    gppString?: string;
+    /** HMAC-SHA256 signature over the record's core fields, hex-encoded — tamper-evidence for
+     * server-stored records via `dataSigningHash` (auto-generated when unset), independent of the
+     * widget's own cookie-signing (`core.cookieSigningKey`). */
     signature?: string;
     createdAt: string;
     updatedAt: string;
@@ -74,15 +104,18 @@ type ConsentAction$1 = 'accept_all' | 'reject_all' | 'custom' | 'update';
 type ConsentValue = Record<string, ConsentStatus>;
 /**
  * Output format for getConsent(type).
- * 'default'           → raw ConsentValue (existing behaviour)
+ * 'default'           → raw ConsentValue, keyed by every cookie parameter ID in the profile (existing behaviour)
  * 'google-gtm'        → Google Consent Mode v2 keys + ads_data_redaction, url_passthrough
- * 'category'          → consent per CookiePurpose category
+ * 'purpose'           → consent per the fixed CookiePurpose taxonomy (necessary/functional/preferences/analytics/marketing)
+ * 'category'          → consent per the tenant's own authored preference-modal category, keyed by category ID.
+ *                        'granted' only when every member parameter is granted; 'denied'/'objected' otherwise
+ *                        (same ConsentStatus values as everything else — see getCategoryConsent for the exact rule)
  * 'adobe'             → { analytics, target, manager, optimizer }
  * 'meta'              → { pixel, api, plugins, facebookLogin }
  * 'microsoft-clarity' → { session, heatmaps, performance }
  * 'twilio-segment'    → { identify, page, track, group, alias }
  */
-type ConsentType = 'default' | 'google-gtm' | 'category' | 'adobe' | 'meta' | 'microsoft-clarity' | 'twilio-segment';
+type ConsentType = 'default' | 'google-gtm' | 'purpose' | 'category' | 'adobe' | 'meta' | 'microsoft-clarity' | 'twilio-segment';
 type GpcMode = 'ignore' | 'honor' | 'strict';
 type LegalBasis = 'mandatory' | 'consent' | 'legitimate_interest';
 type CookiePurpose = typeof COOKIE_PURPOSE_IDS[number];
@@ -170,11 +203,24 @@ interface PreferenceModal extends Omit<MainBanner, "position"> {
     receiptLabel?: string;
     /** Description shown beneath the consent-receipt checkbox. Falls back to a default when omitted. */
     receiptDescription?: string;
+    /**
+     * Renders a "Forget me" control in the modal body, below the categories — only shown to
+     * visitors who already have a stored consent decision (nothing to erase otherwise). Wired to
+     * the same `DELETE /consent/:visitorId` erasure endpoint as `widget.deleteConsent()`, giving
+     * visitors self-service access to GDPR Art. 17 / CCPA-CPRA / LGPD Art. 18 / UK GDPR / DPDPA /
+     * KVKK / POPIA / PDPA-TH / APPI erasure-equivalent rights without the host wiring a link
+     * themselves. See the "Right to erasure" guide for the full compliance mapping.
+     */
+    showForgetMe?: boolean;
+    /** Label for the "Forget me" button (shown when `showForgetMe` is true). Falls back to a default when omitted. */
+    forgetMeLabel?: string;
 }
 interface LocaleTranslations {
     mainBanner: DeepPartial<MainBanner>;
     gpcBanner?: DeepPartial<GpcBanner>;
     preferenceModal: DeepPartial<PreferenceModal>;
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: DeepPartial<AgeGateModalContent>;
 }
 interface ProfileTranslations {
     [locale: string]: LocaleTranslations;
@@ -184,6 +230,29 @@ interface DpdpaConfig {
     grievanceEmail: string;
     purposeDescription?: string;
 }
+/**
+ * Per-profile age gate — GDPR Art. 8's consent age varies 13–16 by EU member state and DPDPA has
+ * its own child-data age rules, so one global age (the old `ConsentiServerConfig.ageGate`) was
+ * wrong for a multi-region deployment. Mirrors `dpdpa` exactly: profile-scoped, not global.
+ */
+interface AgeGateConfig {
+    enabled: boolean;
+    minimumAge: number;
+    requireParentalConsent?: boolean;
+}
+/** Per-locale age-gate modal text — translated the same way `mainBanner`/`preferenceModal`
+ * content is, unlike the widget's own hardcoded UI chrome (close button, locale switcher). */
+interface AgeGateModalContent {
+    heading?: string;
+    htmlText: string;
+    confirmButtonLabel: string;
+    denyButtonLabel: string;
+    parentalConsent: {
+        heading?: string;
+        htmlText: string;
+        confirmButtonLabel: string;
+    };
+}
 interface LocaleTextContent {
     mainBanner: {
         heading?: string;
@@ -210,7 +279,11 @@ interface LocaleTextContent {
         }>;
         receiptLabel?: string;
         receiptDescription?: string;
+        /** Per-locale override of `PreferenceModal.forgetMeLabel`; only meaningful when `showForgetMe` is true. */
+        forgetMeLabel?: string;
     };
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: AgeGateModalContent;
 }
 interface ProfileConfig {
     id: string;
@@ -225,6 +298,12 @@ interface ProfileConfig {
     darkMode?: boolean;
     allowedOrigins?: string[];
     dpdpa?: DpdpaConfig;
+    ageGate?: AgeGateConfig;
+    /** Default locale's age-gate modal text — mirrors `mainBanner`/`preferenceModal` (inline,
+     * required-shape-when-present), not `dpdpa` (which has no locale text at all). Every other
+     * locale's `ageGateModal` lives in `localeContents`/`LocaleContentInput` like the rest of
+     * that locale's content. */
+    ageGateModal?: AgeGateModalContent;
     regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
     regulations?: string[];
     consentTemplateId?: string;
@@ -299,9 +378,21 @@ interface ResolvedProfile {
     preferenceModal: PreferenceModal;
     cookieSigningKey?: string;
     dpdpa?: DpdpaConfig;
+    ageGate?: AgeGateConfig;
+    ageGateModal?: AgeGateModalContent;
     darkMode?: boolean;
     gpcMode?: GpcMode;
-    complianceGroup?: ComplianceGroupId;
+    /** One of the 8 built-in groups, or a custom group id (via `customComplianceGroup` /
+     * `ComplianceType`'s string passthrough) — this is the join key `complianceGroupsOverride`
+     * looks up by, so it must reflect whichever group this profile actually resolved against,
+     * built-in or custom. */
+    complianceGroup?: ComplianceGroupId | (string & {});
+    /** Set when the geo-resolved region carries a `requiresSensitiveOptIn` carve-out (e.g.
+     * Colorado under `opt-out`) — cookies tagged `cpraCategory: 'sensitive'` default to denied
+     * even though the rest of `complianceGroup`'s cookies default to granted. Only ever set by
+     * server-side geo resolution (`api.enabled: true` + a geoip/maxmind provider); the
+     * client-only timezone heuristic never resolves a region, so this is always unset there. */
+    requiresSensitiveOptIn?: boolean;
     complianceConfig?: Record<string, string>;
     /** Falls back to `true` (hidden) if neither the widget config nor the profile set it. */
     hidePoweredBy?: boolean;
@@ -314,26 +405,66 @@ type WidgetCountryResolverFn = () => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
+    /** Optional escape hatch: when set, profile resolution uses this compliance group directly
+     * instead of computing one from `country`/`region` — mirrors the server-side `GeoResult`'s
+     * `complianceGroup` field (`@consenti/types`'s `api.ts`). `country`/`region` are still used for
+     * anything that reads them independently of group selection. Optional — omitting it preserves
+     * the existing timezone/language-based resolution exactly as before. */
+    complianceGroup?: string;
 }>;
-interface AgeGateWidgetConfig {
-    enabled: boolean;
-    minimumAge: number;
-    requireParentalConsent?: boolean;
-}
 /** Mirrors the server-side `TcfConfig` shape (`@consenti/api`) — `cmpId`/`cmpVersion` must match
- * what the backend uses to encode `tcfString`, since both feed the same simplified TC string. */
+ * what the backend uses to encode `tcfString`, since both feed the same simplified TC string.
+ *
+ * The client-side `__tcfapi` stub never fetches the Global Vendor List itself (multi-megabyte,
+ * and IAB policy requires CMPs to cache their own copy rather than have every visitor's browser
+ * fetch it) — `publisherCC`/`vendorListVersion`/`gvlVersion` are therefore operator-supplied
+ * config here, not auto-derived. Spec-correct binary TC-string encoding happens server-side in
+ * `@consenti/api` (see `compliance.tcf.publisherCC` there); this stub's `tcString` stays the
+ * simplified format documented in `@consenti/utils`'s `encodeTcString`. */
 interface TcfWidgetConfig {
     enabled: boolean;
     cmpId: number;
     cmpVersion: number;
+    /** ISO 3166-1 alpha-2 publisher country code. No honest default exists — leave unset only if
+     * you don't rely on this field downstream; ad-tech vendors that read it will see 'AA'
+     * (an explicit "not configured" placeholder, not a real country). */
+    publisherCC?: string;
+    /** Known Global Vendor List version, if you track it. Defaults to 0 ("unknown"). */
+    vendorListVersion?: number;
+    /** Known GVL specification version, if you track it. Defaults to 0 ("unknown"). */
+    gvlVersion?: number;
+}
+/** Mirrors the server-side `GppConfig` shape (`@consenti/api`) — `cmpId`/`cmpVersion` must match
+ * what the backend uses to encode `gppString`. Unlike TCF, the GPP US National section needs no
+ * Global Vendor List, so both the widget's `window.__gpp` and the server's `gppString` use the
+ * same real, spec-correct encoder (the optional `@iabgpp/cmpapi` peer dependency) — there's no
+ * "simplified fallback" format the way TCF has, since a non-spec GPP string has no consumer that
+ * would accept it. When `@iabgpp/cmpapi` isn't installed, `window.__gpp` is simply not exposed. */
+interface GppWidgetConfig {
+    enabled: boolean;
+    cmpId: number;
+    cmpVersion: number;
+    /** MSPA "covered transaction" — whether this deployment's data transactions fall under MSPA
+     * signatory obligations. No honest default, so it's required rather than optional. */
+    mspaCoveredTransaction: boolean;
+    /** IAB's tri-state encoding for both MSPA fields: 0 = not applicable, 1 = yes, 2 = no. */
+    mspaOptOutOptionMode: 0 | 1 | 2;
+    mspaServiceProviderMode: 0 | 1 | 2;
 }
 interface ComplianceWidgetConfig {
     type?: ComplianceType;
     geoDataProvider?: 'default' | WidgetCountryResolverFn;
-    autoComplianceMap?: 'default' | ComplianceMapData | 'auto';
-    complianceMapUrl?: string;
-    ageGate?: AgeGateWidgetConfig;
+    /** Only meaningful in standalone mode (no `api.enabled`) — ignored (with a warning) when
+     * `api.enabled: true`, since the server resolves the compliance group in that mode.
+     * `'default'` (embedded map, the default), a URL to fetch a JSON `ComplianceMapData`
+     * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
+     * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
+     * object. Invalid data from either a URL or an object logs a warning and falls back to
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself
+     * always uses the embedded geo data. */
+    complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
+    gpp?: GppWidgetConfig;
 }
 interface GtmConfig {
     containerId?: string;
@@ -354,37 +485,67 @@ interface ApiConfig {
     complianceGroup?: ComplianceGroupId;
     trustDomain?: boolean;
 }
+/** Field names mirror their `--consenti-*` CSS variable literally (`--consenti-color-primary`
+ * → `colorPrimary`) — see `applyTheme()` in `consenti-setup.ts` for the full mapping. */
 interface ThemeConfig {
-    bgColor?: string;
-    textColor?: string;
-    primaryColor?: string;
-    primaryTextColor?: string;
-    secondaryColor?: string;
-    secondaryTextColor?: string;
-    borderColor?: string;
+    colorBg?: string;
+    colorText?: string;
+    colorTextMuted?: string;
+    colorPrimary?: string;
+    colorPrimaryText?: string;
+    colorSecondary?: string;
+    colorSecondaryText?: string;
+    colorBorder?: string;
+    colorSecondaryBorder?: string;
+    colorOverlay?: string;
+    colorAccent?: string;
+    colorAccentText?: string;
     fontFamily?: string;
+    fontFamilyMono?: string;
     fontSizeBase?: string;
     fontSizeHeading?: string;
     fontSizeMultiplier?: string;
+    fontWeightHeading?: string;
+    lineHeight?: string;
+    spacingXs?: string;
+    spacingSm?: string;
+    spacingMd?: string;
+    spacingLg?: string;
     borderRadius?: string;
-    buttonBorderRadius?: string;
+    borderRadiusBtn?: string;
+    shadow?: string;
     toggleBgOn?: string;
+    toggleBgPartial?: string;
     toggleBgOff?: string;
-    accentColor?: string;
-    accentTextColor?: string;
+    toggleKnob?: string;
+    toggleWidth?: string;
+    toggleHeight?: string;
+    zBanner?: string;
+    zOverlay?: string;
+    zModal?: string;
 }
 interface CoreConfig {
     tenantId?: string;
     locale?: string;
-    /** Text direction for the banner/modal root. `'auto'` (default) derives it from `locale`
-     * (Arabic, Hebrew, Persian, Urdu, ... → `rtl`); set explicitly to override. */
+    /** Text direction for the banner/modal root. `'auto'` (default) derives it from `locale` via
+     * `Intl.Locale(...).getTextInfo().direction` (falling back to a hand-maintained RTL-language
+     * list on engines without `getTextInfo()` support); set explicitly to override. */
     dir?: 'ltr' | 'rtl' | 'auto';
     disableCssTemplate?: boolean;
     cookieSigningKey?: string;
     allowReceipt?: boolean;
     cookieDomains?: string;
+    /** Name of the consent cookie/localStorage key. Default: `'consenti_data'`. Not switched
+     * automatically by detected region — set explicitly if you want a different name (e.g.
+     * `'euconsent-v2'`, the IAB TCF convention, but only meaningful for operators using the
+     * spec-correct binary encoder — `@consenti/api` + the optional `@iabtechlabtcf/core` peer
+     * dependency — since the IAB name implies IAB's binary format, not Consenti's own encoding). */
+    cookieName?: string;
     storage?: 'cookie' | 'localStorage';
     theme?: ThemeConfig;
+    /** Initial logged-in application user ID; empty/anonymous when unset. Prefer `getUserId()`/
+     * `setUserId()` (or the `consenti:listener:identify` event) to change it after init — those
+     * also handle reconsent when the identity changes on a shared device. */
     userId?: string;
     usePrebuiltProfiles?: 'all' | NonEmptyArray<ComplianceGroupId>;
     cacheResolvedProfiles?: boolean;
@@ -404,10 +565,25 @@ interface ConsentiConfig {
     utils?: UtilsConfig;
     plugins?: ConsentiPlugin$1[];
     profileOverride?: DeepPartial<ResolvedProfile>;
+    /** Per-compliance-group text/button/cookie overrides — applied on top of whichever profile the
+     * visitor's resolved group loads, keyed by that group's id (one of the 8 built-in
+     * `ComplianceGroupId`s, or any custom group id). Lets you author different copy per country
+     * without creating a separate profile (and separate `compliance.type` wiring) for each one —
+     * e.g. `{ 'opt-in': { mainBanner: { htmlText: '...' } }, 'my-custom-group': { ... } }`.
+     * Applied before `profileOverride`, which still always applies last as the universal catch-all.
+     * Works identically in standalone and server (`api.enabled`) mode. */
+    complianceGroupsOverride?: Partial<Record<ComplianceGroupId | (string & {}), DeepPartial<ResolvedProfile>>>;
     /** When true, suppresses the "Powered by Consenti" footer link in the banner and modal. */
     hidePoweredBy?: boolean;
 }
-type ConsentiEventName = 'bannerInitialized' | 'consenti:bannerInitialized' | 'bannerVisibility' | 'consenti:bannerVisibility' | 'modalVisibility' | 'consenti:modalVisibility' | 'consentBeingSubmitted' | 'consenti:consentBeingSubmitted' | 'consentSubmitted' | 'consenti:consentSubmitted' | 'parentalConsentRequired' | 'consenti:parentalConsentRequired';
+type ConsentiEventName = 'bannerInitialized' | 'consenti:bannerInitialized' | 'bannerVisibility' | 'consenti:bannerVisibility' | 'modalVisibility' | 'consenti:modalVisibility' | 'consentBeingSubmitted' | 'consenti:consentBeingSubmitted' | 'consentSubmitted' | 'consenti:consentSubmitted' | 'parentalConsentRequired' | 'consenti:parentalConsentRequired' | 'forgetMeRequested' | 'consenti:forgetMeRequested' | 'forgotten' | 'consenti:forgotten';
+/** Snapshot of the current visitor's identity. `visitorId` is `null` until a consent decision
+ * has actually happened — it's never minted just to answer this call, see `getVisitor()`. */
+interface VisitorIdentity {
+    visitorId: string | null;
+    type: 'authenticated' | 'anonymous';
+    userId: string | null;
+}
 interface ConsentiWidgetAPI {
     hasConsent(): boolean;
     getConsent(): ConsentValue | null;
@@ -438,10 +614,25 @@ interface ConsentiWidgetAPI {
     submitConsent(consent: Partial<ConsentValue>): Promise<ConsentDbRecord | void>;
     deleteConsent(): Promise<void>;
     reConsent(): Promise<void>;
+    /** Erases the stored consent record (same underlying call as `deleteConsent()`) and
+     * re-prompts, dispatching `consenti:forgetMeRequested` / `consenti:forgotten` around it so a
+     * host app can hook its own identity-verified erasure workflow. Powers the preference modal's
+     * "Forget me" button; also callable directly for a custom placement of the same action. */
+    forgetMe(resetAgeGate?: boolean): Promise<void>;
     getRootElement(): HTMLElement | null;
     getBannerElement(): HTMLElement | null;
     getModalElement(): HTMLElement | null;
     switchLocale(locale: string): void;
+    getUserId(): string | null;
+    /** Sets the logged-in application user ID (`null` for anonymous/logout). When the stored
+     * consent record's user differs from the new value, reconsents by default — pass
+     * `reConsent: false` to just update the identity without prompting again. No-ops (no
+     * reconsent, no warning) when there's no prior consent record to compare against. */
+    setUserId(userId: string | null, reConsent?: boolean): Promise<void>;
+    /** Snapshot of the current visitor's identity: the stable per-browser `visitorId` (`null` if
+     * no consent decision has happened yet — this never creates one), whether they're
+     * `authenticated` or `anonymous`, and the app `userId` (same as `getUserId()`). */
+    getVisitor(): VisitorIdentity;
     setDarkMode(enable?: boolean): void;
     setTheme(theme: Partial<ThemeConfig>): void;
     setConfig(config: DeepPartial<ConsentiConfig>): void;
@@ -520,17 +711,52 @@ interface ConsentBeingSubmitted {
 interface ConsentSubmittedDetail extends ConsentBeingSubmitted {
     apiResponse: ConsentDbRecord;
 }
-/** Dispatched when the age gate is declined and `requireParentalConsent` is set — see
- * `AgeGateWidgetConfig`. A deny-all consent (mandatory cookies only) has already been
+/** Dispatched when the age gate is declined and `requireParentalConsent` is set — see the
+ * profile's `AgeGateConfig`. A deny-all consent (mandatory cookies only) has already been
  * submitted with `parentalConsentToken` attached; this event is the hook for the site
- * owner to run their own out-of-band parental-consent verification. */
+ * owner to run their own out-of-band parental-consent verification. `parentalConsentToken` is
+ * server-issued (and signed, when `compliance.dataSigningHash` is configured) when `api.enabled`,
+ * otherwise a client-generated, unsigned fallback — see `POST /consent/:visitorId/parental-consent-request`. */
 interface ParentalConsentRequiredDetail {
     parentalConsentToken: string;
     profileId: string;
     visitorId: string;
     timestamp: number;
 }
-type ConsentEvent = BannerInitializedDetail | BannerVisibilityDetail | ModalVisibilityDetail | ConsentBeingSubmitted | ConsentSubmittedDetail | ParentalConsentRequiredDetail;
+/** Dispatched by the standalone `resolveParentalConsent()` util (`apps/ui/src/utils/parental-consent.ts`)
+ * after `POST /consent/parental-consent-resolve` succeeds — typically from a fresh page/session
+ * with no live `ConsentiSetup` instance (the parent's own device, not the child's). A page that
+ * does have a live widget instance can listen for this to react (e.g. re-show the banner/modal for
+ * the real consent choice); what "resolved" should actually do to consent state is host-defined. */
+interface ParentalConsentGrantedDetail {
+    visitorId: string;
+    profileId: string;
+}
+/** Detail payload for the inbound `consenti:listener:identify` event — dispatched by the *host*
+ * page (not the widget) to tell the widget which application user is logged in, equivalent to
+ * calling `setUserId(userId, reConsent)`. `reConsent` defaults to `true`. */
+interface IdentifyEventDetail {
+    userId: string | null;
+    reConsent?: boolean;
+}
+/** Dispatched by `forgetMe()` right before the erasure call goes out — the hook for a host app
+ * to kick off its own identity-verified erasure workflow across other systems (CRM, DMP,
+ * analytics). The CMP itself only ever erases its own consent record; see the server-side
+ * `consent.erased` eventBus event (fired by `DELETE /consent/:visitorId`) for the same hook on
+ * the backend. See the "Right to erasure" guide for the full picture. */
+interface ForgetMeRequestedDetail {
+    visitorId: string;
+    profileId: string;
+    timestamp: number;
+}
+/** Dispatched by `forgetMe()` after the consent record has been erased and the banner/age-gate
+ * has been re-prompted (see `reConsent()`, which `forgetMe()` wraps). */
+interface ForgottenDetail {
+    visitorId: string;
+    profileId: string;
+    timestamp: number;
+}
+type ConsentEvent = BannerInitializedDetail | BannerVisibilityDetail | ModalVisibilityDetail | ConsentBeingSubmitted | ConsentSubmittedDetail | ParentalConsentRequiredDetail | ParentalConsentGrantedDetail | ForgetMeRequestedDetail | ForgottenDetail;
 type ConsentiMessage = {
     type: 'consentUpdated';
     consent: ConsentValue;
@@ -563,6 +789,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private initializing;
     private profile;
     private resolvedBase;
+    private profilePatches;
     /** cookieId → Category lookup, rebuilt whenever `profile` changes. Avoids rescanning categories on every consent action. */
     private categoryIndex;
     /** Watchers created by the declarative `data-consenti-*` DOM scan — destroyed alongside the widget since they have no other owner. */
@@ -595,6 +822,8 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private _bannerMounted;
     /** Active focus trap keydown listener — removed when modal closes. */
     private _focusTrapListener;
+    /** Inbound `consenti:listener:identify` window listener — installed once per init(), removed on destroy(). */
+    private _identifyListener;
     /** Maps original handler functions to their DOM-wrapped listeners for on/off bookkeeping. */
     private _eventHandlers;
     /** `core` defaulted to `{}` in the constructor below — every one of its own fields is
@@ -611,6 +840,29 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      */
     constructor(config: ConsentiConfig);
     private profileId;
+    /** Patches `base` with `complianceGroupsOverride[base.complianceGroup]`, if both exist — the
+     * per-group counterpart to `profileOverride`. Lets an author supply different text/buttons/
+     * cookies per compliance group (built-in or custom) without authoring a separate profile for
+     * each one. Applied before `profileOverride`, which still always wins as the final catch-all. */
+    private applyComplianceGroupOverride;
+    /**
+     * Applied in order: compliance-group override → `config.profileOverride` → each `setProfile()`
+     * patch. The `setProfile()` patches are kept as a list and replayed, not folded into one
+     * object, because folding runs `deepMerge` patch-onto-patch, which consumes `null`/`'*': null`
+     * delete markers before they ever reach the profile they were meant to delete from.
+     */
+    private applyProfileOverrides;
+    private warnIfAcceptOnly;
+    /**
+     * Whether `window.__tcfapi`/`window.__gpp` should stay uninstalled because the corresponding
+     * server-side registration (`compliance.tcf`/`compliance.gpp`) is unconfirmed (cmpId/cmpVersion
+     * changed since the dashboard's confirmation checkbox was last checked, or never confirmed).
+     * Standalone (no-backend) deployments have no governance layer to check against, so this always
+     * resolves `false` there — the client-side config is used as configured, same as before this
+     * feature existed. A network failure fails closed (`true`) rather than assuming the
+     * unverifiable state is fine.
+     */
+    private isRegistrationBlocked;
     /**
      * Starts widget initialisation. Called automatically unless `autoInit: false` is set.
      * Can be called explicitly after construction when `autoInit: false`, or after `destroy()`
@@ -624,7 +876,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * `resolveAgeGate()`, then resume here with `hasExisting` fixed at `false`.
      */
     private continueInit;
-    /** Mounts the age-gate prompt (`compliance.ageGate`) in place of the normal banner flow. */
+    /** Mounts the age-gate prompt (`profile.ageGate`) in place of the normal banner flow. */
     private showAgeGate;
     /**
      * Handles the visitor's age-gate answer.
@@ -647,13 +899,35 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * a resolved profile to read consent from.
      */
     private finishInit;
+    /** Installs the inbound `consenti:listener:identify` window listener — the event-driven
+     * counterpart to `setUserId()`. Removes any previously-installed listener first so repeated
+     * `init()` calls (e.g. from `switchLocale()`) don't stack up duplicate listeners. */
+    private _installIdentifyListener;
+    /** Returns the current logged-in application user ID, or `null` for an anonymous visitor. */
+    getUserId(): string | null;
+    /**
+     * Sets the logged-in application user ID (`null` for anonymous/logout). If a stored consent
+     * record exists and its user differs from `userId`, this is treated as a different data
+     * subject on a shared device: by default it reconsents (deletes the existing record and
+     * re-shows the banner) and logs a warning. Pass `reConsent: false` to just update the identity
+     * without prompting again (still logs the warning). No-ops entirely — no warning, no
+     * reconsent — when there is no prior consent record to compare against (true first-time visitor).
+     */
+    setUserId(userId: string | null, reConsent?: boolean): Promise<void>;
+    /**
+     * Snapshot of the current visitor's identity. `visitorId` is the stable per-browser ID —
+     * `null` until a consent decision has actually happened, since this never mints one just to
+     * answer the call (see `getOrCreateVisitorId()`). `type` is `'authenticated'` whenever a
+     * `userId` is set (via `setUserId()` or `core.userId`), `'anonymous'` otherwise.
+     */
+    getVisitor(): VisitorIdentity;
     /** Sets the `dir` attribute on the root element from `core.dir` (default `'auto'`, derived from `core.locale`). */
     private applyDirection;
     /** Applies the `consenti-root--dark` class based on config or profile flag. */
     private applyDarkMode;
     /** Applies `consenti--enhanced-a11y` class when `profile.enhanceAccessibility` is set. */
     private applyAccessibility;
-    /** Builds and appends the metadata footer strip to a banner or modal container. */
+    /** Builds and appends the metadata footer strip to modal container. */
     private _appendMetaFooter;
     /**
      * Injects a `<style>` element into the root for `stackButtonsOnBreakpoint`.
@@ -697,8 +971,16 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * Pass `type` to get a vendor-ready object instead of the raw Consenti format.
      * Always returns `null` during SSR or when no consent has been saved.
      *
-     * @param type - Vendor format: 'google-gtm', 'category', 'adobe', 'meta',
-     *               'microsoft-clarity', 'twilio-segment', or omit for raw format.
+     * @param type - Output format:
+     *   - omit / `'default'`  → raw ConsentValue, keyed by every cookie parameter ID in the profile
+     *   - `'purpose'`         → consent per the fixed CookiePurpose taxonomy (necessary/functional/preferences/analytics/marketing)
+     *   - `'category'`        → consent per the tenant's own authored preference-modal category, keyed by category ID
+     *                           ('granted' only when every member parameter is granted; 'denied'/'objected' otherwise)
+     *   - `'google-gtm'`      → Google Consent Mode v2 keys + ads_data_redaction, url_passthrough
+     *   - `'adobe'`           → { analytics, target, manager, optimizer }
+     *   - `'meta'`            → { pixel, api, plugins, facebookLogin }
+     *   - `'microsoft-clarity'` → { session, heatmaps, performance }
+     *   - `'twilio-segment'`  → { identify, page, track, group, alias }
      */
     getConsent(): ConsentValue | null;
     getConsent(type: ConsentType): Record<string, string> | null;
@@ -790,8 +1072,30 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * method so callers do not need to coordinate the async deletion with the banner display.
      *
      * Use this to power "Review my consent" links in footers or privacy dashboards.
+     *
+     * @param resetAgeGate - When `true` (default) and the profile has `ageGate.enabled`, the
+     *                        age-gate prompt is shown again instead of jumping straight to the
+     *                        banner — mirroring the original first-visit flow. Pass `false` to
+     *                        skip it and go straight to the banner, keeping the visitor's prior
+     *                        age-gate answer.
+     */
+    reConsent(resetAgeGate?: boolean): Promise<void>;
+    /**
+     * Self-service erasure entry point — GDPR Art. 17 / CCPA-CPRA / LGPD Art. 18 and equivalent
+     * "right to be forgotten" rights, exercised from the widget itself. Wraps `reConsent()` (same
+     * erase-then-reprompt behavior) with `consenti:forgetMeRequested` / `consenti:forgotten`
+     * dispatched around it, so a host app can hook its own identity-verified erasure workflow
+     * across other systems (CRM, DMP, analytics) — the CMP itself only ever erases its own consent
+     * record. See the "Right to erasure" guide for the full picture, including the server-side
+     * `consent:erased` eventBus event fired by `DELETE /consent/:visitorId`.
+     *
+     * Powers the preference modal's "Forget me" button (`preferenceModal.showForgetMe`, only
+     * rendered when the visitor already has a stored consent decision). Also callable directly —
+     * e.g. `widget.forgetMe()` from a custom footer link or privacy-settings page.
+     *
+     * @param resetAgeGate - Forwarded to `reConsent()` — see its docs.
      */
-    reConsent(): Promise<void>;
+    forgetMe(resetAgeGate?: boolean): Promise<void>;
     /**
      * Returns the fully resolved profile for the current session, or `null` during the
      * async init phase (before the profile has been fetched/resolved).
@@ -1470,4 +1774,44 @@ declare class BannerTrigger {
  */
 declare function scanConsentScripts(widget: ConsentiSetup): Array<ConsentScript | CategoryScript>;
 
-export { type AgeGateWidgetConfig, type ApiConfig, BannerTrigger, type BannerTriggerOptions, type Button, type ButtonAction, type ButtonStyle, type Category, CategoryAction, type CategoryActionOptions, type CategoryActionParams, type CategoryMap, CategoryScript, type CategoryScriptOptions, type ComplianceWidgetConfig, ConsentAction, type ConsentActionOptions, type ConsentActionParams, type ConsentAction$1 as ConsentActionType, type ConsentEvent, type ConsentReceipt, type ConsentRecord, ConsentScript, type ConsentScriptOptions, type ConsentStatus, type ConsentValue, type ConsentiConfig, type ConsentiEventName, type ConsentiMessage, ConsentiPlugin, ConsentiProfile, ConsentiSetup, type ConsentiWidgetAPI, type Cookie, type CookieMap, type CookieOptions, type CoreConfig, type GpcBanner, type GtmConfig, type LocaleTranslations, type MainBanner, type ParentalConsentRequiredDetail, type ParsedConsent, type PreferenceModal, type ProfileConfig, type ProfileTranslations, type RegisterableProfileConfig, type ResolvedProfile, type TcfWidgetConfig, type ThemeConfig, type UtilsConfig, scanConsentScripts };
+/**
+ * Standalone resolver for the parental-consent hook (see `AgeGate`/`ConsentiSetup.resolveAgeGate`).
+ * Not a `ConsentiSetup` instance method — the parent typically opens the token link (emailed by
+ * the host's own eventBus listener, see `consenti:parentalConsentRequired`) on a fresh page or
+ * even a different device, with no live widget instance around at all.
+ */
+
+interface ParentalConsentApiConfig {
+    baseUrl?: string;
+    authToken?: string;
+}
+/**
+ * POSTs a parental-consent token to `POST /consent/parental-consent-resolve`. On success,
+ * dispatches `consenti:parentalConsentResolved` on `window` (same mechanism `EventBus.dispatch`
+ * uses) so any page with a live widget instance can react — what "resolved" should actually do to
+ * consent state is left to that listener, matching the "we provide the hook, not the behavior"
+ * scope of this whole feature. Throws on an invalid/expired token or network failure.
+ */
+declare function resolveParentalConsent(token: string, apiConfig?: ParentalConsentApiConfig): Promise<ParentalConsentGrantedDetail>;
+
+/**
+ * Builds a synchronous, dependency-free `<head>` snippet that freezes Google Consent Mode
+ * to denied-by-default the instant a visitor's browser sends the Global Privacy Control (GPC)
+ * signal — before any tag-loading script runs, including GTM/gtag.js itself and Consenti's own
+ * bundle (which only applies GPC once it has loaded, parsed, and initialized asynchronously).
+ *
+ * This is a documentation helper, not something the widget loads itself: paste the returned
+ * string as the very first `<script>` in `<head>`, ahead of GTM/gtag.js and the Consenti bundle.
+ * It only touches `window[dataLayerName]`/`window.gtag` (the same stub-queue pattern
+ * `EventBus.initConsentMode()` uses), so it's safe to run before those exist and harmless to
+ * run again after they do — Consenti's own `gtag('consent', 'default', …)` call on init just
+ * pushes another entry onto the same queue.
+ *
+ * The default values pushed here mirror `getGoogleGTMConsent({})` in `consent-mapper.ts` (safe
+ * defaults for an empty consent map) — keep the two in sync if either changes.
+ */
+declare function buildSyncGpcSnippet(options?: {
+    dataLayerName?: string;
+}): string;
+
+export { type ApiConfig, BannerTrigger, type BannerTriggerOptions, type Button, type ButtonAction, type ButtonStyle, type Category, CategoryAction, type CategoryActionOptions, type CategoryActionParams, type CategoryMap, CategoryScript, type CategoryScriptOptions, type ComplianceWidgetConfig, ConsentAction, type ConsentActionOptions, type ConsentActionParams, type ConsentAction$1 as ConsentActionType, type ConsentEvent, type ConsentReceipt, type ConsentRecord, ConsentScript, type ConsentScriptOptions, type ConsentStatus, type ConsentValue, type ConsentiConfig, type ConsentiEventName, type ConsentiMessage, ConsentiPlugin, ConsentiProfile, ConsentiSetup, type ConsentiWidgetAPI, type Cookie, type CookieMap, type CookieOptions, type CoreConfig, type GpcBanner, type GtmConfig, type IdentifyEventDetail, type LocaleTranslations, type MainBanner, type ParentalConsentApiConfig, type ParentalConsentGrantedDetail, type ParentalConsentRequiredDetail, type ParsedConsent, type PreferenceModal, type ProfileConfig, type ProfileTranslations, type RegisterableProfileConfig, type ResolvedProfile, type TcfWidgetConfig, type ThemeConfig, type UtilsConfig, type VisitorIdentity, buildSyncGpcSnippet, resolveParentalConsent, scanConsentScripts };