@officexapp/catalog-types 0.1.0

package/dist/shared/types.d.ts

@@ -0,0 +1,1043 @@
+export type InputComponentType = "short_text" | "long_text" | "rich_text" | "email" | "phone" | "url" | "address" | "number" | "currency" | "date" | "datetime" | "time" | "date_range" | "dropdown" | "multiselect" | "multiple_choice" | "checkboxes" | "picture_choice" | "switch" | "checkbox" | "choice_matrix" | "ranking" | "star_rating" | "slider" | "opinion_scale" | "file_upload" | "signature" | "password" | "location";
+export type DisplayComponentType = "heading" | "paragraph" | "banner" | "image" | "video" | "pdf_viewer" | "file_download" | "social_links" | "html" | "divider" | "faq" | "testimonial" | "pricing_card" | "timeline" | "iframe" | "modal" | "custom";
+export type LayoutComponentType = "section_collapse" | "table" | "subform";
+export type PageFeatureType = "payment" | "captcha";
+export type ComponentType = InputComponentType | DisplayComponentType | LayoutComponentType | PageFeatureType;
+export interface EmbeddedButton {
+    /** Button label text */
+    label: string;
+    /** URL to navigate to on click */
+    url: string;
+    /** Link target — "_blank" opens in new tab (default), "_self" opens in same tab */
+    target?: "_blank" | "_self";
+    /** Button size — "sm" (default), "md", "lg" */
+    size?: "sm" | "md" | "lg";
+    /** Visual style — "primary" (default), "secondary", "outline", "ghost" */
+    style?: "primary" | "secondary" | "outline" | "ghost";
+    /** Emoji or icon text shown before the label */
+    icon?: string;
+}
+export interface Option {
+    value: string;
+    label: string;
+    image?: string;
+    description?: string;
+    /** Optional button rendered inline with the option */
+    button?: EmbeddedButton;
+    /** When true, the option is visible but not selectable (grayed out) */
+    disabled?: boolean;
+}
+export interface BaseComponentProps {
+    label?: string;
+    /** Smaller text rendered directly below the label */
+    subheading?: string;
+    /** Tooltip text shown on hover/click of an info icon next to the label */
+    tooltip?: string;
+    required?: boolean;
+    placeholder?: string;
+    description?: string;
+    hidden?: boolean;
+    /** Render the input as read-only with a copy-to-clipboard button */
+    readonly?: boolean;
+    /** Show a copy-to-clipboard icon next to the input (works on editable inputs too) */
+    copyable?: boolean;
+    /** Render the input as disabled (greyed out, not interactive) */
+    disabled?: boolean;
+}
+export interface TextProps extends BaseComponentProps {
+    min_length?: number;
+    max_length?: number;
+    default_value?: string;
+    /** Number of visible text rows for long_text (default: 4) */
+    rows?: number;
+    /** Whether the textarea is resizable: "vertical" (default), "horizontal", "both", "none" */
+    resize?: "vertical" | "horizontal" | "both" | "none";
+}
+export interface NumberProps extends BaseComponentProps {
+    min?: number;
+    max?: number;
+    step?: number;
+    default_value?: number;
+    prefix?: string;
+    suffix?: string;
+}
+export interface QuizConfig {
+    /** The correct answer value (must match an option value). For checkboxes/multiselect, use an array. */
+    correct_answer: string | string[];
+    /** Points awarded for a correct answer (default: 1) */
+    points?: number;
+    /** Explanation shown when answer is revealed */
+    explanation?: string;
+    /** Show correct/incorrect feedback inline immediately after the user selects an answer (fillout.com-style) */
+    reveal_on_select?: boolean;
+    /** Custom message shown when the user gets the answer wrong (default: "You got the wrong answer.") */
+    wrong_message?: string;
+    /** Custom message shown when the user gets the answer right (default: "Correct!") */
+    correct_message?: string;
+    /** Per-option custom messages for choice-based inputs. Key = option value, shown when that specific wrong option is selected. */
+    option_messages?: Record<string, string>;
+}
+export interface ChoiceProps extends BaseComponentProps {
+    options: Option[];
+    other_option?: boolean;
+    randomize?: boolean;
+    default_value?: string | string[];
+    /** Require ALL options to be selected (for checkboxes). When true, every option must be checked and all nested required inputs filled. */
+    require_all?: boolean;
+    /** Quiz configuration — marks this component as a quiz question */
+    quiz?: QuizConfig;
+}
+export interface HeadingProps {
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+    /** Small eyebrow/kicker text rendered above the heading */
+    micro_heading?: string;
+    subtitle?: string;
+    align?: "left" | "center" | "right";
+}
+export interface ParagraphProps {
+    text: string;
+    align?: "left" | "center" | "right";
+}
+export interface BannerProps {
+    text: string;
+    variant: "info" | "warning" | "success" | "error";
+}
+export interface ImageProps {
+    /** Image URL — use the compressed_url from the image upload API for auto-optimized WebP delivery */
+    src: string;
+    alt?: string;
+    width?: number | string;
+    height?: number | string;
+    link?: string;
+    border_radius?: number;
+    /** Use the original (uncompressed) image URL instead of the compressed version */
+    use_original?: boolean;
+}
+export interface VideoChapter {
+    time: number;
+    label: string;
+    thumbnail?: string;
+}
+export interface VideoProps {
+    src: string;
+    hls_url?: string;
+    dash_url?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    poster?: string;
+    chapters?: VideoChapter[];
+    skippable?: boolean;
+    require_watch_percent?: number;
+    video_id?: string;
+}
+export interface SliderProps extends BaseComponentProps {
+    min: number;
+    max: number;
+    step?: number;
+    default_value?: number;
+    show_value?: boolean;
+    labels?: {
+        min?: string;
+        max?: string;
+    };
+}
+export interface OpinionScaleProps extends BaseComponentProps {
+    min: number;
+    max: number;
+    labels?: {
+        min?: string;
+        mid?: string;
+        max?: string;
+    };
+    default_value?: number;
+}
+export interface StarRatingProps extends BaseComponentProps {
+    max_stars?: number;
+    default_value?: number;
+}
+export interface PaymentProps {
+    checkout_type: "stripe_embedded" | "redirect";
+    button_text?: string;
+    price_display?: string;
+    stripe_price_id?: string;
+    redirect_url?: string;
+    order_bumps?: OrderBump[];
+}
+export interface OrderBump {
+    id: string;
+    title: string;
+    description?: string;
+    price_display: string;
+    stripe_price_id?: string;
+}
+export interface SocialLinksProps {
+    links: {
+        platform: string;
+        url: string;
+    }[];
+}
+export interface HtmlProps {
+    content: string;
+}
+export interface IframeProps {
+    /** URL to embed — supports {{field_id}} templates for dynamic values */
+    src: string;
+    /** Height in px or CSS value (default: 400) */
+    height?: number | string;
+    /** Width — CSS value (default: "100%") */
+    width?: string;
+    /** Border radius in px (default: 16) */
+    border_radius?: number;
+    /** Sandbox attribute for the iframe (default: "allow-scripts allow-same-origin allow-forms") */
+    sandbox?: string;
+    /** Allow attribute (e.g. "camera; microphone") */
+    allow?: string;
+    /** Show a border (default: false) */
+    border?: boolean;
+    /** Title for accessibility */
+    title?: string;
+}
+export interface ModalNestedInput {
+    id: string;
+    type: string;
+    label?: string;
+    placeholder?: string;
+    required?: boolean;
+    props?: Record<string, any>;
+}
+export interface ModalProps {
+    button_label?: string;
+    button_style?: "primary" | "outline" | "ghost" | "link";
+    title?: string;
+    /** Static body text (markdown-style). Rendered above any embedded components. */
+    body?: string;
+    max_width?: string;
+    /** Embedded components rendered inside the modal body (inputs + display) */
+    components?: ModalNestedInput[];
+    /** Label for the confirm button (default: "Close"). When components are present, this becomes the primary action. */
+    confirm_label?: string;
+    /** When confirm is clicked, set this field ID to the given value (e.g. auto-check a checkbox) */
+    confirm_sets_field?: {
+        field_id: string;
+        value: any;
+    };
+    /** Disable the confirm button until all required embedded inputs are filled */
+    require_inputs?: boolean;
+}
+export interface CustomComponentProps {
+    /** Name of the component registered on window.__catalogkit_components */
+    component: string;
+    /** Arbitrary props passed through to the custom component */
+    [key: string]: any;
+}
+export interface FaqItem {
+    question: string;
+    answer: string;
+}
+export interface FaqProps {
+    items: FaqItem[];
+    title?: string;
+    /** Allow multiple items open at once (default: false) */
+    allow_multiple?: boolean;
+    /** Index of item to open by default (0-based) */
+    default_open?: number;
+}
+export interface TestimonialProps {
+    text: string;
+    author: string;
+    role?: string;
+    avatar?: string;
+    rating?: number;
+    /** Display style */
+    variant?: "card" | "quote" | "minimal";
+}
+export interface PricingCardProps {
+    title: string;
+    price: string;
+    price_subtext?: string;
+    badge?: string;
+    features: string[];
+    /** Features that are NOT included (rendered with strikethrough) */
+    excluded_features?: string[];
+    highlighted?: boolean;
+    cta_text?: string;
+}
+export interface FileUploadProps extends BaseComponentProps {
+    accept?: string[];
+    max_size_mb?: number;
+    multiple?: boolean;
+    /** Upload files to S3 with presigned URLs instead of storing as base64 data URLs.
+     *  Requires authenticated catalog owner (credits charged: 1 per 50MB). */
+    s3_upload?: boolean;
+}
+export interface FileDownloadProps {
+    /** File URL — use the CDN URL from the file upload API */
+    src: string;
+    /** Display filename (shown on the button) */
+    filename: string;
+    /** File size in bytes (shown as formatted size) */
+    size_bytes?: number;
+    /** Button text (default: "Download") */
+    button_text?: string;
+    /** Button style */
+    style?: "primary" | "secondary" | "outline" | "ghost";
+    /** Optional description text shown below the filename */
+    description?: string;
+    /** Optional icon/emoji shown before the filename */
+    icon?: string;
+}
+export interface AddressProps extends BaseComponentProps {
+    show_line2?: boolean;
+    default_country?: string;
+}
+export interface SectionCollapseProps {
+    title: string;
+    default_open?: boolean;
+    components: CatalogComponent[];
+}
+export interface TableProps {
+    headers: string[];
+    rows: string[][];
+}
+export interface SubformProps extends BaseComponentProps {
+    title: string;
+    min_items?: number;
+    max_items?: number;
+    add_button_text?: string;
+    components: CatalogComponent[];
+}
+export interface AiPrefillConfig {
+    /** Enable AI prefill for this field */
+    enabled: boolean;
+    /** Minimum confidence threshold (0-1) for the AI to prefill this field (default: 0.7) */
+    confidence?: number;
+    /** Extra instructions for the AI when filling this specific field */
+    instructions?: string;
+}
+export type PrefillMode = "editable" | "readonly" | "hidden";
+export interface CatalogComponent {
+    id: string;
+    type: ComponentType;
+    props: Record<string, any>;
+    /** Hide this component from rendering (static flag — for dynamic conditions use `visibility`) */
+    hidden?: boolean;
+    visibility?: ConditionGroup;
+    prefill_mode?: PrefillMode;
+    /** Component width within a row: "full" (default), "half", "third", "two_thirds" */
+    width?: "full" | "half" | "third" | "two_thirds";
+    /** Semantic hint for AI agents explaining what this field means */
+    agent_hint?: string;
+    /** AI prefill configuration — opt-in per field */
+    ai_prefill?: AiPrefillConfig;
+    className?: string;
+    style?: Record<string, string | number>;
+}
+export type PageActionStyle = "primary" | "secondary" | "ghost" | "danger";
+export interface PageAction {
+    id: string;
+    label: string;
+    style?: PageActionStyle;
+    icon?: string;
+    redirect_url?: string;
+    /** Text shown to the right of the button */
+    side_statement?: string;
+    /** Small reassurance text shown below the button */
+    reassurance?: string;
+}
+export interface PageOffer {
+    id: string;
+    title: string;
+    price_display?: string;
+    price_subtext?: string;
+    image?: string;
+    stripe_price_id?: string;
+    /** Amount in cents for items without a stripe_price_id (e.g. 2999 = $29.99) */
+    amount_cents?: number;
+    /** Currency code (default: "usd") */
+    currency?: string;
+    /** Override the global payment_type per offer */
+    payment_type?: CheckoutPaymentType;
+    /** Billing interval for subscription offers */
+    interval?: "day" | "week" | "month" | "year";
+    /** The action id or choice value that means "accept this offer" */
+    accept_value?: string;
+    /** The field id that holds the accept/decline choice (for multiple_choice offers) */
+    accept_field?: string;
+}
+export interface CartItem {
+    offer_id: string;
+    page_id: string;
+    title: string;
+    price_display?: string;
+    price_subtext?: string;
+    image?: string;
+    stripe_price_id?: string;
+    /** Amount in cents for items without a stripe_price_id */
+    amount_cents?: number;
+    /** Override the global payment_type per item */
+    payment_type?: CheckoutPaymentType;
+    /** Currency code (default: "usd") */
+    currency?: string;
+    /** Billing interval for subscription items */
+    interval?: "day" | "week" | "month" | "year";
+    /** Optional side button (link) shown next to the item */
+    button?: EmbeddedButton;
+}
+export type StickyBarStyle = "solid" | "glass" | "glass_dark" | "gradient";
+export interface StickyBarAction {
+    /** Button label — supports {{field_id}} templates */
+    label: string;
+    /** Visual style */
+    style?: "primary" | "secondary" | "ghost";
+    /**
+     * What happens on click:
+     * - "next" — advance to next page (default for primary)
+     * - "action:<action_id>" — trigger a page action by id (e.g. "action:accept", "action:skip")
+     * - "field:<field_id>:<value>" — set a field value then advance (e.g. "field:comp_offer1_cta_choice:accept")
+     */
+    action?: string;
+}
+export interface StickyBarConfig {
+    enabled: boolean;
+    /** Visual style of the bar */
+    style?: StickyBarStyle;
+    /** Primary CTA — if not set, falls back to button_text or page submit_label */
+    primary?: StickyBarAction;
+    /** Secondary action (e.g. decline/skip) — rendered as ghost/secondary button */
+    secondary?: StickyBarAction;
+    /** Simple override for primary CTA text (shorthand when you don't need full StickyBarAction) */
+    button_text?: string;
+    /** Subtitle text — supports {{field_id}} templates for dynamic values */
+    subtitle?: string;
+    /** Custom HTML — supports {{field_id}} templates. Replaces the default subtitle area. */
+    html?: string;
+    /** Show cart item count badge on the button */
+    show_cart_count?: boolean;
+    /** Hide the bar when user has scrolled to the bottom (near the normal submit button) */
+    hide_at_bottom?: boolean;
+    /** Show the bar only after user scrolls past an element with this id (e.g. "pricing-section").
+     *  The bar starts hidden and appears once the anchor scrolls out of view (above the viewport). */
+    show_after?: string;
+    /** Delay in milliseconds before the bar can appear (starts hidden, then fades in after this delay) */
+    delay_ms?: number;
+    /** Scroll-direction behavior: "show_on_up" shows bar on scroll-up, hides on scroll-down */
+    scroll_behavior?: "show_on_up";
+}
+export type PageLayout = "cover" | "form" | "default";
+export interface RevealAnswersConfig {
+    /** Page IDs whose quiz answers should be revealed on this page */
+    from_pages: string[];
+    /** Show which answer was correct (default: true) */
+    show_correct?: boolean;
+    /** Show the explanation text (default: true) */
+    show_explanation?: boolean;
+    /** Show score summary (default: true) */
+    show_score?: boolean;
+}
+export interface CatalogPage {
+    title: string;
+    description?: string;
+    layout?: PageLayout;
+    components: CatalogComponent[];
+    submit_label?: string;
+    /** Text shown to the right of the submit button */
+    submit_side_statement?: string;
+    /** Small reassurance text shown below the submit button */
+    submit_reassurance?: string;
+    actions?: PageAction[];
+    offer?: PageOffer;
+    hide_back?: boolean;
+    hide_navigation?: boolean;
+    /** Auto-advance to next page when the last visible selection input is answered */
+    auto_advance?: boolean;
+    /** Auto-skip this page if all visible input fields already have values (from prefill, defaults, or prior entry) */
+    auto_skip?: boolean;
+    /** Disable the Continue/Submit button until all required fields on this page are filled */
+    require_all_fields?: boolean;
+    /** Message shown when the user clicks a disabled button (default: "Please fill in all required fields") */
+    button_disabled_message?: string;
+    /** Sticky bottom bar config — overrides the global setting for this page */
+    sticky_bar?: StickyBarConfig;
+    /** Reveal quiz answers from previous pages */
+    reveal_answers?: RevealAnswersConfig;
+    /** Context hint for AI agents explaining this page's purpose */
+    agent_context?: string;
+    /** Max width of page content area (e.g. "max-w-2xl", "max-w-4xl", "800px") */
+    max_width?: string;
+    className?: string;
+    style?: Record<string, string | number>;
+}
+export interface ProgressStep {
+    id: string;
+    label: string;
+    pages: string[];
+}
+export interface TopBarCountdown {
+    /** ISO date string or epoch ms — countdown to this time */
+    target_date: string;
+    /** Label shown before the timer, e.g. "Sale ends in" */
+    label?: string;
+    /** Text shown when countdown expires */
+    expired_text?: string;
+}
+export interface TopBarConfig {
+    /** false = hide the entire top bar. Default: true */
+    enabled?: boolean;
+    /** Show the back button. Default: true */
+    show_back_button?: boolean;
+    /** Show stepper/progress bar. Default: true */
+    show_progress?: boolean;
+    /** Optional title text displayed in the center of the top bar */
+    title?: string;
+    /** Font weight for the title: "light" (300), "normal" (400), "medium" (500, default), "semibold" (600), "bold" (700) */
+    title_weight?: "light" | "normal" | "medium" | "semibold" | "bold";
+    /** Countdown timer config */
+    countdown?: TopBarCountdown;
+    /** Raw HTML to render in the top bar */
+    custom_html?: string;
+    /** Extra CSS class names */
+    className?: string;
+    /** Inline style overrides */
+    style?: Record<string, string | number>;
+}
+export type ConditionOperator = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "greater_than_or_equal" | "less_than" | "less_than_or_equal" | "is_empty" | "is_not_empty" | "matches_regex" | "in";
+export type ConditionSource = "field" | "url_param" | "hint" | "tracer_prop" | "score" | "video";
+export interface ConditionRule {
+    source?: ConditionSource;
+    field?: string;
+    param?: string;
+    operator: ConditionOperator;
+    value?: any;
+}
+export interface ConditionGroup {
+    match: "all" | "any";
+    rules: (ConditionRule | ConditionGroup)[];
+}
+export interface RoutingEdge {
+    from: string;
+    to: string | null;
+    conditions?: ConditionGroup;
+    priority?: number;
+    is_default?: boolean;
+}
+export interface Routing {
+    entry: string;
+    edges: RoutingEdge[];
+}
+export interface HintDefinition {
+    type: "enum" | "string";
+    options?: string[];
+    default?: string;
+    description?: string;
+}
+export interface CatalogVariant {
+    id: string;
+    slug: string;
+    description?: string;
+    hints?: Record<string, string>;
+    weight?: number;
+    /** If set, route to this OTHER catalog slug (replaces split tests) */
+    target_slug?: string;
+    url_params?: Record<string, string>;
+    /** If false, variant is excluded from routing (hint, random, hybrid). Default: true */
+    enabled?: boolean;
+}
+export interface PersonalizationRule {
+    target: string;
+    prop: string;
+    conditions: ConditionGroup;
+    value: any;
+}
+export interface ThemeSettings {
+    primary_color: string;
+    font?: string;
+    custom_fonts?: CustomFont[];
+    mode?: "light" | "dark";
+    border_radius?: number;
+    /**
+     * Base font size for body text and inputs in rem.
+     * Default: 1 (16px). Use 1.125 for 18px, 0.875 for 14px, etc.
+     */
+    font_size?: number;
+    background_image?: string;
+    background_color?: string;
+    /**
+     * Overlay on cover page background image.
+     * - "dark" (default) — dark gradient for white text readability
+     * - "light" — light overlay for dark text
+     * - "none" — no overlay
+     * - number (0–1) — custom dark opacity (e.g. 0.5)
+     * - string starting with "rgba" or "#" — custom CSS color/gradient
+     */
+    background_overlay?: "dark" | "light" | "none" | number | string;
+}
+export interface CustomFont {
+    family: string;
+    url?: string;
+    weights?: number[];
+}
+export interface ExitIntentSettings {
+    enabled: boolean;
+    offer_page_id?: string;
+}
+export type PopupTriggerType = "exit_intent" | "scroll_depth" | "inactive" | "timed" | "page_count" | "custom" | "video_progress" | "video_chapter";
+export interface PopupTrigger {
+    type: PopupTriggerType;
+    /** Delay in ms before arming the trigger (default: 0) */
+    delay?: number;
+    /** Cooldown duration string e.g. "24h", "7d", "1h" — don't re-show within this window */
+    cooldown?: string;
+    /** For scroll_depth: percentage 0-100 */
+    percent?: number;
+    /** For inactive/timed: seconds */
+    seconds?: number;
+    /** For page_count: number of pages visited */
+    count?: number;
+    /** For custom: event name triggered programmatically */
+    event?: string;
+    /** For video_progress: percentage 0-100 to trigger at */
+    watch_percent?: number;
+    /** For video_chapter: chapter index to trigger at */
+    chapter_index?: number;
+    /** Target video component ID for video triggers */
+    video_component_id?: string;
+}
+export type PopupPosition = "center" | "bottom-right" | "bottom-left" | "full-screen";
+export type PopupAnimation = "slide-up" | "slide-down" | "fade" | "scale";
+export interface PopupStyle {
+    overlay?: "dark" | "light" | "none";
+    position?: PopupPosition;
+    animation?: PopupAnimation;
+    max_width?: string;
+}
+export interface PopupSubmitAction {
+    action: "post" | "track" | "close" | "redirect" | "next_page";
+    /** For post: webhook URL. For redirect: target URL. Supports {{field_id}} templates. */
+    url?: string;
+    /** For track: event name */
+    event?: string;
+}
+export interface PopupForm {
+    fields: CatalogComponent[];
+    submit_label?: string;
+    on_submit?: PopupSubmitAction[];
+}
+export interface PopupAction {
+    label: string;
+    /** Action to perform: navigate to URL, track event, or close toast */
+    action: "redirect" | "track" | "close" | "next_page";
+    url?: string;
+    event?: string;
+    /** Button style — default: "primary" */
+    style?: "primary" | "secondary" | "ghost";
+}
+export interface PopupContent {
+    headline?: string;
+    subheadline?: string;
+    image?: string;
+    /** Action buttons — especially useful for toast-mode popups */
+    actions?: PopupAction[];
+}
+export interface PopupConfig {
+    trigger: PopupTrigger;
+    /** Which page IDs this popup appears on. If omitted, appears on all pages. */
+    pages?: string[];
+    /** Popup mode — "modal" (default, blocks interaction) or "toast" (non-blocking notification) */
+    mode?: "modal" | "toast";
+    /** Auto-dismiss after N seconds — useful for toast mode */
+    auto_dismiss?: number;
+    form?: PopupForm;
+    content?: PopupContent;
+    style?: PopupStyle;
+    /** Custom React component name from merchant's components/ directory */
+    custom_component?: string;
+    /** Hint-variant overrides for any content field using __variants pattern */
+    [key: `${string}__variants`]: Record<string, string> | undefined;
+}
+export interface ScriptTag {
+    src: string;
+    position: "head" | "body_start" | "body_end";
+}
+export type CheckoutPaymentType = "one_time" | "subscription" | "pay_what_you_want";
+export interface CheckoutPrefillFields {
+    /** Component ID to prefill customer email from */
+    customer_email?: string;
+    /** Component ID to prefill customer name from */
+    customer_name?: string;
+    /** Component ID to prefill customer phone from */
+    customer_phone?: string;
+}
+export interface CheckoutTestimonial {
+    enabled: boolean;
+    text?: string;
+    author?: string;
+    avatar?: string;
+}
+export interface CheckoutSettings {
+    payment_type: CheckoutPaymentType;
+    title?: string;
+    stripe_publishable_key?: string;
+    allow_discount_codes?: boolean;
+    free_trial?: {
+        enabled: boolean;
+        days?: number;
+    };
+    prefill_fields?: CheckoutPrefillFields;
+    payment_methods?: string[];
+    payment_description?: string;
+    /** Template string — use {{field_id}} to inject form field values, e.g. "{{comp_email}}" */
+    client_reference_id?: string;
+    /**
+     * Force 3D Secure verification on all card payments.
+     * Ensures the cardholder authenticates via OTP/biometric, reducing payment failures at trial end.
+     */
+    require_3ds?: boolean;
+    /**
+     * What happens if the customer's payment method is missing or fails at trial end.
+     * - "cancel" — cancel the subscription (default, recommended)
+     * - "create_invoice" — create an invoice and retry (Stripe default behavior)
+     * - "pause" — pause the subscription until payment is resolved
+     * Only applies to subscriptions with free_trial enabled.
+     */
+    trial_end_behavior?: "cancel" | "create_invoice" | "pause";
+    /**
+     * Pass-through overrides for Stripe Checkout Session params.
+     * Use this for advanced flows (e.g. Guarded Trial with manual capture) that are
+     * managed by your own billing server via Stripe webhooks.
+     *
+     * payment_intent_data: Applied when mode is "payment" (one_time, or subscription
+     *   forced to payment mode via mode_override).
+     * subscription_data: Merged into subscription_data when mode is "subscription".
+     * mode_override: Force the session mode (e.g. "payment" for a guarded trial that
+     *   uses manual capture instead of a subscription trial).
+     * consent_collection: Request consent for terms/promotions.
+     */
+    stripe_overrides?: {
+        payment_intent_data?: {
+            capture_method?: "automatic" | "automatic_async" | "manual";
+            setup_future_usage?: "off_session" | "on_session";
+            statement_descriptor?: string;
+            statement_descriptor_suffix?: string;
+            transfer_data?: {
+                destination: string;
+                amount?: number;
+            };
+        };
+        subscription_data?: {
+            description?: string;
+            metadata?: Record<string, string>;
+        };
+        /** Force session mode — use "payment" for guarded trials with manual capture */
+        mode_override?: "payment" | "subscription" | "setup";
+        consent_collection?: {
+            terms_of_service?: "required" | "none";
+            promotions?: "auto" | "none";
+        };
+    };
+    button_text?: string;
+    testimonial?: CheckoutTestimonial;
+    show_disclaimer?: boolean;
+    disclaimer_text?: string;
+    /** Custom display components to render below the order summary (FAQs, testimonials, etc.) */
+    components?: CatalogComponent[];
+    send_receipt?: boolean;
+    success_redirect?: string;
+    success_page_id?: string;
+}
+export interface CheckoutLineItem {
+    offer_id: string;
+    title: string;
+    stripe_price_id?: string;
+    /** For pay_what_you_want or arbitrary pricing: amount in cents */
+    amount_cents?: number;
+    quantity?: number;
+    /** Override the global payment_type per line item (allows mixing one_time + subscription in cart) */
+    payment_type?: CheckoutPaymentType;
+    /** Currency code (default: "usd") */
+    currency?: string;
+    /** Billing interval for subscription items (default: "month") */
+    interval?: "day" | "week" | "month" | "year";
+}
+export interface CreateCheckoutSessionRequest {
+    user_id: string;
+    catalog_slug: string;
+    tracer_id: string;
+    line_items: CheckoutLineItem[];
+    coupon_code?: string;
+    form_state: FormState;
+    success_url: string;
+    cancel_url: string;
+}
+export interface CreateCheckoutSessionResponse {
+    session_id: string;
+    session_url: string;
+}
+export interface UrlParamSettings {
+    prefill_mappings?: Record<string, string>;
+    tracking_params?: string[];
+}
+export type CartIconPreset = "cart" | "bag" | "basket";
+export type CartPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+export interface CartSettings {
+    /** Cart icon: a preset name ("cart" | "bag" | "basket") or a URL to a custom image */
+    icon?: CartIconPreset | string;
+    /** Cart drawer title (default: "Your Cart") */
+    title?: string;
+    /** Override text for the "Proceed to Checkout" button in the cart drawer */
+    checkout_button_text?: string;
+    /** External URL to redirect to on checkout instead of the built-in checkout page.
+     *  Supports {{field_id}} template variables (e.g. "https://pay.example.com?email={{email}}"). */
+    checkout_url?: string;
+    /** Position of the floating cart button (default: "bottom-right") */
+    position?: CartPosition;
+    /** Hide the floating cart button entirely (cart can still be opened programmatically via kit.openCart()) */
+    hide_button?: boolean;
+    /** Custom HTML for the cart header area (replaces default header) */
+    header_html?: string;
+    /** Custom HTML inserted above the checkout button in the footer */
+    footer_html?: string;
+    /** Custom HTML shown when the cart is empty (replaces default empty state) */
+    empty_html?: string;
+    /** Custom CSS injected as a <style> tag scoped to the cart drawer */
+    css?: string;
+    /** Structured components rendered below cart items (FAQ, text blocks, etc.) */
+    components?: CatalogComponent[];
+}
+/** Page transition animation style */
+export type PageTransition = "slide-up" | "fade" | "slide-left" | "scale" | "none";
+/** Scroll-to-top behavior when navigating between pages */
+export type PageScrollBehavior = "instant" | "smooth";
+export interface CatalogSettings {
+    theme: ThemeSettings;
+    custom_css?: string;
+    progress_bar?: boolean;
+    progress_steps?: ProgressStep[];
+    exit_intent?: ExitIntentSettings;
+    /** Trigger-based popups — keyed by popup ID */
+    popups?: Record<string, PopupConfig>;
+    gtm_id?: string;
+    scripts?: ScriptTag[];
+    checkout?: CheckoutSettings;
+    url_params?: UrlParamSettings;
+    /** Global sticky bottom bar — can be overridden per-page */
+    sticky_bar?: StickyBarConfig;
+    /** Top bar customization — hide it, add countdown, custom HTML, etc. */
+    top_bar?: TopBarConfig;
+    /** Thin progress line across the top of the viewport */
+    progress_line?: {
+        enabled?: boolean;
+        position?: "top" | "below_topbar";
+        height?: number;
+        color?: string;
+    };
+    /** Tips/messages shown during AI routing/prefill loading screen */
+    loading_tips?: string[];
+    /** Completion screen shown after final submit */
+    completion?: CompletionConfig;
+    /** Cart button, drawer, and checkout button customization */
+    cart?: CartSettings;
+    /** Page transition animation when navigating between pages (default: "slide-up") */
+    page_transition?: PageTransition;
+    /** Scroll-to-top behavior on page change: "instant" (default) or "smooth" */
+    page_scroll?: PageScrollBehavior;
+}
+export interface CompletionAction {
+    type: "fill_again" | "share" | "redirect";
+    label: string;
+    /** For redirect: target URL. Supports {{field_id}} templates. */
+    url?: string;
+    style?: "primary" | "secondary" | "ghost";
+}
+export interface CompletionConfig {
+    /** Custom heading (default: none, shows checkmark only) */
+    heading?: string;
+    /** Custom message body */
+    message?: string;
+    /** Auto-redirect URL after completion. Supports {{field_id}} templates. */
+    redirect_url?: string;
+    /** Delay in ms before auto-redirect (default: 0 = immediate) */
+    redirect_delay?: number;
+    /** Action buttons shown on completion screen */
+    actions?: CompletionAction[];
+}
+export interface CatalogSchema {
+    schema_version: string;
+    catalog_id: string;
+    slug: string;
+    tags?: string[];
+    settings: CatalogSettings;
+    pages: Record<string, CatalogPage>;
+    routing: Routing;
+    hints?: Record<string, HintDefinition>;
+    variants?: CatalogVariant[];
+    /** Variant routing strategy: random (weighted), hint (LLM), or hybrid */
+    variant_routing?: "random" | "hint" | "hybrid";
+    personalization?: {
+        rules: PersonalizationRule[];
+    };
+    /** Agent API configuration — enables headless form submission by AI agents */
+    agent?: AgentConfig;
+}
+export interface AgentConfig {
+    /** Enable the agent API for this catalog */
+    enabled: boolean;
+    /** Agent interaction mode: "form" (structured steps) or "both" (form + future chat) */
+    mode?: "form" | "both";
+    /** Description of what this catalog does, for agent discovery/routing */
+    description?: string;
+    /** Maximum session TTL in seconds (default: 3600) */
+    session_ttl?: number;
+}
+export type AgentSessionStatus = "active" | "completed" | "expired";
+export interface AgentSession {
+    session_id: string;
+    catalog_id: string;
+    user_id: string;
+    catalog_slug: string;
+    mode: "form";
+    form_state: FormState;
+    current_page_id: string;
+    completed_pages: string[];
+    status: AgentSessionStatus;
+    created_at: string;
+    updated_at: string;
+    ttl: number;
+}
+export interface FormState {
+    [componentId: string]: any;
+}
+/** Per-question quiz result */
+export interface QuizAnswer {
+    component_id: string;
+    page_id: string;
+    /** The question label (from component props) */
+    label?: string;
+    /** Available options for choice-based questions (value + label pairs) */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    given_answer: any;
+    correct_answer: string | string[];
+    is_correct: boolean;
+    points_earned: number;
+    points_possible: number;
+    explanation?: string;
+    /** Custom message for wrong answer (from quiz config) */
+    wrong_message?: string;
+}
+/** Aggregated quiz scores */
+export interface QuizScores {
+    /** Individual question results */
+    answers: QuizAnswer[];
+    /** Total points earned */
+    total: number;
+    /** Total points possible */
+    max: number;
+    /** Percentage score (0–100) */
+    percent: number;
+    /** Number of correct answers */
+    correct_count: number;
+    /** Total number of quiz questions answered */
+    question_count: number;
+}
+export interface VideoComponentState {
+    watch_percent: number;
+    watch_time: number;
+    duration: number;
+    current_chapter: number;
+    completed: boolean;
+}
+export interface VideoState {
+    [componentId: string]: VideoComponentState;
+}
+export interface TracerContext {
+    tracer_id: string;
+    url_params: Record<string, string>;
+    hints: Record<string, string>;
+    referrer?: string;
+    device_type?: string;
+    /** Quiz scores — populated at runtime for condition evaluation */
+    quiz_scores?: QuizScores;
+    /** Video player state — populated at runtime for condition evaluation */
+    video_state?: VideoState;
+}
+/**
+ * Event types follow the pattern `event` or `event:scope_id`.
+ * - Unscoped: fires for all pages/fields (e.g. `"fieldchange"`)
+ * - Scoped: fires only for a specific page or field (e.g. `"beforenext:checkout"`, `"fieldchange:email"`)
+ *
+ * Lifecycle events (React-internal, no DOM equivalent):
+ *   pageenter, pageexit, beforenext, submit, fieldchange
+ *
+ * DOM events (blur, focus, click, input, etc.) should use the DOM directly.
+ */
+export type CatalogKitEventType = string;
+export interface FieldChangeEvent {
+    fieldId: string;
+    value: any;
+    prevValue: any;
+}
+export interface PageEnterEvent {
+    pageId: string;
+}
+export interface PageExitEvent {
+    pageId: string;
+}
+export interface BeforeNextEvent {
+    pageId: string;
+    /** Call to block navigation */
+    preventDefault(): void;
+    /** Override the next page destination */
+    setNextPage(pageId: string): void;
+}
+export interface SubmitEvent {
+    pageId: string;
+    formState: Readonly<Record<string, any>>;
+    /** Call to block submission */
+    preventDefault(): void;
+}
+export interface CatalogKitAPI {
+    getField(id: string): any;
+    getAllFields(): Readonly<Record<string, any>>;
+    getVar(key: string): any;
+    getAllVars(): Readonly<Record<string, any>>;
+    getUrlParam(key: string): string | undefined;
+    getAllUrlParams(): Readonly<Record<string, string>>;
+    getPageId(): string;
+    getGlobal(key: string): any;
+    setField(id: string, value: any): void;
+    setVar(key: string, value: any): void;
+    setGlobal(key: string, value: any): void;
+    setButtonLoading(loading: boolean): void;
+    setButtonDisabled(disabled: boolean): void;
+    setValidationError(id: string, message: string | null): void;
+    goNext(): void;
+    goBack(): void;
+    setComponentProp(id: string, prop: string, value: any): void;
+    /**
+     * Subscribe to a lifecycle event. Supports scoped events:
+     *   kit.on('fieldchange', cb)              — all fields
+     *   kit.on('fieldchange:email', cb)        — only the 'email' field
+     *   kit.on('beforenext:checkout', cb)      — only on 'checkout' page
+     *   kit.on('pageenter', cb)                — all pages
+     *
+     * Async callbacks are awaited for beforenext and submit events.
+     */
+    on(event: CatalogKitEventType, callback: (payload: any) => void | Promise<void>): void;
+    off(event: CatalogKitEventType, callback: (payload: any) => void | Promise<void>): void;
+    fetch: typeof globalThis.fetch;
+}
+export interface CatalogKitRegistry {
+    /** Get an instance by catalog_id, or the most recently mounted one if omitted */
+    get(catalogId?: string): CatalogKitAPI | undefined;
+    /** Per-catalog instances keyed by catalog_id */
+    [catalogId: string]: CatalogKitAPI | ((...args: any[]) => any);
+}
+declare global {
+    interface Window {
+        CatalogKit?: CatalogKitRegistry;
+    }
+}