npm - @cookieyes/core - Versions diffs - 0.5.0 → 0.7.0 - Mend

@cookieyes/core 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/dist/categories-DMBKo4Eb.d.ts +778 -0
package/dist/index.cjs +1 -1
package/dist/index.cjs.map +1 -1
package/dist/index.d.ts +60 -739
package/dist/index.js +1 -1
package/dist/index.js.map +1 -1
package/dist/integrations.cjs +2 -0
package/dist/integrations.cjs.map +1 -0
package/dist/integrations.d.ts +1 -0
package/dist/integrations.js +2 -0
package/dist/integrations.js.map +1 -0
package/dist/network-blocker--Z2J__Xr.cjs +2 -0
package/dist/network-blocker--Z2J__Xr.cjs.map +1 -0
package/dist/network-blocker-zdjGiuQN.js +2 -0
package/dist/network-blocker-zdjGiuQN.js.map +1 -0
package/dist/network-blocker.cjs +2 -0
package/dist/network-blocker.cjs.map +1 -0
package/dist/network-blocker.d.ts +1 -0
package/dist/network-blocker.js +2 -0
package/dist/network-blocker.js.map +1 -0
package/package.json +6 -1

package/dist/categories-DMBKo4Eb.d.ts ADDED Viewed

@@ -0,0 +1,778 @@
+/**
+ * The integration format — the shared contract between the consent engine and
+ * every vendor preset (Google, Segment, Meta, …). It carries no vendor
+ * knowledge; a preset in `@cookieyes/scripts` fills it in.
+ *
+ * Two plain axes describe every vendor:
+ * - `load`:     when the vendor starts — right away, or only after consent.
+ * - `onRevoke`: what happens when consent is withdrawn — one of three modes.
+ *
+ * `onRevoke` is declarative (readable without running `setup`, so a debug view
+ * or a version check can inspect it), and it's a discriminated union so the
+ * compiler forces the matching handler — you can't declare `"silence"` with no
+ * way to actually silence.
+ */
+type Cleanup = () => void;
+type SilenceControl = {
+    silence: () => void;
+    resume: () => void;
+};
+/** What a vendor's `setup` receives from the engine. */
+type SetupCtx = {
+    /** Is this integration's category currently committed-granted? */
+    granted: () => boolean;
+    /**
+     * Subscribe to committed-consent changes; returns an unsubscribe function.
+     * `keep` vendors (e.g. Google Consent Mode) use this to emit their own
+     * updates on every change. The engine also releases these automatically when
+     * the integration is torn down, so a vendor listener never outlives it.
+     */
+    onConsentChange: (fn: () => void) => () => void;
+    /** Resolved region/regulation — for a vendor's US-state privacy switch. */
+    region: RegionDecision;
+};
+type Base = {
+    id: string;
+    /**
+     * The consent category (or categories) that gate this integration. Pass an
+     * array to require more than one — combined with {@link Base.match}.
+     */
+    category: ConsentCategory | ConsentCategory[];
+    /**
+     * How to combine multiple categories: `"all"` (default) needs every one
+     * granted; `"any"` needs at least one. Ignored for a single category.
+     */
+    match?: "all" | "any";
+    /** Format version; an unknown version is refused (see {@link runIntegrations}). */
+    version: number;
+    /**
+     * When to start. Note: `setup` always runs on a microtask, so `immediately`
+     * is *very early* but not synchronous / same-tick. The truly-first-thing case
+     * (Consent Mode's deny-default before any tag fires) is the server `<head>`
+     * snippet's job, not the engine's.
+     */
+    load: "immediately" | "afterConsent";
+};
+type Integration = Base & ({
+    onRevoke: "keep";
+    setup: (ctx: SetupCtx) => void | Promise<void>;
+} | {
+    onRevoke: "remove";
+    setup: (ctx: SetupCtx) => Cleanup | Promise<Cleanup>;
+} | {
+    onRevoke: "silence";
+    setup: (ctx: SetupCtx) => SilenceControl | Promise<SilenceControl>;
+});
+/** The format version this engine understands. Bump on a breaking format change. */
+declare const INTEGRATION_FORMAT_VERSION = 1;
+/**
+ * Warn when a vendor is configured on both sides — a new `integrations` preset
+ * whose id matches a deprecated `builtInIntegrations` vendor. Both would run,
+ * which for a tracker means double-counted events (the DEVP-38 double-pixel).
+ * Preset ids are the vendor's canonical name (`"segment"`, `"meta"`, …), which
+ * is exactly the built-in vendor name, so the match is a plain id === vendor.
+ */
+declare function warnOverlappingVendors(integrationIds: string[], builtInVendors: string[]): void;
+/**
+ * Warn when an `afterConsent` integration is gated on a category that isn't in
+ * the configured taxonomy — otherwise it waits for consent that can never be
+ * granted and silently never loads. A common trap with a custom `categories`
+ * list plus a preset left on its default category (e.g. `segment()` → "analytics").
+ * `immediately` integrations aren't gated by category, so they're not checked.
+ */
+declare function warnUnknownCategories(integrations: Integration[], knownCategoryIds: string[]): void;
+/** Live status of one integration — read by the debug/self-check view. */
+type IntegrationStatus = "idle" | "loading" | "active" | "silenced" | "removed" | "error";
+/** What the engine needs from the consent runtime — framework-agnostic. */
+type IntegrationHost = {
+    /** Committed-granted state for a category (never the unsaved toggle). */
+    granted: (category: ConsentCategory) => boolean;
+    /** Subscribe to committed-consent changes; returns unsubscribe. */
+    subscribe: (fn: () => void) => () => void;
+    region: RegionDecision;
+};
+/** One row for a debug view: an integration's config plus its live status. */
+type IntegrationDebugInfo = {
+    id: string;
+    category: ConsentCategory | ConsentCategory[];
+    load: "immediately" | "afterConsent";
+    onRevoke: "keep" | "remove" | "silence";
+    status: IntegrationStatus;
+};
+type IntegrationRunner = {
+    /** Current status per integration id — the debug/self-check view reads this. */
+    status: () => Record<string, IntegrationStatus>;
+    /**
+     * Config + live status for every registered integration, in order — the data
+     * for a debug view (e.g. `console.table(runner.list())`).
+     */
+    list: () => IntegrationDebugInfo[];
+    /**
+     * Tear the runner down: stop reconciling, release every vendor's
+     * consent-change listener, and undo each loaded vendor — `remove` runs its
+     * cleanup, `silence` is silenced. `keep` vendors' scripts stay (that's the
+     * mode), but their listeners are still released. Safe to call more than once.
+     */
+    stop: () => void;
+};
+/**
+ * Run a set of integrations against the consent runtime. Reconciles each one on
+ * load and on every committed-consent change:
+ * - not loaded → load it (immediately, or once its category is granted)
+ * - `keep`     → nothing on revoke (the vendor manages its own update)
+ * - `remove`   → run cleanup on revoke; re-load on re-grant
+ * - `silence`  → call `silence()` on revoke; `resume()` on re-grant
+ *
+ * `setup` may be async and may fail; a failure marks the integration `error`
+ * and is retried on the next trigger (never loops on its own). Nothing here
+ * throws into the host.
+ */
+declare function runIntegrations(integrations: Integration[], host: IntegrationHost): IntegrationRunner;
+type NetworkBlockerRule = {
+    id: string;
+    domain: string;
+    pathIncludes?: string | undefined;
+    methods?: string[] | undefined;
+    category: ConsentCategory;
+};
+type BlockedRequestInfo = {
+    rule: NetworkBlockerRule;
+    url: string;
+    method: string;
+};
+type NetworkBlockerConfig = {
+    rules: NetworkBlockerRule[];
+    onRequestBlocked?: ((info: BlockedRequestInfo) => void) | undefined;
+    logBlockedRequests?: boolean | undefined;
+};
+type ConsentChecker = (category: ConsentCategory) => boolean;
+declare function installNetworkBlocker(config: NetworkBlockerConfig, hasConsent: ConsentChecker): () => void;
+declare function uninstallNetworkBlocker(): void;
+/**
+ * Register the network blocker so that a configured `networkBlocker` actually
+ * installs. Call it once, before your setup call:
+ *
+ * ```ts
+ * import { initCookieYes } from "@cookieyes/core";
+ * import { registerNetworkBlocker } from "@cookieyes/core/network-blocker";
+ *
+ * registerNetworkBlocker();
+ * initCookieYes({ mode: "cookie-only", networkBlocker: { rules: [...] } });
+ * ```
+ *
+ * This indirection is what keeps the blocker out of the download for everyone
+ * who does not use it. Because it is reached by an ordinary static import, the
+ * blocker is already loaded when setup runs and patches the browser's
+ * networking immediately — there is no window in which requests slip through,
+ * which is the flaw a dynamic import would have introduced. See
+ * `network-blocker-slot.ts` for the full reasoning.
+ *
+ * Idempotent: calling it more than once replaces the registration with the same
+ * installer and changes nothing.
+ */
+declare function registerNetworkBlocker(): void;
+/**
+ * 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;
+    acceptAll: string;
+    rejectAll: string;
+    managePreferences: string;
+    savePreferences: string;
+    doNotSell: string;
+    ccpaDescription: string;
+    accept: string;
+    poweredBy: string;
+    /** Appended to the branding link's accessible name; that link opens a new tab. */
+    opensInNewTab: string;
+    preferencesTitle: string;
+    preferencesIntro: string;
+    /** Shown in place of a toggle on a category marked `required: true`. */
+    alwaysActive: string;
+    /** Accessible name of the preferences dialog. */
+    preferencesDialogLabel: string;
+    /** Accessible name of the opt-out dialog. */
+    optOutDialogLabel: string;
+    /** Accessible name of the floating recall button. */
+    recallButtonLabel: string;
+    /** Accessible name of the banner's close button (rendered under CCPA only). */
+    bannerCloseLabel: string;
+    /** Accessible name of the preferences dialog's close button. */
+    preferencesCloseLabel: string;
+    /** Accessible name of the opt-out dialog's close button. */
+    optOutCloseLabel: string;
+    categories: {
+        necessary: CategoryText;
+        functional: CategoryText;
+        analytics: CategoryText;
+        performance: CategoryText;
+        advertisement: CategoryText;
+    } & Record<string, CategoryText>;
+    optOut: {
+        title: string;
+        description: string;
+        cancel: string;
+        successText: string;
+        successCountdown: string;
+    };
+    gatedFrame: {
+        /** Placeholder shown in place of blocked embedded content. `{category}` is substituted. */
+        placeholder: string;
+        /** Label of the placeholder's button, which opens the preferences dialog. */
+        action: 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[];
+};
+/** Returns the visitor's region synchronously, e.g. "DE" or "US-CA" (or undefined). */
+type RegionDetector = () => string | undefined;
+/** Optional geo-detection: pick the banner's regulation from the visitor's region. */
+type RegionConfig = {
+    /** Return the visitor's region synchronously — e.g. from a hosting header you read. */
+    detect?: RegionDetector | undefined;
+    /** Which regulation each region maps to (you own this). Matched most-specific first: "US-CA" then "US". */
+    map?: Record<string, Regulation> | undefined;
+    /** Honour the browser's GPC "do not sell/share" signal (a CCPA opt-out). Default `true`. */
+    honorGpc?: boolean | undefined;
+    /** Regulation to apply when the region is unknown or detection fails. Default `"GDPR"`. */
+    strictest?: Regulation | undefined;
+    /** Log the region decision to the console at setup (for local debugging). Default `false`. */
+    debug?: boolean | undefined;
+};
+/** How the active regulation was decided. */
+type RegionSource = "manual" | "detected" | "strictest";
+/** The outcome of geo-detection — the region seen and the regulation chosen. */
+type RegionDecision = {
+    region: string | undefined;
+    regulation: Regulation;
+    source: RegionSource;
+    confidence: "high" | "low";
+};
+type ThemeConfig = {
+    primaryColor?: string | undefined;
+    backgroundColor?: string | undefined;
+    textColor?: string | undefined;
+    mutedTextColor?: string | undefined;
+    borderColor?: string | undefined;
+    borderRadius?: string | undefined;
+    fontFamily?: string | undefined;
+    /**
+     * Focus-ring color for interactive elements. Falls back to
+     * `var(--cy-primary)` — the ring matches your brand color exactly like it
+     * did before this field existed.
+     */
+    focusColor?: string | undefined;
+    /**
+     * Background color of the floating recall widget (the small circular
+     * re-open button). Falls back to `"#0056a7"` in light mode. In dark mode,
+     * this value is still respected if you set it; only when you don't set it
+     * does a dark-mode default apply, the same way
+     * backgroundColor/textColor/mutedTextColor/borderColor already work.
+     */
+    widgetBackgroundColor?: string | undefined;
+};
+type ScriptEntry = {
+    id: string;
+    src: string;
+    category: ConsentCategory;
+    onLoad?: (() => void) | undefined;
+};
+type I18nConfig = {
+    /** 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?: ColorScheme | undefined;
+    reloadOnRevoke?: boolean | undefined;
+    /**
+     * How to combine multiple categories that map to the same Google Consent Mode
+     * signal: `"any"` (default) grants the signal if any maps-and-granted; `"all"`
+     * requires every mapping category. Only affects custom overlapping mappings.
+     */
+    googleConsentMatch?: "all" | "any" | 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;
+    /** Detected region (e.g. "US-CA"), recorded on the consent-log payload. */
+    region?: string | undefined;
+    /**
+     * Internal — set by the runtime when a CCPA visitor arrives with the browser's
+     * GPC "do not sell" signal on. Starts them opted out (non-required categories
+     * off) until they explicitly choose otherwise, so nothing is shared first.
+     */
+    gpcOptOut?: boolean | 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;
+    /** 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;
+    updateCategory: (category: ConsentCategory, value: boolean) => void;
+    savePreferences: () => void;
+    resetConsent: () => void;
+    showPreferences: () => void;
+    hidePreferences: () => void;
+    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 `apiUrl`
+ * on every consent decision (Accept All / Reject All / Save Preferences).
+ *
+ * Customers building a TypeScript backend can import this type to get
+ * full type safety on their request handler.
+ */
+type ConsentPayload = {
+    consentId: string;
+    categories: Record<string, boolean>;
+    regulation: Regulation;
+    domain: string;
+    /** Detected region when geo-detection is on (e.g. "US-CA"); omitted otherwise. */
+    region?: string | undefined;
+};
+/**
+ * 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 `apiUrl`.
+ *
+ * The SDK hands you a standardised `ConsentPayload`; you transform and
+ * dispatch it however your backend expects.
+ */
+interface ConsentBackend {
+    persist(payload: ConsentPayload): Promise<void> | void;
+}
+/**
+ * @deprecated Use `"cookie-only"` instead — identical behavior, clearer name.
+ * `"offline"` still works but will be removed after three release cycles.
+ */
+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;
+    /**
+     * Optional geo-detection: choose the regulation from the visitor's region.
+     * Fully optional — omit it and nothing changes. A manual `regulation` (above)
+     * always wins over detection. See {@link RegionConfig}.
+     */
+    region?: RegionConfig | undefined;
+    colorScheme?: ColorScheme | undefined;
+    theme?: ThemeConfig | undefined;
+    i18n?: I18nConfig | 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;
+    /**
+     * How to combine multiple categories that map to the same Google Consent Mode
+     * signal: `"any"` (default) or `"all"`. Only matters for a custom taxonomy
+     * where more than one category maps to the same signal.
+     */
+    googleConsentMatch?: "all" | "any" | undefined;
+    /**
+     * Ready-made third-party integrations to gate behind consent — Segment, Meta,
+     * Google, and more — using a preset from `@cookieyes/scripts`. Each preset
+     * returns an {@link Integration}: it loads only once its category is granted
+     * (or, for Google Consent Mode, loads immediately and denies by default), and
+     * is removed or silenced on withdrawal.
+     *
+     * @example integrations: [segment({ writeKey: "..." })]
+     */
+    integrations?: Integration[] | undefined;
+    /**
+     * @deprecated Renamed from `integrations`. Built-in stop-handlers for a few
+     * first-party vendors — e.g. `{ vendor: "meta" }` — stopped cleanly (no
+     * reload) when their category is revoked. Prefer the new `integrations` field
+     * with a preset from `@cookieyes/scripts`; this will be removed after three
+     * release cycles.
+     */
+    builtInIntegrations?: 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;
+    /** 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;
+    /** How the active regulation was decided (region, source, confidence). */
+    getRegion: () => RegionDecision;
+    /**
+     * 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;
+    /** Config + live status for each script integration — data for a debug view. */
+    getIntegrations: () => IntegrationDebugInfo[];
+    /**
+     * Resolves once configured integrations have been loaded and wired up.
+     *
+     * The integration runner is loaded on demand — it is the largest subsystem in
+     * the package and does nothing unless `integrations` is configured — so there
+     * is a short window after setup in which `getIntegrations()` returns `[]` and
+     * no integration has been set up yet. Await this to act after that window;
+     * it resolves immediately when no integrations are configured.
+     *
+     * Nothing about consent gating depends on it: an integration cannot run
+     * before its category is granted whether or not it has loaded yet.
+     */
+    integrationsReady: Promise<void>;
+};
+/**
+ * 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;
+export { DEFAULT_CATEGORIES as M, INTEGRATION_FORMAT_VERSION as O, _clearStopHandlers as a1, installNetworkBlocker as a2, registerNetworkBlocker as a3, registerStopHandler as a4, resolveBuiltInIntegration as a5, resolveCategories as a6, runIntegrations as a7, uninstallNetworkBlocker as a8, warnOverlappingVendors as a9, warnUnknownCategories as aa };
+export type { SetupCtx as $, ActiveUI as A, BuiltInIntegration as B, ConsentRuntimeMode as C, ConsentPayload as D, ConsentRuntimeOptions as E, ConsentStore as F, GoogleConsentSignal as G, ConsentStoreState as H, I18nConfig as I, CookieYesOfflineConfig as J, CookieYesSelfHostedConfig as K, LanguageInfo as L, NetworkBlockerConfig as N, PartialTranslations as P, IntegrationDebugInfo as Q, Regulation as R, StopHandler as S, ThemeConfig as T, IntegrationStatus as U, NetworkBlockerRule as V, RegionDetector as W, RegionSource as X, ReloadNoticeState as Y, ReloadOnlyHandler as Z, ScriptEntry as _, RegionConfig as a, SilenceControl as a0, ColorScheme as b, CategoryDef as c, Integration as d, ConsentSnapshot as e, ConsentBackend as f, CookieYesConfig as g, ConsentEventType as h, ConsentEventListener as i, ConsentEventOptions as j, ResolvedCategories as k, TranslationMap as l, TextDirection as m, IntegrationHost as n, IntegrationRunner as o, CategoryText as p, ConsentConfig as q, ConsentManager as r, ConsentCategory as s, RegionDecision as t, ConsentRuntime as u, AnyStopHandler as v, BlockedRequestInfo as w, Cleanup as x, ConsentChangePayload as y, ConsentEventPayload as z };