@cookieyes/core 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -19,8 +19,82 @@ type ConsentChecker = (category: ConsentCategory) => boolean;
 declare function installNetworkBlocker(config: NetworkBlockerConfig, hasConsent: ConsentChecker): () => void;
 declare function uninstallNetworkBlocker(): void;
 
-type ConsentCategory = "necessary" | "functional" | "analytics" | "performance" | "advertisement";
+/**
+ * A tool that can be stopped (and optionally resumed) at runtime when consent
+ * for its category changes — no page reload needed. `stop()` is called when the
+ * category is revoked; `resume()` (if provided) when it's re-granted.
+ *
+ * If `stop()` throws, that tool is treated as "couldn't be stopped cleanly" and
+ * falls back to the reload notice for that one tool — it never breaks the page.
+ */
+type StopHandler = {
+    id: string;
+    category: ConsentCategory;
+    stop: () => void;
+    resume?: (() => void) | undefined;
+};
+/**
+ * A tool with no known clean runtime stop — revoking its category can only be
+ * fully applied by reloading the page. Registering one means "if this category
+ * is revoked, show the visitor the reload notice."
+ */
+type ReloadOnlyHandler = {
+    id: string;
+    category: ConsentCategory;
+    needsReload: true;
+};
+type AnyStopHandler = StopHandler | ReloadOnlyHandler;
+/**
+ * Built-in, first-party integrations. Each maps to either a clean stop-handler
+ * or a reload-only marker (see the audit in the README).
+ *
+ * Note: Google Analytics 4 and Google Tag Manager are **not** listed here.
+ * They're governed by Google Consent Mode v2, which the SDK broadcasts
+ * automatically whenever a `dataLayer` is present (see google-consent-mode.ts)
+ * — on load and on every consent change, derived from each category's `gcm`
+ * mapping. So you don't register them as integrations; just add the standard
+ * Consent Mode default snippet and the SDK owns the updates.
+ *
+ * VERIFIED clean-stop vendors (documented, stable runtime opt-out):
+ * - `meta`  — `fbq('consent','revoke'|'grant')`, Meta's official consent API.
+ *
+ * The rest have no confident, documented runtime stop, so they're modelled as
+ * reload-only (Story 1's honest answer). Upgrading any of them to a clean-stop
+ * later is a one-line change here once a real API is confirmed.
+ */
+type BuiltInIntegration = {
+    vendor: "meta";
+    category?: ConsentCategory | undefined;
+} | {
+    vendor: "tiktok";
+    category?: ConsentCategory | undefined;
+} | {
+    vendor: "linkedin";
+    category?: ConsentCategory | undefined;
+} | {
+    vendor: "hotjar";
+    category?: ConsentCategory | undefined;
+} | {
+    vendor: "segment";
+    category?: ConsentCategory | undefined;
+};
+declare function resolveBuiltInIntegration(cfg: BuiltInIntegration): AnyStopHandler;
+declare function registerStopHandler(handler: AnyStopHandler): void;
+/** Test-only: reset registry + transition state between cases. */
+declare function _clearStopHandlers(): void;
+
+/**
+ * A consent category id. The five built-in ids are offered for autocomplete,
+ * but any string is valid — customers can define their own taxonomy via
+ * `categories` (see {@link CategoryDef}).
+ */
+type ConsentCategory = "necessary" | "functional" | "analytics" | "performance" | "advertisement" | (string & {});
 type Regulation = "GDPR" | "CCPA" | "DEFAULT";
+/** Display text for one consent category. */
+type CategoryText = {
+    label: string;
+    description: string;
+};
 type TranslationMap = {
     bannerTitle: string;
     bannerDescription: string;
@@ -35,27 +109,12 @@ type TranslationMap = {
     preferencesTitle: string;
     preferencesIntro: string;
     categories: {
-        necessary: {
-            label: string;
-            description: string;
-        };
-        functional: {
-            label: string;
-            description: string;
-        };
-        analytics: {
-            label: string;
-            description: string;
-        };
-        performance: {
-            label: string;
-            description: string;
-        };
-        advertisement: {
-            label: string;
-            description: string;
-        };
-    };
+        necessary: CategoryText;
+        functional: CategoryText;
+        analytics: CategoryText;
+        performance: CategoryText;
+        advertisement: CategoryText;
+    } & Record<string, CategoryText>;
     optOut: {
         title: string;
         description: string;
@@ -63,6 +122,24 @@ type TranslationMap = {
         successText: string;
         successCountdown: string;
     };
+    reloadNotice: {
+        message: string;
+        reloadButton: string;
+        dismissButton: string;
+    };
+};
+/** A subset of TranslationMap — lets a customer override just a few strings. */
+type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+type PartialTranslations = DeepPartial<TranslationMap>;
+/** Reading direction of a language. */
+type TextDirection = "ltr" | "rtl";
+/** The active language, its reading direction, and the languages currently loaded. */
+type LanguageInfo = {
+    language: string;
+    direction: TextDirection;
+    languages: string[];
 };
 type ThemeConfig = {
     primaryColor?: string | undefined;
@@ -83,29 +160,79 @@ type ScriptEntry = {
     onLoad?: (() => void) | undefined;
 };
 type I18nConfig = {
-    messages?: Record<string, TranslationMap> | undefined;
+    /** Translations per language. Each may be partial — missing text falls back to English. */
+    messages?: Record<string, PartialTranslations> | undefined;
     locale?: string | undefined;
     detectBrowserLanguage?: boolean | undefined;
+    /**
+     * Called when a language is switched to that isn't already in `messages` —
+     * return its translations (fetch them from your own URL, import them, etc.).
+     * Lets you load languages on demand instead of bundling them all upfront.
+     */
+    loadLanguage?: ((tag: string) => PartialTranslations | Promise<PartialTranslations>) | undefined;
 };
 type ConsentConfig = {
     apiUrl?: string | undefined;
     apiKey?: string | undefined;
     backend?: ConsentBackend | undefined;
     regulation?: Regulation | undefined;
+    /**
+     * Define your own category taxonomy. Omit to get the built-in five
+     * (necessary, functional, analytics, performance, advertisement) unchanged.
+     * At least one category must be `{ required: true }`. Invalid configs fall
+     * back to the built-in five with a console warning. See {@link CategoryDef}.
+     */
+    categories?: CategoryDef[] | undefined;
     theme?: ThemeConfig | undefined;
-    colorScheme?: "light" | "dark" | "system" | undefined;
+    colorScheme?: ColorScheme | undefined;
     reloadOnRevoke?: boolean | undefined;
+    /**
+     * Built-in, first-party integrations to stop cleanly (no reload) when their
+     * category is revoked — e.g. `{ vendor: "meta" }`. (Google Analytics/Tag
+     * Manager are handled automatically via the Consent Mode broadcast — no entry
+     * needed.) Integrations with no clean runtime stop fall back to the reload notice.
+     */
+    integrations?: BuiltInIntegration[] | undefined;
+    /**
+     * Your own scripts' stop instructions, for anything without a built-in
+     * integration. A handler that can stop cleanly provides `stop()`; one that
+     * can't should be registered as a reload-only handler instead so revoking it
+     * shows the reload notice rather than silently continuing to track.
+     */
+    customStopHandlers?: StopHandler[] | undefined;
     onConsentReady?: ((state: ConsentSnapshot) => void) | undefined;
     onConsentUpdate?: ((state: ConsentSnapshot) => void) | undefined;
 };
+/**
+ * Surfaced when a revoked tool has no clean runtime stop and can only be fully
+ * applied by reloading. `required` is false once dismissed; `reasons` lists the
+ * handler ids that triggered it (e.g. `["hotjar"]`).
+ */
+type ReloadNoticeState = {
+    required: boolean;
+    reasons: string[];
+};
 type ConsentSnapshot = {
     consentId: string;
     hasActed: boolean;
-    categories: Record<ConsentCategory, boolean>;
+    /** Category id → granted. Keys are the configured taxonomy's ids. */
+    categories: Record<string, boolean>;
     regulation: Regulation;
     lastRenewed?: number | undefined;
+    /**
+     * Signature of the category taxonomy in effect when this consent was
+     * recorded. Lets us (and the customer) tell what a returning visitor
+     * actually agreed to, and drives re-request when the taxonomy changes.
+     */
+    taxonomyHash?: string | undefined;
 };
 type ConsentManager = ConsentSnapshot & {
+    /**
+     * Consent in effect — changes only on a real decision (accept / reject / save
+     * / reset), never on a dialog toggle. Gate scripts/embeds on this. (`categories`
+     * is the live value that drives the dialog checkboxes.)
+     */
+    committedCategories: Record<string, boolean>;
     acceptAll: () => void;
     rejectAll: () => void;
     acceptSelected: (categories: ConsentCategory[]) => void;
@@ -117,9 +244,13 @@ type ConsentManager = ConsentSnapshot & {
     isPreferencesOpen: boolean;
     subscribe: (listener: (state: ConsentSnapshot) => void) => () => void;
     registerScript: (entry: ScriptEntry) => void;
+    /** Current reload-notice state (see {@link ReloadNoticeState}). */
+    reloadNotice: ReloadNoticeState;
+    /** Dismiss the reload notice; it won't reappear until a new revoke needs one. */
+    dismissReloadNotice: () => void;
 };
 /**
- * Shape of the JSON body POSTed to the customer's `backendURL`
+ * Shape of the JSON body POSTed to the customer's `apiUrl`
  * on every consent decision (Accept All / Reject All / Save Preferences).
  *
  * Customers building a TypeScript backend can import this type to get
@@ -127,7 +258,7 @@ type ConsentManager = ConsentSnapshot & {
  */
 type ConsentPayload = {
     consentId: string;
-    categories: Record<ConsentCategory, boolean>;
+    categories: Record<string, boolean>;
     regulation: Regulation;
     domain: string;
 };
@@ -135,7 +266,7 @@ type ConsentPayload = {
  * Customer-implemented adapter that decides how a consent decision
  * reaches their backend. Provide this when `mode: "self-hosted"` and you
  * need full control over the request shape, headers, auth, transport,
- * batching, retries, etc. — anything you can't express with `backendURL`.
+ * batching, retries, etc. — anything you can't express with `apiUrl`.
  *
  * The SDK hands you a standardised `ConsentPayload`; you transform and
  * dispatch it however your backend expects.
@@ -143,69 +274,396 @@ type ConsentPayload = {
 interface ConsentBackend {
     persist(payload: ConsentPayload): Promise<void> | void;
 }
-type ConsentRuntimeMode = "self-hosted" | "offline";
-type ConsentRuntimeOptions = {
-    mode: ConsentRuntimeMode;
-    backendURL?: string | undefined;
-    apiKey?: string | undefined;
-    backend?: ConsentBackend | undefined;
-    consentCategories?: ConsentCategory[] | undefined;
-    overrides?: {
-        regulation?: Regulation | undefined;
-    } | undefined;
-    i18n?: I18nConfig | undefined;
-    colorScheme?: "light" | "dark" | "system" | undefined;
+/**
+ * @deprecated Use `"cookie-only"` instead — identical behavior, clearer name.
+ * `"offline"` still works but will be removed in a future release.
+ */
+type DeprecatedOfflineMode = "offline";
+type ConsentRuntimeMode = "self-hosted" | "cookie-only" | DeprecatedOfflineMode;
+type ColorScheme = "light" | "dark" | "system";
+/**
+ * Fields shared by every {@link CookieYesConfig} regardless of `mode`.
+ * This is the one canonical config surface — both `@cookieyes/core` and
+ * `@cookieyes/react` consume the exact same object, so a config is
+ * copy-pasteable between them with zero edits.
+ */
+type CookieYesConfigCommon = {
+    /**
+     * Which privacy regulation applies. Top-level and identical across every
+     * package (replaces the builder's `.regulation()` and core's former
+     * nested `overrides.regulation`).
+     */
+    regulation?: Regulation | undefined;
+    colorScheme?: ColorScheme | undefined;
     theme?: ThemeConfig | undefined;
+    i18n?: I18nConfig | undefined;
+    consentCategories?: ConsentCategory[] | undefined;
+    /**
+     * Define your own category taxonomy. Omit to get the built-in five
+     * (necessary, functional, analytics, performance, advertisement) unchanged.
+     * At least one category must be `{ required: true }`. Invalid configs fall
+     * back to the built-in five with a console warning. See {@link CategoryDef}.
+     */
+    categories?: CategoryDef[] | undefined;
     networkBlocker?: NetworkBlockerConfig | undefined;
     reloadOnRevoke?: boolean | undefined;
+    /**
+     * Built-in, first-party integrations to stop cleanly (no reload) when their
+     * category is revoked — e.g. `{ vendor: "meta" }`. (Google Analytics/Tag
+     * Manager are handled automatically via the Consent Mode broadcast — no entry
+     * needed.) Integrations with no clean runtime stop fall back to the reload notice.
+     */
+    integrations?: BuiltInIntegration[] | undefined;
+    /**
+     * Your own scripts' stop instructions, for anything without a built-in
+     * integration. A handler that can stop cleanly provides `stop()`; one that
+     * can't should be registered as a reload-only handler instead so revoking it
+     * shows the reload notice rather than silently continuing to track.
+     */
+    customStopHandlers?: StopHandler[] | undefined;
+    /** Low-level: fires once, after the runtime's initial state is known (e.g. to conditionally load analytics on first load). For ongoing updates, use `consentStore.subscribeToConsentChanges` instead. */
     onConsentReady?: ((state: ConsentSnapshot) => void) | undefined;
+    /** Low-level: fires on every saved consent change, for the lifetime of this config. If you need to subscribe/unsubscribe dynamically after mount, use `consentStore.getState().subscribeToConsentChanges` instead. */
     onConsentUpdate?: ((state: ConsentSnapshot) => void) | undefined;
+    /**
+     * @deprecated Set `regulation` at the top level instead. This nested form
+     * still works and maps to the top-level field; if both are given, the
+     * top-level `regulation` wins. Retained for back-compat and removed after
+     * three release cycles, per the SDK deprecation policy.
+     */
+    overrides?: {
+        regulation?: Regulation | undefined;
+    } | undefined;
+};
+/**
+ * Cookie-only mode — consent is stored client-side only; no backend keys are
+ * permitted (they fail at the type level). `mode: "cookie-only"` is the
+ * canonical value; `mode: "offline"` is a deprecated alias with identical
+ * behavior that emits a one-time-per-page-load deprecation warning.
+ */
+type CookieYesOfflineConfig = CookieYesConfigCommon & {
+    mode: "cookie-only" | DeprecatedOfflineMode;
 };
+/** Self-hosted mode — consent decisions are persisted to your own backend. */
+type CookieYesSelfHostedConfig = CookieYesConfigCommon & {
+    mode: "self-hosted";
+    /** Endpoint the {@link ConsentPayload} is POSTed to. Canonical key. */
+    apiUrl?: string | undefined;
+    apiKey?: string | undefined;
+    /** Custom persistence adapter — full control over transport/headers/retries. */
+    backend?: ConsentBackend | undefined;
+    /**
+     * @deprecated Renamed to `apiUrl`. This alias still works and maps to
+     * `apiUrl`; if both are given, `apiUrl` wins. Retained for back-compat and
+     * removed after three release cycles, per the SDK deprecation policy.
+     */
+    backendURL?: string | undefined;
+};
+/**
+ * The canonical configuration object for the CookieYes SDK, discriminated on
+ * `mode`. Passed identically to `initCookieYes()` /
+ * `getOrCreateConsentRuntime()` in `@cookieyes/core` and `initCookieYes()` in
+ * `@cookieyes/react`.
+ *
+ * The discriminated union guarantees invalid combinations fail at compile time
+ * — e.g. supplying `apiUrl`/`backend` under `mode: "cookie-only"` is a type error.
+ */
+type CookieYesConfig = CookieYesOfflineConfig | CookieYesSelfHostedConfig;
+/**
+ * @deprecated Renamed to {@link CookieYesConfig}. Retained as a type alias for
+ * back-compat and removed after three release cycles, per the SDK deprecation
+ * policy.
+ */
+type ConsentRuntimeOptions = CookieYesConfig;
 type ConsentChangePayload = {
     allowedCategories: ConsentCategory[];
     deniedCategories: ConsentCategory[];
 };
+/** Which consent event to listen for. See {@link ConsentStore.on}. */
+type ConsentEventType = "save" | "change";
+type ConsentEventPayload = {
+    /** The full committed consent map in effect when the event fired. */
+    categories: Record<string, boolean>;
+    /** Categories whose value differed from before. Empty on the initial replay. */
+    changedCategories: ConsentCategory[];
+    /**
+     * `true` when this is the one-off replay a listener gets on attach (here's
+     * the current state), `false` when the visitor actually just acted.
+     */
+    isInitial: boolean;
+};
+type ConsentEventListener = (payload: ConsentEventPayload) => void;
+/** Restrict a listener to a single category (fires only when it changes). */
+type ConsentEventOptions = {
+    category?: ConsentCategory;
+};
 type ActiveUI = "banner" | "dialog" | null;
 type ConsentStoreState = ConsentSnapshot & {
     activeUI: ActiveUI;
-    consents: Record<ConsentCategory, boolean>;
+    /** Live/working values — reflect in-progress dialog toggles. Drive checkboxes. */
+    consents: Record<string, boolean>;
+    /**
+     * Consent in effect — changes only on a saved decision, not a toggle. Gate
+     * scripts/embeds on this (or {@link ConsentStoreState.has}).
+     */
+    committedConsents: Record<string, boolean>;
+    /** True when `category` is committed-granted (a saved decision), not just toggled. */
     has: (category: ConsentCategory) => boolean;
     saveConsents: (target: "all" | "necessary" | ConsentCategory[]) => Promise<void>;
     setConsent: (category: ConsentCategory, value: boolean) => void;
+    /** Low-level: fires only on *saved* preference changes, not transient UI toggles — see `ConsentStore.subscribe` for the recommended, general-purpose subscription. */
     subscribeToConsentChanges: (listener: (payload: ConsentChangePayload) => void) => () => void;
 };
+/**
+ * The recommended way to read consent state outside React. `subscribe` fires
+ * on every state change (including transient UI toggles, e.g. a checkbox
+ * flip before saving); for saved-changes-only, see
+ * `ConsentStoreState.subscribeToConsentChanges`.
+ */
 type ConsentStore = {
     subscribe: (listener: (state: ConsentStoreState) => void) => () => void;
     getState: () => ConsentStoreState;
+    /** Text for the active language (English fills gaps). Swaps on `setLanguage`. */
+    translations: TranslationMap;
+    /** The active language, its reading direction, and the languages loaded. */
+    getLanguageInfo: () => LanguageInfo;
+    /**
+     * Switch language live (no reload) — `subscribe` listeners fire so a custom UI
+     * can re-render. Loads the language via `i18n.loadLanguage` if not bundled.
+     */
+    setLanguage: (tag: string) => Promise<void>;
+    /** Customer-provided text for a category in the active language, if any. */
+    getCategoryText: (id: string) => Partial<CategoryText> | undefined;
+    /**
+     * The category taxonomy in effect (custom list or the built-in five) — its
+     * ids, which are `required`, etc. Use it to render categories in a custom UI
+     * so it follows whatever taxonomy is configured.
+     */
+    categories: ResolvedCategories;
+    /**
+     * React to consent decisions. `"save"` fires on every save (even an
+     * unchanged re-confirm); `"change"` fires only when a category actually
+     * differs — use it to (re)load a script without re-running on a re-confirm.
+     * The listener fires once immediately with the current state
+     * (`isInitial: true`). Pass `{ category }` to only hear about one category.
+     * Returns an unsubscribe function.
+     */
+    on: (type: ConsentEventType, listener: ConsentEventListener, options?: ConsentEventOptions) => () => void;
 };
 type ConsentRuntime = {
     consentManager: ConsentManager;
     consentStore: ConsentStore;
 };
 
+/**
+ * Google Consent Mode v2 storage/signal types. A category can declare which of
+ * these it represents via {@link CategoryDef.gcm}; the SDK then broadcasts them
+ * (see google-consent-mode.ts). `security_storage` is always granted and is
+ * handled by the broadcast itself, so it never needs to be mapped.
+ */
+type GoogleConsentSignal = "ad_storage" | "ad_user_data" | "ad_personalization" | "analytics_storage" | "functionality_storage" | "personalization_storage" | "security_storage";
+/**
+ * A single consent category. `id` is the stable key stored in the cookie and
+ * used everywhere (banner, preferences, read APIs, integrations). Exactly one
+ * category should be marked `required` — the always-on, non-optional one (like
+ * the default "necessary") — flagged explicitly here, never inferred from a
+ * name, so it survives full renaming.
+ */
+type CategoryDef = {
+    id: ConsentCategory;
+    /** The always-on, non-optional category. At least one is required. */
+    required?: boolean | undefined;
+    /** Display label. Falls back to the translation for built-in ids. */
+    label?: string | undefined;
+    /** Display description. Falls back to the translation for built-in ids. */
+    description?: string | undefined;
+    /** Google Consent Mode signals this category governs (see {@link GoogleConsentSignal}). */
+    gcm?: GoogleConsentSignal[] | undefined;
+};
+/**
+ * The built-in five, used verbatim when a customer configures nothing. GCM
+ * mapping mirrors production's `_ckySetGoogleConsentMode` (analytics →
+ * analytics_storage, advertisement → the ad_* signals, functional →
+ * functionality/personalization; performance maps to nothing; security_storage
+ * is always granted by the broadcast).
+ */
+declare const DEFAULT_CATEGORIES: CategoryDef[];
+type ResolvedCategories = {
+    /** Ordered category definitions actually in effect. */
+    list: CategoryDef[];
+    /** Ordered ids (fast access). */
+    ids: ConsentCategory[];
+    /** Ids marked `required` (always granted, never toggleable). */
+    requiredIds: Set<ConsentCategory>;
+    /** Stable signature of this taxonomy; a change here re-requests consent. */
+    taxonomyHash: string;
+    /** True when the built-in five are in effect (configured or fallback). */
+    isDefault: boolean;
+};
+/**
+ * Resolve the category list from config. Returns the built-in five when nothing
+ * is configured. On an invalid custom config (empty, duplicate/reserved ids, or
+ * no `required` category) it warns and falls back to the built-in five, rather
+ * than leaving the visitor a broken/empty or unprotected setup.
+ */
+declare function resolveCategories(defs?: CategoryDef[]): ResolvedCategories;
+
+/**
+ * The canonical config with every deprecated alias already collapsed into its
+ * top-level key. Both `@cookieyes/core` and `@cookieyes/react` consume the
+ * output of {@link _normalizeConfig}, so alias resolution lives in exactly one
+ * place and the two packages can never drift.
+ *
+ * @internal
+ */
+type _NormalizedConfig = {
+    mode: ConsentRuntimeMode;
+    regulation?: Regulation | undefined;
+    colorScheme?: ColorScheme | undefined;
+    theme?: ThemeConfig | undefined;
+    i18n?: I18nConfig | undefined;
+    consentCategories?: ConsentCategory[] | undefined;
+    categories?: CategoryDef[] | undefined;
+    networkBlocker?: NetworkBlockerConfig | undefined;
+    reloadOnRevoke?: boolean | undefined;
+    integrations?: BuiltInIntegration[] | undefined;
+    customStopHandlers?: StopHandler[] | undefined;
+    onConsentReady?: ((state: ConsentSnapshot) => void) | undefined;
+    onConsentUpdate?: ((state: ConsentSnapshot) => void) | undefined;
+    apiUrl?: string | undefined;
+    apiKey?: string | undefined;
+    backend?: ConsentBackend | undefined;
+};
+/**
+ * Resolve a public {@link CookieYesConfig} into its canonical internal form.
+ *
+ * Deprecated aliases map silently to their canonical key when used alone; when
+ * an alias and its canonical key are both present, the canonical key wins and
+ * exactly one warning is logged for that collision.
+ *
+ * - `overrides.regulation` → `regulation`
+ * - `backendURL` → `apiUrl`
+ *
+ * @internal
+ */
+declare function _normalizeConfig(config: CookieYesConfig): _NormalizedConfig;
+
 type RawCookieFields = {
     consentid?: string;
     consent?: string;
     action?: string;
-    necessary?: string;
-    functional?: string;
-    analytics?: string;
-    performance?: string;
-    advertisement?: string;
+    /** Taxonomy signature stored with the consent (see ResolvedCategories.taxonomyHash). */
+    tax?: string;
     lastRenewedDate?: string;
+    /** Every non-meta pair: category id → "yes" | "no". */
+    categories: Record<string, string>;
 };
 declare function parseCookie(raw: string): RawCookieFields;
 declare function serializeCookie(snapshot: ConsentSnapshot): string;
 declare function generateConsentId(): string;
 
+/**
+ * One-time-per-page-load console warning for `mode: "offline"`.
+ * Both @cookieyes/core and @cookieyes/react call this so the wording and the
+ * "once" behavior stay identical no matter which package reads the setting.
+ */
+declare function _warnOfflineModeDeprecated(): void;
+/** @internal test-only — resets the one-time warning guard between test cases. */
+declare function _resetOfflineModeWarning(): void;
+
+type ConsentEmitter = {
+    /**
+     * Listen for consent events. `"save"` fires on every saved decision (even an
+     * unchanged re-confirm); `"change"` fires only when a category actually
+     * differs. The listener fires once immediately with the current state
+     * (`isInitial: true`) so a late listener isn't blind to earlier choices.
+     * Pass `{ category }` to only be called when that one category changes.
+     * Returns an unsubscribe function.
+     */
+    on: (type: ConsentEventType, listener: ConsentEventListener, options?: ConsentEventOptions) => () => void;
+    /** Feed in the committed categories after a save; the emitter fans out events. */
+    push: (categories: Record<string, boolean>) => void;
+};
+/**
+ * The consent event fan-out, shared by the core and React runtimes so both
+ * behave identically. `getCommitted` returns the consent currently in effect,
+ * used for the immediate replay a new listener receives.
+ */
+declare function createConsentEmitter(getCommitted: () => Record<string, boolean>): ConsentEmitter;
+
+type GcmValue = "granted" | "denied";
+/**
+ * Compute the granted/denied value for every GCM signal from the current
+ * category consent, using each category's `gcm` mapping.
+ *
+ * - A signal is `granted` if *any* granted category maps to it.
+ * - `security_storage` is always `granted` (it's strictly necessary and not
+ *   consentable — this mirrors production's behaviour).
+ * - A signal that no category maps to defaults to `denied`.
+ */
+declare function computeGoogleConsent(resolved: ResolvedCategories, categories: Record<string, boolean>): Record<GoogleConsentSignal, GcmValue>;
+/**
+ * Push a Consent Mode `update` for all seven signals onto the dataLayer, if one
+ * is present. Safe to call on load and on every consent change; a no-op when no
+ * Google service is on the page.
+ *
+ * The customer is responsible for the Consent Mode *default* (the gtag snippet
+ * that must run before their Google tags, typically denying everything). This
+ * function owns the *update* that reflects the visitor's actual choice.
+ */
+declare function broadcastGoogleConsent(resolved: ResolvedCategories, categories: Record<string, boolean>): void;
+
 declare const en: TranslationMap;
 
+/** The base subtag of a language tag, lowercased: "en-GB" → "en". */
+declare function primaryOf(tag: string): string;
+/** Reading direction for a language tag, e.g. "ar" or "ar-EG" → "rtl". */
+declare function getTextDirection(tag: string): TextDirection;
+/** Deep-merge a (possibly partial) override onto a complete base map. */
+declare function mergeTranslations(base: TranslationMap, override?: PartialTranslations): TranslationMap;
+/**
+ * The language to start in, resolved in order: explicit `locale`, then the
+ * browser's language, then English. Only returns one we actually have text for
+ * (others can be brought in later via `loadLanguage`).
+ */
+declare function pickLanguage(i18n?: I18nConfig): string;
+/** Full translations for the resolved starting language, English filling any gaps. */
 declare function resolveTranslations(i18n?: I18nConfig): TranslationMap;
 
+type LanguageController = {
+    /** Text for the active language (English fills any gaps). */
+    getTranslations: () => TranslationMap;
+    getLanguageInfo: () => LanguageInfo;
+    /** Switch language live; loads via `i18n.loadLanguage` if not already present. */
+    setLanguage: (tag: string) => Promise<void>;
+    /**
+     * The customer's own text for a category in the *active* language, if they
+     * provided it — kept separate from the English defaults so a translation can
+     * win over a category's config label without the English default masking it.
+     */
+    getCategoryText: (id: string) => Partial<CategoryText> | undefined;
+};
+/**
+ * Owns the active language: which one is showing, its (English-filled) text,
+ * and switching to another — loading it on demand when a loader is provided.
+ * `onChange` runs after every switch so the UI can re-render.
+ *
+ * Framework-agnostic: used by both the core and React runtimes, so they behave
+ * identically.
+ */
+declare function createLanguageController(i18n: I18nConfig | undefined, onChange: () => void): LanguageController;
+
 declare function createConsentManager(config: ConsentConfig): ConsentManager;
 
-declare function getOrCreateConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime;
+declare function getOrCreateConsentRuntime(config: CookieYesConfig): ConsentRuntime;
+/**
+ * Canonical setup entry point. Alias of {@link getOrCreateConsentRuntime} that
+ * accepts the same {@link CookieYesConfig} and returns the same process-wide
+ * singleton — provided so documentation can use one setup name (`initCookieYes`)
+ * across every package.
+ */
+declare function initCookieYes(config: CookieYesConfig): ConsentRuntime;
 declare function resetConsentRuntime(): void;
 
-export { createConsentManager, en as defaultTranslations, generateConsentId, getOrCreateConsentRuntime, installNetworkBlocker, parseCookie, resetConsentRuntime, resolveTranslations, serializeCookie, uninstallNetworkBlocker };
-export type { ActiveUI, BlockedRequestInfo, ConsentBackend, ConsentCategory, ConsentChangePayload, ConsentConfig, ConsentManager, ConsentPayload, ConsentRuntime, ConsentRuntimeMode, ConsentRuntimeOptions, ConsentSnapshot, ConsentStore, ConsentStoreState, I18nConfig, NetworkBlockerConfig, NetworkBlockerRule, Regulation, ScriptEntry, ThemeConfig, TranslationMap };
+export { DEFAULT_CATEGORIES, _clearStopHandlers, _normalizeConfig, _resetOfflineModeWarning, _warnOfflineModeDeprecated, broadcastGoogleConsent, computeGoogleConsent, createConsentEmitter, createConsentManager, createLanguageController, en as defaultTranslations, generateConsentId, getOrCreateConsentRuntime, getTextDirection, initCookieYes, installNetworkBlocker, mergeTranslations, parseCookie, pickLanguage, primaryOf, registerStopHandler, resetConsentRuntime, resolveBuiltInIntegration, resolveCategories, resolveTranslations, serializeCookie, uninstallNetworkBlocker };
+export type { ActiveUI, AnyStopHandler, BlockedRequestInfo, BuiltInIntegration, CategoryDef, CategoryText, ColorScheme, ConsentBackend, ConsentCategory, ConsentChangePayload, ConsentConfig, ConsentEmitter, ConsentEventListener, ConsentEventOptions, ConsentEventPayload, ConsentEventType, ConsentManager, ConsentPayload, ConsentRuntime, ConsentRuntimeMode, ConsentRuntimeOptions, ConsentSnapshot, ConsentStore, ConsentStoreState, CookieYesConfig, CookieYesOfflineConfig, CookieYesSelfHostedConfig, GoogleConsentSignal, I18nConfig, LanguageController, LanguageInfo, NetworkBlockerConfig, NetworkBlockerRule, PartialTranslations, Regulation, ReloadNoticeState, ReloadOnlyHandler, ResolvedCategories, ScriptEntry, StopHandler, TextDirection, ThemeConfig, TranslationMap, _NormalizedConfig };