@feelflow/ffid-sdk 4.3.0 → 5.0.1

package/dist/{chunk-35UOD62N.js → chunk-YOJJ433H.js}

@@ -838,7 +838,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "4.3.0";
+var SDK_VERSION = "5.0.1";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {

package/dist/components/index.cjs

@@ -1,34 +1,34 @@
 'use strict';
 
-var chunk5MO7G2JW_cjs = require('../chunk-5MO7G2JW.cjs');
+var chunk223MPEBU_cjs = require('../chunk-223MPEBU.cjs');
 
 
 
 Object.defineProperty(exports, "FFIDAnnouncementBadge", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDAnnouncementBadge; }
+  get: function () { return chunk223MPEBU_cjs.FFIDAnnouncementBadge; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementList", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDAnnouncementList; }
+  get: function () { return chunk223MPEBU_cjs.FFIDAnnouncementList; }
 });
 Object.defineProperty(exports, "FFIDInquiryForm", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDInquiryForm; }
+  get: function () { return chunk223MPEBU_cjs.FFIDInquiryForm; }
 });
 Object.defineProperty(exports, "FFIDLoginButton", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDLoginButton; }
+  get: function () { return chunk223MPEBU_cjs.FFIDLoginButton; }
 });
 Object.defineProperty(exports, "FFIDOrganizationSwitcher", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDOrganizationSwitcher; }
+  get: function () { return chunk223MPEBU_cjs.FFIDOrganizationSwitcher; }
 });
 Object.defineProperty(exports, "FFIDSubscriptionBadge", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDSubscriptionBadge; }
+  get: function () { return chunk223MPEBU_cjs.FFIDSubscriptionBadge; }
 });
 Object.defineProperty(exports, "FFIDUserMenu", {
   enumerable: true,
-  get: function () { return chunk5MO7G2JW_cjs.FFIDUserMenu; }
+  get: function () { return chunk223MPEBU_cjs.FFIDUserMenu; }
 });

package/dist/components/index.js

@@ -1 +1 @@
-export { FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDSubscriptionBadge, FFIDUserMenu } from '../chunk-35UOD62N.js';
+export { FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDSubscriptionBadge, FFIDUserMenu } from '../chunk-YOJJ433H.js';

package/dist/consent/index.cjs

@@ -0,0 +1,242 @@
+'use strict';
+
+var chunkIIC2LBD2_cjs = require('../chunk-IIC2LBD2.cjs');
+
+
+
+Object.defineProperty(exports, "ALL_DENIED_EXCEPT_NECESSARY", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.ALL_DENIED_EXCEPT_NECESSARY; }
+});
+Object.defineProperty(exports, "CONSENT_COOKIE_MAX_AGE_SEC", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.CONSENT_COOKIE_MAX_AGE_SEC; }
+});
+Object.defineProperty(exports, "CONSENT_COOKIE_NAME", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.CONSENT_COOKIE_NAME; }
+});
+Object.defineProperty(exports, "CONSENT_SESSION_STORAGE_KEY", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.CONSENT_SESSION_STORAGE_KEY; }
+});
+Object.defineProperty(exports, "COOKIE_VERSION", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.COOKIE_VERSION; }
+});
+Object.defineProperty(exports, "DEFAULT_CONSENT_ERROR_MESSAGES", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.DEFAULT_CONSENT_ERROR_MESSAGES; }
+});
+Object.defineProperty(exports, "DEFAULT_MERGE_WARNING_MESSAGES", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.DEFAULT_MERGE_WARNING_MESSAGES; }
+});
+Object.defineProperty(exports, "DEVICE_ID_LOCAL_STORAGE_KEY", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.DEVICE_ID_LOCAL_STORAGE_KEY; }
+});
+Object.defineProperty(exports, "DEVICE_ID_SESSION_STORAGE_KEY", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.DEVICE_ID_SESSION_STORAGE_KEY; }
+});
+Object.defineProperty(exports, "DeviceIdSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.DeviceIdSchema; }
+});
+Object.defineProperty(exports, "FFIDAnalyticsProvider", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDAnalyticsProvider; }
+});
+Object.defineProperty(exports, "FFIDConsentCategoriesSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentCategoriesSchema; }
+});
+Object.defineProperty(exports, "FFIDConsentCategoryCodeSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentCategoryCodeSchema; }
+});
+Object.defineProperty(exports, "FFIDConsentCategoryMetadataSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentCategoryMetadataSchema; }
+});
+Object.defineProperty(exports, "FFIDConsentContext", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentContext; }
+});
+Object.defineProperty(exports, "FFIDConsentError", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentError; }
+});
+Object.defineProperty(exports, "FFIDConsentMergeStrategySchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentMergeStrategySchema; }
+});
+Object.defineProperty(exports, "FFIDConsentMergeWarningSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentMergeWarningSchema; }
+});
+Object.defineProperty(exports, "FFIDConsentSourceSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentSourceSchema; }
+});
+Object.defineProperty(exports, "FFIDConsentStateSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentStateSchema; }
+});
+Object.defineProperty(exports, "FFIDConsentUpdateSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDConsentUpdateSchema; }
+});
+Object.defineProperty(exports, "FFIDCookieBanner", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDCookieBanner; }
+});
+Object.defineProperty(exports, "FFIDCookieLink", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDCookieLink; }
+});
+Object.defineProperty(exports, "FFIDCookiePolicySchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDCookiePolicySchema; }
+});
+Object.defineProperty(exports, "FFIDCookieSettings", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDCookieSettings; }
+});
+Object.defineProperty(exports, "FFIDInternalConsentSourceSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDInternalConsentSourceSchema; }
+});
+Object.defineProperty(exports, "FFIDPublicConsentSourceSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFIDPublicConsentSourceSchema; }
+});
+Object.defineProperty(exports, "FFID_CONSENT_ERROR_CODES", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFID_CONSENT_ERROR_CODES; }
+});
+Object.defineProperty(exports, "FFID_CONSENT_NOT_DECIDED_STATE", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.FFID_CONSENT_NOT_DECIDED_STATE; }
+});
+Object.defineProperty(exports, "GetCategoriesWireSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.GetCategoriesWireSchema; }
+});
+Object.defineProperty(exports, "GetConsentMeWireSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.GetConsentMeWireSchema; }
+});
+Object.defineProperty(exports, "GetDocumentWireSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.GetDocumentWireSchema; }
+});
+Object.defineProperty(exports, "PostConsentRequestSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.PostConsentRequestSchema; }
+});
+Object.defineProperty(exports, "PostConsentWireSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.PostConsentWireSchema; }
+});
+Object.defineProperty(exports, "PostSyncRequestSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.PostSyncRequestSchema; }
+});
+Object.defineProperty(exports, "PostSyncWireSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.PostSyncWireSchema; }
+});
+Object.defineProperty(exports, "PostWithdrawWireSchema", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.PostWithdrawWireSchema; }
+});
+Object.defineProperty(exports, "clearConsentSessionMirror", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.clearConsentSessionMirror; }
+});
+Object.defineProperty(exports, "clearDeviceId", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.clearDeviceId; }
+});
+Object.defineProperty(exports, "createConsentClient", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.createConsentClient; }
+});
+Object.defineProperty(exports, "createGtagBridge", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.createGtagBridge; }
+});
+Object.defineProperty(exports, "decodeConsentCookie", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.decodeConsentCookie; }
+});
+Object.defineProperty(exports, "deleteConsentCookie", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.deleteConsentCookie; }
+});
+Object.defineProperty(exports, "encodeConsentCookie", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.encodeConsentCookie; }
+});
+Object.defineProperty(exports, "generateDeviceId", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.generateDeviceId; }
+});
+Object.defineProperty(exports, "getOrCreateDeviceId", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.getOrCreateDeviceId; }
+});
+Object.defineProperty(exports, "isUuidV7", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.isUuidV7; }
+});
+Object.defineProperty(exports, "isValidDeviceId", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.isValidDeviceId; }
+});
+Object.defineProperty(exports, "mapCategoriesToGtagParams", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.mapCategoriesToGtagParams; }
+});
+Object.defineProperty(exports, "mapConsentWireToState", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.mapConsentWireToState; }
+});
+Object.defineProperty(exports, "mapMeWireToState", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.mapMeWireToState; }
+});
+Object.defineProperty(exports, "mapSyncWireToResult", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.mapSyncWireToResult; }
+});
+Object.defineProperty(exports, "mapWithdrawWireToState", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.mapWithdrawWireToState; }
+});
+Object.defineProperty(exports, "readConsentCookie", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.readConsentCookie; }
+});
+Object.defineProperty(exports, "readConsentSessionMirror", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.readConsentSessionMirror; }
+});
+Object.defineProperty(exports, "useFFIDConsent", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.useFFIDConsent; }
+});
+Object.defineProperty(exports, "useFFIDConsentPreferences", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.useFFIDConsentPreferences; }
+});
+Object.defineProperty(exports, "writeConsentCookie", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.writeConsentCookie; }
+});
+Object.defineProperty(exports, "writeConsentSessionMirror", {
+  enumerable: true,
+  get: function () { return chunkIIC2LBD2_cjs.writeConsentSessionMirror; }
+});

package/dist/consent/index.d.cts

@@ -0,0 +1,166 @@
+import { F as FFIDConsentResult, a as FFIDConsentState, b as FFIDConsentUpdate, c as FFIDConsentCategories, d as FFIDConsentSyncResult, e as FFIDConsentCategoryMetadata, f as FFIDCookiePolicy, P as PostConsentWire, G as GetConsentMeWire, g as PostSyncWire, h as PostWithdrawWire } from '../FFIDCookieLink-VYI2cSAB.cjs';
+export { A as ALL_DENIED_EXCEPT_NECESSARY, C as CONSENT_COOKIE_MAX_AGE_SEC, i as CONSENT_COOKIE_NAME, j as CONSENT_SESSION_STORAGE_KEY, k as COOKIE_VERSION, D as DEFAULT_CONSENT_ERROR_MESSAGES, l as DEFAULT_MERGE_WARNING_MESSAGES, m as DeviceIdSchema, n as FFIDAnalyticsProvider, o as FFIDAnalyticsProviderProps, p as FFIDConsentCategoriesSchema, q as FFIDConsentCategoryCode, r as FFIDConsentCategoryCodeSchema, s as FFIDConsentCategoryMetadataSchema, t as FFIDConsentContext, u as FFIDConsentContextValue, v as FFIDConsentError, w as FFIDConsentErrorCode, x as FFIDConsentMergeStrategy, y as FFIDConsentMergeStrategySchema, z as FFIDConsentMergeWarning, B as FFIDConsentMergeWarningSchema, E as FFIDConsentSource, H as FFIDConsentSourceSchema, I as FFIDConsentStateSchema, J as FFIDConsentUpdateSchema, K as FFIDCookieBanner, L as FFIDCookieBannerClassNames, M as FFIDCookieBannerProps, N as FFIDCookieLink, O as FFIDCookieLinkProps, Q as FFIDCookiePolicySchema, R as FFIDCookieSettings, S as FFIDCookieSettingsClassNames, T as FFIDCookieSettingsProps, U as FFIDInternalConsentSource, V as FFIDInternalConsentSourceSchema, W as FFIDPublicConsentSource, X as FFIDPublicConsentSourceSchema, Y as FFID_CONSENT_ERROR_CODES, Z as FFID_CONSENT_NOT_DECIDED_STATE, _ as GetCategoriesWire, $ as GetCategoriesWireSchema, a0 as GetConsentMeWireSchema, a1 as GetDocumentWire, a2 as GetDocumentWireSchema, a3 as GtagBridge, a4 as GtagBridgeOptions, a5 as PostConsentRequest, a6 as PostConsentRequestSchema, a7 as PostConsentWireSchema, a8 as PostSyncRequest, a9 as PostSyncRequestSchema, aa as PostSyncWireSchema, ab as PostWithdrawWireSchema, ac as UseFFIDConsentPreferencesReturn, ad as UseFFIDConsentReturn, ae as clearConsentSessionMirror, af as createGtagBridge, ag as decodeConsentCookie, ah as deleteConsentCookie, ai as encodeConsentCookie, aj as mapCategoriesToGtagParams, ak as readConsentCookie, al as readConsentSessionMirror, am as useFFIDConsent, an as useFFIDConsentPreferences, ao as writeConsentCookie, ap as writeConsentSessionMirror } from '../FFIDCookieLink-VYI2cSAB.cjs';
+import 'react';
+import 'zod';
+
+/**
+ * Cookie Consent — Device ID generation and persistence.
+ *
+ * Spec §5.3 / §6.5:
+ *   - 36-char UUIDv7 (time-ordered) stored in `localStorage:ffid_device_id`
+ *   - sessionStorage ephemeral fallback when localStorage is unavailable
+ *     (Safari Private Browsing, ITP cookie partition edge cases, etc.)
+ *   - Server validates against `DeviceIdSchema` (UUIDv4 or UUIDv7 accepted).
+ *
+ * UUIDv7 layout (RFC 9562):
+ *   - 48 bits: unix milliseconds (big-endian)
+ *   - 4 bits: version (0b0111)
+ *   - 12 bits: random
+ *   - 2 bits: variant (0b10)
+ *   - 62 bits: random
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §5.3, §6.5
+ */
+declare const DEVICE_ID_LOCAL_STORAGE_KEY = "ffid_device_id";
+declare const DEVICE_ID_SESSION_STORAGE_KEY = "ffid_device_id_ephemeral";
+/**
+ * Generate a UUIDv7 string. Falls back to crypto.randomUUID() (v4) if
+ * `crypto.getRandomValues` is unavailable.
+ */
+declare function generateDeviceId(): string;
+declare function isValidDeviceId(id: string): boolean;
+declare function isUuidV7(id: string): boolean;
+/**
+ * Return existing device ID or create + persist a new one.
+ *
+ * Persistence order: localStorage (preferred) → sessionStorage (ephemeral
+ * fallback). If neither is available the ID is still returned but not
+ * persisted; the caller can pass it in headers but each call will get a fresh
+ * value (acceptable degradation per spec §5.3).
+ *
+ * Falling through to ephemeral triggers a one-time `console.warn` so the
+ * operator can debug Safari Private Browsing / quota / ITP cases without
+ * silently breaking the shared-device merge UX.
+ */
+declare function getOrCreateDeviceId(): string;
+/** Clear all stored device IDs (used by full withdrawal flows + tests). */
+declare function clearDeviceId(): void;
+
+/**
+ * Cookie Consent — FFID API client (6 endpoints, Zod-validated).
+ *
+ * All responses are safe-parsed against `*WireSchema`. Parse failures or
+ * network errors are mapped to `FFIDConsentError` so consumers receive a
+ * uniform error surface via `Result<T>` returns.
+ *
+ * **HTTP 429 auto-retry** (spec §5.6): one transparent retry with
+ * `Retry-After + ±20% jitter`. On the second 429 (or any other error) the
+ * mapped `FFIDConsentError` surfaces to `Result.error`.
+ *
+ * Auth:
+ *   - `X-Service-Api-Key`: required for all endpoints (spec §5.2).
+ *   - `X-FFID-Device-Id`: required for write paths (`/consent`, `/sync`,
+ *     `/withdraw`) and recommended for reads.
+ *   - `Authorization: Bearer <jwt>`: required only for `/sync`; optional for
+ *     other endpoints. When present, server links the row to the user_id.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §5 + §8
+ */
+
+interface ConsentClientOptions {
+    /** FFID API base URL, e.g., `https://id.feelflow.net`. */
+    baseUrl: string;
+    /**
+     * Service API key that scopes this client to a registered FFID service.
+     * Surfaced through the `X-Service-Api-Key` header on every request.
+     */
+    serviceApiKey: string;
+    /** Resolves the current Bearer token, or null when the user is logged out. */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /**
+     * Resolves the device ID (UUIDv7). MUST return a non-empty string; the
+     * SDK throws `auth_failure` if this returns empty (state-not-ready guard).
+     */
+    getDeviceId: () => string;
+    /**
+     * Optional fetch implementation override. Defaults to global `fetch`.
+     * Useful for SSR contexts and tests.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional language code for `/categories` and `/document` (defaults to 'ja').
+     * The server falls back to JA when EN content is missing.
+     */
+    defaultLang?: 'ja' | 'en';
+    /**
+     * Maximum number of auto-retries on HTTP 429 (default: 1, per spec §5.6).
+     * Set to 0 to disable.
+     */
+    maxAutoRetry429?: number;
+}
+interface FFIDConsentClient {
+    /** `GET /api/v1/ext/consent/me` */
+    getMe(signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentState>>;
+    /** `POST /api/v1/ext/consent` (banner / preference_center submit) */
+    submit(categories: Required<FFIDConsentUpdate>, source: 'banner' | 'preference_center', cookiePolicyVersion: string, signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentState>>;
+    /** `POST /api/v1/ext/consent/sync` */
+    sync(localConsent: (FFIDConsentCategories & {
+        cookiePolicyVersion: string;
+    }) | null, signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentSyncResult>>;
+    /** `POST /api/v1/ext/consent/withdraw` */
+    withdraw(signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentState>>;
+    /** `GET /api/v1/ext/consent/categories` */
+    getCategories(lang?: 'ja' | 'en', signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentCategoryMetadata[]>>;
+    /** `GET /api/v1/ext/consent/document` */
+    getDocument(lang?: 'ja' | 'en', signal?: AbortSignal): Promise<FFIDConsentResult<FFIDCookiePolicy>>;
+}
+/**
+ * Factory function returning a configured client. Idiomatic to the rest of
+ * the SDK (see `createFFIDClient`, `createKVCacheAdapter` etc.) — avoids
+ * exposing a class so the API surface stays narrow.
+ */
+declare function createConsentClient(opts: ConsentClientOptions): FFIDConsentClient;
+
+/**
+ * Cookie Consent — wire ↔ consumer type mappers.
+ *
+ * Routes return snake_case envelopes ("wire" types); React consumers expect
+ * the camelCase discriminated union (`FFIDConsentState`, see spec §6.4).
+ * Map at the SDK boundary so consumer code never touches snake_case keys.
+ */
+
+/**
+ * Convert `GET /me` wire response to the SDK consumer's discriminated union.
+ *
+ * When `consent` is null the server hasn't recorded any decision yet — emit
+ * the "no decision" branch with `default_state` (or hard-coded default-deny)
+ * as the categories.
+ *
+ * When `consent` is non-null but the server doesn't surface the original
+ * source (spec §6.4 wire schema omits `source` on `/me`), we report
+ * `persisted_unknown` to signal "decision is on file but its origin label is
+ * not available" — distinct from `sdk_default` which means "no decision yet".
+ */
+declare function mapMeWireToState(wire: GetConsentMeWire): FFIDConsentState;
+/**
+ * Convert a `POST /consent` response into a consumer state. The submission
+ * `source` is supplied by the caller because the wire envelope echoes the
+ * stored row but not the original `source` field.
+ */
+declare function mapConsentWireToState(wire: PostConsentWire, source: 'banner' | 'preference_center'): FFIDConsentState;
+/**
+ * Convert a `POST /withdraw` response into a consumer state. Withdrawal sets
+ * all optional categories to false (DB CHECK invariant per spec §4.1).
+ */
+declare function mapWithdrawWireToState(wire: PostWithdrawWire): FFIDConsentState;
+/**
+ * Convert a `POST /sync` response into the structured sync result. SDK
+ * consumers should always read `warning` and surface non-null values to the
+ * user per spec §5.3 (silent merge forbidden).
+ *
+ * `wire.merge_strategy` and `wire.warning` are already typed via Zod-derived
+ * `PostSyncWire`, so no `as` cast is needed at this boundary.
+ */
+declare function mapSyncWireToResult(wire: PostSyncWire): FFIDConsentSyncResult;
+
+export { type ConsentClientOptions, DEVICE_ID_LOCAL_STORAGE_KEY, DEVICE_ID_SESSION_STORAGE_KEY, FFIDConsentCategories, FFIDConsentCategoryMetadata, type FFIDConsentClient, FFIDConsentResult, FFIDConsentState, FFIDConsentSyncResult, FFIDConsentUpdate, FFIDCookiePolicy, GetConsentMeWire, PostConsentWire, PostSyncWire, PostWithdrawWire, clearDeviceId, createConsentClient, generateDeviceId, getOrCreateDeviceId, isUuidV7, isValidDeviceId, mapConsentWireToState, mapMeWireToState, mapSyncWireToResult, mapWithdrawWireToState };

package/dist/consent/index.d.ts

@@ -0,0 +1,166 @@
+import { F as FFIDConsentResult, a as FFIDConsentState, b as FFIDConsentUpdate, c as FFIDConsentCategories, d as FFIDConsentSyncResult, e as FFIDConsentCategoryMetadata, f as FFIDCookiePolicy, P as PostConsentWire, G as GetConsentMeWire, g as PostSyncWire, h as PostWithdrawWire } from '../FFIDCookieLink-VYI2cSAB.js';
+export { A as ALL_DENIED_EXCEPT_NECESSARY, C as CONSENT_COOKIE_MAX_AGE_SEC, i as CONSENT_COOKIE_NAME, j as CONSENT_SESSION_STORAGE_KEY, k as COOKIE_VERSION, D as DEFAULT_CONSENT_ERROR_MESSAGES, l as DEFAULT_MERGE_WARNING_MESSAGES, m as DeviceIdSchema, n as FFIDAnalyticsProvider, o as FFIDAnalyticsProviderProps, p as FFIDConsentCategoriesSchema, q as FFIDConsentCategoryCode, r as FFIDConsentCategoryCodeSchema, s as FFIDConsentCategoryMetadataSchema, t as FFIDConsentContext, u as FFIDConsentContextValue, v as FFIDConsentError, w as FFIDConsentErrorCode, x as FFIDConsentMergeStrategy, y as FFIDConsentMergeStrategySchema, z as FFIDConsentMergeWarning, B as FFIDConsentMergeWarningSchema, E as FFIDConsentSource, H as FFIDConsentSourceSchema, I as FFIDConsentStateSchema, J as FFIDConsentUpdateSchema, K as FFIDCookieBanner, L as FFIDCookieBannerClassNames, M as FFIDCookieBannerProps, N as FFIDCookieLink, O as FFIDCookieLinkProps, Q as FFIDCookiePolicySchema, R as FFIDCookieSettings, S as FFIDCookieSettingsClassNames, T as FFIDCookieSettingsProps, U as FFIDInternalConsentSource, V as FFIDInternalConsentSourceSchema, W as FFIDPublicConsentSource, X as FFIDPublicConsentSourceSchema, Y as FFID_CONSENT_ERROR_CODES, Z as FFID_CONSENT_NOT_DECIDED_STATE, _ as GetCategoriesWire, $ as GetCategoriesWireSchema, a0 as GetConsentMeWireSchema, a1 as GetDocumentWire, a2 as GetDocumentWireSchema, a3 as GtagBridge, a4 as GtagBridgeOptions, a5 as PostConsentRequest, a6 as PostConsentRequestSchema, a7 as PostConsentWireSchema, a8 as PostSyncRequest, a9 as PostSyncRequestSchema, aa as PostSyncWireSchema, ab as PostWithdrawWireSchema, ac as UseFFIDConsentPreferencesReturn, ad as UseFFIDConsentReturn, ae as clearConsentSessionMirror, af as createGtagBridge, ag as decodeConsentCookie, ah as deleteConsentCookie, ai as encodeConsentCookie, aj as mapCategoriesToGtagParams, ak as readConsentCookie, al as readConsentSessionMirror, am as useFFIDConsent, an as useFFIDConsentPreferences, ao as writeConsentCookie, ap as writeConsentSessionMirror } from '../FFIDCookieLink-VYI2cSAB.js';
+import 'react';
+import 'zod';
+
+/**
+ * Cookie Consent — Device ID generation and persistence.
+ *
+ * Spec §5.3 / §6.5:
+ *   - 36-char UUIDv7 (time-ordered) stored in `localStorage:ffid_device_id`
+ *   - sessionStorage ephemeral fallback when localStorage is unavailable
+ *     (Safari Private Browsing, ITP cookie partition edge cases, etc.)
+ *   - Server validates against `DeviceIdSchema` (UUIDv4 or UUIDv7 accepted).
+ *
+ * UUIDv7 layout (RFC 9562):
+ *   - 48 bits: unix milliseconds (big-endian)
+ *   - 4 bits: version (0b0111)
+ *   - 12 bits: random
+ *   - 2 bits: variant (0b10)
+ *   - 62 bits: random
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §5.3, §6.5
+ */
+declare const DEVICE_ID_LOCAL_STORAGE_KEY = "ffid_device_id";
+declare const DEVICE_ID_SESSION_STORAGE_KEY = "ffid_device_id_ephemeral";
+/**
+ * Generate a UUIDv7 string. Falls back to crypto.randomUUID() (v4) if
+ * `crypto.getRandomValues` is unavailable.
+ */
+declare function generateDeviceId(): string;
+declare function isValidDeviceId(id: string): boolean;
+declare function isUuidV7(id: string): boolean;
+/**
+ * Return existing device ID or create + persist a new one.
+ *
+ * Persistence order: localStorage (preferred) → sessionStorage (ephemeral
+ * fallback). If neither is available the ID is still returned but not
+ * persisted; the caller can pass it in headers but each call will get a fresh
+ * value (acceptable degradation per spec §5.3).
+ *
+ * Falling through to ephemeral triggers a one-time `console.warn` so the
+ * operator can debug Safari Private Browsing / quota / ITP cases without
+ * silently breaking the shared-device merge UX.
+ */
+declare function getOrCreateDeviceId(): string;
+/** Clear all stored device IDs (used by full withdrawal flows + tests). */
+declare function clearDeviceId(): void;
+
+/**
+ * Cookie Consent — FFID API client (6 endpoints, Zod-validated).
+ *
+ * All responses are safe-parsed against `*WireSchema`. Parse failures or
+ * network errors are mapped to `FFIDConsentError` so consumers receive a
+ * uniform error surface via `Result<T>` returns.
+ *
+ * **HTTP 429 auto-retry** (spec §5.6): one transparent retry with
+ * `Retry-After + ±20% jitter`. On the second 429 (or any other error) the
+ * mapped `FFIDConsentError` surfaces to `Result.error`.
+ *
+ * Auth:
+ *   - `X-Service-Api-Key`: required for all endpoints (spec §5.2).
+ *   - `X-FFID-Device-Id`: required for write paths (`/consent`, `/sync`,
+ *     `/withdraw`) and recommended for reads.
+ *   - `Authorization: Bearer <jwt>`: required only for `/sync`; optional for
+ *     other endpoints. When present, server links the row to the user_id.
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §5 + §8
+ */
+
+interface ConsentClientOptions {
+    /** FFID API base URL, e.g., `https://id.feelflow.net`. */
+    baseUrl: string;
+    /**
+     * Service API key that scopes this client to a registered FFID service.
+     * Surfaced through the `X-Service-Api-Key` header on every request.
+     */
+    serviceApiKey: string;
+    /** Resolves the current Bearer token, or null when the user is logged out. */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /**
+     * Resolves the device ID (UUIDv7). MUST return a non-empty string; the
+     * SDK throws `auth_failure` if this returns empty (state-not-ready guard).
+     */
+    getDeviceId: () => string;
+    /**
+     * Optional fetch implementation override. Defaults to global `fetch`.
+     * Useful for SSR contexts and tests.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional language code for `/categories` and `/document` (defaults to 'ja').
+     * The server falls back to JA when EN content is missing.
+     */
+    defaultLang?: 'ja' | 'en';
+    /**
+     * Maximum number of auto-retries on HTTP 429 (default: 1, per spec §5.6).
+     * Set to 0 to disable.
+     */
+    maxAutoRetry429?: number;
+}
+interface FFIDConsentClient {
+    /** `GET /api/v1/ext/consent/me` */
+    getMe(signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentState>>;
+    /** `POST /api/v1/ext/consent` (banner / preference_center submit) */
+    submit(categories: Required<FFIDConsentUpdate>, source: 'banner' | 'preference_center', cookiePolicyVersion: string, signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentState>>;
+    /** `POST /api/v1/ext/consent/sync` */
+    sync(localConsent: (FFIDConsentCategories & {
+        cookiePolicyVersion: string;
+    }) | null, signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentSyncResult>>;
+    /** `POST /api/v1/ext/consent/withdraw` */
+    withdraw(signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentState>>;
+    /** `GET /api/v1/ext/consent/categories` */
+    getCategories(lang?: 'ja' | 'en', signal?: AbortSignal): Promise<FFIDConsentResult<FFIDConsentCategoryMetadata[]>>;
+    /** `GET /api/v1/ext/consent/document` */
+    getDocument(lang?: 'ja' | 'en', signal?: AbortSignal): Promise<FFIDConsentResult<FFIDCookiePolicy>>;
+}
+/**
+ * Factory function returning a configured client. Idiomatic to the rest of
+ * the SDK (see `createFFIDClient`, `createKVCacheAdapter` etc.) — avoids
+ * exposing a class so the API surface stays narrow.
+ */
+declare function createConsentClient(opts: ConsentClientOptions): FFIDConsentClient;
+
+/**
+ * Cookie Consent — wire ↔ consumer type mappers.
+ *
+ * Routes return snake_case envelopes ("wire" types); React consumers expect
+ * the camelCase discriminated union (`FFIDConsentState`, see spec §6.4).
+ * Map at the SDK boundary so consumer code never touches snake_case keys.
+ */
+
+/**
+ * Convert `GET /me` wire response to the SDK consumer's discriminated union.
+ *
+ * When `consent` is null the server hasn't recorded any decision yet — emit
+ * the "no decision" branch with `default_state` (or hard-coded default-deny)
+ * as the categories.
+ *
+ * When `consent` is non-null but the server doesn't surface the original
+ * source (spec §6.4 wire schema omits `source` on `/me`), we report
+ * `persisted_unknown` to signal "decision is on file but its origin label is
+ * not available" — distinct from `sdk_default` which means "no decision yet".
+ */
+declare function mapMeWireToState(wire: GetConsentMeWire): FFIDConsentState;
+/**
+ * Convert a `POST /consent` response into a consumer state. The submission
+ * `source` is supplied by the caller because the wire envelope echoes the
+ * stored row but not the original `source` field.
+ */
+declare function mapConsentWireToState(wire: PostConsentWire, source: 'banner' | 'preference_center'): FFIDConsentState;
+/**
+ * Convert a `POST /withdraw` response into a consumer state. Withdrawal sets
+ * all optional categories to false (DB CHECK invariant per spec §4.1).
+ */
+declare function mapWithdrawWireToState(wire: PostWithdrawWire): FFIDConsentState;
+/**
+ * Convert a `POST /sync` response into the structured sync result. SDK
+ * consumers should always read `warning` and surface non-null values to the
+ * user per spec §5.3 (silent merge forbidden).
+ *
+ * `wire.merge_strategy` and `wire.warning` are already typed via Zod-derived
+ * `PostSyncWire`, so no `as` cast is needed at this boundary.
+ */
+declare function mapSyncWireToResult(wire: PostSyncWire): FFIDConsentSyncResult;
+
+export { type ConsentClientOptions, DEVICE_ID_LOCAL_STORAGE_KEY, DEVICE_ID_SESSION_STORAGE_KEY, FFIDConsentCategories, FFIDConsentCategoryMetadata, type FFIDConsentClient, FFIDConsentResult, FFIDConsentState, FFIDConsentSyncResult, FFIDConsentUpdate, FFIDCookiePolicy, GetConsentMeWire, PostConsentWire, PostSyncWire, PostWithdrawWire, clearDeviceId, createConsentClient, generateDeviceId, getOrCreateDeviceId, isUuidV7, isValidDeviceId, mapConsentWireToState, mapMeWireToState, mapSyncWireToResult, mapWithdrawWireToState };

package/dist/consent/index.js

@@ -0,0 +1 @@
+export { ALL_DENIED_EXCEPT_NECESSARY, CONSENT_COOKIE_MAX_AGE_SEC, CONSENT_COOKIE_NAME, CONSENT_SESSION_STORAGE_KEY, COOKIE_VERSION, DEFAULT_CONSENT_ERROR_MESSAGES, DEFAULT_MERGE_WARNING_MESSAGES, DEVICE_ID_LOCAL_STORAGE_KEY, DEVICE_ID_SESSION_STORAGE_KEY, DeviceIdSchema, FFIDAnalyticsProvider, FFIDConsentCategoriesSchema, FFIDConsentCategoryCodeSchema, FFIDConsentCategoryMetadataSchema, FFIDConsentContext, FFIDConsentError, FFIDConsentMergeStrategySchema, FFIDConsentMergeWarningSchema, FFIDConsentSourceSchema, FFIDConsentStateSchema, FFIDConsentUpdateSchema, FFIDCookieBanner, FFIDCookieLink, FFIDCookiePolicySchema, FFIDCookieSettings, FFIDInternalConsentSourceSchema, FFIDPublicConsentSourceSchema, FFID_CONSENT_ERROR_CODES, FFID_CONSENT_NOT_DECIDED_STATE, GetCategoriesWireSchema, GetConsentMeWireSchema, GetDocumentWireSchema, PostConsentRequestSchema, PostConsentWireSchema, PostSyncRequestSchema, PostSyncWireSchema, PostWithdrawWireSchema, clearConsentSessionMirror, clearDeviceId, createConsentClient, createGtagBridge, decodeConsentCookie, deleteConsentCookie, encodeConsentCookie, generateDeviceId, getOrCreateDeviceId, isUuidV7, isValidDeviceId, mapCategoriesToGtagParams, mapConsentWireToState, mapMeWireToState, mapSyncWireToResult, mapWithdrawWireToState, readConsentCookie, readConsentSessionMirror, useFFIDConsent, useFFIDConsentPreferences, writeConsentCookie, writeConsentSessionMirror } from '../chunk-VSHBWZXK.js';