@feelflow/ffid-sdk 4.3.0 → 5.0.1

package/dist/FFIDCookieLink-VYI2cSAB.d.cts

@@ -0,0 +1,878 @@
+import * as React$1 from 'react';
+import { ReactNode, CSSProperties } from 'react';
+import { z } from 'zod';
+
+/**
+ * Cookie Consent — Zod schemas (canonical source of truth).
+ *
+ * Two layers of schemas live in this file:
+ *
+ * 1. **SDK consumer-facing schemas** (camelCase, discriminated union). These
+ *    are what `useFFIDConsent()` / `useFFIDConsentPreferences()` surface to
+ *    React code, and what spec §6.4 documents as the SDK public contract.
+ *
+ * 2. **Wire schemas** (`*WireSchema`, snake_case envelopes). These mirror the
+ *    actual FFID API responses from `src/app/api/v1/ext/consent/*`, which
+ *    follow the FFID server-side convention of snake_case body fields plus
+ *    nullable `consent` envelopes. `consent-client.ts` parses responses with
+ *    these and then maps to the consumer-facing types via `mappers.ts`.
+ *
+ * TypeScript types are derived in `types.ts` via `z.infer<>`.
+ * `as` casting is forbidden; cross-trust-boundary data must be safe-parsed.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.4 + §5
+ */
+
+declare const FFIDConsentCategoryCodeSchema: z.ZodEnum<{
+    necessary: "necessary";
+    functional: "functional";
+    analytics: "analytics";
+    marketing: "marketing";
+}>;
+/**
+ * Consent state per category. `necessary` is enforced to be `true` at both
+ * type and runtime levels (`z.literal(true)`). The DB CHECK constraint
+ * `ucc_necessary_always_true` mirrors this on the storage side.
+ */
+declare const FFIDConsentCategoriesSchema: z.ZodObject<{
+    necessary: z.ZodLiteral<true>;
+    functional: z.ZodBoolean;
+    analytics: z.ZodBoolean;
+    marketing: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Public sources exposed to SDK consumers. UI logic should only branch on these.
+ */
+declare const FFIDPublicConsentSourceSchema: z.ZodEnum<{
+    banner: "banner";
+    preference_center: "preference_center";
+}>;
+/**
+ * Internal sources used by SDK / API plumbing. Consumers should treat these
+ * as opaque (no UI branching).
+ *
+ * - `sdk_default`: SDK default state before any decision has been recorded
+ *   (paired with `hasDecided: false`).
+ * - `api_withdraw`: row created by `POST /withdraw` server-side.
+ * - `sync_merge`: row created by `/sync` merge logic server-side.
+ * - `persisted_unknown`: decision is on file (`hasDecided: true`) but
+ *   `/me` did not surface its original source. The decision is authoritative;
+ *   the source label is just unavailable.
+ */
+declare const FFIDInternalConsentSourceSchema: z.ZodEnum<{
+    sdk_default: "sdk_default";
+    api_withdraw: "api_withdraw";
+    sync_merge: "sync_merge";
+    persisted_unknown: "persisted_unknown";
+}>;
+declare const FFIDConsentSourceSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    banner: "banner";
+    preference_center: "preference_center";
+}>, z.ZodEnum<{
+    sdk_default: "sdk_default";
+    api_withdraw: "api_withdraw";
+    sync_merge: "sync_merge";
+    persisted_unknown: "persisted_unknown";
+}>]>;
+/**
+ * Merge strategy returned by `POST /api/v1/ext/consent/sync`.
+ * Closed enum — `safeParse` will fail on unknown values so a server-side
+ * regression that introduces a new strategy is caught at parse time rather
+ * than silently passing through.
+ */
+declare const FFIDConsentMergeStrategySchema: z.ZodEnum<{
+    db_wins: "db_wins";
+    device_promoted: "device_promoted";
+    device_promoted_with_drift: "device_promoted_with_drift";
+    cross_user_insert: "cross_user_insert";
+    first_insert: "first_insert";
+}>;
+/**
+ * Warning literal accompanying merge strategy. Per spec §5.3 the SDK is
+ * required to surface non-null warnings to consumers (silent merge forbidden).
+ */
+declare const FFIDConsentMergeWarningSchema: z.ZodEnum<{
+    shared_device_detected: "shared_device_detected";
+    local_state_overridden: "local_state_overridden";
+    drift_detected: "drift_detected";
+}>;
+/**
+ * Discriminated union: `hasDecided` drives null-ness of dependent fields.
+ * Allows TypeScript narrowing in consumer code:
+ *   if (state.hasDecided) { state.decidedAt /* Date *​/ }
+ */
+declare const FFIDConsentStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    hasDecided: z.ZodLiteral<false>;
+    needsRenewal: z.ZodBoolean;
+    categories: z.ZodObject<{
+        necessary: z.ZodLiteral<true>;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+    }, z.core.$strip>;
+    decidedAt: z.ZodNull;
+    cookiePolicyVersion: z.ZodNull;
+    source: z.ZodNull;
+}, z.core.$strip>, z.ZodObject<{
+    hasDecided: z.ZodLiteral<true>;
+    needsRenewal: z.ZodBoolean;
+    categories: z.ZodObject<{
+        necessary: z.ZodLiteral<true>;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+    }, z.core.$strip>;
+    decidedAt: z.ZodCoercedDate<unknown>;
+    cookiePolicyVersion: z.ZodString;
+    source: z.ZodUnion<readonly [z.ZodEnum<{
+        banner: "banner";
+        preference_center: "preference_center";
+    }>, z.ZodEnum<{
+        sdk_default: "sdk_default";
+        api_withdraw: "api_withdraw";
+        sync_merge: "sync_merge";
+        persisted_unknown: "persisted_unknown";
+    }>]>;
+}, z.core.$strip>], "hasDecided">;
+/**
+ * Setter shape — `necessary` is intentionally not toggleable.
+ */
+declare const FFIDConsentUpdateSchema: z.ZodObject<{
+    functional: z.ZodOptional<z.ZodBoolean>;
+    analytics: z.ZodOptional<z.ZodBoolean>;
+    marketing: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Category metadata for i18n-aware preference center rendering.
+ * Mirrors the camelCase shape `getCategoriesMaster()` returns in the FFID
+ * repository (snake_case DB columns are already converted server-side).
+ */
+declare const FFIDConsentCategoryMetadataSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        necessary: "necessary";
+        functional: "functional";
+        analytics: "analytics";
+        marketing: "marketing";
+    }>;
+    displayOrder: z.ZodNumber;
+    isRequired: z.ZodBoolean;
+    label: z.ZodString;
+    description: z.ZodString;
+    exampleServices: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Cookie policy document — camelCase shape from `getCurrentCookiePolicy()`.
+ */
+declare const FFIDCookiePolicySchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+    content: z.ZodString;
+    effectiveDate: z.ZodISODate;
+    publishedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * Body for `POST /api/v1/ext/consent` (banner / preference center submit).
+ * `necessary` is intentionally NOT accepted from clients — server enforces true.
+ */
+declare const PostConsentRequestSchema: z.ZodObject<{
+    categories: z.ZodObject<{
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+    }, z.core.$strict>;
+    source: z.ZodEnum<{
+        banner: "banner";
+        preference_center: "preference_center";
+    }>;
+    cookie_policy_version: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Body for `POST /api/v1/ext/consent/sync`.
+ * `local_consent` is optional — null indicates the SDK has no local state.
+ */
+declare const PostSyncRequestSchema: z.ZodObject<{
+    local_consent: z.ZodNullable<z.ZodObject<{
+        necessary: z.ZodLiteral<true>;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+        cookie_policy_version: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `GET /api/v1/ext/consent/me` response */
+declare const GetConsentMeWireSchema: z.ZodObject<{
+    consent: z.ZodNullable<z.ZodObject<{
+        necessary: z.ZodBoolean;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+        cookie_policy_version: z.ZodString;
+        decided_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    default_state: z.ZodOptional<z.ZodObject<{
+        necessary: z.ZodLiteral<true>;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+    }, z.core.$strip>>;
+    current_policy_version: z.ZodString;
+    needs_renewal: z.ZodBoolean;
+    degraded: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** `POST /api/v1/ext/consent` response */
+declare const PostConsentWireSchema: z.ZodObject<{
+    consent: z.ZodObject<{
+        necessary: z.ZodBoolean;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+        cookie_policy_version: z.ZodString;
+        decided_at: z.ZodISODateTime;
+        id: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** `POST /api/v1/ext/consent/sync` response */
+declare const PostSyncWireSchema: z.ZodObject<{
+    consent: z.ZodObject<{
+        necessary: z.ZodBoolean;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+        cookie_policy_version: z.ZodString;
+        decided_at: z.ZodISODateTime;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    merge_strategy: z.ZodEnum<{
+        db_wins: "db_wins";
+        device_promoted: "device_promoted";
+        device_promoted_with_drift: "device_promoted_with_drift";
+        cross_user_insert: "cross_user_insert";
+        first_insert: "first_insert";
+    }>;
+    warning: z.ZodNullable<z.ZodEnum<{
+        shared_device_detected: "shared_device_detected";
+        local_state_overridden: "local_state_overridden";
+        drift_detected: "drift_detected";
+    }>>;
+}, z.core.$strip>;
+/** `POST /api/v1/ext/consent/withdraw` response */
+declare const PostWithdrawWireSchema: z.ZodObject<{
+    consent: z.ZodObject<{
+        necessary: z.ZodBoolean;
+        functional: z.ZodBoolean;
+        analytics: z.ZodBoolean;
+        marketing: z.ZodBoolean;
+        cookie_policy_version: z.ZodString;
+        decided_at: z.ZodISODateTime;
+        id: z.ZodString;
+        is_withdrawal: z.ZodLiteral<true>;
+        supersedes_id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** `GET /api/v1/ext/consent/categories` response (already camelCase) */
+declare const GetCategoriesWireSchema: z.ZodObject<{
+    categories: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            necessary: "necessary";
+            functional: "functional";
+            analytics: "analytics";
+            marketing: "marketing";
+        }>;
+        displayOrder: z.ZodNumber;
+        isRequired: z.ZodBoolean;
+        label: z.ZodString;
+        description: z.ZodString;
+        exampleServices: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `GET /api/v1/ext/consent/document` response (already camelCase) */
+declare const GetDocumentWireSchema: z.ZodObject<{
+    document: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+        content: z.ZodString;
+        effectiveDate: z.ZodISODate;
+        publishedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Validate `X-FFID-Device-Id` header value. Accepts UUIDv4 / UUIDv7 (both
+ * 36-char hex with dashes). Reuses the same `UUID_REGEX` as `UuidLikeSchema`
+ * to avoid drift between wire id validators.
+ */
+declare const DeviceIdSchema: z.ZodString;
+
+/**
+ * Cookie Consent — TypeScript types derived from Zod schemas.
+ *
+ * Always derive types via `z.infer<>`; never hand-roll TypeScript types that
+ * could drift from the canonical Zod schema. Refs: schemas.ts
+ */
+
+type FFIDConsentCategoryCode = z.infer<typeof FFIDConsentCategoryCodeSchema>;
+type FFIDConsentCategories = z.infer<typeof FFIDConsentCategoriesSchema>;
+type FFIDPublicConsentSource = z.infer<typeof FFIDPublicConsentSourceSchema>;
+type FFIDInternalConsentSource = z.infer<typeof FFIDInternalConsentSourceSchema>;
+type FFIDConsentSource = z.infer<typeof FFIDConsentSourceSchema>;
+type FFIDConsentState = z.infer<typeof FFIDConsentStateSchema>;
+type FFIDConsentUpdate = z.infer<typeof FFIDConsentUpdateSchema>;
+type FFIDConsentCategoryMetadata = z.infer<typeof FFIDConsentCategoryMetadataSchema>;
+type FFIDCookiePolicy = z.infer<typeof FFIDCookiePolicySchema>;
+type FFIDConsentMergeStrategy = z.infer<typeof FFIDConsentMergeStrategySchema>;
+type FFIDConsentMergeWarning = z.infer<typeof FFIDConsentMergeWarningSchema>;
+type PostConsentRequest = z.infer<typeof PostConsentRequestSchema>;
+type PostSyncRequest = z.infer<typeof PostSyncRequestSchema>;
+type GetConsentMeWire = z.infer<typeof GetConsentMeWireSchema>;
+type PostConsentWire = z.infer<typeof PostConsentWireSchema>;
+type PostSyncWire = z.infer<typeof PostSyncWireSchema>;
+type PostWithdrawWire = z.infer<typeof PostWithdrawWireSchema>;
+type GetCategoriesWire = z.infer<typeof GetCategoriesWireSchema>;
+type GetDocumentWire = z.infer<typeof GetDocumentWireSchema>;
+/**
+ * Warning event surfaced to `onConsentChange(state, warning)` after a `/sync`
+ * call. Spec §5.3 requires non-null warnings to be visible to the user.
+ */
+interface FFIDConsentMergeWarningEvent {
+    code: FFIDConsentMergeWarning;
+    message: string;
+}
+/**
+ * Result of a sync call surfaced to consumers — drops the wire envelope and
+ * folds the warning into a structured object so UI code can pattern-match
+ * without re-implementing `merge_strategy → warning` knowledge.
+ */
+interface FFIDConsentSyncResult {
+    state: FFIDConsentState;
+    mergeStrategy: FFIDConsentMergeStrategy;
+    warning: FFIDConsentMergeWarning | null;
+}
+
+/**
+ * Cookie Consent — error types and reserved errorIds.
+ *
+ * Spec §8.2 reserves these errorIds for Sentry / logger correlation between
+ * SDK, FFID API, and ops dashboards. SDK consumers can branch on `code` to
+ * customize UX (e.g., show retry hint for rate_limited, show "please relogin"
+ * for auth_failure).
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §8
+ */
+/**
+ * Error code literal union for consent SDK failures.
+ *
+ * - The first 10 codes (`cookie_consent_*`) are reserved by spec §8.2 for
+ *   correlation across SDK / FFID API / ops dashboards.
+ * - `auth_failure` is added by the SDK to cover 401 / 403 responses; it is
+ *   NOT part of spec §8.2 reserved codes — the SDK shares this code with the
+ *   wider FFID auth surface so consumer error handlers can branch uniformly.
+ */
+declare const FFID_CONSENT_ERROR_CODES: readonly ["cookie_consent_api_unreachable", "cookie_consent_response_invalid", "cookie_consent_rate_limited", "cookie_consent_cookie_write_failed", "cookie_consent_parse_failed", "cookie_consent_sync_conflict", "cookie_consent_immutable_violation", "cookie_consent_policy_outdated", "cookie_consent_capture_failed", "cookie_consent_db_write_failed", "auth_failure"];
+type FFIDConsentErrorCode = (typeof FFID_CONSENT_ERROR_CODES)[number];
+/**
+ * Error class for all consent-related failures surfaced through SDK callbacks
+ * (`onError`) and hook `error` fields.
+ *
+ * `message` is intended to be user-displayable in Japanese; consumers should
+ * still feel free to override per their i18n needs.
+ */
+declare class FFIDConsentError extends Error {
+    readonly code: FFIDConsentErrorCode;
+    readonly httpStatus?: number;
+    /** For rate-limited errors (HTTP 429): seconds suggested by `Retry-After`. */
+    readonly retryAfterSec?: number;
+    readonly cause?: unknown;
+    constructor(code: FFIDConsentErrorCode, message: string, options?: {
+        httpStatus?: number;
+        retryAfterSec?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Result discriminated union for consent SDK actions.
+ * Mirrors `src/lib/common/types.ts` Result pattern but kept SDK-local so the
+ * package has no FFID-internal imports.
+ */
+type FFIDConsentResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: FFIDConsentError;
+};
+/**
+ * Japanese user-displayable default messages keyed by errorCode.
+ * Consumers can override; SDK UI components use these as fallback.
+ */
+declare const DEFAULT_CONSENT_ERROR_MESSAGES: Record<FFIDConsentErrorCode, string>;
+
+/**
+ * Cookie Consent codec — encode / decode the `ffid_consent` 1st-party cookie.
+ *
+ * Format: `v1:n+,f+,a-,m+`
+ *   - `v1:` version prefix (forward-compat for v2+)
+ *   - n=necessary, f=functional, a=analytics, m=marketing
+ *   - `+` (granted) / `-` (denied)
+ *
+ * **Safe-parse contract**: `decodeConsentCookie` NEVER throws. Any malformed,
+ * truncated, future-version, or otherwise unparseable input returns
+ * `ALL_DENIED_EXCEPT_NECESSARY`. Callers are responsible for logging via
+ * `cookie_consent_parse_failed` errorId if needed.
+ *
+ * This codec is **byte-compatible** with the FFID server-side implementation
+ * (`src/lib/cookie-consent/codec.ts`). Both implementations must produce and
+ * accept the identical wire format — a roundtrip through either codec must
+ * yield the same bytes.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.5
+ */
+
+declare const COOKIE_VERSION: "v1";
+declare const ALL_DENIED_EXCEPT_NECESSARY: FFIDConsentCategories;
+declare function encodeConsentCookie(cats: FFIDConsentCategories): string;
+/**
+ * Safely decode the consent cookie string.
+ * Returns `ALL_DENIED_EXCEPT_NECESSARY` on any failure (fail-safe).
+ */
+declare function decodeConsentCookie(raw: string | null | undefined): FFIDConsentCategories;
+
+/**
+ * Cookie Consent — browser cookie read/write with read-back verification.
+ *
+ * Spec §6.5:
+ *   - Key: `ffid_consent`
+ *   - 1st-party, SameSite=Lax, Secure (production only — localhost dev uses
+ *     non-Secure)
+ *   - TTL: 1 year
+ *   - Write must be verified by read-back; failure -> caller surfaces
+ *     `cookie_consent_cookie_write_failed` and falls back to sessionStorage.
+ *
+ * This module is SSR-safe: all functions become no-ops when `document` is
+ * unavailable (server-side rendering), so calling code does not need to
+ * `typeof window` check itself.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.5
+ */
+
+declare const CONSENT_COOKIE_NAME = "ffid_consent";
+/** 1 year in seconds (Max-Age). */
+declare const CONSENT_COOKIE_MAX_AGE_SEC: number;
+/**
+ * sessionStorage mirror key (spec §6.5).
+ *
+ * **Precedence rule** (spec §6.5 "session 内では cookie より優先"): when
+ * reading consent state during the same browser session, the mirror takes
+ * precedence over the cookie. This protects against the race where the user
+ * just made a decision (we wrote to sessionStorage synchronously) but the
+ * browser hasn't yet committed the cookie write. Callers MUST read mirror
+ * first, then fall back to cookie. See `FFIDAnalyticsProvider.bootstrap`.
+ */
+declare const CONSENT_SESSION_STORAGE_KEY = "ffid_consent_state";
+interface WriteConsentCookieOptions {
+    /** Override Secure flag for non-https custom domains. Defaults to production. */
+    secure?: boolean;
+    /**
+     * Cookie domain. Leave undefined for current host only (1st-party). Setting
+     * a parent domain (e.g., `.feelflow.net`) enables cross-subdomain sync but
+     * requires explicit opt-in.
+     */
+    domain?: string;
+    /** Path for the cookie. Defaults to '/'. */
+    path?: string;
+}
+/**
+ * Read the consent cookie. Returns `ALL_DENIED_EXCEPT_NECESSARY` if absent,
+ * malformed, or `document` unavailable (SSR).
+ *
+ * Per spec §6.5 the codec never throws, so consumers receive a well-formed
+ * value in every code path.
+ */
+declare function readConsentCookie(): FFIDConsentCategories;
+/**
+ * Write the consent cookie and verify via read-back.
+ *
+ * @returns true if write was verified, false if browser silently rejected
+ *          (e.g., ITP, all-cookie block, Brave shields, private mode quirk).
+ *          On false, callers should surface `cookie_consent_cookie_write_failed`
+ *          and switch to sessionStorage fallback.
+ */
+declare function writeConsentCookie(cats: FFIDConsentCategories, opts?: WriteConsentCookieOptions): boolean;
+/**
+ * Delete the consent cookie (used by full withdrawal + tests).
+ *
+ * @returns true if deletion was verified (cookie absent on read-back).
+ */
+declare function deleteConsentCookie(opts?: WriteConsentCookieOptions): boolean;
+/**
+ * Read the sessionStorage mirror. Per spec §6.5, this must be consulted BEFORE
+ * the cookie within the same session (write-after-decision race protection).
+ * See `CONSENT_SESSION_STORAGE_KEY` doc-comment for the precedence rule.
+ */
+declare function readConsentSessionMirror(): FFIDConsentCategories | null;
+declare function writeConsentSessionMirror(cats: FFIDConsentCategories): boolean;
+declare function clearConsentSessionMirror(): void;
+
+/**
+ * Cookie Consent — Google Consent Mode v2 wiring.
+ *
+ * The bridge owns three concerns:
+ *
+ * 1. **Pre-decision default**: pushes `gtag('consent', 'default', ...)` with
+ *    ALL_DENIED_EXCEPT_NECESSARY **before** any GA script loads, so GA's
+ *    initial dataLayer scan picks up the deny defaults. The Provider calls
+ *    `setDefaultConsent()` synchronously on mount, prior to script injection.
+ *
+ * 2. **Post-decision update**: after the SDK resolves the consent state from
+ *    cookie / API, the Provider calls `updateConsent()`, which pushes
+ *    `gtag('consent', 'update', ...)` mapped from `FFIDConsentCategories`.
+ *
+ * 3. **GA script injection**: when `analytics` is granted and a measurement ID
+ *    is configured, the bridge appends the `gtag.js` script tag (no-op when
+ *    consent is denied or measurement ID is empty).
+ *
+ * Tests verify the push order (`consent default` precedes any tag wiring) and
+ * the boolean → 'granted'|'denied' mapping.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.2 + §7.5 (testing strategy)
+ */
+
+declare global {
+    interface Window {
+        dataLayer?: unknown[];
+        gtag?: (...args: unknown[]) => void;
+    }
+}
+interface GtagBridgeOptions {
+    /** GA Measurement ID, e.g., `G-XXXXXXX`. Empty/null = GA not wired. */
+    gaMeasurementId?: string | null;
+    /** Override script src for testing. Default: official gtag URL. */
+    gtagScriptSrc?: string;
+    /** Document/window injection target (server-side stays no-op). */
+    win?: Window;
+}
+interface GtagConsentParams {
+    ad_storage: 'granted' | 'denied';
+    ad_user_data: 'granted' | 'denied';
+    ad_personalization: 'granted' | 'denied';
+    analytics_storage: 'granted' | 'denied';
+    functionality_storage: 'granted' | 'denied';
+    personalization_storage: 'granted' | 'denied';
+    security_storage: 'granted' | 'denied';
+}
+/**
+ * Map our 4-category model to Google's Consent Mode v2 keys.
+ *
+ * - `necessary` → `security_storage` (always granted — regulatory baseline)
+ * - `functional` → `functionality_storage` + `personalization_storage`
+ * - `analytics` → `analytics_storage`
+ * - `marketing` → `ad_storage` + `ad_user_data` + `ad_personalization`
+ */
+declare function mapCategoriesToGtagParams(cats: FFIDConsentCategories): GtagConsentParams;
+interface GtagBridge {
+    /**
+     * Push `consent default` with ALL_DENIED_EXCEPT_NECESSARY. Must be called
+     * **synchronously** before any GA script tag is added. Idempotent.
+     */
+    setDefaultConsent(): void;
+    /**
+     * Push `consent update` mapped from current categories. Safe to call as
+     * many times as needed (consent toggle / banner / withdrawal etc.).
+     */
+    updateConsent(cats: FFIDConsentCategories): void;
+    /**
+     * Inject GA loader script when `analytics` is granted. Does nothing when
+     * GA measurement ID is empty or analytics is denied.
+     */
+    applyGaInjection(cats: FFIDConsentCategories): void;
+}
+declare function createGtagBridge(opts?: GtagBridgeOptions): GtagBridge;
+
+/**
+ * Cookie Consent — `<FFIDAnalyticsProvider>` (gtag + Sentry wiring).
+ *
+ * Responsibilities:
+ *   1. Mount-time: push `gtag('consent', 'default', ALL_DENIED_EXCEPT_NECESSARY)`
+ *      synchronously BEFORE any GA script could load (spec §6.2).
+ *   2. Resolve initial state: read cookie / session mirror, then GET /me to
+ *      reconcile against server-side authoritative.
+ *   3. On consent change: push `gtag('consent', 'update', ...)`, inject GA
+ *      script if `analytics` granted + measurement ID configured.
+ *   4. Sentry replay gating: when `functional` is granted, start replay;
+ *      otherwise stop (graceful no-op if `@sentry/react` is not present).
+ *   5. Surface merge warnings from `/sync` via `onConsentChange(state, warning)`.
+ *
+ * Note: Vercel Analytics integration is **not** yet wired — planned for a
+ * follow-up issue. Until then, consumers can adopt
+ * `@vercel/analytics`'s `<Analytics />` component directly and gate it on
+ * `useFFIDConsent().categories.analytics`.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.2 + §6.3 + §6.7
+ */
+
+/**
+ * Minimal Sentry shape we depend on. Avoids forcing consumers to install
+ * `@sentry/react` if they're not using session replay.
+ */
+interface SentryReplayLike {
+    start: () => void;
+    stop: () => void | Promise<void>;
+}
+interface SentryNamespace {
+    getReplay?: () => SentryReplayLike | undefined;
+}
+interface FFIDAnalyticsProviderProps {
+    /** FFID API base URL (e.g., `https://id.feelflow.net`). Required. */
+    baseUrl: string;
+    /** Service API Key issued by FFID for this app. Required. */
+    serviceApiKey: string;
+    /** Resolves a Bearer token, or null when logged out. Optional. */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /**
+     * GA Measurement ID, e.g., `G-XXXXXXX`. Pass `null` to disable GA wiring.
+     * 2-state field (`string | null`) — null is the explicit "no GA" sentinel,
+     * avoiding the triple-state `string | null | undefined` anti-pattern.
+     */
+    gaMeasurementId?: string | null;
+    /** When true, control Sentry session replay based on `functional` consent. */
+    sentryReplay?: boolean;
+    /** Sentry namespace override; defaults to `(window as any).Sentry`. */
+    sentry?: SentryNamespace;
+    /** Fired whenever consent state changes; second argument is any merge warning. */
+    onConsentChange?: (state: FFIDConsentState, warning: FFIDConsentMergeWarningEvent | null) => void;
+    /** Fired when any action error occurs. */
+    onError?: (error: FFIDConsentError) => void;
+    /** Whether to open banner automatically when no decision is on file. Default: true. */
+    autoShowBanner?: boolean;
+    /** Optional fetch override (mainly for tests). */
+    fetchImpl?: typeof fetch;
+    children: ReactNode;
+}
+declare function FFIDAnalyticsProvider({ baseUrl, serviceApiKey, getAccessToken, gaMeasurementId, sentryReplay, sentry, onConsentChange, onError, autoShowBanner, fetchImpl, children, }: FFIDAnalyticsProviderProps): React.JSX.Element;
+
+interface FFIDConsentContextValue {
+    /** Current consent state. Always non-null; "not yet decided" is encoded by `hasDecided=false`. */
+    state: FFIDConsentState;
+    /** True while the provider is performing initial GET /me / sync. */
+    isLoading: boolean;
+    /** Last error from any action (auto-cleared on next successful action). */
+    error: FFIDConsentError | null;
+    /** Category master data; lazily fetched on first preference center open. */
+    categoryMetadata: FFIDConsentCategoryMetadata[] | null;
+    /** Current cookie_policy document; lazily fetched on banner / settings open. */
+    policy: FFIDCookiePolicy | null;
+    isBannerOpen: boolean;
+    isPreferencesOpen: boolean;
+    openBanner: () => void;
+    closeBanner: () => void;
+    openPreferences: () => Promise<void>;
+    closePreferences: () => void;
+    acceptAll: () => Promise<FFIDConsentResult<FFIDConsentState>>;
+    acceptNecessaryOnly: () => Promise<FFIDConsentResult<FFIDConsentState>>;
+    setCategories: (changes: {
+        functional?: boolean;
+        analytics?: boolean;
+        marketing?: boolean;
+    }, source?: 'banner' | 'preference_center') => Promise<FFIDConsentResult<FFIDConsentState>>;
+    withdraw: () => Promise<FFIDConsentResult<FFIDConsentState>>;
+    refresh: () => Promise<void>;
+    /**
+     * @internal Reconcile local cookie state with server-side via `POST /sync`.
+     *
+     * Consumers integrating FFID auth should call this **from their OAuth
+     * callback handler** so that the freshly-issued Bearer token can be merged
+     * with the pre-login device-scoped consent row. The SDK does NOT subscribe
+     * to auth state internally — it has no portable way to detect login
+     * events across framework conventions (Next.js Middleware, OAuth flows,
+     * etc.). Pattern:
+     *
+     * ```ts
+     * import { useContext } from 'react'
+     * import { FFIDConsentContext } from '@feelflow/ffid-sdk/consent'
+     * function OAuthCallback() {
+     *   const ctx = useContext(FFIDConsentContext)
+     *   useEffect(() => { void ctx.syncWithUser() }, [ctx])
+     * }
+     * ```
+     */
+    syncWithUser: () => Promise<FFIDConsentResult<FFIDConsentSyncResult>>;
+}
+declare const FFID_CONSENT_NOT_DECIDED_STATE: FFIDConsentState;
+declare const FFIDConsentContext: React$1.Context<FFIDConsentContextValue>;
+/**
+ * Warning literal-keyed default copy for `local_state_overridden` /
+ * `shared_device_detected` / `drift_detected`. Surfaced by the Provider via
+ * `onConsentChange(state, warning)` per spec §5.3.
+ */
+declare const DEFAULT_MERGE_WARNING_MESSAGES: Record<FFIDConsentMergeWarning, string>;
+
+/**
+ * `useFFIDConsent` — primary hook for reading + updating cookie consent.
+ *
+ * @example
+ * ```tsx
+ * const { state, isLoading, acceptAll, openPreferences } = useFFIDConsent()
+ * if (state.categories.analytics) {
+ *   // safe to fire analytics events
+ * }
+ * ```
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.3
+ */
+
+interface UseFFIDConsentReturn {
+    /** Full discriminated-union state (camelCase). */
+    state: FFIDConsentContextValue['state'];
+    /** Shortcut for `state.categories`. */
+    categories: FFIDConsentCategories;
+    /** Whether SDK is performing initial bootstrap / sync. */
+    isLoading: boolean;
+    /** Last action error (null after a successful action). */
+    error: FFIDConsentContextValue['error'];
+    /** Whether the banner is currently visible. */
+    isBannerOpen: boolean;
+    /** Whether the preference center modal is currently visible. */
+    isPreferencesOpen: boolean;
+    openBanner: FFIDConsentContextValue['openBanner'];
+    closeBanner: FFIDConsentContextValue['closeBanner'];
+    openPreferences: FFIDConsentContextValue['openPreferences'];
+    closePreferences: FFIDConsentContextValue['closePreferences'];
+    acceptAll: FFIDConsentContextValue['acceptAll'];
+    acceptNecessaryOnly: FFIDConsentContextValue['acceptNecessaryOnly'];
+    setCategories: FFIDConsentContextValue['setCategories'];
+    withdraw: FFIDConsentContextValue['withdraw'];
+    refresh: FFIDConsentContextValue['refresh'];
+}
+declare function useFFIDConsent(): UseFFIDConsentReturn;
+
+/**
+ * `useFFIDConsentPreferences` — advanced hook for building custom preference
+ * center UI. Provides category metadata and policy document alongside the
+ * standard state.
+ *
+ * @example
+ * ```tsx
+ * const { categoryMetadata, policy, save } = useFFIDConsentPreferences()
+ * return (
+ *   <>
+ *     {categoryMetadata?.map(c => <Toggle key={c.code} ... />)}
+ *     <button onClick={() => save({ analytics: true })}>Save</button>
+ *   </>
+ * )
+ * ```
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.3
+ */
+
+interface UseFFIDConsentPreferencesReturn {
+    state: FFIDConsentState;
+    /** Category master with i18n labels; null until `openPreferences()` is called. */
+    categoryMetadata: FFIDConsentCategoryMetadata[] | null;
+    /** Cookie policy document; null until fetched. */
+    policy: FFIDCookiePolicy | null;
+    isLoading: boolean;
+    /**
+     * Save category changes. Source is locked to `preference_center` to make
+     * audit trails easier to interpret.
+     */
+    save: (changes: {
+        functional?: boolean;
+        analytics?: boolean;
+        marketing?: boolean;
+    }) => Promise<FFIDConsentResult<FFIDConsentState>>;
+    withdraw: () => Promise<FFIDConsentResult<FFIDConsentState>>;
+}
+declare function useFFIDConsentPreferences(): UseFFIDConsentPreferencesReturn;
+
+/**
+ * `<FFIDCookieBanner>` — bottom-sheet consent banner.
+ *
+ * Renders only when `state.hasDecided === false` or `state.needsRenewal === true`.
+ * Three buttons (spec §6.2):
+ *   1. "すべて同意" (Accept all)
+ *   2. "必要なものだけ" (Necessary only)
+ *   3. "詳細設定" (Open preference center)
+ *
+ * GDPR Article 7(1)/(2) UX requirements:
+ *   - "同意" and "拒否" share the same size + visual prominence.
+ *   - Buttons share the same styles by default; consumers can override via
+ *     `classNames` props (`primaryButton`, `secondaryButton`, `linkButton`).
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.2
+ */
+
+interface FFIDCookieBannerClassNames {
+    root?: string;
+    message?: string;
+    buttonGroup?: string;
+    primaryButton?: string;
+    secondaryButton?: string;
+    linkButton?: string;
+}
+interface FFIDCookieBannerProps {
+    /** Root container class. */
+    className?: string;
+    /** Per-element override classes for finer customization. */
+    classNames?: FFIDCookieBannerClassNames;
+    /** Override the banner copy (default Japanese). */
+    message?: ReactNode;
+    /** Accept-all button label. Default: "すべて同意". */
+    acceptAllLabel?: ReactNode;
+    /** Necessary-only button label. Default: "必要なものだけ". */
+    necessaryOnlyLabel?: ReactNode;
+    /** Preference center link label. Default: "詳細設定". */
+    preferencesLabel?: ReactNode;
+    /** Custom root style. */
+    style?: CSSProperties;
+}
+declare function FFIDCookieBanner({ className, classNames, message, acceptAllLabel, necessaryOnlyLabel, preferencesLabel, style, }: FFIDCookieBannerProps): React.JSX.Element | null;
+
+/**
+ * `<FFIDCookieSettings>` — preference center modal.
+ *
+ * Renders the 4-category toggle list (necessary is `disabled` per spec §6.2,
+ * runtime + DB invariant both enforce `necessary=true`). Save / Withdraw
+ * buttons commit changes through `useFFIDConsentPreferences`.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.2 + §6.3
+ */
+interface FFIDCookieSettingsClassNames {
+    root?: string;
+    backdrop?: string;
+    header?: string;
+    categoryRow?: string;
+    primaryButton?: string;
+    secondaryButton?: string;
+}
+interface FFIDCookieSettingsProps {
+    className?: string;
+    classNames?: FFIDCookieSettingsClassNames;
+    /** Open/close override; defaults to the context's `isPreferencesOpen`. */
+    open?: boolean;
+    /** When true, also expose a "すべて撤回" button. Default: true. */
+    showWithdrawButton?: boolean;
+}
+declare function FFIDCookieSettings({ className, classNames, open, showWithdrawButton, }: FFIDCookieSettingsProps): React.JSX.Element | null;
+
+/**
+ * `<FFIDCookieLink>` — footer link that opens the preference center.
+ *
+ * **GDPR Article 7(3) compliance**: this link MUST be present on every page
+ * to allow consent withdrawal with the same number of clicks as consent. Use
+ * this component in any footer / header to satisfy the requirement.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.2
+ */
+
+interface FFIDCookieLinkProps {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Optional element id for screen-reader-friendly footer landmarks. */
+    id?: string;
+}
+declare function FFIDCookieLink({ children, className, style, id, }: FFIDCookieLinkProps): React.JSX.Element;
+
+export { GetCategoriesWireSchema as $, ALL_DENIED_EXCEPT_NECESSARY as A, FFIDConsentMergeWarningSchema as B, CONSENT_COOKIE_MAX_AGE_SEC as C, DEFAULT_CONSENT_ERROR_MESSAGES as D, type FFIDConsentSource as E, type FFIDConsentResult as F, type GetConsentMeWire as G, FFIDConsentSourceSchema as H, FFIDConsentStateSchema as I, FFIDConsentUpdateSchema as J, FFIDCookieBanner as K, type FFIDCookieBannerClassNames as L, type FFIDCookieBannerProps as M, FFIDCookieLink as N, type FFIDCookieLinkProps as O, type PostConsentWire as P, FFIDCookiePolicySchema as Q, FFIDCookieSettings as R, type FFIDCookieSettingsClassNames as S, type FFIDCookieSettingsProps as T, type FFIDInternalConsentSource as U, FFIDInternalConsentSourceSchema as V, type FFIDPublicConsentSource as W, FFIDPublicConsentSourceSchema as X, FFID_CONSENT_ERROR_CODES as Y, FFID_CONSENT_NOT_DECIDED_STATE as Z, type GetCategoriesWire as _, type FFIDConsentState as a, GetConsentMeWireSchema as a0, type GetDocumentWire as a1, GetDocumentWireSchema as a2, type GtagBridge as a3, type GtagBridgeOptions as a4, type PostConsentRequest as a5, PostConsentRequestSchema as a6, PostConsentWireSchema as a7, type PostSyncRequest as a8, PostSyncRequestSchema as a9, PostSyncWireSchema as aa, PostWithdrawWireSchema as ab, type UseFFIDConsentPreferencesReturn as ac, type UseFFIDConsentReturn as ad, clearConsentSessionMirror as ae, createGtagBridge as af, decodeConsentCookie as ag, deleteConsentCookie as ah, encodeConsentCookie as ai, mapCategoriesToGtagParams as aj, readConsentCookie as ak, readConsentSessionMirror as al, useFFIDConsent as am, useFFIDConsentPreferences as an, writeConsentCookie as ao, writeConsentSessionMirror as ap, type FFIDConsentUpdate as b, type FFIDConsentCategories as c, type FFIDConsentSyncResult as d, type FFIDConsentCategoryMetadata as e, type FFIDCookiePolicy as f, type PostSyncWire as g, type PostWithdrawWire as h, CONSENT_COOKIE_NAME as i, CONSENT_SESSION_STORAGE_KEY as j, COOKIE_VERSION as k, DEFAULT_MERGE_WARNING_MESSAGES as l, DeviceIdSchema as m, FFIDAnalyticsProvider as n, type FFIDAnalyticsProviderProps as o, FFIDConsentCategoriesSchema as p, type FFIDConsentCategoryCode as q, FFIDConsentCategoryCodeSchema as r, FFIDConsentCategoryMetadataSchema as s, FFIDConsentContext as t, type FFIDConsentContextValue as u, FFIDConsentError as v, type FFIDConsentErrorCode as w, type FFIDConsentMergeStrategy as x, FFIDConsentMergeStrategySchema as y, type FFIDConsentMergeWarning as z };