@businessdash/sdk 0.9.60

package/src/contracts.ts

@@ -0,0 +1,3390 @@
+import { z } from "zod";
+
+/**
+ * A string field whose values the SERVER owns and may extend.
+ *
+ * `T` gives callers the known members — autocomplete, and a `switch` that
+ * reads as a real enum — while `string & {}` keeps any other string
+ * assignable. (The `& {}` is load-bearing: a bare `T | string` collapses to
+ * `string` and the literals vanish from tooling.)
+ */
+export type OpenEnum<T extends string> = T | (string & {});
+
+/**
+ * Declare a server-owned enum on a RESPONSE field.
+ *
+ * ## Why this is not `z.enum([...])`
+ *
+ * Response schemas here are parsed at runtime — `client.ts` ends every request
+ * with `options.responseSchema.parse(body)`, and `.parse` **throws**. So a
+ * `z.enum` on a response is a promise that the set never grows. It does grow:
+ * these mirror pg enums, and a migration can add a member and ship long before
+ * a consumer upgrades their pinned `@businessdash/sdk`. The old value keeps
+ * working; the new one takes down every call that returns a row carrying it.
+ *
+ * So runtime stays permissive (`z.string()` — a string is still a string) and
+ * the precision goes into the TYPE, where being wrong costs a stale hint
+ * instead of an outage. The cast is sound rather than a convenience: every
+ * `string` genuinely is an `OpenEnum<T>`.
+ *
+ * The known members aren't lost — they ride along in `.describe()`, so they
+ * reach `openapi.json` and the clients generated from it.
+ *
+ * Use `z.enum` freely on REQUEST fields: rejecting a bad value the caller
+ * just typed is the entire point, and the blast radius is one call.
+ */
+export function openEnum<const T extends readonly [string, ...string[]]>(
+	...values: T
+): z.ZodType<OpenEnum<T[number]>> {
+	return z
+		.string()
+		.describe(
+			`Known values: ${values.join(" | ")}. The server may add more — treat unrecognised values as forward-compatible rather than invalid.`,
+		) as z.ZodType<OpenEnum<T[number]>>;
+}
+
+export const siteIdSchema = z.string().uuid();
+export const collectionIdSchema = z.string().uuid();
+export const rowIdSchema = z.string().uuid();
+export const fieldIdSchema = z.string().uuid();
+export const apiKeyIdSchema = z.string().uuid();
+export const timestampSchema = z.string().min(1);
+
+export const collectionSlugSchema = z
+	.string()
+	.min(1)
+	.max(80)
+	.regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/);
+
+export const collectionFieldNameSchema = z
+	.string()
+	.min(1)
+	.max(80)
+	.regex(/^[a-zA-Z][a-zA-Z0-9_]*$/);
+
+export const collectionFieldTypeValues = [
+	"string",
+	"number",
+	"boolean",
+	"json",
+	"date",
+	"richtext",
+] as const;
+
+export const collectionFieldTypeSchema = z.enum(collectionFieldTypeValues);
+
+export const jsonValueSchema: z.ZodType<
+	string | number | boolean | null | { [key: string]: unknown } | unknown[]
+> = z.lazy(() =>
+	z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null(),
+		z.record(z.unknown()),
+		z.array(z.unknown()),
+	]),
+);
+
+export const collectionFieldInputSchema = z.object({
+	name: collectionFieldNameSchema,
+	label: z.string().max(120).optional(),
+	type: collectionFieldTypeSchema,
+	required: z.boolean().optional(),
+	searchable: z.boolean().optional(),
+	queryable: z.boolean().optional(),
+	validation: z.record(z.unknown()).optional(),
+	displayConfig: z.record(z.unknown()).optional(),
+	position: z.number().int().min(0).optional(),
+});
+
+export const collectionFieldSchema = z.object({
+	id: fieldIdSchema,
+	tableId: collectionIdSchema,
+	siteId: siteIdSchema,
+	name: collectionFieldNameSchema,
+	label: z.string().max(120).nullable().optional(),
+	type: collectionFieldTypeSchema,
+	required: z.boolean(),
+	searchable: z.boolean(),
+	queryable: z.boolean(),
+	validation: z.record(z.unknown()).nullable().optional(),
+	displayConfig: z.record(z.unknown()).nullable().optional(),
+	position: z.number().int(),
+	createdAt: timestampSchema,
+	updatedAt: timestampSchema,
+});
+
+export const collectionSchema = z.object({
+	id: collectionIdSchema,
+	siteId: siteIdSchema,
+	name: z.string().min(1).max(120),
+	slug: collectionSlugSchema,
+	description: z.string().max(500).nullable().optional(),
+	createdByUserId: z.string().uuid().nullable().optional(),
+	createdAt: timestampSchema,
+	updatedAt: timestampSchema,
+});
+
+export const createCollectionInputSchema = z.object({
+	name: z.string().min(1).max(120),
+	slug: collectionSlugSchema.optional(),
+	description: z.string().max(500).optional(),
+	fields: z.array(collectionFieldInputSchema).max(64).optional(),
+});
+
+export const createCollectionResponseSchema = z.object({
+	collection: collectionSchema,
+	fields: z.array(collectionFieldSchema),
+});
+
+export const listCollectionsResponseSchema = z.object({
+	collections: z.array(collectionSchema),
+});
+
+export const getCollectionResponseSchema = z.object({
+	collection: collectionSchema,
+	fields: z.array(collectionFieldSchema),
+});
+
+export const rowDataSchema = z.record(z.unknown());
+
+export const collectionRowSchema = z.object({
+	id: rowIdSchema,
+	tableId: collectionIdSchema,
+	siteId: siteIdSchema,
+	data: rowDataSchema,
+	createdByUserId: z.string().uuid().nullable().optional(),
+	updatedByUserId: z.string().uuid().nullable().optional(),
+	createdAt: timestampSchema,
+	updatedAt: timestampSchema,
+});
+
+export const listRowsInputSchema = z.object({
+	limit: z.number().int().min(1).max(100).optional(),
+});
+
+export const listRowsResponseSchema = z.object({
+	rows: z.array(collectionRowSchema),
+});
+
+export const upsertRowInputSchema = z.object({
+	rowId: rowIdSchema.optional(),
+	data: rowDataSchema,
+});
+
+export const upsertRowResponseSchema = z.object({
+	row: collectionRowSchema,
+});
+
+export const queryOperatorValues = ["equals", "contains"] as const;
+export const queryOperatorSchema = z.enum(queryOperatorValues);
+
+export const queryFilterSchema = z.object({
+	fieldName: collectionFieldNameSchema,
+	value: z.union([z.string().min(1), z.number(), z.boolean()]),
+	operator: queryOperatorSchema.optional(),
+});
+
+export const queryRowsInputSchema = z.object({
+	filters: z.array(queryFilterSchema).min(1).max(10),
+	limit: z.number().int().min(1).max(100).optional(),
+});
+
+export const queryRowsResponseSchema = z.object({
+	rows: z.array(collectionRowSchema),
+});
+
+export const siteAssetInputSchema = z.object({
+	filename: z.string().min(1),
+	url: z.string().url(),
+	mimeType: z.string().optional(),
+	sizeBytes: z.number().int().nonnegative().optional(),
+	altText: z.string().optional(),
+	folder: z.string().optional(),
+});
+
+export const siteAssetSchema = z.object({
+	id: z.number().int(),
+	siteId: siteIdSchema,
+	filename: z.string(),
+	url: z.string().url(),
+	mimeType: z.string().nullable().optional(),
+	sizeBytes: z.number().int().nullable().optional(),
+	altText: z.string().nullable().optional(),
+	folder: z.string().nullable().optional(),
+	createdAt: timestampSchema,
+});
+
+export const uploadSiteAssetResponseSchema = z.object({
+	asset: siteAssetSchema,
+});
+
+export const followerSchema = z.object({
+	id: z.string().uuid(),
+	email: z.string().email(),
+	name: z.string().nullable().optional(),
+	source: z.string().nullable().optional(),
+	isActive: z.boolean(),
+	joinedAt: timestampSchema,
+	unsubscribedAt: timestampSchema.nullable().optional(),
+});
+
+export const followerJoinInputSchema = z.object({
+	email: z.string().email(),
+	name: z.string().min(1).max(200).optional(),
+	source: z.string().min(1).max(80).optional(),
+});
+
+export const followerJoinResponseSchema = z.object({
+	follower: followerSchema,
+	created: z.boolean(),
+});
+
+export const followerMeInputSchema = z.object({
+	email: z.string().email(),
+});
+
+export const followerMeResponseSchema = z.object({
+	follower: followerSchema.nullable(),
+});
+
+export const followerEditInputSchema = z.object({
+	email: z.string().email(),
+	patch: z.object({
+		name: z.string().min(1).max(200).optional(),
+		source: z.string().min(1).max(80).optional(),
+	}),
+});
+
+export const followerEditResponseSchema = z.object({
+	follower: followerSchema,
+});
+
+export const followerLeaveInputSchema = z.object({
+	email: z.string().email(),
+});
+
+export const followerLeaveResponseSchema = z.object({
+	follower: followerSchema.nullable(),
+});
+
+export const dashboardSessionResponseSchema = z.object({
+	url: z.string().url(),
+	token: z.string().min(1),
+	expiresAt: timestampSchema,
+});
+
+// ── Storefront / Cart / Checkout / Blog embed sessions ─────────────────────
+
+const baseEmbedSessionResponse = z.object({
+	url: z.string().url(),
+	token: z.string().min(1),
+	expiresAt: timestampSchema,
+	orgSlug: z.string().min(1),
+});
+
+export const storefrontSessionInputSchema = z
+	.object({
+		productId: z.string().uuid().optional(),
+	})
+	.optional();
+export type StorefrontSessionInput = z.infer<
+	typeof storefrontSessionInputSchema
+>;
+
+export const storefrontSessionResponseSchema = baseEmbedSessionResponse;
+export type StorefrontSessionResponse = z.infer<
+	typeof storefrontSessionResponseSchema
+>;
+
+export const cartSessionResponseSchema = baseEmbedSessionResponse;
+export type CartSessionResponse = z.infer<typeof cartSessionResponseSchema>;
+
+export const checkoutLineSchema = z.object({
+	productId: z.string().uuid(),
+	variantId: z.string().uuid(),
+	combinationKey: z.string().optional(),
+	quantity: z.number().int().positive(),
+});
+export type CheckoutLine = z.infer<typeof checkoutLineSchema>;
+
+export const checkoutSessionInputSchema = z.object({
+	lines: z.array(checkoutLineSchema).min(1),
+	customerEmail: z.string().email().optional(),
+	successUrl: z.string().url().optional(),
+	cancelUrl: z.string().url().optional(),
+});
+export type CheckoutSessionInput = z.infer<typeof checkoutSessionInputSchema>;
+
+export const checkoutSessionResponseSchema = z.object({
+	url: z.string().url(),
+	stripeUrl: z.string().url(),
+	sessionId: z.string().min(1),
+	totalAmountCents: z.number().int(),
+	currency: z.string().min(1),
+	token: z.string().min(1),
+	expiresAt: timestampSchema,
+});
+export type CheckoutSessionResponse = z.infer<
+	typeof checkoutSessionResponseSchema
+>;
+
+// ── Programmatic checkout-from-cart (Batch II, 0.9.0) ────────────────
+
+export const checkoutStartInputSchema = z
+	.object({
+		customerEmail: z.string().email().optional(),
+		successUrl: z.string().url().optional(),
+		cancelUrl: z.string().url().optional(),
+	})
+	.optional();
+export type CheckoutStartInput = z.infer<typeof checkoutStartInputSchema>;
+
+export const checkoutStartResponseSchema = z.object({
+	sessionId: z.string().min(1),
+	stripeUrl: z.string().url(),
+	totalAmountCents: z.number().int(),
+	currency: z.string().min(1),
+});
+export type CheckoutStartResponse = z.infer<typeof checkoutStartResponseSchema>;
+
+export const checkoutStatusResponseSchema = z.object({
+	sessionId: z.string().min(1),
+	paymentStatus: z.enum(["no_payment_required", "paid", "unpaid"]),
+	amountTotalCents: z.number().int().nullable(),
+	currency: z.string().nullable(),
+	customerEmail: z.string().nullable(),
+	customerName: z.string().nullable(),
+});
+export type CheckoutStatusResponse = z.infer<
+	typeof checkoutStatusResponseSchema
+>;
+
+export const blogSessionInputSchema = z
+	.object({
+		postSlug: z.string().min(1).max(200).optional(),
+	})
+	.optional();
+export type BlogSessionInput = z.infer<typeof blogSessionInputSchema>;
+
+export const blogSessionResponseSchema = baseEmbedSessionResponse;
+export type BlogSessionResponse = z.infer<typeof blogSessionResponseSchema>;
+
+// ── Chatbot ────────────────────────────────────────────────────────────────
+
+export const chatbotSessionResponseSchema = baseEmbedSessionResponse;
+export type ChatbotSessionResponse = z.infer<
+	typeof chatbotSessionResponseSchema
+>;
+
+/** How proactively the bot should suggest "Talk to a person" — server-driven. */
+export const chatbotHandoffThresholdSchema = z.enum([
+	"never",
+	"low",
+	"medium",
+	"high",
+	"always",
+]);
+export type ChatbotHandoffThreshold = z.infer<
+	typeof chatbotHandoffThresholdSchema
+>;
+
+export const chatbotConfigSchema = z.object({
+	systemPrompt: z.string(),
+	knowledgeBase: z.string(),
+	model: z.string().min(1),
+	temperature: z.number().min(0).max(2),
+	lastUpdated: timestampSchema.nullable(),
+	usingDefaults: z.boolean(),
+	/**
+	 * Live-handoff dial. The host bakes the matching guidance into the
+	 * system prompt; SDK consumers can still branch on it to render their
+	 * own UI hints.
+	 */
+	handoffThreshold: chatbotHandoffThresholdSchema.default("medium"),
+	/**
+	 * `true` when the org's subscription plan unlocks live front-desk
+	 * handoff (Growth+ on the host's pricing). Use this to render a
+	 * "Talk to a person" button or hide it when the org is on a tier that
+	 * is bot-only.
+	 */
+	frontDeskEnabled: z.boolean().default(false),
+	/**
+	 * `true` while the org's visitor file-upload "receive window" is open. Use it
+	 * to show/hide an upload affordance. Uploads also require the
+	 * `chat.file_uploads` entitlement (enforced on the upload route).
+	 */
+	fileUploadsEnabled: z.boolean().default(false),
+	/**
+	 * Whether/how the chat should ask the visitor for an email: `"request"` is a
+	 * skippable ask, `"require"` blocks the first message until one is provided.
+	 */
+	emailCaptureMode: z.enum(["off", "request", "require"]).default("off"),
+});
+export type ChatbotConfig = z.infer<typeof chatbotConfigSchema>;
+
+/** Response from the chat file-upload presign endpoint. */
+export const chatbotUploadUrlResponseSchema = z.object({
+	uploadUrl: z.string(),
+	mediaId: z.string(),
+	publicUrl: z.string(),
+	storageId: z.string(),
+	uploadExpiresAt: z.string(),
+});
+export type ChatbotUploadUrlResponse = z.infer<
+	typeof chatbotUploadUrlResponseSchema
+>;
+
+export const chatbotConfigUpdateInputSchema = z.object({
+	systemPrompt: z.string().min(1).max(10_000).optional(),
+	knowledgeBase: z.string().max(50_000).optional(),
+	model: z.string().min(1).max(120).optional(),
+	temperature: z.number().min(0).max(2).optional(),
+});
+export type ChatbotConfigUpdateInput = z.infer<
+	typeof chatbotConfigUpdateInputSchema
+>;
+
+export const chatbotMessageSchema = z.object({
+	role: z.enum(["user", "assistant", "system"]),
+	content: z.string().max(16_000),
+});
+export type ChatbotMessage = z.infer<typeof chatbotMessageSchema>;
+
+/**
+ * Per-call provider override (BYO key). When set, the turn runs against the
+ * SDK consumer's own LLM account — their `apiKey`, their billing — instead
+ * of the BIAB platform's configured provider, and the platform's monthly
+ * token budget is bypassed for that call.
+ *
+ * **Server-only.** Never send this from a browser: the key would be visible
+ * in DevTools. Hold it in your server env (e.g. `process.env.OPENAI_API_KEY`)
+ * and pass it on the server-side `client.chatbot.chat()` call. The
+ * `useChatbot` browser hook deliberately does not surface this field.
+ */
+export const chatbotByoConfigSchema = z.object({
+	provider: z.enum(["openai", "anthropic", "grok"]),
+	apiKey: z.string().min(1).max(500),
+	model: z.string().min(1).max(120).optional(),
+});
+export type ChatbotByoConfig = z.infer<typeof chatbotByoConfigSchema>;
+
+export const chatbotChatInputSchema = z.object({
+	messages: z.array(chatbotMessageSchema).min(1).max(40),
+	/** See {@link chatbotByoConfigSchema}. Server-side use only. */
+	byo: chatbotByoConfigSchema.optional(),
+});
+export type ChatbotChatInput = z.infer<typeof chatbotChatInputSchema>;
+
+/**
+ * Side-effect the assistant requested mid-turn. The SDK consumer renders
+ * each action — currently only `show_form`, which the consumer resolves by
+ * fetching the form definition and rendering inline in the chat thread.
+ */
+export const chatbotUiActionSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("show_form"),
+		formSlug: z.string().min(1).max(120),
+	}),
+]);
+export type ChatbotUiAction = z.infer<typeof chatbotUiActionSchema>;
+
+/**
+ * Live front-desk availability for the org. Mirrors what the public-site
+ * widget surfaces in its presence strip; SDK consumers can render a
+ * "Talk to a person" button conditional on `staffAvailable`, and a
+ * wait-time hint from `estimateLabel`.
+ */
+export const chatbotAvailabilitySchema = z.object({
+	frontDeskEnabled: z.boolean(),
+	staffAvailable: z.boolean(),
+	offline: z.boolean(),
+	estimateLabel: z.string().nullable(),
+	onlineHandlers: z.array(
+		z.object({
+			userId: z.string(),
+			name: z.string(),
+			avatarUrl: z.string().nullable(),
+		}),
+	),
+});
+export type ChatbotAvailability = z.infer<typeof chatbotAvailabilitySchema>;
+
+export const chatbotChatResponseSchema = z.object({
+	text: z.string(),
+	model: z.string(),
+	usingDefaults: z.boolean(),
+	uiActions: z.array(chatbotUiActionSchema).default([]),
+	availability: chatbotAvailabilitySchema.optional(),
+	/** True when the turn ran against a BYO provider key (consumer-paid). */
+	byo: z.boolean().default(false),
+});
+export type ChatbotChatResponse = z.infer<typeof chatbotChatResponseSchema>;
+
+/**
+ * Minimal field shape the SDK needs to render an inline form. Mirrors the
+ * host's `FormField` type but kept loose (only the keys the renderer
+ * actually reads) so additive server-side changes don't break old SDK
+ * builds.
+ */
+export const chatbotFormFieldSchema = z
+	.object({
+		id: z.string(),
+		label: z.string(),
+		type: z.string(),
+		required: z.boolean().default(false),
+		placeholder: z.string().optional(),
+		helpText: z.string().optional(),
+		options: z.array(z.string()).optional(),
+	})
+	.passthrough();
+export type ChatbotFormField = z.infer<typeof chatbotFormFieldSchema>;
+
+export const chatbotFormDefinitionSchema = z.object({
+	id: z.string(),
+	slug: z.string(),
+	name: z.string(),
+	description: z.string(),
+	fields: z.array(chatbotFormFieldSchema),
+	addsInquiry: z.boolean(),
+	addsLead: z.boolean(),
+});
+export type ChatbotFormDefinition = z.infer<typeof chatbotFormDefinitionSchema>;
+
+export const chatbotFormSubmitInputSchema = z.object({
+	data: z.record(z.unknown()),
+	submitterEmail: z.string().email().optional(),
+	submitterName: z.string().optional(),
+	priorChat: z
+		.array(
+			z.object({
+				role: z.string().min(1).max(40),
+				content: z.string().min(1).max(16_000),
+				createdAt: z.number().optional(),
+			}),
+		)
+		.max(200)
+		.optional(),
+});
+export type ChatbotFormSubmitInput = z.infer<
+	typeof chatbotFormSubmitInputSchema
+>;
+
+export const chatbotFormSubmitResponseSchema = z.object({
+	success: z.literal(true),
+	submissionId: z.string(),
+	slug: z.string(),
+});
+export type ChatbotFormSubmitResponse = z.infer<
+	typeof chatbotFormSubmitResponseSchema
+>;
+
+// ── Front Desk programmatic surface (Batch JJ, 0.9.0) ────────────────
+
+export const chatbotPersistedSessionInputSchema = z.object({
+	visitorToken: z.string().min(8).max(200),
+	visitorName: z.string().max(200).optional(),
+	visitorEmail: z.string().email().optional(),
+});
+export type ChatbotPersistedSessionInput = z.infer<
+	typeof chatbotPersistedSessionInputSchema
+>;
+
+export const chatbotPersistedSessionResponseSchema = z.object({
+	sessionId: z.string().uuid(),
+	/** Mirrors the `chat_session_status` pg enum. */
+	status: openEnum("bot", "awaiting_human", "assigned", "closed"),
+	startedAt: timestampSchema,
+	visitorToken: z.string(),
+});
+export type ChatbotPersistedSessionResponse = z.infer<
+	typeof chatbotPersistedSessionResponseSchema
+>;
+
+export const chatbotPersistedMessageSchema = z.object({
+	id: z.string(),
+	/** Mirrors the `chat_message_role` pg enum. */
+	role: openEnum("visitor", "assistant_bot", "staff", "system", "staff_note"),
+	content: z.string(),
+	createdAt: timestampSchema,
+	authorUserId: z.string().nullable(),
+});
+export type ChatbotPersistedMessage = z.infer<
+	typeof chatbotPersistedMessageSchema
+>;
+
+export const chatbotSessionStatusSchema = z.object({
+	sessionId: z.string(),
+	/** Mirrors the `chat_session_status` pg enum. */
+	status: openEnum("bot", "awaiting_human", "assigned", "closed"),
+	assignedUserId: z.string().nullable(),
+	placeInLine: z.number().int().nullable(),
+	stalled: z.boolean(),
+});
+export type ChatbotSessionStatus = z.infer<typeof chatbotSessionStatusSchema>;
+
+export const chatbotMessagesResponseSchema = z.object({
+	session: chatbotSessionStatusSchema,
+	messages: z.array(chatbotPersistedMessageSchema),
+});
+export type ChatbotMessagesResponse = z.infer<
+	typeof chatbotMessagesResponseSchema
+>;
+
+export const chatbotAppendMessageInputSchema = z.object({
+	sessionId: z.string().uuid(),
+	visitorToken: z.string().min(8).max(200),
+	content: z.string().min(1).max(16_000),
+	role: z.enum(["visitor", "assistant_bot"]).default("visitor"),
+});
+export type ChatbotAppendMessageInput = z.infer<
+	typeof chatbotAppendMessageInputSchema
+>;
+
+/**
+ * Plan-gate body shape. Identical across every gated endpoint —
+ * lift this to model upgrade-card props in one place.
+ */
+export const planGatedUnavailableSchema = z.object({
+	available: z.literal(false),
+	reason: z.literal("plan_required"),
+	requiredFeature: z.string(),
+	requiredPlan: z.string(),
+	planDisplayName: z.string(),
+	upgradeUrl: z.string(),
+});
+export type PlanGatedUnavailable = z.infer<typeof planGatedUnavailableSchema>;
+
+export const chatbotRequestHumanInputSchema = z.object({
+	sessionId: z.string().uuid(),
+	visitorToken: z.string().min(8).max(200),
+});
+export type ChatbotRequestHumanInput = z.infer<
+	typeof chatbotRequestHumanInputSchema
+>;
+
+export const chatbotRequestHumanAvailableSchema = z.object({
+	available: z.literal(true),
+	status: z.string(),
+	requestedAt: z.string().nullable(),
+	placeInLine: z.number().int().nullable(),
+	estimateLabel: z.string().nullable(),
+	staffAvailable: z.boolean(),
+	onlineHandlers: z.array(
+		z.object({
+			userId: z.string(),
+			name: z.string(),
+			avatarUrl: z.string().nullable(),
+		}),
+	),
+});
+export type ChatbotRequestHumanAvailable = z.infer<
+	typeof chatbotRequestHumanAvailableSchema
+>;
+
+/**
+ * Discriminated union — every Front Desk write returns one of these.
+ * Branch on `.available` to render the upgrade CTA vs the queue UI.
+ */
+export const chatbotRequestHumanResponseSchema = z.union([
+	chatbotRequestHumanAvailableSchema,
+	planGatedUnavailableSchema,
+]);
+export type ChatbotRequestHumanResponse = z.infer<
+	typeof chatbotRequestHumanResponseSchema
+>;
+
+export const executeActionInputSchema = z.object({
+	payload: z.record(z.unknown()).default({}),
+});
+
+export const executeActionResponseSchema = z.object({
+	actionName: z.string().min(1),
+	result: z.unknown(),
+});
+
+export const siteMarketingPageKeySchema = z
+	.string()
+	.min(1)
+	.max(120)
+	.regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/);
+
+export const siteMarketingPageSchema = z.object({
+	siteId: siteIdSchema,
+	pageKey: siteMarketingPageKeySchema,
+	payload: jsonValueSchema,
+	updatedAt: timestampSchema,
+});
+
+export const getSiteMarketingPageResponseSchema = z.object({
+	page: siteMarketingPageSchema.nullable(),
+});
+
+/**
+ * Lightweight directory entry — `pageKey` + `updatedAt` only. Pair with
+ * a per-page `get(pageKey)` (or React `useMarketingPage(pageKey)`) to
+ * load the payload on demand. Splitting list from content keeps a
+ * many-page site from paying the full-payload cost just to render a
+ * navigation index.
+ */
+export const siteMarketingPageSummarySchema = z.object({
+	siteId: siteIdSchema,
+	pageKey: siteMarketingPageKeySchema,
+	updatedAt: timestampSchema,
+});
+
+export const listSiteMarketingPagesResponseSchema = z.object({
+	pages: z.array(siteMarketingPageSummarySchema),
+});
+
+export const authIntrospectResponseSchema = z.object({
+	apiKeyId: apiKeyIdSchema.optional(),
+	orgId: z.string().uuid(),
+	userId: z.string().uuid().nullable().optional(),
+	siteIds: z.array(siteIdSchema).optional(),
+	scopes: z.array(z.string()).default([]),
+	expiresAt: timestampSchema.nullable().optional(),
+	label: z.string().optional(),
+});
+
+export const emailTemplateRendererValues = ["native-email-builder"] as const;
+export const emailTemplateRendererSchema = z.enum(emailTemplateRendererValues);
+
+export const emailTemplateCategoryValues = [
+	"system",
+	"marketing",
+	"transactional",
+] as const;
+export const emailTemplateCategorySchema = z.enum(emailTemplateCategoryValues);
+
+export const emailTemplateVariableTypeValues = [
+	"string",
+	"number",
+	"url",
+	"currency",
+	"date",
+] as const;
+export const emailTemplateVariableTypeSchema = z.enum(
+	emailTemplateVariableTypeValues,
+);
+
+export const emailTemplateVariableSchema = z.object({
+	key: z.string().min(1),
+	label: z.string().min(1),
+	type: emailTemplateVariableTypeSchema,
+	required: z.boolean(),
+	defaultValue: z.unknown().optional(),
+});
+
+export const emailTemplateSummarySchema = z.object({
+	id: z.number().int(),
+	name: z.string().min(1),
+	slug: z.string().min(1),
+	description: z.string().nullable().optional(),
+	ownerId: z.string().min(1),
+	organizationId: z.string().nullable().optional(),
+	renderer: emailTemplateRendererSchema,
+	category: emailTemplateCategorySchema,
+	isActive: z.boolean(),
+	isArchived: z.boolean(),
+	createdAt: timestampSchema,
+	updatedAt: timestampSchema,
+});
+
+export const emailTemplateVersionSchema = z.object({
+	id: z.number().int(),
+	templateId: z.number().int(),
+	version: z.number().int(),
+	subject: z.string().min(1),
+	renderer: emailTemplateRendererSchema,
+	unlayerDesign: z.unknown().optional(),
+	builderDocument: z.unknown().optional(),
+	html: z.string().nullable().optional(),
+	reactComponent: z.string().nullable().optional(),
+	reactPropsSchema: z.unknown().optional(),
+	variables: z.array(emailTemplateVariableSchema),
+	createdBy: z.string().min(1),
+	createdAt: timestampSchema,
+	isPublished: z.boolean(),
+});
+
+export const listEmailTemplatesInputSchema = z.object({
+	category: emailTemplateCategorySchema.optional(),
+	activeOnly: z.boolean().optional(),
+});
+
+export const listEmailTemplatesResponseSchema = z.object({
+	templates: z.array(emailTemplateSummarySchema),
+});
+
+export const getEmailTemplateResponseSchema = z.object({
+	template: emailTemplateSummarySchema,
+	versions: z.array(emailTemplateVersionSchema),
+});
+
+export const createEmailTemplateInputSchema = z.object({
+	name: z.string().min(1),
+	slug: z.string().min(1),
+	description: z.string().optional(),
+	category: emailTemplateCategorySchema,
+	isActive: z.boolean().optional(),
+});
+
+export const createEmailTemplateResponseSchema = z.object({
+	template: emailTemplateSummarySchema,
+});
+
+export const createEmailTemplateVersionInputSchema = z.object({
+	subject: z.string().min(1),
+	builderDocument: z.unknown().optional(),
+	html: z.string().optional(),
+	reactComponent: z.string().optional(),
+	reactPropsSchema: z.unknown().optional(),
+	variables: z.array(emailTemplateVariableSchema).optional(),
+	isPublished: z.boolean().optional(),
+});
+
+export const createEmailTemplateVersionResponseSchema = z.object({
+	version: emailTemplateVersionSchema,
+});
+
+export type CollectionFieldType = z.infer<typeof collectionFieldTypeSchema>;
+export type CollectionFieldInput = z.infer<typeof collectionFieldInputSchema>;
+export type CollectionField = z.infer<typeof collectionFieldSchema>;
+export type Collection = z.infer<typeof collectionSchema>;
+export type CreateCollectionInput = z.infer<typeof createCollectionInputSchema>;
+export type CreateCollectionResponse = z.infer<
+	typeof createCollectionResponseSchema
+>;
+export type ListCollectionsResponse = z.infer<
+	typeof listCollectionsResponseSchema
+>;
+export type GetCollectionResponse = z.infer<typeof getCollectionResponseSchema>;
+export type CollectionRow = z.infer<typeof collectionRowSchema>;
+export type ListRowsInput = z.infer<typeof listRowsInputSchema>;
+export type ListRowsResponse = z.infer<typeof listRowsResponseSchema>;
+export type UpsertRowInput = z.infer<typeof upsertRowInputSchema>;
+export type UpsertRowResponse = z.infer<typeof upsertRowResponseSchema>;
+export type QueryFilter = z.infer<typeof queryFilterSchema>;
+export type QueryRowsInput = z.infer<typeof queryRowsInputSchema>;
+export type QueryRowsResponse = z.infer<typeof queryRowsResponseSchema>;
+export type SiteAssetInput = z.infer<typeof siteAssetInputSchema>;
+export type SiteAsset = z.infer<typeof siteAssetSchema>;
+export type UploadSiteAssetResponse = z.infer<
+	typeof uploadSiteAssetResponseSchema
+>;
+export type ExecuteActionInput = z.infer<typeof executeActionInputSchema>;
+export type ExecuteActionResponse = z.infer<typeof executeActionResponseSchema>;
+export type AuthIntrospectResponse = z.infer<
+	typeof authIntrospectResponseSchema
+>;
+export type EmailTemplateRenderer = z.infer<typeof emailTemplateRendererSchema>;
+export type EmailTemplateCategory = z.infer<typeof emailTemplateCategorySchema>;
+export type EmailTemplateVariable = z.infer<typeof emailTemplateVariableSchema>;
+export type EmailTemplateSummary = z.infer<typeof emailTemplateSummarySchema>;
+export type EmailTemplateVersion = z.infer<typeof emailTemplateVersionSchema>;
+export type ListEmailTemplatesInput = z.infer<
+	typeof listEmailTemplatesInputSchema
+>;
+export type ListEmailTemplatesResponse = z.infer<
+	typeof listEmailTemplatesResponseSchema
+>;
+export type GetEmailTemplateResponse = z.infer<
+	typeof getEmailTemplateResponseSchema
+>;
+export type CreateEmailTemplateInput = z.infer<
+	typeof createEmailTemplateInputSchema
+>;
+export type CreateEmailTemplateResponse = z.infer<
+	typeof createEmailTemplateResponseSchema
+>;
+export type CreateEmailTemplateVersionInput = z.infer<
+	typeof createEmailTemplateVersionInputSchema
+>;
+export type CreateEmailTemplateVersionResponse = z.infer<
+	typeof createEmailTemplateVersionResponseSchema
+>;
+export type Follower = z.infer<typeof followerSchema>;
+export type FollowerJoinInput = z.infer<typeof followerJoinInputSchema>;
+export type FollowerJoinResponse = z.infer<typeof followerJoinResponseSchema>;
+export type FollowerMeInput = z.infer<typeof followerMeInputSchema>;
+export type FollowerMeResponse = z.infer<typeof followerMeResponseSchema>;
+export type FollowerEditInput = z.infer<typeof followerEditInputSchema>;
+export type FollowerEditResponse = z.infer<typeof followerEditResponseSchema>;
+export type FollowerLeaveInput = z.infer<typeof followerLeaveInputSchema>;
+export type FollowerLeaveResponse = z.infer<typeof followerLeaveResponseSchema>;
+export type DashboardSessionResponse = z.infer<
+	typeof dashboardSessionResponseSchema
+>;
+export type SiteMarketingPage = z.infer<typeof siteMarketingPageSchema>;
+export type GetSiteMarketingPageResponse = z.infer<
+	typeof getSiteMarketingPageResponseSchema
+>;
+export type SiteMarketingPageSummary = z.infer<
+	typeof siteMarketingPageSummarySchema
+>;
+export type ListSiteMarketingPagesResponse = z.infer<
+	typeof listSiteMarketingPagesResponseSchema
+>;
+
+// ── Customer Portal ──────────────────────────────────────────────────────────
+//
+// The customer portal is host- or session-scoped to one organization. The
+// contracts mirror `(public)/portal/*` routes on the platform and the
+// `customerPortal` tRPC router. Hosts: a tenant subdomain like
+// `app.<slug>.<platform>` resolves to one org; in absence of a slug the
+// caller's session organization id is used.
+
+export const customerPortalOrgSchema = z.object({
+	id: z.string().uuid(),
+	name: z.string().nullable(),
+	/** @deprecated Internal auth-provider org id — use `id` (the BIAB org id).
+	 *  Kept for backwards compatibility; will be removed in a future release. */
+	workosOrganizationId: z.string().nullable().optional(),
+});
+
+export const customerPortalUserSchema = z.object({
+	id: z.string().uuid(),
+	email: z.string().nullable(),
+	displayName: z.string().nullable(),
+	avatarUrl: z.string().nullable(),
+});
+
+export const customerPortalContextResponseSchema = z.object({
+	organization: customerPortalOrgSchema,
+	user: customerPortalUserSchema,
+	isCustomer: z.boolean(),
+});
+
+export const customerPortalProfileSchema = z
+	.object({
+		externalCustomerId: z.string().nullable(),
+		profile: z.record(z.unknown()).nullable(),
+		lastSeenAt: timestampSchema.nullable(),
+		joinedAt: timestampSchema.nullable(),
+	})
+	.nullable();
+
+export const customerPortalUpdateProfileInputSchema = z.object({
+	displayName: z.string().min(1).max(120).optional(),
+	profile: z.record(z.unknown()).optional(),
+});
+
+export const customerPortalUpdateProfileResponseSchema = z.object({
+	ok: z.literal(true),
+});
+
+export const customerPortalOtherOrgSchema = z.object({
+	orgId: z.string().uuid(),
+	name: z.string().nullable(),
+	/** @deprecated Internal auth-provider org id — use `orgId` (the BIAB org id).
+	 *  Kept for backwards compatibility; will be removed in a future release. */
+	workosOrganizationId: z.string().nullable().optional(),
+});
+export const customerPortalOtherOrgsResponseSchema = z.array(
+	customerPortalOtherOrgSchema,
+);
+
+export type CustomerPortalOrg = z.infer<typeof customerPortalOrgSchema>;
+export type CustomerPortalUser = z.infer<typeof customerPortalUserSchema>;
+export type CustomerPortalContextResponse = z.infer<
+	typeof customerPortalContextResponseSchema
+>;
+export type CustomerPortalProfile = z.infer<typeof customerPortalProfileSchema>;
+export type CustomerPortalUpdateProfileInput = z.infer<
+	typeof customerPortalUpdateProfileInputSchema
+>;
+export type CustomerPortalUpdateProfileResponse = z.infer<
+	typeof customerPortalUpdateProfileResponseSchema
+>;
+export type CustomerPortalOtherOrg = z.infer<
+	typeof customerPortalOtherOrgSchema
+>;
+export type CustomerPortalOtherOrgsResponse = z.infer<
+	typeof customerPortalOtherOrgsResponseSchema
+>;
+
+// ── Customer notification preferences (per-customer, per-channel) ─────
+//
+// The matrix shape is `{ [categoryId]: { email, sms, push, in_app } }`.
+// The server returns a fully-defaulted matrix plus the category metadata
+// so SDK consumers can render the UI without hardcoding either the
+// categories or the channels list — both grow over time.
+
+export const notificationChannelSchema = z.enum([
+	"email",
+	"sms",
+	"push",
+	"in_app",
+]);
+export type NotificationChannel = z.infer<typeof notificationChannelSchema>;
+
+export const notificationChannelMapSchema = z.object({
+	email: z.boolean(),
+	sms: z.boolean(),
+	push: z.boolean(),
+	in_app: z.boolean(),
+});
+
+export const notificationCategoryDefSchema = z.object({
+	id: z.string(),
+	label: z.string(),
+	description: z.string(),
+	defaults: notificationChannelMapSchema,
+	required: z.record(notificationChannelSchema, z.literal(true)).optional(),
+});
+
+export const notificationPreferencesResponseSchema = z.object({
+	preferences: z.record(notificationChannelMapSchema),
+	categories: z.array(notificationCategoryDefSchema),
+	channels: z.array(notificationChannelSchema),
+});
+
+export const notificationPreferencesUpdateInputSchema = z.object({
+	/**
+	 * Sparse — only the categories / channels you want to flip need to
+	 * be present. Omitted keys keep their persisted (or default) value.
+	 */
+	preferences: z.record(
+		z.object({
+			email: z.boolean().optional(),
+			sms: z.boolean().optional(),
+			push: z.boolean().optional(),
+			in_app: z.boolean().optional(),
+		}),
+	),
+});
+
+export type NotificationChannelMap = z.infer<
+	typeof notificationChannelMapSchema
+>;
+export type NotificationCategoryDef = z.infer<
+	typeof notificationCategoryDefSchema
+>;
+export type NotificationPreferencesResponse = z.infer<
+	typeof notificationPreferencesResponseSchema
+>;
+export type NotificationPreferencesUpdateInput = z.infer<
+	typeof notificationPreferencesUpdateInputSchema
+>;
+
+// ── Customer-portal "work" bundle (jobs / quotes / invoices / contracts / payments) ─────
+
+export const customerJobSummarySchema = z.object({
+	id: z.string(),
+	name: z.string().nullable(),
+	status: z.string(),
+	startDate: z.string().nullable(),
+	dueDate: z.string().nullable(),
+	statusCompletedAt: z.string().nullable(),
+});
+
+export const customerQuoteSummarySchema = z.object({
+	id: z.string(),
+	quoteNumber: z.string(),
+	/** Mirrors the `quote_status` pg enum. */
+	status: openEnum(
+		"draft",
+		"sent",
+		"accepted",
+		"rejected",
+		"converted",
+		"expired",
+	),
+	totalAmount: z.number(),
+	validUntil: z.string(),
+	publicAcceptUrl: z.string().nullable(),
+});
+
+export const customerInvoiceSummarySchema = z.object({
+	id: z.string(),
+	invoiceNumber: z.string(),
+	/** Mirrors the `invoice_status` pg enum. */
+	status: openEnum(
+		"draft",
+		"sent",
+		"partial_paid",
+		"paid",
+		"overdue",
+		"cancelled",
+	),
+	/** Mirrors the `invoice_job_status` pg enum. */
+	jobStatus: openEnum("pending", "in_progress", "complete").nullable(),
+	totalAmount: z.number(),
+	paidAmount: z.number(),
+	balanceDue: z.number(),
+	dueDate: z.string(),
+	issueDate: z.string(),
+	paidAt: z.string().nullable(),
+	publicPayUrl: z.string().nullable(),
+});
+
+export const customerContractSummarySchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	/** Mirrors the `contract_status` pg enum. */
+	status: openEnum("draft", "sent", "signed", "expired", "cancelled"),
+	sentAt: z.string().nullable(),
+	signedAt: z.string().nullable(),
+	signingUrl: z.string().nullable(),
+	signedDocumentUrl: z.string().nullable(),
+});
+
+export const customerPaymentSummarySchema = z.object({
+	id: z.string(),
+	invoiceId: z.string(),
+	amount: z.number(),
+	/** Mirrors the `payment_method` pg enum. */
+	method: openEnum("card", "bank_transfer", "cash", "check", "other"),
+	date: z.string(),
+});
+
+export const customerWorkBundleSchema = z
+	.object({
+		/** True when the customer's email matches no CRM contact in this org. */
+		unlinked: z.boolean(),
+		jobs: z.array(customerJobSummarySchema),
+		quotes: z.array(customerQuoteSummarySchema),
+		invoices: z.array(customerInvoiceSummarySchema),
+		contracts: z.array(customerContractSummarySchema),
+		payments: z.array(customerPaymentSummarySchema),
+		summary: z.object({
+			openJobCount: z.number(),
+			pendingQuoteCount: z.number(),
+			unpaidInvoiceCount: z.number(),
+			unpaidBalance: z.number(),
+			awaitingSignatureCount: z.number(),
+		}),
+	})
+	.passthrough();
+
+export type CustomerJobSummary = z.infer<typeof customerJobSummarySchema>;
+export type CustomerQuoteSummary = z.infer<typeof customerQuoteSummarySchema>;
+export type CustomerInvoiceSummary = z.infer<
+	typeof customerInvoiceSummarySchema
+>;
+export type CustomerContractSummary = z.infer<
+	typeof customerContractSummarySchema
+>;
+export type CustomerPaymentSummary = z.infer<
+	typeof customerPaymentSummarySchema
+>;
+export type CustomerWorkBundle = z.infer<typeof customerWorkBundleSchema>;
+
+// ── Customer-portal per-item detail responses ─────────────────────────
+
+export const customerJobDetailSchema = customerJobSummarySchema.passthrough();
+
+export const customerQuoteDetailSchema = z
+	.object({
+		id: z.string(),
+		quoteNumber: z.string(),
+		/** Mirrors the `quote_status` pg enum. */
+		status: openEnum(
+			"draft",
+			"sent",
+			"accepted",
+			"rejected",
+			"converted",
+			"expired",
+		),
+		items: z.array(z.unknown()),
+		subtotalAmount: z.number(),
+		discountAmount: z.number(),
+		taxRate: z.number(),
+		taxAmount: z.number(),
+		totalAmount: z.number(),
+		validUntil: z.string(),
+		publicAcceptUrl: z.string().nullable(),
+		notes: z.string().nullable(),
+	})
+	.passthrough();
+
+/** One entry in the customer's cross-surface payment history — invoice
+ *  payments, store-order charges, and refunds (negative amount), newest
+ *  first. `reference` is the confirmation # (Stripe PaymentIntent id for
+ *  card, provider refund id, or a manual reference). */
+export const customerPaymentHistoryEntrySchema = z.object({
+	id: z.string(),
+	kind: z.enum(["invoice_payment", "order_charge", "order_refund"]),
+	/** Dollars. Negative for refunds. */
+	amount: z.number(),
+	/** Integer cents for exact math. Negative for refunds. */
+	amountCents: z.number(),
+	/** Mirrors the `payment_method` pg enum. */
+	method: openEnum(
+		"card",
+		"bank_transfer",
+		"cash",
+		"check",
+		"other",
+	).nullable(),
+	status: z.string(),
+	reference: z.string().nullable(),
+	occurredAt: z.string(),
+	invoiceId: z.string().optional(),
+	invoiceNumber: z.string().optional(),
+	orderId: z.string().optional(),
+	orderNumber: z.string().optional(),
+});
+
+export const customerPaymentHistoryResponseSchema = z.object({
+	items: z.array(customerPaymentHistoryEntrySchema),
+});
+
+/** A single recorded payment/refund on an invoice. */
+export const customerInvoicePaymentSchema = z.object({
+	amount: z.number(),
+	/** Mirrors the `payment_method` pg enum. */
+	method: openEnum("card", "bank_transfer", "cash", "check", "other"),
+	date: z.string(),
+	/** Stripe PaymentIntent id (card) or manual reference (check #, etc.). */
+	reference: z.string().nullable(),
+	/**
+	 * These three are what the platform writes today, but unlike the other
+	 * statuses in this file there is no enum behind them — `payments.status` is
+	 * plain `text` with a `"completed"` default, so the column accepts anything.
+	 * `openEnum` is the honest shape for that: helpful to callers, and it can't
+	 * reject a row some other writer put there.
+	 */
+	status: openEnum("completed", "refunded", "failed"),
+});
+
+export const customerInvoiceDetailSchema = z
+	.object({
+		id: z.string(),
+		invoiceNumber: z.string(),
+		/** Mirrors the `invoice_status` pg enum. */
+		status: openEnum(
+			"draft",
+			"sent",
+			"partial_paid",
+			"paid",
+			"overdue",
+			"cancelled",
+		),
+		/** Mirrors the `invoice_job_status` pg enum. */
+		jobStatus: openEnum("pending", "in_progress", "complete").nullable(),
+		totalAmount: z.number(),
+		paidAmount: z.number(),
+		balanceDue: z.number(),
+		dueDate: z.string(),
+		issueDate: z.string(),
+		paidAt: z.string().nullable(),
+		paymentSchedule: z.unknown().nullable(),
+		notes: z.string().nullable(),
+		terms: z.string().nullable(),
+		publicPayUrl: z.string().nullable(),
+		// Optional so the SDK stays compatible with older BIAB deployments
+		// that don't return these yet.
+		/** Recorded payments/refunds, oldest first. */
+		payments: z.array(customerInvoicePaymentSchema).optional(),
+		/** Most-recent completed payment reference — the confirmation number. */
+		confirmationNumber: z.string().nullable().optional(),
+		/** Host-less path to the downloadable invoice PDF. */
+		pdfPath: z.string().nullable().optional(),
+	})
+	.passthrough();
+
+/**
+ * Response of `downloadInvoicePdf` — the invoice rendered as a PDF, base64
+ * encoded (the SDK decodes it to bytes for you).
+ */
+export const customerInvoicePdfSchema = z.object({
+	invoiceNumber: z.string(),
+	filename: z.string(),
+	contentType: z.string(),
+	base64: z.string(),
+});
+
+export const customerContractDetailSchema = z
+	.object({
+		id: z.string(),
+		title: z.string(),
+		/** Mirrors the `contract_status` pg enum. */
+		status: openEnum("draft", "sent", "signed", "expired", "cancelled"),
+		contractNumber: z.string().nullable(),
+		sentAt: z.string().nullable(),
+		signedAt: z.string().nullable(),
+		signedDocumentUrl: z.string().nullable(),
+		signingUrl: z.string().nullable(),
+		pdfUrl: z.string().nullable(),
+	})
+	.passthrough();
+
+export const customerQuoteActionResponseSchema = z.object({
+	ok: z.literal(true),
+	status: z.string(),
+	dealId: z.string().nullable().optional(),
+});
+
+/** Optional storefront return pages for the hosted Stripe Checkout. */
+export const customerInvoicePayInputSchema = z.object({
+	successUrl: z.string().url().max(2000).optional(),
+	cancelUrl: z.string().url().max(2000).optional(),
+});
+
+/** Response of `payInvoice` — a Stripe-hosted Checkout URL to redirect to. */
+export const customerInvoicePayResponseSchema = z.object({
+	invoiceId: z.string(),
+	status: z.string(),
+	checkoutUrl: z.string().url(),
+	checkoutSessionId: z.string(),
+});
+
+/** Response of `signContract` — a ready, absolute hosted signing URL. */
+export const customerContractSignResponseSchema = z.object({
+	contractId: z.string(),
+	status: z.string(),
+	signingUrl: z.string().url(),
+});
+
+export type CustomerInvoicePayInput = z.infer<
+	typeof customerInvoicePayInputSchema
+>;
+export type CustomerInvoicePayResponse = z.infer<
+	typeof customerInvoicePayResponseSchema
+>;
+export type CustomerContractSignResponse = z.infer<
+	typeof customerContractSignResponseSchema
+>;
+
+// ── Customer-portal: referrals (the customer as an affiliate) ──────────
+// Read-only self surface. Counters are real (denormalized on the affiliate
+// row); they read zero / empty until the org's referral attribution +
+// payout pipeline records conversions for this customer.
+
+/** Roll-up of the customer's referral activity, summed across programs. */
+export const customerReferralStatsSchema = z.object({
+	/** True when the customer holds at least one affiliate record. */
+	enrolled: z.boolean(),
+	programCount: z.number(),
+	claimsCount: z.number(),
+	conversionsCount: z.number(),
+	revenueCents: z.number(),
+	earningsCents: z.number(),
+	nextPayoutCents: z.number(),
+	nextPayoutAt: z.string().nullable(),
+});
+
+export const customerReferralConversionSchema = z.object({
+	id: z.string(),
+	programId: z.string(),
+	amountCents: z.number(),
+	commissionCents: z.number(),
+	currency: z.string(),
+	/** Mirrors the `referral_conversion_status` pg enum. */
+	status: openEnum("pending", "confirmed", "reversed"),
+	createdAt: z.string(),
+});
+
+export const customerReferralHistoryResponseSchema = z.object({
+	items: z.array(customerReferralConversionSchema),
+});
+
+export const customerReferralPayoutSchema = z.object({
+	id: z.string(),
+	programId: z.string(),
+	periodStart: z.string(),
+	periodEnd: z.string(),
+	amountCents: z.number(),
+	feeCents: z.number(),
+	totalCents: z.number(),
+	currency: z.string(),
+	/** Mirrors the `referral_payout_status` pg enum. */
+	status: openEnum("upcoming", "pending", "paid", "failed"),
+	paidAt: z.string().nullable(),
+});
+
+export const customerReferralPayoutsResponseSchema = z.object({
+	items: z.array(customerReferralPayoutSchema),
+});
+
+export type CustomerReferralStats = z.infer<typeof customerReferralStatsSchema>;
+export type CustomerReferralConversion = z.infer<
+	typeof customerReferralConversionSchema
+>;
+export type CustomerReferralHistoryResponse = z.infer<
+	typeof customerReferralHistoryResponseSchema
+>;
+export type CustomerReferralPayout = z.infer<
+	typeof customerReferralPayoutSchema
+>;
+export type CustomerReferralPayoutsResponse = z.infer<
+	typeof customerReferralPayoutsResponseSchema
+>;
+
+// ── Customer-portal: orders + shipping status tracker ──────────────────
+
+/** One order in the customer's list, with a shipment roll-up for the chip. */
+export const customerOrderSummarySchema = z.object({
+	id: z.string(),
+	orderNumber: z.string(),
+	/** Mirrors the `order_status` pg enum. */
+	status: openEnum(
+		"pending",
+		"confirmed",
+		"processing",
+		"packed",
+		"shipped",
+		"delivered",
+		"cancelled",
+		"refunded",
+	),
+	/** Mirrors the `order_payment_status` pg enum. */
+	paymentStatus: openEnum("unpaid", "paid", "partial", "refunded"),
+	totalCents: z.number(),
+	createdAt: z.string(),
+	shipmentCount: z.number(),
+	/** Rolled up across the order's shipments. Mirrors `order_shipment_status`. */
+	overallStatus: openEnum(
+		"pending",
+		"label_created",
+		"in_transit",
+		"delivered",
+		"returned",
+	),
+	anyInTransit: z.boolean(),
+	allDelivered: z.boolean(),
+	latestEstimatedDelivery: z.string().nullable(),
+});
+
+export const customerOrderListResponseSchema = z.object({
+	items: z.array(customerOrderSummarySchema),
+});
+
+export const customerOrderItemSchema = z.object({
+	id: z.string(),
+	productName: z.string(),
+	variantName: z.string().nullable(),
+	sku: z.string().nullable(),
+	quantity: z.number(),
+	unitPriceCents: z.number(),
+	totalCents: z.number(),
+	requiresShipping: z.boolean(),
+});
+
+export const customerShipmentSchema = z.object({
+	id: z.string(),
+	carrier: z.string().nullable(),
+	trackingNumber: z.string().nullable(),
+	trackingUrl: z.string().nullable(),
+	serviceName: z.string().nullable(),
+	/** Mirrors the `order_shipment_status` pg enum. */
+	status: openEnum(
+		"pending",
+		"label_created",
+		"in_transit",
+		"delivered",
+		"returned",
+	),
+	estimatedDelivery: z.string().nullable(),
+	shippedAt: z.string().nullable(),
+	deliveredAt: z.string().nullable(),
+	isReturn: z.boolean(),
+	/** Append-only carrier-event timeline (one entry per status transition). */
+	statusHistory: z.array(z.unknown()),
+});
+
+/** A return/refund request the customer opened on this order (P10b). */
+export const customerReturnRequestSchema = z.object({
+	id: z.string(),
+	/**
+	 * Mirrors `order_return_request_status`. Note the spelling: this enum uses
+	 * `cancelled` (two Ls), while `booking_status` uses `canceled` (one). They
+	 * are separate enums and each is spelled as the database spells it.
+	 */
+	status: openEnum("requested", "approved", "denied", "refunded", "cancelled"),
+	reason: z.string().nullable(),
+	items: z
+		.array(
+			z.object({
+				orderItemId: z.string(),
+				productName: z.string(),
+				quantity: z.number(),
+			}),
+		)
+		.nullable(),
+	customerNote: z.string().nullable(),
+	resolutionNote: z.string().nullable(),
+	createdAt: z.string(),
+	resolvedAt: z.string().nullable(),
+});
+
+export const customerOrderDetailSchema = z.object({
+	id: z.string(),
+	orderNumber: z.string(),
+	/** Mirrors the `order_status` pg enum. */
+	status: openEnum(
+		"pending",
+		"confirmed",
+		"processing",
+		"packed",
+		"shipped",
+		"delivered",
+		"cancelled",
+		"refunded",
+	),
+	/** Mirrors the `order_payment_status` pg enum. */
+	paymentStatus: openEnum("unpaid", "paid", "partial", "refunded"),
+	subtotalCents: z.number(),
+	shippingCents: z.number(),
+	taxCents: z.number(),
+	discountCents: z.number(),
+	totalCents: z.number(),
+	createdAt: z.string(),
+	items: z.array(customerOrderItemSchema),
+	shipments: z.array(customerShipmentSchema),
+	// Optional for back-compat with older BIAB deployments.
+	returnRequests: z.array(customerReturnRequestSchema).optional(),
+});
+
+/** Input for `submitReturnRequest`. Omit `items` for a whole-order request. */
+export const customerReturnRequestInputSchema = z.object({
+	reason: z.string().max(120).optional(),
+	customerNote: z.string().max(2000).optional(),
+	items: z
+		.array(
+			z.object({
+				orderItemId: z.string().uuid(),
+				quantity: z.number().int().positive(),
+			}),
+		)
+		.optional(),
+});
+
+/** Response of `submitReturnRequest` — the newly opened request. */
+export const customerReturnRequestCreatedSchema = z.object({
+	id: z.string().nullable(),
+	/** Mirrors the `order_return_request_status` pg enum. */
+	status: openEnum("requested", "approved", "denied", "refunded", "cancelled"),
+	createdAt: z.string().nullable(),
+});
+
+/** One downloadable digital deliverable for a paid order (P10d). */
+export const customerDownloadSchema = z.object({
+	productName: z.string(),
+	fileName: z.string().nullable(),
+	/** Short-lived presigned URL (BIAB-hosted) or the org's external link. */
+	url: z.string(),
+	/** Seconds until `url` expires; null for a non-expiring external link. */
+	expiresInSeconds: z.number().nullable(),
+});
+
+/** Response of `getDownloads` — the order's entitlement-checked downloads. */
+export const customerDownloadsResponseSchema = z.object({
+	items: z.array(customerDownloadSchema),
+});
+
+/** `trackShipment` — stored shipment + a best-effort live carrier status. */
+export const customerShipmentTrackingSchema = z.object({
+	id: z.string(),
+	orderId: z.string().nullable(),
+	carrier: z.string().nullable(),
+	trackingNumber: z.string().nullable(),
+	trackingUrl: z.string().nullable(),
+	serviceName: z.string().nullable(),
+	/** Mirrors the `order_shipment_status` pg enum. */
+	status: openEnum(
+		"pending",
+		"label_created",
+		"in_transit",
+		"delivered",
+		"returned",
+	),
+	estimatedDelivery: z.string().nullable(),
+	shippedAt: z.string().nullable(),
+	deliveredAt: z.string().nullable(),
+	statusHistory: z.array(z.unknown()),
+	/** Live Shippo tracking_status when polled; null otherwise. */
+	liveStatus: z.unknown().nullable(),
+});
+
+export type CustomerOrderSummary = z.infer<typeof customerOrderSummarySchema>;
+export type CustomerOrderListResponse = z.infer<
+	typeof customerOrderListResponseSchema
+>;
+export type CustomerOrderItem = z.infer<typeof customerOrderItemSchema>;
+export type CustomerShipment = z.infer<typeof customerShipmentSchema>;
+export type CustomerOrderDetail = z.infer<typeof customerOrderDetailSchema>;
+export type CustomerReturnRequest = z.infer<typeof customerReturnRequestSchema>;
+export type CustomerReturnRequestInput = z.infer<
+	typeof customerReturnRequestInputSchema
+>;
+export type CustomerReturnRequestCreated = z.infer<
+	typeof customerReturnRequestCreatedSchema
+>;
+export type CustomerDownload = z.infer<typeof customerDownloadSchema>;
+export type CustomerDownloadsResponse = z.infer<
+	typeof customerDownloadsResponseSchema
+>;
+export type CustomerShipmentTracking = z.infer<
+	typeof customerShipmentTrackingSchema
+>;
+
+// ── Storefront branding ────────────────────────────────────────────────
+
+/** Org storefront branding — logo + favicon (site media) + org name/icon. */
+export const siteBrandingSchema = z.object({
+	siteId: z.string(),
+	siteName: z.string().nullable(),
+	logoUrl: z.string().nullable(),
+	faviconUrl: z.string().nullable(),
+	orgName: z.string().nullable(),
+	orgIcon: z.string().nullable(),
+});
+
+export type SiteBranding = z.infer<typeof siteBrandingSchema>;
+
+export type CustomerJobDetail = z.infer<typeof customerJobDetailSchema>;
+export type CustomerQuoteDetail = z.infer<typeof customerQuoteDetailSchema>;
+export type CustomerInvoiceDetail = z.infer<typeof customerInvoiceDetailSchema>;
+export type CustomerInvoicePayment = z.infer<
+	typeof customerInvoicePaymentSchema
+>;
+export type CustomerPaymentHistoryEntry = z.infer<
+	typeof customerPaymentHistoryEntrySchema
+>;
+export type CustomerPaymentHistoryResponse = z.infer<
+	typeof customerPaymentHistoryResponseSchema
+>;
+export type CustomerInvoicePdf = z.infer<typeof customerInvoicePdfSchema>;
+export type CustomerContractDetail = z.infer<
+	typeof customerContractDetailSchema
+>;
+export type CustomerQuoteActionResponse = z.infer<
+	typeof customerQuoteActionResponseSchema
+>;
+
+// ── Customer-portal: first-party reviews ──────────────────────────────
+
+export const customerReviewSummarySchema = z.object({
+	id: z.string(),
+	rating: z.number().int(),
+	title: z.string().nullable(),
+	body: z.string(),
+	/** Mirrors the `first_party_review_status` pg enum. */
+	status: openEnum("pending", "published", "hidden"),
+	jobId: z.string().nullable(),
+	submittedAt: z.string(),
+	publishedAt: z.string().nullable(),
+});
+
+export const customerReviewListResponseSchema = z.object({
+	items: z.array(customerReviewSummarySchema),
+});
+
+export const customerReviewSubmitInputSchema = z.object({
+	rating: z.number().int().min(1).max(5),
+	title: z.string().max(200).optional(),
+	body: z.string().min(1).max(5000),
+	jobId: z.string().uuid().optional(),
+});
+
+export const customerReviewSubmitResponseSchema = z
+	.object({
+		id: z.string().optional(),
+		status: z.string().optional(),
+		submittedAt: z.string().nullable().optional(),
+	})
+	.passthrough();
+
+export type CustomerReviewSummary = z.infer<typeof customerReviewSummarySchema>;
+export type CustomerReviewListResponse = z.infer<
+	typeof customerReviewListResponseSchema
+>;
+export type CustomerReviewSubmitInput = z.infer<
+	typeof customerReviewSubmitInputSchema
+>;
+export type CustomerReviewSubmitResponse = z.infer<
+	typeof customerReviewSubmitResponseSchema
+>;
+
+// ── Customer-portal: per-job comments ─────────────────────────────────
+
+export const customerJobCommentSchema = z.object({
+	id: z.string(),
+	authorKind: z.enum(["customer", "staff", "system"]),
+	authorName: z.string().nullable(),
+	body: z.string(),
+	createdAt: z.string(),
+});
+
+export const customerJobCommentsListResponseSchema = z.object({
+	items: z.array(customerJobCommentSchema),
+});
+
+export const customerJobCommentPostInputSchema = z.object({
+	body: z.string().min(1).max(5000),
+});
+
+export type CustomerJobComment = z.infer<typeof customerJobCommentSchema>;
+export type CustomerJobCommentsListResponse = z.infer<
+	typeof customerJobCommentsListResponseSchema
+>;
+export type CustomerJobCommentPostInput = z.infer<
+	typeof customerJobCommentPostInputSchema
+>;
+
+// ── Customer-portal: contact-the-company (front-desk session start) ───
+
+export const customerContactCompanyInputSchema = z.object({
+	message: z.string().min(1).max(8000),
+	subject: z.string().max(200).optional(),
+});
+
+export const customerContactCompanyResponseSchema = z.object({
+	sessionId: z.string(),
+	visitorToken: z.string(),
+	status: z.string(),
+});
+
+export type CustomerContactCompanyInput = z.infer<
+	typeof customerContactCompanyInputSchema
+>;
+export type CustomerContactCompanyResponse = z.infer<
+	typeof customerContactCompanyResponseSchema
+>;
+
+// ── Customer-portal: staff ETA on a job ────────────────────────────────
+
+export const customerJobEtaAssignmentSchema = z.object({
+	displayName: z.string(),
+	role: z.string().nullable(),
+	dispatchStatus: z.string(),
+	lastKnownLocation: z
+		.object({
+			lat: z.number(),
+			lng: z.number(),
+			capturedAt: z.string(),
+		})
+		.nullable(),
+});
+
+export const customerJobEtaResponseSchema = z.object({
+	assignments: z.array(customerJobEtaAssignmentSchema),
+	eta: z
+		.object({
+			seconds: z.number().nullable(),
+			distanceMeters: z.number().nullable(),
+			snapshotAt: z.string(),
+			source: z.literal("dispatch_offer_snapshot"),
+		})
+		.nullable(),
+	liveEtaAvailable: z.boolean(),
+});
+
+export type CustomerJobEtaAssignment = z.infer<
+	typeof customerJobEtaAssignmentSchema
+>;
+export type CustomerJobEtaResponse = z.infer<
+	typeof customerJobEtaResponseSchema
+>;
+
+// ── Customer-portal: job activity feed (events + chat interleaved) ────
+
+export const customerJobActivityEntrySchema = z.discriminatedUnion("kind", [
+	z
+		.object({
+			kind: z.literal("event"),
+			id: z.string(),
+			at: z.string(),
+			event: z.object({
+				eventKind: z.string(),
+				title: z.string(),
+				body: z.string().nullable(),
+				actorName: z.string().nullable(),
+				metadata: z.record(z.string(), z.unknown()).nullable(),
+			}),
+		})
+		.passthrough(),
+	z
+		.object({
+			kind: z.literal("chat"),
+			id: z.string(),
+			at: z.string(),
+			chat: z.object({
+				role: z.string(),
+				content: z.string(),
+				sessionId: z.string(),
+			}),
+		})
+		.passthrough(),
+]);
+
+export const customerJobActivityResponseSchema = z.object({
+	items: z.array(customerJobActivityEntrySchema),
+});
+
+export type CustomerJobActivityEntry = z.infer<
+	typeof customerJobActivityEntrySchema
+>;
+export type CustomerJobActivityResponse = z.infer<
+	typeof customerJobActivityResponseSchema
+>;
+
+// ── Blog programmatic surface (0.9.0) ─────────────────────────────────
+
+export const blogPublicPostSchema = z
+	.object({
+		id: z.string(),
+		orgId: z.string().nullable(),
+		title: z.string(),
+		slug: z.string(),
+		content: z.string(),
+		excerpt: z.string().nullable(),
+		imageUrl: z.string().nullable(),
+		imageUrlDark: z.string().nullable(),
+		muxPlaybackId: z.string().nullable(),
+		muxStatus: z.string().nullable(),
+		accessLevel: z.enum(["public", "followers", "paid"]),
+		downloadAccessLevel: z.enum(["public", "followers", "paid"]),
+		publishedAt: z.string().nullable(),
+		isPinned: z.boolean(),
+		authorName: z.string().nullable(),
+		authorAvatarUrl: z.string().nullable(),
+		tags: z.array(z.string()),
+		likes: z.number(),
+		commentsCount: z.number(),
+		viewCount: z.number(),
+		createdAt: z.string(),
+		updatedAt: z.string(),
+		ctaLabel: z.string().nullable(),
+		ctaHref: z.string().nullable(),
+		ctaDescription: z.string().nullable(),
+	})
+	.passthrough();
+
+export const blogListPostsResponseSchema = z.object({
+	items: z.array(blogPublicPostSchema),
+	nextCursor: z.number().nullable(),
+});
+
+export const blogPostBySlugResponseSchema = z.object({
+	post: blogPublicPostSchema,
+	access: z.enum(["granted", "paywall"]),
+});
+
+export const blogCategorySchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	description: z.string().nullable(),
+});
+export const blogCategoryListResponseSchema = z.object({
+	items: z.array(blogCategorySchema),
+});
+
+export const blogTagListResponseSchema = z.object({
+	items: z.array(z.string()),
+});
+
+export const blogPublicCommentSchema = z.object({
+	id: z.string(),
+	postId: z.string(),
+	parentId: z.string().nullable(),
+	content: z.string(),
+	authorName: z.string().nullable(),
+	authorAvatarUrl: z.string().nullable(),
+	createdAt: z.string(),
+});
+export const blogCommentListResponseSchema = z.object({
+	items: z.array(blogPublicCommentSchema),
+	nextCursor: z.number().nullable(),
+});
+
+export const blogCommentPostInputSchema = z.object({
+	content: z.string().min(1).max(5000),
+	parentId: z.string().uuid().optional(),
+});
+export const blogCommentPostResponseSchema = z.object({
+	comment: z
+		.object({
+			id: z.string(),
+			postId: z.string(),
+			content: z.string(),
+			isApproved: z.boolean(),
+			/** Mirrors the `blog_comment_screening_status` pg enum. */
+			screeningStatus: openEnum(
+				"ok",
+				"flagged",
+				"blocked",
+				"reviewed_ok",
+				"reviewed_blocked",
+			),
+			createdAt: z.string(),
+		})
+		.passthrough(),
+	moderation: z.object({
+		status: z.string(),
+		isApproved: z.boolean(),
+	}),
+});
+
+/** Like state + count returned by GET/POST `blog/posts/:slug/like`. */
+export const blogLikeResponseSchema = z.object({
+	liked: z.boolean(),
+	likesCount: z.number(),
+});
+
+export type BlogPublicPost = z.infer<typeof blogPublicPostSchema>;
+export type BlogListPostsResponse = z.infer<typeof blogListPostsResponseSchema>;
+export type BlogPostBySlugResponse = z.infer<
+	typeof blogPostBySlugResponseSchema
+>;
+export type BlogCategory = z.infer<typeof blogCategorySchema>;
+export type BlogCategoryListResponse = z.infer<
+	typeof blogCategoryListResponseSchema
+>;
+export type BlogTagListResponse = z.infer<typeof blogTagListResponseSchema>;
+export type BlogPublicComment = z.infer<typeof blogPublicCommentSchema>;
+export type BlogCommentListResponse = z.infer<
+	typeof blogCommentListResponseSchema
+>;
+export type BlogCommentPostInput = z.infer<typeof blogCommentPostInputSchema>;
+export type BlogCommentPostResponse = z.infer<
+	typeof blogCommentPostResponseSchema
+>;
+export type BlogLikeResponse = z.infer<typeof blogLikeResponseSchema>;
+
+// ── Storefront programmatic surface (0.9.0) ───────────────────────────
+
+/**
+ * Loose-shape storefront product row. Server-side schema has many
+ * columns; we keep this `.passthrough()` so consumers don't break
+ * when new columns ship and so cross-variant fields (deferred to
+ * 0.10) flow through untyped today.
+ */
+/** Resolved category attached to a product row/card (mirrors a storefront category). */
+export const storefrontProductCategorySchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+});
+
+export const storefrontProductRowSchema = z
+	.object({
+		id: z.string(),
+		orgId: z.string(),
+		name: z.string(),
+		isLive: z.boolean(),
+		categoryId: z.string().nullable().optional(),
+		/** Resolved category (name/description), when the product is categorized. */
+		category: storefrontProductCategorySchema.nullable().optional(),
+		images: z.array(z.string()).nullable().optional(),
+		createdAt: z.string(),
+	})
+	.passthrough();
+
+export const storefrontListProductsResponseSchema = z.object({
+	items: z.array(storefrontProductRowSchema),
+	nextCursor: z.number().nullable(),
+});
+
+export const storefrontProductDetailSchema = storefrontProductRowSchema.and(
+	z.object({
+		variants: z.array(z.record(z.string(), z.unknown())),
+		productImages: z.array(z.record(z.string(), z.unknown())),
+		variantImages: z.array(z.record(z.string(), z.unknown())),
+		// Cross-variant option groups (Size/Color/…) — the combinatorial picker.
+		crossVariantTitles: z.array(z.record(z.string(), z.unknown())),
+		crossVariants: z.array(z.record(z.string(), z.unknown())),
+		// Raw specifications jsonb (shape is org-defined) — rides on the product
+		// row; surfaced here for typing.
+		specifications: z.unknown().optional(),
+	}),
+);
+
+/** A single approved product review. Lenient — server columns evolve. */
+export const storefrontReviewSchema = z
+	.object({
+		id: z.string(),
+		productId: z.string(),
+		rating: z.number(),
+		title: z.string().nullable().optional(),
+		body: z.string().nullable().optional(),
+		content: z.string().nullable().optional(),
+		reviewerName: z.string().nullable().optional(),
+		createdAt: z.string().nullable().optional(),
+	})
+	.passthrough();
+
+export const storefrontProductReviewsResponseSchema = z.object({
+	items: z.array(storefrontReviewSchema),
+	nextCursor: z.number().nullable(),
+	avgRating: z.number(),
+	totalCount: z.number(),
+});
+
+/** A "you may also like" recommendation. */
+export const storefrontRelatedProductSchema = z
+	.object({
+		id: z.string(),
+		name: z.string(),
+		description: z.string().nullable(),
+		categoryId: z.string().nullable(),
+		coverImageUrl: z.string().nullable(),
+		minPriceDollars: z.number().nullable(),
+		reasons: z.array(z.string()).optional(),
+	})
+	.passthrough();
+
+export const storefrontRelatedProductsResponseSchema = z.object({
+	items: z.array(storefrontRelatedProductSchema),
+});
+
+/** A companion/exclusive cross-sell addon for the "complete your X" rail. */
+export const storefrontAddonSchema = z
+	.object({
+		id: z.string(),
+		addonProductId: z.string(),
+		addonName: z.string(),
+		addonDescription: z.string().nullable(),
+		kind: z.string(),
+		groupLabel: z.string().nullable(),
+		priceCents: z.number().nullable(),
+		originalPriceCents: z.number().nullable(),
+		imageUrl: z.string().nullable(),
+		variants: z.array(z.record(z.string(), z.unknown())),
+		crossVariantTitles: z.array(z.record(z.string(), z.unknown())),
+	})
+	.passthrough();
+
+export const storefrontAddonsResponseSchema = z.object({
+	items: z.array(storefrontAddonSchema),
+});
+
+export type StorefrontAddon = z.infer<typeof storefrontAddonSchema>;
+export type StorefrontAddonsResponse = z.infer<
+	typeof storefrontAddonsResponseSchema
+>;
+
+export type StorefrontReview = z.infer<typeof storefrontReviewSchema>;
+export type StorefrontProductReviewsResponse = z.infer<
+	typeof storefrontProductReviewsResponseSchema
+>;
+export type StorefrontRelatedProduct = z.infer<
+	typeof storefrontRelatedProductSchema
+>;
+export type StorefrontRelatedProductsResponse = z.infer<
+	typeof storefrontRelatedProductsResponseSchema
+>;
+
+export type StorefrontProductRow = z.infer<typeof storefrontProductRowSchema>;
+export type StorefrontListProductsResponse = z.infer<
+	typeof storefrontListProductsResponseSchema
+>;
+export type StorefrontProductDetail = z.infer<
+	typeof storefrontProductDetailSchema
+>;
+
+/**
+ * Storefront sort options for the listing grid (mirrors the platform shop demo).
+ */
+export const storefrontSortValues = [
+	"featured",
+	"newest",
+	"price-asc",
+	"price-desc",
+	"rating-desc",
+] as const;
+export type StorefrontSort = (typeof storefrontSortValues)[number];
+
+/** Enriched grid card — price, ratings, badges, cover image — for the
+ *  filterable listing page (`listProductsWithMeta`). */
+export const storefrontProductCardSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+	categoryId: z.string().nullable(),
+	/** Resolved category (name/description), when the product is categorized. */
+	category: storefrontProductCategorySchema.nullable().optional(),
+	coverImage: z.string().nullable(),
+	cheapestPriceCents: z.number().nullable(),
+	comparePriceCents: z.number().nullable(),
+	isOnSale: z.boolean(),
+	isLowStock: z.boolean(),
+	hasMultipleVariants: z.boolean(),
+	avgRating: z.number(),
+	reviewCount: z.number(),
+	isBestSeller: z.boolean(),
+	isNew: z.boolean(),
+});
+
+export const storefrontProductsWithMetaResponseSchema = z.object({
+	items: z.array(storefrontProductCardSchema),
+	categoryCounts: z.array(
+		z.object({ categoryId: z.string(), count: z.number() }),
+	),
+	priceRange: z.object({ minDollars: z.number(), maxDollars: z.number() }),
+});
+
+export const storefrontCategorySchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+});
+
+export const storefrontCategoriesResponseSchema = z.object({
+	items: z.array(storefrontCategorySchema),
+});
+
+export type StorefrontProductCard = z.infer<typeof storefrontProductCardSchema>;
+export type StorefrontProductsWithMetaResponse = z.infer<
+	typeof storefrontProductsWithMetaResponseSchema
+>;
+export type StorefrontCategory = z.infer<typeof storefrontCategorySchema>;
+export type StorefrontCategoriesResponse = z.infer<
+	typeof storefrontCategoriesResponseSchema
+>;
+
+// ── Cart programmatic surface (0.9.0) ─────────────────────────────────
+
+export const cartItemSnapshotSchema = z.object({
+	id: z.string(),
+	productId: z.string(),
+	variantId: z.string().nullable(),
+	quantity: z.number().int(),
+	options: z.record(z.string(), z.unknown()).nullable(),
+	addedAt: z.string(),
+	updatedAt: z.string(),
+	productName: z.string().nullable(),
+	productImage: z.string().nullable(),
+	variantTitle: z.string().nullable(),
+	unitPrice: z.number(),
+	currency: z.string(),
+	subtotal: z.number(),
+});
+
+export const cartSnapshotSchema = z.object({
+	id: z.string(),
+	orgId: z.string(),
+	visitorToken: z.string().nullable(),
+	customerUserId: z.string().nullable(),
+	couponCode: z.string().nullable(),
+	currency: z.string(),
+	items: z.array(cartItemSnapshotSchema),
+	subtotal: z.number(),
+	itemCount: z.number(),
+	lastActivityAt: z.string(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+});
+
+export const cartAddItemInputSchema = z.object({
+	productId: z.string().uuid(),
+	variantId: z.string().uuid().optional(),
+	quantity: z.number().int().min(1).max(999).default(1),
+	options: z.record(z.string(), z.unknown()).nullable().optional(),
+});
+
+export const cartUpdateItemInputSchema = z.object({
+	quantity: z.number().int().min(0).max(999),
+});
+
+export const cartCouponInputSchema = z.object({
+	code: z.string().min(1).max(80),
+});
+
+export type CartItemSnapshot = z.infer<typeof cartItemSnapshotSchema>;
+export type CartSnapshot = z.infer<typeof cartSnapshotSchema>;
+export type CartAddItemInput = z.infer<typeof cartAddItemInputSchema>;
+export type CartUpdateItemInput = z.infer<typeof cartUpdateItemInputSchema>;
+export type CartCouponInput = z.infer<typeof cartCouponInputSchema>;
+
+// ── Shipping (Batch shipping, 0.9.0) ──────────────────────────────────
+
+export const shippingDeliveryAddressSchema = z.object({
+	name: z.string().min(1).max(120),
+	street1: z.string().min(1).max(200),
+	street2: z.string().max(200).optional(),
+	city: z.string().min(1).max(120),
+	state: z.string().min(1).max(80),
+	postalCode: z.string().min(1).max(20),
+	country: z.string().length(2),
+	phone: z.string().max(40).optional(),
+	email: z.string().email().optional(),
+});
+export type ShippingDeliveryAddress = z.infer<
+	typeof shippingDeliveryAddressSchema
+>;
+
+export const shippingRatesInputSchema = z.object({
+	deliveryAddress: shippingDeliveryAddressSchema,
+});
+export type ShippingRatesInput = z.infer<typeof shippingRatesInputSchema>;
+
+export const shippingOptionBreakdownSchema = z.object({
+	originId: z.string().nullable(),
+	shippoShipmentId: z.string(),
+	shippoRateId: z.string(),
+	amountCents: z.number().int().nonnegative(),
+	parcelSummary: z.string(),
+});
+
+export const shippingOptionSchema = z.object({
+	id: z.string(),
+	displayName: z.string(),
+	carrierName: z.string(),
+	serviceToken: z.string(),
+	totalCents: z.number().int().nonnegative(),
+	currency: z.string().min(3),
+	estimatedDays: z.number().int().nullable(),
+	durationTerms: z.string().nullable(),
+	breakdown: z.array(shippingOptionBreakdownSchema),
+});
+export type ShippingOption = z.infer<typeof shippingOptionSchema>;
+
+export const shippingRatesResponseSchema = z.object({
+	options: z.array(shippingOptionSchema),
+	requiresShipping: z.boolean(),
+});
+export type ShippingRatesResponse = z.infer<typeof shippingRatesResponseSchema>;
+
+export const shippingTrackResponseSchema = z.object({
+	shipmentId: z.string(),
+	orderId: z.string(),
+	carrier: z.string().nullable(),
+	trackingNumber: z.string().nullable(),
+	trackingUrl: z.string().nullable(),
+	labelUrl: z.string().nullable(),
+	/** Mirrors the `order_shipment_status` pg enum. */
+	status: openEnum(
+		"pending",
+		"label_created",
+		"in_transit",
+		"delivered",
+		"returned",
+	),
+	estimatedDelivery: z.string().nullable(),
+	shippedAt: z.string().nullable(),
+	deliveredAt: z.string().nullable(),
+	serviceName: z.string().nullable(),
+	rateAmountCents: z.number().int().nullable(),
+	currency: z.string().nullable(),
+	statusHistory: z.unknown(),
+	liveStatus: z
+		.object({
+			status: z.string(),
+			status_details: z.string().optional(),
+			status_date: z.string().optional(),
+			location: z
+				.object({
+					city: z.string().optional(),
+					state: z.string().optional(),
+					zip: z.string().optional(),
+					country: z.string().optional(),
+				})
+				.nullable()
+				.optional(),
+		})
+		.nullable(),
+});
+export type ShippingTrackResponse = z.infer<typeof shippingTrackResponseSchema>;
+
+/**
+ * The org's storefront-facing shipping config. Sanitized: no API keys/secrets,
+ * and only a coarse city/state/country "ships from" (never the precise origin
+ * street).
+ */
+export const shippingSettingsResponseSchema = z.object({
+	enabled: z.boolean(),
+	shipsFrom: z
+		.object({
+			city: z.string().nullable(),
+			state: z.string().nullable(),
+			country: z.string().nullable(),
+		})
+		.nullable(),
+	/** ISO-3166-1 alpha-2 list. null = ships anywhere; [] = ships nowhere. */
+	allowedDestinationCountries: z.array(z.string()).nullable(),
+	/** DDU = customer pays duties, DDP = seller pays, FCA = free carrier. */
+	defaultIncoterm: openEnum("DDU", "DDP", "FCA"),
+	preferredCarriers: z.array(z.string()).nullable(),
+});
+export type ShippingSettingsResponse = z.infer<
+	typeof shippingSettingsResponseSchema
+>;
+
+// ── Customer notification preferences (Batch shipping, 0.9.0) ─────────
+// Distinct from the BIAB-user notification prefs in this file —
+// these are per-customer-per-org preferences exposed via the SDK so
+// the *consumer's* site can render a preferences UI for its signed-
+// in shoppers (in-app / email / SMS / outbound webhook).
+
+export const customerNotificationEventMapSchema = z.record(
+	z.string(),
+	z.boolean(),
+);
+
+export const customerNotificationPreferencesResponseSchema = z.object({
+	exists: z.boolean(),
+	inAppEvents: customerNotificationEventMapSchema,
+	emailEvents: customerNotificationEventMapSchema,
+	smsEvents: customerNotificationEventMapSchema,
+	webhookEvents: customerNotificationEventMapSchema,
+	emailAddress: z.string().nullable(),
+	phoneNumber: z.string().nullable(),
+	webhookUrl: z.string().nullable(),
+	webhookHasSigningSecret: z.boolean(),
+	emailVerified: z.boolean(),
+	phoneVerified: z.boolean(),
+});
+export type CustomerNotificationPreferencesResponse = z.infer<
+	typeof customerNotificationPreferencesResponseSchema
+>;
+
+export const customerNotificationPreferencesUpdateInputSchema = z.object({
+	inAppEvents: customerNotificationEventMapSchema.optional(),
+	emailEvents: customerNotificationEventMapSchema.optional(),
+	smsEvents: customerNotificationEventMapSchema.optional(),
+	webhookEvents: customerNotificationEventMapSchema.optional(),
+	emailAddress: z.string().email().nullable().optional(),
+	phoneNumber: z.string().min(7).max(40).nullable().optional(),
+	webhookUrl: z.string().url().nullable().optional(),
+	webhookSigningSecret: z.string().min(16).max(128).nullable().optional(),
+});
+export type CustomerNotificationPreferencesUpdateInput = z.infer<
+	typeof customerNotificationPreferencesUpdateInputSchema
+>;
+
+export const customerNotificationPreferencesUpdateResponseSchema = z.object({
+	ok: z.literal(true),
+});
+export type CustomerNotificationPreferencesUpdateResponse = z.infer<
+	typeof customerNotificationPreferencesUpdateResponseSchema
+>;
+
+// ── Customer destination verification (Batch shipping, 0.9.0) ─────────
+
+export const startVerificationInputSchema = z.object({
+	kind: z.enum(["email", "phone"]),
+	destination: z.string().min(3).max(200),
+});
+export type StartVerificationInput = z.infer<
+	typeof startVerificationInputSchema
+>;
+
+export const startVerificationResponseSchema = z.object({
+	ok: z.literal(true),
+	message: z.string(),
+	flow: z.enum(["link", "otp"]),
+});
+export type StartVerificationResponse = z.infer<
+	typeof startVerificationResponseSchema
+>;
+
+export const confirmVerificationInputSchema = z.object({
+	token: z.string().min(4).max(128),
+});
+export type ConfirmVerificationInput = z.infer<
+	typeof confirmVerificationInputSchema
+>;
+
+export const confirmVerificationResponseSchema = z.object({
+	ok: z.literal(true),
+	verifiedKind: z.enum(["email", "phone"]),
+	destination: z.string(),
+});
+export type ConfirmVerificationResponse = z.infer<
+	typeof confirmVerificationResponseSchema
+>;
+
+// ── Address search + verify (0.9.0) ───────────────────────────────────
+// Field shape mirrors Resources/addressParser/src/types/address.ts so
+// the working reference React components copy in cleanly.
+
+export const addressSearchInputSchema = z.object({
+	query: z.string().min(1).max(200),
+});
+export type AddressSearchInput = z.infer<typeof addressSearchInputSchema>;
+
+export const addressPlacePredictionSchema = z.object({
+	place_id: z.string(),
+	structured_formatting: z.object({
+		main_text: z.string(),
+		secondary_text: z.string(),
+	}),
+});
+export type AddressPlacePrediction = z.infer<
+	typeof addressPlacePredictionSchema
+>;
+
+export const addressSearchResponseSchema = z.union([
+	z.object({
+		enabled: z.literal(true),
+		predictions: z.array(addressPlacePredictionSchema),
+	}),
+	z.object({
+		enabled: z.literal(false),
+		reason: z.string(),
+		predictions: z.array(addressPlacePredictionSchema),
+	}),
+]);
+export type AddressSearchResponse = z.infer<typeof addressSearchResponseSchema>;
+
+/**
+ * Structured address as Google returns it. Pipe through
+ * `googleAddressToFormValues` (exported from the SDK helpers) to
+ * fill a form whose fields match the reference `AddressFormValues`
+ * shape.
+ */
+export const googleAddressSchema = z.object({
+	street_number: z.string(),
+	route: z.string(),
+	subpremise: z.string().optional(),
+	locality: z.string(),
+	administrative_area_level_1: z.string(),
+	postal_code: z.string(),
+	country: z.string(),
+});
+export type GoogleAddress = z.infer<typeof googleAddressSchema>;
+
+export const addressDetailsResponseSchema = z.union([
+	z.object({ enabled: z.literal(true), address: googleAddressSchema }),
+	z.object({
+		enabled: z.literal(false),
+		reason: z.string(),
+		address: z.null(),
+	}),
+]);
+export type AddressDetailsResponse = z.infer<
+	typeof addressDetailsResponseSchema
+>;
+
+export const addressFormValuesSchema = z.object({
+	address_ln1: z.string().min(1).max(200),
+	address_ln2: z.string().max(200).optional(),
+	city: z.string().min(1).max(120),
+	state: z.string().min(1).max(80),
+	zip: z.string().min(1).max(20),
+	country: z.string().min(2).max(80),
+});
+export type AddressFormValues = z.infer<typeof addressFormValuesSchema>;
+
+export const addressVerifyResponseSchema = z.object({
+	isVerified: z.boolean(),
+	googleAddress: z.string().nullable(),
+});
+export type AddressVerifyResponse = z.infer<typeof addressVerifyResponseSchema>;
+
+// ── Subscriptions (consumer-facing) ───────────────────────────────────
+
+export const subscriptionOfferingSchema = z.object({
+	id: z.string().uuid(),
+	name: z.string(),
+	description: z.string().nullable(),
+	imageUrl: z.string().nullable(),
+	amountCents: z.number().int(),
+	interval: z.enum(["day", "week", "month", "year"]),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+});
+export type SubscriptionOffering = z.infer<typeof subscriptionOfferingSchema>;
+
+export const subscriptionOfferingsListResponseSchema = z.object({
+	items: z.array(subscriptionOfferingSchema),
+});
+export type SubscriptionOfferingsListResponse = z.infer<
+	typeof subscriptionOfferingsListResponseSchema
+>;
+
+export const subscriptionCheckoutInputSchema = z
+	.object({
+		customerEmail: z.string().email().optional(),
+		successUrl: z.string().url().optional(),
+		cancelUrl: z.string().url().optional(),
+	})
+	.optional();
+export type SubscriptionCheckoutInput = z.infer<
+	typeof subscriptionCheckoutInputSchema
+>;
+
+export const subscriptionCheckoutResponseSchema = z.object({
+	sessionId: z.string(),
+	stripeUrl: z.string().url(),
+	amountCents: z.number().int(),
+	currency: z.string(),
+	/** Mirrors the `subscription_interval` pg enum. */
+	interval: openEnum("day", "week", "month", "year"),
+});
+export type SubscriptionCheckoutResponse = z.infer<
+	typeof subscriptionCheckoutResponseSchema
+>;
+
+// ── Coupons (Batch LL, 0.9.0) ─────────────────────────────────────────
+
+export const couponValidateInputSchema = z.object({
+	code: z.string().min(1).max(80),
+});
+export type CouponValidateInput = z.infer<typeof couponValidateInputSchema>;
+
+export const couponValidateValidSchema = z.object({
+	valid: z.literal(true),
+	code: z.string(),
+	discountType: z.enum(["percent", "amount"]),
+	percentOff: z.number().nullable(),
+	amountOffCents: z.number().int().nullable(),
+	currency: z.string().nullable(),
+	duration: z.enum(["once", "forever", "repeating"]),
+	durationInMonths: z.number().int().nullable(),
+	expiresAt: z.string().nullable(),
+});
+export type CouponValidateValid = z.infer<typeof couponValidateValidSchema>;
+
+export const couponValidateInvalidSchema = z.object({
+	valid: z.literal(false),
+	reason: z.enum([
+		"unknown_code",
+		"expired",
+		"inactive",
+		"no_stripe_account",
+		"lookup_failed",
+	]),
+	message: z.string(),
+});
+export type CouponValidateInvalid = z.infer<typeof couponValidateInvalidSchema>;
+
+export const couponValidateResponseSchema = z.union([
+	couponValidateValidSchema,
+	couponValidateInvalidSchema,
+]);
+export type CouponValidateResponse = z.infer<
+	typeof couponValidateResponseSchema
+>;
+
+// ── Tenant auth (per-org hosted sign-in / sign-up / sign-out) ─────────
+
+export const tenantAuthIntentSchema = z.enum(["sign-in", "sign-up"]);
+
+export const tenantAuthStartInputSchema = z.object({
+	intent: tenantAuthIntentSchema,
+	/** Where the tenant's site should send the user after auth completes. */
+	returnTo: z.string().url().optional(),
+	/** Pre-fills the email field on the platform-hosted page. */
+	loginHint: z.string().email().optional(),
+	/**
+	 * The tenant's installed callback URL — must match what was registered with
+	 * the platform. Required because the tenant lives on its own domain.
+	 */
+	redirectUri: z.string().url(),
+});
+
+export const tenantAuthStartResponseSchema = z.object({
+	url: z.string().url(),
+});
+
+export const tenantAuthExchangeInputSchema = z.object({
+	code: z.string().min(1),
+	/** Sealed OAuth `state` returned on the callback URL — contains the PKCE verifier for the hosted auth flow. */
+	state: z.string().min(1),
+	/** The same redirectUri used when starting; the platform validates this matches. */
+	redirectUri: z.string().url(),
+});
+
+export const tenantAuthUserSchema = z.object({
+	id: z.string(),
+	email: z.string().email().nullable(),
+	firstName: z.string().nullable(),
+	lastName: z.string().nullable(),
+});
+
+export const tenantAuthSessionSchema = z.object({
+	user: tenantAuthUserSchema,
+	organizationId: z.string(),
+	role: z.string().nullable(),
+	/** Opaque token the tenant cookie should store; pass back as Bearer for `/me`. */
+	sessionToken: z.string(),
+	expiresAt: timestampSchema,
+});
+
+export const tenantAuthExchangeResponseSchema = tenantAuthSessionSchema;
+
+export const tenantAuthMeResponseSchema = z
+	.object({
+		user: tenantAuthUserSchema,
+		organizationId: z.string(),
+		role: z.string().nullable(),
+	})
+	.nullable();
+
+export const tenantAuthSignOutResponseSchema = z.object({
+	ok: z.literal(true),
+});
+
+/**
+ * Programmatic password-reset request. Always succeeds from the caller's
+ * perspective — the server returns `ok: true` regardless of whether an
+ * account matched, to avoid leaking which emails are registered. The
+ * actual reset link is mailed out-of-band when a match exists.
+ */
+export const tenantAuthPasswordResetInputSchema = z.object({
+	email: z.string().email().max(320),
+	/**
+	 * Optional override for the redirect after the user sets a new password.
+	 * Falls back to the org's default sign-in landing page server-side.
+	 */
+	returnTo: z.string().url().max(2048).optional(),
+});
+
+export const tenantAuthPasswordResetResponseSchema = z.object({
+	ok: z.literal(true),
+});
+
+export type TenantAuthIntent = z.infer<typeof tenantAuthIntentSchema>;
+export type TenantAuthStartInput = z.infer<typeof tenantAuthStartInputSchema>;
+export type TenantAuthStartResponse = z.infer<
+	typeof tenantAuthStartResponseSchema
+>;
+export type TenantAuthExchangeInput = z.infer<
+	typeof tenantAuthExchangeInputSchema
+>;
+export type TenantAuthExchangeResponse = z.infer<
+	typeof tenantAuthExchangeResponseSchema
+>;
+export type TenantAuthSession = z.infer<typeof tenantAuthSessionSchema>;
+export type TenantAuthUser = z.infer<typeof tenantAuthUserSchema>;
+export type TenantAuthMeResponse = z.infer<typeof tenantAuthMeResponseSchema>;
+export type TenantAuthSignOutResponse = z.infer<
+	typeof tenantAuthSignOutResponseSchema
+>;
+export type TenantAuthPasswordResetInput = z.infer<
+	typeof tenantAuthPasswordResetInputSchema
+>;
+export type TenantAuthPasswordResetResponse = z.infer<
+	typeof tenantAuthPasswordResetResponseSchema
+>;
+
+// ── Schema-driven marketing flow (Phase 2 — V7 dashboard) ────────────────
+//
+// The bundle endpoint is the live-site read path. Each section is tagged
+// `{ ok: true, data, source } | { ok: false, error }` so one malformed
+// row degrades to empty in the consumer's renderer instead of crashing
+// the page. `source` records whether the value came from the requested
+// locale, fell back to EN, or was deep-merged from both.
+
+export const siteMarketingSectionEntrySchema = z.discriminatedUnion("ok", [
+	z.object({
+		ok: z.literal(true),
+		sectionKey: z.string(),
+		data: z.unknown(),
+		source: z.enum(["locale", "en-fallback", "merged"]),
+		updatedAt: timestampSchema,
+	}),
+	z.object({
+		ok: z.literal(false),
+		sectionKey: z.string(),
+		error: z.string(),
+	}),
+]);
+
+export const siteMarketingSeoDataSchema = z.object({
+	seoTitle: z.string().nullable(),
+	seoDescription: z.string().nullable(),
+	canonicalUrl: z.string().nullable(),
+	noIndex: z.boolean(),
+	ogTitle: z.string().nullable(),
+	ogDescription: z.string().nullable(),
+	ogImageUrl: z.string().nullable(),
+	twitterCard: z.enum(["summary", "summary_large_image", "app", "player"]),
+	keywords: z.array(z.string()),
+	jsonldNodes: z.array(z.unknown()),
+	hreflang: z.record(z.string()),
+});
+
+// ──────────────────────────────────────────────────────────────────────
+// Bundle: brand / company / gallery / reviews surfaces
+//
+// Added in SDK 0.8.4. Prior versions zod-stripped these keys at the
+// response boundary even though the BIAB server already shipped them
+// (the underlying `.passthrough()` in this file is on a chatbot
+// schema, NOT on the bundle response). Consumers that need the
+// stripped data on older SDK versions can raw-fetch
+// /sites/{id}/marketing/bundle directly — same auth, same caching —
+// until they bump.
+//
+// The new keys are all optional + null-able to match the
+// server's opt-in posture: company.profile is null when the org
+// hasn't filled out /settings/company-profile; gallery is null when
+// no public-flagged media exists; reviews is null when the org
+// hasn't set their Google Place ID. Consumers branch on null and
+// either render an empty section or hide it.
+
+const brandTokensSchema = z.object({
+	logoUrl: z.string().nullable(),
+	faviconUrl: z.string().nullable(),
+});
+
+export const companyAddressSchema = z
+	.object({
+		addressLine1: z.string().nullable().optional(),
+		addressLine2: z.string().nullable().optional(),
+		city: z.string().nullable().optional(),
+		state: z.string().nullable().optional(),
+		zip: z.string().nullable().optional(),
+		country: z.string().nullable().optional(),
+	})
+	.nullable();
+
+export const companyLocationSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	isPrimary: z.boolean(),
+	isPublic: z.boolean(),
+	type: z
+		.enum([
+			"office",
+			"store",
+			"showroom",
+			"warehouse",
+			"service_center",
+			"other",
+		])
+		.optional(),
+	businessType: z.string().nullable().optional(),
+	address: companyAddressSchema.unwrap(),
+	phone: z.string().nullable().optional(),
+	webPhone: z.string().nullable().optional(),
+	supportEmail: z.string().nullable().optional(),
+	website: z.string().nullable().optional(),
+	googlePlaceId: z.string().nullable().optional(),
+	latitude: z.number().nullable().optional(),
+	longitude: z.number().nullable().optional(),
+	timezone: z.string().nullable().optional(),
+	operationHours: z.record(z.string(), z.unknown()).nullable().optional(),
+	serviceAreas: z.record(z.string(), z.unknown()).nullable().optional(),
+});
+
+/**
+ * Loose-typed CompanyProfileRow. The server-side shape is fully
+ * typed; we keep this looser at the SDK boundary so adding a column
+ * on the BIAB side doesn't break older SDK consumers.
+ */
+const companyProfileRowSchema = z
+	.object({
+		id: z.string(),
+		orgId: z.string(),
+		website: z.string().nullable(),
+		phone: z.string().nullable(),
+		webPhone: z.string().nullable(),
+		supportEmail: z.string().nullable(),
+		aboutShort: z.string().nullable(),
+		aboutLongHtml: z.string().nullable(),
+		shareImageUrl: z.string().nullable(),
+		googlePlaceId: z.string().nullable().optional(),
+		address: companyAddressSchema,
+		locations: z.array(companyLocationSchema).nullable().optional(),
+		operationHours: z.record(z.string(), z.unknown()).nullable(),
+		serviceAreas: z.record(z.string(), z.unknown()).nullable(),
+		paymentOptions: z.record(z.string(), z.unknown()).nullable(),
+		warranties: z.record(z.string(), z.unknown()).nullable(),
+		socials: z.record(z.string(), z.unknown()).nullable(),
+	})
+	.passthrough()
+	.nullable();
+
+const bundleCompanySchema = z.object({
+	profile: companyProfileRowSchema,
+	jsonLd: z.record(z.string(), z.unknown()),
+	locationJsonLd: z.array(z.record(z.string(), z.unknown())).optional(),
+	shareMetadata: z.object({
+		title: z.string(),
+		description: z.string().nullable(),
+		imageUrl: z.string().nullable(),
+		siteName: z.string(),
+	}),
+});
+
+const bundleGalleryItemSchema = z.object({
+	id: z.string(),
+	type: z.enum(["image", "video"]),
+	src: z.string(),
+	width: z.number().nullable(),
+	height: z.number().nullable(),
+	blurDataURL: z.string().nullable(),
+	alt: z.string().nullable(),
+	title: z.string().nullable(),
+	category: z.string().nullable(),
+	jobId: z.string().nullable(),
+	jobName: z.string().nullable(),
+	takenAt: z.string().nullable(),
+	location: z.string().nullable(),
+	system: z.string().nullable(),
+	year: z.number().nullable(),
+	aboutHtml: z.string().nullable(),
+});
+
+const bundleGallerySchema = z
+	.object({
+		items: z.array(bundleGalleryItemSchema),
+		totalCount: z.number(),
+	})
+	.nullable();
+
+const bundleReviewSchema = z.object({
+	reviewee: z.string(),
+	rating: z.number(),
+	image: z.string().nullable(),
+	description: z.string(),
+	date: z.string(),
+	// Reviewer-attached gallery photos (URLs). Optional for back-compat with
+	// bundles served by pre-photo servers; empty/absent when the review has none.
+	photos: z.array(z.string()).optional(),
+	// Widened from the 0.9.x `"Google"` literal: reviews now come from the
+	// org's unified review store (Google + Yelp + manual + CSV), so the
+	// platform can be any of those. Consumers should render this as a label.
+	platform: z.string(),
+});
+
+/** Per-rating histogram bucket (e.g. `{ rating: 5, count: 182 }`). */
+const bundleReviewCountSchema = z.object({
+	rating: z.number(),
+	count: z.number(),
+});
+
+const bundleReviewsSchema = z
+	.object({
+		enabled: z.literal(true),
+		// `org_external_reviews` is the canonical store; `google_places` is the
+		// legacy Place-ID cache, kept as a fallback. Widened from the 0.9.x
+		// `"google_places"` literal.
+		source: z.enum(["org_external_reviews", "google_places"]),
+		// Null when the payload didn't originate from a Place-ID source.
+		placeId: z.string().nullable(),
+		// Average + count are computed over ALL of the org's reviews, not just
+		// the `items` page below.
+		rating: z.number().nullable(),
+		totalCount: z.number().nullable(),
+		// Per-rating distribution over ALL reviews (newest 5→1), so the consumer
+		// renders the histogram without holding every review client-side.
+		// Optional for back-compat with bundles served by pre-0.9.4 servers.
+		counts: z.array(bundleReviewCountSchema).optional(),
+		// Only the first `reviewsLimit` reviews (newest-first). The rest are
+		// fetched lazily via `client.reviews.list({ offset })`.
+		items: z.array(bundleReviewSchema),
+		// items.length — paired with `totalCount` so the consumer knows whether
+		// more pages exist. Optional for back-compat.
+		returnedCount: z.number().optional(),
+		cachedAt: z.string(),
+	})
+	.nullable();
+
+// ── Reviews wall: paginated public reviews ────────────────────────────
+// Backs `client.reviews.list({ limit, offset, source })` → the key-scoped
+// GET /reviews route. The marketing bundle ships the first page + the
+// aggregate; this endpoint fetches deeper pages on demand (View All / scroll).
+
+export const reviewWallItemSchema = z.object({
+	id: z.string(),
+	source: z.enum(["google", "yelp", "housecall_pro", "other"]),
+	rating: z.number(),
+	text: z.string(),
+	reviewUrl: z.string().nullable(),
+	reviewerName: z.string(),
+	reviewerImageUrl: z.string().nullable(),
+	/** Reviewer-attached gallery photos (URLs); optional for back-compat,
+	 *  empty/absent when the review has no media. */
+	photos: z.array(z.string()).optional(),
+	/** ISO 8601 timestamp of the original review. */
+	timeCreated: z.string(),
+	verified: z.boolean(),
+});
+
+export const reviewWallListResponseSchema = z.object({
+	items: z.array(reviewWallItemSchema),
+	/** Total reviews matching the (optional) source filter — for "N reviews". */
+	totalCount: z.number(),
+	/** Offset to pass back for the next page, or null when the list is exhausted. */
+	nextOffset: z.number().nullable(),
+});
+
+export type ReviewWallItem = z.infer<typeof reviewWallItemSchema>;
+export type ReviewWallListResponse = z.infer<
+	typeof reviewWallListResponseSchema
+>;
+
+/**
+ * Org-owned marketing-page banner (announcement strip / marquee).
+ * Mirrors the platform-banner shape so consumer storefronts can
+ * render a near-identical UI to BIAB's own marketing banner.
+ * `null` when the org hasn't enabled one or has no visible messages.
+ */
+const bundleBannerMessageSchema = z
+	.object({
+		id: z.string(),
+		enabled: z.boolean(),
+		text: z.string(),
+		marqueeLines: z.array(z.string()).optional(),
+		linkUrl: z.string(),
+		buttonText: z.string(),
+		openInNewTab: z.boolean(),
+		linkStyle: z.enum(["link", "button"]).optional(),
+		urgent: z.boolean().optional(),
+		appearance: z.enum(["always", "once", "until_dismiss", "every"]),
+		everyIntervalHours: z.number().optional(),
+		scheduleActive: z.boolean().optional(),
+		displayFromUtc: z.string().nullable().optional(),
+		displayUntilUtc: z.string().nullable().optional(),
+	})
+	.passthrough();
+
+const bundleBannerSchema = z
+	.object({
+		enabled: z.boolean(),
+		hiddenOnHome: z.boolean(),
+		messages: z.array(bundleBannerMessageSchema),
+	})
+	.passthrough()
+	.nullable();
+
+export type BundleBannerMessage = z.infer<typeof bundleBannerMessageSchema>;
+export type BundleBanner = z.infer<typeof bundleBannerSchema>;
+
+/**
+ * Org Updates feed — cached Google Business Profile "Posts" (the Updates tab):
+ * a blurb + image(s) + deep link, optionally with an offer/event window. Lets a
+ * consumer storefront render a "News"/"Updates" feed from the bundle without a
+ * second API call. `null` when the org has none.
+ */
+const bundleUpdateItemSchema = z
+	.object({
+		id: z.string(),
+		kind: z.string().nullable(),
+		title: z.string().nullable(),
+		body: z.string(),
+		link: z.string().nullable(),
+		imageUrl: z.string().nullable(),
+		images: z.array(z.string()),
+		postedAt: z.string().nullable(),
+		startsAt: z.string().nullable(),
+		endsAt: z.string().nullable(),
+	})
+	.passthrough();
+
+const bundleUpdatesSchema = z
+	.object({
+		items: z.array(bundleUpdateItemSchema),
+	})
+	.passthrough()
+	.nullable();
+
+export type BundleUpdateItem = z.infer<typeof bundleUpdateItemSchema>;
+export type BundleUpdates = z.infer<typeof bundleUpdatesSchema>;
+
+export const getMarketingPageBundleResponseSchema = z
+	.object({
+		pageKey: z.string(),
+		locale: z.string(),
+		sections: z.record(z.string(), siteMarketingSectionEntrySchema),
+		availableLocales: z.array(z.string()),
+		seo: siteMarketingSeoDataSchema,
+		// New in 0.8.4:
+		brand: brandTokensSchema.optional(),
+		company: bundleCompanySchema.optional(),
+		gallery: bundleGallerySchema.optional(),
+		reviews: bundleReviewsSchema.optional(),
+		// New in 0.8.9:
+		banner: bundleBannerSchema.optional(),
+		// New in 0.9.6:
+		updates: bundleUpdatesSchema.optional(),
+	})
+	// `.passthrough()` at the top level so any future BIAB-side
+	// addition (e.g. bundle.events, bundle.faq, etc.) flows through
+	// to consumers without an SDK release — the lesson from the
+	// brand/company/gallery/reviews oversight on this version.
+	.passthrough();
+
+export const marketingSchemaSlotRowSchema = z.object({
+	slot: z.enum(["draft", "published"]),
+	schema: z.record(z.string(), z.unknown()),
+	checksum: z.string().length(64),
+	version: z.number().int().positive(),
+	updatedAt: timestampSchema,
+});
+
+export const getPublishedMarketingSchemaResponseSchema = z.object({
+	schema: marketingSchemaSlotRowSchema.nullable(),
+});
+
+export const upsertDraftMarketingSchemaInputSchema = z.object({
+	schema: z.record(z.string(), z.unknown()),
+	checksum: z.string().length(64),
+	note: z.string().max(280).nullable().optional(),
+});
+
+export const upsertDraftMarketingSchemaResponseSchema = z.object({
+	ok: z.literal(true),
+	version: z.number().int().positive(),
+	checksum: z.string().length(64),
+	noop: z.boolean(),
+});
+
+export const getMarketingLocalesResponseSchema = z.object({
+	locales: z.array(z.string()),
+	brandTokens: z.record(z.string()),
+});
+
+/**
+ * Bulk section upsert — sent by `biab-dev sync-content`.
+ *
+ * One request carries up to 256 items (server-enforced). The CLI batches
+ * larger imports automatically. Each item is a single
+ * `(pageKey, locale, sectionKey)` value and goes through the same
+ * validation pipeline as a dashboard save, so a partial failure on one
+ * row reports `ok: false, error: "..."` without rolling back the rest.
+ */
+export const publishMarketingSectionsItemSchema = z.object({
+	pageKey: z.string().min(1).max(120),
+	locale: z.string().min(1).max(20),
+	sectionKey: z.string().min(1).max(120),
+	payload: z.unknown(),
+});
+
+export const publishMarketingSectionsInputSchema = z.object({
+	items: z.array(publishMarketingSectionsItemSchema).min(1).max(256),
+	validate: z.boolean().default(true).optional(),
+	note: z.string().max(280).nullable().optional(),
+});
+
+export const publishMarketingSectionsResultItemSchema = z.discriminatedUnion(
+	"ok",
+	[
+		z.object({
+			ok: z.literal(true),
+			pageKey: z.string(),
+			locale: z.string(),
+			sectionKey: z.string(),
+			version: z.number().int().positive(),
+		}),
+		z.object({
+			ok: z.literal(false),
+			pageKey: z.string(),
+			locale: z.string(),
+			sectionKey: z.string(),
+			error: z.string(),
+		}),
+	],
+);
+
+export const publishMarketingSectionsResponseSchema = z.object({
+	results: z.array(publishMarketingSectionsResultItemSchema),
+});
+
+export type SiteMarketingSectionEntry = z.infer<
+	typeof siteMarketingSectionEntrySchema
+>;
+export type SiteMarketingSeoData = z.infer<typeof siteMarketingSeoDataSchema>;
+export type BusinessAddress = NonNullable<z.infer<typeof companyAddressSchema>>;
+export type BusinessLocation = z.infer<typeof companyLocationSchema>;
+export type GetMarketingPageBundleResponse = z.infer<
+	typeof getMarketingPageBundleResponseSchema
+>;
+export type MarketingSchemaSlotRow = z.infer<
+	typeof marketingSchemaSlotRowSchema
+>;
+export type GetPublishedMarketingSchemaResponse = z.infer<
+	typeof getPublishedMarketingSchemaResponseSchema
+>;
+export type UpsertDraftMarketingSchemaInput = z.infer<
+	typeof upsertDraftMarketingSchemaInputSchema
+>;
+export type UpsertDraftMarketingSchemaResponse = z.infer<
+	typeof upsertDraftMarketingSchemaResponseSchema
+>;
+export type GetMarketingLocalesResponse = z.infer<
+	typeof getMarketingLocalesResponseSchema
+>;
+export type PublishMarketingSectionsItem = z.infer<
+	typeof publishMarketingSectionsItemSchema
+>;
+export type PublishMarketingSectionsInput = z.infer<
+	typeof publishMarketingSectionsInputSchema
+>;
+export type PublishMarketingSectionsResultItem = z.infer<
+	typeof publishMarketingSectionsResultItemSchema
+>;
+export type PublishMarketingSectionsResponse = z.infer<
+	typeof publishMarketingSectionsResponseSchema
+>;
+
+// ── Data model: reading records ──────────────────────────────────────
+//
+// The read half of the custom data model. Until these existed the model was
+// write-only from outside: `sync-data-model` pushed a schema and `sync-records`
+// seeded rows, and nothing could read either back.
+//
+// Note this is NOT the `collections:*` family above. Those read `site_data_rows`
+// (Site Data / the site builder's tables). Custom-object rows live in
+// `org_object_records` and are reached only through here.
+
+/** One edge out of a record. Relations are links, not embedded rows. */
+export const recordRelationLinkSchema = z.object({
+	/** The linked row's `id`. Read it with a follow-up `listRecords` call. */
+	recordId: z.string().uuid(),
+	/** `universalIdentifier` of the object the linked row belongs to. */
+	object: z.string(),
+});
+export type RecordRelationLink = z.infer<typeof recordRelationLinkSchema>;
+
+export const dataModelRecordSchema = z.object({
+	id: z.string().uuid(),
+	/**
+	 * The identity a seed file gave this row, or null when a human created it
+	 * in the dashboard. Null means "not reproducible from your config".
+	 */
+	universalIdentifier: z.string().uuid().nullable(),
+	/** Scalar values, keyed by field name. */
+	fields: z.record(z.string(), z.unknown()),
+	/**
+	 * Keyed by field name. EVERY declared relation field is present — `[]` when
+	 * it has no links — so an empty relation is never mistaken for a missing one.
+	 */
+	relations: z.record(z.string(), z.array(recordRelationLinkSchema)),
+	createdAt: timestampSchema,
+	updatedAt: timestampSchema,
+});
+export type DataModelRecord = z.infer<typeof dataModelRecordSchema>;
+
+export const listDataModelRecordsInputSchema = z.object({
+	/**
+	 * The object's `universalIdentifier` — the same value your config declares,
+	 * and the same one `sync-records` writes against. Not its name, which can
+	 * change without the identity changing.
+	 */
+	object: z.string().min(1),
+	limit: z.number().int().min(1).max(200).optional(),
+	/** Pass back the previous page's `nextCursor`. Opaque; don't construct one. */
+	cursor: z.string().optional(),
+});
+export type ListDataModelRecordsInput = z.infer<
+	typeof listDataModelRecordsInputSchema
+>;
+
+export const listDataModelRecordsAvailableSchema = z.object({
+	available: z.literal(true),
+	records: z.array(dataModelRecordSchema),
+	/** Null on the last page. */
+	nextCursor: z.string().nullable(),
+});
+export type ListDataModelRecordsAvailable = z.infer<
+	typeof listDataModelRecordsAvailableSchema
+>;
+
+/**
+ * Discriminated union — branch on `.available`. Custom objects are an à-la-carte
+ * surface (`crm.custom_objects`), so an org without it gets the upgrade shape
+ * rather than an exception.
+ */
+export const listDataModelRecordsResponseSchema = z.union([
+	listDataModelRecordsAvailableSchema,
+	planGatedUnavailableSchema,
+]);
+export type ListDataModelRecordsResponse = z.infer<
+	typeof listDataModelRecordsResponseSchema
+>;
+
+// ── Analytics: reading visitor counts ────────────────────────────────
+//
+// The read half of site analytics. The `<BIABAnalytics/>` tracker records
+// pageviews (write-only); these read the totals back so a site can show them.
+
+export const viewCountSchema = z.object({
+	/** Pageviews (`kind = 'pageview'` events). */
+	views: z.number().int().nonnegative(),
+	/**
+	 * Distinct anonId — an approximation of unique visitors. anonId rotates every
+	 * UTC day, so this is exact within a day and, over a longer window, counts a
+	 * returning visitor once per day they came (visitor-days). Never identifies
+	 * anyone; never undercounts.
+	 */
+	visitors: z.number().int().nonnegative(),
+});
+export type ViewCount = z.infer<typeof viewCountSchema>;
+
+export const pageViewsInputSchema = z.object({
+	/**
+	 * Exact paths to count. Omit (or pass `[]`) for a SITE-WIDE total. Each path
+	 * comes back in `paths`, zero-filled if it has no views yet.
+	 */
+	paths: z.array(z.string().min(1)).max(50).optional(),
+	/** Window in days. Omit for all-time. */
+	days: z.number().int().min(1).optional(),
+});
+export type PageViewsInput = z.infer<typeof pageViewsInputSchema>;
+
+export const pageViewsAvailableSchema = z.object({
+	available: z.literal(true),
+	/** ISO start of the window, or null for all-time. */
+	since: z.string().nullable(),
+	/** Over the whole scope: site-wide when no paths, else summed over them. */
+	total: viewCountSchema,
+	/** One entry per requested path (empty for a site-wide query). */
+	paths: z.array(viewCountSchema.extend({ path: z.string() })),
+});
+export type PageViewsAvailable = z.infer<typeof pageViewsAvailableSchema>;
+
+/**
+ * Discriminated union — branch on `.available`. Visitor analytics is an
+ * entitlement (`analytics.web`), so an org without it gets the upgrade shape
+ * rather than an exception.
+ */
+export const pageViewsResponseSchema = z.union([
+	pageViewsAvailableSchema,
+	planGatedUnavailableSchema,
+]);
+export type PageViewsResponse = z.infer<typeof pageViewsResponseSchema>;
+
+// ── AI-crawler visibility (AEO) ──────────────────────────────────────
+
+export const aiVisibilityInputSchema = z.object({
+	/** Window in days (default 30 server-side). */
+	days: z.number().int().min(1).optional(),
+});
+export type AiVisibilityInput = z.infer<typeof aiVisibilityInputSchema>;
+
+export const aiCrawlerVisibilitySchema = z.object({
+	/** Stable crawler name, e.g. "GPTBot". */
+	name: z.string(),
+	/** Operator, e.g. "OpenAI". Null when the platform can't say. */
+	vendor: z.string().nullable(),
+	/**
+	 * What the fetch means: "training" (corpus building), "search" (answer-
+	 * engine indexing — citation supply), or "user" (a live assistant reading
+	 * on a person's behalf). Null when unknown.
+	 */
+	intent: z.enum(["training", "search", "user"]).nullable(),
+	/** Fetches in the window. */
+	fetches: z.number().int().nonnegative(),
+	/** Distinct paths this crawler read. */
+	distinctPages: z.number().int().nonnegative(),
+	/** ISO timestamp of the crawler's most recent fetch. */
+	lastSeenAt: z.string(),
+});
+export type AiCrawlerVisibility = z.infer<typeof aiCrawlerVisibilitySchema>;
+
+export const aiVisibilityAvailableSchema = z.object({
+	available: z.literal(true),
+	/** ISO start of the window. */
+	since: z.string(),
+	/** Ordered most-fetches-first. Empty = no AI crawler came. */
+	crawlers: z.array(aiCrawlerVisibilitySchema),
+});
+export type AiVisibilityAvailable = z.infer<typeof aiVisibilityAvailableSchema>;
+
+/** Branch on `.available` — same entitlement gating as pageViews. */
+export const aiVisibilityResponseSchema = z.union([
+	aiVisibilityAvailableSchema,
+	planGatedUnavailableSchema,
+]);
+export type AiVisibilityResponse = z.infer<typeof aiVisibilityResponseSchema>;
+
+// ── Attribution footer ───────────────────────────────────────────────
+//
+// The "Powered by BusinessDash" badge's one narrow function. READ its policy;
+// WRITE an (untrusted) heartbeat. See the plan in the app repo.
+
+export const attributionPolicySchema = z.object({
+	/** The site the policy is for — build the badge's `?ref=<siteId>` from this. */
+	siteId: z.string().uuid(),
+	/**
+	 * Whether the badge must stay. `true` on launch plans (which can't remove
+	 * it); `false` on growth/scale. Advisory — the real check is server-side, but
+	 * an honest site uses this to decide whether it may hide the badge.
+	 */
+	required: z.boolean(),
+});
+export type AttributionPolicy = z.infer<typeof attributionPolicySchema>;
+
+export const attributionHeartbeatInputSchema = z.object({
+	/** Absolute URL the badge rendered on. Normalized + de-duped server-side. */
+	url: z.string().min(1).max(2048),
+});
+export type AttributionHeartbeatInput = z.infer<
+	typeof attributionHeartbeatInputSchema
+>;
+
+export const attributionHeartbeatResponseSchema = z.object({
+	/** `false` when the URL was unparseable — a heartbeat never errors. */
+	recorded: z.boolean(),
+});
+export type AttributionHeartbeatResponse = z.infer<
+	typeof attributionHeartbeatResponseSchema
+>;
+
+/* ---------------------------------------------------------------------------
+   Hiring — public job postings for a consumer-built careers page.
+
+   Read-only and deliberately narrower than the dashboard's job row: internal
+   hiring state (openings filled, application caps, default permissions/roles,
+   the role-ladder pointer, interview questions) never crosses this boundary.
+   Applications ride the existing forms surface via `applicationFormId`.
+   --------------------------------------------------------------------------- */
+
+export const jobCategorySchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	description: z.string().nullable(),
+	/** Free-form chip tint set in the dashboard (hex or CSS colour). */
+	color: z.string().nullable(),
+});
+export type JobCategory = z.infer<typeof jobCategorySchema>;
+
+export const jobCategoryWithCountSchema = jobCategorySchema.extend({
+	/** Open postings currently in this category. */
+	openCount: z.number(),
+});
+export type JobCategoryWithCount = z.infer<typeof jobCategoryWithCountSchema>;
+
+export const jobPostingSchema = z.object({
+	id: z.string(),
+	slug: z.string(),
+	title: z.string(),
+	/** Rich-text HTML, sanitized server-side. Safe to render. */
+	description: z.string(),
+	department: z.string().nullable(),
+	level: z.string().nullable(),
+	employmentType: z.string(),
+	workMode: z.string(),
+	location: z.string().nullable(),
+	region: z.object({ id: z.string(), name: z.string() }).nullable(),
+	/** The posting's single group. `null` when uncategorized. */
+	category: jobCategorySchema.nullable(),
+	/** Free-form labels for filtering/search; never a grouping. */
+	tags: z.array(z.string()),
+	responsibilities: z.array(z.string()).nullable(),
+	requirements: z.string().nullable(),
+	languages: z.array(z.string()).nullable(),
+	payRangeText: z.string().nullable(),
+	salaryMin: z.number().nullable(),
+	salaryMax: z.number().nullable(),
+	currency: z.string().nullable(),
+	/**
+	 * Pass to `client.forms.schema()` / `<BiabForm/>` to render the application
+	 * form. `null` means the posting is listed but not yet accepting applications.
+	 */
+	applicationFormId: z.string().nullable(),
+	publishedAt: z.string().nullable(),
+	updatedAt: z.string(),
+});
+export type JobPosting = z.infer<typeof jobPostingSchema>;
+
+export const jobPostingListResponseSchema = z.object({
+	items: z.array(jobPostingSchema),
+	/** Total open postings matching the (optional) category filter. */
+	totalCount: z.number(),
+	/** Offset to pass back for the next page, or null when exhausted. */
+	nextOffset: z.number().nullable(),
+});
+export type JobPostingListResponse = z.infer<
+	typeof jobPostingListResponseSchema
+>;
+
+export const jobCategoryListResponseSchema = z.object({
+	items: z.array(jobCategoryWithCountSchema),
+});
+export type JobCategoryListResponse = z.infer<
+	typeof jobCategoryListResponseSchema
+>;