@businessdash/sdk 0.9.60

package/dist/contracts.js

@@ -0,0 +1,2428 @@
+import { z } from "zod";
+/**
+ * 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(...values) {
+    return z
+        .string()
+        .describe(`Known values: ${values.join(" | ")}. The server may add more — treat unrecognised values as forward-compatible rather than invalid.`);
+}
+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",
+];
+export const collectionFieldTypeSchema = z.enum(collectionFieldTypeValues);
+export const jsonValueSchema = 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"];
+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 const storefrontSessionResponseSchema = baseEmbedSessionResponse;
+export const cartSessionResponseSchema = baseEmbedSessionResponse;
+export const checkoutLineSchema = z.object({
+    productId: z.string().uuid(),
+    variantId: z.string().uuid(),
+    combinationKey: z.string().optional(),
+    quantity: z.number().int().positive(),
+});
+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 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,
+});
+// ── 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 const checkoutStartResponseSchema = z.object({
+    sessionId: z.string().min(1),
+    stripeUrl: z.string().url(),
+    totalAmountCents: z.number().int(),
+    currency: z.string().min(1),
+});
+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 const blogSessionInputSchema = z
+    .object({
+    postSlug: z.string().min(1).max(200).optional(),
+})
+    .optional();
+export const blogSessionResponseSchema = baseEmbedSessionResponse;
+// ── Chatbot ────────────────────────────────────────────────────────────────
+export const chatbotSessionResponseSchema = baseEmbedSessionResponse;
+/** How proactively the bot should suggest "Talk to a person" — server-driven. */
+export const chatbotHandoffThresholdSchema = z.enum([
+    "never",
+    "low",
+    "medium",
+    "high",
+    "always",
+]);
+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"),
+});
+/** 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 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 const chatbotMessageSchema = z.object({
+    role: z.enum(["user", "assistant", "system"]),
+    content: z.string().max(16_000),
+});
+/**
+ * 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 const chatbotChatInputSchema = z.object({
+    messages: z.array(chatbotMessageSchema).min(1).max(40),
+    /** See {@link chatbotByoConfigSchema}. Server-side use only. */
+    byo: chatbotByoConfigSchema.optional(),
+});
+/**
+ * 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),
+    }),
+]);
+/**
+ * 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 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),
+});
+/**
+ * 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 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 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 const chatbotFormSubmitResponseSchema = z.object({
+    success: z.literal(true),
+    submissionId: z.string(),
+    slug: z.string(),
+});
+// ── 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 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 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 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 const chatbotMessagesResponseSchema = z.object({
+    session: chatbotSessionStatusSchema,
+    messages: z.array(chatbotPersistedMessageSchema),
+});
+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"),
+});
+/**
+ * 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 const chatbotRequestHumanInputSchema = z.object({
+    sessionId: z.string().uuid(),
+    visitorToken: z.string().min(8).max(200),
+});
+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(),
+    })),
+});
+/**
+ * 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 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"];
+export const emailTemplateRendererSchema = z.enum(emailTemplateRendererValues);
+export const emailTemplateCategoryValues = [
+    "system",
+    "marketing",
+    "transactional",
+];
+export const emailTemplateCategorySchema = z.enum(emailTemplateCategoryValues);
+export const emailTemplateVariableTypeValues = [
+    "string",
+    "number",
+    "url",
+    "currency",
+    "date",
+];
+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,
+});
+// ── 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);
+// ── 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 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(),
+    })),
+});
+// ── 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();
+// ── 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(),
+});
+// ── 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),
+});
+// ── 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(),
+});
+// ── 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(),
+});
+// ── 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();
+// ── 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),
+});
+// ── 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(),
+});
+// ── 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(),
+});
+// ── 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),
+});
+// ── 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(),
+});
+// ── 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),
+});
+/**
+ * Storefront sort options for the listing grid (mirrors the platform shop demo).
+ */
+export const storefrontSortValues = [
+    "featured",
+    "newest",
+    "price-asc",
+    "price-desc",
+    "rating-desc",
+];
+/** 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),
+});
+// ── 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),
+});
+// ── 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 const shippingRatesInputSchema = z.object({
+    deliveryAddress: shippingDeliveryAddressSchema,
+});
+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 const shippingRatesResponseSchema = z.object({
+    options: z.array(shippingOptionSchema),
+    requiresShipping: z.boolean(),
+});
+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(),
+});
+/**
+ * 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(),
+});
+// ── 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 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 const customerNotificationPreferencesUpdateResponseSchema = z.object({
+    ok: z.literal(true),
+});
+// ── 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 const startVerificationResponseSchema = z.object({
+    ok: z.literal(true),
+    message: z.string(),
+    flow: z.enum(["link", "otp"]),
+});
+export const confirmVerificationInputSchema = z.object({
+    token: z.string().min(4).max(128),
+});
+export const confirmVerificationResponseSchema = z.object({
+    ok: z.literal(true),
+    verifiedKind: z.enum(["email", "phone"]),
+    destination: z.string(),
+});
+// ── 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 const addressPlacePredictionSchema = z.object({
+    place_id: z.string(),
+    structured_formatting: z.object({
+        main_text: z.string(),
+        secondary_text: z.string(),
+    }),
+});
+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),
+    }),
+]);
+/**
+ * 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 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 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 const addressVerifyResponseSchema = z.object({
+    isVerified: z.boolean(),
+    googleAddress: z.string().nullable(),
+});
+// ── 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 const subscriptionOfferingsListResponseSchema = z.object({
+    items: z.array(subscriptionOfferingSchema),
+});
+export const subscriptionCheckoutInputSchema = z
+    .object({
+    customerEmail: z.string().email().optional(),
+    successUrl: z.string().url().optional(),
+    cancelUrl: z.string().url().optional(),
+})
+    .optional();
+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"),
+});
+// ── Coupons (Batch LL, 0.9.0) ─────────────────────────────────────────
+export const couponValidateInputSchema = z.object({
+    code: z.string().min(1).max(80),
+});
+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 const couponValidateInvalidSchema = z.object({
+    valid: z.literal(false),
+    reason: z.enum([
+        "unknown_code",
+        "expired",
+        "inactive",
+        "no_stripe_account",
+        "lookup_failed",
+    ]),
+    message: z.string(),
+});
+export const couponValidateResponseSchema = z.union([
+    couponValidateValidSchema,
+    couponValidateInvalidSchema,
+]);
+// ── 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),
+});
+// ── 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(),
+});
+/**
+ * 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();
+/**
+ * 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 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),
+});
+// ── 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 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 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 const listDataModelRecordsAvailableSchema = z.object({
+    available: z.literal(true),
+    records: z.array(dataModelRecordSchema),
+    /** Null on the last page. */
+    nextCursor: z.string().nullable(),
+});
+/**
+ * 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,
+]);
+// ── 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 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 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() })),
+});
+/**
+ * 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,
+]);
+// ── AI-crawler visibility (AEO) ──────────────────────────────────────
+export const aiVisibilityInputSchema = z.object({
+    /** Window in days (default 30 server-side). */
+    days: z.number().int().min(1).optional(),
+});
+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 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),
+});
+/** Branch on `.available` — same entitlement gating as pageViews. */
+export const aiVisibilityResponseSchema = z.union([
+    aiVisibilityAvailableSchema,
+    planGatedUnavailableSchema,
+]);
+// ── 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 const attributionHeartbeatInputSchema = z.object({
+    /** Absolute URL the badge rendered on. Normalized + de-duped server-side. */
+    url: z.string().min(1).max(2048),
+});
+export const attributionHeartbeatResponseSchema = z.object({
+    /** `false` when the URL was unparseable — a heartbeat never errors. */
+    recorded: z.boolean(),
+});
+/* ---------------------------------------------------------------------------
+   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 const jobCategoryWithCountSchema = jobCategorySchema.extend({
+    /** Open postings currently in this category. */
+    openCount: z.number(),
+});
+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 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 const jobCategoryListResponseSchema = z.object({
+    items: z.array(jobCategoryWithCountSchema),
+});
+//# sourceMappingURL=contracts.js.map