@consenti/ui 0.3.0 → 0.4.0

package/dist/vue.d.cts

@@ -13,6 +13,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"];
 
@@ -44,11 +70,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 {
@@ -63,9 +92,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;
@@ -76,15 +106,18 @@ type ConsentAction = '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];
@@ -172,12 +205,46 @@ 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 DpdpaConfig {
     dataFiduciary: string;
     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 ResolvedProfile {
     id: string;
     /** Incremented in place on every save of this profile. Absent for embedded/local profiles that have no server-side version counter. */
@@ -193,9 +260,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;
@@ -208,26 +287,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;
@@ -248,37 +367,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;
@@ -298,10 +447,25 @@ interface ConsentiConfig {
     utils?: UtilsConfig;
     plugins?: ConsentiPlugin[];
     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;
@@ -332,10 +496,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;
@@ -383,17 +562,45 @@ 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;
+}
+/** 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;
 
 /**
  * Main entry point for the Consenti widget.
@@ -449,6 +656,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
@@ -465,6 +674,21 @@ 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;
+    /**
+     * 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()`
@@ -478,7 +702,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.
@@ -501,13 +725,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`.
@@ -551,8 +797,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;
@@ -644,8 +898,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(): Promise<void>;
+    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.
+     */
+    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).
@@ -824,14 +1100,21 @@ declare function useConsent(): {
     denyAll: (includingMandatory?: boolean) => Promise<void>;
     /** Saves the given partial consent map. */
     submitConsent: (c: Partial<ConsentValue>) => Promise<void | ConsentDbRecord>;
-    /** Deletes the current consent record and re-shows the banner. */
-    reConsent: () => Promise<void>;
+    /** Deletes the current consent record and re-shows the banner. Pass `false` to skip
+     * re-showing the age-gate prompt (if the profile has one) and go straight to the banner. */
+    reConsent: (resetAgeGate?: boolean) => Promise<void>;
     /** Returns `true` if the given cookie ID is `'granted'`. */
     isCookieGranted: (id: string) => boolean;
     /** Returns `true` if every cookie in the given category is `'granted'`. */
     isCategoryGranted: (id: string) => boolean;
     /** Switches the active locale and re-renders the banner and modal. */
     switchLocale: (locale: string) => void | undefined;
+    /** Returns the current logged-in application user ID, or `null` if anonymous. */
+    getUserId: () => string | null;
+    /** Sets the logged-in application user ID; reconsents by default when it changes. */
+    setUserId: (userId: string | null, reConsent?: boolean) => Promise<void>;
+    /** Snapshot of the current visitor's identity (`visitorId`, `type`, `userId`). */
+    getVisitor: () => VisitorIdentity;
 };
 
 export { setConsentiWidget, useConsent };