@salla.sa/twilight-theme-engine 1.0.71 → 1.0.72

package/dist/types/index.d.ts

@@ -7,13 +7,17 @@ export type JsonObject = {
     [key: string]: {};
 };
 export interface Language {
+    /** Language name written in that language. */
     name: string;
+    /** Language code. */
     code: string;
-    /** Same as `code` — the SDK's salla-localization-modal reads `iso_code`, not `code` */
+    /** Same as `code` — the SDK's salla-localization-modal reads `iso_code`, not `code`. */
     iso_code?: string;
-    /** Flag icon URL (e.g., "https://assets.salla.sa/images/flags/ar.svg") - NOT the store URL */
+    /** Flag icon URL (e.g., "https://assets.salla.sa/images/flags/ar.svg") - NOT the store URL. */
     url: string;
+    /** Whether the language is written right to left. */
     is_rtl: boolean;
+    /** Country code used to pick the flag. */
     country_code: string;
     /**
      * Whether this store has its own wording for this language.
@@ -30,175 +34,396 @@ export interface Language {
     has_custom_translations?: boolean;
 }
 export interface Store {
+    /** Store id. */
     id: number;
+    /** Store name, as the merchant typed it. */
     name: string;
+    /** Store username. */
     username: string;
+    /** Store description, as HTML rather than plain text. */
     description: string;
+    /** Store slogan. */
     slogan?: string;
+    /** Logo image URL. */
     logo: string;
+    /** Store home URL. On a multilingual store it ends with the language prefix (`/ar/`). */
     url: string;
+    /** Base URL of the store API. */
     api?: string;
+    /** Icon image URL. */
     icon: string;
+    /** Favicon URL. Marked for removal. */
     favicon?: string;
+    /** Longer "about the store" text. */
     about?: string;
+    /** When the store was created. */
     created_at?: string;
+    /** When the store was last updated. */
     updated_at?: string;
+    /** Default SEO values for pages that set none. Empty strings when the merchant set none. */
     meta?: {
+        /** Default page title. */
         title?: string;
+        /** Default page description. */
         description?: string;
+        /** Default page keywords. */
         keywords?: string;
     };
-    /** Store-level settings (auth, cart, product, etc.) */
+    /** Store-level settings (auth, cart, product, ratings and so on). */
     settings: StoreSettings;
+    /** Contact details the store shows to customers. */
     contacts: StoreContacts;
+    /** Links to the store's social media profiles. */
     social: StoreSocial;
-    /** Store's default country code (uppercase ISO, e.g., "SA") */
+    /** Store's default country code (uppercase ISO, e.g., "SA"). */
     country: string;
-    /** Store's configured country for operations (uppercase ISO, e.g., "SA") */
+    /** Country the store operates in (uppercase ISO, e.g., "SA"). */
     store_country?: string;
+    /** Internal platform request value; nothing in a theme should depend on it. */
     ray?: number;
+    /** Platform feature flags that are on for this store. */
     features?: string[];
-    /** Mobile app download links */
+    /** Mobile app download links. */
     apps?: StoreApps;
+    /** Reserved by the platform; usually null. */
     template?: string | null;
+    /** The selected market or branch, or null when the store has none. */
     scope?: StoreScope | null;
+    /** Whether the visitor is the merchant. Marked for removal: rely on `theme.mode` instead. */
     is_merchant?: boolean;
+    /** Whether the store offers pickup (mirrors `shipping.support_pickup`). */
+    support_pickup?: boolean;
+    /** Shipping and delivery options the store offers. */
+    shipping?: StoreShipping;
+    /** Store-wide rating summary. */
+    rating?: {
+        /** Number of ratings the store has received. */
+        total: number;
+        /** Average star rating. */
+        stars: number;
+    };
+    /** Rating distribution: how many ratings gave each star value. */
+    ratings?: {
+        /** The star value (for example 5). */
+        stars: number;
+        /** Number of ratings that gave this star value. */
+        total: number;
+    }[];
+    /** Order confirmation page messages (HTML strings). */
+    order_instruction?: StoreOrderInstruction;
+}
+export interface StoreShipping {
+    /** Delivery location details, or null when the store has none. */
+    delivery_location?: unknown | null;
+    /** Express-delivery promise details, or null when the store has none. */
+    express_delivery_promise?: unknown | null;
+    /** Whether the store offers pickup. */
+    support_pickup?: boolean;
+    /** Whether products show the fast-delivery ("bullet") tag. */
+    has_bullet_delivery_tag?: boolean;
+}
+export interface StoreOrderInstruction {
+    /** Heading of the order confirmation page. */
+    thank_title?: string;
+    /** Message shown while the order waits for payment. */
+    order_instructions_payment_waiting?: string;
+    /** Message shown while the order is under review. */
+    order_instructions_under_review?: string;
+    /** Message shown once the order is completed. */
+    order_instructions_completed?: string;
 }
 /** Mobile app download URLs for the store */
 export interface StoreApps {
+    /** App Store link. */
     appstore?: string;
+    /** Google Play link. */
     googleplay?: string;
 }
 export interface StoreContacts {
+    /** Mobile number. */
     mobile?: string;
+    /** Phone number. */
     phone?: string;
+    /** Support email address. */
     email?: string;
+    /** WhatsApp link or number. */
     whatsapp?: string;
+    /** Telegram link. */
     telegram?: string;
 }
 export interface StoreSocial {
+    /** Instagram profile link. */
     instagram?: string;
+    /** Snapchat profile link. */
     snapchat?: string;
+    /** X (Twitter) profile link. */
     twitter?: string;
+    /** YouTube channel link. */
     youtube?: string;
+    /** Facebook page link. */
     facebook?: string;
+    /** Pinterest profile link. */
     pinterest?: string;
+    /** Maroof page link. */
     maroof?: string;
+    /** WhatsApp link. */
     whatsapp?: string;
+    /** TikTok profile link. */
     tiktok?: string;
 }
 export interface StoreSettings {
+    /** Sign-in and registration options. */
     auth: {
+        /** Customers can sign in with email. */
         email_allowed: boolean;
+        /** Customers can sign in with a mobile number. */
         mobile_allowed: boolean;
+        /** Email is required when registering. */
         is_email_required: boolean;
+        /** Country codes allowed for mobile numbers, lowercase. */
         countries?: string[];
+        /** Visitors must sign in to browse the store. */
         force_login?: boolean;
+        /** Customers can sign in through WhatsApp. */
+        whatsapp_allowed?: boolean;
+        /** Country codes where WhatsApp sign-in is offered. */
+        whatsapp_countries?: string[];
+        /** Whether the merchant has enabled WhatsApp sign-in. */
+        whatsapp_merchant_allowed?: boolean;
+        /** Visitor's detected country (uppercase ISO), e.g. "DE". */
+        user_country?: string;
+        /** Extra sign-in configuration sent by the platform; its shape is not typed, and it is null when unused. */
+        config?: unknown | null;
     };
+    /** Cart options. */
     cart: {
+        /** Show the coupon field in the cart. */
         apply_coupon_enabled: boolean;
+        /** Platform flag for the cart layout. */
+        basket_gap?: boolean;
+        /** More than one coupon can be applied. */
+        multi_coupon?: boolean;
     };
+    /** Product page and listing options. */
     product: {
+        /** Show how many units were sold. It is 1 or 0, not a boolean. */
         total_sold_enabled: number;
+        /** Customers can type the quantity instead of using a stepper. */
         manual_quantity?: boolean;
+        /** How product images fill their frame; null when not set. */
         fit_type?: 'cover' | 'contain' | null;
+        /** Show related products. */
         related_products_enabled?: boolean;
-        filters?: boolean | null;
+        /** Switches for the listing filters, one per filter (`{ category_id: true, price: true, ... }`). */
+        filters?: ProductFiltersSettings | boolean | null;
+        /** Kind of product recommendations to show. The key has hyphens, so read it with brackets. */
+        'product-recommendation-type'?: string;
+        /** Show "bought together" products. */
+        bought_together?: boolean;
+        /** Show product comments. */
         show_comments?: boolean;
+        /** Customers can comment on products. */
         user_can_comment?: boolean;
+        /** Hide prices and show a dash instead. */
         show_price_as_dash?: boolean;
+        /** Offer "notify me" for sold-out options. */
         notify_options_availability?: boolean;
+        /** Show special offers on the product. */
         show_special_offers?: boolean;
+        /** Show the "show more" control. */
         show_more?: boolean;
+        /** Channels offered for "notify me when available", or null when the feature is off. */
         availability_notify?: {
+            /** Notify by email. */
             email: boolean;
+            /** Notify by SMS. */
             sms: boolean;
+            /** Notify by mobile notification. */
             mobile: boolean;
+            /** Notify by WhatsApp. */
             whatsapp: boolean;
         } | null;
     };
+    /** Category page options. */
     category: {
+        /** Show testimonials on category pages. */
         testimonial_enabled: boolean;
     };
+    /** Enabled payment methods. */
     payments?: string[];
+    /** Show Arabic-Indic digits. */
     arabic_numbers_enabled: boolean;
+    /** Content copy protection is on. */
     content_copyright?: boolean;
+    /** Show the Saudi riyal symbol instead of the currency code. */
     use_sar_symbol?: boolean;
+    /** The store offers more than one language. */
     is_multilingual: boolean;
+    /** The store offers more than one currency. */
     currencies_enabled: boolean;
+    /** Ratings are turned on for the store. */
     rating_enabled: boolean;
+    /** Rating and review options. */
     rating?: {
+        /** Ratings are on. */
         is_enabled: boolean;
+        /** Show ratings on category pages. */
         show_on_category: boolean;
+        /** Show ratings on product pages. */
         show_on_product: boolean;
+        /** Customers can rate the store. */
         can_rate_store: boolean;
+        /** Customers can rate products. */
         can_rate_product: boolean;
+        /** Customers can rate shipping. */
         can_rate_shipping: boolean;
+        /** Show the rating summary block. */
         show_rating_summary: boolean;
+        /** Show the "would you recommend" question. */
         show_recommendation: boolean;
+        /** Reviews can be liked. */
         allow_likes: boolean;
+        /** Reviews can include images. */
         allow_attach_images: boolean;
+        /** Show a contact-support action on reviews. */
         allow_contact_support: boolean;
+        /** Customers can edit their review. */
         allow_update: boolean;
+        /** Number of days a review can be edited. */
         update_period: number;
+        /** Reviewers can hide their name. */
         can_customer_hide_name: boolean;
+        /** Visitors who are not signed in can comment. */
         visitor_can_comment: boolean;
+        /** Page feedback is on. */
         page_feedback_enabled: boolean;
     };
+    /** Blog options. */
     blog?: {
+        /** The blog is on. */
         is_enabled: boolean;
+        /** Readers can like and comment on articles. */
         allow_likes_and_comments: boolean;
     };
+    /** The loyalty program is on. */
     is_loyalty_enabled?: boolean;
+    /** Public keys for third-party services. */
     keys?: {
+        /** Maps API key for the storefront. */
         maps?: string;
+        /** Google Tag Manager container ids. */
         gtm?: string[];
-        /** Sift Science beacon key for fraud detection - TODO: add to API response */
+        /** Sift Science beacon key for fraud detection. Not yet sent by the API. */
         sift?: string;
     };
+    /** The store uses the Salla payment gateway. */
     is_salla_gateway?: boolean;
+    /** Maximum upload size. */
     upload_size?: number;
+    /** Tax details. */
     tax?: {
+        /** Tax registration number. */
         number?: string;
+        /** Tax certificate image URL, or null. */
         certificate?: string | null;
+        /** Prices include tax. */
         taxable_prices_enabled: boolean;
     };
+    /** Commerce certificate details, or null. */
     certificate?: {
+        /** Commerce certificate id. */
         id: string;
     } | null;
+    /** Show the "Made in KSA" mark. */
     made_in_ksa?: boolean;
+    /** Commercial registration number, or null. */
     commercial_number?: string | null;
+    /** Freelance license number, or null. */
     freelance_number?: string | null;
-    buy_now?: string | null;
-    installments?: string | null;
-    quick_order?: string | null;
-    bullet_delivery?: string | null;
+    /** Fast-checkout (Apple Pay style) configuration object, or null when off. Typed `string | null` in older releases; the API sends an object. */
+    buy_now?: BuyNowSettings | string | null;
+    /** Installment providers. An empty array means none, and an empty array is truthy. */
+    installments?: unknown[] | Record<string, unknown> | string | null;
+    /** Quick-order configuration, or null when off. */
+    quick_order?: Record<string, unknown> | string | null;
+    /** Fast ("bullet") delivery configuration, or null when off. */
+    bullet_delivery?: Record<string, unknown> | string | null;
+    /** Support tickets are on. */
     ticketing_system_enabled?: boolean;
-    /** Opening hours configuration for receiving orders - TODO: add to API response */
+    /** Opening hours for receiving orders. Not yet sent by the API. */
     opening_hours?: OpeningHoursSettings;
-    /** Feature flags - TODO: add to API response */
+    /** Feature flags. Not yet sent by the API. */
     features?: {
+        /** Customers can ask for a price quote. */
         price_quote?: boolean;
+        /** Pre-order campaigns are available. */
         'pre-order-campaigns'?: boolean;
     };
 }
+export interface ProductFiltersSettings {
+    /** Filter by category. */
+    category_id?: boolean;
+    /** Filter by brand. */
+    brand_id?: boolean;
+    /** Filter by price range. */
+    price?: boolean;
+    /** Filter by product variants. */
+    variants?: boolean;
+    /** Filter by rating. */
+    rating?: boolean;
+    /** Filter by tag. */
+    tag_name?: boolean;
+    [filter: string]: boolean | undefined;
+}
+/** Shape of `store.settings.buy_now` when the fast-checkout button is on. */
+export interface BuyNowSettings {
+    /** Button label. */
+    label?: string;
+    /** Store country code used by the payment sheet. */
+    countryCode?: string;
+    /** Countries the fast-checkout button supports. */
+    supportedCountries?: string[];
+    /** Card networks the payment sheet supports. */
+    supportedNetworks?: string[];
+    /** URL the merchant session is validated against. */
+    validateUri?: string;
+    /** Whether the MyFatoorah server-to-server flow is used. */
+    myfatoorahS2s?: boolean;
+    /** Currency code of the payment. */
+    currency?: string;
+    /** Card networks accepted. */
+    networks?: string[];
+    /** Countries where the button is offered. */
+    countries?: string[];
+    /** Whether the product is digital, so no shipping is needed. */
+    is_digital?: boolean;
+    /** Merchant identifier registered with the payment provider. */
+    merchant_identifier?: string;
+    [key: string]: unknown;
+}
 /**
  * Opening hours settings for receiving orders.
  * Uses the Spatie\OpeningHours format (day names as keys).
  * TODO: add to API response
  */
 export interface OpeningHoursSettings {
-    /** Whether the opening hours feature is enabled */
+    /** The store only takes orders during opening hours. */
     enabled?: boolean;
-    /** Opening hours per day. Keys are lowercase day names (monday, tuesday, etc.) */
+    /** Time ranges per lowercase day name (monday, tuesday, ...). A day with no entry or an empty list is closed. */
     hours?: Record<string, string[]>;
 }
 export interface StoreScope {
+    /** Scope id. */
     id?: number;
+    /** Market or branch name. */
     name: string;
+    /** This scope is the active one. */
     selected?: boolean;
+    /** Scope type, such as a branch. */
     type?: string;
+    /** The scope is open. */
     is_open?: boolean;
+    /** How the scope selector is shown. */
     display_as: 'popup' | 'inline' | 'default';
     /** Available language codes (lowercase, e.g., ["ar", "en"]) */
     languages?: string[];
@@ -206,106 +431,184 @@ export interface StoreScope {
     currencies?: string[];
     /** Available country codes (uppercase ISO, e.g., ["SA", "AE"]) */
     countries?: string[];
+    /** Ask the visitor to choose a scope. */
     always_ask?: boolean;
+    /** Allocation details sent by the platform, or null; its shape is not typed. */
     allocation?: unknown | null;
 }
 export interface Theme {
-    /** May be absent in some API responses; treat as optional. */
+    /** Theme id. Not sent by the settings API (absent on the demo store); treat as optional. */
     id?: number;
+    /** Theme name. The engine adds it to `<body>` as the class `salla-<name>`. */
     name: string;
+    /** The merchant's theme profile (the saved set of choices). */
     profile?: {
+        /** Profile id. */
         id: number;
+        /** Profile name, or null. */
         name: string | null;
     };
+    /** 'preview' while the merchant previews a draft (the engine adds the body class `preview-mode`), otherwise 'live'. */
     mode: 'live' | 'preview' | string;
+    /** Whether the theme reads right to left. */
     is_rtl: boolean;
+    /** Brand colors of the theme. */
     color: ThemeColor;
+    /** Merchant values for the theme's settings. */
     settings: ThemeSettings;
+    /** URL template of the theme's published files; `:path` stands for the file path. */
     assets?: string;
+    /** URL template of component bundles (`:bundle`, `:component`). */
     bundle_assets?: string;
+    /** The merchant's custom CSS and JS, as a URL or inline code. The engine loads them for you. */
     customization?: {
+        /** Custom CSS, or null. */
         css?: string | null;
+        /** Custom JS, or null. */
         js?: string | null;
     };
+    /** Whether the merchant turned on the side menu. */
     side_menu_enabled?: boolean | null;
     /** Platform-pinned twilight SDK release, served from the production CDN. */
     twilight?: {
+        /** The pinned SDK version, or null. */
         version?: string | null;
     };
+    /** The selected font. Can be missing. */
     font?: ThemeFont;
+    /** Not typed and empty on the demo store. Home blocks do not come from here. */
     components?: unknown[];
+    /** Sent by the platform, usually null. Use `color.is_dark` instead. */
     isDark?: boolean | null;
     /** Hash of current translations for cache invalidation */
     translations_hash?: string;
 }
 export interface ThemeColor {
+    /** Primary brand color. */
     primary: string;
+    /** Text color chosen for the theme. */
     text: string;
+    /** Dark color scheme. The engine adds `color-mode-dark` or `color-mode-light` to `<body>`. */
     is_dark: boolean;
+    /** The reverse counterpart of the primary color. */
     reverse_primary: string;
+    /** Text color to put on top of `primary`. */
     reverse_text: string;
 }
 export interface ThemeFont {
+    /** Font id. */
     id?: number;
+    /** Font family name. */
     name: string;
+    /** Relative path of the stylesheet that loads the font. */
     path?: string;
+    /** Stylesheet URL that loads the font. */
     url?: string;
+    /** Source of the font. `theme.font` sends a string, `theme.settings.font` a number. */
     type?: string | number;
+    /** CSS family name. Present on `settings.font`, not on `theme.font`. */
     family_name?: string;
 }
 export interface ThemeSettings {
+    /** The selected font. */
     font?: ThemeFont;
+    /** Zoom on the product gallery. */
     imageZoom?: boolean;
+    /** Show product tags. */
     show_tags?: boolean;
+    /** Brand color value. Platform-managed. */
     store_color?: string;
+    /** Whether the merchant has custom JS. Platform-managed. */
     is_custom_js?: boolean;
+    /** Whether the merchant has custom CSS. Platform-managed. */
+    is_custom_css?: boolean;
+    /** Kind of home page. Platform-managed. */
     homepage_type?: string;
+    /** Installed theme version. Platform-managed. */
     theme_version?: string;
+    /** Dark footer. Adds `footer-is-dark` or `footer-is-light` to `<body>`. */
     footer_is_dark?: boolean;
+    /** Dark top bar. Adds the body class `topnav-is-dark`. */
     topnav_is_dark?: boolean;
+    /** Show the Saudi riyal symbol instead of the currency code. */
     use_sar_symbol?: boolean;
+    /** Show the important-links block. Platform-managed. */
     important_links?: boolean;
+    /** Font type of the store. Platform-managed. */
     store_font_type?: string;
+    /** Footer menu variant. Platform-managed. */
     footer_menu_type?: string;
+    /** Keep the main menu at the top while scrolling. */
     header_is_sticky?: boolean;
-    /** Breadcrumb trail on the product page / product list pages (default on). */
+    /** Breadcrumb trail on the product page (default on). */
     product_show_breadcrumbs?: boolean;
+    /** Breadcrumb trail on product list pages (default on). */
     product_index_show_breadcrumbs?: boolean;
     /** Out-of-stock cards offer "notify me when available" (default on). */
     notify_when_available_in_card?: boolean;
+    /** Header menu variant. Platform-managed. */
     header_menu_type?: string;
+    /** Header layout variant of the reference theme. */
     header_layout?: 'lite' | 'default';
+    /** Footer layout variant of the reference theme. */
     footer_layout?: 'columns' | 'centered';
+    /** Product card image ratio. Either shape can arrive. */
     product_card_img_ratio?: string | {
         value?: string;
     }[];
+    /** Name of the default font. Platform-managed. */
     default_font_name?: string;
+    /** Sticky add-to-cart bar on mobile. Adds `is-sticky-product-bar` to `<body>`. */
     sticky_add_to_cart?: boolean;
-    customization_js_ver?: number;
+    /** Version of the merchant's custom JS, or null. Platform-managed. */
+    customization_js_ver?: number | null;
+    /** Version of the merchant's custom CSS, or null. Platform-managed. */
+    customization_css_ver?: number | null;
+    /** Hash of current translations (also sent at `theme.translations_hash`). */
+    translations_hash?: string;
+    /** The "All" button on home blocks. */
     is_more_button_enabled?: boolean;
+    /** How product gallery images fit their frame. */
     slider_background_size?: 'cover' | 'contain';
+    /** Show products in a vertical fixed layout. */
     vertical_fixed_products?: boolean;
+    /** Custom widgets are enabled. */
     is_custom_widgets_enabled?: boolean;
+    /** How images fit in the square-photos block. */
     squar_photo_bg_image_size?: 'cover' | 'contain';
+    /** Show the "more details" control. */
     is_show_more_detail_enabled?: boolean;
+    /** Breadcrumbs on or off. */
     is_breadcrumbs_enabled?: boolean;
     /** Image the SDK's product cards show when a product has none. */
     placeholder?: string;
+    /** Show a toast after adding to the cart. */
     enable_add_product_toast?: boolean;
+    /** Show the "More" menu. */
     enable_more_menu?: boolean;
 }
 export interface CurrencyConfig {
+    /** Currency code. */
     code: string;
+    /** Currency name. */
     name: string;
+    /** Currency symbol. */
     symbol: string;
+    /** Exchange rate against the store's base currency. */
     amount: number;
+    /** Country code of the currency's flag. */
     country_code: string;
 }
 export interface LanguageConfig {
+    /** Language name written in that language. */
     name: string;
+    /** Language code. */
     code: string;
+    /** URL of the language's flag icon, not a store page. */
     url: string;
+    /** Whether the language is written right to left. */
     is_rtl: boolean;
+    /** Country code used to pick the flag. */
     country_code: string;
     /** @see Language.has_custom_translations — the same field, same payload. */
     has_custom_translations?: boolean;
@@ -365,311 +668,551 @@ export interface BootData {
     swoole: string[];
     policy_url: string;
 }
+/**
+ * `auth/user` needs a logged-in session, so the key names could not be checked against
+ * the public demo store. The user API test fixture (`tests/api/user.test.ts`) sends
+ * `currency` / `language`, while engine code (`useGtm`) reads `currency_code`. Both
+ * spellings are declared, optional, until the real response is confirmed.
+ */
 export interface UserPreferences {
-    currency_code: string;
-    language_code: string;
+    /** Currency the customer chose. */
+    currency_code?: string;
+    /** Language the customer chose. */
+    language_code?: string;
+    /** Currency the customer chose, under the other key the API may use. */
+    currency?: string;
+    /** Language the customer chose, under the other key the API may use. */
+    language?: string;
+    /** Whether the customer's name is visible to others. */
     name_visible: boolean;
+    /** Whether the customer accepts marketing messages. */
     notifications_enabled: boolean;
 }
 export interface UserSocialAccount {
+    /** The customer's id at that provider. */
     provider_id: string;
+    /** Provider name, such as "google". */
     provider: string;
+    /** Whether the account is currently linked. */
     linked: boolean;
 }
 export interface User {
+    /** Kind of customer. `useUser` only ever gives 'user'; a guest is null. */
     type: 'guest' | 'user';
+    /** Customer id. */
     id?: number;
+    /** First name. */
     first_name?: string;
+    /** Last name. */
     last_name?: string;
+    /** Email address. */
     email?: string;
+    /** Mobile number with the country prefix. */
     mobile?: string;
+    /** Avatar image URL. */
     avatar?: string;
+    /** Country of the customer. */
     country_code?: string;
+    /** Gender as saved in the profile. */
     gender?: string;
+    /** Birthday, or null. */
     birthday?: string | null;
+    /** When the account was created, as Unix seconds. */
     created_at?: number;
+    /** The customer's saved preferences. */
     preferences?: UserPreferences;
+    /** Linked social sign-in accounts. */
     social_accounts?: UserSocialAccount[];
 }
 export type ProductType = 'product' | 'service' | 'group_products' | 'codes' | 'digital' | 'food' | 'donating' | 'booking' | 'financial_support';
 export type ProductStatus = 'sale' | 'out' | 'out-and-notify' | 'hidden';
 export interface Product {
+    /** Product id. Number on `products/{id}/details`, but a numeric STRING on list responses (`products`, e.g. "677709975"). Typed `number`: use `Number(product.id)` when you compare ids from a list item. */
     id: number;
+    /** Product name in the current language. */
     name: string;
+    /** Product description, as HTML. May be empty. */
     description: string;
+    /** Absolute URL of the product page. */
     url: string;
+    /** Badge text the merchant set. Can be "" or null. */
     promotion_title?: string;
+    /** Short line under the name. */
     subtitle?: string;
+    /** Product type. */
     type: ProductType;
+    /** Product availability status. */
     status: ProductStatus;
+    /** Weight with its unit, as text. */
     weight?: string | null;
+    /** Calories, for food products. */
     calories?: number | null;
+    /** Merchant SKU. Can be "" or null. */
     sku?: string | null;
+    /** Barcode. Can be "" or null. */
     barcode?: string | null;
+    /** Manufacturer part number. Can be "" or null. */
     mpn?: string | null;
+    /** Global trade item number. Can be "" or null. */
     gtin?: string | null;
+    /** What the customer pays now. Show this when the product is not on sale. */
     price: number | string;
-    sale_price: number;
+    /** The discounted price. `null` on list responses when the product is not on sale; `0` on `products/{id}/details` in the same case. Check `is_on_sale` rather than the truthiness of this field. */
+    sale_price: number | null;
+    /** The price before the discount. */
     regular_price: number;
+    /** Lowest SKU price of a product with variants, otherwise null. */
     starting_price?: number | null;
+    /** Price in the store's base currency. */
     base_currency_price: {
+        /** Currency code of the base currency. */
         currency: string;
+        /** Amount in the base currency. */
         amount: number;
     } | number;
+    /** Currency code of the prices. */
     currency: string;
+    /** Declared but never sent by the Salla API (absent on list and detail). Compute it from `regular_price` and `price`. */
     discount_percentage?: string;
+    /** Price as a plain float. */
     price_as_float?: number;
+    /** Price as a plain float, as used for payment. */
     price_as_float_for_payment?: number;
+    /** Currency code used for payment. */
     currency_for_payment?: string;
+    /** Stock on hand. `-1` means UNLIMITED stock (what `products/{id}/details` sends for products without a tracked quantity), not "one short". List responses send `null` and expose `unlimited_quantity` instead. */
     quantity?: number | null;
+    /** Units sold. Absent or null when not shown. */
     sold_quantity?: number;
+    /** Most the customer can add to the cart. Null on list responses. */
     max_quantity: number;
+    /** When the discount ends. */
     discount_ends?: string;
+    /** Reviews summary. Null on the demo store. */
     rating?: ProductRating;
+    /** The product's category. */
     category?: ProductCategory;
+    /** The product's brand. */
     brand?: ProductBrand;
+    /** The product's tags. Empty when there are none. */
     tags?: ProductTag[];
+    /** The main image. On list items it has only `url`. */
     image: ProductImage;
+    /** The image gallery. Detail responses only. */
     images?: ProductImage[];
+    /** Options the customer picks, such as size or color. Detail responses only. */
     options?: ProductOption[];
+    /** Variant rows. Present only when requested with `with[]=skus`. */
     skus?: ProductSku[];
+    /** "Notify me when available" settings and subscription state. Detail responses only. */
     notify_availability?: NotifyAvailability;
+    /** Donation progress, for products of type 'donating'. */
     donation?: ProductDonation;
+    /** Tax applies to the product. */
     is_taxable: boolean;
+    /** The description is long: collapse it behind "Read more". */
     has_read_more: boolean;
+    /** The add-to-cart form shows a note field. */
     can_add_note: boolean;
+    /** Whether to show `quantity` to customers. */
     can_show_remained_quantity: boolean;
+    /** Declared but never sent by the Salla API (absent on list and detail). */
     can_show_sold?: boolean;
+    /** The add-to-cart form shows a file upload. */
     can_upload_file: boolean;
+    /** The merchant added a custom form to the product. */
     has_custom_form: boolean;
+    /** The product has extra spec data. */
     has_metadata: boolean;
+    /** The product has options. */
     has_options?: boolean;
+    /** The product is a bundle of other products. */
     has_bundle_products?: boolean;
+    /** A discount is active. */
     is_on_sale: boolean;
-    is_hidden_quantity: boolean;
+    /** The quantity input is hidden (the customer buys one). Sent on `products/{id}/details` only. List responses use the misspelled `is_hidded_quantity`. */
+    is_hidden_quantity?: boolean;
+    /** The API's own (misspelled) name for `is_hidden_quantity` on list responses. */
+    is_hidded_quantity?: boolean;
+    /** The product can be bought. */
     is_available: boolean;
+    /** Whether the product is in the wishlist. Prefer `useWishlist` over reading this. */
     is_in_wishlist?: boolean;
+    /** The customer cannot buy it now. */
     is_out_of_stock: boolean;
+    /** The product needs shipping. */
     is_require_shipping: boolean;
+    /** The product has a 3D image. */
     has_3d_image?: boolean;
+    /** A size guide exists for the product. */
     has_size_guide: boolean;
+    /** The product can be bought as a gift. */
     giftable?: boolean;
+    /** Show a "buy now" button. */
     can_quick_buy?: boolean;
+    /** Show the product's availability state. */
     show_availability?: boolean;
+    /** A pre-order campaign is active. */
     has_preorder_campaign?: boolean;
+    /** The product is a wallet gift card. Sent on `products/{id}/details`. */
+    is_wallet_gift_card?: boolean;
+    /** The product can be picked up. */
+    supports_pickup?: boolean;
+    /** The product can be delivered. */
+    supports_delivery?: boolean;
+    /** Products bundled into this one (bundle products); `null`/absent otherwise. */
+    included_products?: Product[] | null;
+    /** Custom add-to-cart button label. Not sent by the demo store. */
     add_to_cart_label?: string;
+    /** The customer's note for the product. */
     notes?: string;
+    /** File settings of a digital product. */
     digital_files_settings?: JsonObject;
+    /** Pre-order details; `preorder.label` is shown as the card badge. */
     preorder?: JsonObject;
 }
 export interface ProductRating {
+    /** Number of ratings. */
     count: number;
+    /** Average star rating. */
     stars: number;
 }
 export interface ProductCategory {
+    /** Category id. */
     id?: number;
+    /** Category name. Can be null on list responses. */
     name: string;
+    /** Category page URL. Can be null on list responses. */
     url: string;
+    /** CSS icon class of the category. */
     icon?: string;
+    /** Category image URL, or null. */
     image?: string | null;
+    /** Child categories. */
     sub_categories?: Category[];
 }
 export interface ProductBrand {
+    /** Brand id. A slug string on the demo store. */
     id: number;
+    /** Brand name. */
     name?: string;
+    /** Brand description. */
     description?: string;
+    /** Brand page URL. */
     url?: string;
+    /** Brand logo URL. */
     logo?: string;
 }
 export interface ProductTag {
+    /** Tag id. */
     id?: number;
+    /** Tag text. */
     name: string;
+    /** Tag page URL. */
     url: string;
 }
 export interface ProductImage {
+    /** Image id. */
     id?: number;
+    /** Image URL. */
     url?: string;
+    /** Alt text; usually the product name. */
     alt?: string;
+    /** Video URL when the item is a video, otherwise null. */
     video_url?: string;
+    /** Media kind. The API also sends '3d-image' for a 3D main image. */
     type?: 'image' | 'video';
+    /** `.glb` 3D model URL, or "" when none. */
     three_d_image_url?: string;
+    /** True for the main image. */
     main?: boolean;
+    /** Position in the gallery. */
     sort?: number;
 }
 export interface ProductOption {
+    /** Option id. */
     id: number;
+    /** Option label. */
     name: string;
-    type: 'text' | 'textarea' | 'radio' | 'checkbox' | 'select' | 'image' | 'color' | string;
+    /** Kind of input. Unknown types should be treated as a plain list. */
+    type: 'text' | 'textarea' | 'radio' | 'checkbox' | 'select' | 'image' | 'color' | 'thumbnail' | 'single-option' | string;
+    /** The customer must choose a value. */
     required: boolean;
-    /** Listing shape. Absent on `products/{id}/details`, which sends `details` instead. */
+    /** Values in the older listing shape. Absent on `products/{id}/details`, which sends `details` instead. */
     values?: ProductOptionValue[];
+    /** Values on a detail response. */
     details?: ProductOptionDetail[];
 }
 export interface ProductOptionDetail {
+    /** Value id. This is what a SKU's `related_option_values` lists. */
     id: number;
+    /** Value label. */
     name: string;
+    /** Id of the option the value belongs to. */
     option_id: number;
+    /** Extra price when this value is picked. */
     additional_price: number;
+    /** The raw value: a color hex, an image id, or "". */
     option_value: string;
+    /** Image URL, or the hex for a color. */
     image: string;
+    /** Color hex for `color` options. */
     color: string;
+    /** Merchant code of the value. */
     code: string;
+    /** This value is out of stock. */
     is_out: boolean;
+    /** 1 for the preselected value, otherwise 0. */
     is_default: 0 | 1;
+    /** SKU id to in-stock flag, for the SKUs that use this value. */
     skus_availability: Record<string, boolean>;
 }
 /** Variant rows from `products/{id}/details?with[]=skus`. */
 export interface ProductSku {
+    /** SKU id. */
     id: number;
+    /** Id of the parent product. */
     product_id: number;
+    /** SKU price as a `{ amount, currency }` object. */
     price: Money;
+    /** SKU price before any discount. */
     regular_price: Money;
+    /** Discounted SKU price, or null when not discounted. */
     sale_price: Money | null;
+    /** A discount applies to this SKU. */
     has_special_price: boolean;
+    /** Stock on hand, or null when unlimited. */
     stock_quantity: number | null;
+    /** Stock is not tracked. */
     unlimited_quantity: boolean;
+    /** This is the default SKU. */
     is_default: boolean;
+    /** Ids of the options the SKU is made of. */
     related_options: number[];
+    /** Ids of the option values that select this SKU. */
     related_option_values: number[];
 }
 export interface ProductOptionValue {
+    /** Value id. */
     id: number;
+    /** Value label. */
     name: string;
+    /** Extra price when this value is picked. */
     price?: number;
+    /** Image URL of the value. */
     image_url?: string;
+    /** Image URL of the value. */
     image?: string;
+    /** This value is preselected. */
     is_selected?: boolean;
 }
 export interface NotifyAvailability {
+    /** Channels the customer can be notified through. */
     channels: ('sms' | 'email' | string)[];
+    /** The customer has asked to be notified. */
     subscribed: boolean;
+    /** Options the customer subscribed to, when they subscribed per option. */
     subscribed_options?: number[] | JsonObject;
+    /** Whether subscription is offered per option. */
     options?: boolean;
 }
 export interface ProductDonation {
+    /** Message shown with the donation goal. */
     target_message?: string;
+    /** Amount collected so far. */
     collected_amount: number;
+    /** Amount the donation aims to collect. */
     target_amount: number;
+    /** Progress towards the goal, as a percentage. */
     target_percent: number;
+    /** When the donation campaign ends. */
     target_end_date?: string;
+    /** Donations are currently accepted. `ProductCard` hides the price when this is true. */
     can_donate: boolean;
 }
 export interface Cart {
-    /** Twig: string — matches API string cart ID (SDK CartSummary incorrectly types this as number) */
+    /** Cart id. Twig: string — matches API string cart ID (SDK CartSummary incorrectly types this as number) */
     id: string;
-    /** Present in SDK CartSummary; not documented in Twig docblock */
+    /** Number of items. Present in SDK CartSummary; not documented in Twig docblock */
     count: number;
+    /** The cart lines. An empty array means an empty cart. */
     items: CartItem[];
+    /** Items total, the first row of the order summary. */
     sub_total: number;
+    /** Final amount. */
     total: number | string;
+    /** Discount amount. */
     discount: number;
+    /** Applied coupon code, or null. */
     coupon?: string | null;
+    /** Tax amount. */
     tax_amount: number;
+    /** Whether anything in the cart needs shipping. */
     is_require_shipping?: boolean;
+    /** Whether a shipping cost applies now. */
     has_shipping: boolean;
+    /** The shipping cost. */
     real_shipping_cost: number;
+    /** Progress towards free shipping. Null or missing when the store does not offer it. */
     free_shipping_bar?: FreeShippingBar | null;
+    /** Order-level options. */
     options: CartOption[];
+    /** Total price of the order-level options. */
     options_total?: number | null;
+    /** Discount row of the order summary. Often 0, null or missing: test with `!!`. */
     total_discount?: number | null;
     /** React-only runtime flag — triggers a client-side cart re-fetch after mutations */
     should_refresh?: boolean;
-    /**
-     * Twig exposes `gift` as a top-level page variable, not nested inside `cart`.
-     * The REST API returns it inside the cart object, so the loader maps it here.
-     */
+    /** Gifting settings, or null. Twig exposes `gift` as a top-level page variable, not nested inside `cart`; the REST API returns it inside the cart object, so the loader maps it here. */
     gift?: {
+        /** Gifting is on. */
         enabled: boolean;
+        /** Gift message text. */
         text?: string;
+        /** Gift type. */
         type?: string;
     } | null;
-    /**
-     * Twig exposes `loyalty` as a top-level page variable, not nested inside `cart`.
-     * The REST API returns it inside the cart object, so the loader maps it here.
-     */
+    /** The loyalty reward the customer can win, or null. Twig exposes `loyalty` as a top-level page variable, not nested inside `cart`; the REST API returns it inside the cart object, so the loader maps it here. */
     loyalty?: {
+        /** The reward. */
         prize: {
+            /** Points the reward costs. */
             points: number;
+            /** Reward title. */
             title: string;
         };
     } | null;
 }
 export interface CartItem {
-    /** Twig docblock says `int`; API returns numeric string IDs — kept as string for safe attribute binding */
+    /** Line id. Use it to update or remove the line, not `product_id`. Twig docblock says `int`; API returns numeric string IDs — kept as string for safe attribute binding */
     id: string;
+    /** Id of the product. */
     product_id: number;
+    /** Product name. */
     product_name: string;
+    /** Image URL (a plain string, not an image object). */
     product_image: string;
+    /** Product page URL. */
     url: string;
+    /** Quantity in the cart. */
     quantity: number;
+    /** Most the customer can buy. */
     max_quantity?: number;
+    /** Product type, such as "product" or "donating". */
     type: ProductType | string;
+    /** Unit price the customer pays. */
     price: number | Money;
+    /** Unit price of the product. */
     product_price: number | Money;
+    /** Price before a sale. */
     original_price?: number | Money;
+    /** Line total. */
     total: number | Money;
+    /** Line total after tiered offers. */
     total_special_price?: number | Money;
+    /** Readable weight, such as "2 kg". */
     weight_label?: string;
+    /** The customer's note. */
     notes?: string;
+    /** False when the product is out of stock. */
     is_available: boolean;
+    /** When true, show the quantity as text instead of a stepper. */
     is_hidden_quantity: boolean;
+    /** A sale price applies. */
     is_on_sale?: boolean;
+    /** A discount applies. */
     has_discount?: boolean;
+    /** The product accepts a note. */
     can_add_note: boolean;
+    /** The product accepts file attachments. */
     can_upload_file: boolean;
+    /** A simple offer on this line, or null. */
     offer?: CartItemOffer | null;
+    /** Detailed offers, shown by the offers component. */
     detailed_offers?: JsonObject[] | null;
+    /** Donation data when `type` is "donating". */
     donation?: JsonObject | null;
+    /** Files the customer uploaded. */
     attachments?: CartItemAttachment[];
+    /** The options the customer picked. */
     options?: CartItemOption[];
-    /** TODO: add to API response — indicates item has an active pre-order campaign */
+    /** Item has an active pre-order campaign. TODO: add to API response */
     has_pre_order_campaign?: boolean;
 }
 export interface CartItemOption {
+    /** Option id. */
     id: number;
+    /** Option name. */
     name?: string;
+    /** Chosen value. */
     value?: string;
+    /** Quantity, when the option has one. */
     quantity?: number;
+    /** Nested option details. */
     options?: Record<string, string | number | boolean>[];
 }
 export interface CartItemOffer {
+    /** Discount amount. */
     discount: number;
+    /** The item is free. */
     is_free: boolean;
+    /** Offer name to show. */
     names?: string;
 }
 export interface CartItemAttachment {
+    /** Attachment id. */
     id: number;
+    /** File URL. */
     url: string;
+    /** Product the file belongs to. */
     product_id: number;
+    /** Cart line the file belongs to. */
     item_id: number;
-    /** Twig docblock incorrectly types this as `int` — it is a filename string */
+    /** File name. Twig docblock incorrectly types this as `int` — it is a filename string */
     name: string;
 }
 export interface FreeShippingBar {
+    /** Cart value needed for free shipping. */
     minimum_amount: number;
+    /** True once the customer has reached it. */
     has_free_shipping: boolean;
+    /** Progress from 0 to 100, ready for a bar width. */
     percent: number;
+    /** Amount still missing. It is a plain number: format it yourself. */
     remaining: number;
 }
 export interface CartOption {
+    /** Option id. */
     id: number;
+    /** Option name. */
     name?: string;
+    /** Chosen value. */
     value?: string;
+    /** Quantity, when the option has one. */
     quantity?: number;
+    /** Nested option details. */
     options?: Record<string, string | number | boolean>[];
 }
 export interface Money {
+    /** The amount as a number. */
     amount: number;
+    /** Currency code. */
     currency: string;
+    /** Ready-made text, when the API sends one. */
     formatted?: string;
 }
 export interface Breadcrumb {
+    /** Label. */
     name: string;
+    /** Link target. */
     url: string;
 }
 export interface Page {
+    /** Page title. */
     title: string;
+    /** Route id of the page, such as "product.single". */
     slug: string;
+    /** Page description. */
     description?: string;
     /** Entity ID associated with the page (e.g. category ID on a category page). */
     id?: string | number;
@@ -677,38 +1220,48 @@ export interface Page {
     url?: string;
     /** Parent entity, if any. */
     parent?: {
+        /** Parent entity id. */
         id: string | number;
+        /** Parent entity name. */
         name: string;
+        /** Parent entity URL. */
         url: string;
     } | null;
     /** Breadcrumb trail built by the route loader. If omitted, useBreadcrumbs provides a fallback. */
     breadcrumbs?: Breadcrumb[];
 }
 export interface Category {
-    /** Hashed string ID as returned by the API, e.g. "xzjvNQ" */
+    /** Id as the API sends it, a hashed string such as "xzjvNQ". */
     id: number | string;
-    /** Raw numeric ID, e.g. 868669273 */
+    /** The raw numeric id, e.g. 868669273. */
     id_?: number;
+    /** Category name. */
     name: string;
+    /** Category description. */
     description?: string;
+    /** Full URL of the category page. */
     url: string;
-    /** CSS icon class, e.g. "sicon-store", or null */
+    /** CSS icon class, e.g. "sicon-store", or null. */
     icon?: string | null;
-    /**
-     * Flat image URL string (NOT a nested ProductImage object).
-     * Aligns with both the API response and Twig which treat this as a plain URL.
-     */
+    /** Flat image URL string (NOT a nested ProductImage object), or null. Aligns with both the API response and Twig. */
     image?: string | null;
+    /** Number of products in the category. */
     products_count?: number;
+    /** Child categories, possibly empty. */
     sub_categories?: Category[];
-    /** Always null from the API; reserved for future use */
-    items?: null;
+    /** Mirror of `sub_categories` on parent categories (an array, possibly empty); `null` on some root categories without children. */
+    items?: Category[] | null;
 }
 export interface Slider {
+    /** Slide id. */
     id: number;
+    /** Slide image URL. */
     image: string;
+    /** URL the slide links to. */
     link?: string;
+    /** Slide title. */
     title?: string;
+    /** Slide text. */
     description?: string;
 }
 export interface HomeComponentConfig {
@@ -740,26 +1293,33 @@ export interface ComponentDefinition {
 }
 export * from './hooks';
 export interface Brand {
-    id: number;
+    /** Brand id. Number on `brands` list responses; the brands route type declares a string. */
+    id: number | string;
+    /** Brand name. */
     name: string;
+    /** Brand logo image URL. */
     logo: string;
+    /** Brand page URL. */
     url: string;
 }
 export interface Feature {
+    /** Icon class or URL of the feature. */
     icon: string;
+    /** Feature title. */
     title: string;
-    /**
-     * Subtitle text for the feature. Internally mapped from the raw API / Twig
-     * field `text` (which is `items[].text` in `store-features.twig`).
-     * The mapping happens in `StoreFeatures.tsx`.
-     */
+    /** Subtitle text for the feature. Internally mapped from the raw API / Twig field `text` (which is `items[].text` in `store-features.twig`). The mapping happens in `StoreFeatures.tsx`. */
     description?: string;
 }
 export interface Testimonial {
+    /** Testimonial id. */
     id: number;
+    /** Name of the customer who wrote it. */
     name: string;
+    /** Testimonial text. */
     content: string;
+    /** Star rating the customer gave. */
     rating?: number;
+    /** Customer image URL. */
     image?: string;
 }
 import type { ReactNode } from 'react';
@@ -777,12 +1337,25 @@ export interface LayoutProps {
  * Menu item structure from Salla API
  */
 export interface MenuItem {
+    /** Item id. Built-in links use a word, such as "offers" or "blog". */
     id: number | string;
+    /** Text to show. */
     title: string;
+    /** Link URL. */
     url: string;
     /** Root-level image the merchant attached in the menu builder, when there is one. */
     image?: string | null;
+    /** Sub-items. Missing on some items: use `children ?? []`. */
     children?: MenuItem[];
+    /** Whether there are sub-items. Missing on some items. */
     has_children?: boolean;
+    /** Link target, e.g. "_self". */
+    target?: string;
+    /** Sort position. */
+    order?: number;
+    /** Raw HTML attribute string for the item element (e.g. ` id="offers"`). */
+    attrs?: string;
+    /** Raw HTML attribute string for the anchor (e.g. ` target="_self" class="offers-link"`). */
+    link_attrs?: string;
 }
 //# sourceMappingURL=index.d.ts.map