@consenti/ui 0.2.0 → 0.3.0

package/dist/profiles-OEZAKEWL.mjs

@@ -0,0 +1,2 @@
+import{a,b,c,d,e,f,g,h,i,j}from"./chunk-J4BKXUD6.mjs";export{i as DEFAULT_PROFILES,g as GENERAL_PRIVACY_CONSENT_EN_PROFILE,h as NOTICE_ONLY_EN_PROFILE,f as OPT_IN_BRAZIL_EN_PROFILE,e as OPT_IN_CHINA_EN_PROFILE,d as OPT_IN_DPDPA_EN_PROFILE,a as OPT_IN_EN_PROFILE,b as OPT_OUT_EN_PROFILE,c as OPT_OUT_STRICT_EN_PROFILE,j as resolveLocaleTranslation};
+//# sourceMappingURL=profiles-OEZAKEWL.mjs.map

package/dist/profiles-OEZAKEWL.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react.d.cts

@@ -1,9 +1,18 @@
 type NonEmptyArray<T> = [T, ...T[]];
+/**
+ * Deep-partial with JSON Merge Patch (RFC 7396) delete semantics: any key may be
+ * set to `null` instead of its usual type to signal "delete this key" when the
+ * partial is applied with `deepMerge()` — `undefined`/omitted keeps the base
+ * value, `null` removes it. Only meaningful for object/map keys (e.g. removing
+ * a `CategoryMap`/`CookieMap` entry via `profileOverride`); array elements are
+ * merged positionally and don't support deletion this way.
+ */
 type DeepPartial<T> = T extends Function ? T : T extends Array<infer InferredArrayType> ? Array<DeepPartial<InferredArrayType>> : T extends ReadonlyArray<infer InferredReadonlyArrayType> ? ReadonlyArray<DeepPartial<InferredReadonlyArrayType>> : T extends object ? {
-    [Key in keyof T]?: DeepPartial<T[Key]>;
+    [Key in keyof T]?: DeepPartial<T[Key]> | null;
 } : T;
 
 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"];
 
 /**
  * Compliance-related literal types, derived from the regulation/group ID data
@@ -19,6 +28,13 @@ declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-stri
  */
 
 type ComplianceGroupId = typeof COMPLIANCE_GROUP_IDS[number];
+/**
+ * `(string & {})` (rather than plain `string`) keeps IDE autocomplete for the
+ * known `ComplianceGroupId` literals while still allowing any other string —
+ * used to target a profile authored against a custom (non-built-in)
+ * `customComplianceGroup` instead of one of the 8 built-in groups.
+ */
+type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
@@ -33,24 +49,67 @@ interface CountryComplianceEntry {
         description: string;
     }>;
 }
+interface ConsentDbRecord {
+    id: string;
+    tenantId: string;
+    visitorId: string;
+    profileId: string;
+    locale: string;
+    consentJson: ConsentValue;
+    gpcDetected: boolean;
+    source: 'banner' | 'api' | 'import';
+    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`). */
+    signature?: string;
+    createdAt: string;
+    updatedAt: string;
+}
 
 type ConsentStatus = 'granted' | 'denied' | 'objected';
 type ConsentAction = 'accept_all' | 'reject_all' | 'custom' | 'update';
 type ConsentValue = Record<string, ConsentStatus>;
+/**
+ * Output format for getConsent(type).
+ * 'default'           → raw ConsentValue (existing behaviour)
+ * 'google-gtm'        → Google Consent Mode v2 keys + ads_data_redaction, url_passthrough
+ * 'category'          → consent per CookiePurpose category
+ * '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 GpcMode = 'ignore' | 'honor' | 'strict';
+type LegalBasis = 'mandatory' | 'consent' | 'legitimate_interest';
+type CookiePurpose = typeof COOKIE_PURPOSE_IDS[number];
+/**
+ * A single consent parameter (tracker/cookie definition).
+ * Keyed by its own id inside `Record<string, Cookie>` — the map key IS the id,
+ * there is no `id` field on the value itself.
+ */
 interface Cookie {
-    id: string;
-    legalBasis?: 'mandatory' | 'consent' | 'legitimate_interest';
-    /** @deprecated use legalBasis: 'mandatory' */
-    mandatory?: boolean;
-    /** @deprecated use legalBasis */
-    type?: 'consent' | 'legitimate_interest';
+    purpose?: CookiePurpose;
     listenGpc?: boolean;
-    expiry?: number;
+    /**
+     * Pre-grant this parameter's default consent to 'granted' (instead of the
+     * compliance-group-driven default) when no stored decision exists yet.
+     * Only meaningful when the owning category's `legalBasis === 'consent'` —
+     * `mandatory`/`legitimate_interest` categories are already effectively
+     * pre-granted regardless of this flag. Never overrides an active GPC signal.
+     * Default: false.
+     */
+    preGrant?: boolean;
     tcfVendorId?: number;
     tcfPurposes?: number[];
     tcfSpecialFeatures?: number[];
     cpraCategory?: 'sale' | 'sharing' | 'sensitive';
 }
+/** `Cookie` keyed by its own id — the standard shape used everywhere a parameter list is passed around. */
+type CookieMap = Record<string, Cookie>;
 type ButtonStyle = 'primary' | 'secondary' | 'text' | 'accent';
 type ButtonAction = 'submit' | 'manage' | 'close' | 'custom' | 'link';
 interface Button {
@@ -59,8 +118,11 @@ interface Button {
     action: ButtonAction;
     cookies?: string[] | '*' | '!';
     url?: string;
-    type?: string;
 }
+/** `Button` keyed by its own id — e.g. `'accept-all'`. The map key IS the id, rendered as the DOM
+ * `id` (`consenti-btn-{id}`) so integrators can target specific buttons, and is what
+ * `profileOverride`'s `deepMerge` deletes by (`{ 'reject-optional': null }` removes one button). */
+type ButtonMap = Record<string, Button>;
 interface MainBanner {
     position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
     overlayOpacity?: number;
@@ -69,29 +131,45 @@ interface MainBanner {
     heading?: string;
     headingTag?: string;
     htmlText: string;
-    buttons: Button[];
+    buttons: ButtonMap;
+    /** Stack buttons vertically below this viewport width in px. 0 or undefined = disabled. Default: 576. */
+    stackButtonsOnBreakpoint?: number;
+    /** Trap keyboard Tab focus within the consent root while this banner is visible. */
+    trapFocus?: boolean;
 }
 type GpcBanner = MainBanner;
+/**
+ * A consent category — the single source of legal basis for every parameter
+ * it lists in `cookies`. Keyed by its own id inside `Record<string, Category>` —
+ * the map key IS the id, there is no `id` field on the value itself.
+ *
+ * A parameter must belong to exactly one category (enforced at authoring time,
+ * not by this type) — that relationship is what `getCookieLegalBasis`/
+ * `isMandatoryCookie` (`@consenti/utils`) resolve at runtime.
+ */
 interface Category {
-    id: string;
     heading: string;
     headingTag?: string;
     htmlText: string;
-    mandatory?: boolean;
-    type?: 'consent' | 'legitimate_interest';
-    legitimateInterest?: {
-        enabled?: boolean;
-        description?: string;
-    };
+    legalBasis: LegalBasis;
+    /** Only meaningful when legalBasis === 'legitimate_interest' — the GDPR balancing-test justification shown to visitors. */
+    legitimateInterestDescription?: string;
+    /** IDs of the parameters (from the profile's `cookies` map) that belong to this category. */
     cookies: string[];
 }
+/** `Category` keyed by its own id — the standard shape used everywhere a category list is passed around. */
+type CategoryMap = Record<string, Category>;
 interface PreferenceModal extends Omit<MainBanner, "position"> {
     position?: 'left' | 'right' | 'center';
     subheading?: string;
-    categories: Category[];
+    categories: CategoryMap;
     persistent?: boolean;
     /** Screen width in px below which the modal expands to full screen. Default: 576. Set to 0 to disable. */
     mobileFullScreenBreakpoint?: number;
+    /** Label for the optional consent-receipt download checkbox (shown when `allowReceipt` is true). Falls back to a default when omitted. */
+    receiptLabel?: string;
+    /** Description shown beneath the consent-receipt checkbox. Falls back to a default when omitted. */
+    receiptDescription?: string;
 }
 interface DpdpaConfig {
     dataFiduciary: string;
@@ -99,21 +177,30 @@ interface DpdpaConfig {
     purposeDescription?: string;
 }
 interface ResolvedProfile {
-    id: number;
-    profileUuid?: string;
-    version: number;
+    id: string;
+    /** Incremented in place on every save of this profile. Absent for embedded/local profiles that have no server-side version counter. */
+    version?: number;
     defaultLocale: string;
     locales?: string[];
-    cookies: Cookie[];
+    cookies: CookieMap;
+    /** Days until consent expires and the visitor is asked again (profile-wide). Default: 365. */
+    expiryDays?: number;
+    allowReceipt?: boolean;
     mainBanner: MainBanner;
     gpcBanner?: GpcBanner;
     preferenceModal: PreferenceModal;
     cookieSigningKey?: string;
     dpdpa?: DpdpaConfig;
     darkMode?: boolean;
-    gpcMode?: 'ignore' | 'honor' | 'strict';
-    complianceGroup?: string;
+    gpcMode?: GpcMode;
+    complianceGroup?: ComplianceGroupId;
     complianceConfig?: Record<string, string>;
+    /** Falls back to `true` (hidden) if neither the widget config nor the profile set it. */
+    hidePoweredBy?: boolean;
+    /** Show metadata footer strip (Consent ID, Date, Version, Privacy Settings link). */
+    showFooterMetadata?: boolean;
+    /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
+    enhanceAccessibility?: boolean;
 }
 type WidgetCountryResolverFn = () => Promise<{
     country: string | null;
@@ -125,12 +212,20 @@ interface AgeGateWidgetConfig {
     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. */
+interface TcfWidgetConfig {
+    enabled: boolean;
+    cmpId: number;
+    cmpVersion: number;
+}
 interface ComplianceWidgetConfig {
-    type?: 'auto' | ComplianceGroupId | string;
+    type?: ComplianceType;
     geoDataProvider?: 'default' | WidgetCountryResolverFn;
     autoComplianceMap?: 'default' | ComplianceMapData | 'auto';
     complianceMapUrl?: string;
     ageGate?: AgeGateWidgetConfig;
+    tcf?: TcfWidgetConfig;
 }
 interface GtmConfig {
     containerId?: string;
@@ -138,6 +233,7 @@ interface GtmConfig {
     dataLayer?: string;
     urlPassthrough?: boolean;
     adsDataRedaction?: boolean;
+    verbose?: boolean;
 }
 interface UtilsConfig {
     gtm?: GtmConfig;
@@ -147,7 +243,7 @@ interface ApiConfig {
     baseUrl?: string;
     authToken?: string;
     tenantId?: string;
-    complianceGroup?: string;
+    complianceGroup?: ComplianceGroupId;
     trustDomain?: boolean;
 }
 interface ThemeConfig {
@@ -171,8 +267,10 @@ interface ThemeConfig {
 }
 interface CoreConfig {
     tenantId?: string;
-    autoHonorGPC?: boolean | 'strict';
     locale?: string;
+    /** Text direction for the banner/modal root. `'auto'` (default) derives it from `locale`
+     * (Arabic, Hebrew, Persian, Urdu, ... → `rtl`); set explicitly to override. */
+    dir?: 'ltr' | 'rtl' | 'auto';
     disableCssTemplate?: boolean;
     cookieSigningKey?: string;
     allowReceipt?: boolean;
@@ -185,7 +283,11 @@ interface CoreConfig {
     console?: Array<'info' | 'log' | 'warning' | 'error'>;
 }
 interface ConsentiConfig {
-    core: CoreConfig;
+    verbose?: boolean;
+    /** Optional — every field of `CoreConfig` is itself optional, so `new ConsentiSetup({})` and
+     * `new ConsentiSetup({ compliance: { type: 'opt-in' } })` (omitting `core` entirely) both work,
+     * matching the widget's own "Minimal config" documentation. */
+    core?: CoreConfig;
     compliance?: ComplianceWidgetConfig;
     rootEl?: string | HTMLElement;
     darkMode?: boolean;
@@ -197,10 +299,12 @@ interface ConsentiConfig {
     /** 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';
+type ConsentiEventName = 'bannerInitialized' | 'consenti:bannerInitialized' | 'bannerVisibility' | 'consenti:bannerVisibility' | 'modalVisibility' | 'consenti:modalVisibility' | 'consentBeingSubmitted' | 'consenti:consentBeingSubmitted' | 'consentSubmitted' | 'consenti:consentSubmitted' | 'parentalConsentRequired' | 'consenti:parentalConsentRequired';
 interface ConsentiWidgetAPI {
     hasConsent(): boolean;
     getConsent(): ConsentValue | null;
+    getConsent(type: ConsentType): Record<string, string> | null;
+    getConsent(type?: ConsentType): ConsentValue | Record<string, string> | null;
     getConsentDate(): Date | false;
     getGTMConsent(): Record<string, string> | null;
     isCookieGranted(cookieId: string, requestValue?: boolean): boolean | ConsentStatus;
@@ -213,8 +317,8 @@ interface ConsentiWidgetAPI {
     off(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
     version(): {
         package: string;
-        profileVersion: number | null;
-        consentVersion: number;
+        profileVersion: string | null;
+        consentVersion: string | null;
     };
     bannerVisibility(): 'main' | 'gpc' | false;
     modalVisibility(): 'preference' | false;
@@ -223,7 +327,7 @@ interface ConsentiWidgetAPI {
     hideBanner(): void;
     showModal(triggerEl?: HTMLElement): void;
     hideModal(): void;
-    submitConsent(consent: Partial<ConsentValue>): Promise<void>;
+    submitConsent(consent: Partial<ConsentValue>): Promise<ConsentDbRecord | void>;
     deleteConsent(): Promise<void>;
     reConsent(): Promise<void>;
     getRootElement(): HTMLElement | null;
@@ -247,19 +351,47 @@ declare abstract class ConsentiPlugin {
     onModalShow?(): void | Promise<void>;
     onModalHide?(): void | Promise<void>;
 }
-interface ConsentEvent {
-    profileId?: number;
-    consent?: ConsentValue;
-    hasExistingConsent?: boolean;
-    show?: boolean;
-    action?: boolean;
-    consentAction?: ConsentAction;
-    consentId?: string;
-    pageUrl?: string;
-    apiResponse?: unknown;
+interface BannerInitializedDetail {
+    profileId: string;
+    complianceGroup?: ComplianceType;
+    hasExistingConsent: boolean;
+    gpcDetected: boolean;
+    willShow: boolean;
+}
+interface BannerVisibilityDetail {
+    visible: boolean;
+    variant: 'main' | 'gpc';
+    action: boolean;
+}
+interface ModalVisibilityDetail {
+    visible: boolean;
+    action: boolean;
+}
+interface ConsentBeingSubmitted {
+    consentId: string;
+    visitorId: string;
+    profileId: string;
+    consentJson: ConsentValue;
+    consentAction: ConsentAction;
+    gpcDetected: boolean;
+    pageUrl: string;
+    timestamp: number;
     fromBroadcast?: boolean;
-    gpcDetected?: boolean;
 }
+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
+ * submitted with `parentalConsentToken` attached; this event is the hook for the site
+ * owner to run their own out-of-band parental-consent verification. */
+interface ParentalConsentRequiredDetail {
+    parentalConsentToken: string;
+    profileId: string;
+    visitorId: string;
+    timestamp: number;
+}
+type ConsentEvent = BannerInitializedDetail | BannerVisibilityDetail | ModalVisibilityDetail | ConsentBeingSubmitted | ConsentSubmittedDetail | ParentalConsentRequiredDetail;
 
 /**
  * Main entry point for the Consenti widget.
@@ -279,16 +411,30 @@ interface ConsentEvent {
  */
 
 declare class ConsentiSetup implements ConsentiWidgetAPI {
-    private config;
     private initialized;
     private initializing;
     private profile;
     private resolvedBase;
+    /** 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. */
+    private scannedScripts;
     private consentStore;
+    /**
+     * Stable per-browser identifier. Created lazily the first time a consent decision actually
+     * happens (manual submit, GPC auto-response, or relaying a decision already made in another
+     * tab) — never minted before that, so an undecided visitor leaves nothing in storage. See
+     * `getOrCreateVisitorId()`.
+     */
+    private visitorId;
     private eventBus;
     private banner;
     private modal;
+    private ageGate;
     private renderer;
+    /** Set once the age gate (if enabled) resolves; threaded onto every `submitConsent` call thereafter. */
+    private _ageVerified;
+    private _parentalConsentToken;
     private broadcastChannel;
     private readyResolve;
     private readyPromise;
@@ -297,15 +443,23 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private lastSignature;
     /** Tracks which banner variant is currently visible, or null when hidden. */
     private _bannerVariant;
+    /** Tracks which banner variant is currently mounted in the DOM (persists when banner is hidden). */
+    private _bannerMounted;
+    /** Active focus trap keydown listener — removed when modal closes. */
+    private _focusTrapListener;
     /** 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
+     * optional, so this narrows back to non-optional for every other method in this class. */
+    private config;
     /**
      * Creates and initialises the consent widget.
      *
      * Construction is synchronous; the async `init()` is launched in the background.
      * Use `await widget.ready` or `widget.onReady(cb)` to run code after init completes.
      *
-     * @param config - Widget configuration. See `ConsentiConfig` for all options.
+     * @param config - Widget configuration. See `ConsentiConfig` for all options. `core` may be
+     *   omitted entirely — every one of its own fields is optional too.
      */
     constructor(config: ConsentiConfig);
     private profileId;
@@ -315,8 +469,53 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * to re-initialise the same instance.
      */
     init(): Promise<void>;
+    /**
+     * Everything after the "does consent already exist" check — GPC/CCPA/CPRA silent paths,
+     * then the normal opt-in banner. Extracted from `init()` so the age gate (when enabled and
+     * no consent exists yet) can defer this whole sequence until the visitor answers it via
+     * `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. */
+    private showAgeGate;
+    /**
+     * Handles the visitor's age-gate answer.
+     * - Confirmed → records `ageVerified: true` for all future `submitConsent` calls and
+     *   resumes the normal init flow via `continueInit()`.
+     * - Declined, no parental consent required → immediately submits a deny-all consent
+     *   (mandatory cookies still granted), mirroring the GPC-strict silent-write pattern.
+     * - Declined, parental consent required → same deny-all submission, plus a
+     *   `parentalConsentToken` and a `consenti:parentalConsentRequired` event so the site
+     *   owner can wire their own out-of-band verification flow (no email infra exists in
+     *   this package to do that here).
+     */
+    private resolveAgeGate;
+    /**
+     * Marks the widget ready and runs the declarative DOM-scan for
+     * `data-consenti-consent-script`/`data-consenti-category-script` tags. Called from
+     * every exit path of `init()` so the scan always runs exactly once per init cycle,
+     * whether `init()` was triggered automatically (`autoInit !== false`) or explicitly
+     * by the caller (`autoInit: false`) — it never runs before the widget actually has
+     * a resolved profile to read consent from.
+     */
+    private finishInit;
+    /** 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. */
+    private _appendMetaFooter;
+    /**
+     * Injects a `<style>` element into the root for `stackButtonsOnBreakpoint`.
+     * Called once per profile load; a new style replaces the previous one.
+     */
+    private applyStackButtonsBreakpoint;
+    /** Installs a keyboard focus trap on `container` while the modal is open. */
+    private _installFocusTrap;
+    /** Removes the active focus trap keyboard listener. */
+    private _removeFocusTrap;
     /**
      * Injects CSS custom property overrides supplied via `core.theme` into the
      * Consenti root element so they cascade down to all widget elements.
@@ -346,22 +545,23 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      */
     hasConsent(): boolean;
     /**
-     * Returns the stored consent map, or `null` if no consent has been saved.
-     * Always returns `null` during SSR.
+     * Returns the stored consent map, optionally transformed for a specific vendor.
+     * 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.
      */
     getConsent(): ConsentValue | null;
+    getConsent(type: ConsentType): Record<string, string> | null;
     /**
      * Returns the `Date` when consent was last saved, or `false` if no consent exists.
      * Always returns `false` during SSR.
      */
     getConsentDate(): Date | false;
     /**
-     * Returns the consent map in Google Consent Mode v2 format, ready to pass to
-     * `gtag('consent', 'update', ...)`. Returns `null` if no consent has been saved.
-     *
-     * Maps Consenti cookie IDs to the seven Google Consent Mode v2 parameters.
-     * Cookies whose IDs exactly match a GCM v2 key are forwarded directly.
-     * Non-GCM cookies are ignored by this method (they appear in `getConsent()` only).
+     * @deprecated Use `getConsent('google-gtm')` instead.
+     * Returns the consent map in Google Consent Mode v2 format.
      */
     getGTMConsent(): Record<string, string> | null;
     /**
@@ -373,7 +573,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * @param consent    - Partial or full map of cookie ID → status.
      * @param gpcDerived - Internal flag set to `true` when called from the GPC strict path.
      */
-    submitConsent(consent: Partial<ConsentValue>, gpcDerived?: boolean): Promise<void>;
+    submitConsent(consent: Partial<ConsentValue>, gpcDerived?: boolean, source?: number): Promise<ConsentDbRecord | void>;
     /**
      * Returns the currently visible banner variant, or `false` if no banner is shown.
      * Useful for programmatically checking state before calling `showBanner` / `hideBanner`.
@@ -542,8 +742,8 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      */
     version(): {
         package: string;
-        profileVersion: number | null;
-        consentVersion: number;
+        profileVersion: string;
+        consentVersion: string | null;
     };
     /**
      * Toggles or sets dark mode at runtime without re-initialising the widget.
@@ -577,45 +777,6 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     destroy(): void;
 }
 
-/**
- * React integration for `@consenti/ui`.
- *
- * Import from the `@consenti/ui/react` subpath to keep this module
- * tree-shaken out of vanilla JS or Vue bundles.
- *
- * Intended for **Next.js** (App Router and Pages Router) and any other React 18+
- * project where you manage the `ConsentiSetup` instance yourself and want the
- * `useConsent()` hook to re-render when consent or UI state changes.
- *
- * @example
- * ```tsx
- * // app/providers.tsx (Next.js App Router)
- * 'use client'
- * import { useEffect } from 'react'
- * import { ConsentiSetup } from '@consenti/ui'
- * import { setConsentiWidget } from '@consenti/ui/react'
- *
- * export function ConsentiProvider({ children }: { children: React.ReactNode }) {
- *   useEffect(() => {
- *     const widget = new ConsentiSetup({
- *       api: { enabled: true, baseUrl: process.env.NEXT_PUBLIC_API_URL },
- *     })
- *     setConsentiWidget(widget)
- *   }, [])
- *   return <>{children}</>
- * }
- *
- * // Any component
- * import { useConsent } from '@consenti/ui/react'
- *
- * function CookieStatus() {
- *   const { hasConsent, consent, showModal } = useConsent()
- *   if (!hasConsent) return <button onClick={showModal}>Manage Cookies</button>
- *   return <span>{consent?.analytics === 'granted' ? 'Analytics on' : 'Analytics off'}</span>
- * }
- * ```
- */
-
 /**
  * Registers the active `ConsentiSetup` instance so `useConsent()` can read from it.
  * Call this once after creating your widget, typically inside a `useEffect`.
@@ -635,22 +796,38 @@ declare function setConsentiWidget(widget: ConsentiSetup): void;
  * @returns Consent state values and widget action functions.
  */
 declare function useConsent(): {
+    /** `true` if the visitor has saved a valid consent record. */
     hasConsent: boolean;
+    /** The stored consent map (`Record<cookieId, status>`), or `null` before first submission. */
     consent: ConsentValue | null;
-    consentDate: Date | false;
-    bannerVisible: "main" | "gpc" | false;
-    modalVisible: "preference" | false;
-    showBanner: (_gpc?: boolean) => void;
-    hideBanner: () => void;
-    showModal: () => void;
-    hideModal: () => void;
-    grantAll: (_onlyMandatory?: boolean) => Promise<void>;
-    denyAll: (_includingMandatory?: boolean) => Promise<void>;
-    submitConsent: (_c: Partial<ConsentValue>) => Promise<void>;
+    /** `Date` of the last consent submission, or `false` if no consent exists. */
+    consentDate: false | Date;
+    /** Current banner state: `'main'`, `'gpc'`, or `false` (hidden). */
+    bannerVisible: false | "main" | "gpc";
+    /** Current modal state: `'preference'` or `false` (hidden). */
+    modalVisible: false | "preference";
+    /** Shows the consent banner. Pass `true` to force the GPC variant. */
+    showBanner: (gpc?: boolean) => void | undefined;
+    /** Hides the consent banner. */
+    hideBanner: () => void | undefined;
+    /** Opens the preference modal. */
+    showModal: () => void | undefined;
+    /** Closes the preference modal. */
+    hideModal: () => void | undefined;
+    /** Grants all non-mandatory cookies. Pass `true` to grant only mandatory ones and deny the rest. */
+    grantAll: (onlyMandatory?: boolean) => Promise<void>;
+    /** Denies all non-mandatory cookies. Pass `true` to deny mandatory ones too (use with care). */
+    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>;
-    isCookieGranted: (_id: string) => boolean;
-    isCategoryGranted: (_id: string) => boolean;
-    switchLocale: (_locale: string) => 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;
 };
 
 export { setConsentiWidget, useConsent };