@businessdash/sdk 0.9.60 → 0.9.70

package/src/data-model-schema.ts

@@ -2640,7 +2640,7 @@ export type FindFieldTypeByPath<
 	C extends readonly CollectionDefinition[],
 > =
 	C[number] extends CollectionDefinition<infer F>
-		? Path extends `${infer N}.${infer K}`
+		? Path extends `${string}.${infer K}`
 			? K extends keyof F
 				? InferFieldValue<F[K]>
 				: never

package/src/element.ts

@@ -319,3 +319,105 @@ declare global {
 		"biab-form": BiabFormElement;
 	}
 }
+
+export type {
+	FollowersController,
+	FollowersSnapshot,
+	UserController,
+	UserSnapshot,
+} from "./account-core/index.js";
+export type { ChatController, ChatSnapshot } from "./chat-core/index.js";
+export type {
+	CheckoutController,
+	CheckoutSnapshot,
+} from "./checkout-core/index.js";
+export type {
+	MarketingController,
+	MarketingSnapshot,
+} from "./marketing-core/index.js";
+export type { PortalController, PortalSnapshot } from "./portal-core/index.js";
+export type { StoreController, StoreSnapshot } from "./store-core/index.js";
+// The native (non-iframe) storefront and chat controllers. `<biab-form>` is a
+// custom element because forms need DOM; a storefront controller does not, so
+// it is re-exported as-is from the framework-free binding rather than wrapped
+// in an element that would only get in the way.
+export {
+	type CreateChatOptions,
+	type CreateStorefrontOptions,
+	createChat,
+	createCheckout,
+	createFollowers,
+	createMarketing,
+	createPortal,
+	createStorefront,
+	createUser,
+	createVerify,
+	signIn,
+	signInHref,
+	signOut,
+	signOutHref,
+	signUp,
+	signUpHref,
+} from "./vanilla.js";
+export type {
+	VerifyController,
+	VerifyFlow,
+	VerifySnapshot,
+} from "./verify-core/index.js";
+
+import { mountSocialLinks } from "./vanilla.js";
+
+export type { SocialLinkRow } from "./social-core/index.js";
+export { mountSocialLinks, resolveSocialLinks } from "./vanilla.js";
+
+/**
+ * `<biab-social-links>` — the social block as a custom element.
+ *
+ * Attributes: `color`, `size`, `link-class`, `icon-class`. The `socials` record
+ * is a PROPERTY rather than an attribute, because it is an object and an
+ * attribute would mean stringifying it:
+ *
+ * ```js
+ * const el = document.querySelector("biab-social-links");
+ * el.socials = company.socials;
+ * ```
+ */
+export class BiabSocialLinksElement extends HTMLElement {
+	#socials: unknown = null;
+
+	set socials(value: unknown) {
+		this.#socials = value;
+		this.#render();
+	}
+	get socials(): unknown {
+		return this.#socials;
+	}
+
+	connectedCallback(): void {
+		this.#render();
+	}
+
+	#render(): void {
+		const size = Number(this.getAttribute("size") ?? 20);
+		mountSocialLinks(this, {
+			socials: this.#socials,
+			...(this.getAttribute("color")
+				? { color: this.getAttribute("color") as string }
+				: {}),
+			size: Number.isFinite(size) ? size : 20,
+			...(this.getAttribute("link-class")
+				? { linkClass: this.getAttribute("link-class") as string }
+				: {}),
+			...(this.getAttribute("icon-class")
+				? { iconClass: this.getAttribute("icon-class") as string }
+				: {}),
+		});
+	}
+}
+
+/** Register `<biab-social-links>`. Safe to call more than once. */
+export function defineBiabSocialLinks(tagName = "biab-social-links"): void {
+	if (typeof customElements === "undefined") return;
+	if (customElements.get(tagName)) return;
+	customElements.define(tagName, BiabSocialLinksElement);
+}

package/src/embed-protocol.ts

@@ -0,0 +1,100 @@
+/**
+ * The postMessage protocol shared by every embed surface, and the guard that
+ * decides which messages are trusted.
+ *
+ * This lives in its own framework-free module because more than one binding
+ * renders these iframes. The React binding had it inline, and copying it into
+ * the Solid binding would have meant two implementations of an ORIGIN CHECK —
+ * the kind of duplication where the copies drift and the weaker one silently
+ * becomes the security posture of whichever framework a customer happened to
+ * pick. One implementation, imported by both.
+ *
+ * @module
+ */
+
+/** Every event a BusinessDash embed posts to its host page. */
+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 };
+
+/**
+ * The sandbox tokens every embed iframe gets. Checkout adds
+ * `allow-top-navigation` so Stripe can take over the tab.
+ */
+export const DEFAULT_EMBED_SANDBOX =
+	"allow-scripts allow-forms allow-same-origin allow-popups";
+
+/**
+ * Listen for embed messages on `window` and hand the trusted ones to `handler`.
+ * Returns an unsubscribe function, which each binding wires to its own cleanup
+ * (`useEffect` teardown in React, `onCleanup` in Solid).
+ *
+ * `getIframe` is a callback rather than an element because the iframe may not
+ * exist yet when the listener is attached, and because a re-render can swap it.
+ * When it resolves to an element, messages from any other window are dropped —
+ * that check is the whole point of this function.
+ */
+export function subscribeToEmbedMessages(
+	getIframe: () => HTMLIFrameElement | null | undefined,
+	handler: (event: BiabEmbedEvent) => void,
+): () => void {
+	if (typeof window === "undefined") return () => {};
+
+	const onMessage = (e: MessageEvent) => {
+		if (!e.data || typeof e.data !== "object") return;
+		if ((e.data as { kind?: string }).kind !== "biab") return;
+		const iframe = getIframe();
+		if (iframe && e.source !== null && e.source !== iframe.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);
+}
+
+/** The session shape every embed surface resolves to before it can render. */
+export type EmbedSessionState<T> =
+	| { status: "idle" }
+	| { status: "loading" }
+	| { status: "ready"; session: T }
+	| { status: "error"; error: Error };
+
+/**
+ * When to refresh a session, in ms from now. Sessions carry an `expiresAt`;
+ * both bindings refresh `refreshLeadMs` before it, with a 1s floor so a
+ * clock skew or an already-expired session can't spin.
+ */
+export function refreshDelayMs(
+	expiresAt: string,
+	refreshLeadMs: number,
+	now: number,
+): number | null {
+	const expiry = Date.parse(expiresAt);
+	if (Number.isNaN(expiry)) return null;
+	return Math.max(1_000, expiry - now - refreshLeadMs);
+}
+
+export const DEFAULT_REFRESH_LEAD_MS = 30_000;

package/src/framework-support.ts

@@ -0,0 +1,440 @@
+/**
+ * Which framework versions each adapter supports — one source of truth,
+ * consumed by `package.json` peer ranges, the docs matrix, and (later) the
+ * runtime mismatch warning.
+ *
+ * WHY THIS EXISTS
+ *
+ * Frameworks break their own APIs. When one ships a major that reworks
+ * reactivity or JSX, an adapter written against the old dialect stops
+ * compiling for anyone who upgrades — and, just as bad, our docs keep showing
+ * one implementation as if it were universal. A developer on the new major
+ * follows a page that silently describes the old one.
+ *
+ * The blast radius is already small by design: every binding is a thin view
+ * over the framework-agnostic core (`createFormController` in
+ * `@businessdash/sdk/forms`). Values, validation, conditional visibility,
+ * multi-step navigation, uploads and submit lifecycle all live there and
+ * survive any framework major untouched. Only the binding layer — how an
+ * external store becomes reactive state, and how a list renders — is
+ * version-sensitive.
+ *
+ * `frameworkApis` names exactly which imports each binding leans on, so when
+ * a major lands the question "does this break us?" is a diff against a list
+ * rather than a reread of 1,400 lines.
+ *
+ * WHEN A MAJOR BREAKS AN ADAPTER
+ *
+ * Add a second entry for the same adapter with the new range and a distinct
+ * `dialect`, rather than rewriting the existing one. Both ship; the docs show
+ * both; consumers on either major get working code. Retire the old entry only
+ * when that major is genuinely out of support.
+ */
+
+export type FrameworkSupport = {
+	/** Subpath consumers import, e.g. `@businessdash/sdk/solid`. */
+	entry: string;
+	/** npm package the adapter binds to. */
+	pkg: string;
+	/** Semver range this adapter is written against and tested on. */
+	range: string;
+	/**
+	 * Distinguishes two adapters for the same framework across a breaking
+	 * major. `default` until a second dialect is needed.
+	 */
+	dialect: string;
+	/**
+	 * SOURCE ships uncompiled and is built by the consumer's toolchain (so
+	 * their compiler version matters); COMPILED ships as JS from our build.
+	 */
+	shipMode: "source" | "compiled";
+	/**
+	 * The framework imports this binding depends on. A breaking major is
+	 * assessed by diffing this list against the framework's changelog.
+	 */
+	frameworkApis: readonly string[];
+	/** `supported` = tested. `untested` = expected to work, unverified. */
+	status: "supported" | "untested" | "deprecated";
+	/**
+	 * What this adapter can actually DO, and — just as important — HOW.
+	 *
+	 * A capability recorded as `embed` is a BusinessDash-hosted page in a
+	 * sandboxed iframe. It works, but it renders our markup inside your app, not
+	 * yours. `native` means real components rendering into your own DOM, themed
+	 * by your own CSS. Collapsing the two into a yes/no would let a binding that
+	 * only wraps an iframe claim the same support as one with real components —
+	 * which is exactly how `chatbot` briefly looked equal on React and Solid when
+	 * React has 1,200 lines of headless chat UI and Solid has an iframe.
+	 *
+	 * This map is the single source of truth for that claim: the docs matrix
+	 * renders it, and `test/framework-parity.test.ts` derives the same levels
+	 * from the source and asserts they agree — so the page cannot promise a
+	 * capability, or a level of it, the adapter doesn't have.
+	 */
+	capabilities: CapabilityMatrix;
+	notes?: string;
+};
+
+/** The capability areas an adapter can expose. See `CAPABILITY_LABELS`. */
+export type Capability =
+	| "forms"
+	| "client-di"
+	| "chatbot"
+	| "auth"
+	| "storefront"
+	| "cart"
+	| "checkout"
+	| "blog"
+	| "customer-portal"
+	| "marketing-pages"
+	| "followers"
+	| "social-links"
+	| "email-verify"
+	| "phone-verify";
+
+/**
+ * HOW a capability is delivered.
+ *
+ *   `native` — components/hooks rendering into the consumer's own DOM.
+ *   `embed`  — a BusinessDash-hosted page in a sandboxed iframe.
+ *   `both`   — the surface exists in both forms (e.g. React's chat: an iframe
+ *              widget AND a headless hook for hosts rendering their own UI).
+ */
+export type CapabilityLevel = "native" | "embed" | "both";
+
+export type CapabilityMatrix = Readonly<
+	Partial<Record<Capability, CapabilityLevel>>
+>;
+
+/** Human-readable names, in the order the docs table renders them. */
+export const CAPABILITY_LABELS: Readonly<Record<Capability, string>> = {
+	forms: "Forms",
+	"client-di": "Shared client",
+	chatbot: "AI chat",
+	auth: "Customer auth",
+	storefront: "Storefront",
+	cart: "Cart",
+	checkout: "Checkout",
+	blog: "Blog",
+	"customer-portal": "Customer portal",
+	"marketing-pages": "Marketing pages",
+	followers: "Followers",
+	"social-links": "Social links",
+	"email-verify": "Email verification",
+	"phone-verify": "Phone verification",
+};
+
+export const ALL_CAPABILITIES = Object.keys(CAPABILITY_LABELS) as Capability[];
+
+/**
+ * Everything `@businessdash/sdk/react` exposes — the full product.
+ *
+ * Note how much of it is `embed`: storefront, cart and blog are hosted pages in
+ * every binding INCLUDING React. No framework has a native storefront, so on
+ * those surfaces the other bindings are not behind — there is simply nothing
+ * more to have yet.
+ */
+const FULL_SURFACE: CapabilityMatrix = {
+	forms: "native",
+	"client-di": "native",
+	chatbot: "both",
+	auth: "native",
+	// `both`: the hosted iframe widget AND the headless controller. The native
+	// path is `useStorefront` / `useChatbot` over `store-core` / `chat-core`.
+	storefront: "both",
+	cart: "both",
+	checkout: "both",
+	blog: "both",
+	"customer-portal": "both",
+	"marketing-pages": "native",
+	followers: "native",
+	"social-links": "native",
+	"email-verify": "native",
+	"phone-verify": "native",
+};
+
+/**
+ * Forms, a shared client, and the two native surfaces every binding now has.
+ *
+ * `storefront`, `cart` and `chatbot` are `native` rather than `both` here: these
+ * bindings expose the headless controllers, not the hosted iframe widgets. They
+ * render into the consumer's own DOM, which is the harder and better half.
+ */
+const FORMS_AND_CLIENT: CapabilityMatrix = {
+	forms: "native",
+	"client-di": "native",
+	storefront: "native",
+	cart: "native",
+	chatbot: "native",
+	blog: "native",
+	auth: "native",
+	checkout: "native",
+	followers: "native",
+	"marketing-pages": "native",
+	"email-verify": "native",
+	"phone-verify": "native",
+	"social-links": "native",
+	"customer-portal": "native",
+};
+
+export const FRAMEWORK_SUPPORT: readonly FrameworkSupport[] = [
+	{
+		entry: "@businessdash/sdk/react",
+		pkg: "react",
+		range: ">=18.0.0 <20",
+		dialect: "default",
+		shipMode: "compiled",
+		frameworkApis: [
+			"useSyncExternalStore",
+			"useState",
+			"useMemo",
+			"useEffect",
+			"useId",
+			"createContext",
+			"useContext",
+		],
+		capabilities: FULL_SURFACE,
+		status: "supported",
+	},
+	{
+		entry: "@businessdash/sdk/solid",
+		pkg: "solid-js",
+		range: ">=1.8.0 <2",
+		dialect: "v1",
+		shipMode: "source",
+		frameworkApis: [
+			"from",
+			"createSignal",
+			"createMemo",
+			"createContext",
+			"useContext",
+			"createUniqueId",
+			"onMount",
+			"onCleanup",
+			"For",
+			"Show",
+			"Switch",
+			"Match",
+		],
+		capabilities: {
+			forms: "native",
+			"client-di": "native",
+			// The hosted widget plus `createChat`. React additionally ships
+			// `<ChatbotInline>`, a rendered chat UI that Solid does not have — the
+			// headless controller beneath them is the same.
+			chatbot: "both",
+			auth: "native",
+			storefront: "both",
+			cart: "both",
+			checkout: "both",
+			blog: "both",
+			"customer-portal": "both",
+			followers: "native",
+			"social-links": "native",
+			"marketing-pages": "native",
+			"email-verify": "native",
+			"phone-verify": "native",
+		},
+		status: "supported",
+		notes:
+			"Solid 2.0 shipped 2026-08 with a substantial API rework. This adapter is written against the 1.x dialect and is NOT yet verified on 2.x — a `v2` entry alongside this one is the intended shape, not a rewrite of it.",
+	},
+	{
+		entry: "@businessdash/sdk/vue",
+		pkg: "vue",
+		range: ">=3.3.0 <4",
+		dialect: "default",
+		shipMode: "source",
+		frameworkApis: [
+			"defineComponent",
+			"ref",
+			"computed",
+			"onMounted",
+			"onUnmounted",
+			"provide",
+			"inject",
+			"h",
+		],
+		capabilities: FORMS_AND_CLIENT,
+		status: "supported",
+	},
+	{
+		entry: "@businessdash/sdk/svelte",
+		pkg: "svelte",
+		range: ">=5.0.0 <6",
+		dialect: "runes",
+		shipMode: "source",
+		frameworkApis: ["$state", "$derived", "$effect", "onMount", "onDestroy"],
+		capabilities: FORMS_AND_CLIENT,
+		status: "supported",
+		notes:
+			"Written against Svelte 5 runes. Svelte 4's store-based dialect is a separate entry if it's ever needed.",
+	},
+	{
+		entry: "@businessdash/sdk/qwik",
+		pkg: "@builder.io/qwik",
+		range: ">=1.5.0 <2",
+		dialect: "default",
+		shipMode: "source",
+		frameworkApis: [
+			"component$",
+			"useSignal",
+			"useStore",
+			"useVisibleTask$",
+			"useComputed$",
+		],
+		capabilities: {
+			forms: "native",
+			storefront: "native",
+			cart: "native",
+			chatbot: "native",
+			blog: "native",
+			auth: "native",
+			checkout: "native",
+			followers: "native",
+			"marketing-pages": "native",
+			"email-verify": "native",
+			"phone-verify": "native",
+			"social-links": "native",
+			"customer-portal": "native",
+		},
+		status: "untested",
+	},
+	{
+		entry: "@businessdash/sdk/angular",
+		pkg: "@angular/core",
+		range: ">=17.0.0",
+		dialect: "standalone",
+		shipMode: "source",
+		frameworkApis: ["Component", "signal", "computed", "effect", "inject"],
+		capabilities: FORMS_AND_CLIENT,
+		status: "untested",
+		notes: "Written against standalone components + signals (Angular 17+).",
+	},
+	{
+		entry: "@businessdash/sdk/vanilla",
+		pkg: "(none)",
+		range: "*",
+		dialect: "default",
+		shipMode: "compiled",
+		frameworkApis: [],
+		capabilities: {
+			forms: "native",
+			storefront: "native",
+			cart: "native",
+			chatbot: "native",
+			blog: "native",
+			auth: "native",
+			checkout: "native",
+			followers: "native",
+			"marketing-pages": "native",
+			"email-verify": "native",
+			"phone-verify": "native",
+			"social-links": "native",
+			"customer-portal": "native",
+		},
+		status: "supported",
+		notes:
+			"No framework dependency — the fallback that cannot be broken by anyone else's major.",
+	},
+	{
+		entry: "@businessdash/sdk/element",
+		pkg: "(none)",
+		range: "*",
+		dialect: "default",
+		shipMode: "compiled",
+		frameworkApis: ["customElements"],
+		capabilities: FORMS_AND_CLIENT,
+		status: "supported",
+		notes:
+			"Web component. Works inside any framework, and is the recommended escape hatch when a framework major outpaces its adapter.",
+	},
+];
+
+/** All adapters for one framework package — several when majors diverge. */
+export function supportFor(pkg: string): readonly FrameworkSupport[] {
+	return FRAMEWORK_SUPPORT.filter((f) => f.pkg === pkg);
+}
+
+/**
+ * REACT-COMPATIBLE TARGETS.
+ *
+ * These are not separate adapters and never will be: they render React (or a
+ * drop-in replacement for it), so they import `@businessdash/sdk/react` and get
+ * the FULL surface — all fourteen capabilities, not the forms-only subset the
+ * non-React bindings have. Someone choosing Next, Astro or Preact is not
+ * choosing a smaller SDK.
+ *
+ * They are listed because that was not previously discoverable anywhere. The
+ * adapter table names eight bindings and says nothing about the meta-frameworks
+ * most people actually build on, so "does Next work?" had no documented answer.
+ *
+ * `requires` is the per-target integration detail — the thing that bites on day
+ * one, not a general description.
+ */
+export type ReactTarget = {
+	/** Framework name as its own docs spell it. */
+	name: string;
+	/** Which SDK entry point to import. */
+	entry: string;
+	/** What the consumer must do to make it work in that framework. */
+	requires: string;
+	/** Starter template that exercises it, under `SDK-Starter-Templates/`. */
+	starter?: string;
+	status: "supported" | "untested";
+};
+
+export const REACT_TARGETS: readonly ReactTarget[] = [
+	{
+		name: "React",
+		entry: "@businessdash/sdk/react",
+		requires: "Nothing — import and render.",
+		starter: "React-Bun",
+		status: "supported",
+	},
+	{
+		name: "Next.js (App Router)",
+		entry: "@businessdash/sdk/react",
+		requires:
+			'Nothing as of 0.9.61 — the adapter now carries its own `"use client"` boundary, so components import directly into a server-rendered page. Before that, every component needed a hand-written client wrapper.',
+		starter: "T3-App",
+		status: "supported",
+	},
+	{
+		name: "Astro",
+		entry: "@businessdash/sdk/react",
+		requires:
+			"`@astrojs/react`, and a client directive on the island (`<ContactForm client:load />`) — without one Astro renders it to static HTML and no handler ever attaches.",
+		starter: "Astro",
+		status: "supported",
+	},
+	{
+		name: "Remix / React Router 7",
+		entry: "@businessdash/sdk/react",
+		requires: "Nothing — no RSC boundary to cross.",
+		starter: "Remix",
+		status: "supported",
+	},
+	{
+		name: "TanStack Start",
+		entry: "@businessdash/sdk/react",
+		requires: "Nothing — no RSC boundary to cross.",
+		starter: "Tanstack-Start",
+		status: "supported",
+	},
+	{
+		name: "Preact",
+		entry: "@businessdash/sdk/react",
+		requires:
+			"The standard `preact/compat` alias in your bundler — nothing SDK-specific. The binding imports nine runtime symbols from `react` and never imports `react-dom`, so it is renderer-agnostic; `test/preact-compat.test.ts` renders components on both and asserts identical markup.",
+		status: "supported",
+	},
+	{
+		name: "React Native / Expo",
+		entry: "@businessdash/sdk/native",
+		requires:
+			"The `native` entry, not `react` — the DOM components don't render there. Data access and auth are shared; the UI is yours.",
+		starter: "React-Native",
+		status: "supported",
+	},
+];