@businessdash/sdk 0.9.60 → 0.9.80

package/src/solid-surfaces.tsx

@@ -0,0 +1,1311 @@
+/**
+ * `@businessdash/sdk/solid` — the product surfaces beyond forms.
+ *
+ * Solid used to stop at `<BiabForm>` while React carried the whole product:
+ * storefront, cart, checkout, blog, the customer portal, chat, auth, followers
+ * and social links. This file closes most of that gap.
+ *
+ * ## Why this was cheap, and what it means
+ *
+ * Six of these surfaces are not bespoke UI. `Storefront`, `Cart`, `Checkout`,
+ * `Blog`, `Chatbot` and `Dashboard` are BusinessDash-hosted pages rendered in a
+ * sandboxed iframe: the binding mints a short-lived session, points an iframe
+ * at its URL, and relays `postMessage` events back to the host. That logic is
+ * two primitives — `createEmbedSession` and `<EmbedIframe>` — and every embed
+ * surface is a dozen lines on top of them. The React binding is built the same
+ * way; this is the same architecture expressed in signals.
+ *
+ * The consequence worth stating plainly: these surfaces render BusinessDash's
+ * markup, not yours. They are the fastest path to a working store, not a
+ * design-system component. `<BiabForm>` remains the only surface here that
+ * renders into your own DOM, and `BiabClient` is always available if you want
+ * to build the UI yourself.
+ *
+ * ## Solid specifics
+ *
+ * Props are never destructured — a Solid props object is a reactive proxy and
+ * pulling values out of it at call time freezes them. Everything reads
+ * `props.x` at the point of use. External state (session status, auth, the
+ * follower hint) lives in signals, and every listener and timer is torn down
+ * through `onCleanup`.
+ *
+ * Ship mode: SOURCE. Compiled by the consumer's Solid toolchain, never by tsc
+ * here — same as `solid.tsx`.
+ *
+ * @module
+ */
+
+// Only primitives that exist UNCHANGED in both Solid 1 and Solid 2. Everything
+// Solid 2 moved or dropped comes from `solid-compat` — see that module for the
+// measured differences.
+import {
+	createContext,
+	createEffect,
+	createMemo,
+	createSignal,
+	onCleanup,
+	useContext,
+} from "solid-js";
+import {
+	createFollowersController,
+	createUserController,
+} from "./account-core/index.js";
+// Only the href builder is still needed here; the follower storage helpers and
+// the session read moved to `account-core` when this binding stopped
+// hand-rolling them.
+import { buildAuthHref } 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 {
+	BlogCommentPostInput,
+	BlogSessionInput,
+	BlogSessionResponse,
+	CartAddItemInput,
+	CartSessionResponse,
+	ChatbotFormSubmitInput,
+	ChatbotRequestHumanInput,
+	ChatbotSessionResponse,
+	CheckoutSessionInput,
+	CheckoutSessionResponse,
+	CustomerContactCompanyInput,
+	CustomerInvoicePayInput,
+	CustomerJobCommentPostInput,
+	CustomerPortalMessagePostInput,
+	CustomerPortalUpdateProfileInput,
+	CustomerReturnRequestInput,
+	CustomerReviewSubmitInput,
+	DashboardSessionResponse,
+	NotificationPreferencesUpdateInput,
+	StorefrontSessionInput,
+	StorefrontSessionResponse,
+} from "./contracts.js";
+import {
+	type BiabEmbedEvent,
+	DEFAULT_EMBED_SANDBOX,
+	DEFAULT_REFRESH_LEAD_MS,
+	type EmbedSessionState,
+	refreshDelayMs,
+	subscribeToEmbedMessages,
+} from "./embed-protocol.js";
+import { createMarketingController } from "./marketing-core/index.js";
+import { createPortalController } from "./portal-core/index.js";
+import { createBiabClient } from "./sdk.js";
+import {
+	resolveSocialLinks,
+	SOCIAL_FALLBACK_GLYPH,
+	SOCIAL_LIST_STYLE,
+} from "./social-core/index.js";
+import {
+	For,
+	onMount,
+	providerFor,
+	renderNode,
+	Show,
+	type SolidNode,
+	type SolidStyle,
+} from "./solid-compat.js";
+import { createStoreController } from "./store-core/index.js";
+import {
+	type CreateVerifyControllerOptions,
+	createVerifyController,
+} from "./verify-core/index.js";
+
+export type { BiabEmbedEvent } from "./embed-protocol.js";
+
+/** Package-API base URL used when a surface doesn't specify one. */
+export const DEFAULT_PACKAGE_BASE_URL =
+	"https://businessdash.us/api/package/v1";
+
+const defaultIframeStyle: SolidStyle = {
+	width: "100%",
+	height: "100%",
+	"min-height": "600px",
+	border: "0",
+	display: "block",
+};
+
+const messageStyle: SolidStyle = { padding: "16px" };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// createEmbedSession — mint a session, keep it fresh
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type EmbedSessionOptions = {
+	apiKey: string;
+	baseUrl: string;
+	/** Refresh this many ms before the session expires. Default 30s. */
+	refreshLeadMs?: number | undefined;
+};
+
+/**
+ * Create and maintain an embed session.
+ *
+ * `options` is a getter so the session follows a changing `apiKey`/`baseUrl`
+ * instead of capturing whatever they were on first render — the Solid
+ * equivalent of React's dependency array, and the reason props aren't
+ * destructured on the way in.
+ *
+ * The session is re-minted shortly before it expires, so a page left open
+ * overnight doesn't wake up to a dead iframe.
+ */
+export function createEmbedSession<
+	T extends { url: string; expiresAt: string },
+>(
+	loader: (client: BiabDevClient) => Promise<T>,
+	options: () => EmbedSessionOptions,
+) {
+	const client = createMemo(
+		() =>
+			new BiabDevClient({
+				apiKey: options().apiKey,
+				baseUrl: options().baseUrl,
+			}),
+	);
+
+	const [state, setState] = createSignal<EmbedSessionState<T>>({
+		status: "idle",
+	});
+
+	const refresh = async (): Promise<void> => {
+		setState({ status: "loading" });
+		try {
+			const session = await loader(client());
+			setState({ status: "ready", session });
+		} catch (error) {
+			setState({
+				status: "error",
+				error:
+					error instanceof Error ? error : new Error("Unknown session error"),
+			});
+		}
+	};
+
+	// Mint on mount, and again whenever the client identity changes.
+	createEffect(() => {
+		client();
+		void refresh();
+	});
+
+	// Re-mint before expiry. Re-runs on every status change, which is what
+	// schedules the next timer after each successful refresh.
+	createEffect(() => {
+		const current = state();
+		if (current.status !== "ready") return;
+		const delay = refreshDelayMs(
+			current.session.expiresAt,
+			options().refreshLeadMs ?? DEFAULT_REFRESH_LEAD_MS,
+			Date.now(),
+		);
+		if (delay === null) return;
+		const timer = setTimeout(() => void refresh(), delay);
+		onCleanup(() => clearTimeout(timer));
+	});
+
+	return { client, state, refresh };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EmbedIframe — the shared shell for every hosted surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+type EmbedIframeProps<T extends { url: string }> = {
+	state: EmbedSessionState<T>;
+	refresh: () => Promise<void>;
+	title: string;
+	class?: string | undefined;
+	style?: SolidStyle | undefined;
+	loadingFallback?: SolidNode | undefined;
+	errorFallback?:
+		| ((error: Error, refresh: () => void) => SolidNode)
+		| undefined;
+	onEvent?: ((event: BiabEmbedEvent) => void) | undefined;
+	/** Extra `sandbox` tokens beyond the safe defaults. */
+	extraSandbox?: string | undefined;
+};
+
+function EmbedIframe<T extends { url: string }>(props: EmbedIframeProps<T>) {
+	let iframe: HTMLIFrameElement | undefined;
+
+	onMount(() => {
+		// The handler is read through `props` on every message rather than
+		// captured, so a host swapping its callback takes effect immediately.
+		const unsubscribe = subscribeToEmbedMessages(
+			() => iframe,
+			(event) => props.onEvent?.(event),
+		);
+		onCleanup(unsubscribe);
+	});
+
+	const errored = () =>
+		props.state.status === "error" ? props.state.error : null;
+	const ready = () =>
+		props.state.status === "ready" ? props.state.session : null;
+
+	return (
+		<Show
+			fallback={
+				props.errorFallback ? (
+					props.errorFallback(errored() as Error, () => void props.refresh())
+				) : (
+					<div class={props.class} style={{ ...messageStyle, ...props.style }}>
+						Embed unavailable: {errored()?.message}
+					</div>
+				)
+			}
+			when={!errored()}
+		>
+			<Show
+				fallback={
+					props.loadingFallback ?? (
+						<div
+							class={props.class}
+							style={{ ...messageStyle, ...props.style }}
+						>
+							Loading…
+						</div>
+					)
+				}
+				when={ready()}
+			>
+				{(session) => (
+					<iframe
+						class={props.class}
+						ref={iframe}
+						sandbox={
+							props.extraSandbox
+								? `${DEFAULT_EMBED_SANDBOX} ${props.extraSandbox}`
+								: DEFAULT_EMBED_SANDBOX
+						}
+						src={session().url}
+						style={{ ...defaultIframeStyle, ...props.style }}
+						title={props.title}
+					/>
+				)}
+			</Show>
+		</Show>
+	);
+}
+
+/** Props every hosted embed surface accepts. */
+type BaseEmbedProps = {
+	apiKey: string;
+	baseUrl: string;
+	class?: string;
+	style?: SolidStyle;
+	title?: string;
+	loadingFallback?: SolidNode;
+	errorFallback?: (error: Error, refresh: () => void) => SolidNode;
+	onEvent?: (event: BiabEmbedEvent) => void;
+	refreshLeadMs?: number;
+};
+
+// ─── Storefront ──────────────────────────────────────────────────────────────
+
+export type StorefrontProps = BaseEmbedProps & {
+	productId?: string;
+	/** Convenience: fires only on cart updates. */
+	onCartChange?: (count: number, subtotalCents: number) => void;
+};
+
+/** The org's hosted storefront, embedded. */
+export function Storefront(props: StorefrontProps) {
+	const { state, refresh } = createEmbedSession<StorefrontSessionResponse>(
+		(client) => {
+			const input: StorefrontSessionInput = props.productId
+				? { productId: props.productId }
+				: undefined;
+			return client.storefront.createSession(input);
+		},
+		() => ({
+			apiKey: props.apiKey,
+			baseUrl: props.baseUrl,
+			refreshLeadMs: props.refreshLeadMs,
+		}),
+	);
+
+	return (
+		<EmbedIframe
+			class={props.class}
+			errorFallback={props.errorFallback}
+			loadingFallback={props.loadingFallback}
+			onEvent={(event) => {
+				props.onEvent?.(event);
+				if (event.type === "biab:cart:update") {
+					props.onCartChange?.(event.count, event.subtotalCents);
+				}
+			}}
+			refresh={refresh}
+			state={state()}
+			style={props.style}
+			title={props.title ?? "Storefront"}
+		/>
+	);
+}
+
+// ─── Cart ────────────────────────────────────────────────────────────────────
+
+export type CartProps = BaseEmbedProps & {
+	onCartChange?: (count: number, subtotalCents: number) => void;
+};
+
+/** The visitor's cart, embedded. */
+export function Cart(props: CartProps) {
+	const { state, refresh } = createEmbedSession<CartSessionResponse>(
+		(client) => client.cart.createSession(),
+		() => ({
+			apiKey: props.apiKey,
+			baseUrl: props.baseUrl,
+			refreshLeadMs: props.refreshLeadMs,
+		}),
+	);
+
+	return (
+		<EmbedIframe
+			class={props.class}
+			errorFallback={props.errorFallback}
+			loadingFallback={props.loadingFallback}
+			onEvent={(event) => {
+				props.onEvent?.(event);
+				if (event.type === "biab:cart:update") {
+					props.onCartChange?.(event.count, event.subtotalCents);
+				}
+			}}
+			refresh={refresh}
+			state={state()}
+			style={props.style}
+			title={props.title ?? "Cart"}
+		/>
+	);
+}
+
+// ─── Blog ────────────────────────────────────────────────────────────────────
+
+export type BlogProps = BaseEmbedProps & { postSlug?: string };
+
+/** The org's blog — index, or a single post when `postSlug` is given. */
+export function Blog(props: BlogProps) {
+	const { state, refresh } = createEmbedSession<BlogSessionResponse>(
+		(client) => {
+			const input: BlogSessionInput = props.postSlug
+				? { postSlug: props.postSlug }
+				: undefined;
+			return client.blog.createSession(input);
+		},
+		() => ({
+			apiKey: props.apiKey,
+			baseUrl: props.baseUrl,
+			refreshLeadMs: props.refreshLeadMs,
+		}),
+	);
+
+	return (
+		<EmbedIframe
+			class={props.class}
+			errorFallback={props.errorFallback}
+			loadingFallback={props.loadingFallback}
+			onEvent={props.onEvent}
+			refresh={refresh}
+			state={state()}
+			style={props.style}
+			title={props.title ?? "Blog"}
+		/>
+	);
+}
+
+// ─── Chatbot ─────────────────────────────────────────────────────────────────
+
+export type ChatbotProps = BaseEmbedProps & {
+	/** Convenience: fires when the assistant replies. */
+	onAssistantMessage?: (content: string, model?: string) => void;
+};
+
+/**
+ * The org's Front Desk assistant, embedded.
+ *
+ * This is the hosted chat UI. React additionally ships a headless
+ * `useChatbot` + `<ChatbotInline>` for hosts that render their own chat; that
+ * pair has no Solid equivalent yet, and `BiabClient.chatbot` is the way to
+ * build one in the meantime.
+ */
+export function Chatbot(props: ChatbotProps) {
+	const { state, refresh } = createEmbedSession<ChatbotSessionResponse>(
+		(client) => client.chatbot.createSession(),
+		() => ({
+			apiKey: props.apiKey,
+			baseUrl: props.baseUrl,
+			refreshLeadMs: props.refreshLeadMs,
+		}),
+	);
+
+	return (
+		<EmbedIframe
+			class={props.class}
+			errorFallback={props.errorFallback}
+			loadingFallback={props.loadingFallback}
+			onEvent={(event) => {
+				props.onEvent?.(event);
+				if (event.type === "biab:chatbot:assistant-message") {
+					props.onAssistantMessage?.(event.content, event.model);
+				}
+			}}
+			refresh={refresh}
+			state={state()}
+			style={props.style}
+			title={props.title ?? "Assistant"}
+		/>
+	);
+}
+
+// ─── Checkout ────────────────────────────────────────────────────────────────
+
+export type CheckoutProps = {
+	apiKey: string;
+	baseUrl: string;
+	cart: CheckoutSessionInput;
+	/**
+	 * `"redirect"` (default) renders a button that sends the browser to Stripe
+	 * at the top level. `"iframe"` embeds the checkout surface, where Stripe
+	 * opens in a new tab via `allow-top-navigation`.
+	 */
+	mode?: "redirect" | "iframe";
+	class?: string;
+	style?: SolidStyle;
+	title?: string;
+	children?: SolidNode;
+	loadingFallback?: SolidNode;
+	errorFallback?: (error: Error, refresh: () => void) => SolidNode;
+	onEvent?: (event: BiabEmbedEvent) => void;
+	onSuccess?: (sessionId: string) => void;
+	onCancel?: (sessionId: string) => void;
+	onError?: (error: Error) => void;
+};
+
+/** Start a Stripe checkout, as a button (default) or an embedded surface. */
+export function Checkout(props: CheckoutProps) {
+	const client = createMemo(
+		() => new BiabDevClient({ apiKey: props.apiKey, baseUrl: props.baseUrl }),
+	);
+	const [state, setState] = createSignal<
+		EmbedSessionState<CheckoutSessionResponse>
+	>({ status: "idle" });
+
+	const start = async (): Promise<void> => {
+		setState({ status: "loading" });
+		try {
+			const session = await client().checkout.createSession(props.cart);
+			setState({ status: "ready", session });
+			if ((props.mode ?? "redirect") === "redirect") {
+				window.location.href = session.stripeUrl;
+			}
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error("Checkout failed");
+			setState({ status: "error", error: err });
+			props.onError?.(err);
+		}
+	};
+
+	// Iframe mode mints its session eagerly; redirect mode waits for the click,
+	// because starting a checkout the visitor hasn't asked for creates an
+	// abandoned Stripe session every time the component mounts.
+	createEffect(() => {
+		if (
+			(props.mode ?? "redirect") !== "redirect" &&
+			state().status === "idle"
+		) {
+			void start();
+		}
+	});
+
+	return (
+		<Show
+			fallback={
+				<button
+					class={props.class}
+					disabled={state().status === "loading"}
+					onClick={() => void start()}
+					style={props.style}
+					type="button"
+				>
+					{renderNode(
+						props.children ??
+							(state().status === "loading" ? "Loading…" : "Checkout"),
+					)}
+				</button>
+			}
+			when={(props.mode ?? "redirect") !== "redirect"}
+		>
+			<EmbedIframe
+				class={props.class}
+				errorFallback={props.errorFallback}
+				extraSandbox="allow-top-navigation"
+				loadingFallback={props.loadingFallback}
+				onEvent={(event) => {
+					props.onEvent?.(event);
+					if (event.type === "biab:checkout:success") {
+						props.onSuccess?.(event.sessionId);
+					} else if (event.type === "biab:checkout:cancel") {
+						props.onCancel?.(event.sessionId);
+					} else if (event.type === "biab:checkout:error") {
+						props.onError?.(new Error(event.message));
+					}
+				}}
+				refresh={start}
+				state={state()}
+				style={props.style}
+				title={props.title ?? "Checkout"}
+			/>
+		</Show>
+	);
+}
+
+export type CheckoutResultState = {
+	status: "loading" | "paid" | "unpaid" | "error";
+	error?: Error;
+	amountTotalCents?: number | null;
+	currency?: string | null;
+	customerEmail?: string | null;
+};
+
+export type CheckoutResultProps = {
+	apiKey: string;
+	baseUrl: string;
+	orgSlug: string;
+	sessionIdParam?: string;
+	render?: (state: CheckoutResultState) => SolidNode;
+};
+
+/**
+ * Pair with `<Checkout>` in redirect mode: drop this on the success URL and it
+ * reads `?session_id=…` and reports the resolved payment status.
+ */
+export function CheckoutResult(props: CheckoutResultProps) {
+	const [state, setState] = createSignal<CheckoutResultState>({
+		status: "loading",
+	});
+
+	onMount(() => {
+		let cancelled = false;
+		onCleanup(() => {
+			cancelled = true;
+		});
+
+		const paramName = props.sessionIdParam ?? "session_id";
+		const sessionId = new URL(window.location.href).searchParams.get(paramName);
+		if (!sessionId) {
+			setState({ status: "error", error: new Error("Missing session id.") });
+			return;
+		}
+
+		// The public tRPC endpoint — no API key required.
+		const trpcBase = props.baseUrl.replace(/\/api\/package\/v1\/?$/, "");
+		const requestUrl = `${trpcBase}/api/trpc/store.checkoutSessionStatus?input=${encodeURIComponent(
+			JSON.stringify({ json: { orgSlug: props.orgSlug, sessionId } }),
+		)}`;
+
+		// Defensive: a misconfigured baseUrl must not become a `javascript:` fetch.
+		const parsed = (() => {
+			try {
+				return new URL(requestUrl);
+			} catch {
+				return null;
+			}
+		})();
+		if (
+			!parsed ||
+			(parsed.protocol !== "https:" && parsed.protocol !== "http:")
+		) {
+			setState({
+				status: "error",
+				error: new Error(`Invalid baseUrl: ${props.baseUrl}`),
+			});
+			return;
+		}
+
+		fetch(parsed.toString())
+			.then((r) => r.json())
+			.then((data) => {
+				if (cancelled) return;
+				const result = data?.result?.data?.json ?? data?.result?.data;
+				if (!result) throw new Error("Empty checkout-status response.");
+				setState({
+					status: result.paymentStatus === "paid" ? "paid" : "unpaid",
+					amountTotalCents: result.amountTotalCents,
+					currency: result.currency,
+					customerEmail: result.customerEmail,
+				});
+			})
+			.catch((err) => {
+				if (cancelled) return;
+				setState({
+					status: "error",
+					error: err instanceof Error ? err : new Error(String(err)),
+				});
+			});
+	});
+
+	return (
+		<Show fallback={props.render?.(state())} when={!props.render}>
+			<Show when={state().status === "loading"}>
+				<p>Loading order…</p>
+			</Show>
+			<Show when={state().status === "error"}>
+				<p>Couldn't load order: {state().error?.message}</p>
+			</Show>
+			<Show when={state().status === "paid"}>
+				<p>
+					Thank you! Receipt sent to {state().customerEmail ?? "your email"}.
+				</p>
+			</Show>
+			<Show when={state().status === "unpaid"}>
+				<p>Payment status: pending. We'll email you when it finalizes.</p>
+			</Show>
+		</Show>
+	);
+}
+
+// ─── Customer portal (Dashboard) ─────────────────────────────────────────────
+
+type DashboardContextValue = {
+	state: () => EmbedSessionState<DashboardSessionResponse>;
+	refresh: () => Promise<void>;
+};
+
+const DashboardContext = createContext<DashboardContextValue | null>(null);
+/** Solid 1 exposes `.Provider`; Solid 2 makes the context its own provider. */
+const DashboardCtxProvider = providerFor<DashboardContextValue | null>(
+	DashboardContext,
+);
+
+export type DashboardProviderProps = {
+	apiKey: string;
+	baseUrl: string;
+	children?: SolidNode;
+	refreshLeadMs?: number;
+};
+
+/**
+ * Mint and hold one customer-portal session for a subtree, so several
+ * `<Dashboard>` instances (or your own UI reading `useDashboardSession`) share
+ * a session instead of each minting their own.
+ */
+export function DashboardProvider(props: DashboardProviderProps) {
+	if (!props.apiKey)
+		throw new Error("<DashboardProvider> requires an `apiKey`.");
+	if (!props.baseUrl) {
+		throw new Error("<DashboardProvider> requires a `baseUrl`.");
+	}
+
+	const { state, refresh } = createEmbedSession<DashboardSessionResponse>(
+		(client) => client.dashboard.createSession(),
+		() => ({
+			apiKey: props.apiKey,
+			baseUrl: props.baseUrl,
+			refreshLeadMs: props.refreshLeadMs,
+		}),
+	);
+
+	return (
+		<DashboardCtxProvider value={{ state, refresh }}>
+			{renderNode(props.children)}
+		</DashboardCtxProvider>
+	);
+}
+
+/** Read the portal session provided by the nearest `<DashboardProvider>`. */
+export function useDashboardSession(): DashboardContextValue {
+	const ctx = useContext(DashboardContext);
+	if (!ctx) {
+		throw new Error(
+			"useDashboardSession must be used inside <DashboardProvider>.",
+		);
+	}
+	return ctx;
+}
+
+export type DashboardProps = {
+	class?: string;
+	style?: SolidStyle;
+	title?: string;
+	loadingFallback?: SolidNode;
+	errorFallback?: (error: Error, refresh: () => void) => SolidNode;
+};
+
+/** The signed-in customer portal, embedded. Requires `<DashboardProvider>`. */
+export function Dashboard(props: DashboardProps) {
+	const ctx = useDashboardSession();
+	return (
+		<EmbedIframe
+			class={props.class}
+			errorFallback={props.errorFallback}
+			loadingFallback={
+				props.loadingFallback ?? (
+					<div class={props.class} style={{ ...messageStyle, ...props.style }}>
+						Loading dashboard…
+					</div>
+				)
+			}
+			refresh={ctx.refresh}
+			state={ctx.state()}
+			style={props.style}
+			title={props.title ?? "Business In A Box Dashboard"}
+		/>
+	);
+}
+
+// ─── Tenant auth ─────────────────────────────────────────────────────────────
+
+export type AuthLinkProps = {
+	returnTo?: string;
+	loginHint?: string;
+	basePath?: string;
+	class?: string;
+	style?: SolidStyle;
+	children?: SolidNode;
+};
+
+/** Link into the auth handler's sign-in route. */
+export function SignIn(props: AuthLinkProps) {
+	return (
+		<a
+			class={props.class}
+			href={buildAuthHref("sign-in", props)}
+			style={props.style}
+		>
+			{renderNode(props.children ?? "Sign in")}
+		</a>
+	);
+}
+
+/** Link into the auth handler's sign-up route. */
+export function SignUp(props: AuthLinkProps) {
+	return (
+		<a
+			class={props.class}
+			href={buildAuthHref("sign-up", props)}
+			style={props.style}
+		>
+			{renderNode(props.children ?? "Create account")}
+		</a>
+	);
+}
+
+/** Link into the auth handler's sign-out route. */
+export function SignOut(props: AuthLinkProps) {
+	return (
+		<a
+			class={props.class}
+			href={buildAuthHref("sign-out", { basePath: props.basePath })}
+			style={props.style}
+		>
+			{renderNode(props.children ?? "Sign out")}
+		</a>
+	);
+}
+
+export type ProgrammaticAuthOptions = {
+	returnTo?: string;
+	loginHint?: string;
+	basePath?: string;
+};
+
+/** Imperative sign-in, for router guards and event handlers. Browser-only. */
+export function signIn(options: ProgrammaticAuthOptions = {}): void {
+	if (typeof window === "undefined") return;
+	window.location.assign(buildAuthHref("sign-in", options));
+}
+
+/** Imperative sign-up. Browser-only. */
+export function signUp(options: ProgrammaticAuthOptions = {}): void {
+	if (typeof window === "undefined") return;
+	window.location.assign(buildAuthHref("sign-up", options));
+}
+
+/** Imperative sign-out. Browser-only. */
+export function signOut(options: { basePath?: string } = {}): void {
+	if (typeof window === "undefined") return;
+	window.location.assign(buildAuthHref("sign-out", options));
+}
+
+// The customer session and followers bindings that used to live here — a
+// hand-rolled fetch and a hand-rolled local-storage hint — now come from
+// `account-core` further down this file, shared with every other binding.
+
+// ─── Social links ────────────────────────────────────────────────────────────
+
+export type SocialLinksProps = {
+	/** The company profile's `socials` record (e.g. `storefrontMeta().socials`). */
+	socials: unknown;
+	/**
+	 * Icon colour for branded glyphs — a hex without `#`, or a CSS colour
+	 * keyword. Omit to use each brand's official colour.
+	 */
+	color?: string;
+	/** Icon edge length in px (default 20). */
+	size?: number;
+	class?: string;
+	linkClass?: string;
+	iconClass?: string;
+};
+
+function SocialGlyph(props: {
+	iconUrl: string | null;
+	size: number;
+	class?: string | undefined;
+	label: string;
+}) {
+	return (
+		<Show
+			fallback={
+				<svg
+					aria-hidden="true"
+					class={props.class}
+					fill="none"
+					height={props.size}
+					stroke="currentColor"
+					stroke-width={SOCIAL_FALLBACK_GLYPH.strokeWidth}
+					viewBox={SOCIAL_FALLBACK_GLYPH.viewBox}
+					width={props.size}
+				>
+					<title>{props.label}</title>
+					<circle
+						cx={SOCIAL_FALLBACK_GLYPH.circle.cx}
+						cy={SOCIAL_FALLBACK_GLYPH.circle.cy}
+						r={SOCIAL_FALLBACK_GLYPH.circle.r}
+					/>
+					<path d={SOCIAL_FALLBACK_GLYPH.path} />
+				</svg>
+			}
+			when={props.iconUrl}
+		>
+			{(url) => (
+				<img
+					alt={props.label}
+					class={props.class}
+					height={props.size}
+					loading="lazy"
+					src={url()}
+					width={props.size}
+				/>
+			)}
+		</Show>
+	);
+}
+
+/** Every social profile on the company, as icon links in canonical order. */
+export function SocialLinks(props: SocialLinksProps) {
+	// Rows, URLs and icon URLs come from `social-core`; only the markup is Solid's.
+	const rows = createMemo(() =>
+		resolveSocialLinks(props.socials, { color: props.color }),
+	);
+
+	return (
+		<Show when={rows().length > 0}>
+			<ul class={props.class} style={SOCIAL_LIST_STYLE}>
+				<For each={rows()}>
+					{(row) => (
+						<li>
+							<a
+								aria-label={row.label}
+								class={props.linkClass}
+								href={row.url}
+								rel="noopener noreferrer"
+								target="_blank"
+								title={row.label}
+							>
+								<SocialGlyph
+									class={props.iconClass}
+									iconUrl={row.iconUrl}
+									label={row.label}
+									size={props.size ?? 20}
+								/>
+							</a>
+						</li>
+					)}
+				</For>
+			</ul>
+		</Show>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Native storefront + chat — the non-iframe path
+//
+// `<Storefront>` and `<Chatbot>` above are hosted pages in a sandbox: fast to
+// adopt, but they render BusinessDash's markup, not yours. These primitives are
+// the alternative. All of the behaviour lives in `store-core` / `chat-core`,
+// shared with every other binding; this only bridges the controller's
+// subscribe/snapshot observable into a Solid signal.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Bridge a controller with a `subscribe`/`snapshot` observable into a signal.
+ *
+ * The core does NOT replay on subscribe, so the signal is seeded from
+ * `snapshot()` and only then subscribed — without the seed the first render
+ * would have nothing to draw.
+ */
+function bridge<
+	TSnapshot,
+	TController extends {
+		snapshot(): TSnapshot;
+		subscribe(cb: (s: TSnapshot) => void): () => void;
+		destroy(): void;
+	},
+>(
+	create: () => TController,
+	start?: (controller: TController) => void,
+): { controller: () => TController; snapshot: () => TSnapshot } {
+	const controller = createMemo(create);
+	// Boxed: Solid 2 types the value overload of `createSignal` as
+	// `Exclude<T, Function>` because a bare function argument is read as a
+	// compute function. A wrapper object is never callable, so this compiles on
+	// both versions. See `fromStore` in solid-compat for the same reasoning.
+	const [snapshot, setSnapshot] = createSignal<{ value: TSnapshot }>({
+		value: controller().snapshot(),
+	});
+
+	createEffect(() => {
+		const current = controller();
+		setSnapshot({ value: current.snapshot() });
+		const unsubscribe = current.subscribe((next) =>
+			setSnapshot({ value: next }),
+		);
+		start?.(current);
+		onCleanup(() => {
+			unsubscribe();
+			current.destroy();
+		});
+	});
+
+	// Unwrap the box at the boundary so callers still get a plain accessor.
+	return { controller, snapshot: () => snapshot().value };
+}
+
+export type CreateStorefrontOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+/**
+ * Headless storefront + cart for Solid.
+ *
+ * ```tsx
+ * const store = createStorefront(() => ({ apiKey, baseUrl }));
+ * <For each={store.snapshot().products}>{(p) => <MyCard product={p} />}</For>
+ * ```
+ */
+export function createStorefront(options: () => CreateStorefrontOptions) {
+	const { controller, snapshot } = bridge(
+		() =>
+			createStoreController({
+				client: new BiabDevClient({
+					apiKey: options().apiKey,
+					baseUrl: options().baseUrl,
+				}),
+				...(options().pageSize ? { pageSize: options().pageSize } : {}),
+				...(options().categoryId ? { categoryId: options().categoryId } : {}),
+			}),
+		(c) => void c.load(),
+	);
+
+	return {
+		snapshot,
+		loadMore: () => controller().loadMore(),
+		filterByCategory: (id: string | null) => controller().filterByCategory(id),
+		openProduct: (id: string) => controller().openProduct(id),
+		closeProduct: () => controller().closeProduct(),
+		addToCart: (input: CartAddItemInput) => controller().addToCart(input),
+		updateQuantity: (itemId: string, quantity: number) =>
+			controller().updateQuantity(itemId, quantity),
+		removeItem: (itemId: string) => controller().removeItem(itemId),
+		applyCoupon: (code: string) => controller().applyCoupon(code),
+		removeCoupon: () => controller().removeCoupon(),
+		clearCart: () => controller().clearCart(),
+		refreshCart: () => controller().refreshCart(),
+	};
+}
+
+export type CreateChatOptions = { apiKey: string; baseUrl: string };
+
+/**
+ * Headless Front Desk chat for Solid — the native alternative to `<Chatbot>`.
+ *
+ * ```tsx
+ * const chat = createChat(() => ({ apiKey, baseUrl }));
+ * <For each={chat.snapshot().messages}>{(m) => <Bubble message={m} />}</For>
+ * ```
+ */
+export function createChat(options: () => CreateChatOptions) {
+	const { controller, snapshot } = bridge(() =>
+		createChatController({
+			client: new BiabDevClient({
+				apiKey: options().apiKey,
+				baseUrl: options().baseUrl,
+			}),
+		}),
+	);
+
+	return {
+		snapshot,
+		send: (content: string) => controller().send(content),
+		reset: () => controller().reset(),
+		loadConfig: () => controller().loadConfig(),
+		refreshAvailability: () => controller().refreshAvailability(),
+		getForm: (slug: string) => controller().getForm(slug),
+		submitForm: (slug: string, input: ChatbotFormSubmitInput) =>
+			controller().submitForm(slug, input),
+		requestHuman: (input: ChatbotRequestHumanInput) =>
+			controller().requestHuman(input),
+	};
+}
+
+export type CreateBlogOptions = {
+	apiKey: string;
+	baseUrl: string;
+	pageSize?: number;
+	categoryId?: string | null;
+};
+
+/**
+ * Headless blog for Solid — the native alternative to `<Blog>`.
+ *
+ * ```tsx
+ * const blog = createBlog(() => ({ apiKey, baseUrl }));
+ * <For each={blog.snapshot().posts}>{(p) => <MyCard post={p} />}</For>
+ * ```
+ */
+export function createBlog(options: () => CreateBlogOptions) {
+	const { controller, snapshot } = bridge(
+		() =>
+			createBlogController({
+				client: new BiabDevClient({
+					apiKey: options().apiKey,
+					baseUrl: options().baseUrl,
+				}),
+				...(options().pageSize ? { pageSize: options().pageSize } : {}),
+				...(options().categoryId ? { categoryId: options().categoryId } : {}),
+			}),
+		(c) => void c.load(),
+	);
+
+	return {
+		snapshot,
+		loadMore: () => controller().loadMore(),
+		filterByCategory: (id: string | null) => controller().filterByCategory(id),
+		openPost: (slug: string) => controller().openPost(slug),
+		closePost: () => controller().closePost(),
+		loadComments: () => controller().loadComments(),
+		loadMoreComments: () => controller().loadMoreComments(),
+		postComment: (input: BlogCommentPostInput) =>
+			controller().postComment(input),
+		toggleLike: () => controller().toggleLike(),
+	};
+}
+
+export type CreateCheckoutOptions = { apiKey: string; baseUrl: string };
+
+/** Headless checkout. `start()` mints a session; `redirect()` navigates. */
+export function createCheckout(options: () => CreateCheckoutOptions) {
+	const { controller, snapshot } = bridge(() =>
+		createCheckoutController({
+			client: new BiabDevClient({
+				apiKey: options().apiKey,
+				baseUrl: options().baseUrl,
+			}),
+		}),
+	);
+	return {
+		snapshot,
+		start: (input: CheckoutSessionInput) => controller().start(input),
+		redirect: () => controller().redirect(),
+		resolve: (sessionId: string) => controller().resolve(sessionId),
+		reset: () => controller().reset(),
+	};
+}
+
+/**
+ * The signed-in customer, from the auth handler's `/me`.
+ *
+ * Replaces the hand-rolled fetch this binding used to carry: the logic now
+ * lives in `account-core` alongside every other framework's.
+ */
+export function createUser(options: () => { basePath?: string } = () => ({})) {
+	const { controller, snapshot } = bridge(
+		() => createUserController(options()),
+		(c) => c.start(),
+	);
+	return { snapshot, refresh: () => controller().refresh() };
+}
+
+export type CreateFollowersOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+
+/** Newsletter / follower subscribe with the local already-subscribed hint. */
+export function createFollowers(options: () => CreateFollowersOptions) {
+	const { controller, snapshot } = bridge(() =>
+		createFollowersController({
+			client: createBiabClient({
+				apiKey: options().token,
+				siteId: options().siteId,
+				...(options().baseUrl ? { baseUrl: options().baseUrl } : {}),
+			}),
+			siteId: options().siteId,
+		}),
+	);
+	return {
+		snapshot,
+		join: (input: { email: string; name?: string; source?: string }) =>
+			controller().join(input),
+		leave: (email: string) => controller().leave(email),
+		me: (email: string) => controller().me(email),
+		edit: (email: string, patch: { name?: string; source?: string }) =>
+			controller().edit(email, patch),
+	};
+}
+
+export type CreateMarketingOptions = {
+	token: string;
+	siteId: string;
+	baseUrl?: string;
+};
+
+/** Headless marketing pages — the index, plus one page at a time. */
+export function createMarketing(options: () => CreateMarketingOptions) {
+	const { controller, snapshot } = bridge(
+		() =>
+			createMarketingController({
+				client: createBiabClient({
+					apiKey: options().token,
+					siteId: options().siteId,
+					...(options().baseUrl ? { baseUrl: options().baseUrl } : {}),
+				}),
+			}),
+		(c) => void c.load(),
+	);
+	return {
+		snapshot,
+		open: (pageKey?: string, opts?: { skipCache?: boolean }) =>
+			controller().open(pageKey, opts),
+		prefetch: (pageKey?: string) => controller().prefetch(pageKey),
+		close: () => controller().close(),
+	};
+}
+
+export type CreateVerifyOptions = {
+	apiKey: string;
+	baseUrl: string;
+} & Omit<CreateVerifyControllerOptions, "client">;
+
+/** Headless email / phone verification. Read `snapshot().flow` before rendering. */
+export function createVerify(options: () => CreateVerifyOptions) {
+	const { controller, snapshot } = bridge(() => {
+		const { apiKey, baseUrl, ...rest } = options();
+		return createVerifyController({
+			client: new BiabDevClient({ apiKey, baseUrl }),
+			...rest,
+		});
+	});
+	return {
+		snapshot,
+		start: (destination: string) => controller().start(destination),
+		resend: () => controller().resend(),
+		confirm: (token: string) => controller().confirm(token),
+		canResend: (now?: number) => controller().canResend(now),
+		reset: () => controller().reset(),
+	};
+}
+
+export type CreatePortalOptions = {
+	apiKey: string;
+	baseUrl: string;
+	sessionToken: string;
+};
+
+/**
+ * The signed-in customer's portal — work, quotes, contracts, invoices, orders,
+ * downloads, shipping, reviews, referrals, profile and notification settings.
+ *
+ * `sessionToken` is required: every portal route is scoped to the signed-in
+ * customer, and without one the portal renders empty rather than signed-out.
+ *
+ * There are no list endpoints for invoices, quotes, contracts or shipments —
+ * `snapshot().work` carries the counts and you open each by id. A submitted
+ * review is queued for staff approval, so it will not appear in
+ * `snapshot().reviews`; watch `reviewAwaitingModeration`.
+ */
+export function createPortal(options: () => CreatePortalOptions) {
+	const { controller, snapshot } = bridge(
+		() =>
+			createPortalController({
+				client: new BiabDevClient({
+					apiKey: options().apiKey,
+					baseUrl: options().baseUrl,
+				}),
+				sessionToken: options().sessionToken,
+			}),
+		(c) => void c.load(),
+	);
+
+	return {
+		snapshot,
+		load: () => controller().load(),
+		loadOrders: (opts?: { limit?: number }) => controller().loadOrders(opts),
+		loadInvoices: (opts?: {
+			limit?: number;
+			status?: string;
+			unpaid?: boolean;
+		}) => controller().loadInvoices(opts),
+		loadQuotes: (opts?: { limit?: number; status?: string }) =>
+			controller().loadQuotes(opts),
+		loadContracts: (opts?: { limit?: number; status?: string }) =>
+			controller().loadContracts(opts),
+		loadShipments: (opts?: { limit?: number; active?: boolean }) =>
+			controller().loadShipments(opts),
+		loadMessages: (opts?: { limit?: number; jobId?: string }) =>
+			controller().loadMessages(opts),
+		postMessage: (input: CustomerPortalMessagePostInput) =>
+			controller().postMessage(input),
+		markMessagesRead: () => controller().markMessagesRead(),
+		loadPayments: (opts?: { limit?: number }) =>
+			controller().loadPayments(opts),
+		loadReviews: () => controller().loadReviews(),
+		loadReferrals: () => controller().loadReferrals(),
+		loadNotificationPreferences: () =>
+			controller().loadNotificationPreferences(),
+		loadOtherOrgs: () => controller().loadOtherOrgs(),
+		openJob: (id: string) => controller().openJob(id),
+		openOrder: (id: string) => controller().openOrder(id),
+		openInvoice: (id: string) => controller().openInvoice(id),
+		openQuote: (id: string) => controller().openQuote(id),
+		openContract: (id: string) => controller().openContract(id),
+		trackShipment: (id: string) => controller().trackShipment(id),
+		closeDetail: () => controller().closeDetail(),
+		postJobComment: (jobId: string, input: CustomerJobCommentPostInput) =>
+			controller().postJobComment(jobId, input),
+		acceptQuote: (id: string) => controller().acceptQuote(id),
+		rejectQuote: (id: string) => controller().rejectQuote(id),
+		signContract: (id: string) => controller().signContract(id),
+		payInvoice: (id: string, opts?: CustomerInvoicePayInput) =>
+			controller().payInvoice(id, opts),
+		updateProfile: (input: CustomerPortalUpdateProfileInput) =>
+			controller().updateProfile(input),
+		updateNotificationPreferences: (
+			input: NotificationPreferencesUpdateInput,
+		) => controller().updateNotificationPreferences(input),
+		submitReview: (input: CustomerReviewSubmitInput) =>
+			controller().submitReview(input),
+		submitReturnRequest: (
+			orderId: string,
+			input?: CustomerReturnRequestInput,
+		) => controller().submitReturnRequest(orderId, input),
+		contactCompany: (input: CustomerContactCompanyInput) =>
+			controller().contactCompany(input),
+	};
+}