@businessdash/sdk 0.9.60

package/src/client.ts

@@ -0,0 +1,3578 @@
+import { z } from "zod";
+
+import {
+	type AddressDetailsResponse,
+	type AddressFormValues,
+	type AddressSearchInput,
+	type AddressSearchResponse,
+	type AddressVerifyResponse,
+	type AiVisibilityInput,
+	type AiVisibilityResponse,
+	type AttributionHeartbeatInput,
+	type AttributionHeartbeatResponse,
+	type AttributionPolicy,
+	type AuthIntrospectResponse,
+	addressDetailsResponseSchema,
+	addressFormValuesSchema,
+	addressSearchInputSchema,
+	addressSearchResponseSchema,
+	addressVerifyResponseSchema,
+	aiVisibilityInputSchema,
+	aiVisibilityResponseSchema,
+	attributionHeartbeatInputSchema,
+	attributionHeartbeatResponseSchema,
+	attributionPolicySchema,
+	authIntrospectResponseSchema,
+	type BlogCategoryListResponse,
+	type BlogCommentListResponse,
+	type BlogCommentPostInput,
+	type BlogCommentPostResponse,
+	type BlogLikeResponse,
+	type BlogListPostsResponse,
+	type BlogPostBySlugResponse,
+	type BlogSessionInput,
+	type BlogSessionResponse,
+	type BlogTagListResponse,
+	blogCategoryListResponseSchema,
+	blogCommentListResponseSchema,
+	blogCommentPostInputSchema,
+	blogCommentPostResponseSchema,
+	blogLikeResponseSchema,
+	blogListPostsResponseSchema,
+	blogPostBySlugResponseSchema,
+	blogSessionInputSchema,
+	blogSessionResponseSchema,
+	blogTagListResponseSchema,
+	type CartAddItemInput,
+	type CartCouponInput,
+	type CartSessionResponse,
+	type CartSnapshot,
+	type CartUpdateItemInput,
+	type ChatbotAppendMessageInput,
+	type ChatbotAvailability,
+	type ChatbotChatInput,
+	type ChatbotChatResponse,
+	type ChatbotConfig,
+	type ChatbotConfigUpdateInput,
+	type ChatbotFormDefinition,
+	type ChatbotFormSubmitInput,
+	type ChatbotFormSubmitResponse,
+	type ChatbotMessagesResponse,
+	type ChatbotPersistedSessionInput,
+	type ChatbotPersistedSessionResponse,
+	type ChatbotRequestHumanInput,
+	type ChatbotRequestHumanResponse,
+	type ChatbotSessionResponse,
+	type CheckoutSessionInput,
+	type CheckoutSessionResponse,
+	type CheckoutStartInput,
+	type CheckoutStartResponse,
+	type CheckoutStatusResponse,
+	type ConfirmVerificationInput,
+	type ConfirmVerificationResponse,
+	type CouponValidateResponse,
+	type CreateCollectionInput,
+	type CreateCollectionResponse,
+	type CreateEmailTemplateInput,
+	type CreateEmailTemplateResponse,
+	type CreateEmailTemplateVersionInput,
+	type CreateEmailTemplateVersionResponse,
+	type CustomerContactCompanyInput,
+	type CustomerContactCompanyResponse,
+	type CustomerContractDetail,
+	type CustomerContractSignResponse,
+	type CustomerDownloadsResponse,
+	type CustomerInvoiceDetail,
+	type CustomerInvoicePayInput,
+	type CustomerInvoicePayResponse,
+	type CustomerInvoicePdf,
+	type CustomerJobActivityResponse,
+	type CustomerJobComment,
+	type CustomerJobCommentPostInput,
+	type CustomerJobCommentsListResponse,
+	type CustomerJobDetail,
+	type CustomerJobEtaResponse,
+	type CustomerNotificationPreferencesResponse,
+	type CustomerNotificationPreferencesUpdateInput,
+	type CustomerNotificationPreferencesUpdateResponse,
+	type CustomerOrderDetail,
+	type CustomerOrderListResponse,
+	type CustomerPortalContextResponse,
+	type CustomerPortalOtherOrgsResponse,
+	type CustomerPortalProfile,
+	type CustomerPortalUpdateProfileInput,
+	type CustomerPortalUpdateProfileResponse,
+	type CustomerQuoteActionResponse,
+	type CustomerQuoteDetail,
+	type CustomerReferralHistoryResponse,
+	type CustomerReferralPayoutsResponse,
+	type CustomerReferralStats,
+	type CustomerReturnRequestCreated,
+	type CustomerReturnRequestInput,
+	type CustomerReviewListResponse,
+	type CustomerReviewSubmitInput,
+	type CustomerReviewSubmitResponse,
+	type CustomerShipmentTracking,
+	type CustomerWorkBundle,
+	cartAddItemInputSchema,
+	cartCouponInputSchema,
+	cartSessionResponseSchema,
+	cartSnapshotSchema,
+	cartUpdateItemInputSchema,
+	chatbotAppendMessageInputSchema,
+	chatbotAvailabilitySchema,
+	chatbotChatInputSchema,
+	chatbotChatResponseSchema,
+	chatbotConfigSchema,
+	chatbotConfigUpdateInputSchema,
+	chatbotFormDefinitionSchema,
+	chatbotFormSubmitInputSchema,
+	chatbotFormSubmitResponseSchema,
+	chatbotMessagesResponseSchema,
+	chatbotPersistedSessionInputSchema,
+	chatbotPersistedSessionResponseSchema,
+	chatbotRequestHumanInputSchema,
+	chatbotRequestHumanResponseSchema,
+	chatbotSessionResponseSchema,
+	chatbotUploadUrlResponseSchema,
+	checkoutSessionInputSchema,
+	checkoutSessionResponseSchema,
+	checkoutStartInputSchema,
+	checkoutStartResponseSchema,
+	checkoutStatusResponseSchema,
+	confirmVerificationInputSchema,
+	confirmVerificationResponseSchema,
+	couponValidateInputSchema,
+	couponValidateResponseSchema,
+	createCollectionInputSchema,
+	createCollectionResponseSchema,
+	createEmailTemplateInputSchema,
+	createEmailTemplateResponseSchema,
+	createEmailTemplateVersionInputSchema,
+	createEmailTemplateVersionResponseSchema,
+	customerContactCompanyInputSchema,
+	customerContactCompanyResponseSchema,
+	customerContractDetailSchema,
+	customerContractSignResponseSchema,
+	customerDownloadsResponseSchema,
+	customerInvoiceDetailSchema,
+	customerInvoicePayInputSchema,
+	customerInvoicePayResponseSchema,
+	customerInvoicePdfSchema,
+	customerJobActivityResponseSchema,
+	customerJobCommentPostInputSchema,
+	customerJobCommentSchema,
+	customerJobCommentsListResponseSchema,
+	customerJobDetailSchema,
+	customerJobEtaResponseSchema,
+	customerNotificationPreferencesResponseSchema,
+	customerNotificationPreferencesUpdateInputSchema,
+	customerNotificationPreferencesUpdateResponseSchema,
+	customerOrderDetailSchema,
+	customerOrderListResponseSchema,
+	customerPaymentHistoryResponseSchema,
+	customerPortalContextResponseSchema,
+	customerPortalOtherOrgsResponseSchema,
+	customerPortalProfileSchema,
+	customerPortalUpdateProfileInputSchema,
+	customerPortalUpdateProfileResponseSchema,
+	customerQuoteActionResponseSchema,
+	customerQuoteDetailSchema,
+	customerReferralHistoryResponseSchema,
+	customerReferralPayoutsResponseSchema,
+	customerReferralStatsSchema,
+	customerReturnRequestCreatedSchema,
+	customerReturnRequestInputSchema,
+	customerReviewListResponseSchema,
+	customerReviewSubmitInputSchema,
+	customerReviewSubmitResponseSchema,
+	customerShipmentTrackingSchema,
+	customerWorkBundleSchema,
+	type DashboardSessionResponse,
+	type DataModelRecord,
+	dashboardSessionResponseSchema,
+	type ExecuteActionInput,
+	type ExecuteActionResponse,
+	executeActionInputSchema,
+	executeActionResponseSchema,
+	type FollowerEditInput,
+	type FollowerEditResponse,
+	type FollowerJoinInput,
+	type FollowerJoinResponse,
+	type FollowerLeaveInput,
+	type FollowerLeaveResponse,
+	type FollowerMeInput,
+	type FollowerMeResponse,
+	followerEditInputSchema,
+	followerEditResponseSchema,
+	followerJoinInputSchema,
+	followerJoinResponseSchema,
+	followerLeaveInputSchema,
+	followerLeaveResponseSchema,
+	followerMeInputSchema,
+	followerMeResponseSchema,
+	type GetCollectionResponse,
+	type GetEmailTemplateResponse,
+	type GetMarketingLocalesResponse,
+	type GetMarketingPageBundleResponse,
+	type GetPublishedMarketingSchemaResponse,
+	type GetSiteMarketingPageResponse,
+	type GoogleAddress,
+	getCollectionResponseSchema,
+	getEmailTemplateResponseSchema,
+	getMarketingLocalesResponseSchema,
+	getMarketingPageBundleResponseSchema,
+	getPublishedMarketingSchemaResponseSchema,
+	getSiteMarketingPageResponseSchema,
+	type JobCategoryListResponse,
+	type JobPosting,
+	type JobPostingListResponse,
+	jobCategoryListResponseSchema,
+	jobPostingListResponseSchema,
+	jobPostingSchema,
+	type ListCollectionsResponse,
+	type ListDataModelRecordsInput,
+	type ListDataModelRecordsResponse,
+	type ListEmailTemplatesInput,
+	type ListEmailTemplatesResponse,
+	type ListRowsInput,
+	type ListRowsResponse,
+	type ListSiteMarketingPagesResponse,
+	listCollectionsResponseSchema,
+	listDataModelRecordsInputSchema,
+	listDataModelRecordsResponseSchema,
+	listEmailTemplatesInputSchema,
+	listEmailTemplatesResponseSchema,
+	listRowsInputSchema,
+	listRowsResponseSchema,
+	listSiteMarketingPagesResponseSchema,
+	type NotificationPreferencesResponse,
+	type NotificationPreferencesUpdateInput,
+	notificationPreferencesResponseSchema,
+	notificationPreferencesUpdateInputSchema,
+	type PageViewsInput,
+	type PageViewsResponse,
+	type PublishMarketingSectionsInput,
+	type PublishMarketingSectionsResponse,
+	pageViewsInputSchema,
+	pageViewsResponseSchema,
+	publishMarketingSectionsInputSchema,
+	publishMarketingSectionsResponseSchema,
+	type QueryRowsInput,
+	type QueryRowsResponse,
+	queryRowsInputSchema,
+	queryRowsResponseSchema,
+	type ReviewWallListResponse,
+	reviewWallListResponseSchema,
+	type ShippingRatesInput,
+	type ShippingRatesResponse,
+	type ShippingSettingsResponse,
+	type ShippingTrackResponse,
+	type SiteAssetInput,
+	type SiteBranding,
+	type StartVerificationInput,
+	type StartVerificationResponse,
+	type StorefrontAddonsResponse,
+	type StorefrontCategoriesResponse,
+	type StorefrontListProductsResponse,
+	type StorefrontProductDetail,
+	type StorefrontProductReviewsResponse,
+	type StorefrontProductsWithMetaResponse,
+	type StorefrontRelatedProductsResponse,
+	type StorefrontSessionInput,
+	type StorefrontSessionResponse,
+	type StorefrontSort,
+	type SubscriptionCheckoutInput,
+	type SubscriptionCheckoutResponse,
+	type SubscriptionOffering,
+	type SubscriptionOfferingsListResponse,
+	shippingRatesInputSchema,
+	shippingRatesResponseSchema,
+	shippingSettingsResponseSchema,
+	shippingTrackResponseSchema,
+	siteAssetInputSchema,
+	siteBrandingSchema,
+	startVerificationInputSchema,
+	startVerificationResponseSchema,
+	storefrontAddonsResponseSchema,
+	storefrontCategoriesResponseSchema,
+	storefrontListProductsResponseSchema,
+	storefrontProductDetailSchema,
+	storefrontProductReviewsResponseSchema,
+	storefrontProductsWithMetaResponseSchema,
+	storefrontRelatedProductsResponseSchema,
+	storefrontSessionInputSchema,
+	storefrontSessionResponseSchema,
+	subscriptionCheckoutInputSchema,
+	subscriptionCheckoutResponseSchema,
+	subscriptionOfferingSchema,
+	subscriptionOfferingsListResponseSchema,
+	type TenantAuthExchangeInput,
+	type TenantAuthExchangeResponse,
+	type TenantAuthMeResponse,
+	type TenantAuthPasswordResetInput,
+	type TenantAuthPasswordResetResponse,
+	type TenantAuthSignOutResponse,
+	type TenantAuthStartInput,
+	type TenantAuthStartResponse,
+	tenantAuthExchangeInputSchema,
+	tenantAuthExchangeResponseSchema,
+	tenantAuthMeResponseSchema,
+	tenantAuthPasswordResetInputSchema,
+	tenantAuthPasswordResetResponseSchema,
+	tenantAuthSignOutResponseSchema,
+	tenantAuthStartInputSchema,
+	tenantAuthStartResponseSchema,
+	type UploadSiteAssetResponse,
+	type UpsertDraftMarketingSchemaInput,
+	type UpsertDraftMarketingSchemaResponse,
+	type UpsertRowInput,
+	type UpsertRowResponse,
+	uploadSiteAssetResponseSchema,
+	upsertDraftMarketingSchemaInputSchema,
+	upsertDraftMarketingSchemaResponseSchema,
+	upsertRowInputSchema,
+	upsertRowResponseSchema,
+} from "./contracts.js";
+import {
+	accessRejectionFromBody,
+	BiabApiError,
+	isBiabPlanGateBody,
+} from "./errors.js";
+
+export type FetchLike = typeof fetch;
+
+/** Options for {@link BiabDevClient} / {@link createBiabDevClient}. */
+export type BiabDevClientOptions = {
+	baseUrl: string;
+	apiKey: string;
+	fetch?: FetchLike;
+	defaultHeaders?: HeadersInit;
+	/**
+	 * Origin to send to the platform on every request. Required when the API
+	 * key has an Allowed Host set on the host (server-to-server `fetch` does
+	 * not send `Origin` automatically — without it the platform replies 403
+	 * `origin_required`). Accepts a full URL (`https://my-site.com`) or a
+	 * bare hostname (`my-site.com`); only the origin is sent on the wire.
+	 */
+	siteOrigin?: string;
+};
+
+/** An array value becomes a repeated param: `?path=/a&path=/b`. */
+type QueryValue =
+	| string
+	| number
+	| boolean
+	| Array<string | number>
+	| undefined;
+
+type RequestOptions<T> = {
+	method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+	path: string;
+	query?: Record<string, QueryValue>;
+	body?: unknown;
+	responseSchema: z.ZodType<T, z.ZodTypeDef, unknown>;
+	headers?: HeadersInit;
+};
+
+function buildUrl(
+	baseUrl: string,
+	path: string,
+	query?: Record<string, QueryValue>,
+) {
+	/**
+	 * Strip any leading slash from `path` so it is treated as a relative path and
+	 * appended to `baseUrl`'s pathname (e.g. `/api/package/v1`). Adding a leading
+	 * slash here would make `path` absolute under the URL spec and silently drop
+	 * the base URL's path component — see https://url.spec.whatwg.org/#concept-basic-url-parser.
+	 */
+	const relativePath = path.startsWith("/") ? path.slice(1) : path;
+	const url = new URL(relativePath, baseUrl);
+
+	for (const [key, value] of Object.entries(query ?? {})) {
+		if (value == null) continue;
+		if (Array.isArray(value)) {
+			// Repeat the param once per element so the server reads getAll(key).
+			for (const item of value) url.searchParams.append(key, String(item));
+		} else {
+			url.searchParams.set(key, String(value));
+		}
+	}
+
+	return url;
+}
+
+async function parseResponseBody(response: Response) {
+	const text = await response.text();
+	if (!text) return null;
+
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		return text;
+	}
+}
+
+/**
+ * Coerce a user-provided origin (URL or bare hostname) into a wire-safe
+ * `scheme://host` value. Returns `undefined` if input is empty.
+ */
+function normalizeSiteOrigin(raw: string | undefined): string | undefined {
+	if (!raw) return undefined;
+	const trimmed = raw.trim();
+	if (!trimmed) return undefined;
+	const withScheme = /^https?:\/\//i.test(trimmed)
+		? trimmed
+		: `https://${trimmed}`;
+	try {
+		const url = new URL(withScheme);
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return undefined;
+	}
+}
+
+function extractErrorMessage(body: unknown, fallback: string) {
+	if (body && typeof body === "object" && "message" in body) {
+		const message = body.message;
+		if (typeof message === "string" && message.trim()) {
+			return message;
+		}
+	}
+
+	return fallback;
+}
+
+/**
+ * Typed client for the BIAB package HTTP API.
+ *
+ * @remarks
+ * **Alpha:** This SDK is in alpha. Surfaces and behavior may change without semver guarantees.
+ * Do not rely on it for production workloads—use development, staging, or experiments only.
+ */
+export class BiabDevClient {
+	private readonly baseUrl: string;
+	private readonly apiKey: string;
+	private readonly fetchImpl: FetchLike;
+	private readonly defaultHeaders: HeadersInit | undefined;
+
+	constructor(options: BiabDevClientOptions) {
+		// Trailing slash is required by the WHATWG URL parser so the relative
+		// `path` segments are appended to (rather than replacing) the base path.
+		this.baseUrl = options.baseUrl.endsWith("/")
+			? options.baseUrl
+			: `${options.baseUrl}/`;
+		this.apiKey = options.apiKey;
+		// Bind `fetch` to its global so that calling it as a method on
+		// `this` (`this.fetchImpl(url, init)`) doesn't trigger the
+		// "Illegal invocation" error in browsers — `Window.fetch` requires
+		// `this === window`. `globalThis` works in Node 18+ and the browser.
+		this.fetchImpl =
+			options.fetch ??
+			((input: RequestInfo | URL, init?: RequestInit) =>
+				globalThis.fetch(input, init));
+		this.defaultHeaders = options.defaultHeaders;
+		this.siteOrigin = normalizeSiteOrigin(options.siteOrigin);
+	}
+
+	private readonly siteOrigin: string | undefined;
+
+	site(siteId: string) {
+		return new BiabDevSiteClient(this, siteId);
+	}
+
+	get emailTemplates() {
+		return new BiabDevEmailTemplatesClient(this);
+	}
+
+	get dashboard() {
+		return new BiabDevDashboardClient(this);
+	}
+
+	get storefront() {
+		return new BiabDevStorefrontClient(this);
+	}
+
+	get cart() {
+		return new BiabDevCartClient(this);
+	}
+
+	get checkout() {
+		return new BiabDevCheckoutClient(this);
+	}
+
+	get coupons() {
+		return new BiabDevCouponsClient(this);
+	}
+
+	get subscriptions() {
+		return new BiabDevSubscriptionsClient(this);
+	}
+
+	get shipping() {
+		return new BiabDevShippingClient(this);
+	}
+
+	get notifications() {
+		return new BiabDevNotificationsClient(this);
+	}
+
+	get address() {
+		return new BiabDevAddressClient(this);
+	}
+
+	get blog() {
+		return new BiabDevBlogClient(this);
+	}
+
+	get reviews() {
+		return new BiabDevReviewsClient(this);
+	}
+
+	/** Public job postings — build a careers page on your own domain. */
+	get hiring() {
+		return new BiabDevHiringClient(this);
+	}
+
+	get chatbot() {
+		return new BiabDevChatbotClient(this);
+	}
+
+	get auth() {
+		return new BiabDevAuthClient(this);
+	}
+
+	/**
+	 * Customer-portal client. Pin to a specific BIAB organization id so the
+	 * caller never sees data from any other org (recommended). Omit
+	 * `organizationId` to fall back to the user's currently-active session
+	 * org — only use that on first-party hosts where the host already pins
+	 * the org.
+	 */
+	customerPortal(organizationId?: string) {
+		return new BiabDevCustomerPortalClient(this, organizationId ?? null);
+	}
+
+	async introspect(): Promise<AuthIntrospectResponse> {
+		return this.request({
+			method: "POST",
+			path: "auth/introspect",
+			responseSchema: authIntrospectResponseSchema,
+		});
+	}
+
+	async request<T>(options: RequestOptions<T>): Promise<T> {
+		const url = buildUrl(this.baseUrl, options.path, options.query);
+		const init: RequestInit = {
+			method: options.method ?? "GET",
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${this.apiKey}`,
+				...(options.body === undefined
+					? {}
+					: { "Content-Type": "application/json" }),
+				...(this.siteOrigin ? { Origin: this.siteOrigin } : {}),
+				...(this.defaultHeaders ?? {}),
+				...(options.headers ?? {}),
+			},
+		};
+
+		if (options.body !== undefined) {
+			init.body = JSON.stringify(options.body);
+		}
+
+		const response = await this.fetchImpl(url, init);
+
+		const body = await parseResponseBody(response);
+
+		// Access gate — 200 (reads, body-only signal) and 402 (writes)
+		// both surface as a typed error so consumer code is uniform.
+		// Three flavours: plan-required (BiabFeatureNotEntitledError),
+		// payment-required (BiabPaymentLapsedError), service-suspended
+		// (BiabServiceSuspendedError) — all extend BiabAccessRejectedError
+		// for "catch any" patterns. `unwrapAccess()` is the opt-in
+		// Result-shape escape hatch.
+		if (isBiabPlanGateBody(body)) {
+			throw accessRejectionFromBody({
+				body,
+				path: url.pathname,
+				status: response.status,
+			});
+		}
+
+		if (!response.ok) {
+			throw new BiabApiError({
+				status: response.status,
+				path: url.pathname,
+				message: extractErrorMessage(
+					body,
+					`BIAB API request failed with status ${response.status}.`,
+				),
+				body,
+			});
+		}
+
+		return options.responseSchema.parse(body);
+	}
+}
+
+export class BiabDevSiteClient {
+	readonly collections: BiabDevCollectionsClient;
+	readonly rows: BiabDevRowsClient;
+	/**
+	 * The org's custom database — the tables from `defineDataModel()`.
+	 * Distinct from `collections`/`rows`, which are Site Data. See
+	 * {@link BiabDevDataModelClient}.
+	 */
+	readonly dataModel: BiabDevDataModelClient;
+	/**
+	 * Read your site's visitor counts back (the counterpart to the
+	 * `<BIABAnalytics/>` tracker, which only records). See
+	 * {@link BiabDevAnalyticsClient}.
+	 */
+	readonly analytics: BiabDevAnalyticsClient;
+	/**
+	 * The "Powered by BusinessDash" badge's policy + heartbeat. See
+	 * {@link BiabDevAttributionClient}.
+	 */
+	readonly attribution: BiabDevAttributionClient;
+	readonly assets: BiabDevAssetsClient;
+	readonly actions: BiabDevActionsClient;
+	readonly followers: BiabDevFollowersClient;
+	readonly marketingPages: BiabDevMarketingPagesClient;
+	/**
+	 * Schema-driven marketing flow (Phase 2). Pair with the SDK's
+	 * `defineSiteMarketingSchema()` builder + the `biab-dev sync-schema`
+	 * CLI for the authoring side; this client is the live-site read
+	 * path (`getPageBundle`) and the upload entry point for the CLI.
+	 */
+	readonly marketing: BiabDevMarketingClient;
+	readonly parallelPages: BiabDevParallelPagesClient;
+
+	constructor(
+		readonly client: BiabDevClient,
+		readonly siteId: string,
+	) {
+		this.collections = new BiabDevCollectionsClient(client, siteId);
+		this.rows = new BiabDevRowsClient(client, siteId);
+		this.dataModel = new BiabDevDataModelClient(client, siteId);
+		this.analytics = new BiabDevAnalyticsClient(client, siteId);
+		this.attribution = new BiabDevAttributionClient(client, siteId);
+		this.assets = new BiabDevAssetsClient(client, siteId);
+		this.actions = new BiabDevActionsClient(client, siteId);
+		this.followers = new BiabDevFollowersClient(client, siteId);
+		this.marketingPages = new BiabDevMarketingPagesClient(client, siteId);
+		this.marketing = new BiabDevMarketingClient(client, siteId);
+		this.parallelPages = new BiabDevParallelPagesClient(client, siteId);
+	}
+
+	/**
+	 * The org's storefront branding — logo + favicon (site static media) plus
+	 * the org name + icon. Render the masthead/favicon/og without the org
+	 * re-supplying assets. Available even when billing has lapsed.
+	 *
+	 * @example
+	 * ```ts
+	 * const b = await client.site(SITE_ID).branding();
+	 * <img src={b.logoUrl ?? b.orgIcon ?? ""} alt={b.orgName ?? ""} />
+	 * ```
+	 */
+	async branding(): Promise<SiteBranding> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/branding`,
+			responseSchema: siteBrandingSchema,
+		});
+	}
+}
+
+const parallelPageMetaSchema = z.object({
+	title: z.string(),
+	description: z.string(),
+	canonical: z.string().nullable(),
+	ogImage: z.string().nullable(),
+});
+
+export const parallelPagesListResponseSchema = z.object({
+	items: z.array(
+		z.object({
+			id: z.string(),
+			key: z.string(),
+			routePattern: z.string(),
+			variables: z.array(
+				z.object({
+					name: z.string(),
+					source: z.object({
+						section: z.string(),
+						path: z.string().optional(),
+					}),
+					slugField: z.string(),
+					tokenFields: z.array(z.string()),
+				}),
+			),
+			meta: z.object({
+				title: z.string(),
+				description: z.string(),
+				canonical: z.string().optional(),
+				ogImage: z.string().optional(),
+			}),
+			templateRef: z.string(),
+			source: z.enum(["sdk", "site_builder"]),
+			crawlRule: z.enum(["inherit", "index", "noindex"]),
+			isActive: z.boolean(),
+		}),
+	),
+});
+
+export const parallelPagesVariantsResponseSchema = z.object({
+	variants: z.array(z.record(z.string(), z.string())),
+});
+
+export const parallelPagesRenderResponseSchema = z.object({
+	key: z.string(),
+	routePattern: z.string(),
+	slugs: z.record(z.string(), z.string()),
+	meta: parallelPageMetaSchema,
+	body: z.unknown().nullable(),
+});
+
+export type ParallelPagesListResponse = z.infer<
+	typeof parallelPagesListResponseSchema
+>;
+export type ParallelPagesVariantsResponse = z.infer<
+	typeof parallelPagesVariantsResponseSchema
+>;
+export type ParallelPagesRenderResponse = z.infer<
+	typeof parallelPagesRenderResponseSchema
+>;
+
+/**
+ * Programmatic SEO ("parallel pages") client. Same shape across
+ * SDK-defined and site-builder-defined pages — both share the
+ * `org_parallel_pages` table on the server.
+ *
+ * Typical wiring in Next.js:
+ *
+ *   export async function generateStaticParams() {
+ *     const { variants } = await client
+ *       .site(SITE_ID)
+ *       .parallelPages
+ *       .listVariants("repair-area");
+ *     return variants;
+ *   }
+ *
+ *   export default async function Page({ params }) {
+ *     const bundle = await client
+ *       .site(SITE_ID)
+ *       .parallelPages
+ *       .render("repair-area", await params);
+ *     return <RenderTemplate bundle={bundle} />;
+ *   }
+ */
+export class BiabDevParallelPagesClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	async list(): Promise<ParallelPagesListResponse> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/parallel-pages`,
+			responseSchema: parallelPagesListResponseSchema,
+		});
+	}
+
+	async listVariants(
+		key: string,
+		opts: { locale?: string } = {},
+	): Promise<ParallelPagesVariantsResponse> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/parallel-pages/${encodeURIComponent(key)}/variants`,
+			...(opts.locale ? { query: { locale: opts.locale } } : {}),
+			responseSchema: parallelPagesVariantsResponseSchema,
+		});
+	}
+
+	async render(
+		key: string,
+		slugs: Record<string, string>,
+		opts: { locale?: string } = {},
+	): Promise<ParallelPagesRenderResponse> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/parallel-pages/${encodeURIComponent(key)}/render`,
+			query: {
+				...slugs,
+				...(opts.locale ? { locale: opts.locale } : {}),
+			},
+			responseSchema: parallelPagesRenderResponseSchema,
+		});
+	}
+
+	/**
+	 * URL of the auto-generated sitemap. Consumer's `/sitemap.xml` route
+	 * proxies straight through. Returns null when the client isn't
+	 * configured with a base URL.
+	 */
+	sitemapUrl(): string {
+		return `sites/${encodeURIComponent(this.siteId)}/sitemap.xml`;
+	}
+
+	/**
+	 * URL of the auto-generated robots.txt. Consumer's `/robots.txt` route
+	 * proxies straight through.
+	 */
+	robotsUrl(): string {
+		return `sites/${encodeURIComponent(this.siteId)}/robots.txt`;
+	}
+}
+
+/**
+ * Process-wide cache for the schema-driven marketing reads, keyed by
+ * the response's content-version fingerprint so cache hits are safe
+ * across SDK consumer re-renders. Bundle entries are short-lived (the
+ * server already sets `Cache-Control: s-maxage=60` so an upstream CDN
+ * does most of the work); the cache here is the SDK-process tier
+ * that prerendered Next builds reuse across all generated pages.
+ */
+const marketingBundleCache: Map<string, GetMarketingPageBundleResponse> =
+	new Map();
+const marketingSchemaCache: Map<string, GetPublishedMarketingSchemaResponse> =
+	new Map();
+const marketingLocalesCache: Map<string, GetMarketingLocalesResponse> =
+	new Map();
+
+function bundleCacheKey(
+	siteId: string,
+	pageKey: string,
+	locale: string,
+): string {
+	return `${siteId}/${pageKey}/${locale}`;
+}
+
+/**
+ * Manually invalidate marketing caches scoped to a site. Useful after a
+ * server-side mutation the SDK didn't initiate (e.g. an operator saved a
+ * section in the dashboard while the consumer's Next process is still
+ * warm).
+ */
+export function clearMarketingCache(siteId: string): void {
+	const prefix = `${siteId}/`;
+	for (const k of Array.from(marketingBundleCache.keys())) {
+		if (k.startsWith(prefix)) marketingBundleCache.delete(k);
+	}
+	marketingSchemaCache.delete(siteId);
+	marketingLocalesCache.delete(siteId);
+}
+
+/**
+ * Live-site read client for the schema-driven marketing flow.
+ *
+ * Surfaces:
+ *   - `getPageBundle({ pageKey, locale })` — every section for a page,
+ *     tagged ok|error per section, plus SEO + availableLocales.
+ *   - `getPublishedSchema()` — the live schema (returns `{ schema: null }`
+ *     until the consumer's CLI has published one).
+ *   - `getDraftSchema()` — what's currently staged (CLI-only path).
+ *   - `publishDraftSchema(input)` — CLI upload. Idempotent (same
+ *     checksum = `noop: true`).
+ *   - `getLocales()` — enabled locales + brand-token map.
+ */
+export class BiabDevMarketingClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	async getPageBundle(
+		input: { pageKey?: string; locale?: string; reviewsLimit?: number } = {},
+		options: { skipCache?: boolean } = {},
+	): Promise<GetMarketingPageBundleResponse> {
+		const pageKey = input.pageKey ?? "home";
+		const locale = input.locale ?? "en";
+		// reviewsLimit sizes bundle.reviews.items; different sizes are different
+		// payloads, so it participates in the cache key.
+		const cacheKey =
+			bundleCacheKey(this.siteId, pageKey, locale) +
+			(input.reviewsLimit != null ? `/r${input.reviewsLimit}` : "");
+		if (!options.skipCache) {
+			const hit = marketingBundleCache.get(cacheKey);
+			if (hit) return hit;
+		}
+		const response = await this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing/bundle`,
+			query: { pageKey, locale, reviewsLimit: input.reviewsLimit },
+			responseSchema: getMarketingPageBundleResponseSchema,
+		});
+		marketingBundleCache.set(cacheKey, response);
+		return response;
+	}
+
+	getPageBundleCached(
+		input: { pageKey?: string; locale?: string } = {},
+	): GetMarketingPageBundleResponse | null {
+		const pageKey = input.pageKey ?? "home";
+		const locale = input.locale ?? "en";
+		return (
+			marketingBundleCache.get(bundleCacheKey(this.siteId, pageKey, locale)) ??
+			null
+		);
+	}
+
+	async prefetchPageBundle(
+		input: { pageKey?: string; locale?: string } = {},
+	): Promise<GetMarketingPageBundleResponse> {
+		return this.getPageBundle(input);
+	}
+
+	async getPublishedSchema(
+		options: { skipCache?: boolean } = {},
+	): Promise<GetPublishedMarketingSchemaResponse> {
+		if (!options.skipCache) {
+			const hit = marketingSchemaCache.get(this.siteId);
+			if (hit) return hit;
+		}
+		const response = await this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing/published-schema`,
+			responseSchema: getPublishedMarketingSchemaResponseSchema,
+		});
+		marketingSchemaCache.set(this.siteId, response);
+		return response;
+	}
+
+	async getDraftSchema(): Promise<GetPublishedMarketingSchemaResponse> {
+		// Same response shape as published-schema, just from the other slot.
+		// Not cached — the CLI calls this once per upload cycle.
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing/draft-schema`,
+			responseSchema: getPublishedMarketingSchemaResponseSchema,
+		});
+	}
+
+	async publishDraftSchema(
+		input: UpsertDraftMarketingSchemaInput,
+	): Promise<UpsertDraftMarketingSchemaResponse> {
+		const body = upsertDraftMarketingSchemaInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing/draft-schema`,
+			body,
+			responseSchema: upsertDraftMarketingSchemaResponseSchema,
+		});
+	}
+
+	/**
+	 * Bulk-upsert section values. Used by `biab-dev sync-content` to push
+	 * local JSON content to BIAB. Server caps each request at 256 items;
+	 * larger imports are batched by the CLI. Per-item failures are
+	 * reported in the response (`results[].ok === false`) without aborting
+	 * the rest of the batch.
+	 *
+	 * The CLI's `--lax` flag sets `validate: false` for first-time imports
+	 * of legacy content that doesn't yet match the published schema —
+	 * useful so writers can pull existing content into BIAB and fix
+	 * validation errors in the dashboard incrementally.
+	 */
+	async publishSections(
+		input: PublishMarketingSectionsInput,
+	): Promise<PublishMarketingSectionsResponse> {
+		const body = publishMarketingSectionsInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing/sections`,
+			body,
+			responseSchema: publishMarketingSectionsResponseSchema,
+		});
+	}
+
+	async getLocales(
+		options: { skipCache?: boolean } = {},
+	): Promise<GetMarketingLocalesResponse> {
+		if (!options.skipCache) {
+			const hit = marketingLocalesCache.get(this.siteId);
+			if (hit) return hit;
+		}
+		const response = await this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing/locales`,
+			responseSchema: getMarketingLocalesResponseSchema,
+		});
+		marketingLocalesCache.set(this.siteId, response);
+		return response;
+	}
+}
+
+/**
+ * Process-wide cache for marketing-page payloads, keyed by `(siteId, pageKey)`.
+ * Shared across `BiabDevMarketingPagesClient` instances so that
+ * `prefetch(pageKey)` warms the same store `get(pageKey)` reads on demand.
+ *
+ * Lives on a module-level `Map` rather than instance state because consumers
+ * commonly create transient `client.site(siteId)` proxies inside React
+ * components — instance-level caching would evict on every re-render.
+ */
+const marketingPageCache: Map<string, GetSiteMarketingPageResponse> = new Map();
+
+function marketingPageCacheKey(siteId: string, pageKey: string): string {
+	return `${siteId} ${pageKey}`;
+}
+
+/**
+ * Manually clear the SDK's cache for `(siteId, pageKey)` (or the whole
+ * site when `pageKey` is omitted). Useful after a server-side mutation
+ * that the SDK didn't initiate, or in tests.
+ */
+export function clearMarketingPageCache(
+	siteId: string,
+	pageKey?: string,
+): void {
+	if (pageKey) {
+		marketingPageCache.delete(marketingPageCacheKey(siteId, pageKey));
+		return;
+	}
+	const prefix = `${siteId} `;
+	for (const key of Array.from(marketingPageCache.keys())) {
+		if (key.startsWith(prefix)) marketingPageCache.delete(key);
+	}
+}
+
+/**
+ * Read-only access to the host's `org_site_marketing_pages` table — the JSON
+ * documents the Site Builder writes for marketing landing pages (e.g. the
+ * `home` page rendered by `custom-demo`).
+ *
+ * Requires the `collections:read` scope on the API key (the same scope used
+ * for collection reads, so existing keys created from the host's Site Builder
+ * → Developer panel work without re-issuing).
+ *
+ * The client transparently caches per-page responses across instances; pair
+ * `list()` (no payloads) with `get(pageKey)` / `prefetch(pageKey)` to load
+ * pages on demand instead of paying the full-content cost up front.
+ */
+export class BiabDevMarketingPagesClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	/**
+	 * Payload-free directory of every marketing page for the site. Use this
+	 * to render a navigation index without loading any content; call
+	 * {@link get} or {@link prefetch} when the visitor selects a page.
+	 */
+	async list(): Promise<ListSiteMarketingPagesResponse> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing-pages`,
+			responseSchema: listSiteMarketingPagesResponseSchema,
+		});
+	}
+
+	/**
+	 * Fetches a single marketing page payload by `pageKey` (defaults to `"home"`).
+	 * Returns `{ page: null }` when the host has not published one yet — callers
+	 * typically render a static fallback in that case.
+	 *
+	 * Reads from the shared cache when present (warmed by {@link prefetch} or
+	 * a previous `get`). Pass `{ skipCache: true }` to force a network round-trip
+	 * (e.g. after a save the SDK didn't make itself).
+	 */
+	async get(
+		pageKey = "home",
+		options: { skipCache?: boolean } = {},
+	): Promise<GetSiteMarketingPageResponse> {
+		const cacheKey = marketingPageCacheKey(this.siteId, pageKey);
+		if (!options.skipCache) {
+			const hit = marketingPageCache.get(cacheKey);
+			if (hit) return hit;
+		}
+		const response = await this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/marketing-pages/${encodeURIComponent(pageKey)}`,
+			responseSchema: getSiteMarketingPageResponseSchema,
+		});
+		marketingPageCache.set(cacheKey, response);
+		return response;
+	}
+
+	/**
+	 * Read the cached value for `pageKey` without making a network call.
+	 * Returns `null` when the entry hasn't been fetched yet — callers can
+	 * fall back to a synchronous static default while {@link prefetch}
+	 * warms the cache in the background.
+	 */
+	getCached(pageKey: string): GetSiteMarketingPageResponse | null {
+		return (
+			marketingPageCache.get(marketingPageCacheKey(this.siteId, pageKey)) ??
+			null
+		);
+	}
+
+	/**
+	 * Warm the SDK cache for `pageKey` without rendering anything yet.
+	 * Common pattern: call from a `<Link onPointerEnter>` / `onFocus` so
+	 * the next page is already loaded by the time the visitor clicks.
+	 * Subsequent `get(pageKey)` calls resolve from cache.
+	 */
+	async prefetch(pageKey = "home"): Promise<GetSiteMarketingPageResponse> {
+		return this.get(pageKey);
+	}
+}
+
+export class BiabDevCollectionsClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	async list(): Promise<ListCollectionsResponse> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/collections`,
+			responseSchema: listCollectionsResponseSchema,
+		});
+	}
+
+	async create(
+		input: CreateCollectionInput,
+	): Promise<CreateCollectionResponse> {
+		const body = createCollectionInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/collections`,
+			body,
+			responseSchema: createCollectionResponseSchema,
+		});
+	}
+
+	async get(slug: string): Promise<GetCollectionResponse> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/collections/${encodeURIComponent(slug)}`,
+			responseSchema: getCollectionResponseSchema,
+		});
+	}
+}
+
+export class BiabDevRowsClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	async list(
+		collectionSlug: string,
+		input: ListRowsInput = {},
+	): Promise<ListRowsResponse> {
+		const query = listRowsInputSchema.parse(input);
+
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/collections/${encodeURIComponent(collectionSlug)}/rows`,
+			query,
+			responseSchema: listRowsResponseSchema,
+		});
+	}
+
+	async upsert(
+		collectionSlug: string,
+		input: UpsertRowInput,
+	): Promise<UpsertRowResponse> {
+		const body = upsertRowInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/collections/${encodeURIComponent(collectionSlug)}/rows`,
+			body,
+			responseSchema: upsertRowResponseSchema,
+		});
+	}
+
+	async query(
+		collectionSlug: string,
+		input: QueryRowsInput,
+	): Promise<QueryRowsResponse> {
+		const body = queryRowsInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/collections/${encodeURIComponent(collectionSlug)}/query`,
+			body,
+			responseSchema: queryRowsResponseSchema,
+		});
+	}
+}
+
+/**
+ * Read rows out of the org's CUSTOM DATABASE — the tables you declare with
+ * `defineDataModel()` and push with `biab-dev sync-data-model`.
+ *
+ * ⚠️ Not the same thing as `.collections` / `.rows`. Those read Site Data (the
+ * site builder's tables, `site_data_rows`). Rows seeded with
+ * `biab-dev sync-records` live in `org_object_records` and are reachable only
+ * through here — no `collections:*` call will ever return one.
+ *
+ * Requires the `metadata:read_records` scope. What a key can actually read is
+ * decided per object by its `visibility`:
+ *
+ *   - `private` (default) — a SECRET key only. Call from a server component, a
+ *     route handler, or at build time; a `pk_…` key gets "not found".
+ *   - `authenticated` — a secret key, or a publishable key carrying a signed-in
+ *     tenant session.
+ *   - `public` — any key, including a publishable (`pk_…`) one in page JS.
+ *
+ * So a table you declared `public` is readable straight from the browser; a
+ * private one never is. Open a table by declaring `visibility` in your model.
+ *
+ * ```ts
+ * const result = await biab.site(siteId).dataModel.listRecords({
+ *   object: TECH_OBJECT_ID,   // the universalIdentifier from your config
+ * });
+ * if (!result.available) return <UpgradeCard feature={result.requiredFeature} />;
+ * for (const tech of result.records) {
+ *   tech.fields.name;      // scalar values, keyed by field name
+ *   tech.relations.icon;   // [{ recordId, object }] — links, not embedded rows
+ * }
+ * ```
+ */
+export class BiabDevDataModelClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	/**
+	 * One page of an object's rows, newest first, with relations expanded.
+	 *
+	 * Relations come back as LINKS (`{ recordId, object }`), not embedded rows —
+	 * fetch the targets with a follow-up call for the object they point at.
+	 * Every declared relation field is present; `[]` means "no links yet", which
+	 * is deliberately distinguishable from a field that wasn't returned.
+	 *
+	 * Paginate by passing the previous response's `nextCursor` back as `cursor`
+	 * until it comes back `null`. The cursor is opaque — don't build one.
+	 */
+	async listRecords(
+		input: ListDataModelRecordsInput,
+	): Promise<ListDataModelRecordsResponse> {
+		const query = listDataModelRecordsInputSchema.parse(input);
+
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/data-model/records`,
+			query,
+			responseSchema: listDataModelRecordsResponseSchema,
+		});
+	}
+
+	/**
+	 * Every row of an object, walking `nextCursor` to exhaustion.
+	 *
+	 * For build-time rendering of a table you own and whose size you know. It is
+	 * an unbounded loop over your data by definition — for anything visitor-facing
+	 * or open-ended, page with {@link listRecords} instead.
+	 *
+	 * Returns the plan-gate shape unchanged if the org lacks the entitlement, so
+	 * the same `available` branch works for both.
+	 */
+	async listAllRecords(
+		input: Omit<ListDataModelRecordsInput, "cursor">,
+	): Promise<ListDataModelRecordsResponse> {
+		const records: DataModelRecord[] = [];
+		let cursor: string | undefined;
+
+		do {
+			const page = await this.listRecords({ ...input, cursor });
+			if (!page.available) return page;
+			records.push(...page.records);
+			cursor = page.nextCursor ?? undefined;
+		} while (cursor);
+
+		return { available: true, records, nextCursor: null };
+	}
+}
+
+/**
+ * Read your site's visitor counts back.
+ *
+ * The `<BIABAnalytics/>` tracker (`@businessdash/sdk/react-analytics`) RECORDS
+ * pageviews; this READS the totals, so you can put a number on the page instead
+ * of only feeding the dashboard.
+ *
+ * ```ts
+ * // Site-wide, all time
+ * const all = await biab.site(siteId).analytics.pageViews();
+ * if (all.available) console.log(`${all.total.views} views`);
+ *
+ * // One page, last 30 days
+ * const home = await biab.site(siteId).analytics.pageViews({ paths: ['/'], days: 30 });
+ *
+ * // A batch of pages in one round-trip
+ * const list = await biab.site(siteId).analytics.pageViews({
+ *   paths: ['/tech/typescript', '/tech/rust'],
+ * });
+ * // list.paths → [{ path, views, visitors }, …], every requested path present
+ * ```
+ *
+ * `visitors` approximates unique visitors (distinct daily-rotating anon id).
+ * Requires the `analytics.web` entitlement — an org without it gets
+ * `{ available: false }`, so branch on `.available`.
+ */
+export class BiabDevAnalyticsClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	/**
+	 * Pageview + visitor counts. Pass `paths` for a per-path breakdown (plus a
+	 * combined `total`), or omit them for a site-wide `total`. `days` windows the
+	 * count; omit for all-time.
+	 */
+	async pageViews(input: PageViewsInput = {}): Promise<PageViewsResponse> {
+		const { paths, days } = pageViewsInputSchema.parse(input);
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/analytics/views`,
+			query: {
+				// `path` repeats once per requested path; the route reads getAll.
+				...(paths && paths.length > 0 ? { path: paths } : {}),
+				...(days !== undefined ? { days } : {}),
+			},
+			responseSchema: pageViewsResponseSchema,
+		});
+	}
+
+	/**
+	 * Which AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) actually fetched
+	 * this site's pages: fetch counts, distinct pages read, vendor, intent
+	 * (training / search / live-assistant), and when each last came.
+	 *
+	 * First-party AEO visibility — recorded when crawlers hit the tracker (the
+	 * assistant browsing agents run JS) and when your server reports the rest
+	 * via `reportAiCrawlerHit` from `@businessdash/sdk/analytics-server`. Defaults
+	 * to a 30-day window.
+	 *
+	 * ```ts
+	 * const ai = await biab.site(siteId).analytics.aiVisibility({ days: 30 });
+	 * if (ai.available) {
+	 *   for (const c of ai.crawlers)
+	 *     console.log(`${c.name}: ${c.fetches} fetches over ${c.distinctPages} pages`);
+	 * }
+	 * ```
+	 */
+	async aiVisibility(
+		input: AiVisibilityInput = {},
+	): Promise<AiVisibilityResponse> {
+		const { days } = aiVisibilityInputSchema.parse(input);
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/analytics/ai-crawlers`,
+			query: { ...(days !== undefined ? { days } : {}) },
+			responseSchema: aiVisibilityResponseSchema,
+		});
+	}
+}
+
+/**
+ * The "Powered by BusinessDash" attribution badge's one narrow function.
+ *
+ * `<BusinessDashFooter/>` uses this to (a) read whether the badge is required on
+ * this plan and (b) optionally report that it rendered. Both are scoped to your
+ * own site with a publishable key.
+ *
+ * ⚠️ The heartbeat is a courtesy signal, not proof of anything — BusinessDash
+ * verifies the badge by fetching your live domain, not by trusting this call. So
+ * don't build logic on the heartbeat; do honor `policy().required`.
+ */
+export class BiabDevAttributionClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	/**
+	 * This site's badge policy: `{ siteId, required }`. `required` is `true` on
+	 * plans that can't remove the badge (launch), `false` otherwise. Build the
+	 * badge's `?ref=<siteId>` backlink from `siteId`.
+	 */
+	async policy(): Promise<AttributionPolicy> {
+		return this.client.request({
+			path: `sites/${encodeURIComponent(this.siteId)}/attribution`,
+			responseSchema: attributionPolicySchema,
+		});
+	}
+
+	/**
+	 * Report that the badge rendered on `url`. Best-effort and untrusted — it
+	 * never throws for a bad URL (you get `{ recorded: false }`), and it's safe to
+	 * fire-and-forget. Don't await it in a render path.
+	 */
+	async heartbeat(
+		input: AttributionHeartbeatInput,
+	): Promise<AttributionHeartbeatResponse> {
+		const body = attributionHeartbeatInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/attribution/heartbeat`,
+			body,
+			responseSchema: attributionHeartbeatResponseSchema,
+		});
+	}
+}
+
+export class BiabDevAssetsClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	async create(input: SiteAssetInput): Promise<UploadSiteAssetResponse> {
+		const body = siteAssetInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/assets`,
+			body,
+			responseSchema: uploadSiteAssetResponseSchema,
+		});
+	}
+}
+
+export class BiabDevActionsClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	async run(
+		actionName: string,
+		input: ExecuteActionInput = { payload: {} },
+	): Promise<ExecuteActionResponse> {
+		const body = executeActionInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: `sites/${encodeURIComponent(this.siteId)}/actions/${encodeURIComponent(actionName)}`,
+			body,
+			responseSchema: executeActionResponseSchema,
+		});
+	}
+}
+
+export class BiabDevEmailTemplatesClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	async list(
+		input: ListEmailTemplatesInput = {},
+	): Promise<ListEmailTemplatesResponse> {
+		const query = listEmailTemplatesInputSchema.parse(input);
+
+		return this.client.request({
+			path: "email/templates",
+			query,
+			responseSchema: listEmailTemplatesResponseSchema,
+		});
+	}
+
+	async get(templateId: number): Promise<GetEmailTemplateResponse> {
+		return this.client.request({
+			path: `email/templates/${templateId}`,
+			responseSchema: getEmailTemplateResponseSchema,
+		});
+	}
+
+	async create(
+		input: CreateEmailTemplateInput,
+	): Promise<CreateEmailTemplateResponse> {
+		const body = createEmailTemplateInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: "email/templates",
+			body,
+			responseSchema: createEmailTemplateResponseSchema,
+		});
+	}
+
+	async createVersion(
+		templateId: number,
+		input: CreateEmailTemplateVersionInput,
+	): Promise<CreateEmailTemplateVersionResponse> {
+		const body = createEmailTemplateVersionInputSchema.parse(input);
+
+		return this.client.request({
+			method: "POST",
+			path: `email/templates/${templateId}/versions`,
+			body,
+			responseSchema: createEmailTemplateVersionResponseSchema,
+		});
+	}
+}
+
+export class BiabDevFollowersClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly siteId: string,
+	) {}
+
+	private actionPath(action: string) {
+		return `sites/${encodeURIComponent(this.siteId)}/actions/${encodeURIComponent(action)}`;
+	}
+
+	async join(input: FollowerJoinInput): Promise<FollowerJoinResponse> {
+		const payload = followerJoinInputSchema.parse(input);
+		const body = executeActionInputSchema.parse({ payload });
+		const response = await this.client.request({
+			method: "POST",
+			path: this.actionPath("followers.join"),
+			body,
+			responseSchema: executeActionResponseSchema,
+		});
+		return followerJoinResponseSchema.parse(response.result);
+	}
+
+	async me(input: FollowerMeInput): Promise<FollowerMeResponse> {
+		const payload = followerMeInputSchema.parse(input);
+		const body = executeActionInputSchema.parse({ payload });
+		const response = await this.client.request({
+			method: "POST",
+			path: this.actionPath("followers.me"),
+			body,
+			responseSchema: executeActionResponseSchema,
+		});
+		return followerMeResponseSchema.parse(response.result);
+	}
+
+	async edit(input: FollowerEditInput): Promise<FollowerEditResponse> {
+		const payload = followerEditInputSchema.parse(input);
+		const body = executeActionInputSchema.parse({ payload });
+		const response = await this.client.request({
+			method: "POST",
+			path: this.actionPath("followers.edit"),
+			body,
+			responseSchema: executeActionResponseSchema,
+		});
+		return followerEditResponseSchema.parse(response.result);
+	}
+
+	async leave(input: FollowerLeaveInput): Promise<FollowerLeaveResponse> {
+		const payload = followerLeaveInputSchema.parse(input);
+		const body = executeActionInputSchema.parse({ payload });
+		const response = await this.client.request({
+			method: "POST",
+			path: this.actionPath("followers.leave"),
+			body,
+			responseSchema: executeActionResponseSchema,
+		});
+		return followerLeaveResponseSchema.parse(response.result);
+	}
+}
+
+export class BiabDevDashboardClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	async createSession(): Promise<DashboardSessionResponse> {
+		return this.client.request({
+			method: "POST",
+			path: "dashboard/session",
+			responseSchema: dashboardSessionResponseSchema,
+		});
+	}
+}
+
+export class BiabDevStorefrontClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	/**
+	 * Legacy embed-session mint (kept for iframe-widget consumers).
+	 * The programmatic methods below let consumer sites render their
+	 * own native product catalog using BIAB as the data layer.
+	 */
+	async createSession(
+		input?: StorefrontSessionInput,
+	): Promise<StorefrontSessionResponse> {
+		const body = storefrontSessionInputSchema.parse(input ?? undefined);
+		return this.client.request({
+			method: "POST",
+			path: "storefront/session",
+			body: body ?? {},
+			responseSchema: storefrontSessionResponseSchema,
+		});
+	}
+
+	/**
+	 * Paginated list of live products for the calling org's storefront.
+	 * Cursor is an opaque integer offset — pass back the response's
+	 * `nextCursor` to fetch the next page. Filter by category via the
+	 * `categoryId` option.
+	 */
+	async listProducts(input?: {
+		limit?: number;
+		cursor?: number | null;
+		categoryId?: string;
+	}): Promise<StorefrontListProductsResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		if (input?.cursor != null) query["cursor"] = input.cursor;
+		if (input?.categoryId) query["categoryId"] = input.categoryId;
+		return this.client.request({
+			path: "storefront/products",
+			query,
+			responseSchema: storefrontListProductsResponseSchema,
+		});
+	}
+
+	/**
+	 * Filterable listing grid with facets — the data behind a full shop page.
+	 * Returns enriched per-card price/ratings/badges plus `categoryCounts` and
+	 * the catalog-wide `priceRange` for a sidebar. Supports `search`,
+	 * `categoryId`, `minPriceCents`/`maxPriceCents`, `minRating` (1–5), and
+	 * `sort` (featured | newest | price-asc | price-desc | rating-desc).
+	 */
+	async listProductsWithMeta(input?: {
+		search?: string;
+		categoryId?: string;
+		minPriceCents?: number;
+		maxPriceCents?: number;
+		minRating?: number;
+		sort?: StorefrontSort;
+		limit?: number;
+		/** Dev-only: also surface pending (non-live) products. Caller-gated. */
+		preview?: boolean;
+	}): Promise<StorefrontProductsWithMetaResponse> {
+		const query: Record<string, string | number | undefined> = { meta: "1" };
+		if (input?.search) query["search"] = input.search;
+		if (input?.categoryId) query["categoryId"] = input.categoryId;
+		if (input?.minPriceCents != null)
+			query["minPriceCents"] = input.minPriceCents;
+		if (input?.maxPriceCents != null)
+			query["maxPriceCents"] = input.maxPriceCents;
+		if (input?.minRating != null) query["minRating"] = input.minRating;
+		if (input?.sort) query["sort"] = input.sort;
+		if (input?.limit != null) query["limit"] = input.limit;
+		if (input?.preview) query["preview"] = "1";
+		return this.client.request({
+			path: "storefront/products",
+			query,
+			responseSchema: storefrontProductsWithMetaResponseSchema,
+		});
+	}
+
+	/** Org-scoped product categories for a storefront sidebar. */
+	async listCategories(): Promise<StorefrontCategoriesResponse> {
+		return this.client.request({
+			path: "storefront/categories",
+			responseSchema: storefrontCategoriesResponseSchema,
+		});
+	}
+
+	/**
+	 * Full product detail with variants + per-image rows. Returns 404
+	 * via `BiabApiError` if the product isn't live or doesn't belong
+	 * to the org bound to the API key.
+	 */
+	async getProduct(productId: string): Promise<StorefrontProductDetail> {
+		return this.client.request({
+			path: `storefront/products/${encodeURIComponent(productId)}`,
+			responseSchema: storefrontProductDetailSchema,
+		});
+	}
+
+	/** Approved reviews for a product + aggregate (`avgRating`, `totalCount`).
+	 *  Cursor-paginated — pass back `nextCursor` for the next page. */
+	async getProductReviews(
+		productId: string,
+		input?: { limit?: number; cursor?: number | null },
+	): Promise<StorefrontProductReviewsResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		if (input?.cursor != null) query["cursor"] = input.cursor;
+		return this.client.request({
+			path: `storefront/products/${encodeURIComponent(productId)}/reviews`,
+			query,
+			responseSchema: storefrontProductReviewsResponseSchema,
+		});
+	}
+
+	/** "You may also like" — same-category / paired recommendations. */
+	async getRelatedProducts(
+		productId: string,
+		input?: { limit?: number },
+	): Promise<StorefrontRelatedProductsResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		return this.client.request({
+			path: `storefront/products/${encodeURIComponent(productId)}/related`,
+			query,
+			responseSchema: storefrontRelatedProductsResponseSchema,
+		});
+	}
+
+	/** Companion / exclusive cross-sell addons for the "complete your X" rail. */
+	async getProductAddons(productId: string): Promise<StorefrontAddonsResponse> {
+		return this.client.request({
+			path: `storefront/products/${encodeURIComponent(productId)}/addons`,
+			responseSchema: storefrontAddonsResponseSchema,
+		});
+	}
+}
+
+export class BiabDevCartClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly visitorToken: string | null = null,
+		private readonly sessionToken: string | null = null,
+	) {}
+
+	/**
+	 * Use an anonymous visitor token (UUID stored in the consumer's
+	 * own httpOnly cookie). Same shopper across page loads, no
+	 * sign-in required.
+	 */
+	forVisitor(visitorToken: string): BiabDevCartClient {
+		return new BiabDevCartClient(this.client, visitorToken, null);
+	}
+
+	/**
+	 * Use a tenantAuth session token instead of a visitor token.
+	 * Carts are now keyed to the signed-in customer; persists
+	 * across devices.
+	 */
+	withSession(sessionToken: string): BiabDevCartClient {
+		return new BiabDevCartClient(this.client, null, sessionToken);
+	}
+
+	private headers(): HeadersInit {
+		const out: Record<string, string> = {};
+		if (this.visitorToken) out["X-BIAB-Cart-Visitor"] = this.visitorToken;
+		if (this.sessionToken) out["X-BIAB-Session-Token"] = this.sessionToken;
+		return out;
+	}
+
+	/**
+	 * Legacy embed-session mint (kept for iframe-widget consumers).
+	 * The programmatic methods below let the consumer site render
+	 * its own native cart UI.
+	 */
+	async createSession(): Promise<CartSessionResponse> {
+		return this.client.request({
+			method: "POST",
+			path: "cart/session",
+			responseSchema: cartSessionResponseSchema,
+		});
+	}
+
+	/**
+	 * Read the current cart snapshot — item count, items with
+	 * resolved product detail (name, image, variant title, unit
+	 * price), subtotal, currency. Auto-creates an empty cart row
+	 * the first time it's called for a new visitor/session, so
+	 * the consumer always gets a valid snapshot.
+	 */
+	async get(): Promise<CartSnapshot> {
+		return this.client.request({
+			path: "cart",
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Add a product (optionally with a variant) to the cart. If the
+	 * (productId, variantId) already exists, increments its quantity
+	 * rather than creating a duplicate line.
+	 */
+	async addItem(input: CartAddItemInput): Promise<CartSnapshot> {
+		const body = cartAddItemInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "cart/items",
+			body,
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Set a line's quantity. Pass quantity=0 to delete the line.
+	 */
+	async updateItem(
+		itemId: string,
+		input: CartUpdateItemInput,
+	): Promise<CartSnapshot> {
+		const body = cartUpdateItemInputSchema.parse(input);
+		return this.client.request({
+			method: "PATCH",
+			path: `cart/items/${encodeURIComponent(itemId)}`,
+			body,
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+
+	async removeItem(itemId: string): Promise<CartSnapshot> {
+		return this.client.request({
+			method: "DELETE",
+			path: `cart/items/${encodeURIComponent(itemId)}`,
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Stamp a coupon code on the cart. Validation runs at checkout —
+	 * stamping here is a no-op when invalid; the consumer learns
+	 * via the Stripe-checkout-session response whether the code
+	 * actually applies.
+	 */
+	async applyCoupon(input: CartCouponInput): Promise<CartSnapshot> {
+		const body = cartCouponInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "cart/coupon",
+			body,
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+
+	async removeCoupon(): Promise<CartSnapshot> {
+		return this.client.request({
+			method: "DELETE",
+			path: "cart/coupon",
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Empty all items + drop the stamped coupon. Keeps the cart row itself. */
+	async clear(): Promise<CartSnapshot> {
+		return this.client.request({
+			method: "POST",
+			path: "cart/clear",
+			responseSchema: cartSnapshotSchema,
+			headers: this.headers(),
+		});
+	}
+}
+
+export class BiabDevCheckoutClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly visitorToken: string | null = null,
+		private readonly sessionToken: string | null = null,
+	) {}
+
+	/**
+	 * Authenticate the start-from-cart call as an anonymous shopper
+	 * (visitor-token cart). Same UUID you used with `client.cart.forVisitor(...)`.
+	 */
+	forVisitor(visitorToken: string): BiabDevCheckoutClient {
+		return new BiabDevCheckoutClient(this.client, visitorToken, null);
+	}
+
+	/**
+	 * Authenticate as a signed-in customer (tenantAuth session token).
+	 * The Stripe Checkout Session will be created against this
+	 * customer's saved cart.
+	 */
+	withSession(sessionToken: string): BiabDevCheckoutClient {
+		return new BiabDevCheckoutClient(this.client, null, sessionToken);
+	}
+
+	private headers(): HeadersInit {
+		const out: Record<string, string> = {};
+		if (this.visitorToken) out["X-BIAB-Cart-Visitor"] = this.visitorToken;
+		if (this.sessionToken) out["X-BIAB-Session-Token"] = this.sessionToken;
+		return out;
+	}
+
+	/**
+	 * Legacy iframe-embed mint — gives back a tokenized URL to render
+	 * inside an iframe that redirects to Stripe. Kept for `<Checkout/>`
+	 * consumers; new code should call `start()` for native handoff.
+	 */
+	async createSession(
+		input: CheckoutSessionInput,
+	): Promise<CheckoutSessionResponse> {
+		const body = checkoutSessionInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "checkout/session",
+			body,
+			responseSchema: checkoutSessionResponseSchema,
+		});
+	}
+
+	/**
+	 * Convert the caller's saved BIAB cart (resolved via visitor token
+	 * or session token) into a Stripe Checkout Session. Returns the
+	 * Stripe-hosted URL; redirect the browser there to collect payment.
+	 *
+	 * `successUrl` + `cancelUrl` may be full URLs on the consumer's own
+	 * domain. We append `session_id={CHECKOUT_SESSION_ID}` to the
+	 * success URL automatically so the success page can call
+	 * `getStatus(sessionId)` to confirm payment.
+	 */
+	async start(input?: CheckoutStartInput): Promise<CheckoutStartResponse> {
+		const body = checkoutStartInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "checkout/start",
+			body: body ?? {},
+			responseSchema: checkoutStartResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Look up a Stripe Checkout Session by id. Returns paid / unpaid
+	 * status plus the customer details Stripe collected — what the
+	 * consumer's "thank you" page calls before rendering.
+	 */
+	async getStatus(sessionId: string): Promise<CheckoutStatusResponse> {
+		return this.client.request({
+			path: `checkout/${encodeURIComponent(sessionId)}`,
+			responseSchema: checkoutStatusResponseSchema,
+		});
+	}
+}
+
+/**
+ * White-glove Google Places proxy. BIAB owns the API key — consumer
+ * code never sees it. Use at the checkout delivery-address input
+ * to give shoppers text-search predictions + verify deliverability
+ * before submitting the order.
+ *
+ * Mirrors the working reference in `Resources/addressParser/`:
+ *   - `search(query)` — text-search predictions (uses Google
+ *     `places:searchText`)
+ *   - `getDetails(placeId)` — placeId → `GoogleAddress` shape
+ *   - `verify(form)` — text-searches the entered address and
+ *     compares component-by-component
+ *
+ * Three pure converters are exported alongside as static methods —
+ * the same ones the reference React hooks wrap, just plain functions
+ * so they work outside React too.
+ *
+ * @example
+ * ```tsx
+ * // On each keystroke (debounced):
+ * const result = await client.address.search({ query: input });
+ * if (!result.enabled) return; // platform not configured; show plain input
+ *
+ * // When user picks a prediction:
+ * const detail = await client.address.getDetails(prediction.place_id);
+ * if (detail.enabled && detail.address) {
+ *   const form = BiabDevAddressClient.googleToFormValues(detail.address);
+ *   reactHookForm.reset(form);
+ * }
+ *
+ * // Before submitting the order:
+ * const v = await client.address.verify(form);
+ * if (!v.isVerified) showDidYouMean(v.googleAddress);
+ * ```
+ */
+export class BiabDevAddressClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	async search(input: AddressSearchInput): Promise<AddressSearchResponse> {
+		const body = addressSearchInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "address/search",
+			body,
+			responseSchema: addressSearchResponseSchema,
+		});
+	}
+
+	async getDetails(placeId: string): Promise<AddressDetailsResponse> {
+		return this.client.request({
+			path: `address/details/${encodeURIComponent(placeId)}`,
+			responseSchema: addressDetailsResponseSchema,
+		});
+	}
+
+	async verify(input: AddressFormValues): Promise<AddressVerifyResponse> {
+		const body = addressFormValuesSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "address/validate",
+			body,
+			responseSchema: addressVerifyResponseSchema,
+		});
+	}
+
+	/** Convert Google's `GoogleAddress` shape into a form-values object. */
+	static googleToFormValues(g: GoogleAddress): AddressFormValues {
+		return {
+			address_ln1: `${g.street_number} ${g.route}`.trim(),
+			address_ln2: g.subpremise ?? "",
+			city: g.locality,
+			state: g.administrative_area_level_1,
+			zip: g.postal_code,
+			country: g.country,
+		};
+	}
+
+	/** Convert a form-values object into Stripe's billing-address shape. */
+	static formToStripeAddress(a: AddressFormValues): {
+		line1: string;
+		line2: string | null;
+		city: string;
+		state: string;
+		postal_code: string;
+		country: string;
+	} {
+		return {
+			line1: a.address_ln1,
+			line2: a.address_ln2 || null,
+			city: a.city,
+			state: a.state,
+			postal_code: a.zip,
+			country: a.country,
+		};
+	}
+}
+
+/**
+ * Org-side recurring offerings (gym memberships, monthly service
+ * plans, software subscriptions). Lists are public read; the
+ * checkout-start endpoint hands the customer off to Stripe-hosted
+ * Checkout in `mode: 'subscription'`.
+ *
+ * Requires the org to have synced each offering to Stripe via the
+ * dashboard's "Sync to Stripe" action — otherwise `startCheckout`
+ * returns 409 `subscription_not_synced`.
+ */
+export class BiabDevSubscriptionsClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	async list(): Promise<SubscriptionOfferingsListResponse> {
+		return this.client.request({
+			path: "subscriptions",
+			responseSchema: subscriptionOfferingsListResponseSchema,
+		});
+	}
+
+	async get(id: string): Promise<SubscriptionOffering> {
+		return this.client.request({
+			path: `subscriptions/${encodeURIComponent(id)}`,
+			responseSchema: subscriptionOfferingSchema,
+		});
+	}
+
+	async startCheckout(
+		id: string,
+		input?: SubscriptionCheckoutInput,
+	): Promise<SubscriptionCheckoutResponse> {
+		const body = subscriptionCheckoutInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `subscriptions/${encodeURIComponent(id)}/checkout`,
+			body: body ?? {},
+			responseSchema: subscriptionCheckoutResponseSchema,
+		});
+	}
+}
+
+export class BiabDevCouponsClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	/**
+	 * Validate a coupon code against the org's Stripe-connected
+	 * account. Returns the discount shape (percent / amount /
+	 * duration) when valid; `{ valid: false, reason, message }`
+	 * otherwise so the consumer's UI can show "$10 off" before the
+	 * shopper proceeds to checkout.
+	 *
+	 * Source of truth is Stripe — what this endpoint validates is
+	 * exactly what Stripe-hosted Checkout will accept.
+	 *
+	 * @example
+	 * ```ts
+	 * const result = await client.coupons.validate("SAVE10");
+	 * if (result.valid) showDiscount(result.percentOff ?? result.amountOffCents);
+	 * else toast.error(result.message);
+	 * ```
+	 */
+	async validate(code: string): Promise<CouponValidateResponse> {
+		const body = couponValidateInputSchema.parse({ code });
+		return this.client.request({
+			method: "POST",
+			path: "coupons/validate",
+			body,
+			responseSchema: couponValidateResponseSchema,
+		});
+	}
+}
+
+/**
+ * Shipping: rate lookups + on-demand tracking. White-glove model —
+ * BIAB owns the carrier integration; consumer code never sees the
+ * underlying provider name. Gated on `ecommerce.shipping` so calls
+ * from orgs on the Launch plan return the standard plan-gate body
+ * via {@link BiabApiError} (status 403).
+ *
+ * @example
+ * ```ts
+ * const { options, requiresShipping } = await client.shipping
+ *   .forVisitor(visitorToken)
+ *   .getRates({ deliveryAddress });
+ * if (!requiresShipping) skipShippingStep();
+ * else {
+ *   const picked = options[0]; // cheapest
+ *   await client.checkout.forVisitor(visitorToken).start({
+ *     shipping: picked,
+ *     successUrl, cancelUrl,
+ *   });
+ * }
+ * ```
+ */
+export class BiabDevShippingClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly visitorToken: string | null = null,
+		private readonly sessionToken: string | null = null,
+	) {}
+
+	forVisitor(visitorToken: string): BiabDevShippingClient {
+		return new BiabDevShippingClient(this.client, visitorToken, null);
+	}
+
+	withSession(sessionToken: string): BiabDevShippingClient {
+		return new BiabDevShippingClient(this.client, null, sessionToken);
+	}
+
+	private headers(): HeadersInit {
+		const out: Record<string, string> = {};
+		if (this.visitorToken) out["X-BIAB-Cart-Visitor"] = this.visitorToken;
+		if (this.sessionToken) out["X-BIAB-Session-Token"] = this.sessionToken;
+		return out;
+	}
+
+	/**
+	 * Fetch shipping rate options for the caller's cart + a delivery
+	 * address. Multi-origin + multi-parcel orders surface as a single
+	 * combined cost per service tier (carrier+speed). Pass the chosen
+	 * option directly to `client.checkout.start({ shipping })`.
+	 */
+	async getRates(input: ShippingRatesInput): Promise<ShippingRatesResponse> {
+		const body = shippingRatesInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "shipping/rates",
+			body,
+			responseSchema: shippingRatesResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * On-demand tracking lookup for a known tracking number. Returns
+	 * the cached `status_history` we already received via webhook
+	 * PLUS a fresh poll against the carrier (`liveStatus`). Consumer
+	 * apps that don't subscribe to push notifications use this to
+	 * refresh "Where's my order?" pages.
+	 */
+	async track(input: {
+		trackingNumber: string;
+	}): Promise<ShippingTrackResponse> {
+		return this.client.request({
+			path: `shipping/track/${encodeURIComponent(input.trackingNumber)}`,
+			responseSchema: shippingTrackResponseSchema,
+		});
+	}
+
+	/**
+	 * The org's storefront shipping config — whether shipping is on, a coarse
+	 * "ships from" (city/state/country), the destinations it ships to, the duty
+	 * model, and preferred carriers. Sanitized (no keys/secrets, no precise
+	 * origin address). Render shipping copy without the org re-declaring it.
+	 *
+	 * @example
+	 * ```ts
+	 * const s = await client.shipping.settings();
+	 * if (s.enabled) show(`Ships to ${s.allowedDestinationCountries?.join(", ") ?? "anywhere"}`);
+	 * ```
+	 */
+	async settings(): Promise<ShippingSettingsResponse> {
+		return this.client.request({
+			path: "shipping/settings",
+			responseSchema: shippingSettingsResponseSchema,
+		});
+	}
+}
+
+/**
+ * Customer notification preferences. Per-customer-per-org channel
+ * settings (in-app / email / SMS / outbound webhook). Identified by
+ * the tenantAuth session token — bind with `.withSession(token)`.
+ *
+ * Outbound-webhook events the consumer site can subscribe to are
+ * the same as the shipping fan-out keys:
+ *   - `order.shipped`
+ *   - `order.out_for_delivery`
+ *   - `order.delivered`
+ *   - `order.exception`
+ *   - `order.return_label_created`
+ *
+ * The webhook payload is JSON + signed with the customer's saved
+ * `webhookSigningSecret` via `X-BIAB-Signature: <hex hmac-sha256>`.
+ * Consumer's receiver verifies via:
+ *   crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
+ */
+export class BiabDevNotificationsClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly sessionToken: string | null = null,
+	) {}
+
+	withSession(sessionToken: string): BiabDevNotificationsClient {
+		return new BiabDevNotificationsClient(this.client, sessionToken);
+	}
+
+	private headers(): HeadersInit {
+		return this.sessionToken
+			? { "X-BIAB-Session-Token": this.sessionToken }
+			: {};
+	}
+
+	async getPreferences(): Promise<CustomerNotificationPreferencesResponse> {
+		return this.client.request({
+			path: "notifications/preferences",
+			responseSchema: customerNotificationPreferencesResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	async updatePreferences(
+		input: CustomerNotificationPreferencesUpdateInput,
+	): Promise<CustomerNotificationPreferencesUpdateResponse> {
+		const body = customerNotificationPreferencesUpdateInputSchema.parse(input);
+		return this.client.request({
+			method: "PATCH",
+			path: "notifications/preferences",
+			body,
+			responseSchema: customerNotificationPreferencesUpdateResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Start a verification flow for a destination the customer wants to
+	 * use for shipping notifications. Email: a verification link is sent
+	 * (15-min TTL). Phone: a 6-digit OTP is sent (5-min TTL).
+	 *
+	 * Until verified, the channel stays inert — preventing the customer
+	 * from spamming arbitrary destinations.
+	 */
+	async startVerification(
+		input: StartVerificationInput,
+	): Promise<StartVerificationResponse> {
+		const body = startVerificationInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "notifications/preferences/verify",
+			body,
+			responseSchema: startVerificationResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Consume the verification token from the email link / SMS OTP.
+	 * On success: stamps `*VerifiedAt` on the prefs row + activates the
+	 * channel.
+	 */
+	async confirmVerification(
+		input: ConfirmVerificationInput,
+	): Promise<ConfirmVerificationResponse> {
+		const body = confirmVerificationInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "notifications/preferences/verify/confirm",
+			body,
+			responseSchema: confirmVerificationResponseSchema,
+			headers: this.headers(),
+		});
+	}
+}
+
+export class BiabDevBlogClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly sessionToken: string | null = null,
+	) {}
+
+	/**
+	 * Chainable: return a blog client whose `postComment` + future
+	 * write methods authenticate via the tenantAuth session token.
+	 * Reads (listPosts, getPost, listCategories, listTags, listComments)
+	 * don't require a session and work the same either way.
+	 *
+	 * @example
+	 * ```ts
+	 * await client.blog().withSession(token).postComment(slug, { content });
+	 * ```
+	 */
+	withSession(sessionToken: string): BiabDevBlogClient {
+		return new BiabDevBlogClient(this.client, sessionToken);
+	}
+
+	private headers(): HeadersInit {
+		return this.sessionToken
+			? { "X-BIAB-Session-Token": this.sessionToken }
+			: {};
+	}
+
+	/**
+	 * Legacy embed-session mint (kept for backwards compat with
+	 * embedded-iframe consumers).
+	 */
+	async createSession(input?: BlogSessionInput): Promise<BlogSessionResponse> {
+		const body = blogSessionInputSchema.parse(input ?? undefined);
+		return this.client.request({
+			method: "POST",
+			path: "blog/session",
+			body: body ?? {},
+			responseSchema: blogSessionResponseSchema,
+		});
+	}
+
+	/**
+	 * Paginated list of published blog posts for the calling org's
+	 * site. Cursor is an opaque number — pass back the `nextCursor`
+	 * from the previous response to fetch the next page.
+	 */
+	async listPosts(input?: {
+		limit?: number;
+		cursor?: number | null;
+		categoryId?: string;
+	}): Promise<BlogListPostsResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		if (input?.cursor != null) query["cursor"] = input.cursor;
+		if (input?.categoryId) query["categoryId"] = input.categoryId;
+		return this.client.request({
+			path: "blog/posts",
+			query,
+			responseSchema: blogListPostsResponseSchema,
+		});
+	}
+
+	/**
+	 * Get a single post by its slug. Returns `{ post, access }`
+	 * where `access === 'paywall'` and `post.content === ''` for
+	 * posts marked `accessLevel: 'paid' | 'followers'`. The
+	 * consumer renders a paywall over the empty body when access
+	 * is restricted.
+	 */
+	async getPost(slug: string): Promise<BlogPostBySlugResponse> {
+		return this.client.request({
+			path: `blog/posts/${encodeURIComponent(slug)}`,
+			responseSchema: blogPostBySlugResponseSchema,
+		});
+	}
+
+	async listCategories(): Promise<BlogCategoryListResponse> {
+		return this.client.request({
+			path: "blog/categories",
+			responseSchema: blogCategoryListResponseSchema,
+		});
+	}
+
+	async listTags(): Promise<BlogTagListResponse> {
+		return this.client.request({
+			path: "blog/tags",
+			responseSchema: blogTagListResponseSchema,
+		});
+	}
+
+	async listComments(
+		slug: string,
+		input?: { limit?: number; cursor?: number | null },
+	): Promise<BlogCommentListResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		if (input?.cursor != null) query["cursor"] = input.cursor;
+		return this.client.request({
+			path: `blog/posts/${encodeURIComponent(slug)}/comments`,
+			query,
+			responseSchema: blogCommentListResponseSchema,
+		});
+	}
+
+	/**
+	 * Submit a comment on a published post. Requires `withSession()` —
+	 * anonymous comments aren't supported in 0.9.0 (the blog_comments
+	 * row references a `user_id` text column that's NOT NULL). The
+	 * server runs the same moderation screener used by the dashboard
+	 * tRPC path; the response surfaces both the comment row + the
+	 * moderation verdict so the consumer can show "your comment is
+	 * pending review" when applicable.
+	 */
+	async postComment(
+		slug: string,
+		input: BlogCommentPostInput,
+	): Promise<BlogCommentPostResponse> {
+		const body = blogCommentPostInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `blog/posts/${encodeURIComponent(slug)}/comments`,
+			body,
+			responseSchema: blogCommentPostResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Current like state + count for a post. With `withSession()`, `liked`
+	 * reflects whether this visitor already liked it (filled heart on load);
+	 * without a session the public count is returned with `liked: false`.
+	 */
+	async likeStatus(slug: string): Promise<BlogLikeResponse> {
+		return this.client.request({
+			path: `blog/posts/${encodeURIComponent(slug)}/like`,
+			responseSchema: blogLikeResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Toggle the session visitor's like on a post. Requires `withSession()`
+	 * (same identity as `postComment`). Returns the new like state + count.
+	 */
+	async toggleLike(slug: string): Promise<BlogLikeResponse> {
+		return this.client.request({
+			method: "POST",
+			path: `blog/posts/${encodeURIComponent(slug)}/like`,
+			responseSchema: blogLikeResponseSchema,
+			headers: this.headers(),
+		});
+	}
+}
+
+/**
+ * Public reviews-wall client. Reads the org's external reviews
+ * (Google + Yelp + manual + CSV) — the same store the marketing bundle's
+ * `reviews` aggregate is built from. The bundle ships the first page + the
+ * aggregate (count / average / histogram); use this to lazily fetch deeper
+ * pages on "View all" / scroll.
+ *
+ * @example
+ * ```ts
+ * const page1 = await client.reviews.list({ limit: 10 });
+ * if (page1.nextOffset != null) {
+ *   const page2 = await client.reviews.list({ limit: 10, offset: page1.nextOffset });
+ * }
+ * ```
+ */
+export class BiabDevReviewsClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	/**
+	 * One page of the org's public reviews, newest-first. `limit` defaults to
+	 * the server default (10, max 50). Pass the previous response's
+	 * `nextOffset` to page forward — it's `null` once the list is exhausted.
+	 * `source` narrows to a single platform (e.g. `"yelp"`).
+	 */
+	async list(input?: {
+		limit?: number;
+		offset?: number;
+		source?: "google" | "yelp" | "housecall_pro" | "other";
+	}): Promise<ReviewWallListResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		if (input?.offset !== undefined) query["offset"] = input.offset;
+		if (input?.source) query["source"] = input.source;
+		return this.client.request({
+			path: "reviews",
+			query,
+			responseSchema: reviewWallListResponseSchema,
+		});
+	}
+}
+
+/**
+ * Public hiring client — the org's open job postings and their categories, so
+ * a consumer can render a careers page in their own design system.
+ *
+ * Read-only by construction: everything returned is content the org published
+ * for candidates. To take applications, hand the posting's `applicationFormId`
+ * to the forms surface — this client grants no submit path of its own.
+ *
+ * @example
+ * ```ts
+ * const { items } = await client.hiring.list({ limit: 20 });
+ * const posting = await client.hiring.get("senior-installer");
+ * if (posting.applicationFormId) {
+ *   const form = await client.forms.schema(posting.applicationFormId);
+ * }
+ * ```
+ */
+export class BiabDevHiringClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	/**
+	 * One page of open postings, newest-first. `limit` defaults to the server
+	 * default (25, max 100). Pass the previous response's `nextOffset` to page
+	 * forward — it's `null` once the list is exhausted. `category` narrows to a
+	 * single group by its slug.
+	 *
+	 * Only postings that are published, active, have seats left, and are under
+	 * their application cap are returned, so a careers page never advertises a
+	 * role that can no longer be applied to.
+	 */
+	async list(input?: {
+		limit?: number;
+		offset?: number;
+		category?: string;
+	}): Promise<JobPostingListResponse> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input?.limit !== undefined) query["limit"] = input.limit;
+		if (input?.offset !== undefined) query["offset"] = input.offset;
+		if (input?.category) query["category"] = input.category;
+		return this.client.request({
+			path: "hiring/jobs",
+			query,
+			responseSchema: jobPostingListResponseSchema,
+		});
+	}
+
+	/**
+	 * One open posting by slug. Rejects with a 404 error when the posting is a
+	 * draft, closed, archived, fully filled, or has hit its application cap —
+	 * treat that as "this role is gone" rather than as a transient failure.
+	 */
+	async get(slug: string): Promise<JobPosting> {
+		return this.client.request({
+			path: `hiring/jobs/${encodeURIComponent(slug)}`,
+			responseSchema: jobPostingSchema,
+		});
+	}
+
+	/**
+	 * The org's job categories with a count of open postings in each — enough to
+	 * render filter chips or grouped sections without fetching every posting.
+	 */
+	async categories(): Promise<JobCategoryListResponse> {
+		return this.client.request({
+			path: "hiring/categories",
+			responseSchema: jobCategoryListResponseSchema,
+		});
+	}
+}
+
+export class BiabDevChatbotClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	/** Returns the iframe URL for `<Chatbot/>`. */
+	async createSession(): Promise<ChatbotSessionResponse> {
+		return this.client.request({
+			method: "POST",
+			path: "chatbot/session",
+			responseSchema: chatbotSessionResponseSchema,
+		});
+	}
+
+	/** Reads the org's persisted chatbot config (system prompt, KB, model). */
+	async getConfig(): Promise<ChatbotConfig> {
+		return this.client.request({
+			method: "GET",
+			path: "chatbot/config",
+			responseSchema: chatbotConfigSchema,
+		});
+	}
+
+	/**
+	 * Persists the org's chatbot config. Requires `chatbot:write` scope on the
+	 * API key — typically only used by admin tools, not embedded widgets.
+	 */
+	async updateConfig(input: ChatbotConfigUpdateInput): Promise<ChatbotConfig> {
+		const body = chatbotConfigUpdateInputSchema.parse(input);
+		return this.client.request({
+			method: "PATCH",
+			path: "chatbot/config",
+			body,
+			responseSchema: chatbotConfigSchema,
+		});
+	}
+
+	/**
+	 * Headless chat — host owns the UI. Each request is fully org-scoped: the
+	 * server runs the LLM with the org's saved system prompt + KB + model.
+	 *
+	 * The response includes `uiActions` (e.g. `show_form`) and `availability`
+	 * (front-desk presence + wait-time hint). Headless consumers should resolve
+	 * any `show_form` action via {@link getChatForm}, render the fields, and POST
+	 * back through {@link submitChatForm} (which carries the chat transcript).
+	 */
+	async chat(input: ChatbotChatInput): Promise<ChatbotChatResponse> {
+		const body = chatbotChatInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "chatbot/chat",
+			body,
+			responseSchema: chatbotChatResponseSchema,
+		});
+	}
+
+	/**
+	 * Upload a file a visitor attached in the chat. Presigns a direct-to-R2 PUT
+	 * (gated by the org's `chat.file_uploads` entitlement — check
+	 * `getConfig().fileUploadsEnabled` before offering it), uploads the bytes, and
+	 * returns a ref you can attach to the conversation. `sessionId` is any stable
+	 * per-chat id (drives the 5-files/hour cap + provenance). Throws on a refused
+	 * upload (entitlement, 7 MB cap, or rate limit).
+	 */
+	async uploadFile(args: {
+		sessionId: string;
+		file: File;
+		/** Captured visitor email — stored for provenance + checked against the
+		 *  platform block-list. Optional. */
+		uploaderEmail?: string | null;
+	}): Promise<{ url: string; name: string; type: string; size: number }> {
+		const contentType = args.file.type || "application/octet-stream";
+		const presigned = await this.client.request({
+			method: "POST",
+			path: "chatbot/upload-url",
+			body: {
+				sessionId: args.sessionId,
+				filename: args.file.name,
+				contentType,
+				sizeBytes: args.file.size,
+				uploaderEmail: args.uploaderEmail ?? null,
+			},
+			responseSchema: chatbotUploadUrlResponseSchema,
+		});
+		const put = await fetch(presigned.uploadUrl, {
+			method: "PUT",
+			headers: { "Content-Type": contentType },
+			body: args.file,
+		});
+		if (!put.ok) throw new Error(`Upload failed (${put.status}).`);
+		return {
+			url: presigned.publicUrl,
+			name: args.file.name,
+			type: contentType,
+			size: args.file.size,
+		};
+	}
+
+	/**
+	 * Live front-desk availability — tier flag, staff-online presence, and
+	 * a wait-time hint string. Safe to poll (every 20–30s) so the SDK
+	 * consumer can render or hide a "Talk to a person" CTA without sending
+	 * a chat turn.
+	 */
+	async getAvailability(): Promise<ChatbotAvailability> {
+		return this.client.request({
+			method: "GET",
+			path: "chatbot/availability",
+			responseSchema: chatbotAvailabilitySchema,
+		});
+	}
+
+	/**
+	 * Fetch a **Live** form definition to render inline on your own page.
+	 * A form is reachable here when it is Live (`isActive`) — independent of
+	 * `chatbotAccess`. Returns a 404-equivalent throw when the form is missing
+	 * or not Live. For a form the AI chatbot recommended via a `show_form`
+	 * action, use {@link getChatForm} instead (it carries the chat transcript on
+	 * submit).
+	 */
+	async getForm(slug: string): Promise<ChatbotFormDefinition> {
+		return this.client.request({
+			method: "GET",
+			path: `forms/${encodeURIComponent(slug)}`,
+			responseSchema: chatbotFormDefinitionSchema,
+		});
+	}
+
+	/**
+	 * Submit a **Live** form. Fans out to the same hiring/leads/inquiries CRM
+	 * mirrors, actions, scheduling, and staff notification as every other ingest
+	 * point. Gated on Live only — no `chatbotAccess` required.
+	 */
+	async submitForm(
+		slug: string,
+		input: ChatbotFormSubmitInput,
+	): Promise<ChatbotFormSubmitResponse> {
+		const body = chatbotFormSubmitInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `forms/${encodeURIComponent(slug)}`,
+			body,
+			responseSchema: chatbotFormSubmitResponseSchema,
+		});
+	}
+
+	/**
+	 * Fetch a form the AI chatbot recommended via a `show_form` UI action. This
+	 * additionally requires the form to be chatbot-accessible (`chatbotAccess`),
+	 * which a recommended form always is. Most embeds want {@link getForm}; reach
+	 * for this only inside the chat flow.
+	 */
+	async getChatForm(slug: string): Promise<ChatbotFormDefinition> {
+		return this.client.request({
+			method: "GET",
+			path: `chatbot/forms/${encodeURIComponent(slug)}`,
+			responseSchema: chatbotFormDefinitionSchema,
+		});
+	}
+
+	/**
+	 * Submit a chatbot-recommended form. Same CRM fan-out as {@link submitForm},
+	 * but on the chatbot path — pass `priorChat` so the resulting CRM inquiry can
+	 * include the chat transcript that led to the submission.
+	 */
+	async submitChatForm(
+		slug: string,
+		input: ChatbotFormSubmitInput,
+	): Promise<ChatbotFormSubmitResponse> {
+		const body = chatbotFormSubmitInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `chatbot/forms/${encodeURIComponent(slug)}`,
+			body,
+			responseSchema: chatbotFormSubmitResponseSchema,
+		});
+	}
+
+	// ── Front Desk (Batch JJ) ────────────────────────────────────────
+
+	/**
+	 * Create or resume the persisted `chatSessions` row for this
+	 * visitor. Idempotent on `(orgId, visitorToken)`. The returned
+	 * `sessionId` is what you pass to `postMessage`, `pollMessages`,
+	 * and `requestHuman`.
+	 *
+	 * Distinct from {@link createSession} — that mints an iframe-embed
+	 * token. This one exposes the underlying server session so the
+	 * consumer can render their own UI and still reach Front Desk.
+	 */
+	async createPersistedSession(
+		input: ChatbotPersistedSessionInput,
+	): Promise<ChatbotPersistedSessionResponse> {
+		const body = chatbotPersistedSessionInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "chatbot/persisted-session",
+			body,
+			responseSchema: chatbotPersistedSessionResponseSchema,
+		});
+	}
+
+	/**
+	 * Poll messages + session status. Pass `since` (ISO timestamp) on
+	 * subsequent polls to only fetch new rows. Recommended cadence:
+	 * 3–5s while the widget is open and focused.
+	 */
+	async pollMessages(input: {
+		sessionId: string;
+		visitorToken: string;
+		since?: string;
+	}): Promise<ChatbotMessagesResponse> {
+		return this.client.request({
+			path: "chatbot/messages",
+			query: {
+				sessionId: input.sessionId,
+				visitorToken: input.visitorToken,
+				since: input.since,
+			},
+			responseSchema: chatbotMessagesResponseSchema,
+		});
+	}
+
+	/**
+	 * Append a visitor message. Returns the updated message log so
+	 * the consumer can replace its local list with an authoritative
+	 * snapshot rather than tracking optimistic updates manually.
+	 */
+	async postMessage(
+		input: ChatbotAppendMessageInput,
+	): Promise<ChatbotMessagesResponse> {
+		const body = chatbotAppendMessageInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "chatbot/messages",
+			body,
+			responseSchema: chatbotMessagesResponseSchema,
+		});
+	}
+
+	/**
+	 * Visitor presses "Talk to a person." Plan-gated on
+	 * `chat.front_desk` — orgs on Launch get back
+	 * `{ available: false, reason: 'plan_required', requiredFeature, upgradeUrl }`.
+	 * Orgs on Growth+ get `{ available: true, status, placeInLine, ... }`.
+	 *
+	 * Branch on `result.available` to render an upgrade CTA vs the
+	 * "you're in line" UI.
+	 *
+	 * @example
+	 * ```ts
+	 * const result = await client.chatbot.requestHuman({ sessionId, visitorToken });
+	 * if (!result.available) return <UpgradeCard feature={result.requiredFeature} />;
+	 * return <Queue position={result.placeInLine} eta={result.estimateLabel} />;
+	 * ```
+	 */
+	async requestHuman(
+		input: ChatbotRequestHumanInput,
+	): Promise<ChatbotRequestHumanResponse> {
+		const body = chatbotRequestHumanInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "chatbot/request-human",
+			body,
+			responseSchema: chatbotRequestHumanResponseSchema,
+		});
+	}
+}
+
+/**
+ * Reads the active customer-portal context (organization + user) and exposes
+ * profile mutations + a list of *only this user's* other customer
+ * relationships.
+ *
+ * @remarks
+ * **Privacy:** When `organizationId` is set, every request is pinned to that
+ * org via the `X-BIAB-Customer-Portal-Org` header. The server-side
+ * `customerPortalProcedure` will reject any access to a different org, so a
+ * customer browsing a Dominoes-branded site can never accidentally see Pizza
+ * Hut data even if their account is linked to both. This is the recommended
+ * mode for embedding the SDK on a tenant's site or app.
+ */
+/**
+ * Decode a base64 string to bytes. Uses `atob` (available in browsers and
+ * Node >= 16), so it needs no Buffer polyfill in browser bundles.
+ */
+function decodeBase64ToBytes(base64: string): Uint8Array {
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) {
+		bytes[i] = binary.charCodeAt(i);
+	}
+	return bytes;
+}
+
+export class BiabDevCustomerPortalClient {
+	constructor(
+		private readonly client: BiabDevClient,
+		private readonly organizationId: string | null,
+		/**
+		 * Optional tenantAuth session token. When set, requests include
+		 * an `X-BIAB-Session-Token` header and the BIAB customer-portal
+		 * routes resolve the calling user via the session payload
+		 * instead of the API key's user binding.
+		 *
+		 * This is the right path for consumer storefronts that don't
+		 * mint per-customer API keys: sign customers in via
+		 * `client.auth.signIn()`, store the resulting session token
+		 * (the SDK's `createAuthHandler` does this in an httpOnly
+		 * cookie automatically), then pass that token to
+		 * `client.customerPortal(orgId).withSession(token)` for every
+		 * customer-scoped call.
+		 */
+		private readonly sessionToken: string | null = null,
+	) {}
+
+	/**
+	 * Return a customer-portal client that authenticates the calling
+	 * user via the tenantAuth session token instead of (or in
+	 * addition to) the API key's user binding. Chainable.
+	 *
+	 * @example
+	 * ```ts
+	 * const session = await getTenantSessionFromCookie({ cookieValue });
+	 * const work = await client
+	 *   .customerPortal(orgId)
+	 *   .withSession(session.sessionToken)
+	 *   .getWork();
+	 * ```
+	 */
+	withSession(sessionToken: string): BiabDevCustomerPortalClient {
+		return new BiabDevCustomerPortalClient(
+			this.client,
+			this.organizationId,
+			sessionToken,
+		);
+	}
+
+	private headers(): HeadersInit {
+		const out: Record<string, string> = {};
+		if (this.organizationId) {
+			out["X-BIAB-Customer-Portal-Org"] = this.organizationId;
+		}
+		if (this.sessionToken) {
+			out["X-BIAB-Session-Token"] = this.sessionToken;
+		}
+		return out;
+	}
+
+	async context(): Promise<CustomerPortalContextResponse> {
+		return this.client.request({
+			path: "customer-portal/context",
+			responseSchema: customerPortalContextResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	async getProfile(): Promise<CustomerPortalProfile> {
+		return this.client.request({
+			path: "customer-portal/profile",
+			responseSchema: customerPortalProfileSchema,
+			headers: this.headers(),
+		});
+	}
+
+	async updateProfile(
+		input: CustomerPortalUpdateProfileInput,
+	): Promise<CustomerPortalUpdateProfileResponse> {
+		const body = customerPortalUpdateProfileInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "customer-portal/profile",
+			body,
+			responseSchema: customerPortalUpdateProfileResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	async myOtherCustomerOrgs(): Promise<CustomerPortalOtherOrgsResponse> {
+		return this.client.request({
+			path: "customer-portal/other-orgs",
+			responseSchema: customerPortalOtherOrgsResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Read the signed-in customer's notification preferences (per category,
+	 * per channel) for the bound org. The response also includes the full
+	 * category + channel catalog so SDK consumers can render the UI
+	 * without hardcoding either — both grow over time on the server side.
+	 *
+	 * @example
+	 * ```ts
+	 * const { preferences, categories, channels } =
+	 *   await client.customerPortal().getNotificationPreferences();
+	 *
+	 * categories.map((c) => (
+	 *   <Row category={c} state={preferences[c.id]} />
+	 * ));
+	 * ```
+	 */
+	async getNotificationPreferences(): Promise<NotificationPreferencesResponse> {
+		return this.client.request({
+			path: "customer-portal/notification-preferences",
+			responseSchema: notificationPreferencesResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Update notification preferences. Sparse: only send the toggles you
+	 * want to flip — omitted keys keep their persisted (or default) value.
+	 * Compliance-required channels (e.g. transactional email) silently
+	 * stay true regardless of what's sent.
+	 *
+	 * @example
+	 * ```ts
+	 * await client.customerPortal().updateNotificationPreferences({
+	 *   preferences: { marketing: { email: false, sms: false } },
+	 * });
+	 * ```
+	 */
+	async updateNotificationPreferences(
+		input: NotificationPreferencesUpdateInput,
+	): Promise<NotificationPreferencesResponse> {
+		const body = notificationPreferencesUpdateInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "customer-portal/notification-preferences",
+			body,
+			responseSchema: notificationPreferencesResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Read the signed-in customer's "what's on my plate" bundle: open
+	 * jobs, pending quotes, unpaid invoices, contracts awaiting signature,
+	 * and a recent payment history, plus a roll-up summary for the
+	 * consumer header.
+	 *
+	 * URLs are host-less paths — resolve them against the consumer's own
+	 * storefront origin to build clickable links.
+	 *
+	 * @example
+	 * ```ts
+	 * const work = await client.customerPortal().getWork();
+	 * const { openJobCount, unpaidBalance } = work.summary;
+	 * work.invoices.filter((i) => i.balanceDue > 0).map(...)
+	 * ```
+	 */
+	async getWork(): Promise<CustomerWorkBundle> {
+		return this.client.request({
+			path: "customer-portal/work",
+			responseSchema: customerWorkBundleSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Read a single job the signed-in customer owns. */
+	async getJob(jobId: string): Promise<CustomerJobDetail> {
+		return this.client.request({
+			path: `customer-portal/jobs/${encodeURIComponent(jobId)}`,
+			responseSchema: customerJobDetailSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Read a single quote the signed-in customer owns. */
+	async getQuote(quoteId: string): Promise<CustomerQuoteDetail> {
+		return this.client.request({
+			path: `customer-portal/quotes/${encodeURIComponent(quoteId)}`,
+			responseSchema: customerQuoteDetailSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Naming alias for {@link getQuote} — read a single quote the customer owns. */
+	async viewQuote(quoteId: string): Promise<CustomerQuoteDetail> {
+		return this.getQuote(quoteId);
+	}
+
+	/**
+	 * Accept a quote as the signed-in customer. Idempotent — re-accepting
+	 * an already-accepted quote resolves the existing state without
+	 * additional side effects.
+	 */
+	async acceptQuote(quoteId: string): Promise<CustomerQuoteActionResponse> {
+		return this.client.request({
+			method: "POST",
+			path: `customer-portal/quotes/${encodeURIComponent(quoteId)}/accept`,
+			responseSchema: customerQuoteActionResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Reject a quote as the signed-in customer. Idempotent. */
+	async rejectQuote(quoteId: string): Promise<CustomerQuoteActionResponse> {
+		return this.client.request({
+			method: "POST",
+			path: `customer-portal/quotes/${encodeURIComponent(quoteId)}/reject`,
+			responseSchema: customerQuoteActionResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Read a single invoice the signed-in customer owns. */
+	async getInvoice(invoiceId: string): Promise<CustomerInvoiceDetail> {
+		return this.client.request({
+			path: `customer-portal/invoices/${encodeURIComponent(invoiceId)}`,
+			responseSchema: customerInvoiceDetailSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Start payment for an invoice the customer owns. Returns a Stripe-hosted
+	 * Checkout URL to redirect to — card entry happens entirely on Stripe, so
+	 * your app never touches card data (stays out of PCI scope).
+	 *
+	 * Pass your own `successUrl` / `cancelUrl` to return into your storefront,
+	 * or omit them to land back on the org's branded hosted invoice page.
+	 *
+	 * @example
+	 * ```ts
+	 * const { checkoutUrl } = await client
+	 *   .customerPortal()
+	 *   .payInvoice(invoiceId, { successUrl: "https://shop.example.com/paid" });
+	 * window.location.href = checkoutUrl;
+	 * ```
+	 */
+	async payInvoice(
+		invoiceId: string,
+		opts?: CustomerInvoicePayInput,
+	): Promise<CustomerInvoicePayResponse> {
+		const body = customerInvoicePayInputSchema.parse(opts ?? {});
+		return this.client.request({
+			method: "POST",
+			path: `customer-portal/invoices/${encodeURIComponent(invoiceId)}/pay`,
+			body,
+			responseSchema: customerInvoicePayResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Download the customer's invoice as a PDF. Returns the file metadata plus
+	 * the decoded `bytes` (a `Uint8Array`) — the auth headers ride along on the
+	 * SDK request, so this works for a signed-in customer without exposing a
+	 * public URL. Once paid, the PDF carries a PAID marker + payment history.
+	 *
+	 * @example Browser download
+	 * ```ts
+	 * const file = await client.customerPortal(orgId).withSession(token)
+	 *   .downloadInvoicePdf(invoiceId);
+	 * const url = URL.createObjectURL(
+	 *   new Blob([file.bytes], { type: file.contentType }),
+	 * );
+	 * const a = document.createElement("a");
+	 * a.href = url;
+	 * a.download = file.filename;
+	 * a.click();
+	 * URL.revokeObjectURL(url);
+	 * ```
+	 */
+	async downloadInvoicePdf(
+		invoiceId: string,
+	): Promise<CustomerInvoicePdf & { bytes: Uint8Array }> {
+		const res = await this.client.request({
+			path: `customer-portal/invoices/${encodeURIComponent(invoiceId)}/pdf`,
+			responseSchema: customerInvoicePdfSchema,
+			headers: this.headers(),
+		});
+		return { ...res, bytes: decodeBase64ToBytes(res.base64) };
+	}
+
+	/** Read a single contract the signed-in customer owns. */
+	async getContract(contractId: string): Promise<CustomerContractDetail> {
+		return this.client.request({
+			path: `customer-portal/contracts/${encodeURIComponent(contractId)}`,
+			responseSchema: customerContractDetailSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Begin signing a contract the customer owns. Returns a ready, absolute
+	 * signing URL on the org's branded hostname — redirect the customer there
+	 * to BIAB's hosted e-sign page, which captures the signature and generates
+	 * the executed PDF. No signature payload is collected client-side, so the
+	 * legal record stays consistent across consumers.
+	 *
+	 * Rejects with `contract_already_signed` (409) or `contract_not_signable`
+	 * (409) when the contract isn't in a signable state.
+	 *
+	 * @example
+	 * ```ts
+	 * const { signingUrl } = await client
+	 *   .customerPortal()
+	 *   .signContract(contractId);
+	 * window.location.href = signingUrl;
+	 * ```
+	 */
+	async signContract(
+		contractId: string,
+	): Promise<CustomerContractSignResponse> {
+		return this.client.request({
+			method: "POST",
+			path: `customer-portal/contracts/${encodeURIComponent(contractId)}/sign`,
+			responseSchema: customerContractSignResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** List reviews the signed-in customer has submitted in this org. */
+	async listMyReviews(): Promise<CustomerReviewListResponse> {
+		return this.client.request({
+			path: "customer-portal/reviews",
+			responseSchema: customerReviewListResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Referral roll-up for the signed-in customer (as an affiliate), summed
+	 * across every program they're enrolled in. `enrolled: false` with zeroed
+	 * counters when the customer holds no affiliate record. Real data appears
+	 * once the org's referral attribution + payout pipeline records activity.
+	 *
+	 * @example
+	 * ```ts
+	 * const stats = await client.customerPortal().myReferralStats();
+	 * if (stats.enrolled) showEarnings(stats.earningsCents);
+	 * ```
+	 */
+	async myReferralStats(): Promise<CustomerReferralStats> {
+		return this.client.request({
+			path: "customer-portal/referrals/stats",
+			responseSchema: customerReferralStatsSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * The customer's referral conversion feed (most recent first). Empty until
+	 * the attribution pipeline records conversions. `limit` 1–200 (default 50).
+	 */
+	async myReferralHistory(opts?: {
+		limit?: number;
+	}): Promise<CustomerReferralHistoryResponse> {
+		const limit = opts?.limit;
+		const qs =
+			typeof limit === "number"
+				? `?limit=${encodeURIComponent(String(limit))}`
+				: "";
+		return this.client.request({
+			path: `customer-portal/referrals/history${qs}`,
+			responseSchema: customerReferralHistoryResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** The customer's referral payout history + upcoming rows (newest first). */
+	async myReferralPayouts(): Promise<CustomerReferralPayoutsResponse> {
+		return this.client.request({
+			path: "customer-portal/referrals/payouts",
+			responseSchema: customerReferralPayoutsResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * The signed-in customer's orders (newest first), each with a shipment
+	 * roll-up (`overallStatus`, `anyInTransit`, `latestEstimatedDelivery`) for
+	 * an orders/shipping dashboard list. `limit` 1–100 (default 30). Requires
+	 * the org's `ecommerce.shipping` entitlement.
+	 *
+	 * @example
+	 * ```ts
+	 * const { items } = await client.customerPortal().listOrders();
+	 * items.filter((o) => o.anyInTransit).map(renderTracker);
+	 * ```
+	 */
+	async listOrders(opts?: {
+		limit?: number;
+	}): Promise<CustomerOrderListResponse> {
+		const limit = opts?.limit;
+		const qs =
+			typeof limit === "number"
+				? `?limit=${encodeURIComponent(String(limit))}`
+				: "";
+		return this.client.request({
+			path: `customer-portal/orders${qs}`,
+			responseSchema: customerOrderListResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * The customer's full payment history with this org — invoice payments,
+	 * store-order charges, and refunds (negative amounts), newest first.
+	 * Powers a "Payments" tab on the customer dashboard.
+	 *
+	 * ```ts
+	 * const { items } = await client.customerPortal().listPayments();
+	 * items.map((p) => `${p.occurredAt} ${p.kind} $${p.amount}`);
+	 * ```
+	 */
+	async listPayments(opts?: {
+		limit?: number;
+	}): Promise<import("./contracts").CustomerPaymentHistoryResponse> {
+		const limit = opts?.limit;
+		const qs =
+			typeof limit === "number"
+				? `?limit=${encodeURIComponent(String(limit))}`
+				: "";
+		return this.client.request({
+			path: `customer-portal/payments${qs}`,
+			responseSchema: customerPaymentHistoryResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * One order the customer owns: line items + shipments, each shipment with
+	 * its carrier, tracking link, status, and `statusHistory` timeline (read
+	 * from stored data — webhook-fresh).
+	 */
+	async getOrder(orderId: string): Promise<CustomerOrderDetail> {
+		return this.client.request({
+			path: `customer-portal/orders/${encodeURIComponent(orderId)}`,
+			responseSchema: customerOrderDetailSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Open a return / refund request on an order the customer owns. Creates a
+	 * `requested` record and notifies the org's review queue — the org's
+	 * approval (not this call) triggers the actual Stripe refund. Omit `items`
+	 * for a whole-order request. The request then shows up under
+	 * `getOrder(orderId).returnRequests`.
+	 *
+	 * @example
+	 * ```ts
+	 * await portal.submitReturnRequest(orderId, {
+	 *   reason: "damaged",
+	 *   customerNote: "Arrived cracked.",
+	 *   items: [{ orderItemId, quantity: 1 }],
+	 * });
+	 * ```
+	 */
+	async submitReturnRequest(
+		orderId: string,
+		input?: CustomerReturnRequestInput,
+	): Promise<CustomerReturnRequestCreated> {
+		const body = customerReturnRequestInputSchema.parse(input ?? {});
+		return this.client.request({
+			method: "POST",
+			path: `customer-portal/orders/${encodeURIComponent(orderId)}/return-request`,
+			body,
+			responseSchema: customerReturnRequestCreatedSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * List the digital downloads the customer is entitled to for a paid order
+	 * (P10d). Each item is a ready-to-use URL — a short-lived presigned link for
+	 * BIAB-hosted files (`expiresInSeconds` set) or the org's external link.
+	 * Returns an empty list until the order's payment settles.
+	 *
+	 * @example
+	 * ```ts
+	 * const { items } = await portal.getDownloads(orderId);
+	 * for (const d of items) console.log(d.productName, d.url);
+	 * ```
+	 */
+	async getDownloads(orderId: string): Promise<CustomerDownloadsResponse> {
+		return this.client.request({
+			path: `customer-portal/orders/${encodeURIComponent(orderId)}/downloads`,
+			responseSchema: customerDownloadsResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Track a single shipment the customer owns (resolved through their own
+	 * order). Returns the stored shipment plus a best-effort live carrier status
+	 * (`liveStatus`) when it's still in transit.
+	 */
+	async trackShipment(shipmentId: string): Promise<CustomerShipmentTracking> {
+		return this.client.request({
+			path: `customer-portal/shipments/${encodeURIComponent(shipmentId)}/track`,
+			responseSchema: customerShipmentTrackingSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Submit a review tied to the signed-in customer's email. Land
+	 * with `status: pending` so org staff can moderate before the
+	 * review surfaces on the public bundle. `jobId` is optional and
+	 * validated server-side against the customer's own jobs — a
+	 * stranger's id is rejected with a 403.
+	 */
+	async submitReview(
+		input: CustomerReviewSubmitInput,
+	): Promise<CustomerReviewSubmitResponse> {
+		const body = customerReviewSubmitInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "customer-portal/reviews",
+			body,
+			responseSchema: customerReviewSubmitResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** List the comment thread on a job the customer owns. */
+	async listJobComments(
+		jobId: string,
+	): Promise<CustomerJobCommentsListResponse> {
+		return this.client.request({
+			path: `customer-portal/jobs/${encodeURIComponent(jobId)}/comments`,
+			responseSchema: customerJobCommentsListResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/** Post a customer comment on one of the customer's own jobs. */
+	async postJobComment(
+		jobId: string,
+		input: CustomerJobCommentPostInput,
+	): Promise<CustomerJobComment> {
+		const body = customerJobCommentPostInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: `customer-portal/jobs/${encodeURIComponent(jobId)}/comments`,
+			body,
+			responseSchema: customerJobCommentSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Open (or reuse) a front-desk chat session bound to the signed-in
+	 * customer and post their first message. Staff see the thread in
+	 * the chatbot inbox with `linkedContactId` set so they know who's
+	 * reaching out. Returns the `sessionId` + `visitorToken` so the
+	 * consumer can poll for staff replies or render the chatbot widget
+	 * over the same session via the existing chatbot embed flow.
+	 */
+	async contactCompany(
+		input: CustomerContactCompanyInput,
+	): Promise<CustomerContactCompanyResponse> {
+		const body = customerContactCompanyInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "customer-portal/contact-company",
+			body,
+			responseSchema: customerContactCompanyResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Staff-on-the-way view for a job the customer owns. First-cut:
+	 * returns assigned-tech display names + dispatch status, the last
+	 * known GPS ping per tech (when available), and the most recent
+	 * ETA snapshot from the dispatch_offers cascade.
+	 *
+	 * `liveEtaAvailable: false` today — flips to true once the
+	 * dispatch travel-time recompute layer ships, at which point the
+	 * `eta` field switches sources without breaking this shape.
+	 */
+	async getJobEta(jobId: string): Promise<CustomerJobEtaResponse> {
+		return this.client.request({
+			path: `customer-portal/jobs/${encodeURIComponent(jobId)}/eta`,
+			responseSchema: customerJobEtaResponseSchema,
+			headers: this.headers(),
+		});
+	}
+
+	/**
+	 * Unified job activity feed: structured events (status changes,
+	 * dispatch lifecycle, media uploads, quote/contract/invoice
+	 * transitions) interleaved with chat messages linked to this
+	 * customer's contact. One linear timeline so the customer can
+	 * see "what happened, then what was said, then what happened
+	 * next" without piecing together separate views.
+	 *
+	 * Each entry is `{ kind: 'event' | 'chat', id, at, ... }`. The
+	 * discriminated union means TypeScript narrows correctly when
+	 * you branch on `kind`.
+	 */
+	async getJobActivity(jobId: string): Promise<CustomerJobActivityResponse> {
+		return this.client.request({
+			path: `customer-portal/jobs/${encodeURIComponent(jobId)}/activity`,
+			responseSchema: customerJobActivityResponseSchema,
+			headers: this.headers(),
+		});
+	}
+}
+
+/**
+ * Creates a {@link BiabDevClient} for the given host `baseUrl` and package API key.
+ *
+ * @remarks
+ * **Alpha:** This package is still in alpha release. APIs may change; it is **not** intended
+ * for production use yet. Prefer non-production environments until a stable major is published.
+ */
+export function createBiabDevClient(options: BiabDevClientOptions) {
+	return new BiabDevClient(options);
+}
+
+/**
+ * Per-tenant auth: hosted sign-in/sign-up scoped to the org bound to
+ * the API key. Used by the SDK's `createAuthHandler` (server) and
+ * `<SignIn />` / `<SignUp />` / `<SignOut />` components (client).
+ */
+export class BiabDevAuthClient {
+	constructor(private readonly client: BiabDevClient) {}
+
+	async start(input: TenantAuthStartInput): Promise<TenantAuthStartResponse> {
+		const body = tenantAuthStartInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "auth/start",
+			body,
+			responseSchema: tenantAuthStartResponseSchema,
+		});
+	}
+
+	/**
+	 * Ergonomic shortcut for `start({ intent: "sign-in", ... })`. Returns
+	 * the platform-hosted redirect URL the caller should navigate to;
+	 * stateless on its own — pair with `exchange()` on your callback
+	 * route to mint the session.
+	 */
+	async signIn(input: {
+		redirectUri: string;
+		returnTo?: string;
+		loginHint?: string;
+	}): Promise<TenantAuthStartResponse> {
+		return this.start({ intent: "sign-in", ...input });
+	}
+
+	/**
+	 * Ergonomic shortcut for `start({ intent: "sign-up", ... })`. Same
+	 * shape as `signIn`; only the platform-hosted page that opens differs.
+	 */
+	async signUp(input: {
+		redirectUri: string;
+		returnTo?: string;
+		loginHint?: string;
+	}): Promise<TenantAuthStartResponse> {
+		return this.start({ intent: "sign-up", ...input });
+	}
+
+	/**
+	 * Alias for `requestPasswordReset`. Always resolves `{ ok: true }`
+	 * (the server doesn't reveal whether the email matched an account).
+	 */
+	async forgotPassword(
+		input: TenantAuthPasswordResetInput,
+	): Promise<TenantAuthPasswordResetResponse> {
+		return this.requestPasswordReset(input);
+	}
+
+	async exchange(
+		input: TenantAuthExchangeInput,
+	): Promise<TenantAuthExchangeResponse> {
+		const body = tenantAuthExchangeInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "auth/exchange",
+			body,
+			responseSchema: tenantAuthExchangeResponseSchema,
+		});
+	}
+
+	async me(input: { sessionToken: string }): Promise<TenantAuthMeResponse> {
+		return this.client.request({
+			method: "GET",
+			path: "auth/me",
+			headers: { "x-biab-session": input.sessionToken },
+			responseSchema: tenantAuthMeResponseSchema,
+		});
+	}
+
+	async signOut(): Promise<TenantAuthSignOutResponse> {
+		return this.client.request({
+			method: "POST",
+			path: "auth/sign-out",
+			responseSchema: tenantAuthSignOutResponseSchema,
+		});
+	}
+
+	/**
+	 * Trigger a password-reset email for `input.email`. Always resolves
+	 * with `{ ok: true }` — the server intentionally does not reveal
+	 * whether a matching account exists. The email (when sent) contains
+	 * a platform-hosted reset URL; the consumer never needs to build a
+	 * "set new password" page.
+	 *
+	 * Server-only by design (the API key may not be exposed to the
+	 * browser). The matching browser-side `requestPasswordReset()` in
+	 * `@businessdash/sdk/react` proxies through the auth-handler.
+	 */
+	async requestPasswordReset(
+		input: TenantAuthPasswordResetInput,
+	): Promise<TenantAuthPasswordResetResponse> {
+		const body = tenantAuthPasswordResetInputSchema.parse(input);
+		return this.client.request({
+			method: "POST",
+			path: "auth/password-reset",
+			body,
+			responseSchema: tenantAuthPasswordResetResponseSchema,
+		});
+	}
+}