@feelflow/ffid-sdk 4.3.0 → 5.0.1

package/dist/server/index.d.ts

@@ -1,6 +1,7 @@
 import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-BaStAONh.js';
 export { f as FFIDAddMemberParams, g as FFIDAddMemberRequest, h as FFIDAddMemberResponse, i as FFIDAssignableMemberRole, j as FFIDCacheConfig, k as FFIDClient, l as FFIDConfig, m as FFIDListMembersResponse, n as FFIDMemberRole, o as FFIDOrganization, p as FFIDOrganizationMember, q as FFIDOtpSendResponse, r as FFIDOtpVerifyResponse, s as FFIDPasswordResetConfirmResponse, t as FFIDPasswordResetResponse, u as FFIDPasswordResetVerifyResponse, v as FFIDProfileCallOptions, w as FFIDRemoveMemberResponse, x as FFIDResetSessionResponse, y as FFIDSubscription, z as FFIDUpdateMemberRoleResponse, A as FFIDUpdateUserProfileRequest, B as FFIDUser, C as FFIDUserProfile, T as TokenData, D as TokenStore, E as createFFIDClient, G as createTokenStore } from '../ffid-client-BaStAONh.js';
 export { D as DEFAULT_API_BASE_URL, a as DEFAULT_OAUTH_SCOPES } from '../constants-D61jqRIO.js';
+import { z } from 'zod';
 import '../types-5g_Bg6Ey.js';
 
 /** Token verification - verifyAccessToken() implementation */
@@ -57,4 +58,151 @@ interface KVNamespaceLike {
  */
 declare function createKVCacheAdapter(kv: KVNamespaceLike): FFIDCacheAdapter;
 
-export { FFIDCacheAdapter, FFIDOAuthUserInfo, FFIDVerifyAccessTokenOptions, type KVNamespaceLike, createKVCacheAdapter, createMemoryCacheAdapter, createVerifyAccessToken };
+/**
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * Server-side cookie consent helpers for RSC / Server Actions.
+ *
+ * These are intentionally cookie-only (no DB / API calls) so they remain
+ * cheap for every request. The semantics mirror `readConsentCookie()` on the
+ * client side — fail-safe to `ALL_DENIED_EXCEPT_NECESSARY` on any error.
+ *
+ * @example
+ * ```tsx
+ * // app/page.tsx (Next.js App Router)
+ * import { cookies } from 'next/headers'
+ * import { getFFIDConsentFromCookies } from '@feelflow/ffid-sdk/server'
+ *
+ * export default async function Page() {
+ *   const cookieStore = await cookies()
+ *   const consent = getFFIDConsentFromCookies(cookieStore)
+ *   if (consent.analytics) { ... }
+ * }
+ * ```
+ *
+ * Refs: docs/02-design/COOKIE_CONSENT.md §6.6
+ */
+
+/**
+ * Structural type that matches both `next/headers` `cookies()` return value
+ * (`RequestCookies`) and any custom store with a `get(name)` method that
+ * returns `{ value }` or `undefined`.
+ */
+interface FFIDCookieStoreLike {
+    get(name: string): {
+        value: string;
+    } | undefined;
+}
+/**
+ * Read the FFID consent cookie from a Next.js `cookies()` store (or any
+ * compatible object) and decode it.
+ *
+ * Returns `ALL_DENIED_EXCEPT_NECESSARY` when the cookie is absent,
+ * malformed, or the store is undefined — `decodeConsentCookie` never throws.
+ */
+declare function getFFIDConsentFromCookies(store: FFIDCookieStoreLike | undefined | null): FFIDConsentCategories;
+/**
+ * Parse a raw cookie header string (`document.cookie` shape: "k=v; k2=v2").
+ * Useful when working with raw Request headers in Edge runtimes that don't
+ * expose a `cookies()` API.
+ */
+declare function getFFIDConsentFromCookieHeader(cookieHeader: string | null | undefined): FFIDConsentCategories;
+
+/**
+ * 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";
+
+export { ALL_DENIED_EXCEPT_NECESSARY, CONSENT_COOKIE_NAME, COOKIE_VERSION, FFIDCacheAdapter, type FFIDConsentCategories, type FFIDConsentCategoryCode, type FFIDCookieStoreLike, FFIDOAuthUserInfo, FFIDVerifyAccessTokenOptions, type KVNamespaceLike, createKVCacheAdapter, createMemoryCacheAdapter, createVerifyAccessToken, decodeConsentCookie, encodeConsentCookie, getFFIDConsentFromCookieHeader, getFFIDConsentFromCookies };

package/dist/server/index.js

@@ -834,7 +834,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() {
@@ -2759,4 +2759,95 @@ function createKVCacheAdapter(kv) {
   };
 }
 
-export { createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken };
+// src/consent/storage/encode.ts
+var COOKIE_VERSION = "v1";
+var ALL_DENIED_EXCEPT_NECESSARY = {
+  necessary: true,
+  functional: false,
+  analytics: false,
+  marketing: false
+};
+var CATEGORY_LETTERS = {
+  n: "necessary",
+  f: "functional",
+  a: "analytics",
+  m: "marketing"
+};
+var ORDERED_LETTERS = ["n", "f", "a", "m"];
+function encodeConsentCookie(cats) {
+  const parts = ORDERED_LETTERS.map((letter) => {
+    const key = CATEGORY_LETTERS[letter];
+    return `${letter}${cats[key] ? "+" : "-"}`;
+  });
+  return `${COOKIE_VERSION}:${parts.join(",")}`;
+}
+function decodeConsentCookie(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  const colonIdx = raw.indexOf(":");
+  if (colonIdx === -1) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  const version = raw.slice(0, colonIdx);
+  if (version !== COOKIE_VERSION) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  const body = raw.slice(colonIdx + 1);
+  if (body.length === 0) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  const tokens = body.split(",");
+  if (tokens.length !== ORDERED_LETTERS.length) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const result = {};
+  for (const token of tokens) {
+    if (token.length !== 2) {
+      return { ...ALL_DENIED_EXCEPT_NECESSARY };
+    }
+    const letter = token[0];
+    const value = token[1];
+    if (!CATEGORY_LETTERS[letter] || value !== "+" && value !== "-") {
+      return { ...ALL_DENIED_EXCEPT_NECESSARY };
+    }
+    if (seen.has(letter)) {
+      return { ...ALL_DENIED_EXCEPT_NECESSARY };
+    }
+    seen.add(letter);
+    const key = CATEGORY_LETTERS[letter];
+    result[key] = value === "+";
+  }
+  if (result.necessary !== true) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  return {
+    necessary: true,
+    functional: result.functional ?? false,
+    analytics: result.analytics ?? false,
+    marketing: result.marketing ?? false
+  };
+}
+
+// src/consent/storage/cookie.ts
+var CONSENT_COOKIE_NAME = "ffid_consent";
+
+// src/server/cookie-consent.ts
+function getFFIDConsentFromCookies(store) {
+  if (!store) return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  const entry = store.get(CONSENT_COOKIE_NAME);
+  if (!entry) return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  return decodeConsentCookie(entry.value);
+}
+function getFFIDConsentFromCookieHeader(cookieHeader) {
+  if (typeof cookieHeader !== "string" || cookieHeader.length === 0) {
+    return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  }
+  const raw = cookieHeader.split(";").map((c) => c.trim()).find((c) => c.startsWith(`${CONSENT_COOKIE_NAME}=`));
+  if (!raw) return { ...ALL_DENIED_EXCEPT_NECESSARY };
+  const value = raw.slice(CONSENT_COOKIE_NAME.length + 1);
+  return decodeConsentCookie(decodeURIComponent(value));
+}
+
+export { ALL_DENIED_EXCEPT_NECESSARY, CONSENT_COOKIE_NAME, COOKIE_VERSION, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken, decodeConsentCookie, encodeConsentCookie, getFFIDConsentFromCookieHeader, getFFIDConsentFromCookies };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelflow/ffid-sdk",
-  "version": "4.3.0",
+  "version": "5.0.1",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",
@@ -36,6 +36,11 @@
       "import": "./dist/components/index.js",
       "require": "./dist/components/index.cjs"
     },
+    "./consent": {
+      "types": "./dist/consent/index.d.ts",
+      "import": "./dist/consent/index.js",
+      "require": "./dist/consent/index.cjs"
+    },
     "./legal": {
       "types": "./dist/legal/index.d.ts",
       "import": "./dist/legal/index.js",
@@ -85,7 +90,8 @@
     "sdk:publish": "./scripts/publish.sh"
   },
   "dependencies": {
-    "jose": "^6.0.0"
+    "jose": "^6.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",