@frontdesk-africa/store-js 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,2421 @@
+/**
+ * Floating pill header — the styling contract for `header.layout === 'floating_pill'`.
+ *
+ * One rounded bar centred at the top of the page, carrying the brand, nav and actions. Everything a
+ * merchant can shape about it lives here so the React renderer, the pro-api normalizer and the Vue
+ * builder resolve identical geometry: colours (or `null` for the automatic tone), corner radius,
+ * inner padding, width, how far it floats from the page edges, its surface treatment, and what it
+ * does on scroll.
+ *
+ * The nullable colours are the important part of the model: `null` is not "no colour", it means
+ * "work it out" — the palette's ink over the page, or the tone already resolved as legible over a
+ * hero. A merchant who picks a colour overrides that for good.
+ */
+/** Depth under the pill. `soft` is the default lift; `lifted` reads as a floating card. */
+type StorefrontPillShadow = "none" | "soft" | "lifted";
+/** What the pill does as the visitor scrolls the page. */
+type StorefrontPillScroll = 
+/** Stays exactly where it is. */
+"stay"
+/** Slides away on scroll down, returns the moment they scroll up. */
+ | "hide"
+/** Tightens slightly once past the top of the page. */
+ | "shrink";
+/**
+ * Which way round the pill sits against the site.
+ *
+ * `light` and `dark` are the PALETTE's own pair, not generic white and black: light takes the palette's
+ * surface colour with its ink on top, dark takes the ink with the palette's paper on top. On a dark
+ * palette that means "light" is the palette's dark panel — the names describe which of the two roles
+ * the pill borrows, not an absolute brightness, and a branded palette tints the pill either way.
+ *
+ * `auto` is the original behaviour: resolved from whatever the pill sits on, which means the hero on a
+ * home page and the palette ink everywhere else — so the pill can change between pages. Choosing light
+ * or dark is what makes it the same site-wide.
+ */
+type StorefrontPillTone = "auto" | "light" | "dark";
+/** How wide the pill runs: hug its content (null), a % of the screen, or the page's content column. */
+type StorefrontPillWidth = number | "content" | null;
+interface StorefrontHeaderPillStyle {
+    /** Which of the palette's two roles the pill borrows. `bgColor`/`textColor` still override it. */
+    tone: StorefrontPillTone;
+    /** null = the tone decides. A colour here wins over the tone. */
+    bgColor: string | null;
+    /** null = automatic: ink or paper, whichever the background can carry. */
+    textColor: string | null;
+    /** Corner radius in px. 999 is a full capsule. */
+    radius: number;
+    /** Inner padding, px. */
+    paddingX: number;
+    paddingY: number;
+    /** null = hug the content (never under 600px on desktop). A number is a % of the screen.
+     *  'content' spans the same column the page's sections use, so the pill lines up with them. */
+    width: StorefrontPillWidth;
+    /** Gap between the pill and the top of the page, px. */
+    topOffset: number;
+    /** Gap kept clear at the left and right page edges, px. */
+    sideOffset: number;
+    shadow: StorefrontPillShadow;
+    /** A hairline outline; `borderColor` null = the pill's own text colour, faded. */
+    border: boolean;
+    borderColor: string | null;
+    /** Frosted glass: blurs whatever is behind and drops the pill to a translucent fill. */
+    blur: boolean;
+    scroll: StorefrontPillScroll;
+}
+
+/**
+ * Canonical storefront LINK model — the single "linking engine" shared by every linkable element
+ * (CTA buttons, header nav links, and anything that adopts it later). One shape, one resolver, one
+ * normalizer; no per-surface link types.
+ *
+ * - `resolveLinkHref` is framework-agnostic so the React renderer and the builder preview produce
+ *   byte-identical hrefs (it mirrors the renderer's `pageHref`).
+ * - `normalizeLink` clamps arbitrary input to a valid link — reused by the pro-api normalizer and
+ *   any safe read.
+ * The portal builder edits this shape through `<StorefrontLinkEditor>`.
+ */
+type StorefrontLinkType = "none" | "section" | "page" | "external" | "package" | "product" | "collection" | "catalog" | "event" | "contact_form" | "chat" | "chat_widget";
+interface StorefrontLink {
+    type: StorefrontLinkType;
+    /** type==='section' — a section id on the current page (jumps to its #anchor). */
+    sectionId?: string | null;
+    /** type==='page' — a page slug. */
+    pageSlug?: string | null;
+    /** type==='external' — an absolute URL. */
+    url?: string | null;
+    /** type==='package' — the package's slug (its public detail page). */
+    packageSlug?: string | null;
+    /** type==='package' (optional) — a specific option ref; opens that option's checkout modal. */
+    packageOptionRef?: string | null;
+    /** type==='product' — the product's slug (its public Store detail page). */
+    productSlug?: string | null;
+    /** type==='collection' — the collection's slug (its public /collections page); null/'' = the
+     *  all-collections index. */
+    collectionSlug?: string | null;
+    /** type==='catalog' — a media catalog / Portfolio slug (its public /catalog/media/{slug} page). */
+    catalogSlug?: string | null;
+    /** type==='event' — an event's slug (its public /events/{slug} page); null/'' = the all-events
+     *  listing at /events. */
+    eventSlug?: string | null;
+}
+
+/**
+ * People (CRM) shared contracts — FrontDesk spec §3, §10.4 (PV-003).
+ *
+ * One unified, tag-driven contact object per workspace. A single People record can carry
+ * multiple tags (Client / Customer / Vendor / Lead / Guest). Promotion = tag-add on the same
+ * record (D-8), never a merge of records. Storefront buyers + booking submitters upsert into
+ * People by matching on email OR phone (see `upsertContact` in the people service).
+ */
+type PeopleTag = 'client' | 'customer' | 'vendor' | 'lead' | 'guest' | 'team' | 'promoter' | 'subscriber';
+
+/**
+ * Storefront PROMO campaigns — the on-load lightbox and the exit-intent catcher.
+ *
+ * Site-wide content (it lives beside `tracking`, not in a section) because a promo is not part of any
+ * one page's layout: an on-load campaign belongs to the home page, and an exit-intent one follows the
+ * visitor across every page.
+ *
+ * Everything a visitor's browser needs to DECIDE whether to show a campaign is computed here, so the
+ * React renderer and the builder preview agree by construction — the same rule that keeps
+ * `resolveLinkHref` honest.
+ */
+/** What makes a campaign appear. */
+type PromoTrigger = 
+/** Home page only, after `delayMs`. The classic "here's our sale" lightbox. */
+"on_load"
+/** Every page, when the visitor looks like they're leaving. */
+ | "exit_intent";
+type PromoMediaType = "none" | "image" | "video";
+/** A promo's call-to-action. Reuses the canonical link engine, so it can point anywhere a nav link can. */
+interface PromoButton {
+    id: string;
+    label: string;
+    link: StorefrontLink;
+}
+interface PromoCampaign {
+    id: string;
+    /** Author-facing name. Never shown to buyers — it's how the merchant tells campaigns apart. */
+    name: string;
+    enabled: boolean;
+    trigger: PromoTrigger;
+    /** on_load only: how long after the page settles before it appears. Clamped to 0..30s. */
+    delayMs: number;
+    /** Optional window (ISO dates). Absent = starts/runs forever. A merchant setting an end date is how
+     *  a sale promo stops on its own instead of being left up for weeks. */
+    startAt?: string | null;
+    endAt?: string | null;
+    mediaType: PromoMediaType;
+    imageUrl?: string | null;
+    videoUrl?: string | null;
+    /** Video autoplays muted + looping. When true the modal offers an unmute control; the buyer's click
+     *  on it must not follow `mediaLink` (the media area is otherwise clickable). */
+    videoSoundEnabled?: boolean;
+    heading: string;
+    body: string;
+    /** Up to 2. The FIRST is the primary CTA and is what the clickable media area follows. */
+    buttons: PromoButton[];
+    /** Label for the "no thanks" action. Empty falls back to "Dismiss". */
+    dismissLabel?: string | null;
+    emailCaptureEnabled?: boolean;
+    emailPlaceholder?: string | null;
+    emailButtonLabel?: string | null;
+    /** Shown in place of the form once they submit. */
+    emailSuccessMessage?: string | null;
+    /** Tag applied to the captured contact in People. Constrained to the real People tag set (it is a DB
+     *  enum, not free text), so this is a picker in the editor, not a text field. Absent = 'lead'. */
+    emailTag?: PeopleTag | null;
+    /**
+     * Bumped by the editor's "Show this again" button. The browser's dismissal record is keyed on
+     * `{id}:{version}`, so bumping it re-opens the campaign for everyone — including people who already
+     * dismissed it. Editing copy deliberately does NOT re-show it; that would mean a typo fix re-interrupts
+     * every visitor.
+     */
+    version: number;
+}
+/** The site-wide promo block. One ordered list; each entry carries its own trigger. */
+interface StorefrontPromoContent {
+    campaigns: PromoCampaign[];
+}
+
+/**
+ * Storefront FOOTER TEMPLATES — the one registry of which footer layouts exist.
+ *
+ * This list was previously restated in six places (two content types, a zod enum, a hand-written
+ * normalizer, the builder's picker options and the renderer's branches). Adding a template meant
+ * finding all six, and missing the zod one silently stripped the value on save. Everything now
+ * derives from here.
+ *
+ * Adding a template: append to FOOTER_TEMPLATES + FOOTER_TEMPLATE_META, give it a palette in the
+ * builder's `footerTemplatePalette`, a branch in the renderer's `Footer`, a skeleton in the editor's
+ * picker, and an entry in FOOTER_TRUST_DIVIDER_DEFAULT.
+ */
+declare const FOOTER_TEMPLATES: readonly ["minimal", "brand_columns", "pale_grid", "bold_cta", "wordmark_band", "stark_columns", "business_local", "trust_grid"];
+type FooterTemplate = (typeof FOOTER_TEMPLATES)[number];
+
+/**
+ * Optional own colors for a block. `null`/absent = inherit the footer palette.
+ *
+ * This is what makes a contrasting band possible (the lilac newsletter strip in the Parcel Monkey
+ * reference, the dark newsletter column in RELISTED) without the merchant hand-editing the whole
+ * footer palette to get one band.
+ */
+interface FooterBlockStyle {
+    backgroundColor?: string | null;
+    textColor?: string | null;
+    /** Button fill / icon color inside the block. Falls back to the footer accent. */
+    accentColor?: string | null;
+}
+/**
+ * Space above/below a block, in px, so it can be pushed off its neighbours. Mirrors the
+ * spaceTop/spaceBottom knobs on hero blocks and groups, including the 0..200 range, so the control
+ * reads as one the merchant already knows.
+ *
+ * Carried by the blocks that occupy a full-width ROW of the footer (newsletter, payments, trust) —
+ * the ones whose spacing a merchant can actually see. Address and hours sit inside a column where
+ * the surrounding grid gap owns the rhythm, so they deliberately have no spacing knobs.
+ */
+interface FooterBlockSpacing {
+    spaceTop?: number;
+    spaceBottom?: number;
+}
+/**
+ * A FULL-BLEED hairline rule above a block — it escapes the footer's horizontal padding, so it reads
+ * as a band separator rather than a boxed underline. Carried by the blocks that occupy a full-width
+ * row (newsletter, trust).
+ *
+ * `showDivider` absent means "follow the template" (FOOTER_TRUST_DIVIDER_DEFAULT); an explicit
+ * true/false always wins. Resolve with `footerTrustDividerVisible`, never by reading the field.
+ */
+interface FooterBlockDivider {
+    showDivider?: boolean;
+    /** 0-100. Percentage of the block's text colour. */
+    dividerOpacity?: number;
+    /** Rule thickness in px, 1..8. */
+    dividerHeight?: number;
+}
+/** Field/button scale for the newsletter form. */
+declare const FOOTER_FIELD_SIZES: readonly ["small", "normal", "big"];
+type FooterFieldSize = (typeof FOOTER_FIELD_SIZES)[number];
+interface StorefrontFooterNewsletter extends FooterBlockStyle, FooterBlockSpacing, FooterBlockDivider {
+    enabled: boolean;
+    heading: string;
+    /** Sub-copy under the heading. Blank hides the line. */
+    body: string;
+    /** Whether the name field is shown. Name is NEVER required to submit, even when shown. */
+    showNameField: boolean;
+    namePlaceholder: string;
+    emailPlaceholder: string;
+    buttonLabel: string;
+    /** Replaces the form in place once they subscribe. */
+    successMessage: string;
+    /** Small print under the field, in lieu of a consent checkbox. Blank hides it. */
+    consentNote: string;
+    /** People tag applied to the contact. Constrained to the real tag set (a DB enum), so this is a
+     *  picker in the editor. Absent = 'subscriber'. */
+    tag?: PeopleTag | null;
+    /** Workspace-branded welcome email to whoever subscribed. */
+    welcomeEmailEnabled: boolean;
+    /** null = the platform default copy. Merchants who never open this still send a good email. */
+    welcomeSubject?: string | null;
+    welcomeBody?: string | null;
+    /** Input + button scale. Absent = 'normal'. */
+    fieldSize?: FooterFieldSize;
+    /** Corner radius of the fields and button, px. Absent = 8; 0 = hard square edges. */
+    radius?: number;
+}
+/**
+ * The payment-method logo row. Deliberately carries NO list of marks: the marks are derived
+ * server-side from the store's enabled methods (see ./payment-marks), so a footer can never
+ * advertise a method the checkout will not actually offer.
+ */
+interface StorefrontFooterPayments extends FooterBlockStyle, FooterBlockSpacing {
+    enabled: boolean;
+    /** Optional small heading, e.g. "We accept". Blank/null renders the marks alone. */
+    title?: string | null;
+}
+/**
+ * The address block. Reads `content.contact` — the address is entered once, in the contact section,
+ * and the footer shows the parts the merchant ticks.
+ */
+interface StorefrontFooterAddress extends FooterBlockStyle {
+    enabled: boolean;
+    /** Heading above the block. null = the storefront display name, but only when `showBusinessName`
+     *  is on — which defaults OFF, because this block usually sits directly under the footer's brand
+     *  text and would otherwise print the business name twice. */
+    title?: string | null;
+    showBusinessName: boolean;
+    showAddress: boolean;
+    /** Email and phone render as ICONS in the footer's social row, not as text lines in this block —
+     *  they are contact handles like the socials, and reading as one row of icons is tidier. */
+    showEmail: boolean;
+    showPhone: boolean;
+}
+/**
+ * The opening-hours block. Rows come from the workspace's front-desk `businessHours`, so there is
+ * nothing to retype; the block self-hides when hours were never configured.
+ */
+interface StorefrontFooterHours extends FooterBlockStyle {
+    enabled: boolean;
+    /** null = "Opening hours". */
+    title?: string | null;
+    /** Label for a day with no configured window. */
+    closedLabel?: string | null;
+}
+/** Curated icon set for trust items. A closed list beats exposing all of lucide to a picker. */
+declare const FOOTER_TRUST_ICONS: readonly ["shield-check", "lock", "truck", "package", "headset", "star", "badge-check", "credit-card", "globe", "clock", "heart", "leaf"];
+type FooterTrustIcon = (typeof FOOTER_TRUST_ICONS)[number];
+interface StorefrontFooterTrustItem {
+    id: string;
+    icon: FooterTrustIcon;
+    /** The light first line, e.g. "100% SECURE". */
+    label: string;
+    /** The bold second line, e.g. "CHECKOUT". Blank renders a single-line item. */
+    emphasis: string;
+    /**
+     * This badge's icon colour. Absent/null = the strip's own icon colour (the block's `accentColor`),
+     * which in turn falls back to the footer accent. An OVERRIDE rather than a required value, so the
+     * strip still reads as one unit by default and a merchant only breaks that deliberately.
+     */
+    iconColor?: string | null;
+}
+/**
+ * 1 to 4 icon items. A single item renders as a plain inline trust line ("Secure checkout"); two or
+ * more render as the spread strip from the Parcel Monkey reference.
+ */
+interface StorefrontFooterTrust extends FooterBlockStyle, FooterBlockSpacing, FooterBlockDivider {
+    enabled: boolean;
+    items: StorefrontFooterTrustItem[];
+}
+
+/**
+ * SOCIAL SHARE IMAGE — the one registry of how a storefront link previews on WhatsApp/iMessage/
+ * Facebook/X, and the only place the style + template lists exist.
+ *
+ * Three styles:
+ *   'card'   — a designed 1200x630 card rendered by the storefront's /api/og, laid out by one of
+ *              SOCIAL_CARD_TEMPLATES and written from the site's own name/description (or the
+ *              owner's overrides).
+ *   'photo'  — the owner's best real photo, full frame, no text.
+ *   'custom' — artwork the owner designed and uploaded, cover-cropped to 1200x630.
+ *
+ * Adding a template: append to SOCIAL_CARD_TEMPLATES + SOCIAL_CARD_TEMPLATE_META and give it a
+ * branch in the storefront's /api/og route. The builder picker renders straight from the META list,
+ * so it needs no edit.
+ */
+declare const SOCIAL_PREVIEW_STYLES: readonly ["card", "photo", "custom"];
+type SocialPreviewStyle = (typeof SOCIAL_PREVIEW_STYLES)[number];
+/**
+ * Card layouts. `scrim` is FIRST and the default because it renders exactly what every storefront
+ * on the old two-way 'card' | 'photo' switch already had — an existing site must keep its share
+ * image byte-identical when this list ships.
+ */
+declare const SOCIAL_CARD_TEMPLATES: readonly ["scrim", "bold", "split", "lockup"];
+type SocialCardTemplate = (typeof SOCIAL_CARD_TEMPLATES)[number];
+
+/**
+ * Social embeds — shared platform detection + embed helpers (Tier 1).
+ *
+ * The `social` storefront section (and its future hero-block twin) lets a merchant paste links to
+ * their Instagram / TikTok / YouTube / Facebook / X posts and have them rendered inline on the
+ * storefront. Detection + canonicalisation live here so all three apps agree byte-for-byte: pro-api
+ * validates the pasted URL (unknown platform = dropped), the React renderer picks the right embed
+ * strategy, and the Nuxt builder shows the right icon + preview.
+ *
+ * v1 is CURATED (the merchant pastes each URL) and renders via each platform's own no-auth embed
+ * script (Meta SDK for IG/FB, X widgets.js, TikTok embed.js) or a plain iframe (YouTube). A synced
+ * auto-feed is a later phase; the item shape already carries a `source` so it can slot in.
+ */
+type SocialPlatform = "instagram" | "tiktok" | "youtube" | "facebook" | "x";
+/**
+ * How a `social` section arranges its items. `auto` (the default) resolves at render time from the
+ * item count: a lone post shows large (featured), two or more tile into a grid — the renderer/editor
+ * both call `resolveSocialLayout`. The other three are explicit user choices.
+ */
+type SocialLayout = "auto" | "grid" | "carousel" | "featured";
+/**
+ * One embedded social item. `url` is the canonical, embeddable permalink (never a shortener).
+ * `thumbnailUrl` is an optional cached poster (fetched from a public oEmbed endpoint on save, where
+ * the platform still returns one); the live embed hydrates over it. `source` is `curated` today; a
+ * synced feed writes `synced` rows into the same list later.
+ */
+interface SocialEmbedItem {
+    id: string;
+    platform: SocialPlatform;
+    url: string;
+    thumbnailUrl?: string | null;
+    caption?: string;
+    source?: "curated" | "synced";
+    visible: boolean;
+}
+
+/**
+ * How uploaded images are encoded:
+ *  - webp              — re-encode everything to WebP (smallest; WebP keeps alpha). The default.
+ *  - webp_preserve_png — photos → WebP, but keep PNG when the source is a PNG (safest for anything
+ *                        downstream that can't read WebP; slightly larger for transparent logos).
+ *  - original          — no resize, no re-encode; upload the file as-is (the high-fidelity escape
+ *                        hatch for a FrontDesk that genuinely needs full-quality images).
+ */
+type MediaImageFormat = 'webp' | 'webp_preserve_png' | 'original';
+/**
+ * The resolved policy handed to an upload client. `quality` is a 0..1 float (canvas.toBlob units).
+ * This is what portal/storefront resize code consumes.
+ */
+interface MediaUploadPolicy {
+    maxDim: number;
+    quality: number;
+    format: MediaImageFormat;
+}
+
+type BookingFieldType = 'short_text' | 'long_text' | 'number' | 'currency' | 'date' | 'time' | 'single_select' | 'multi_select' | 'radio' | 'checkbox' | 'toggle' | 'file';
+/** Conditional logic (v1): show this field only when another field equals a value. */
+interface BookingFieldCondition {
+    field: string;
+    equals: string | number | boolean;
+}
+interface BookingFormField {
+    key: string;
+    type: BookingFieldType;
+    label: string;
+    required?: boolean;
+    hidden?: boolean;
+    placeholder?: string;
+    helpText?: string;
+    options?: string[];
+    showIf?: BookingFieldCondition;
+}
+
+/** Who bears the FrontDesk charge on a paid line/order — added ON TOP for the customer, or netted from
+ *  the merchant's credit. Mirrors the event ticket fee mode. */
+type ChargeMode = 'pass_on' | 'absorb';
+
+/** The rating distribution, keyed by star. Always all five keys, zeros included, so the bars render
+ *  without the caller having to fill gaps. */
+interface ProductRatingCounts {
+    1: number;
+    2: number;
+    3: number;
+    4: number;
+    5: number;
+}
+/** The aggregate that drives the header, the distribution bars and the JSON-LD. */
+interface ProductReviewAggregate {
+    count: number;
+    /** Rounded to one decimal for display. Derived from sum/count, never stored. */
+    average: number;
+    counts: ProductRatingCounts;
+    /** The cached AI summary, when one has been built and is not stale. */
+    aiSummary?: string | null;
+}
+
+/**
+ * Product Information (PV-111) — the enrichment layer on a store product: a detailed description, key
+ * highlights, retail identifiers, brand/make, weight + dimensions, category specifications, care,
+ * warranty, origin and sustainability.
+ *
+ * Everything here is OPTIONAL. A product with none of it behaves exactly as it did before; the portal
+ * nudges (never blocks) and the storefront hides every empty field.
+ *
+ * Three things live in this file rather than in the API or the portal, because all three surfaces need
+ * the SAME answer:
+ *  - the category list + its suggested spec templates (portal renders them, pro-api validates against
+ *    them, the AI prompt is built from them),
+ *  - the spec/highlight normalizers (one definition of "clean", used on write),
+ *  - `scoreProductInfo` (the portal completion ring, and any later analytics).
+ *
+ * Plan: `services/design-docs/frontdesk-docs/product-information-tab.md`.
+ */
+
+type WeightUnit = 'kg' | 'g' | 'lb' | 'oz';
+type DimensionUnit = 'cm' | 'mm' | 'm' | 'in';
+/** How a spec value is captured + rendered. Advisory: every value is stored as a string either way. */
+type SpecKind = 'text' | 'number' | 'select' | 'boolean' | 'multi';
+/**
+ * One row in a product's specification list. The list holds BOTH category-template answers and the
+ * merchant's own custom rows, in one ordered array, which is what lets a merchant reorder freely across
+ * the two. A custom row is simply one with `key: null`.
+ */
+interface ProductSpec {
+    /** Stable id so an edit or a reorder round-trips without re-keying by index. */
+    id: string;
+    /** Template key when this row came from a category template ('screen_size'), null when merchant-authored. */
+    key: string | null;
+    label: string;
+    value: string;
+    kind: SpecKind;
+    /** Optional unit suffix rendered after the value ('inch', 'ml', 'W'). */
+    unit?: string | null;
+    /** Display order, persisted so a drag-reorder survives a reload. */
+    sort: number;
+}
+/**
+ * A product description is an ordered list of blocks, not one text field: merchants sell with pictures
+ * BETWEEN paragraphs (a size chart after the fit copy, a lifestyle shot after the story), the way
+ * Alibaba and Jumia product pages read.
+ *
+ * `long_description` is still stored, but DERIVED from the text blocks on write (see
+ * `blocksToPlainText`). That keeps one source of truth for the merchant to edit while search, the AI
+ * prompt, the completion score and the schema.org `description` all keep reading clean prose without
+ * knowing blocks exist.
+ */
+type DescriptionBlockKind = 'text' | 'image' | 'video' | 'embed';
+/** How wide a media block renders in the storefront description column. */
+type BlockWidth = 'full' | 'half';
+interface ProductDescriptionBlock {
+    id: string;
+    kind: DescriptionBlockKind;
+    /** `text` blocks: a paragraph or a short heading. */
+    text?: string | null;
+    /** `image` / `video` blocks: the uploaded asset. `embed` blocks: the canonical post permalink. */
+    url?: string | null;
+    /**
+     * `embed` blocks only: which platform the link resolved to. Detected SERVER-SIDE from the pasted URL
+     * via the shared `normalizeSocialUrl`, never trusted from the client, so the storefront can pick the
+     * right embed strategy without re-parsing.
+     */
+    platform?: SocialPlatform | null;
+    /** Accessibility text for an image. Also what a screen reader and Google see. */
+    alt?: string | null;
+    /** Optional caption rendered under the media. */
+    caption?: string | null;
+    width?: BlockWidth;
+    sort: number;
+}
+type ProductInfoCategory = 'fashion' | 'footwear' | 'electronics' | 'phones' | 'beauty' | 'food' | 'home' | 'furniture' | 'appliances' | 'auto' | 'health' | 'baby' | 'digital' | 'other';
+/**
+ * What a product actually stores in `infoCategory`. The 14 built-ins keep their slugs so no existing
+ * row moves; a category a merchant added through the `product_category` vocab stores its LABEL
+ * verbatim. Everything reading the field goes through `productInfoCategoryLabel`, which handles both.
+ */
+type ProductCategoryValue = ProductInfoCategory | (string & {});
+/** Everything the Product Information tab owns, as it reads back. Folded into `ProductView`. */
+interface ProductInfoView {
+    infoCategory: ProductCategoryValue | null;
+    /** DERIVED from `descriptionBlocks` whenever there are any (see `blocksToPlainText`); authored
+     *  directly only on a product that has no blocks. Never edit both. */
+    longDescription: string | null;
+    /** The authored description: paragraphs and media, in order. */
+    descriptionBlocks: ProductDescriptionBlock[];
+    highlights: string[];
+    sku: string | null;
+    barcode: string | null;
+    mpn: string | null;
+    hsCode: string | null;
+    brand: string | null;
+    manufacturer: string | null;
+    modelName: string | null;
+    weightValue: number | null;
+    weightUnit: WeightUnit | null;
+    dimLength: number | null;
+    dimWidth: number | null;
+    dimHeight: number | null;
+    dimUnit: DimensionUnit | null;
+    /** ISO-3166 alpha-2. */
+    countryOfOrigin: string | null;
+    warrantyText: string | null;
+    warrantyMonths: number | null;
+    careInstructions: string | null;
+    sustainabilityText: string | null;
+    specs: ProductSpec[];
+}
+/**
+ * What the STOREFRONT receives. The HS code is customs paperwork the merchant keeps for shipping
+ * documents; it means nothing to a buyer, so it never leaves the portal.
+ */
+type PublicProductInfo = Omit<ProductInfoView, 'hsCode'>;
+
+/**
+ * Store — products with variants (size/colour), inventory, delivery zones. The storefront "Store" lets a
+ * pro sell physical (or digital) products directly + attach them to events. Mirrors Packages: a Product
+ * owns 1..N Variants (each its own price/stock/image); a product with one variant = a simple product.
+ * Money is in MINOR units. Cross-DB refs are UUIDv7 `ref`s, never FKs.
+ */
+
+/** How a package product's options are chosen: one tier (radio) vs a menu (pick many + quantity). */
+type SelectionMode = 'choose_one' | 'choose_many';
+/** How the storefront draws a product's option picker. A variant missing an image/hex falls back to text. */
+type VariantDisplay = 'text' | 'image' | 'color';
+/** Product/option payment modes: the shipped package modes + Pay Later (Save-For-It deferred). */
+type ProductPricingMode = PackagePricingMode | 'pay_later';
+interface ProductAddonOption {
+    ref: string;
+    kind: AddonOptionKind;
+    label: string;
+    description: string | null;
+    priceMinor: number;
+    /** This add-on's price per accepted-secondary currency (public payloads only): the linked variant's
+     *  explicit per-currency price when set, else the server's FX default (rounded up clean) — exactly
+     *  what a booking in that currency will charge. Currency absent = add-on unavailable in it. */
+    prices?: VariantPrice[];
+    imageUrl: string | null;
+    allowQuantity: boolean;
+    maxQty: number | null;
+    /** For `linked` add-ons, the referenced product/variant (price-only link in v1); else null. */
+    linkedProductRef: string | null;
+    linkedVariantRef: string | null;
+}
+interface ProductAddonGroup {
+    ref: string;
+    name: string;
+    selectionType: AddonSelectionType;
+    required: boolean;
+    minSelect: number | null;
+    maxSelect: number | null;
+    sort: number;
+    /** null = applies to every option; set = scoped to one option (variant), e.g. Drone only for Gold. */
+    variantRef: string | null;
+    options: ProductAddonOption[];
+}
+/** Buyer-facing payment methods a Store/checkout can offer (the unified payment layer). */
+type StorePaymentMethod = 'paystack' | 'flutterwave' | 'pvb' | 'stripe';
+/**
+ * A variant's price in ONE currency. Multi-currency pricing: the variant's base `priceMinor` + `currency`
+ * is the PRIMARY price; these rows are the accepted-secondary prices. Money in MINOR units, so cents are
+ * representable (e.g. USD 24.99 = 2499). A currency with no row (and ≠ the primary) = not sold in it.
+ */
+interface VariantPrice {
+    currency: string;
+    priceMinor: number;
+    compareAtMinor: number | null;
+}
+/** Availability summary so the storefront booking calendar can grey out unavailable days (mirrors the
+ *  legacy package-option summary). Derived from the option's AvailabilityConfig on the server. */
+interface StoreAvailabilitySummary {
+    /** Weekdays the business is open (sun..sat); empty = open every day (no weekly config). */
+    weekdays: string[];
+    /** Explicit blocks that remove a day / weekday / range. */
+    blocks: Array<{
+        type: 'date';
+        date: string;
+    } | {
+        type: 'range';
+        start: string;
+        end: string;
+    } | {
+        type: 'weekday';
+        weekday: string;
+    }>;
+    /** Dates (YYYY-MM-DD) force-opened even if outside the weekly rule. */
+    overrideDates: string[];
+    /** How many days ahead bookings are accepted. */
+    windowDays: number;
+    /** Minimum lead time before the earliest bookable slot. */
+    leadTimeMinutes: number;
+}
+type PreorderDepositType = 'percent' | 'fixed';
+interface PublicProductVariant {
+    ref: string;
+    name: string;
+    priceMinor: number;
+    compareAtMinor: number | null;
+    currency: string;
+    /** Accepted-secondary prices (multi-currency); excludes the primary `currency`. The storefront picks
+     *  the price matching the buyer's selected currency and hides the variant when there's no match. */
+    prices?: VariantPrice[];
+    media: string[];
+    /** EFFECTIVE sold-out: the merchant declared it (variant or product master) OR the tracked stock ran
+     *  out. Shown but not purchasable — and while sold out the chip STAYS selectable, because a saver still
+     *  has to pick which variant their plan (and its locked price) is for. */
+    soldOut: boolean;
+    /**
+     * Units a buyer may still put in the cart. `null` = untracked stock, so no cap at all (the ∞ the
+     * portal shows). A tracked variant sends `stockQty - reservedQty`, and 0 whenever it reads sold out
+     * for any reason. The storefront caps its quantity stepper on this and only reveals the number once
+     * it drops to `LOW_STOCK_THRESHOLD` or below.
+     */
+    availableQty?: number | null;
+    /** '#RRGGBB' for the colour swatch; null under 'color' mode falls back to a text chip. */
+    swatchHex?: string | null;
+    description?: string | null;
+    badge?: string | null;
+    features?: PackageFeature[];
+    fineprint?: string | null;
+    durationMinutes?: number | null;
+    pricingMode?: ProductPricingMode | null;
+    /** Effective scheduling mode for this option (its own override, else the product default). null = not scheduled. */
+    schedulingType?: 'slots' | 'single_date' | 'date_range' | null;
+    /** Effective availability summary so the calendar can block unavailable days. null = not scheduled. */
+    availability?: StoreAvailabilitySummary | null;
+    /** Local dates (YYYY-MM-DD) already fully booked for this option, so the calendar can block them. */
+    takenDates?: string[];
+    /** Extra checkout questions for THIS option (asked in addition to the product-level questions). */
+    formFields?: BookingFormField[];
+}
+interface PublicProduct {
+    ref: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    coverUrl: string | null;
+    needsDelivery: boolean;
+    currency: string;
+    /** Who-pays override for the FrontDesk charge (FD-CHG). null = inherit the store default. */
+    feeMode?: ChargeMode | null;
+    /** Lowest available variant price (minor). */
+    priceMinorFrom: number | null;
+    /** Gallery: cover + variant media, de-duped. */
+    media: string[];
+    variants: PublicProductVariant[];
+    isPackage?: boolean;
+    selectionMode?: SelectionMode;
+    /** How the option picker is drawn: text chips (default), image swatches, or colour swatches. */
+    variantDisplay?: VariantDisplay;
+    schedulingEnabled?: boolean;
+    /** Add-on groups the buyer can pick from (option-scoped groups carry variantRef). */
+    addonGroups?: ProductAddonGroup[];
+    /** Product-level checkout questions (asked on every option; merged with the option's own extras). */
+    formFields?: BookingFormField[];
+    /** Buyers may start an installment plan toward this product (shown even when it's sold out). */
+    saveForItEnabled?: boolean;
+    /** Rolling window ceiling in DAYS (decision 11a); the finish-date picker is capped at start + this. */
+    saveForItMaxDays?: number | null;
+    /** Fixed cohort finish dates (ISO, decision 11b) the buyer can pick instead of a rolling date. */
+    saveForItFixedDates?: string[];
+    /** Whether the price is frozen for savers (default true). Off = live price at checkout, saved balance
+     *  applied as a credit. Drives the disclosure the buyer sees at plan start. */
+    saveForItFreezePrice?: boolean;
+    /** Fuzzed social proof for the savings panel — "About 100 people". Already vague when it reaches the
+     *  browser (the real count is never sent) and null whenever the crowd is too small, the store opted out,
+     *  or Ops switched it off. Only present on the product DETAIL fetch, never on list payloads. */
+    saveForItCrowdLabel?: string | null;
+    /** Resolved server-side: a plan can actually be started right now. Enabled, and — when the product is
+     *  sold out — backorders are on AND the unit cap still has room. The storefront gates the whole save
+     *  path on this rather than on `saveForItEnabled`, so a closed backorder reads as a plain sold-out item
+     *  instead of offering a plan that would be rejected at submit. */
+    saveForItSaveable?: boolean;
+    /** Resolved server-side: a buyer can pre-order this RIGHT NOW. Sold out, the switch on, and the unit
+     *  cap still has room. The storefront gates its whole pre-order path on this, so a full pre-order book
+     *  reads as a plain sold-out item instead of offering a checkout that would be rejected. */
+    preorderable?: boolean;
+    /** The merchant's free-text promise, shown wherever the buyer is committing ("Ships in 4 to 6 weeks").
+     *  Absent when they did not write one. */
+    preorderEtaText?: string | null;
+    /** Units still open against the pre-order cap (`preorderLimit - unitsCommitted`). The storefront caps
+     *  its quantity stepper on THIS while pre-ordering, since `availableQty` is 0 by definition — without
+     *  it a buyer could build a basket of 50 that checkout would reject. Absent when not pre-orderable. */
+    preorderRemaining?: number | null;
+    /** PO-2 — the deposit RULE when this pre-order takes one; absent means pay in full. Sent as the rule
+     *  rather than an amount because the deposit is struck on the order total (delivery included), which a
+     *  product page cannot know: "Pay 25% now" is exact, a guessed figure would drift from the charge. */
+    preorderDepositType?: PreorderDepositType | null;
+    /** Whole percent under 'percent'; minor units of `currency` under 'fixed'. */
+    preorderDepositValue?: number | null;
+    /** Effective sold-out for the product as a whole (declared or every variant gone). */
+    soldOut?: boolean;
+    /** Full review aggregate for the detail page: header stars, distribution bars, and the cached AI
+     *  summary. Absent when the store has reviews off or the cold-start floor is not met. */
+    reviews?: ProductReviewAggregate;
+    /** The store's reviews toggle, resolved server-side. Drives whether the product page renders the
+     *  reviews block under the Similar strip at all. */
+    reviewsEnabled?: boolean;
+    /** PV-117: the store's restock-alert toggle, resolved server-side. The storefront offers "Email me
+     *  when it is back" only on a DEAD END — sold out with `saveForItSaveable` false — so a page that can
+     *  still start a savings plan keeps that as its one call to action. */
+    restockAlertsEnabled?: boolean;
+    /** Drives the brand byline, the always-visible description prose and the accordion sections on the
+     *  product page, plus the schema.org Product block. Absent when the merchant has added nothing, so the
+     *  storefront can skip the whole block on a bare product. HS code is stripped (merchant-only). */
+    info?: PublicProductInfo;
+}
+/** Bookable slots for one scheduled product on one date. */
+interface PublicProductSlots {
+    date: string;
+    slots: Array<{
+        startUtc: string;
+        startLocal: string;
+    }>;
+}
+/**
+ * Live availability for the variants a cart already holds — a cart is localStorage, so its lines can be
+ * days old by the time the buyer comes back. Keyed by variantRef: units left, or null when stock is
+ * untracked (no cap). A variantRef that is missing from the map no longer exists or is no longer
+ * purchasable, and the cart drops the line.
+ */
+interface PublicStoreAvailability {
+    variants: Record<string, number | null>;
+    /**
+     * Variant refs whose product is PRE-ORDERABLE right now (PO-1). Their `variants` entry is 0 — a
+     * pre-orderable product is sold out by definition — but the line is still perfectly purchasable, so
+     * the cart must neither drop it nor clamp it to zero. Instead it caps on `preorderRemaining` below.
+     */
+    preorderable?: string[];
+    /** Units still open against each pre-orderable product's cap, keyed by VARIANT ref for the cart's
+     *  convenience (the cap itself is product-level, so sibling variants share a figure). */
+    preorderRemaining?: Record<string, number>;
+}
+interface PublicProductSummary {
+    ref: string;
+    name: string;
+    slug: string;
+    /** Distinguishes bookable services/packages from standard retail products. */
+    isPackage?: boolean;
+    coverUrl: string | null;
+    currency: string;
+    priceMinorFrom: number | null;
+    /** Cheapest available price per accepted-secondary currency (minor units), for the storefront card when
+     *  the buyer switches currency. Keyed by ISO code; excludes the primary `currency`. A currency absent
+     *  here (and ≠ primary) means the product isn't sold in it → the card hides it. */
+    pricesFrom?: Record<string, number>;
+    /** Compare-at of the cheapest available variant (primary currency) — drives the storefront card's
+     *  strikethrough + "% OFF" badge; null when not on sale. */
+    compareAtMinorFrom: number | null;
+    /** Compare-at "from" per accepted-secondary currency (minor units), aligned with `pricesFrom` so the
+     *  badge/strikethrough stay correct after a currency switch. Keyed by ISO code; excludes the primary. */
+    compareAtFrom?: Record<string, number>;
+    /** Resolved: show the "% OFF" discount badge for this product (product override ?? store default). The
+     *  storefront still only renders it when the product is actually on sale. */
+    showSaleBadge?: boolean;
+    /** Number of variants — when > 1 the storefront card shows the price as "From ₦X". */
+    variantCount: number;
+    soldOut: boolean;
+    /** A plan can be started from this card's product right now (see PublicProduct.saveForItSaveable). Drives
+     *  the green "Save for it" pill, which REPLACES the "Sold out" pill on a sold-out card — the card keeps
+     *  its full colour and the sold-out fact moves to the price line, because the item is still gettable. */
+    saveForItSaveable?: boolean;
+    /** A buyer can pre-order this card's product right now (see PublicProduct.preorderable). Drives the
+     *  PRE-ORDER pill, which like the save pill REPLACES the grey sold-out one — the item is still gettable. */
+    preorderable?: boolean;
+    /** Review average (1 decimal) for the card's star line. Absent when the store's cold-start floor is not
+     *  met — the card then shows no stars at all, rather than a 5.0 built from one review. */
+    ratingAvg?: number;
+    /** Published review count behind `ratingAvg`. Absent under the floor, for the same reason. */
+    ratingCount?: number;
+}
+type CollectionCoverKind = 'image' | 'video';
+/** Buyer-facing collection in the storefront payload / public endpoints. */
+interface PublicCollectionSummary {
+    ref: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    coverUrl: string | null;
+    coverKind: CollectionCoverKind | null;
+    gallery: string[];
+    /** Ordered refs into the storefront's public product summaries — membership already resolved
+     *  (manual order or sort preset applied) and filtered to publicly visible products. */
+    productRefs: string[];
+    itemCount: number;
+    seoTitle: string | null;
+    seoDescription: string | null;
+}
+/** A delivery zone's fee in ONE currency. Public payloads carry one per accepted currency (`prices`):
+ *  the authored-currency row is the exact fee, the rest are FX-converted (rounded up clean). */
+interface ZoneFee {
+    currency: string;
+    feeMinor: number;
+}
+interface DeliveryZone {
+    ref: string;
+    name: string;
+    /** The fee in the zone's authored `currency`. */
+    feeMinor: number;
+    /** The currency `feeMinor` is authored in (the store primary when the zone was created). */
+    currency: string;
+    sort: number;
+    /** Public (storefront) payload only: the fee FX-converted into every accepted currency, so the
+     *  checkout can switch currency instantly without a refetch. The authored-currency entry is exact;
+     *  the rest are `convertMinor` + `roundUpCleanMinor`. Omitted on portal/admin (single-currency)
+     *  payloads and on single-currency stores. */
+    prices?: ZoneFee[];
+}
+interface StoreCheckoutItem {
+    variantRef: string;
+    quantity: number;
+}
+interface StoreCheckoutContact {
+    name: string;
+    email: string;
+    phone?: string | null;
+}
+interface StoreShippingAddress {
+    addressLine1: string;
+    addressLine2?: string | null;
+    city: string;
+    state?: string | null;
+    country?: string | null;
+    /** Buyer's pinned delivery coordinates (optional; from the checkout map). */
+    lat?: number | null;
+    lng?: number | null;
+}
+
+/**
+ * Packages — sellable offerings + priced tiers (options). Spec §13.1, §10.18 (PV-012/054).
+ *
+ * A Package is the top-level offering (type product/service/consultation/rental). It owns 1..N
+ * Options (tiers like Basic/Standard/Premium). A package with one option = a flat offering
+ * (D-11). Each option carries its own pricing, an optional attached Booking Form (scheduling +
+ * intake, §12), and an occupancy mode (exclusive vs shared) used by the unified calendar later.
+ */
+
+type PackagePricingMode = 'full_payment' | 'deposit' | 'free' | 'request';
+type AddonSelectionType = 'single' | 'multi';
+/** inline = a typed-in extra; linked = points at another package (price-only in v1). */
+type AddonOptionKind = 'inline' | 'linked';
+/** A "what's included" line. `included` distinguishes a green tick from a muted cross (not included). */
+interface PackageFeature {
+    text: string;
+    included: boolean;
+}
+
+/**
+ * Hosted checkout (Storefront API Surface B, §8). D2: hosted now, headless later.
+ *
+ * The split that makes this safe: the merchant's SERVER declares WHAT is being bought, and the BUYER
+ * chooses HOW to pay, on a FrontDesk page. That is why there is no `provider` here — payment method,
+ * card entry, Paystack inline, PVB transfer, Save For It credit and every rail behind them stay on
+ * our origin, so a merchant-built frontend never touches money and we add no new money code.
+ *
+ * The flow:
+ *   1. their server POSTs /v1/store/checkouts with an Idempotency-Key  -> { ref, hostedUrl, expiresAt }
+ *   2. they redirect the buyer to hostedUrl (our origin, their brand if a checkout host is connected)
+ *   3. the buyer pays with the existing storefront checkout
+ *   4. we redirect to their returnUrl?checkout=<ref>
+ *   5. their server confirms via GET /v1/store/checkouts/:ref, or the checkout.completed webhook
+ *
+ * Step 5 matters: the return redirect is a browser navigation and can be lost, faked or replayed, so
+ * it is a UX signal only. NEVER fulfil on the redirect — confirm server-side.
+ */
+type StoreCheckoutSessionStatus = 'open' | 'completed' | 'expired' | 'cancelled';
+/**
+ * 'test' sessions are opened by an `fd_sk_test_…` key and can be completed WITHOUT paying, so an
+ * integration is buildable without a bank account.
+ *
+ * 🔴 A test checkout deliberately produces NO order, NO wallet credit and NO ledger posting. It
+ * proves the INTEGRATION LOOP (open → hosted page → return → confirm → webhook), not fulfilment.
+ * That boundary is the point: the alternative is a second, fake money path beside the real one, and
+ * only provider-verified inflows may ever credit a wallet.
+ */
+type StoreCheckoutMode = 'live' | 'test';
+/** What a merchant's server sends to open a checkout. */
+interface StoreCheckoutSessionInput {
+    items: StoreCheckoutItem[];
+    /** Prefills the hosted page. The buyer can still correct it before paying. */
+    contact?: Partial<StoreCheckoutContact> | null;
+    deliveryZoneRef?: string | null;
+    shipping?: StoreShippingAddress | null;
+    /** Must be a currency the store accepts. Omit for the store primary. */
+    currency?: string | null;
+    /** Where we send the buyer after payment. Must be https (or localhost while testing). */
+    returnUrl: string;
+}
+/** One attendee on a ticket line. `responses` answers that tier's `formFields`. */
+interface StoreTicketAttendee {
+    name?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    /** YYYY-MM-DD. Required when the event or tier sets an age gate and dobMode is per attendee. */
+    dateOfBirth?: string | null;
+    responses?: Record<string, unknown> | null;
+}
+interface StoreTicketItem {
+    ticketTypeRef: string;
+    quantity: number;
+    /** Donation tiers only. Per ticket, in minor units, and must clear the tier floor. */
+    amountMinor?: number | null;
+    /** Length = quantity x groupSize. Omit to keep every seat under the buyer. */
+    attendees?: StoreTicketAttendee[] | null;
+}
+/**
+ * Opening a ticket checkout (D18).
+ *
+ * D19: the merchant COLLECTS attendee data, the server still VALIDATES all of it. What to collect is
+ * discoverable per tier on GET /v1/store/events/:slug: `formFields`, `requiresAttendeeDetails`,
+ * `groupSize`, `minPerOrder`/`maxPerOrder`, plus `minAge`/`dobMode` on the event.
+ */
+interface StoreEventCheckoutInput {
+    tickets: StoreTicketItem[];
+    /** Products already attached to this event. Not the general catalogue. */
+    products?: StoreCheckoutItem[] | null;
+    contact: StoreCheckoutContact;
+    /** Buyer DOB, when the event uses order-level age checks. YYYY-MM-DD. */
+    dateOfBirth?: string | null;
+    /** Order-level answers to the event's own questions. */
+    responses?: Record<string, unknown> | null;
+    discountCode?: string | null;
+    /** Reveals hidden and invite-only tiers. Re-verified server-side. */
+    unlockCodes?: string[] | null;
+    /** Affiliate attribution from a ?p=CODE share link. Ignored silently if unknown. */
+    promoterCode?: string | null;
+    currency?: string | null;
+    returnUrl: string;
+}
+/**
+ * Headless ticket checkout (§16). The organizer owns the entire UI, including the payment picker.
+ *
+ * The rail is named HERE rather than every rail being minted up front: three live payment paths on
+ * one order means a buyer can pay by card AND transfer, and refunds are merchant-manual. Fetch the
+ * rails with GET /v1/store/payment-methods, render your own picker, then call this with the choice.
+ */
+interface StoreHeadlessCheckoutInput extends Omit<StoreEventCheckoutInput, 'returnUrl'> {
+    provider: StorePaymentMethod;
+    /** Where a redirecting rail (Stripe) returns the buyer. Ignored by rails that stay in place. */
+    returnUrl?: string | null;
+}
+interface StoreHeadlessCheckoutView {
+    ref: string;
+    orderRef: string;
+    status: StoreCheckoutSessionStatus;
+    mode: StoreCheckoutMode;
+    amount: {
+        subtotalMinor: number;
+        feeMinor: number;
+        totalMinor: number;
+        currency: string;
+    };
+    provider: StorePaymentMethod;
+    payment: {
+        /** Paystack: open the inline popup with this. The card fields are Paystack's, never yours. */
+        accessCode?: string | null;
+        /** Stripe: send the buyer here. */
+        checkoutUrl?: string | null;
+        /** Bank transfer: attached once the provider confirms it, so poll if it is null. */
+        account?: {
+            accountNumber: string;
+            accountName: string | null;
+            bankName: string | null;
+        } | null;
+        reference: string | null;
+    };
+    expiresAt: string;
+}
+/** What they get back, and what GET /v1/store/checkouts/:ref returns thereafter. */
+interface StoreCheckoutSessionView {
+    ref: string;
+    status: StoreCheckoutSessionStatus;
+    /** Set from the KEY that opened it, never chosen by the caller. */
+    mode: StoreCheckoutMode;
+    /** Send the buyer here. Valid until `expiresAt`. */
+    hostedUrl: string;
+    returnUrl: string;
+    currency: string | null;
+    /**
+     * The order this became, once the buyer paid. Null while open.
+     *
+     * On a TEST session this is a synthetic `test_ord_…` ref that resolves to no real order, because a
+     * test checkout never creates one. Do not try to fetch it.
+     */
+    orderRef: string | null;
+    expiresAt: string;
+    completedAt: string | null;
+    createdAt: string;
+}
+
+/** A resolved commission rate (after applying any per-workspace override over the platform default). */
+interface EventCommissionConfig {
+    /** Percentage cut on the gross (0..100). */
+    pct: number;
+    /** Flat fee in minor units added on top of the percentage cut. */
+    flatMinor: number;
+}
+
+/** One slot type at launch; secondary slots (category sponsor, media partner) are a data change later. */
+type SponsorshipSlotType = 'official_ticket_sponsor';
+/** The public branding payload injected into event pages / checkout / ticket surfaces. */
+interface PublicEventSponsorship {
+    slotType: SponsorshipSlotType;
+    brandName: string;
+    logoUrl: string | null;
+    tagline: string | null;
+    clickUrl: string | null;
+    sponsorshipRef: string;
+    /** Already contrast-clamped server-side via `sponsorQrColor()` — safe to render as-is. */
+    qrColor?: string | null;
+    /** The banner creative. When present it IS the placement; the text lockup is the fallback. */
+    bannerUrl?: string | null;
+}
+
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+
+interface PublicPackageSummary {
+    ref: string;
+    type: string;
+    name: string;
+    slug: string;
+    coverUrl: string | null;
+    priceMinorFrom: number | null;
+    currency: string | null;
+    optionCount: number;
+}
+interface PublicPackageOption {
+    ref: string;
+    name: string;
+    pricingMode: 'full_payment' | 'deposit' | 'free' | 'request';
+    priceMinor: number | null;
+    compareAtMinor: number | null;
+    currency: string;
+    badge: string | null;
+    /** Option images; the first is used as the card image when the section uses the "Media" card style. */
+    media?: string[];
+    features: Array<{
+        text: string;
+        included: boolean;
+    } | string>;
+    /** Optional fine print (terms / small print) shown under the package. */
+    fineprint: string | null;
+    occupancyMode: 'exclusive' | 'shared';
+    schedulingType: 'slots' | 'single_date' | 'date_range' | null;
+    /** Availability summary so the checkout calendar can grey out unavailable days. */
+    availability?: {
+        weekdays: string[];
+        blocks: Array<{
+            type: 'date';
+            date: string;
+        } | {
+            type: 'range';
+            start: string;
+            end: string;
+        } | {
+            type: 'weekday';
+            weekday: string;
+        }>;
+        overrideDates: string[];
+        windowDays: number;
+        leadTimeMinutes: number;
+    } | null;
+    /** Effective add-ons for this option (its own override if any, else the package default). */
+    addonGroups?: PublicAddonGroup[];
+    /** Custom checkout questions for this option (Phase B). The renderer evaluates showIf client-side. */
+    formFields?: BookingFormField[];
+    /** Local dates (YYYY-MM-DD) already fully booked for this option, so the calendar can block them. */
+    takenDates?: string[];
+}
+/** A selectable add-on option (linked options arrive with their name/price already resolved). */
+interface PublicAddonOption {
+    ref: string;
+    kind: 'inline' | 'linked';
+    label: string;
+    description: string | null;
+    priceMinor: number;
+    imageUrl: string | null;
+    allowQuantity: boolean;
+    maxQty: number | null;
+    linkedPackageRef: string | null;
+    linkedOptionRef: string | null;
+}
+/** A group of add-on options (single = pick one, multi = pick any within min/max). */
+interface PublicAddonGroup {
+    ref: string;
+    name: string;
+    selectionType: 'single' | 'multi';
+    required: boolean;
+    minSelect: number | null;
+    maxSelect: number | null;
+    sort: number;
+    options: PublicAddonOption[];
+}
+interface PublicPackage {
+    ref: string;
+    type: string;
+    name: string;
+    slug: string;
+    description: string;
+    coverUrl: string | null;
+    currency: string;
+    options: PublicPackageOption[];
+    /** Service-level add-on groups shown in checkout (empty when none). May be absent on older payloads. */
+    addonGroups?: PublicAddonGroup[];
+    brand: {
+        ref: string;
+        displayName: string;
+        avatarUrl: string | null;
+    } | null;
+    storefrontPublished?: boolean;
+}
+interface PublicCollectionDetail {
+    collection: PublicCollectionSummary;
+    products: PublicProductSummary[];
+}
+
+/**
+ * Save For It — a buyer saves toward a purchase over time; the money sits in walletless escrow neither
+ * side can spend; the merchant is paid on completion (design: services/design-docs/saveforit.md).
+ * First slice: invoices, manual top-up (no auto-debit, no card-on-file).
+ */
+
+/** How a seat is held against capacity while a buyer saves toward a ticket (decision D-14, per event): none
+ *  (save freely, refund/credit if it sells out) · from_start (reserve immediately) · threshold (reserve once
+ *  saved ≥ the threshold %). */
+type SaveForItHoldPolicy = 'none' | 'from_start' | 'threshold';
+/** Which price a ticket saver pays: freeze the price at plan start, or the tier live at completion. */
+type SaveForItPriceMode = 'freeze' | 'current';
+/** The resolved (event default ← per-ticket-type override) Save For It config for one ticket type. */
+interface EventTicketSaveForItConfig {
+    enabled: boolean;
+    holdPolicy: SaveForItHoldPolicy;
+    holdThresholdPct: number;
+    priceMode: SaveForItPriceMode;
+    cutoffHours: number;
+}
+
+/** The event's primary intent — tailors the builder, the public flow, and the CTA (doc 48 §1). */
+type EventMode = 'rsvp' | 'ticketed' | 'registration' | 'mixed';
+type EventFormat = 'physical' | 'online' | 'hybrid';
+/** Who supplies the date of birth when an event has an age restriction. */
+type EventDobMode = 'order' | 'attendee';
+interface EventMediaItem {
+    type: 'image' | 'video';
+    url: string;
+    thumbnail?: string;
+}
+/** Where the event happens. Physical fields + an online URL; a hybrid event uses both. */
+interface EventLocation {
+    venueName: string | null;
+    address: string | null;
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    lat: number | null;
+    lng: number | null;
+    onlineUrl: string | null;
+    onlineProvider: string | null;
+}
+/** Who may see the exact venue (venue name / address / map pin / online link). `public` = everyone
+ *  (default, today's behaviour); `confirmed_only` = stripped from the public page + pending/waitlist
+ *  comms, revealed only to attendees whose spot is confirmed (organizer feedback 2026-07-03). The
+ *  coarse area (city/state/country) stays public either way so buyers know where it roughly is. */
+type EventVenueVisibility = 'public' | 'confirmed_only';
+/** Public day (storefront schedule). */
+interface PublicEventDay {
+    ref: string;
+    label: string;
+    dayDate: string | null;
+    startAt: string | null;
+    endAt: string | null;
+    /** Per-day timezone override (IANA). Null = the event's timezone. */
+    timezone: string | null;
+    /** Per-day location override (null = the event's location). Exact-venue fields are stripped
+     *  server-side for unconfirmed viewers when the event is `confirmed_only`, same as the event's. */
+    location: EventLocation | null;
+    /** Day-level capacity (null = unlimited). */
+    capacity: number | null;
+    /** Admissions still available on this day (null = unlimited). */
+    remaining: number | null;
+    /** True when the day's overall capacity is full (independent of per-ticket stock). */
+    soldOut: boolean;
+}
+type EventTicketKind = 'free' | 'paid' | 'donation' | 'deposit';
+/** Where a deposit ticket's remaining balance is settled. `door` = the organizer collects it in
+ *  person (no money moves through FrontDesk); `online` = the buyer clears it on the order page
+ *  before the cutoff, or the seat is released and the deposit forfeited. */
+type EventDepositBalanceMode = 'door' | 'online';
+/** Who pays FrontDesk's ticket charge for this ticket type. */
+type EventTicketFeeMode = 'absorb' | 'pass_on';
+/** Lightweight event card for the storefront section + listing. */
+interface PublicEventSummary {
+    ref: string;
+    title: string;
+    slug: string;
+    tagline: string | null;
+    coverUrl: string | null;
+    format: EventFormat;
+    mode: EventMode;
+    startAt: string | null;
+    endAt: string | null;
+    /** When the event was first published — used by the storefront "recent" (newest added) sort. */
+    publishedAt: string | null;
+    /** Venue name + city compose the storefront card location line ("Venue, City"). */
+    venueName: string | null;
+    city: string | null;
+    category: string | null;
+}
+/** A sellable/registerable ticket type as seen publicly (public-visibility free + paid; PV-073). */
+interface PublicEventTicketType {
+    ref: string;
+    name: string;
+    description: string | null;
+    /** Optional cover image (hosted URL); null when none. */
+    imageUrl: string | null;
+    kind: EventTicketKind;
+    /** pass_on (default) = this ticket's amount is included in the event-level customer checkout charge;
+     *  absorb = exempt (organizer bears the FrontDesk charge on it). */
+    frontdeskFeeMode: EventTicketFeeMode;
+    /** Per-ticket price in minor units (0 for free) — the EFFECTIVE price now (early-bird applied). */
+    priceMinor: number;
+    currency: string;
+    /** Accepted-secondary prices (multi-currency, flat — no windows). The buyer's switcher resolves the
+     *  shown price via `resolveVariantPrice`; a ticket with no row in the selected currency is hidden. */
+    prices?: VariantPrice[];
+    /** Optional struck-through compare-at price (minor units). */
+    compareAtMinor: number | null;
+    /** DONATION — the floor the buyer's typed amount must clear. Null = any amount above zero. The
+     *  amount is per ticket: the quantity stepper multiplies it. */
+    minPriceMinor: number | null;
+    /** DONATION — suggested amounts (minor units) rendered as chips beside the "Other amount" box. */
+    donationPresets: number[];
+    /** DEPOSIT — the rule splitting `priceMinor` into a part paid now and a balance owed later. */
+    depositType: 'percent' | 'fixed' | null;
+    depositValue: number | null;
+    /** DEPOSIT — what one ticket charges today, resolved from the rule against the live price. The
+     *  storefront shows this as the CTA amount; the balance is `priceMinor - depositDueNowMinor`. */
+    depositDueNowMinor: number | null;
+    /** DEPOSIT — where the balance is settled, and (online mode) the resolved cutoff instant, derived
+     *  from the event start minus the ticket's days-before setting. Null cutoff = door mode. */
+    depositBalanceMode: EventDepositBalanceMode | null;
+    depositBalanceDueAt: string | null;
+    /** When the current early-bird/timed price ends (ISO), for a "price goes up on …" hint; null = no schedule. */
+    priceEndsAt: string | null;
+    /** Tickets left at the CURRENT early-bird price (its quantity cap minus sold); null = uncapped / no window. */
+    priceRemaining: number | null;
+    capacity: number | null;
+    soldCount: number;
+    remaining: number | null;
+    soldOut: boolean;
+    /** Resolved low-stock threshold (per-ticket override → event default → 10). Show "Only N left" when
+     *  remaining ≤ this and > 0; 0 = never show. */
+    lowStockThreshold: number;
+    /** Quantity bounds per order (the box-office stepper clamps to these + `remaining`). */
+    minPerOrder: number;
+    maxPerOrder: number | null;
+    /** Effective minimum age for this ticket (max of event + type; 0 = no restriction). */
+    minAge: number;
+    approvalRequired: boolean;
+    /** Admissions issued per unit (1 = normal; >1 = group/table ticket that explodes into N seats). */
+    groupSize: number;
+    /** Day labels this ticket admits (empty = all days = "Full pass"). Multi-day. */
+    validDays: string[];
+    /** Whether each seat must be named at checkout (vs. allowing "keep all under the buyer"). */
+    requiresAttendeeDetails: boolean;
+    /** Per-ticket custom questions (visible ones; showIf evaluated client-side). */
+    formFields: BookingFormField[];
+    /** PV-106 Save For It — the RESOLVED (event default ← type override) config for this ticket. */
+    saveForIt: EventTicketSaveForItConfig;
+    /** Whether the storefront should offer "Save for it" on this ticket: enabled + priced at/above the
+     *  platform minimum. The saver commits to the frozen (or live-at-completion) price of `saveForIt`. */
+    saveForItSaveable: boolean;
+}
+interface PublicEvent {
+    ref: string;
+    title: string;
+    slug: string;
+    tagline: string | null;
+    description: string | null;
+    mode: EventMode;
+    format: EventFormat;
+    /** When `venueVisibility` is `confirmed_only`, the exact-venue fields (venueName/address/lat/lng/
+     *  onlineUrl) arrive null here — only the coarse area remains. */
+    location: EventLocation;
+    /** `confirmed_only` = the page should say the exact venue is shared once the spot is confirmed. */
+    venueVisibility: EventVenueVisibility;
+    timezone: string | null;
+    startAt: string | null;
+    endAt: string | null;
+    doorsAt: string | null;
+    capacity: number | null;
+    coverUrl: string | null;
+    media: EventMediaItem[];
+    category: string | null;
+    /** Event-level minimum age (0 = none); per-ticket effective age is on each ticket type. */
+    minAge: number;
+    /** Who supplies the DOB when an age check applies. */
+    dobMode: EventDobMode;
+    /** Require an email from every ticket holder (vs just the buyer). */
+    attendeeEmailRequired: boolean;
+    /** Current FrontDesk ticket-charge rate so checkout can preview passed-through charges. */
+    frontdeskFee: EventCommissionConfig;
+    /** RESOLVED event-level customer checkout charge (organizer override or the FrontDesk rate). Applies
+     *  once to the non-exempt ticket amount of a checkout. */
+    customerFee: EventCommissionConfig;
+    /** The customer-charge FLAT component FX-converted (rounded up clean) into each accepted SECONDARY
+     *  currency, so the client fee preview matches the server's converted charge. Absent for
+     *  single-currency stores or currencies with no configured rate (treat as unavailable). */
+    customerFeeFlatByCurrency?: Record<string, number>;
+    /** Named days for a multi-day event (empty = single-day). Drives the day-pass labels. */
+    days: PublicEventDay[];
+    /** PV-106 Save For It — the event master switch. A ticket is only saveable when this is on AND that
+     *  ticket's own `saveForItSaveable` is true; use for the section-level "Save for it available" copy. */
+    saveForItEnabled: boolean;
+    /** Fuzzed social proof for the savings panel — "About 100 people". Counts savers across ALL of this
+     *  event's ticket types, arrives ALREADY vague (the real count never reaches the browser), and is null
+     *  whenever the crowd is too small, the organizer opted out, or Ops switched it off. */
+    saveForItCrowdLabel?: string | null;
+    ticketTypes: PublicEventTicketType[];
+    /** Packages the organizer attached to sell alongside tickets (PV-082) — active + public only,
+     *  bought via the package's own page + checkout. Empty when none. */
+    attachedPackages: PublicEventPackage[];
+    /** Store products the organizer attached (Store epic) — active + public only, shown under tickets.
+     *  Full products (with variants) so they can be added to the combined event cart (Phase 5b: tickets +
+     *  products in one order, one payment). Empty when none. */
+    attachedProducts: PublicProduct[];
+    brand: {
+        ref: string;
+        displayName: string;
+        avatarUrl: string | null;
+        handle: string | null;
+    };
+    /** Whether the workspace storefront is published (so the page can render in-chrome). */
+    storefrontPublished: boolean;
+    /** FD-SPONS — the active Official Ticket Sponsor of this event, injected server-side ONLY while the
+     *  sponsorship is active. Null the moment it pauses/ends, so branding de-injects automatically. */
+    sponsorship?: PublicEventSponsorship | null;
+}
+/** A package attached to an event (PV-082) — rendered as its own container on the event page with its
+ *  options/tiers inline. The full public package (active + public only), reused from the package engine. */
+interface PublicEventPackage {
+    ref: string;
+    type: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    coverUrl: string | null;
+    currency: string;
+    /** The SAME shape a standalone public package serves: `publicForEvent` delegates to
+     *  `buildPublicPackage`/`serializePublicOption`, so scheduling + availability really are present.
+     *  Was `PublicEventPackageOption[]`, which under-declared it. */
+    options: PublicPackageOption[];
+}
+
+/** A choice in a select / multi_select column. */
+interface SelectOption {
+    id: string;
+    label: string;
+    color?: string;
+}
+
+/** Question input types. A strict SUBSET of the Tables column types (no relations) so every field maps
+ *  1:1 to a column. `formFieldToColumnType` is the (identity) bridge. */
+type FormFieldType = "text" | "long_text" | "number" | "currency" | "date" | "datetime" | "checkbox" | "select" | "multi_select" | "email" | "phone" | "url" | "file" | "multi_file";
+/** Which kinds of file a `multi_file` question accepts. */
+type FormFileKind = "image" | "document" | "any";
+/** Per-question file constraints for a `multi_file` question (stored in `FormField.options.file`). */
+interface FormFileConstraints {
+    /** Minimum number of files (also implied by `required` >= 1). null = no explicit minimum. */
+    minFiles?: number | null;
+    /** Maximum number of files allowed. null = no cap (bounded by MULTI_FILE_HARD_CAP). */
+    maxFiles?: number | null;
+    /** Accepted file kinds. Defaults to 'image'. */
+    kinds?: FormFileKind;
+}
+/** Fields flagged as identity drive the community-contact upsert (matched by email). */
+type FormFieldIdentity = "name" | "email" | "phone";
+/** A field as exposed on the PUBLIC page (no internal columnId leaked). */
+interface PublicFormField {
+    id: string;
+    label: string;
+    type: FormFieldType;
+    required: boolean;
+    helpText?: string | null;
+    placeholder?: string | null;
+    options?: {
+        choices?: SelectOption[];
+        file?: FormFileConstraints;
+    };
+    identity?: FormFieldIdentity | null;
+}
+/** FD.forms item baked into a custom_html frame's __FD_INIT__: the CTA-card basics plus enough of
+ *  the definition (fields + submit/thank-you copy) for the frame to render and client-validate a
+ *  bound form. `redirectUrl` is deliberately NOT baked — redirects are performed by the HOST page,
+ *  and frame script cannot top-navigate without user activation anyway. */
+interface CustomHtmlFormDef {
+    slug: string;
+    name: string;
+    description: string | null;
+    submitLabel: string | null;
+    thankYouMessage: string;
+    fields: PublicFormField[];
+}
+
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+interface PublicCatalogItem {
+    ref: string;
+    type: 'image' | 'video';
+    url: string;
+    thumbnailUrl: string | null;
+    title: string;
+    description: string;
+    linkUrl: string | null;
+    tags: string[];
+    width: number | null;
+    height: number | null;
+}
+interface PublicCatalog {
+    catalog: {
+        name: string;
+        slug: string;
+        description: string;
+        allowDownloads: boolean;
+        fullScreenMasonry: boolean;
+        showGalleryName: boolean;
+        showGalleryDescription: boolean;
+        seoIndexable: boolean;
+        /** 'media_catalog' gallery vs 'mood_board' (renders the brief strip). */
+        type?: 'media_catalog' | 'mood_board' | 'standard';
+        /** Mood boards only: the AI-captured creative brief. */
+        brief?: {
+            theme?: string;
+            palette?: string[];
+            occasion?: string;
+            notes?: string;
+        } | null;
+    };
+    items: PublicCatalogItem[];
+    brand: {
+        ref: string;
+        displayName: string;
+        avatarUrl: string | null;
+    };
+    storefrontPublished: boolean;
+}
+/** A catalog hydrated into the storefront payload for catalog-bound sections (e.g. portfolio). */
+interface HydratedCatalog {
+    ref: string;
+    name: string;
+    slug: string;
+    description: string;
+    allowDownloads: boolean;
+    fullScreenMasonry: boolean;
+    showGalleryName: boolean;
+    showGalleryDescription: boolean;
+    visibility: 'public' | 'private';
+    publicPath: string;
+    itemCount: number;
+    coverUrl: string | null;
+    items: PublicCatalogItem[];
+}
+type PublicFileKind = 'image' | 'video' | 'pdf' | 'doc' | 'sheet' | 'slides' | 'audio' | 'file';
+interface PublicFolderFile {
+    ref: string;
+    fileKind: PublicFileKind;
+    url: string;
+    thumbnailUrl: string | null;
+    filename: string;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    width: number | null;
+    height: number | null;
+    createdAt: string;
+}
+interface PublicFolder {
+    folder: {
+        name: string;
+        slug: string;
+        description: string;
+        allowDownloads: boolean;
+        seoIndexable: boolean;
+    };
+    files: PublicFolderFile[];
+    brand: {
+        ref: string;
+        displayName: string;
+        avatarUrl: string | null;
+    };
+    storefrontPublished: boolean;
+}
+
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+
+/** A public trust signal on a storefront. */
+interface StorefrontBadge {
+    type: string;
+    grantedAt: string;
+}
+interface StorefrontSectionConfig {
+    id: string;
+    type: 'hero' | 'packages' | 'store' | 'events' | 'portfolio' | 'booking_cta' | 'reviews' | 'product_reviews' | 'about' | 'faq' | 'contact' | 'logo_strip' | 'image_text' | 'rich_text' | 'media_gallery' | 'content_showcase' | 'social' | 'form' | 'profiles' | 'collections' | 'custom_html' | 'newsletter';
+    visible: boolean;
+    hasBeenEdited?: boolean;
+    options?: Record<string, string | number | boolean | null>;
+}
+interface StorefrontPageConfig {
+    id: string;
+    type: 'home' | 'about' | 'contact' | 'gallery' | 'portfolio' | 'services' | 'menu' | 'vendors' | 'custom';
+    title: string;
+    slug: string;
+    visible: boolean;
+    metaTitle?: string;
+    sections: StorefrontSectionConfig[];
+    options?: Record<string, string | number | boolean | null>;
+}
+interface StorefrontButton {
+    id: string;
+    label: string;
+    visible: boolean;
+    fill?: 'solid' | 'outline';
+    bgColor?: string | null;
+    textColor?: string | null;
+    radius?: number | null;
+    fontScale?: number;
+    fontFamily?: string;
+    fontWeight?: number | null;
+    italic?: boolean;
+    underline?: boolean;
+    uppercase?: boolean;
+    /** Where the button points (canonical link engine). */
+    link: StorefrontLink;
+}
+/** A single composable content block (Composed hero, reusable). text=rich HTML, image/video=url,
+ *  media=an image/video playlist, buttons=a button row. width is a % of the row
+ *  (two <100 blocks sit side-by-side = a "split"). */
+interface StorefrontBlock {
+    id: string;
+    type: 'text' | 'image' | 'buttons' | 'video' | 'logos' | 'media' | 'testimonial' | 'divider' | 'chat' | 'social' | 'countdown' | 'profiles';
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+    /** Per-block vertical spacing in px (on top of the section's block gap). */
+    spaceTop?: number;
+    spaceBottom?: number;
+    /** false = hidden in the preview/live site (kept, not deleted). */
+    visible?: boolean;
+    /** Image/video/media blocks: rendered pixel width, opacity, monochrome tint, animation, and corner treatment. */
+    mediaWidth?: number;
+    mediaOpacity?: number;
+    mediaMono?: boolean;
+    mediaAnimate?: boolean;
+    mediaRadius?: 'sharp' | 'curved' | 'rounded';
+    /** Legacy numeric radius kept for older saved drafts. */
+    radius?: number;
+    /** Video blocks: false = normal player with sound + controls; absent/true = autoplay muted loop, no controls. */
+    autoplay?: boolean;
+    html?: string;
+    url?: string | null;
+    media?: Array<{
+        id: string;
+        type: 'image' | 'video';
+        url: string;
+    }>;
+    buttons?: StorefrontButton[];
+    /** Logos block: logo images + optional lead label, layout (row / marquee), monochrome tint, height (px). */
+    logos?: Array<{
+        id: string;
+        name: string;
+        imageUrl: string;
+        url?: string | null;
+        visible: boolean;
+    }>;
+    label?: string;
+    logoLayout?: 'row' | 'marquee';
+    logoMono?: boolean;
+    logoHeight?: number;
+    /** Logo corner radius preset: sharp (square) / curved (~8px) / rounded (pill). */
+    logoRadius?: 'sharp' | 'curved' | 'rounded';
+    /** Testimonial block: one or more quote cards with star rating + attribution. */
+    testimonials?: Array<{
+        id: string;
+        quote: string;
+        authorName: string;
+        authorRole: string;
+        rating?: number;
+        visible?: boolean;
+    }>;
+    /** Testimonial block styling. Unset = current default theme. */
+    testimonialPrimaryColor?: string;
+    testimonialBaseColor?: string;
+    testimonialBubbleColor?: string;
+    testimonialBubbleOpacity?: number;
+    testimonialBubbleWidth?: number;
+    testimonialBubbleHeight?: number;
+    testimonialBubblePadding?: number;
+    /** Divider block: horizontal rule with editable thickness, colour and stroke style. */
+    dividerHeight?: number;
+    dividerColor?: string;
+    dividerStyle?: 'solid' | 'dashed' | 'dotted';
+    /** FrontDesk Chat block: the AI greeting bubble + composer placeholder (behaviour lives in the
+     *  workspace's AI Front Desk Website policy, not here). */
+    chatGreeting?: string;
+    chatPlaceholder?: string;
+    /** Optional composer accent override: input border + send button. Empty = use storefront brand. */
+    chatAccentColor?: string;
+    /** Chat block: tap-to-ask starter prompts shown before a conversation starts. label = the short
+     *  pill text, message = the full question sent when tapped. The server grafts workspace defaults
+     *  onto chat blocks that have none, so the client just renders what it gets. */
+    chips?: Array<{
+        label: string;
+        message: string;
+    }>;
+    /** Social block: curated posts (inline, like chat's chips) + how they arrange. */
+    socialLayout?: SocialLayout;
+    socialItems?: SocialEmbedItem[];
+    /** Profiles block: people cards inline on the block (same item shape as profilesSections items). */
+    profiles?: Array<{
+        id: string;
+        name: string;
+        title: string;
+        tag?: string | null;
+        bio?: string | null;
+        imageUrl?: string | null;
+        socials?: Array<{
+            id: string;
+            platform: string;
+            url: string;
+            visible: boolean;
+        }>;
+        link?: StorefrontLink | null;
+        visible: boolean;
+    }>;
+    profilesLayout?: 'carousel' | 'grid' | 'marquee' | 'spotlight';
+    profilesShape?: 'square' | 'circle' | 'portrait' | 'arch';
+    profilesCardSize?: 'small' | 'medium' | 'large';
+    profilesColumns?: number;
+    profilesScrollSpeed?: 'slow' | 'medium' | 'fast';
+    profilesCardTextAlign?: 'auto' | 'left' | 'center';
+    profilesShowTitles?: boolean;
+    profilesShowTags?: boolean;
+    profilesShowBios?: boolean;
+    profilesShowSocials?: boolean;
+    countdownTargetAt?: string;
+    countdownUpDurationSeconds?: number;
+    countdownShowDays?: boolean;
+    countdownShowHours?: boolean;
+    countdownShowMinutes?: boolean;
+    countdownShowSeconds?: boolean;
+    countdownHeader?: string;
+    countdownHeaderPosition?: 'above' | 'below' | 'hidden';
+    countdownSubtext?: string;
+    countdownSubtextPosition?: 'above' | 'below' | 'hidden';
+    countdownCompletionText?: string;
+    countdownLayout?: 'plain' | 'cards';
+    countdownSeparator?: 'colon' | 'dot' | 'none';
+    countdownDayLabel?: string;
+    countdownHourLabel?: string;
+    countdownMinuteLabel?: string;
+    countdownSecondLabel?: string;
+    countdownBackgroundColor?: string;
+    countdownBackgroundOpacity?: number;
+    countdownBorderColor?: string;
+    countdownBorderWidth?: number;
+    countdownRadius?: number;
+    countdownPadding?: number;
+    countdownGap?: number;
+    countdownRevealBlockId?: string;
+    countdownHideAtZero?: boolean;
+    countdownTransition?: 'fade' | 'slide_up';
+    countdownCtaEnabled?: boolean;
+    countdownCta?: StorefrontButton;
+    countdownTrackAnalytics?: boolean;
+    countdownPreviewState?: 'live' | 'before' | 'countup' | 'completed';
+    /** Legacy single-card fields, kept so older drafts still render and can be migrated lazily. */
+    quote?: string;
+    authorName?: string;
+    authorRole?: string;
+    rating?: number;
+}
+interface StorefrontBlockGroup {
+    id: string;
+    label?: string;
+    width?: number;
+    /** column = shares a row with other groups; hero = spans the full Hero row. */
+    span?: 'column' | 'hero';
+    align?: 'left' | 'center' | 'right';
+    valign?: 'top' | 'center' | 'bottom';
+    /** Per-group margin in px, useful when rows/columns need breathing room independent of HGap/VGap. */
+    spaceTop?: number;
+    spaceRight?: number;
+    spaceBottom?: number;
+    spaceLeft?: number;
+    visible?: boolean;
+    blockIds: string[];
+}
+interface StorefrontHeaderLink {
+    id: string;
+    label: string;
+    /** Where the nav link points (canonical link engine — same as buttons). */
+    link: StorefrontLink;
+    visible: boolean;
+}
+interface StorefrontHeaderLinkStyle {
+    color: string | null;
+    fontScale: number;
+    weight: number | null;
+    uppercase: boolean;
+    /** Letter case for nav links. 'auto' = each layout's native look (sentence in the floating bars,
+     *  uppercase in the solid ones); anything else applies everywhere. */
+    textCase: 'auto' | 'sentence' | 'upper' | 'capitalize' | 'lower';
+    fontFamily: string;
+    italic: boolean;
+    underline: boolean;
+}
+interface StorefrontFieldStyle {
+    fontScale?: number;
+    hidden?: boolean;
+    color?: string | null;
+    opacity?: number;
+    fontFamily?: string;
+    fontWeight?: number | null;
+    italic?: boolean;
+    underline?: boolean;
+    uppercase?: boolean;
+    /** Unitless CSS line-height; null/absent = inherit the layout default. */
+    lineHeight?: number | null;
+    /** Max width of the text block in px; null/absent = auto. Controls how the field wraps. */
+    maxWidth?: number | null;
+    /** Per-field text alignment; null/absent = inherit the section's own alignment. Setting it makes
+     *  the field a full-width block so left/center/right actually take effect on an inline span. */
+    align?: 'left' | 'center' | 'right' | null;
+}
+interface StorefrontRenderConfig {
+    templateId: string;
+    theme: {
+        fontPairing: 'modern-sans' | 'editorial-serif' | 'compact-sans' | string;
+        palette: 'frontdesk' | 'midnight' | 'fresh' | 'mono' | string;
+        brandColor?: string | null;
+        /** Where the accent comes from: the palette (default) or the brand colour. */
+        accentSource?: 'brand' | 'palette';
+        spacing?: 'compact' | 'comfortable' | 'editorial';
+        contentWidth?: 'full' | 'standard' | 'compact' | 'thin';
+        /** User-created palettes (keys `custom-<slug>`); `palette` and band overrides may reference them. */
+        customPalettes?: Record<string, {
+            label?: string;
+            bg: string;
+            panel: string;
+            text: string;
+            muted: string;
+            line: string;
+            accent?: string;
+        }>;
+        /** User-created font pairings (keys `customfont-<slug>`); `fontPairing` and band overrides too. */
+        customFontPacks?: Record<string, {
+            label: string;
+            heading: {
+                stack: string;
+                weight: number;
+                letterSpacing: string;
+            };
+            body: {
+                stack: string;
+                weight: number;
+                letterSpacing: string;
+            };
+        }>;
+    };
+    sections: StorefrontSectionConfig[];
+    pages?: StorefrontPageConfig[];
+}
+interface StorefrontContent {
+    header: {
+        websiteTitle?: string;
+        logoText: string;
+        logoImageUrl?: string | null;
+        logoMode?: 'logo_text' | 'text' | 'logo';
+        logoHeight?: number;
+        logoSvg?: string | null;
+        logoSvgFill?: string | null;
+        logoSvgStroke?: string | null;
+        logoSvgStrokeWidth?: number;
+        faviconUrl?: string | null;
+        /** How a shared storefront link previews on WhatsApp/social. 'card' = a designed 1200x630 share
+         *  card (laid out by socialCardTemplate); 'photo' = the best real photo used as-is; 'custom' =
+         *  the owner's own artwork. The logo stays the small favicon/icon. */
+        socialPreviewStyle?: SocialPreviewStyle;
+        socialCardTemplate?: SocialCardTemplate;
+        /** Share-only copy. Blank = written from websiteTitle + the profile description. */
+        socialCardHeadline?: string | null;
+        socialCardSubline?: string | null;
+        /** The owner's uploaded 1200x630 artwork, used by the 'custom' style. */
+        socialPreviewImageUrl?: string | null;
+        layout: 'brand_left' | 'brand_center' | 'floating_pill' | 'floating_split';
+        /** Styling for the floating pill layout; ignored by the other two. */
+        pillStyle?: StorefrontHeaderPillStyle;
+        navPosition?: 'left' | 'center' | 'right';
+        ctas?: StorefrontButton[];
+        linkStyle?: StorefrontHeaderLinkStyle;
+        links?: StorefrontHeaderLink[];
+        maxWidth?: 'full' | 'standard' | 'compact' | 'thin';
+        /** Transparent header that sits flush over the hero on load and solidifies on scroll. */
+        overlayHeader?: boolean;
+        /** Nav/logo/icon colour while transparent over the hero. 'auto' reads the hero bg brightness. */
+        overlayColor?: 'light' | 'dark' | 'auto';
+        /** Optional raster logo variant shown only while transparent (light/overlay logo). */
+        overlayLogoImageUrl?: string | null;
+        /** Phone-menu extras: show the business phone / email / socials under the links. Default false. */
+        menuShowPhone?: boolean;
+        menuShowEmail?: boolean;
+        menuShowSocials?: boolean;
+        /** Hide the automatic "Collections" nav link (shown once the store has a visible collection). */
+        hideCollectionsNav?: boolean;
+        /** Theme overrides for the header band. Blank/absent = inherit the page theme (see section-theme). */
+        palette?: string;
+        fontPairing?: string;
+    };
+    hero: {
+        eyebrow: string;
+        title: string;
+        subtitle: string;
+        buttons: StorefrontButton[];
+        backgroundMedia: Array<{
+            id: string;
+            type: 'image' | 'video';
+            url: string;
+        }>;
+        backgroundMode?: 'image' | 'slideshow' | 'video';
+        backgroundUrl?: string | null;
+        backgroundType?: 'image' | 'video' | null;
+        overlay: number;
+        /** Seconds an image slide holds in a rotation; videos always play to their end. */
+        slideDuration?: number;
+    };
+    /** Additional hero sections, keyed by section id. The primary legacy hero still lives at `hero`. */
+    heroSections?: Record<string, StorefrontContent['hero']>;
+    fieldStyles?: Record<string, StorefrontFieldStyle>;
+    footer: {
+        /** Selection state only — a footer palette pick is written through into the colour fields below,
+         *  so the renderer reads those, never this. */
+        palette?: string;
+        /** Font-pack override for the footer band. Blank/absent = inherit the page theme. */
+        fontPairing?: string;
+        template: FooterTemplate;
+        brandText: string;
+        tagline: string;
+        copyright: string;
+        statusText?: string | null;
+        showBackToTop?: boolean;
+        backgroundColor: string;
+        /** Optional photo behind the footer (cover, centred); falls back to backgroundColor when null. */
+        backgroundImageUrl?: string | null;
+        /** Dark scrim over the background image, 0-90, so footer text stays legible. */
+        backgroundOverlay?: number;
+        /** Footer brand logo (mirrors the header logo). 'text' = brand text only (default). */
+        logoMode?: 'logo_text' | 'text' | 'logo';
+        logoImageUrl?: string | null;
+        logoSvg?: string | null;
+        logoSvgFill?: string | null;
+        logoSvgStroke?: string | null;
+        logoSvgStrokeWidth?: number;
+        logoHeight?: number;
+        /** False = follow the theme palette; true (or absent, for footers predating the flag) = paint the
+         *  six colours below. */
+        customColors?: boolean;
+        textColor: string;
+        mutedTextColor: string;
+        accentColor: string;
+        copyrightBackgroundColor: string;
+        copyrightTextColor: string;
+        socialLinks: Array<{
+            id: string;
+            platform: string;
+            label: string;
+            url: string;
+            visible: boolean;
+        }>;
+        linkGroups: Array<{
+            id: string;
+            title: string;
+            links: Array<{
+                id: string;
+                label: string;
+                link: StorefrontLink;
+                visible: boolean;
+            }>;
+        }>;
+        maxWidth?: 'full' | 'standard' | 'compact' | 'thin';
+        /** Optional blocks. Absent = off; the TEMPLATE decides where each renders. */
+        newsletter?: StorefrontFooterNewsletter;
+        payments?: StorefrontFooterPayments;
+        address?: StorefrontFooterAddress;
+        hours?: StorefrontFooterHours;
+        trust?: StorefrontFooterTrust;
+    };
+    contact: {
+        addressLine1: string;
+        addressLine2: string;
+        city: string;
+        state: string;
+        country: string;
+        googleMapsUrl?: string | null;
+        email?: string | null;
+        phoneNumbers: string[];
+        socials: Array<{
+            id: string;
+            platform: string;
+            label: string;
+            url: string;
+            visible: boolean;
+        }>;
+        showMap: boolean;
+    };
+    logoStrips: Record<string, {
+        logos: Array<{
+            id: string;
+            name: string;
+            imageUrl: string;
+            url?: string | null;
+            visible: boolean;
+            radius?: number | null;
+            size?: 'small' | 'medium' | 'large';
+        }>;
+    }>;
+    faqSections: Record<string, {
+        items: Array<{
+            id: string;
+            question: string;
+            answer: string;
+            category?: string;
+            visible: boolean;
+        }>;
+    }>;
+    imageTextSections: Record<string, {
+        media: Array<{
+            id: string;
+            type: 'image' | 'video';
+            url: string;
+        }>;
+        body: string;
+    }>;
+    richTextSections?: Record<string, {
+        body: string;
+    }>;
+    /** Composable content blocks, keyed by section id (the "Composed" hero is the first consumer). */
+    blockSections?: Record<string, {
+        blocks: StorefrontBlock[];
+        groups?: StorefrontBlockGroup[];
+    }>;
+    mediaGallerySections: Record<string, {
+        media: Array<{
+            id: string;
+            type: 'image' | 'video';
+            url: string;
+            caption?: string;
+        }>;
+        ctas: StorefrontButton[];
+    }>;
+    /** Curated social embeds, keyed by section id (used by the social section). */
+    socialSections?: Record<string, {
+        layout: 'grid' | 'carousel' | 'featured';
+        items: SocialEmbedItem[];
+    }>;
+    reviewsSections?: Record<string, {
+        items: Array<{
+            id: string;
+            name: string;
+            role: string;
+            text: string;
+            avatarUrl?: string | null;
+            rating?: number;
+            visible: boolean;
+        }>;
+    }>;
+    /** People cards (team/lineup/speakers), keyed by section id (used by the profiles section). */
+    profilesSections?: Record<string, {
+        source?: string;
+        items: Array<{
+            id: string;
+            name: string;
+            title: string;
+            tag?: string | null;
+            bio?: string | null;
+            imageUrl?: string | null;
+            socials?: Array<{
+                id: string;
+                platform: string;
+                url: string;
+                visible: boolean;
+            }>;
+            link?: StorefrontLink | null;
+            visible: boolean;
+        }>;
+    }>;
+    /** Content Showcase ("Highlights") cards, keyed by section id. Purely storefront-authored, no portal data. */
+    contentShowcaseSections?: Record<string, {
+        items: Array<{
+            id: string;
+            eyebrow?: string | null;
+            title: string;
+            description?: string | null;
+            mediaType: 'image' | 'video';
+            imageUrl?: string | null;
+            videoUrl?: string | null;
+            buttons: StorefrontButton[];
+            link?: StorefrontLink | null;
+            visible: boolean;
+        }>;
+    }>;
+    /** Custom HTML section code bodies (raw html/css/js the author wrote) + picked photo URLs, keyed by section id. */
+    /** Newsletter section copy, keyed by section id — the SAME shape as the footer's newsletter block,
+     *  so one form component serves both. */
+    newsletterSections?: Record<string, StorefrontFooterNewsletter>;
+    customHtmlSections?: Record<string, {
+        html?: string;
+        css?: string;
+        js?: string;
+        images?: string[];
+        videos?: string[];
+        links?: Array<{
+            id?: string;
+            label?: string;
+            link?: StorefrontLink;
+        }>;
+        pins?: StorefrontCustomHtmlPins;
+        fields?: Record<string, string>;
+    }>;
+    sectionButtons?: Record<string, StorefrontButton>;
+    sectionButtonGroups?: Record<string, StorefrontButton[]>;
+    tracking?: {
+        facebookPixelId?: string;
+        ga4Id?: string;
+        gtmId?: string;
+        tiktokPixelId?: string;
+        snapPixelId?: string;
+        xPixelId?: string;
+        xPurchaseEventId?: string;
+        xAddToCartEventId?: string;
+        xLeadEventId?: string;
+        shareHashedEmail?: boolean;
+        customHead?: string;
+        customBodyEnd?: string;
+    };
+    /** On-load + exit-intent promo campaigns. Site-wide, not a section (see @frontdesk/shared promo). */
+    promo?: StorefrontPromoContent;
+}
+/** The public storefront payload returned by GET /v1/storefront/:ref. */
+interface Storefront {
+    ref: string;
+    type: string;
+    displayName: string;
+    /** Workspace business-hours timezone used by date-sensitive storefront components. */
+    timezone?: string;
+    description: string | null;
+    /** Kept for back-compat — prefer categorySlugs. */
+    categorySlug: string | null;
+    categorySlugs?: string[];
+    website?: string | null;
+    socials?: Record<string, string>;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    avatarUrl: string | null;
+    coverUrl: string | null;
+    badges: StorefrontBadge[];
+    memberCount?: number;
+    renderConfig?: StorefrontRenderConfig;
+    content?: StorefrontContent;
+    /** Media catalogs referenced by sections (options.catalogRef), hydrated server-side. */
+    catalogs?: Record<string, HydratedCatalog>;
+    /** Hand-picked media assets (portfolio custom mode, options.assetRefs CSV), keyed by ref. */
+    assets?: Record<string, PublicCatalogItem>;
+    /** Active public packages for the `packages` section (lightweight summaries). */
+    packages?: PublicPackageSummary[];
+    /** Full packages (with options) for packages sections in 'options'/'custom' mode, keyed by package ref. */
+    packageDetails?: Record<string, PublicPackage>;
+    /** Active public products for the `store` section (lightweight summaries). */
+    products?: PublicProductSummary[];
+    /** Active collections (membership resolved into refs against `products`) — the `collections`
+     *  section, the /collections pages and the auto nav link. */
+    collections?: PublicCollectionSummary[];
+    /** Published public events for the `events` section + /events listing (lightweight summaries). */
+    events?: PublicEventSummary[];
+    /** The workspace's primary verified custom domain — the canonical host, when set. */
+    primaryDomain?: string | null;
+    /** Every verified custom domain the site is live on, primary first — the tracking allowlist's
+     *  source of truth for "is this host really ours?" (see `trackingAllowedHosts`). */
+    verifiedDomains?: string[];
+    /** Effective image-upload policy (admin default + this FrontDesk's override) for client-side resize. */
+    mediaPolicy?: MediaUploadPolicy;
+    /** The store's effective payment methods — the footer's payment marks are DERIVED from these
+     *  server-side, so the footer can never advertise a rail checkout won't offer. Absent when the
+     *  footer's payment block is off. */
+    paymentMethods?: string[];
+    /** Weekly opening hours from the workspace's front-desk policy, for the footer's hours block.
+     *  Absent when hours were never configured, which is how that block self-hides. */
+    businessHours?: Array<{
+        day: string;
+        start: string;
+        end: string;
+    }>;
+    /** Own-site floating chat bubble (frontdesk-embed-chat-widget): the renderer injects /widget.js with
+     *  this embed key when set (suppressed on /chat, chat-hero pages, and the builder preview). */
+    widgetBubble?: {
+        key: string;
+    } | null;
+    /** Store-wide review aggregate + recent published reviews — feeds the custom_html sandbox's
+     *  FD.reviews. Only present when a visible custom_html section has code AND reviews are enabled. */
+    reviews?: StorefrontReviewsData;
+    /** Published public forms (FD.forms) — same hydration gate as `reviews`. */
+    forms?: StorefrontFormSummary[];
+}
+/** Per-entity pinned refs for a Custom HTML section's FD.* data lists (forms pin by slug). */
+interface StorefrontCustomHtmlPins {
+    products?: string[];
+    packages?: string[];
+    collections?: string[];
+    catalogs?: string[];
+    events?: string[];
+    forms?: string[];
+}
+/** FD.reviews: store-wide aggregate + recent published reviews, product-attributed. */
+interface StorefrontReviewsData {
+    average: number;
+    count: number;
+    items: Array<{
+        author: string;
+        rating: number;
+        text: string;
+        date: string;
+        productName: string;
+        productSlug: string | null;
+    }>;
+}
+/** FD.forms item — the CTA-card basics plus the public field definitions + submit/thank-you copy,
+ *  so a custom_html frame can render and client-validate a BOUND form (data-fd-form). */
+type StorefrontFormSummary = CustomHtmlFormDef;
+
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+interface PublicNoteApproval {
+    approverName: string;
+    approverEmail: string | null;
+    note: string | null;
+    approvedAt: string;
+}
+interface PublicNoteComment {
+    ref: string;
+    authorKind: 'client' | 'team';
+    authorName: string;
+    body: string;
+    createdAt: string;
+}
+interface PublicNote {
+    ref: string;
+    title: string;
+    slug: string;
+    contentHtml: string;
+    publicPath: string;
+    updatedAt: string;
+    lastEditedAt: string | null;
+    approvals: PublicNoteApproval[];
+    approvalCount: number;
+    comments: PublicNoteComment[];
+    brand: {
+        ref: string;
+        displayName: string;
+        avatarUrl: string | null;
+        handle: string | null;
+    };
+    storefrontPublished: boolean;
+}
+/** A shared table (PRO Tables). Read-only, already stripped to the columns the merchant left visible. */
+interface PublicTableColumn {
+    id: string;
+    name: string;
+    type: string;
+    options?: {
+        choices?: {
+            id: string;
+            label: string;
+            color?: string;
+        }[];
+        currency?: string;
+        agg?: string;
+    };
+    width?: number;
+}
+interface PublicTable {
+    name: string;
+    description: string | null;
+    icon: string | null;
+    slug: string;
+    publicPath: string;
+    columns: PublicTableColumn[];
+    rows: Record<string, unknown>[];
+    total: number;
+    truncated: boolean;
+    aggregates: Record<string, number | null>;
+    updatedAt: string;
+    lastEditedAt: string | null;
+    brand: {
+        ref: string;
+        displayName: string;
+        avatarUrl: string | null;
+        handle: string | null;
+    };
+    storefrontPublished: boolean;
+}
+
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+
+interface PublicForm {
+    ref: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    status: 'draft' | 'published' | 'closed';
+    fields: PublicFormField[];
+    settings: {
+        displayTitle?: string | null;
+        displayDescription?: string | null;
+        sideTitle?: string | null;
+        sideDescription?: string | null;
+        thankYouMessage: string;
+        redirectUrl?: string | null;
+        submitButtonLabel?: string | null;
+    };
+    coverUrl: string | null;
+    workspace: {
+        name: string;
+        handle: string | null;
+        logoUrl: string | null;
+    };
+    /** Short-lived permit for the public upload endpoint (sent as x-fd-upload-token). */
+    uploadToken?: string;
+}
+
+/**
+ * Typed client for the FrontDesk Storefront API.
+ *
+ * Deliberately thin. It is a fetch wrapper with the response types attached and the error envelope
+ * turned into a real Error — nothing more. A client that caches, retries or reshapes responses
+ * becomes a second implementation of the API's semantics, and then the docs describe one thing while
+ * the client does another.
+ *
+ * The types come from `@frontdesk/shared`, which is the SAME source the server serialises from, so
+ * this client cannot describe a shape the API does not return.
+ */
+interface StoreClientOptions {
+    /** e.g. `https://api.frontdesk.africa/v1`. No trailing slash needed. */
+    baseUrl: string;
+    /** `fd_pk_…` in a browser, `fd_sk_…` on a server. */
+    key: string;
+    /** Override for tests, or a custom-instrumented fetch. */
+    fetch?: typeof fetch;
+}
+/** The contract's error envelope, thrown so a caller can branch on `code` without parsing. */
+declare class StoreApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly requestId: string | null;
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, body: unknown);
+}
+declare function createStoreClient(opts: StoreClientOptions): {
+    /** Escape hatch for anything not yet wrapped. Same auth, same error handling. */
+    request: <T>(path: string, init?: RequestInit & {
+        idempotencyKey?: string;
+    }) => Promise<T>;
+    storefront: () => Promise<Storefront>;
+    products: () => Promise<PublicProductSummary[]>;
+    product: (slug: string) => Promise<PublicProduct>;
+    productSlots: (slug: string, opts: {
+        variantRef: string;
+        date: string;
+    }) => Promise<PublicProductSlots>;
+    collections: () => Promise<PublicCollectionSummary[]>;
+    collection: (slug: string) => Promise<PublicCollectionDetail>;
+    events: () => Promise<PublicEventSummary[]>;
+    event: (slug: string) => Promise<PublicEvent>;
+    form: (slug: string) => Promise<PublicForm>;
+    table: (slug: string) => Promise<PublicTable>;
+    catalog: (slug: string) => Promise<PublicCatalog>;
+    files: (slug: string) => Promise<PublicFolder>;
+    note: (slug: string) => Promise<PublicNote>;
+    deliveryZones: () => Promise<DeliveryZone[]>;
+    /**
+     * Live stock for the variants a cart already holds — a cart is localStorage, so its lines can be
+     * days old. A ref missing from the response map is no longer purchasable: drop that line. Refs in
+     * `preorderable` are still buyable at 0 stock; cap those on `preorderRemaining` instead.
+     */
+    availability: (variantRefs: string[]) => Promise<PublicStoreAvailability>;
+    /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
+    paymentMethods: (currency?: string) => Promise<string[]>;
+    /**
+     * Open a hosted checkout. SERVER ONLY — needs a secret key.
+     *
+     * `idempotencyKey` is required by the API, not optional politeness: reuse the same value on a
+     * retry and you get the SAME checkout back instead of charging a buyer twice. Derive it from
+     * something stable in your own system (your cart id), never a random value per attempt.
+     */
+    createCheckout: (input: StoreCheckoutSessionInput, idempotencyKey: string) => Promise<StoreCheckoutSessionView>;
+    /**
+     * Open a hosted checkout for event tickets. SERVER ONLY — needs a secret key.
+     *
+     * `GET /store/events/:slug` tells you what to collect first: each tier carries formFields,
+     * requiresAttendeeDetails, groupSize and min/max per order; the event carries minAge and dobMode.
+     * Everything is re-validated server-side, so prices and availability are never yours to decide.
+     */
+    createEventCheckout: (slug: string, input: StoreEventCheckoutInput, idempotencyKey: string) => Promise<StoreCheckoutSessionView>;
+    /**
+     * Open a ticket checkout you render yourself, including the payment step. SERVER ONLY, and the
+     * workspace must have headless switched on. Name ONE provider from `paymentMethods()`; branch on
+     * the provider you asked for, never on which payment field came back filled in.
+     */
+    createHeadlessCheckout: (slug: string, input: StoreHeadlessCheckoutInput, idempotencyKey: string) => Promise<StoreHeadlessCheckoutView>;
+    /**
+     * The state of a checkout. THIS is how you confirm a purchase — the return redirect is a browser
+     * navigation and can be lost, replayed or forged, so never fulfil on it alone. Safe to poll while
+     * a buyer is paying: an open session is verified against the provider before we answer.
+     */
+    getCheckout: (ref: string) => Promise<StoreCheckoutSessionView>;
+    /**
+     * Cancel an open checkout and release the seats it was holding, instead of leaving them out of
+     * stock until the session lapses. Cancelling an already-paid checkout returns 409.
+     */
+    cancelCheckout: (ref: string) => Promise<StoreCheckoutSessionView>;
+};
+type StoreClient = ReturnType<typeof createStoreClient>;
+/**
+ * Verify a webhook signature.
+ *
+ * Node only (uses `node:crypto`). Pass the RAW request body — parse it after verifying, never
+ * before: `JSON.parse` then `JSON.stringify` will not reproduce the bytes we signed, and the check
+ * will fail for reasons that look like a key mismatch.
+ *
+ * `toleranceSec` rejects a delivery whose timestamp is far from now, which is what stops a captured
+ * request being replayed at you later.
+ */
+declare function verifyWebhook(opts: {
+    rawBody: string;
+    signatureHeader: string | null | undefined;
+    timestampHeader: string | null | undefined;
+    secret: string;
+    toleranceSec?: number;
+}): Promise<boolean>;
+
+export { StoreApiError, type StoreClient, type StoreClientOptions, createStoreClient, verifyWebhook };