@businessdash/sdk 0.9.60 → 0.9.80

package/src/react.tsx

@@ -1,3 +1,28 @@
+"use client";
+
+/**
+ * Every export in this file is browser-only. The components hold state and
+ * subscribe to stores; the four programmatic helpers (`signIn`, `signUp`,
+ * `signOut`, `requestPasswordReset`) each bail out on
+ * `typeof window === "undefined"` because they navigate. Nothing here is meant
+ * to execute during a server render.
+ *
+ * WHY THE DIRECTIVE IS HERE
+ *
+ * Without it, a React Server Components framework treats this module as server
+ * code by default, and importing `<BiabForm>` into a page throws "you're
+ * importing a component that needs useState". The only way out is for every
+ * consumer to hand-write a `"use client"` wrapper per component — which is
+ * exactly what the Next App Router starter had to do, sixteen times, for
+ * components the SDK could have marked itself.
+ *
+ * `react-analytics.tsx` already carried this. `react.tsx` — the entry point
+ * that actually holds the components — did not.
+ *
+ * Bundlers that don't implement the directive treat it as a no-op string
+ * expression, so this is inert everywhere except RSC.
+ */
+
 import {
 	type CSSProperties,
 	createContext,
@@ -11,7 +36,22 @@ import {
 	useState,
 	useSyncExternalStore,
 } from "react";
-
+import {
+	createFollowersController,
+	createUserController,
+} from "./account-core/index.js";
+import {
+	buildAuthHref,
+	clearLocalFollow,
+	DEFAULT_AUTH_BASE_PATH,
+	followerStoreKey,
+	type LocalFollow,
+	readLocalFollow,
+	writeLocalFollow,
+} from "./auth-links.js";
+import { createBlogController } from "./blog-core/index.js";
+import { createChatController } from "./chat-core/index.js";
+import { createCheckoutController } from "./checkout-core/index.js";
 import { BiabDevClient } from "./client.js";
 import type {
 	BlogSessionInput,
@@ -37,6 +77,14 @@ import type {
 	StorefrontSessionInput,
 	StorefrontSessionResponse,
 } from "./contracts.js";
+import {
+	type BiabEmbedEvent,
+	DEFAULT_EMBED_SANDBOX,
+	DEFAULT_REFRESH_LEAD_MS,
+	type EmbedSessionState,
+	refreshDelayMs,
+	subscribeToEmbedMessages,
+} from "./embed-protocol.js";
 import {
 	type AutocompleteConfig,
 	type BiabFormsClient,
@@ -69,17 +117,25 @@ import {
 	unitsForCategory,
 } from "./forms-core/units.js";
 import { US_STATES } from "./forms-core/us-states.js";
+import { createMarketingController } from "./marketing-core/index.js";
+import { createPortalController } from "./portal-core/index.js";
 import type { FormFileValue, FormSchema, FormSubmitResult } from "./sdk.js";
 import { createBiabClient } from "./sdk.js";
-import { resolveSocialProfiles } from "./socials.js";
+import {
+	resolveSocialLinks,
+	SOCIAL_FALLBACK_GLYPH,
+	SOCIAL_LIST_STYLE,
+} from "./social-core/index.js";
+import { createStoreController } from "./store-core/index.js";
+import {
+	type CreateVerifyControllerOptions,
+	createVerifyController,
+} from "./verify-core/index.js";
 
 // ─── Shared session state machine ─────────────────────────────────────────
 
-type SessionState<T> =
-	| { status: "idle" }
-	| { status: "loading" }
-	| { status: "ready"; session: T }
-	| { status: "error"; error: Error };
+/** Alias kept so the many call sites below read unchanged. */
+type SessionState<T> = EmbedSessionState<T>;
 
 function useEmbedSession<T extends { url: string; expiresAt: string }>(
 	loader: (client: BiabDevClient) => Promise<T>,
@@ -89,7 +145,7 @@ function useEmbedSession<T extends { url: string; expiresAt: string }>(
 		refreshLeadMs?: number | undefined;
 	},
 ) {
-	const { apiKey, baseUrl, refreshLeadMs = 30_000 } = options;
+	const { apiKey, baseUrl, refreshLeadMs = DEFAULT_REFRESH_LEAD_MS } = options;
 	const client = useMemo(
 		() => new BiabDevClient({ apiKey, baseUrl }),
 		[apiKey, baseUrl],
@@ -119,9 +175,15 @@ function useEmbedSession<T extends { url: string; expiresAt: string }>(
 
 	useEffect(() => {
 		if (state.status !== "ready") return;
-		const expiresAt = Date.parse(state.session.expiresAt);
-		if (Number.isNaN(expiresAt)) return;
-		const delay = Math.max(1_000, expiresAt - Date.now() - refreshLeadMs);
+		// The schedule itself lives in `embed-protocol.ts` so both bindings
+		// re-mint at the same moment — an embed that expires in Solid but not in
+		// React would be a bug nobody thinks to look for.
+		const delay = refreshDelayMs(
+			state.session.expiresAt,
+			refreshLeadMs,
+			Date.now(),
+		);
+		if (delay === null) return;
 		const timer = setTimeout(() => {
 			void refresh();
 		}, delay);
@@ -133,50 +195,23 @@ function useEmbedSession<T extends { url: string; expiresAt: string }>(
 
 // ─── postMessage protocol ─────────────────────────────────────────────────
 
-export type BiabEmbedEvent =
-	| { type: "biab:ready"; surface: string }
-	| { type: "biab:cart:update"; count: number; subtotalCents: number }
-	| {
-			type: "biab:cart:checkout-requested";
-			lines: Array<{
-				productId: string;
-				variantId: string;
-				combinationKey?: string;
-				quantity: number;
-			}>;
-	  }
-	| {
-			type: "biab:checkout:success";
-			sessionId: string;
-			orderId?: string | null;
-	  }
-	| { type: "biab:checkout:cancel"; sessionId: string }
-	| { type: "biab:checkout:error"; message: string }
-	| { type: "biab:chatbot:user-message"; content: string }
-	| { type: "biab:chatbot:assistant-message"; content: string; model?: string }
-	| { type: "biab:chatbot:error"; message: string };
+/**
+ * Re-exported from `./embed-protocol.js`, where the type and the origin check
+ * that guards it live together. Kept exported here so existing
+ * `@businessdash/sdk/react` imports keep working.
+ */
+export type { BiabEmbedEvent } from "./embed-protocol.js";
 
 function useEmbedMessages(
 	iframeRef: React.RefObject<HTMLIFrameElement | null>,
 	handler: (event: BiabEmbedEvent) => void,
 ) {
-	useEffect(() => {
-		const onMessage = (e: MessageEvent) => {
-			if (!e.data || typeof e.data !== "object") return;
-			if ((e.data as { kind?: string }).kind !== "biab") return;
-			if (
-				iframeRef.current &&
-				e.source !== null &&
-				e.source !== iframeRef.current.contentWindow
-			)
-				return;
-			const { kind, ...rest } = e.data as { kind: string } & BiabEmbedEvent;
-			void kind;
-			handler(rest as BiabEmbedEvent);
-		};
-		window.addEventListener("message", onMessage);
-		return () => window.removeEventListener("message", onMessage);
-	}, [handler, iframeRef]);
+	// The listener, and the origin check inside it, live in
+	// `embed-protocol.ts` so the Solid binding enforces exactly the same rule.
+	useEffect(
+		() => subscribeToEmbedMessages(() => iframeRef.current, handler),
+		[handler, iframeRef],
+	);
 }
 
 // ─── Dashboard (existing) ─────────────────────────────────────────────────
@@ -286,7 +321,7 @@ export function Dashboard({
 	return (
 		<iframe
 			className={className}
-			sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
+			sandbox={DEFAULT_EMBED_SANDBOX}
 			src={state.session.url}
 			style={{ ...defaultIframeStyle, ...style }}
 			title={title}
@@ -353,9 +388,9 @@ function EmbedIframe<T extends { url: string }>({
 		);
 	}
 
-	const sandbox = `allow-scripts allow-forms allow-same-origin allow-popups${
-		extraSandbox ? ` ${extraSandbox}` : ""
-	}`;
+	const sandbox = extraSandbox
+		? `${DEFAULT_EMBED_SANDBOX} ${extraSandbox}`
+		: DEFAULT_EMBED_SANDBOX;
 
 	return (
 		<iframe
@@ -779,127 +814,100 @@ export function Chatbot({
  */
 export function useChatbot(options: { apiKey: string; baseUrl: string }) {
 	const { apiKey, baseUrl } = options;
-	const client = useMemo(
-		() => new BiabDevClient({ apiKey, baseUrl }),
+	const controller = useMemo(
+		() =>
+			createChatController({
+				client: new BiabDevClient({ apiKey, baseUrl }),
+			}),
 		[apiKey, baseUrl],
 	);
-	const [messages, setMessages] = useState<ChatbotMessage[]>([]);
-	const [isPending, setIsPending] = useState(false);
-	const [error, setError] = useState<Error | null>(null);
-	const [latestUiActions, setLatestUiActions] = useState<ChatbotUiAction[]>([]);
-	const [availability, setAvailability] = useState<ChatbotAvailability | null>(
-		null,
-	);
+	useEffect(() => () => controller.destroy(), [controller]);
 
-	const send = useCallback(
-		async (content: string): Promise<ChatbotChatResponse | null> => {
-			const trimmed = content.trim();
-			if (!trimmed) return null;
-			setError(null);
-			setIsPending(true);
-			const next: ChatbotMessage[] = [
-				...messages,
-				{ role: "user", content: trimmed },
-			];
-			setMessages(next);
-			try {
-				const input: ChatbotChatInput = { messages: next };
-				const reply = await client.chatbot.chat(input);
-				setMessages((prev) => [
-					...prev,
-					{ role: "assistant", content: reply.text },
-				]);
-				setLatestUiActions(reply.uiActions ?? []);
-				if (reply.availability) setAvailability(reply.availability);
-				return reply;
-			} catch (err) {
-				const e = err instanceof Error ? err : new Error("Chat failed");
-				setError(e);
-				return null;
-			} finally {
-				setIsPending(false);
-			}
-		},
-		[client, messages],
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
 	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
-	const reset = useCallback(() => {
-		setMessages([]);
-		setError(null);
-		setLatestUiActions([]);
-	}, []);
-
-	const getConfig = useCallback(
-		async (): Promise<ChatbotConfig> => client.chatbot.getConfig(),
-		[client],
+	const uploadFile = useCallback(
+		(args: { sessionId: string; file: File; uploaderEmail?: string | null }) =>
+			new BiabDevClient({ apiKey, baseUrl }).chatbot.uploadFile(args),
+		[apiKey, baseUrl],
 	);
 
-	const refreshAvailability =
-		useCallback(async (): Promise<ChatbotAvailability | null> => {
-			try {
-				const next = await client.chatbot.getAvailability();
-				setAvailability(next);
-				return next;
-			} catch {
-				return null;
-			}
-		}, [client]);
+	// The returned shape is unchanged from before this hook was moved onto
+	// `chat-core`, so existing consumers keep working — only the implementation
+	// moved, and it now backs every other framework's chat binding too.
+	return {
+		messages: snap.messages,
+		send: controller.send,
+		reset: controller.reset,
+		isPending: snap.isPending,
+		error: snap.error,
+		getConfig: controller.loadConfig,
+		latestUiActions: snap.uiActions,
+		availability: snap.availability,
+		refreshAvailability: controller.refreshAvailability,
+		getForm: controller.getForm,
+		submitForm: controller.submitForm,
+		requestHuman: controller.requestHuman,
+		uploadFile,
+	};
+}
 
-	const getForm = useCallback(
-		async (slug: string): Promise<ChatbotFormDefinition | null> => {
-			try {
-				// Chat `show_form` flow → the chatbot path (Live + chatbotAccess).
-				return await client.chatbot.getChatForm(slug);
-			} catch {
-				return null;
-			}
-		},
-		[client],
+/**
+ * Headless storefront + cart for React — the native alternative to
+ * `<Storefront>`, which is a hosted page in an iframe. Everything lives in
+ * `createStoreController`; this only bridges it into React.
+ *
+ * ```tsx
+ * const store = useStorefront({ apiKey, baseUrl });
+ * return store.products.map((p) => <MyCard key={p.id} product={p} />);
+ * ```
+ */
+export function useStorefront(options: {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+}) {
+	const { apiKey, baseUrl, pageSize, categoryId } = options;
+	const controller = useMemo(
+		() =>
+			createStoreController({
+				client: new BiabDevClient({ apiKey, baseUrl }),
+				...(pageSize ? { pageSize } : {}),
+				...(categoryId ? { categoryId } : {}),
+			}),
+		[apiKey, baseUrl, pageSize, categoryId],
 	);
 
-	const submitForm = useCallback(
-		async (
-			slug: string,
-			input: ChatbotFormSubmitInput,
-		): Promise<ChatbotFormSubmitResponse | null> => {
-			try {
-				const priorChat = messages.map((m, i) => ({
-					role: m.role,
-					content: m.content,
-					createdAt: i,
-				}));
-				// Chatbot submit carries the transcript → chatbot path.
-				return await client.chatbot.submitChatForm(slug, {
-					...input,
-					priorChat: input.priorChat ?? priorChat,
-				});
-			} catch (err) {
-				setError(err instanceof Error ? err : new Error("Submit failed"));
-				return null;
-			}
-		},
-		[client, messages],
-	);
+	useEffect(() => {
+		void controller.load();
+		return () => controller.destroy();
+	}, [controller]);
 
-	const uploadFile = useCallback(
-		(args: { sessionId: string; file: File; uploaderEmail?: string | null }) =>
-			client.chatbot.uploadFile(args),
-		[client],
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
 	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
 	return {
-		messages,
-		send,
-		reset,
-		isPending,
-		error,
-		getConfig,
-		latestUiActions,
-		availability,
-		refreshAvailability,
-		getForm,
-		submitForm,
-		uploadFile,
+		...snap,
+		loadMore: controller.loadMore,
+		filterByCategory: controller.filterByCategory,
+		openProduct: controller.openProduct,
+		closeProduct: controller.closeProduct,
+		addToCart: controller.addToCart,
+		updateQuantity: controller.updateQuantity,
+		removeItem: controller.removeItem,
+		applyCoupon: controller.applyCoupon,
+		removeCoupon: controller.removeCoupon,
+		clearCart: controller.clearCart,
+		refreshCart: controller.refreshCart,
 	};
 }
 
@@ -1323,7 +1331,10 @@ export function ChatbotInline({
 		let cancelled = false;
 		void getConfig()
 			.then((cfg) => {
-				if (cancelled) return;
+				// `null` means the config couldn't be read — the core reports that
+				// rather than throwing, because a chat that can't fetch its upload
+				// settings should still let the visitor talk. Keep the defaults.
+				if (cancelled || !cfg) return;
 				setFileUploadsEnabled(cfg.fileUploadsEnabled);
 				setEmailCaptureMode(cfg.emailCaptureMode);
 			})
@@ -2050,23 +2061,8 @@ type AuthLinkProps = {
 	children?: ReactNode;
 };
 
-const DEFAULT_AUTH_BASE_PATH = "/api/biab-auth";
-
-function buildAuthHref(
-	subroute: "sign-in" | "sign-up" | "sign-out",
-	props: {
-		returnTo?: string | undefined;
-		loginHint?: string | undefined;
-		basePath?: string | undefined;
-	},
-): string {
-	const base = (props.basePath ?? DEFAULT_AUTH_BASE_PATH).replace(/\/$/, "");
-	const params = new URLSearchParams();
-	if (props.returnTo) params.set("returnTo", props.returnTo);
-	if (props.loginHint) params.set("loginHint", props.loginHint);
-	const qs = params.toString();
-	return `${base}/${subroute}${qs ? `?${qs}` : ""}`;
-}
+// `buildAuthHref` and `DEFAULT_AUTH_BASE_PATH` come from `./auth-links.js` so
+// every binding builds the same handler URLs from the same query contract.
 
 export function SignIn({ children, ...rest }: AuthLinkProps) {
 	return (
@@ -2233,37 +2229,29 @@ type UseUserState =
  * the cookie + handler path are the source of truth.
  */
 export function useUser(options?: { basePath?: string }): UseUserState {
-	const basePath = (options?.basePath ?? DEFAULT_AUTH_BASE_PATH).replace(
-		/\/$/,
-		"",
+	const basePath = options?.basePath;
+	const controller = useMemo(
+		() => createUserController(basePath ? { basePath } : {}),
+		[basePath],
 	);
-	const [state, setState] = useState<UseUserState>({
-		status: "loading",
-		user: null,
-	});
 
 	useEffect(() => {
-		let cancelled = false;
-		fetch(`${basePath}/me`, { credentials: "include" })
-			.then((r) => (r.ok ? r.json() : null))
-			.then((body: TenantAuthMeResponse) => {
-				if (cancelled) return;
-				if (body) {
-					setState({ status: "signed-in", user: body });
-				} else {
-					setState({ status: "signed-out", user: null });
-				}
-			})
-			.catch(() => {
-				if (cancelled) return;
-				setState({ status: "signed-out", user: null });
-			});
-		return () => {
-			cancelled = true;
-		};
-	}, [basePath]);
+		controller.start();
+		return () => controller.destroy();
+	}, [controller]);
 
-	return state;
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
+	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	// The shape is unchanged for callers; the fetch moved to `account-core` so
+	// every framework reads the session the same way.
+	return useSyncExternalStore(
+		subscribe,
+		getSnapshot,
+		getSnapshot,
+	) as UseUserState;
 }
 
 // ─── Followers / subscribe ───────────────────────────────────────────────────
@@ -2278,39 +2266,9 @@ export type UseFollowersOptions = {
 	baseUrl?: string;
 };
 
-type LocalFollow = { email: string; at: number };
-
-const FOLLOWER_STORE_PREFIX = "biab.followers.";
-
-function readLocalFollow(key: string): LocalFollow | null {
-	if (typeof window === "undefined") return null;
-	try {
-		const raw = window.localStorage.getItem(key);
-		if (!raw) return null;
-		const parsed = JSON.parse(raw) as Partial<LocalFollow>;
-		return typeof parsed?.email === "string"
-			? { email: parsed.email, at: Number(parsed.at) || 0 }
-			: null;
-	} catch {
-		return null;
-	}
-}
-function writeLocalFollow(key: string, value: LocalFollow): void {
-	if (typeof window === "undefined") return;
-	try {
-		window.localStorage.setItem(key, JSON.stringify(value));
-	} catch {
-		// storage disabled / quota — the local hint is best-effort.
-	}
-}
-function clearLocalFollow(key: string): void {
-	if (typeof window === "undefined") return;
-	try {
-		window.localStorage.removeItem(key);
-	} catch {
-		// ignore
-	}
-}
+// `LocalFollow`, `followerStoreKey`, `readLocalFollow`, `writeLocalFollow` and
+// `clearLocalFollow` come from `./auth-links.js` — one storage format, so a
+// visitor who subscribed through one binding is recognised by another.
 
 /**
  * Visitor-facing followers/subscribe client, bound to a publishable token so it
@@ -2336,70 +2294,71 @@ function clearLocalFollow(key: string): void {
  */
 export function useFollowers(options: UseFollowersOptions) {
 	const { token, siteId, baseUrl } = options;
-	const client = useMemo(
+	const controller = useMemo(
 		() =>
-			createBiabClient({
-				apiKey: token,
+			createFollowersController({
+				client: createBiabClient({
+					apiKey: token,
+					siteId,
+					baseUrl: baseUrl ?? DEFAULT_PACKAGE_BASE_URL,
+				}),
 				siteId,
-				baseUrl: baseUrl ?? DEFAULT_PACKAGE_BASE_URL,
 			}),
 		[token, siteId, baseUrl],
 	);
-	const storeKey = `${FOLLOWER_STORE_PREFIX}${siteId}`;
-	const [local, setLocal] = useState<LocalFollow | null>(() =>
-		readLocalFollow(storeKey),
-	);
-	useEffect(() => {
-		setLocal(readLocalFollow(storeKey));
-	}, [storeKey]);
-
-	const join = useCallback(
-		async (input: { email: string; name?: string; source?: string }) => {
-			const res = await client.followers.join(input);
-			const entry: LocalFollow = { email: input.email, at: Date.now() };
-			writeLocalFollow(storeKey, entry);
-			setLocal(entry);
-			return res;
-		},
-		[client, storeKey],
-	);
 
-	const leave = useCallback(
-		async (email: string) => {
-			const res = await client.followers.leave({ email });
-			clearLocalFollow(storeKey);
-			setLocal(null);
-			return res;
-		},
-		[client, storeKey],
-	);
+	useEffect(() => () => controller.destroy(), [controller]);
 
-	const me = useCallback(
-		(email: string) => client.followers.me({ email }),
-		[client],
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
 	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+	// Same shape as before the move onto `account-core`, including the
+	// local-storage hint, so existing consumers are untouched.
+	return {
+		join: controller.join,
+		leave: controller.leave,
+		me: controller.me,
+		edit: controller.edit,
+		subscribedLocally: snap.subscribedLocally,
+		localEmail: snap.localEmail,
+	};
+}
 
-	const edit = useCallback(
-		(email: string, patch: { name?: string; source?: string }) =>
-			client.followers.edit({ email, patch }),
-		[client],
+/**
+ * Headless checkout for React. `start()` mints a Stripe session and `redirect()`
+ * navigates — split apart so a native app or an SSR render can use the first
+ * without the second.
+ */
+export function useCheckout(options: { apiKey: string; baseUrl: string }) {
+	const { apiKey, baseUrl } = options;
+	const controller = useMemo(
+		() =>
+			createCheckoutController({
+				client: new BiabDevClient({ apiKey, baseUrl }),
+			}),
+		[apiKey, baseUrl],
 	);
 
-	return useMemo(
-		() => ({
-			join,
-			leave,
-			me,
-			edit,
-			/** This browser already subscribed (instant, no network). Use to hide a
-			 *  newsletter form for anonymous visitors. */
-			subscribedLocally: local !== null,
-			/** Email this browser subscribed with — pass to `me()` for an
-			 *  authoritative re-check, or `null` if this browser hasn't subscribed. */
-			localEmail: local?.email ?? null,
-		}),
-		[join, leave, me, edit, local],
+	useEffect(() => () => controller.destroy(), [controller]);
+
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
 	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+	return {
+		...snap,
+		start: controller.start,
+		redirect: controller.redirect,
+		resolve: controller.resolve,
+		reset: controller.reset,
+	};
 }
 
 // ─── Marketing pages — list, lazy-load per page, preload ─────────────────────
@@ -5380,22 +5339,17 @@ export function BiabForm(props: BiabFormProps) {
 }
 
 function SocialGlyph({
-	iconSlug,
-	color,
+	iconUrl,
 	size,
 	className,
 	label,
 }: {
-	iconSlug: string | null;
-	color?: string | undefined;
+	iconUrl: string | null;
 	size: number;
 	className?: string | undefined;
 	label: string;
 }) {
-	if (iconSlug) {
-		const src = color
-			? `https://cdn.simpleicons.org/${iconSlug}/${encodeURIComponent(color)}`
-			: `https://cdn.simpleicons.org/${iconSlug}`;
+	if (iconUrl) {
 		return (
 			// biome-ignore lint: remote brand icon from the simple-icons CDN
 			<img
@@ -5403,7 +5357,7 @@ function SocialGlyph({
 				className={className}
 				height={size}
 				loading="lazy"
-				src={src}
+				src={iconUrl}
 				width={size}
 			/>
 		);
@@ -5415,13 +5369,13 @@ function SocialGlyph({
 			fill="none"
 			height={size}
 			stroke="currentColor"
-			strokeWidth={1.8}
-			viewBox="0 0 24 24"
+			strokeWidth={SOCIAL_FALLBACK_GLYPH.strokeWidth}
+			viewBox={SOCIAL_FALLBACK_GLYPH.viewBox}
 			width={size}
 		>
 			<title>{label}</title>
-			<circle cx="12" cy="12" r="9" />
-			<path d="M3 12h18M12 3a14 14 0 0 1 0 18M12 3a14 14 0 0 0 0 18" />
+			<circle {...SOCIAL_FALLBACK_GLYPH.circle} />
+			<path d={SOCIAL_FALLBACK_GLYPH.path} />
 		</svg>
 	);
 }
@@ -5455,21 +5409,12 @@ export function SocialLinks({
 	linkClassName,
 	iconClassName,
 }: SocialLinksProps) {
-	const rows = resolveSocialProfiles(socials);
+	// Rows, URLs and icon URLs come from `social-core`, shared with every other
+	// binding — only the markup below is React's.
+	const rows = resolveSocialLinks(socials, { color });
 	if (rows.length === 0) return null;
 	return (
-		<ul
-			className={className}
-			style={{
-				display: "flex",
-				flexWrap: "wrap",
-				alignItems: "center",
-				gap: "0.75rem",
-				listStyle: "none",
-				margin: 0,
-				padding: 0,
-			}}
-		>
+		<ul className={className} style={SOCIAL_LIST_STYLE as CSSProperties}>
 			{rows.map((row) => (
 				<li key={row.key}>
 					<a
@@ -5482,8 +5427,7 @@ export function SocialLinks({
 					>
 						<SocialGlyph
 							className={iconClassName}
-							color={color}
-							iconSlug={row.iconSlug}
+							iconUrl={row.iconUrl}
 							label={row.label}
 							size={size}
 						/>
@@ -5493,3 +5437,174 @@ export function SocialLinks({
 		</ul>
 	);
 }
+
+/**
+ * Headless blog for React — the native alternative to `<Blog>`, which is a
+ * hosted page in an iframe. Posts, taxonomy, a single post, comments and likes
+ * as data; the layout and the URLs are yours.
+ *
+ * ```tsx
+ * const blog = useBlog({ apiKey, baseUrl });
+ * return blog.posts.map((p) => <MyCard key={p.slug} post={p} />);
+ * ```
+ */
+export function useBlog(options: {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+}) {
+	const { apiKey, baseUrl, pageSize, categoryId } = options;
+	const controller = useMemo(
+		() =>
+			createBlogController({
+				client: new BiabDevClient({ apiKey, baseUrl }),
+				...(pageSize ? { pageSize } : {}),
+				...(categoryId ? { categoryId } : {}),
+			}),
+		[apiKey, baseUrl, pageSize, categoryId],
+	);
+
+	useEffect(() => {
+		void controller.load();
+		return () => controller.destroy();
+	}, [controller]);
+
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
+	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+	return {
+		...snap,
+		loadMore: controller.loadMore,
+		filterByCategory: controller.filterByCategory,
+		openPost: controller.openPost,
+		closePost: controller.closePost,
+		loadComments: controller.loadComments,
+		loadMoreComments: controller.loadMoreComments,
+		postComment: controller.postComment,
+		toggleLike: controller.toggleLike,
+	};
+}
+
+/**
+ * Headless email / phone verification for React.
+ *
+ * Read `flow` before rendering: `otp` wants a code field, `link` wants a
+ * "check your email" message and no field at all.
+ */
+export function useVerify(
+	options: { apiKey: string; baseUrl: string } & Omit<
+		CreateVerifyControllerOptions,
+		"client"
+	>,
+) {
+	const { apiKey, baseUrl, kind, resendCooldownSeconds } = options;
+	const controller = useMemo(
+		() =>
+			createVerifyController({
+				client: new BiabDevClient({ apiKey, baseUrl }),
+				kind,
+				...(resendCooldownSeconds ? { resendCooldownSeconds } : {}),
+			}),
+		[apiKey, baseUrl, kind, resendCooldownSeconds],
+	);
+
+	useEffect(() => () => controller.destroy(), [controller]);
+
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
+	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+	return {
+		...snap,
+		start: controller.start,
+		resend: controller.resend,
+		confirm: controller.confirm,
+		canResend: controller.canResend,
+		reset: controller.reset,
+	};
+}
+
+/**
+ * The signed-in customer's portal for React — work, quotes, contracts,
+ * invoices, orders, downloads, shipping, reviews, referrals, profile and
+ * notification settings. The native alternative to `<Dashboard>`, which is a
+ * hosted page in an iframe.
+ *
+ * `sessionToken` is required: every portal route is scoped to the signed-in
+ * customer, and without one the portal renders empty rather than signed-out.
+ *
+ * Two things the API imposes and this hook does not hide. There are no list
+ * endpoints for invoices, quotes, contracts or shipments — `work` carries the
+ * counts and you open each by id. And a submitted review is queued for staff
+ * approval, so it will NOT appear in `reviews`; watch `reviewAwaitingModeration`
+ * to tell the customer it is pending rather than live.
+ */
+export function usePortal(options: {
+	apiKey: string;
+	baseUrl: string;
+	sessionToken: string;
+}) {
+	const { apiKey, baseUrl, sessionToken } = options;
+	const controller = useMemo(
+		() =>
+			createPortalController({
+				client: new BiabDevClient({ apiKey, baseUrl }),
+				sessionToken,
+			}),
+		[apiKey, baseUrl, sessionToken],
+	);
+
+	useEffect(() => {
+		void controller.load();
+		return () => controller.destroy();
+	}, [controller]);
+
+	const subscribe = useCallback(
+		(onStoreChange: () => void) => controller.subscribe(() => onStoreChange()),
+		[controller],
+	);
+	const getSnapshot = useCallback(() => controller.snapshot(), [controller]);
+	const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+	return {
+		...snap,
+		loadOrders: controller.loadOrders,
+		loadInvoices: controller.loadInvoices,
+		loadQuotes: controller.loadQuotes,
+		loadContracts: controller.loadContracts,
+		loadShipments: controller.loadShipments,
+		loadMessages: controller.loadMessages,
+		postMessage: controller.postMessage,
+		markMessagesRead: controller.markMessagesRead,
+		loadPayments: controller.loadPayments,
+		loadReviews: controller.loadReviews,
+		loadReferrals: controller.loadReferrals,
+		loadNotificationPreferences: controller.loadNotificationPreferences,
+		loadOtherOrgs: controller.loadOtherOrgs,
+		openJob: controller.openJob,
+		openOrder: controller.openOrder,
+		openInvoice: controller.openInvoice,
+		openQuote: controller.openQuote,
+		openContract: controller.openContract,
+		trackShipment: controller.trackShipment,
+		closeDetail: controller.closeDetail,
+		postJobComment: controller.postJobComment,
+		acceptQuote: controller.acceptQuote,
+		rejectQuote: controller.rejectQuote,
+		signContract: controller.signContract,
+		payInvoice: controller.payInvoice,
+		updateProfile: controller.updateProfile,
+		updateNotificationPreferences: controller.updateNotificationPreferences,
+		submitReview: controller.submitReview,
+		submitReturnRequest: controller.submitReturnRequest,
+		contactCompany: controller.contactCompany,
+	};
+}