@consenti/ui 0.1.0 → 0.3.0

package/dist/react.d.ts

@@ -1,15 +1,115 @@
+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]> | 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
+ * that lives in @consenti/utils (packages/utils/src/compliance.ts).
+ *
+ * This import is type-only and fully erased at compile time — @consenti/types
+ * has no runtime dependency on @consenti/utils. The actual data (COMPLIANCE_GROUPS,
+ * EMBEDDED_COMPLIANCE_MAP, COMPLIANCE_VALIDATION_RULES, GPC_OPTIONS, etc.) lives in
+ * @consenti/utils; import it from there.
+ *
+ * HOW TO ADD A NEW REGULATION OR COMPLIANCE GROUP: see the header comment in
+ * packages/utils/src/compliance.ts — these types auto-update from that data.
+ */
+
+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;
+    countries: Record<string, CountryComplianceEntry>;
+}
+interface CountryComplianceEntry {
+    complianceGroup: ComplianceGroupId;
+    default: ComplianceGroupId;
+    description: string;
+    overriddenRegions?: Record<string, {
+        complianceGroup: ComplianceGroupId;
+        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;
-    type?: 'consent' | 'legitimate_interest';
-    mandatory?: boolean;
+    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 {
@@ -19,6 +119,10 @@ interface Button {
     cookies?: string[] | '*' | '!';
     url?: 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;
@@ -27,34 +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[];
 }
-interface PreferenceModal {
+/** `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';
-    overlayOpacity?: number;
-    showClose?: boolean;
-    showLocaleSwitcher?: boolean;
-    heading?: string;
-    headingTag?: string;
     subheading?: string;
-    htmlText?: string;
-    buttons: Button[];
-    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;
@@ -62,17 +177,55 @@ interface DpdpaConfig {
     purposeDescription?: string;
 }
 interface ResolvedProfile {
-    id: number;
-    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?: 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;
+    region: string | null;
+    confidence: number;
+}>;
+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. */
+interface TcfWidgetConfig {
+    enabled: boolean;
+    cmpId: number;
+    cmpVersion: number;
+}
+interface ComplianceWidgetConfig {
+    type?: ComplianceType;
+    geoDataProvider?: 'default' | WidgetCountryResolverFn;
+    autoComplianceMap?: 'default' | ComplianceMapData | 'auto';
+    complianceMapUrl?: string;
+    ageGate?: AgeGateWidgetConfig;
+    tcf?: TcfWidgetConfig;
 }
 interface GtmConfig {
     containerId?: string;
@@ -80,6 +233,7 @@ interface GtmConfig {
     dataLayer?: string;
     urlPassthrough?: boolean;
     adsDataRedaction?: boolean;
+    verbose?: boolean;
 }
 interface UtilsConfig {
     gtm?: GtmConfig;
@@ -88,6 +242,9 @@ interface ApiConfig {
     enabled?: boolean;
     baseUrl?: string;
     authToken?: string;
+    tenantId?: string;
+    complianceGroup?: ComplianceGroupId;
+    trustDomain?: boolean;
 }
 interface ThemeConfig {
     bgColor?: string;
@@ -109,35 +266,60 @@ interface ThemeConfig {
     accentTextColor?: string;
 }
 interface CoreConfig {
-    profileId?: number;
-    autoHonorGPC?: boolean | 'strict';
+    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. */
+    dir?: 'ltr' | 'rtl' | 'auto';
     disableCssTemplate?: boolean;
-    signCookies?: boolean;
     cookieSigningKey?: string;
     allowReceipt?: boolean;
     cookieDomains?: string;
     storage?: 'cookie' | 'localStorage';
     theme?: ThemeConfig;
-    privacyPolicyUrl?: string;
-    regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
     userId?: string;
+    usePrebuiltProfiles?: 'all' | NonEmptyArray<ComplianceGroupId>;
+    cacheResolvedProfiles?: boolean;
+    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;
     autoInit?: boolean;
     api?: ApiConfig;
     utils?: UtilsConfig;
     plugins?: ConsentiPlugin[];
-    profileOverride?: Partial<ResolvedProfile>;
+    profileOverride?: 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';
 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;
+    isCategoryGranted(categoryId: string, requestValue?: boolean): boolean | {
+        [cookieId: string]: ConsentStatus;
+    }[];
+    grantAll(onlyMandatory?: boolean): Promise<void>;
+    denyAll(includingMandatory?: boolean): Promise<void>;
+    on(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    off(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    version(): {
+        package: string;
+        profileVersion: string | null;
+        consentVersion: string | null;
+    };
     bannerVisibility(): 'main' | 'gpc' | false;
     modalVisibility(): 'preference' | false;
     getProfile(): ResolvedProfile | null;
@@ -145,13 +327,17 @@ 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;
     getBannerElement(): HTMLElement | null;
     getModalElement(): HTMLElement | null;
     switchLocale(locale: string): void;
+    setDarkMode(enable?: boolean): void;
+    setTheme(theme: Partial<ThemeConfig>): void;
+    setConfig(config: DeepPartial<ConsentiConfig>): void;
+    setProfile(override: DeepPartial<ResolvedProfile>): void;
     init(): Promise<void>;
     onReady(callback: () => void): void;
     destroy(): void;
@@ -165,6 +351,47 @@ declare abstract class ConsentiPlugin {
     onModalShow?(): void | Promise<void>;
     onModalHide?(): void | Promise<void>;
 }
+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;
+}
+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.
@@ -176,7 +403,7 @@ declare abstract class ConsentiPlugin {
  * @example
  * ```ts
  * const widget = new ConsentiSetup({
- *   core: { profileId: 0 },
+ *   compliance: { type: 'opt-in' },
  * })
  * await widget.ready
  * console.log(widget.hasConsent())
@@ -184,15 +411,30 @@ declare abstract class ConsentiPlugin {
  */
 
 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;
@@ -201,13 +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;
@@ -217,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.
@@ -233,6 +530,8 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * @param invoke - Function that calls the desired hook method on a single plugin.
      */
     private callPluginHook;
+    private _buildGrantAllConsent;
+    private _buildDenyAllConsent;
     private buildHandlers;
     /**
      * Classifies a consent submission as `accept_all`, `reject_all`, `custom`, or `update`.
@@ -246,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;
     /**
@@ -273,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`.
@@ -381,6 +681,93 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * @param locale - BCP 47 locale code to switch to (e.g. `'fr'`, `'de-AT'`).
      */
     switchLocale(locale: string): void;
+    /**
+     * Returns `true` if the named cookie's consent is `'granted'`.
+     * When `requestValue` is `true`, returns the raw `ConsentStatus` string instead of a boolean,
+     * or `false` if the cookie is not in the consent map.
+     */
+    isCookieGranted(cookieId: string, requestValue?: boolean): boolean | 'granted' | 'denied' | 'objected';
+    /**
+     * Checks consent for all cookies belonging to the given category.
+     *
+     * With `requestValue = false` (default): returns `true` only when every cookie in the
+     * category is `'granted'`, `false` otherwise.
+     *
+     * With `requestValue = true`: returns an array of one-key records — one per cookie in the
+     * category — e.g. `[{ analytics: 'granted' }, { pixel: 'denied' }]`.
+     *
+     * Returns `false` / `[]` if the category is not found or the widget is not yet initialized.
+     */
+    isCategoryGranted(categoryId: string, requestValue?: boolean): boolean | {
+        [cookieId: string]: 'granted' | 'denied' | 'objected';
+    }[];
+    /**
+     * Programmatically accepts cookies and hides the banner.
+     *
+     * @param onlyMandatory - When `true`, only mandatory cookies are granted and all others
+     *                        are set to `'denied'`. Defaults to `false` (grant everything).
+     */
+    grantAll(onlyMandatory?: boolean): Promise<void>;
+    /**
+     * Programmatically denies cookies and hides the banner.
+     *
+     * @param includingMandatory - When `true`, mandatory cookies are also denied. Defaults to
+     *                             `false` (mandatory cookies remain `'granted'`). Passing `true`
+     *                             logs a warning — ensure this is intentional.
+     */
+    denyAll(includingMandatory?: boolean): Promise<void>;
+    /**
+     * Subscribes to a Consenti widget event. The `consenti:` prefix is optional —
+     * both `'consentSubmitted'` and `'consenti:consentSubmitted'` are accepted.
+     *
+     * The same handler reference must be passed to `off()` to unsubscribe.
+     *
+     * @example
+     * ```ts
+     * const handler = (data) => console.log(data)
+     * widget.on('consentSubmitted', handler)
+     * // later:
+     * widget.off('consentSubmitted', handler)
+     * ```
+     */
+    on(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    /**
+     * Removes a previously registered event handler. The same function reference passed to
+     * `on()` must be used here.
+     */
+    off(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
+    /**
+     * Returns the current version of the package and the active profile/consent versions.
+     * Useful for debugging and support diagnostics.
+     */
+    version(): {
+        package: string;
+        profileVersion: string;
+        consentVersion: string | null;
+    };
+    /**
+     * Toggles or sets dark mode at runtime without re-initialising the widget.
+     * When `enable` is omitted, the current dark mode state is toggled.
+     */
+    setDarkMode(enable?: boolean): void;
+    /**
+     * Applies partial theme token overrides at runtime, merging them into the current theme.
+     * CSS custom properties on the root element are updated immediately.
+     */
+    setTheme(theme: Partial<ThemeConfig>): void;
+    /**
+     * Deep-merges a partial config into the current widget config.
+     * Theme and dark mode side-effects are re-applied immediately.
+     * Changes to locale or profile require an explicit `switchLocale()` or `init()` call.
+     */
+    setConfig(config: DeepPartial<ConsentiConfig>): void;
+    /**
+     * Merges a partial profile override into the current profile and re-renders any visible UI.
+     * Does not make a network request — the resolved base profile from the last `init()` is reused.
+     *
+     * No-op before `init()` completes (while `resolvedBase` is null).
+     */
+    setProfile(override: DeepPartial<ResolvedProfile>): void;
     /**
      * Destroys the widget — removes all DOM elements, disconnects the BroadcastChannel,
      * and calls `destroy()` on all registered plugins.
@@ -390,43 +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 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({ core: { profileId: 0 } })
- *     setConsentiWidget(widget)
- *   }, [])
- *   return <>{children}</>
- * }
- *
- * // Any component
- * import { useConsent } from '@consenti/ui/react'
- *
- * function CookieBanner() {
- *   const { hasConsent, submitConsent } = useConsent()
- *   if (hasConsent()) return null
- *   return <button onClick={() => submitConsent({ analytics: 'granted' })}>Accept</button>
- * }
- * ```
- */
-
 /**
  * Registers the active `ConsentiSetup` instance so `useConsent()` can read from it.
  * Call this once after creating your widget, typically inside a `useEffect`.
@@ -435,18 +785,49 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
  */
 declare function setConsentiWidget(widget: ConsentiSetup): void;
 /**
- * React hook that exposes consent state and lets components react to consent changes.
+ * React hook that exposes consent state, banner/modal visibility, and widget actions.
+ *
+ * Subscribes to `consenti:consentSubmitted`, `consenti:bannerVisibility`, and
+ * `consenti:modalVisibility` on `window` and triggers re-renders on each event.
+ * Returns SSR-safe initial values during server render.
  *
- * Subscribes to `consenti:consentSubmitted` on `window` and triggers a re-render
- * each time consent is updated. Returns SSR-safe fallback values during server render.
+ * Destructure only what you need — unused values do not cause extra renders.
  *
- * @returns An object with `hasConsent`, `getConsent`, `submitConsent`, and `getConsentDate`.
+ * @returns Consent state values and widget action functions.
  */
 declare function useConsent(): {
-    hasConsent: () => boolean;
-    getConsent: () => ConsentValue | null;
-    submitConsent: (_consent: Partial<ConsentValue>) => Promise<void>;
-    getConsentDate: () => Date | false;
+    /** `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;
+    /** `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>;
+    /** 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 };