@businessdash/sdk 0.9.60

package/src/sdk.ts

@@ -0,0 +1,1671 @@
+/**
+ * High-level SDK surface — what the consumer actually writes against.
+ *
+ * The principle: the consumer authors design + granular data requests,
+ * and that's it. Auth, caching, revalidation, tagging, retries — all
+ * handled inside this module so the consumer code reads as:
+ *
+ *   const items = await biab.gallery.list({
+ *     limit: 12,
+ *     fields: ["src", "title", "category", "blurDataURL"],
+ *   });
+ *
+ * Auto-applied per request:
+ *   • `Authorization: Bearer <apiKey>`
+ *   • `next: { tags: ["biab:<resource>", "biab:site:<orgId-when-known>"],
+ *              revalidate: <longBackstop> }`  — invisible on non-Next
+ *     runtimes that ignore the `next` key
+ *   • Field selection forwarded as `?fields=…` so the platform
+ *     SELECTs only what's needed.
+ *
+ * The companion `@businessdash/sdk/next/revalidate` route export closes
+ * the loop: when BIAB POSTs `content.published`, the route handler
+ * verifies the HMAC and calls `revalidateTag(...)` to bust the local
+ * Next cache. End-to-end, the consumer wrote ~5 lines.
+ */
+
+import {
+	BiabDevAddressClient,
+	BiabDevBlogClient,
+	BiabDevCartClient,
+	BiabDevCheckoutClient,
+	BiabDevClient,
+	BiabDevCouponsClient,
+	BiabDevCustomerPortalClient,
+	BiabDevFollowersClient,
+	BiabDevMarketingClient,
+	BiabDevMarketingPagesClient,
+	BiabDevNotificationsClient,
+	BiabDevParallelPagesClient,
+	BiabDevReviewsClient,
+	BiabDevShippingClient,
+	BiabDevStorefrontClient,
+	BiabDevSubscriptionsClient,
+} from "./client.js";
+import {
+	getEmailDomain,
+	isConsumerEmailDomain,
+} from "./forms-core/email-domains.js";
+import type { BundleGalleryItem } from "./gallery-types.js";
+
+// Apex host on purpose: www.biab.app 307-redirects to the apex and CORS
+// preflight doesn't follow redirects, which breaks browser publishable-token
+// clients. Server-side callers are unaffected, but one default keeps them aligned.
+const DEFAULT_BASE_URL = "https://biab.app/api/package/v1";
+const DEFAULT_REVALIDATE_SECONDS = 60 * 60 * 24; // 24h backstop
+
+export interface CreateBiabClientOptions {
+	apiKey: string;
+	siteId: string;
+	baseUrl?: string;
+	/** Override the default 24h ISR backstop. */
+	revalidateSeconds?: number;
+	/** Custom fetch (testing, instrumentation, edge runtimes). */
+	fetch?: typeof fetch;
+	/**
+	 * Optional `Origin` to forward — required when the API key has an
+	 * Allowed Host configured on the platform (server-to-server fetch
+	 * does not send `Origin` automatically).
+	 */
+	siteOrigin?: string;
+}
+
+type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+
+interface InternalState {
+	apiKey: string;
+	siteId: string;
+	baseUrl: string;
+	revalidateSeconds: number;
+	fetch: Fetcher;
+	siteOrigin: string | undefined;
+}
+
+function buildHeaders(state: InternalState): Record<string, string> {
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${state.apiKey}`,
+		Accept: "application/json",
+	};
+	if (state.siteOrigin) headers["Origin"] = state.siteOrigin;
+	return headers;
+}
+
+function buildNextHint(tags: string[], seconds: number) {
+	// `next` is a Next.js-only field on RequestInit. Non-Next runtimes
+	// (Cloudflare Workers, Deno, raw Node fetch) ignore it cleanly.
+	return { tags, revalidate: seconds } as const;
+}
+
+async function jsonGet<T>(
+	state: InternalState,
+	pathWithQuery: string,
+	tags: string[],
+): Promise<T> {
+	const url = `${state.baseUrl.replace(/\/$/, "")}/${pathWithQuery.replace(/^\//, "")}`;
+	const init: RequestInit & { next?: unknown } = {
+		method: "GET",
+		headers: buildHeaders(state),
+		next: buildNextHint(tags, state.revalidateSeconds),
+	};
+	const res = await state.fetch(url, init);
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new Error(
+			`BIAB SDK ${res.status} ${res.statusText} on ${pathWithQuery}: ${text.slice(0, 200)}`,
+		);
+	}
+	return (await res.json()) as T;
+}
+
+// ---------------------------------------------------------------------------
+// Gallery resource
+// ---------------------------------------------------------------------------
+
+export type GalleryField = keyof BundleGalleryItem;
+
+export interface GalleryListParams<F extends readonly GalleryField[]> {
+	limit?: number;
+	fields?: F;
+}
+
+export type GalleryItemFor<F extends readonly GalleryField[]> = {
+	[K in F[number]]: BundleGalleryItem[K];
+};
+
+export interface GalleryResource {
+	list<const F extends readonly GalleryField[]>(
+		params?: GalleryListParams<F>,
+	): Promise<GalleryItemFor<F>[]>;
+}
+
+function createGalleryResource(state: InternalState): GalleryResource {
+	return {
+		async list<const F extends readonly GalleryField[]>(
+			params?: GalleryListParams<F>,
+		): Promise<GalleryItemFor<F>[]> {
+			const query = new URLSearchParams();
+			if (params?.limit) query.set("limit", String(params.limit));
+			if (params?.fields && params.fields.length > 0) {
+				query.set("fields", params.fields.join(","));
+			}
+			const qs = query.toString();
+			const path = `sites/${encodeURIComponent(state.siteId)}/gallery${qs ? `?${qs}` : ""}`;
+			const tags = ["biab:gallery", `biab:site:${state.siteId}`];
+			// The server projects to exactly the requested `fields`, so the row
+			// shape is `GalleryItemFor<F>` — a fact only the wire can vouch for.
+			// Stating it as the fetch's type argument confines the assumption to
+			// this one boundary. The previous `as never` was strictly worse: it
+			// asserted the items were assignable to *anything*, so a genuine
+			// mismatch between projection and type would never have shown up.
+			const result = await jsonGet<{ items: GalleryItemFor<F>[] }>(
+				state,
+				path,
+				tags,
+			);
+			return result.items ?? [];
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Scheduling resource — full Calendly-shape booking flow
+// ---------------------------------------------------------------------------
+
+/**
+ * Public-facing shape of an event type the consumer renders into a
+ * "book a meeting" page. Matches `/sites/{siteId}/scheduling/event-types`.
+ */
+export interface SchedulingEventType {
+	id: string;
+	name: string;
+	slug: string;
+	description: string | null;
+	durationMinutes: number;
+	locationType: string;
+	meetingProvider: string | null;
+	color: string | null;
+	requiresApproval: boolean;
+}
+
+export interface SchedulingQuestion {
+	id: string;
+	label: string;
+	fieldType: string;
+	optionsJson: unknown;
+	isRequired: boolean;
+	sortOrder: number;
+}
+
+/**
+ * A booking as returned by `getBookingByToken`.
+ *
+ * Timestamps are ISO-8601 **strings**. The server holds them as `Date` and
+ * they cross the wire as JSON, so typing them `Date` here would compile and
+ * then fail at runtime on the first `.getTime()`.
+ */
+export interface SchedulingBookingView {
+	booking: {
+		id: string;
+		startAt: string;
+		endAt: string;
+		status: SchedulingBookingStatus;
+		title: string;
+		notes: string | null;
+		conferenceLink: string | null;
+	};
+	invitee: { name: string; email: string; timezone: string } | null;
+	eventType: {
+		name: string;
+		slug: string;
+		durationMinutes: number;
+		locationType: string;
+	} | null;
+}
+
+/** What `rescheduleBooking` echoes back — the booking's new window. */
+export interface SchedulingRescheduleResult {
+	bookingId: string;
+	startAt: string;
+	endAt: string;
+}
+
+export interface SchedulingSlot {
+	startAt: string;
+	endAt: string;
+}
+
+export interface SchedulingInvitee {
+	email: string;
+	name: string;
+	phone?: string | null;
+	timezone: string;
+}
+
+export interface SchedulingAnswer {
+	questionId: string;
+	valueText: string;
+}
+
+/**
+ * Booking lifecycle states, mirroring the `booking_status` pg enum.
+ *
+ * Note the spelling: the platform stores **`canceled`** (one L). This type
+ * previously read `"pending" | "confirmed" | "cancelled" | string`, which was
+ * wrong twice over — the two-L spelling matches nothing the server ever
+ * sends, and the trailing `| string` widened the union back to `string` so
+ * neither the typo nor the missing `no_show` could ever surface. Keep this
+ * closed; a new state should land here as a deliberate edit.
+ */
+export type SchedulingBookingStatus =
+	| "confirmed"
+	| "pending"
+	| "canceled"
+	| "no_show";
+
+export interface SchedulingBookingResult {
+	bookingId: string;
+	status: SchedulingBookingStatus;
+	manageToken: string;
+	rescheduleToken: string;
+	cancelToken: string;
+	payment: {
+		clientSecret: string;
+		amountCents: number;
+		currency: string;
+	} | null;
+}
+
+export interface SchedulingResource {
+	listEventTypes(): Promise<SchedulingEventType[]>;
+	getEventType(slug: string): Promise<{
+		eventType: SchedulingEventType;
+		questions: SchedulingQuestion[];
+	}>;
+	getAvailableSlots(
+		slug: string,
+		params: { from: Date; to: Date },
+	): Promise<SchedulingSlot[]>;
+	confirmBooking(input: {
+		eventTypeSlug: string;
+		startAt: Date;
+		invitee: SchedulingInvitee;
+		answers?: SchedulingAnswer[];
+		notes?: string | null;
+		schedulingLinkId?: string;
+		holderKey?: string | null;
+	}): Promise<SchedulingBookingResult>;
+	getBookingByToken(
+		token: string,
+		type?: "manage" | "cancel" | "reschedule",
+	): Promise<SchedulingBookingView>;
+	rescheduleBooking(input: {
+		token: string;
+		newStartAt: Date;
+		reason?: string | null;
+	}): Promise<SchedulingRescheduleResult>;
+	cancelBooking(input: {
+		token: string;
+		reason?: string | null;
+	}): Promise<{ ok: true }>;
+}
+
+function createSchedulingResource(state: InternalState): SchedulingResource {
+	const sitePath = `sites/${encodeURIComponent(state.siteId)}/scheduling`;
+	async function postJson<T>(
+		path: string,
+		body: unknown,
+		tags: string[],
+	): Promise<T> {
+		const url = `${state.baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+		const init: RequestInit & { next?: unknown } = {
+			method: "POST",
+			headers: { ...buildHeaders(state), "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+			next: { tags, revalidate: 0 },
+		};
+		const res = await state.fetch(url, init);
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(
+				`BIAB SDK ${res.status} ${res.statusText} on ${path}: ${text.slice(0, 200)}`,
+			);
+		}
+		return (await res.json()) as T;
+	}
+	return {
+		async listEventTypes() {
+			const tags = ["biab:scheduling", `biab:site:${state.siteId}`];
+			const result = await jsonGet<{ items: SchedulingEventType[] }>(
+				state,
+				`${sitePath}/event-types`,
+				tags,
+			);
+			return result.items ?? [];
+		},
+		async getEventType(slug) {
+			const tags = [
+				"biab:scheduling",
+				`biab:scheduling:event:${slug}`,
+				`biab:site:${state.siteId}`,
+			];
+			return await jsonGet(
+				state,
+				`${sitePath}/event-types/${encodeURIComponent(slug)}`,
+				tags,
+			);
+		},
+		async getAvailableSlots(slug, params) {
+			const query = new URLSearchParams({
+				from: params.from.toISOString(),
+				to: params.to.toISOString(),
+			});
+			const path = `${sitePath}/event-types/${encodeURIComponent(slug)}/slots?${query.toString()}`;
+			// Slots are dynamic — no caching, no tags. revalidate: 0 keeps
+			// Next from applying the default backstop.
+			const url = `${state.baseUrl.replace(/\/$/, "")}/${path}`;
+			const init: RequestInit & { next?: unknown } = {
+				method: "GET",
+				headers: buildHeaders(state),
+				next: { revalidate: 0 },
+				cache: "no-store",
+			};
+			const res = await state.fetch(url, init);
+			if (!res.ok) {
+				const text = await res.text().catch(() => "");
+				throw new Error(
+					`BIAB SDK ${res.status} ${res.statusText} on ${path}: ${text.slice(0, 200)}`,
+				);
+			}
+			const data = (await res.json()) as { slots: SchedulingSlot[] };
+			return data.slots ?? [];
+		},
+		async confirmBooking(input) {
+			return await postJson<SchedulingBookingResult>(
+				`${sitePath}/bookings`,
+				{
+					eventTypeSlug: input.eventTypeSlug,
+					startAt: input.startAt.toISOString(),
+					invitee: input.invitee,
+					answers: input.answers,
+					notes: input.notes ?? null,
+					schedulingLinkId: input.schedulingLinkId,
+					holderKey: input.holderKey ?? null,
+				},
+				[],
+			);
+		},
+		async getBookingByToken(token, type = "manage") {
+			const path = `${sitePath}/bookings/${encodeURIComponent(token)}?type=${type}`;
+			const url = `${state.baseUrl.replace(/\/$/, "")}/${path}`;
+			const res = await state.fetch(url, {
+				method: "GET",
+				headers: buildHeaders(state),
+				cache: "no-store",
+			});
+			if (!res.ok) {
+				const text = await res.text().catch(() => "");
+				throw new Error(
+					`BIAB SDK ${res.status} ${res.statusText}: ${text.slice(0, 200)}`,
+				);
+			}
+			return (await res.json()) as SchedulingBookingView;
+		},
+		async rescheduleBooking(input) {
+			return await postJson<SchedulingRescheduleResult>(
+				`${sitePath}/bookings/${encodeURIComponent(input.token)}`,
+				{
+					action: "reschedule",
+					newStartAt: input.newStartAt.toISOString(),
+					reason: input.reason ?? null,
+				},
+				[],
+			);
+		},
+		async cancelBooking(input) {
+			return await postJson<{ ok: true }>(
+				`${sitePath}/bookings/${encodeURIComponent(input.token)}`,
+				{
+					action: "cancel",
+					reason: input.reason ?? null,
+				},
+				[],
+			);
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Forms resource — schema export + runtime validator
+// ---------------------------------------------------------------------------
+
+/**
+ * Public-facing description of one form field. Mirrors BIAB's
+ * `FormField` type so the consumer can type their submission payload
+ * against the schema fetched at runtime.
+ */
+export interface FormFieldDef {
+	id: string;
+	/**
+	 * Stable, human-readable output key for this field's value (camelCase or
+	 * snake_case, per the form's configuration). Prefer this when building the
+	 * submission payload. The server also accepts the UUID `id` for back-compat,
+	 * so older integrations keep working.
+	 */
+	key?: string;
+	label: string;
+	type: string;
+	required: boolean;
+	/**
+	 * Consent semantic for `type === "boolean"`: the value must be `true` to
+	 * submit (e.g. "I agree"). Independent of `display`. When false/unset, an
+	 * optional/required boolean accepts true OR false.
+	 */
+	mustBeTrue?: boolean;
+	/** Boolean UI variant: "toggle" (default switch) or "checkbox". */
+	display?: "toggle" | "checkbox";
+	/**
+	 * select / radio / checkbox: an "Other…" free-text value outside `options`
+	 * is allowed. When true, the value may be any string (single) or include a
+	 * non-option string (checkbox array); the options whitelist isn't enforced.
+	 */
+	allowCustom?: boolean;
+	placeholder?: string;
+	helpText?: string;
+	options?: string[];
+	regexPattern?: string;
+	validation?: { min?: number; max?: number };
+	/**
+	 * Set on file-type fields (`type === "file_upload"`). The SDK
+	 * uploader enforces these client-side as a UX nicety; the
+	 * server is the source of truth and re-enforces them when
+	 * minting the upload URL.
+	 */
+	fileConfig?: {
+		allowedTypes?: string[];
+		maxFiles?: number;
+		maxSize?: number;
+	};
+	/** Phone-field config — `international` switches the digit-count rule. */
+	phoneConfig?: {
+		international?: boolean;
+	};
+	/**
+	 * choice_cards config: a set of selectable cards. `single` = radio semantics
+	 * (value is the chosen option `label`); `multi` = checkbox semantics (value is
+	 * a `string[]` of chosen labels). Options may carry richer card content
+	 * (image/price/description/etc.) for showcasing a product or service — that
+	 * content is display + metadata only; the submitted value is always the
+	 * `label`, so validation is unaffected by the extra fields.
+	 */
+	choiceConfig?: {
+		mode?: "single" | "multi";
+		options?: Array<{
+			label: string;
+			/** Lucide icon name (kebab-case, e.g. "phone"). */
+			icon?: string;
+			/** Image to show on the card (URL). */
+			imageUrl?: string;
+			/** Display price string (e.g. "$49/mo"). */
+			price?: string;
+			/** Short supporting description shown under the label. */
+			description?: string;
+			/** Your catalog id for this option (product/service) — metadata only. */
+			productId?: string;
+			/** Optional link for the card (e.g. a product detail page). */
+			href?: string;
+		}>;
+	};
+	/**
+	 * Display content for static elements. For `richtext` this is
+	 * server-sanitized HTML; for `body_text` it is plain text. Carries no
+	 * submitted value.
+	 */
+	content?: string;
+	/**
+	 * `bullet_list` display element. `variant: "bullets"` → optional `title` +
+	 * plain bullet `items[].text`; `variant: "details"` → one row per point with
+	 * an optional Lucide `icon`, a `text` heading, and a `description`. Display
+	 * only — carries no submitted value.
+	 */
+	listConfig?: {
+		variant?: "bullets" | "details";
+		title?: string;
+		items?: Array<{ text: string; description?: string; icon?: string }>;
+	};
+	/**
+	 * `table` display element. `columns` (header / `type` "text"|"check" / align)
+	 * + `rows[].cells` aligned to columns by index; a "check" column renders ✓/–
+	 * from a truthy/falsy cell. `highlightColumn` emphasizes one column. Display
+	 * only — carries no submitted value.
+	 */
+	tableConfig?: {
+		columns?: Array<{
+			header: string;
+			type?: "text" | "check";
+			align?: "left" | "center" | "right";
+		}>;
+		rows?: Array<{ cells: string[] }>;
+		highlightColumn?: number;
+	};
+	/**
+	 * `multi_populator` repeater: the submitted value is an ARRAY of instance
+	 * records, each keyed by the child field ids/keys (same shape as a scoped
+	 * submission). `maxInstances` caps the count. The template fields live on
+	 * `children` in the rendered schema tree.
+	 */
+	populatorConfig?: {
+		maxInstances?: number;
+		minInstances?: number;
+		addButtonLabel?: string;
+		itemLabel?: string;
+	};
+	/**
+	 * `measurement` field: a number + unit. The submitted value is
+	 * `{ value, unit, base, baseUnit }` — `base` is `value` in the category's base
+	 * unit (server-computed, for downstream sorting). `outputUnit` is the org's
+	 * preferred unit (convert `base` → `outputUnit` to resolve internally).
+	 */
+	unitConfig?: {
+		category?: string;
+		units?: string[];
+		mode?: "select" | "fixed";
+		defaultUnit?: string;
+		outputUnit?: string;
+		allowDecimal?: boolean;
+	};
+	/** `number` field: when false, only whole numbers are accepted. */
+	allowDecimal?: boolean;
+	/** `number` field: when false, negatives are rejected (enforce >= 0). */
+	allowNegative?: boolean;
+	/** `currency` field: ISO code / symbol + whether negatives are allowed. */
+	currencyConfig?: {
+		currency?: string;
+		symbol?: string;
+		allowNegative?: boolean;
+		allowDecimal?: boolean;
+	};
+	/**
+	 * `calculation` (Math) element: a value computed from other fields via an
+	 * inline `formula` or a referenced business `functionId` (pick `outputKey`).
+	 * `inputMap` binds variable / function-input names to source field ids.
+	 * Non-sensitive calcs compute live client-side (using `schema.businessFunctions`
+	 * for function refs); `sensitive` ones compute server-side on submit and are
+	 * published WITHOUT their formula/def — the field shows a placeholder until
+	 * the submitted value comes back.
+	 */
+	calculationConfig?: {
+		mode?: "formula" | "function";
+		formula?: string;
+		functionId?: string;
+		outputKey?: string;
+		inputMap?: Array<{ variable: string; fieldId: string }>;
+		display?: {
+			show?: boolean;
+			prefix?: string;
+			suffix?: string;
+			decimals?: number;
+		};
+		sensitive?: boolean;
+	};
+	/**
+	 * `credit_card` element — collect a card via Stripe Elements (`<BiabForm/>`
+	 * only). `card_on_file` saves the card (SetupIntent); `deposit` charges
+	 * `amountCents` now (PaymentIntent). The card is created on the org's Stripe
+	 * connected account via `forms.paymentIntent(slug, fieldId)`; the submission
+	 * stores only the opaque intent id + brand/last4 (PCI-safe). Added in 0.9.9.
+	 */
+	paymentConfig?: {
+		mode?: "card_on_file" | "deposit";
+		amountCents?: number;
+		currency?: string;
+		buttonLabel?: string;
+		description?: string;
+	};
+	/**
+	 * `schedule` element (availability v1). The visitor states when they're free;
+	 * the submitted value is `{ asap?, days?: string[], times?: string[], notes? }`.
+	 * `<BiabForm/>` renders day + time-window chips, an ASAP toggle, and notes.
+	 * Added in 0.9.9.
+	 */
+	scheduleConfig?: {
+		mode?: "availability";
+		allowAsap?: boolean;
+		days?: string[];
+		timeWindows?: string[];
+		allowNotes?: boolean;
+	};
+}
+
+/**
+ * Value shape stored in `data` for a file field after the upload
+ * completes. The hiring mirror at `src/server/forms/hiring-mirror.ts`
+ * reads these exact fields to populate `job_application_files` — the
+ * SDK keeps the contract honest.
+ */
+export interface FormFileValue {
+	storageId: string;
+	url: string;
+	name: string;
+	mimeType: string;
+	size: number;
+}
+
+/** How the org configured the form to render — apply these for a 1:1 match. */
+export interface FormRenderSettings {
+	animation?: "none" | "fade" | "slide" | "scale" | "scroll";
+	isConsecutive?: boolean;
+	showProgress?: boolean;
+	progressStyle?: "bar" | "steps";
+	/**
+	 * Warn before the visitor abandons a dirty, unsubmitted form. `<BiabForm/>`
+	 * attaches a `beforeunload` guard when `enabled` (the browser shows a generic
+	 * prompt); `message` is provided so you can show it in your own modal too.
+	 */
+	exitConfirm?: { enabled?: boolean; message?: string };
+	/**
+	 * Present (true) only when the org's subscription (or platform-admin access)
+	 * grants link-safety checking AND the form has url fields. When absent, the
+	 * org hasn't paid for it — do no extra URL verification. The reputation scan
+	 * runs server-side on submit (it needs the platform's API key); this flag just
+	 * tells the form the feature is active so you can surface it.
+	 */
+	urlSafety?: boolean;
+}
+
+/** Action types a form can run on submit (see {@link FormActionPreview}). */
+export type FormActionType =
+	| "add_follower"
+	| "unsubscribe"
+	| "send_webhook"
+	| "autoresponder_email"
+	| "grant_coupon";
+
+/**
+ * Sanitized preview of an on-submit action — `type` + the optional condition
+ * that gates it. The action's wiring (URLs, secrets, email bodies, field
+ * mapping) stays server-side; execution happens automatically on submit. Use
+ * this to preview to the user what submitting will do (e.g. "you'll be added
+ * to the list"). Added in 0.9.7.
+ */
+export interface FormActionPreview {
+	type: FormActionType;
+	condition?: {
+		fieldId: string;
+		operator: string;
+		value?: string;
+	} | null;
+	/**
+	 * `grant_coupon` only: the display-safe coupon notice to show before submit
+	 * (e.g. "{code} will be applied to this inquiry"). `<BiabForm/>` renders it
+	 * above the submit button. The coupon id / field mapping never leave the
+	 * server. Added in 0.9.9.
+	 */
+	coupon?: { code?: string; notice?: string; finePrint?: string };
+}
+
+export interface FormSchema {
+	id: string;
+	slug: string;
+	title?: string;
+	description?: string | null;
+	fields: FormFieldDef[];
+	/** Render settings (animation, multi-step, progress). Added in 0.9.7. */
+	settings?: FormRenderSettings;
+	/** Org icon URL when the form opts into `showOrgIcon`. Added in 0.9.7. */
+	orgIcon?: string;
+	/** On-submit actions this form will run (sanitized). Added in 0.9.7. */
+	actions?: FormActionPreview[];
+	/**
+	 * NON-sensitive business functions referenced by this form's `calculation`
+	 * fields, so the SDK can compute them live in the browser. Sensitive
+	 * functions are NEVER included — they run server-side on submit. Added in
+	 * 0.9.9.
+	 */
+	businessFunctions?: Array<{
+		id: string;
+		slug: string;
+		inputs: Array<{
+			key: string;
+			label?: string;
+			type: string;
+			required?: boolean;
+			default?: unknown;
+		}>;
+		outputs: Array<{
+			key: string;
+			label?: string;
+			type: string;
+			formula: string;
+			fallback?: unknown;
+		}>;
+	}>;
+}
+
+export type FormSubmissionData = Record<string, unknown>;
+
+export interface FormValidationIssue {
+	fieldId: string;
+	label: string;
+	reason:
+		| "required"
+		| "type"
+		| "min"
+		| "max"
+		| "regex"
+		| "options"
+		| "format"
+		| "unknown_field"
+		| "invalid_payload"
+		| "too_many_fields"
+		// Forward-compat: tolerate reasons added server-side without a type bump.
+		| (string & {});
+	message: string;
+}
+
+export interface FormValidationResult {
+	ok: boolean;
+	issues: FormValidationIssue[];
+}
+
+/**
+ * Runtime validate a submission against the fetched form schema.
+ * Returns `ok: true` only when every required field is present and
+ * every supplied value passes its type / min / max / regex /
+ * options check. Designed to mirror what BIAB's server enforces so
+ * the consumer can show inline errors before round-tripping.
+ *
+ * For build-time type safety, the future `biab-dev codegen forms`
+ * CLI emits a `.d.ts` per form so TypeScript can also enforce
+ * shape at compile time. Until that ships, this runtime check is
+ * the safety net.
+ */
+
+/**
+ * Narrow check for the shape `biab.forms.uploadFile` returns —
+ * mirrors what the BIAB hiring mirror reads (storageId, url, name,
+ * mimeType, size). Used by both `validateFormSubmission` and any
+ * caller that wants to assert "this value is a successful upload."
+ */
+export function isFormFileValue(value: unknown): value is FormFileValue {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Partial<FormFileValue>;
+	return (
+		typeof v.storageId === "string" &&
+		typeof v.url === "string" &&
+		typeof v.name === "string" &&
+		typeof v.mimeType === "string" &&
+		typeof v.size === "number"
+	);
+}
+
+export function validateFormSubmission(
+	schema: FormSchema,
+	data: FormSubmissionData,
+): FormValidationResult {
+	const issues: FormValidationIssue[] = [];
+	// A submission may key values by the field's output `key` (preferred) or its
+	// legacy UUID `id`. Accept both everywhere.
+	const knownFieldIds = new Set<string>();
+	for (const f of schema.fields) {
+		knownFieldIds.add(f.id);
+		if (f.key) knownFieldIds.add(f.key);
+	}
+
+	for (const field of schema.fields) {
+		// `calculation` fields are computed server-side on submit — never user-validated.
+		if (field.type === "calculation") continue;
+		const value =
+			field.key != null && field.key in data ? data[field.key] : data[field.id];
+		const scheduleEmpty =
+			field.type === "schedule" &&
+			(() => {
+				const s = (value ?? {}) as {
+					slotStartAt?: unknown;
+					asap?: boolean;
+					days?: unknown[];
+					times?: unknown[];
+				};
+				return !(
+					(typeof s.slotStartAt === "string" && s.slotStartAt.length > 0) ||
+					s.asap === true ||
+					(Array.isArray(s.days) && s.days.length > 0) ||
+					(Array.isArray(s.times) && s.times.length > 0)
+				);
+			})();
+		const urlEmpty =
+			field.type === "url" &&
+			!(typeof (value as { url?: unknown })?.url === "string"
+				? (value as { url: string }).url
+				: "");
+		const isEmpty =
+			value == null ||
+			value === "" ||
+			(Array.isArray(value) && value.length === 0) ||
+			scheduleEmpty ||
+			urlEmpty;
+		// Consent boolean: must be exactly `true` (independent of `required`).
+		// `false` is otherwise a valid answer for an optional/required toggle.
+		const consentUnmet = field.mustBeTrue === true && value !== true;
+		if ((field.required && isEmpty) || consentUnmet) {
+			issues.push({
+				fieldId: field.id,
+				label: field.label,
+				reason: "required",
+				message: consentUnmet
+					? `${field.label} must be checked.`
+					: `${field.label} is required.`,
+			});
+			continue;
+		}
+		if (isEmpty) continue;
+		switch (field.type) {
+			case "email": {
+				if (
+					typeof value !== "string" ||
+					!/^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(value)
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be a valid email.`,
+					});
+					break;
+				}
+				if (
+					(field as { emailConfig?: { businessOnly?: boolean } }).emailConfig
+						?.businessOnly &&
+					isConsumerEmailDomain(getEmailDomain(value) ?? "")
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be a business email address.`,
+					});
+				}
+				break;
+			}
+			case "url": {
+				// Value object: { url, verified }. Validate the `url` member.
+				const u = (value as { url?: unknown })?.url;
+				if (
+					typeof u !== "string" ||
+					!/^(https?:\/\/)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}(?::\d{1,5})?(?:[/?#]\S*)?$/i.test(
+						u.trim(),
+					)
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be a valid URL.`,
+					});
+				}
+				break;
+			}
+			case "phone": {
+				// Digit-count pre-check mirroring the server: international fields
+				// allow E.164 (7-15), otherwise a 10-digit US number (optionally
+				// with a leading "1"). The server is the authoritative check.
+				const digits =
+					typeof value === "string" ? value.replace(/\D/g, "") : "";
+				const intl = field.phoneConfig?.international === true;
+				const national =
+					digits.length === 11 && digits.startsWith("1")
+						? digits.slice(1)
+						: digits;
+				const ok = intl
+					? digits.length >= 7 && digits.length <= 15
+					: national.length === 10;
+				if (!ok) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be a valid phone number.`,
+					});
+				}
+				break;
+			}
+			case "number":
+			case "slider":
+				if (typeof value !== "number") {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be a number.`,
+					});
+					break;
+				}
+				if (
+					field.type === "number" &&
+					(field as { allowNegative?: boolean }).allowNegative === false &&
+					value < 0
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "min",
+						message: `${field.label} must be 0 or greater.`,
+					});
+				}
+				if (field.validation?.min != null && value < field.validation.min) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "min",
+						message: `${field.label} must be at least ${field.validation.min}.`,
+					});
+				}
+				if (field.validation?.max != null && value > field.validation.max) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "max",
+						message: `${field.label} must be at most ${field.validation.max}.`,
+					});
+				}
+				break;
+			case "select":
+			case "radio":
+				if (
+					field.options &&
+					!field.allowCustom &&
+					!field.options.includes(String(value))
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "options",
+						message: `${field.label} must be one of: ${field.options.join(", ")}.`,
+					});
+				}
+				break;
+			case "checkbox":
+				if (typeof value !== "boolean" && !Array.isArray(value)) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be a boolean or list.`,
+					});
+				}
+				break;
+			case "choice_cards": {
+				const ccLabels = (field.choiceConfig?.options ?? []).map(
+					(o) => o.label,
+				);
+				const ccMulti = field.choiceConfig?.mode === "multi";
+				const ccVals = ccMulti
+					? Array.isArray(value)
+						? (value as unknown[])
+						: null
+					: typeof value === "string"
+						? [value]
+						: null;
+				if (ccVals === null) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: ccMulti
+							? `${field.label} must be a list.`
+							: `${field.label} must be a string.`,
+					});
+					break;
+				}
+				if (ccLabels.length) {
+					for (const v of ccVals) {
+						if (typeof v !== "string" || !ccLabels.includes(v)) {
+							issues.push({
+								fieldId: field.id,
+								label: field.label,
+								reason: "options",
+								message: `${field.label} must be one of: ${ccLabels.join(", ")}.`,
+							});
+							break;
+						}
+					}
+				}
+				break;
+			}
+			case "file_upload":
+			case "file": {
+				const items = Array.isArray(value) ? value : [value];
+				let badShape = false;
+				for (const item of items) {
+					if (!isFormFileValue(item)) {
+						badShape = true;
+						break;
+					}
+					if (
+						field.fileConfig?.maxSize != null &&
+						// `fileConfig.maxSize` is MB (builder slider unit); `item.size`
+						// is bytes — convert before comparing.
+						item.size > field.fileConfig.maxSize * 1024 * 1024
+					) {
+						issues.push({
+							fieldId: field.id,
+							label: field.label,
+							reason: "max",
+							message: `${field.label} exceeds the ${field.fileConfig.maxSize} MB limit.`,
+						});
+					}
+				}
+				if (badShape) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} must be uploaded via biab.forms.uploadFile().`,
+					});
+				}
+				if (
+					field.fileConfig?.maxFiles != null &&
+					Array.isArray(value) &&
+					value.length > field.fileConfig.maxFiles
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "max",
+						message: `${field.label} accepts at most ${field.fileConfig.maxFiles} files.`,
+					});
+				}
+				break;
+			}
+			case "schedule": {
+				// { asap?, days?: string[], times?: string[], notes? } — structural
+				// parity with the server (which also enforces length caps). Client
+				// pre-check only; the server gate is authoritative.
+				if (
+					typeof value !== "object" ||
+					value === null ||
+					Array.isArray(value)
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} has an unexpected value.`,
+					});
+					break;
+				}
+				const s = value as {
+					asap?: unknown;
+					days?: unknown;
+					times?: unknown;
+					notes?: unknown;
+				};
+				const badType =
+					(s.asap !== undefined && typeof s.asap !== "boolean") ||
+					(s.notes !== undefined && typeof s.notes !== "string") ||
+					(["days", "times"] as const).some(
+						(k) =>
+							s[k] !== undefined &&
+							(!Array.isArray(s[k]) ||
+								(s[k] as unknown[]).some((x) => typeof x !== "string")),
+					);
+				if (badType) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "type",
+						message: `${field.label} has an unexpected value.`,
+					});
+				}
+				break;
+			}
+			default:
+				if (
+					field.regexPattern &&
+					typeof value === "string" &&
+					!new RegExp(field.regexPattern).test(value)
+				) {
+					issues.push({
+						fieldId: field.id,
+						label: field.label,
+						reason: "regex",
+						message: `${field.label} format is invalid.`,
+					});
+				}
+		}
+	}
+
+	for (const key of Object.keys(data)) {
+		if (!knownFieldIds.has(key)) {
+			issues.push({
+				fieldId: key,
+				label: key,
+				reason: "unknown_field",
+				message: `Unknown field "${key}" — not in the form schema.`,
+			});
+		}
+	}
+
+	return { ok: issues.length === 0, issues };
+}
+
+/**
+ * Why a `forms.submit` call didn't succeed. Lets the consumer branch the UI
+ * without parsing error strings.
+ *
+ * - `client_validation_failed` — the local `validateFormSubmission` caught it
+ *   before any network call (see `issues`).
+ * - `validation_failed` — the server rejected the payload against the live form
+ *   schema (unknown field, wrong type/format, failed required, oversized, …).
+ *   This is also what a value the validator considers unsafe surfaces as. See
+ *   `issues`.
+ * - `unauthorized` — missing / invalid / expired package API key (401).
+ * - `forbidden` — the key lacks the scope/permission, or the request origin
+ *   isn't on the key's allowed-host list (403).
+ * - `plan_required` — the org's plan doesn't include forms (entitlement gate).
+ * - `payment_required` — the org's BIAB billing is past due.
+ * - `service_suspended` — the org's BIAB billing has lapsed 60+ days.
+ * - `rate_limited` — too many submissions too fast (429).
+ * - `not_found` — the form doesn't exist, is inactive, or isn't accepting
+ *   external submissions (404).
+ * - `invalid_request` — the request body was malformed (400).
+ * - `server_error` — BIAB failed to process the submission (5xx).
+ * - `network_error` — the request never reached BIAB (offline, DNS, CORS, …).
+ */
+export type FormSubmitFailureReason =
+	| "client_validation_failed"
+	| "validation_failed"
+	| "unauthorized"
+	| "forbidden"
+	| "plan_required"
+	| "payment_required"
+	| "service_suspended"
+	| "rate_limited"
+	| "not_found"
+	| "invalid_request"
+	| "server_error"
+	| "network_error";
+
+/**
+ * Result of `forms.submit`. Always resolves (never throws for an expected
+ * failure) so the consumer can render success or the exact problem inline.
+ * Discriminate on `ok`.
+ */
+export type FormSubmitResult =
+	| {
+			ok: true;
+			/** HTTP status of the accepted submission (200). */
+			status: number;
+			/** Present on a real submit; null/absent on a `dryRun`. */
+			submissionId?: string | null;
+			slug?: string;
+			/** True when this was a `dryRun` — validated but not stored. */
+			dryRun?: boolean;
+			/** Any additional fields BIAB returned (forward-compat). */
+			[key: string]: unknown;
+	  }
+	| {
+			ok: false;
+			/** HTTP status, or 0 when the request never reached BIAB. */
+			status: number;
+			reason: FormSubmitFailureReason;
+			/** Human-readable summary, safe to surface to the consumer. */
+			message: string;
+			/** Field-level detail when `reason` is a validation failure. */
+			issues?: FormValidationIssue[];
+	  };
+
+export interface FormsResource {
+	/**
+	 * Fetch the form's field definitions. Cached via `biab:forms`
+	 * + `biab:forms:<slug>` tags so admin edits invalidate via the
+	 * webhook layer.
+	 */
+	schema(slug: string): Promise<FormSchema>;
+	/**
+	 * Submit a form. Validates against the schema client-side (via
+	 * `validateFormSubmission`) before round-tripping, then posts to BIAB.
+	 *
+	 * Always resolves to a {@link FormSubmitResult} — it does NOT throw for an
+	 * expected failure. Check `result.ok`; on failure, `result.reason` says what
+	 * went wrong (bad API key, plan gate, schema mismatch, rate limit, network,
+	 * …) and `result.issues` carries field-level detail for validation failures.
+	 */
+	submit(
+		slug: string,
+		data: FormSubmissionData,
+		opts?: {
+			submitterEmail?: string;
+			submitterName?: string;
+			/** Skip client-side validation. Use sparingly. */
+			skipValidate?: boolean;
+			/** Test mode: validate against the live schema on the server but store
+			 *  nothing and skip all CRM/notification side effects. The result has
+			 *  `dryRun: true` and no `submissionId`. Ideal for Postman/CI checks. */
+			dryRun?: boolean;
+			/** Provenance — how/where the form was filled (e.g. "facebook",
+			 *  "google-ads:summer"), an optional referrer, and free-form metadata.
+			 *  Drives lead-source reporting. Added in 0.9.7. */
+			source?: string;
+			referrer?: string;
+			metadata?: Record<string, unknown>;
+		},
+	): Promise<FormSubmitResult>;
+	/**
+	 * Upload a single file for a file-type field on the form.
+	 *
+	 *   1. Calls the BIAB upload-url endpoint to get a presigned PUT
+	 *      URL + storageId (the server validates the form, field,
+	 *      MIME type, and size cap against the org's plan).
+	 *   2. PUTs the file bytes directly to R2 — BIAB never sees the
+	 *      bytes, only the metadata.
+	 *   3. Returns a `FormFileValue` to drop into the form's `data`
+	 *      payload when calling `submit`.
+	 *
+	 * Throws on plan-gate (`forms.file_uploads` entitlement
+	 * missing), field/file mismatch, or transfer failure.
+	 */
+	uploadFile(
+		slug: string,
+		fieldId: string,
+		file: File | Blob,
+		opts?: { filename?: string },
+	): Promise<FormFileValue>;
+	/**
+	 * Mint a Stripe intent for a `credit_card` field so `<BiabForm/>` can mount
+	 * Stripe Elements. `card_on_file` → a SetupIntent; `deposit` → a PaymentIntent
+	 * for the configured amount. The intent is created on the org's connected
+	 * account; initialize Stripe with `{ stripeAccount: connectedAccountId }` and
+	 * the returned `publishableKey`, then confirm with `clientSecret`. The card
+	 * never touches BIAB — only the opaque intent id flows back in the submission.
+	 */
+	paymentIntent(slug: string, fieldId: string): Promise<FormPaymentIntent>;
+	/**
+	 * Open booking slots for an auto-mode `schedule` field — the form's assigned
+	 * staff's combined real availability over [from, to]. `<BiabForm/>` renders
+	 * the instant-booking picker from these; the visitor picks one and the
+	 * meeting books on submit. Returns absolute UTC instants (`startAt`); host
+	 * identities stay server-side. Empty when the org lacks the scheduling
+	 * add-on or the field has no assignees.
+	 */
+	scheduleSlots(
+		slug: string,
+		input: { fieldId: string; from: Date; to: Date },
+	): Promise<{ slots: Array<{ startAt: string }> }>;
+}
+
+/** Stripe intent details for mounting Elements on a `credit_card` field. */
+export interface FormPaymentIntent {
+	mode: "card_on_file" | "deposit";
+	clientSecret: string;
+	intentId: string;
+	publishableKey: string;
+	connectedAccountId: string;
+}
+
+/** Normalize the server's `issues` array into typed `FormValidationIssue`s. */
+function mapSubmitIssues(
+	body: Record<string, unknown> | null,
+): FormValidationIssue[] | undefined {
+	const raw = body?.["issues"];
+	if (!Array.isArray(raw)) return undefined;
+	return raw.map((it) => {
+		const o = (it ?? {}) as Record<string, unknown>;
+		const id =
+			typeof o["id"] === "string"
+				? o["id"]
+				: typeof o["fieldId"] === "string"
+					? o["fieldId"]
+					: "";
+		const label = typeof o["label"] === "string" ? o["label"] : id || "field";
+		const reason = typeof o["reason"] === "string" ? o["reason"] : "type";
+		return {
+			fieldId: id,
+			label,
+			reason,
+			message:
+				typeof o["message"] === "string" ? o["message"] : `${label}: ${reason}`,
+		};
+	});
+}
+
+/** Map a non-2xx submit response (status + parsed body) to a failure result. */
+function mapSubmitResponse(
+	status: number,
+	body: Record<string, unknown> | null,
+): FormSubmitResult {
+	const message =
+		(typeof body?.["message"] === "string" && body["message"]) ||
+		`Submission failed (${status}).`;
+	const code = typeof body?.["error"] === "string" ? body["error"] : undefined;
+	const gateReason =
+		typeof body?.["reason"] === "string" ? body["reason"] : undefined;
+	const issues = mapSubmitIssues(body);
+
+	let reason: FormSubmitFailureReason;
+	if (status === 401) reason = "unauthorized";
+	else if (status === 403) reason = "forbidden";
+	else if (status === 402)
+		reason =
+			gateReason === "payment_required"
+				? "payment_required"
+				: gateReason === "service_suspended"
+					? "service_suspended"
+					: "plan_required";
+	else if (status === 429) reason = "rate_limited";
+	else if (status === 404) reason = "not_found";
+	else if (status === 400 || status === 422)
+		reason =
+			code === "validation_failed" || issues
+				? "validation_failed"
+				: "invalid_request";
+	else reason = "server_error";
+
+	return {
+		ok: false,
+		status,
+		reason,
+		message,
+		...(issues ? { issues } : {}),
+	};
+}
+
+/** Map a thrown error during the pre-submit schema fetch to a failure result. */
+function mapSubmitThrow(err: unknown): FormSubmitResult {
+	if (err instanceof Error) {
+		// `jsonGet` embeds the HTTP status in its message — recover it if present.
+		const m = err.message.match(/BIAB SDK (\d{3})/);
+		if (m) return mapSubmitResponse(Number(m[1]), null);
+		return {
+			ok: false,
+			status: 0,
+			reason: "network_error",
+			message: `Could not load the form schema: ${err.message}`,
+		};
+	}
+	return {
+		ok: false,
+		status: 0,
+		reason: "network_error",
+		message: "Could not load the form schema.",
+	};
+}
+
+function createFormsResource(state: InternalState): FormsResource {
+	return {
+		async schema(slug) {
+			// Non-chatbot form read: a form is reachable here when it is **Live**
+			// (`isActive`) — independent of `chatbotAccess`. Embedding a form on
+			// your own page no longer requires opting it into the AI chatbot.
+			const tags = [
+				"biab:forms",
+				`biab:forms:${slug}`,
+				`biab:site:${state.siteId}`,
+			];
+			const path = `forms/${encodeURIComponent(slug)}`;
+			const result = await jsonGet<{
+				id: string;
+				slug: string;
+				title?: string;
+				description?: string | null;
+				fields: FormFieldDef[];
+				settings?: FormRenderSettings;
+				orgIcon?: string;
+				actions?: FormActionPreview[];
+			}>(state, path, tags);
+			return result as FormSchema;
+		},
+		async submit(slug, data, opts) {
+			// 1. Client-side schema check (unless skipped) — return, don't throw,
+			//    so the consumer handles it the same way as a server rejection.
+			if (!opts?.skipValidate) {
+				let schema: FormSchema;
+				try {
+					schema = await this.schema(slug);
+				} catch (err) {
+					return mapSubmitThrow(err);
+				}
+				const v = validateFormSubmission(schema, data);
+				if (!v.ok) {
+					return {
+						ok: false,
+						status: 0,
+						reason: "client_validation_failed",
+						message: `Form validation failed — ${v.issues
+							.map((i) => `${i.label}: ${i.message}`)
+							.join("; ")}`,
+						issues: v.issues,
+					};
+				}
+			}
+
+			// 2. Round-trip. Map every transport / HTTP outcome to a result.
+			//    Live (non-chatbot) submit path — gated on `isActive` only.
+			const url = `${state.baseUrl.replace(/\/$/, "")}/forms/${encodeURIComponent(slug)}`;
+			const init: RequestInit & { next?: unknown } = {
+				method: "POST",
+				headers: {
+					...buildHeaders(state),
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					data,
+					submitterEmail: opts?.submitterEmail,
+					submitterName: opts?.submitterName,
+					...(opts?.dryRun ? { dryRun: true } : {}),
+					...(opts?.source ? { source: opts.source } : {}),
+					...(opts?.referrer ? { referrer: opts.referrer } : {}),
+					...(opts?.metadata ? { metadata: opts.metadata } : {}),
+				}),
+				next: { revalidate: 0 },
+			};
+
+			let res: Response;
+			try {
+				res = await state.fetch(url, init);
+			} catch (err) {
+				return {
+					ok: false,
+					status: 0,
+					reason: "network_error",
+					message:
+						err instanceof Error
+							? `Could not reach BIAB: ${err.message}`
+							: "Could not reach BIAB.",
+				};
+			}
+
+			const body = (await res.json().catch(() => null)) as Record<
+				string,
+				unknown
+			> | null;
+
+			if (res.ok) {
+				return {
+					ok: true,
+					status: res.status,
+					...(body ?? {}),
+				} as FormSubmitResult;
+			}
+
+			return mapSubmitResponse(res.status, body);
+		},
+		async uploadFile(slug, fieldId, file, opts) {
+			const filename =
+				opts?.filename ?? (file instanceof File ? file.name : "upload.bin");
+			const contentType = file.type || "application/octet-stream";
+			const sizeBytes = file.size;
+
+			// Step 1 — presign. The server validates entitlement
+			// (`forms.file_uploads`), Live form access, field type, MIME
+			// allow-list, and the per-plan / per-field max-size cap.
+			const presignUrl = `${state.baseUrl.replace(/\/$/, "")}/forms/${encodeURIComponent(slug)}/upload-url`;
+			const presignRes = await state.fetch(presignUrl, {
+				method: "POST",
+				headers: {
+					...buildHeaders(state),
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					fieldId,
+					filename,
+					contentType,
+					sizeBytes,
+				}),
+			});
+			if (!presignRes.ok) {
+				const text = await presignRes.text().catch(() => "");
+				if (presignRes.status === 403 || presignRes.status === 402) {
+					throw new Error(
+						`BIAB SDK: file upload requires the "forms.file_uploads" entitlement on this org. ${text.slice(0, 200)}`,
+					);
+				}
+				throw new Error(
+					`BIAB SDK ${presignRes.status} ${presignRes.statusText} on upload-url: ${text.slice(0, 200)}`,
+				);
+			}
+			const presign = (await presignRes.json()) as {
+				uploadUrl: string;
+				storageId: string;
+				publicUrl: string;
+				expiresAt: string;
+			};
+
+			// Step 2 — PUT bytes directly to R2 (signed URL).
+			const putRes = await state.fetch(presign.uploadUrl, {
+				method: "PUT",
+				headers: { "Content-Type": contentType },
+				body: file,
+			});
+			if (!putRes.ok) {
+				const text = await putRes.text().catch(() => "");
+				throw new Error(
+					`BIAB SDK upload to R2 failed: ${putRes.status} ${putRes.statusText}: ${text.slice(0, 200)}`,
+				);
+			}
+
+			// Step 3 — return the value to drop into form data.
+			return {
+				storageId: presign.storageId,
+				url: presign.publicUrl,
+				name: filename,
+				mimeType: contentType,
+				size: sizeBytes,
+			};
+		},
+
+		async paymentIntent(slug, fieldId) {
+			const url = `${state.baseUrl.replace(/\/$/, "")}/forms/${encodeURIComponent(slug)}/payment-intent`;
+			const res = await state.fetch(url, {
+				method: "POST",
+				headers: {
+					...buildHeaders(state),
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ fieldId }),
+			});
+			if (!res.ok) {
+				const text = await res.text().catch(() => "");
+				throw new Error(
+					`BIAB SDK ${res.status} ${res.statusText} on payment-intent: ${text.slice(0, 200)}`,
+				);
+			}
+			return (await res.json()) as FormPaymentIntent;
+		},
+		async scheduleSlots(slug, input) {
+			const base = state.baseUrl.replace(/\/$/, "");
+			const qs = new URLSearchParams({
+				fieldId: input.fieldId,
+				from: input.from.toISOString(),
+				to: input.to.toISOString(),
+			});
+			const url = `${base}/forms/${encodeURIComponent(slug)}/schedule-slots?${qs.toString()}`;
+			const res = await state.fetch(url, {
+				method: "GET",
+				headers: buildHeaders(state),
+			});
+			if (!res.ok) {
+				const text = await res.text().catch(() => "");
+				throw new Error(
+					`BIAB SDK ${res.status} ${res.statusText} on schedule-slots: ${text.slice(0, 200)}`,
+				);
+			}
+			return (await res.json()) as { slots: Array<{ startAt: string }> };
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Top-level client
+// ---------------------------------------------------------------------------
+
+export interface BiabClient {
+	gallery: GalleryResource;
+	scheduling: SchedulingResource;
+	forms: FormsResource;
+	// Existing class-based resources composed onto the same client so
+	// the consumer only ever sees one entry point. Each class is the
+	// long-form transport for its surface; the consumer pattern is
+	// `client.<resource>.<method>(...)`. Field selection / typed
+	// narrowing lands here surface-by-surface (gallery shipped first).
+	blog: BiabDevBlogClient;
+	reviews: BiabDevReviewsClient;
+	storefront: BiabDevStorefrontClient;
+	cart: BiabDevCartClient;
+	checkout: BiabDevCheckoutClient;
+	coupons: BiabDevCouponsClient;
+	subscriptions: BiabDevSubscriptionsClient;
+	shipping: BiabDevShippingClient;
+	address: BiabDevAddressClient;
+	customerPortal: BiabDevCustomerPortalClient;
+	notifications: BiabDevNotificationsClient;
+	followers: BiabDevFollowersClient;
+	marketing: BiabDevMarketingClient;
+	marketingPages: BiabDevMarketingPagesClient;
+	parallelPages: BiabDevParallelPagesClient;
+}
+
+export function createBiabClient(opts: CreateBiabClientOptions): BiabClient {
+	if (!opts.apiKey) {
+		throw new Error("createBiabClient: apiKey is required.");
+	}
+	if (!opts.siteId) {
+		throw new Error("createBiabClient: siteId is required.");
+	}
+	const state: InternalState = {
+		apiKey: opts.apiKey,
+		siteId: opts.siteId,
+		baseUrl: opts.baseUrl ?? DEFAULT_BASE_URL,
+		revalidateSeconds: opts.revalidateSeconds ?? DEFAULT_REVALIDATE_SECONDS,
+		fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
+		siteOrigin: opts.siteOrigin,
+	};
+	const transport = new BiabDevClient({
+		baseUrl: state.baseUrl,
+		apiKey: state.apiKey,
+		...(opts.fetch ? { fetch: opts.fetch } : {}),
+		...(opts.siteOrigin ? { siteOrigin: opts.siteOrigin } : {}),
+	});
+	return {
+		gallery: createGalleryResource(state),
+		scheduling: createSchedulingResource(state),
+		forms: createFormsResource(state),
+		blog: new BiabDevBlogClient(transport),
+		reviews: new BiabDevReviewsClient(transport),
+		storefront: new BiabDevStorefrontClient(transport),
+		cart: new BiabDevCartClient(transport, state.siteId),
+		checkout: new BiabDevCheckoutClient(transport, state.siteId),
+		coupons: new BiabDevCouponsClient(transport),
+		subscriptions: new BiabDevSubscriptionsClient(transport),
+		shipping: new BiabDevShippingClient(transport, state.siteId),
+		address: new BiabDevAddressClient(transport),
+		// CustomerPortal needs an org id binding; when the consumer's API
+		// key already binds an org, pass `null` here (server resolves via
+		// the key). For multi-tenant proxies, override after construction.
+		customerPortal: new BiabDevCustomerPortalClient(transport, null),
+		notifications: new BiabDevNotificationsClient(transport, state.siteId),
+		followers: new BiabDevFollowersClient(transport, state.siteId),
+		marketing: new BiabDevMarketingClient(transport, state.siteId),
+		marketingPages: new BiabDevMarketingPagesClient(transport, state.siteId),
+		parallelPages: new BiabDevParallelPagesClient(transport, state.siteId),
+	};
+}