@salla.sa/twilight-theme-engine 1.0.0-beta.4

package/dist/types/index.d.ts

@@ -0,0 +1,724 @@
+/**
+ * Utility type for JSON-like objects.
+ * Using `{ [key: string]: {} }` to be compatible with TanStack Router's type inference,
+ * which expects all values to be non-null.
+ */
+export type JsonObject = {
+    [key: string]: {};
+};
+export interface Language {
+    name: string;
+    code: string;
+    /** 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 */
+    url: string;
+    is_rtl: boolean;
+    country_code: string;
+}
+export interface Store {
+    id: number;
+    name: string;
+    username: string;
+    description: string;
+    slogan?: string;
+    logo: string;
+    url: string;
+    api?: string;
+    icon: string;
+    favicon?: string;
+    about?: string;
+    created_at?: string;
+    updated_at?: string;
+    meta?: {
+        title?: string;
+        description?: string;
+        keywords?: string;
+    };
+    /** Store-level settings (auth, cart, product, etc.) */
+    settings: StoreSettings;
+    contacts: StoreContacts;
+    social: StoreSocial;
+    /** Store's default country code (uppercase ISO, e.g., "SA") */
+    country: string;
+    /** Store's configured country for operations (uppercase ISO, e.g., "SA") */
+    store_country?: string;
+    ray?: number;
+    features?: string[];
+    /** Mobile app download links */
+    apps?: StoreApps;
+    template?: string | null;
+    scope?: StoreScope | null;
+    is_merchant?: boolean;
+}
+/** Mobile app download URLs for the store */
+export interface StoreApps {
+    appstore?: string;
+    googleplay?: string;
+}
+export interface StoreContacts {
+    mobile?: string;
+    phone?: string;
+    email?: string;
+    whatsapp?: string;
+    telegram?: string;
+}
+export interface StoreSocial {
+    instagram?: string;
+    snapchat?: string;
+    twitter?: string;
+    youtube?: string;
+    facebook?: string;
+    pinterest?: string;
+    maroof?: string;
+    whatsapp?: string;
+    tiktok?: string;
+}
+export interface StoreSettings {
+    auth: {
+        email_allowed: boolean;
+        mobile_allowed: boolean;
+        is_email_required: boolean;
+        countries?: string[];
+        force_login?: boolean;
+    };
+    cart: {
+        apply_coupon_enabled: boolean;
+    };
+    product: {
+        total_sold_enabled: number;
+        manual_quantity?: boolean;
+        fit_type?: 'cover' | 'contain' | null;
+        related_products_enabled?: boolean;
+        filters?: boolean | null;
+        show_comments?: boolean;
+        user_can_comment?: boolean;
+        show_price_as_dash?: boolean;
+        notify_options_availability?: boolean;
+        show_special_offers?: boolean;
+        show_more?: boolean;
+        availability_notify?: {
+            email: boolean;
+            sms: boolean;
+            mobile: boolean;
+            whatsapp: boolean;
+        } | null;
+    };
+    category: {
+        testimonial_enabled: boolean;
+    };
+    payments?: string[];
+    arabic_numbers_enabled: boolean;
+    content_copyright?: boolean;
+    use_sar_symbol?: boolean;
+    is_multilingual: boolean;
+    currencies_enabled: boolean;
+    rating_enabled: boolean;
+    rating?: {
+        is_enabled: boolean;
+        show_on_category: boolean;
+        show_on_product: boolean;
+        can_rate_store: boolean;
+        can_rate_product: boolean;
+        can_rate_shipping: boolean;
+        show_rating_summary: boolean;
+        show_recommendation: boolean;
+        allow_likes: boolean;
+        allow_attach_images: boolean;
+        allow_contact_support: boolean;
+        allow_update: boolean;
+        update_period: number;
+        can_customer_hide_name: boolean;
+        visitor_can_comment: boolean;
+        page_feedback_enabled: boolean;
+    };
+    blog?: {
+        is_enabled: boolean;
+        allow_likes_and_comments: boolean;
+    };
+    is_loyalty_enabled?: boolean;
+    keys?: {
+        maps?: string;
+        gtm?: string[];
+        /** Sift Science beacon key for fraud detection - TODO: add to API response */
+        sift?: string;
+    };
+    is_salla_gateway?: boolean;
+    upload_size?: number;
+    tax?: {
+        number?: string;
+        certificate?: string | null;
+        taxable_prices_enabled: boolean;
+    };
+    certificate?: {
+        id: string;
+    } | null;
+    made_in_ksa?: boolean;
+    commercial_number?: string | null;
+    freelance_number?: string | null;
+    buy_now?: string | null;
+    installments?: string | null;
+    quick_order?: string | null;
+    bullet_delivery?: string | null;
+    ticketing_system_enabled?: boolean;
+    /** Opening hours configuration for receiving orders - TODO: add to API response */
+    opening_hours?: OpeningHoursSettings;
+    /** Feature flags - TODO: add to API response */
+    features?: {
+        price_quote?: boolean;
+        'pre-order-campaigns'?: boolean;
+    };
+}
+/**
+ * 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 */
+    enabled?: boolean;
+    /** Opening hours per day. Keys are lowercase day names (monday, tuesday, etc.) */
+    hours?: Record<string, string[]>;
+}
+export interface StoreScope {
+    id?: number;
+    name: string;
+    selected?: boolean;
+    type?: string;
+    is_open?: boolean;
+    display_as: 'popup' | 'inline' | 'default';
+    /** Available language codes (lowercase, e.g., ["ar", "en"]) */
+    languages?: string[];
+    /** Available currency codes (e.g., ["SAR", "USD"]) */
+    currencies?: string[];
+    /** Available country codes (uppercase ISO, e.g., ["SA", "AE"]) */
+    countries?: string[];
+    always_ask?: boolean;
+    allocation?: unknown | null;
+}
+export interface Theme {
+    /** May be absent in some API responses; treat as optional. */
+    id?: number;
+    name: string;
+    profile?: {
+        id: number;
+        name: string | null;
+    };
+    mode: 'live' | 'preview' | string;
+    is_rtl: boolean;
+    color: ThemeColor;
+    settings: ThemeSettings;
+    assets?: string;
+    bundle_assets?: string;
+    customization?: {
+        css?: string | null;
+        js?: string | null;
+    };
+    side_menu_enabled?: boolean | null;
+    font?: ThemeFont;
+    components?: unknown[];
+    isDark?: boolean | null;
+    /** Hash of current translations for cache invalidation */
+    translations_hash?: string;
+}
+export interface ThemeColor {
+    primary: string;
+    text: string;
+    is_dark: boolean;
+    reverse_primary: string;
+    reverse_text: string;
+}
+export interface ThemeFont {
+    id?: number;
+    name: string;
+    path?: string;
+    url?: string;
+    type?: string | number;
+    family_name?: string;
+}
+export interface ThemeSettings {
+    font?: ThemeFont;
+    imageZoom?: boolean;
+    show_tags?: boolean;
+    store_color?: string;
+    is_custom_js?: boolean;
+    homepage_type?: string;
+    theme_version?: string;
+    footer_is_dark?: boolean;
+    topnav_is_dark?: boolean;
+    use_sar_symbol?: boolean;
+    important_links?: boolean;
+    store_font_type?: string;
+    footer_menu_type?: string;
+    header_is_sticky?: boolean;
+    header_menu_type?: string;
+    default_font_name?: string;
+    sticky_add_to_cart?: boolean;
+    customization_js_ver?: number;
+    is_more_button_enabled?: boolean;
+    slider_background_size?: 'cover' | 'contain';
+    vertical_fixed_products?: boolean;
+    is_custom_widgets_enabled?: boolean;
+    squar_photo_bg_image_size?: 'cover' | 'contain';
+    is_show_more_detail_enabled?: boolean;
+    is_breadcrumbs_enabled?: boolean;
+    enable_add_product_toast?: boolean;
+    enable_more_menu?: boolean;
+}
+export interface CurrencyConfig {
+    code: string;
+    name: string;
+    symbol: string;
+    amount: number;
+    country_code: string;
+}
+export interface LanguageConfig {
+    name: string;
+    code: string;
+    url: string;
+    is_rtl: boolean;
+    country_code: string;
+}
+export interface ResponseHeaders {
+    'S-Ray': number;
+    's-version-id': number;
+    's-scope-id': number;
+    's-scope-type': string;
+}
+export interface LoginConfig {
+    url: string;
+    turnstile_site_key: string;
+    turnstile: {
+        key: string;
+        level: string;
+    };
+    social: {
+        google: boolean;
+        facebook: boolean;
+        apple: boolean;
+        x: boolean;
+    };
+}
+export interface JitsuConfig {
+    host: string;
+    key: string;
+    events: string[];
+    context: {
+        extra: {
+            version: string;
+            headers: string[];
+        };
+    };
+}
+export interface AffiliateConfig {
+    utm_url: string;
+    cta_enabled: boolean;
+}
+export interface ExternalServices {
+    [serviceName: string]: {
+        services: Record<string, unknown>;
+    };
+}
+export interface BootData {
+    store: Store;
+    theme: Theme;
+    debug: boolean;
+    trace_console: boolean;
+    external_services: ExternalServices;
+    currencies: Record<string, CurrencyConfig>;
+    languages: Record<string, LanguageConfig>;
+    headers: ResponseHeaders;
+    login: LoginConfig;
+    jitsu: JitsuConfig;
+    affiliate: AffiliateConfig;
+    swoole: string[];
+    policy_url: string;
+}
+export interface UserPreferences {
+    currency_code: string;
+    language_code: string;
+    name_visible: boolean;
+    notifications_enabled: boolean;
+}
+export interface UserSocialAccount {
+    provider_id: string;
+    provider: string;
+    linked: boolean;
+}
+export interface User {
+    type: 'guest' | 'user';
+    id?: number;
+    first_name?: string;
+    last_name?: string;
+    email?: string;
+    mobile?: string;
+    avatar?: string;
+    country_code?: string;
+    gender?: string;
+    birthday?: string | null;
+    created_at?: number;
+    preferences?: UserPreferences;
+    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 {
+    id: number;
+    name: string;
+    description: string;
+    url: string;
+    promotion_title?: string;
+    subtitle?: string;
+    type: ProductType;
+    status: ProductStatus;
+    weight?: string | null;
+    calories?: number | null;
+    sku?: string | null;
+    mpn?: string | null;
+    gtin?: string | null;
+    price: number | string;
+    sale_price: number;
+    regular_price: number;
+    starting_price?: number | null;
+    base_currency_price: {
+        currency: string;
+        amount: number;
+    } | number;
+    currency: string;
+    discount_percentage?: string;
+    price_as_float?: number;
+    price_as_float_for_payment?: number;
+    currency_for_payment?: string;
+    quantity?: number | null;
+    sold_quantity?: number;
+    max_quantity: number;
+    discount_ends?: string;
+    rating?: ProductRating;
+    category?: ProductCategory;
+    brand?: ProductBrand;
+    tags?: ProductTag[];
+    image: ProductImage;
+    images?: ProductImage[];
+    options?: ProductOption[];
+    notify_availability?: NotifyAvailability;
+    donation?: ProductDonation;
+    is_taxable: boolean;
+    has_read_more: boolean;
+    can_add_note: boolean;
+    can_show_remained_quantity: boolean;
+    can_show_sold?: boolean;
+    can_upload_file: boolean;
+    has_custom_form: boolean;
+    has_metadata: boolean;
+    has_options?: boolean;
+    has_bundle_products?: boolean;
+    is_on_sale: boolean;
+    is_hidden_quantity: boolean;
+    is_available: boolean;
+    is_in_wishlist?: boolean;
+    is_out_of_stock: boolean;
+    is_require_shipping: boolean;
+    has_3d_image?: boolean;
+    has_size_guide: boolean;
+    giftable?: boolean;
+    can_quick_buy?: boolean;
+    show_availability?: boolean;
+    has_preorder_campaign?: boolean;
+    add_to_cart_label?: string;
+    notes?: string;
+    digital_files_settings?: JsonObject;
+    preorder?: JsonObject;
+}
+export interface ProductRating {
+    count: number;
+    stars: number;
+}
+export interface ProductCategory {
+    id?: number;
+    name: string;
+    url: string;
+    icon?: string;
+    image?: string | null;
+    sub_categories?: Category[];
+}
+export interface ProductBrand {
+    id: number;
+    name?: string;
+    description?: string;
+    url?: string;
+    logo?: string;
+}
+export interface ProductTag {
+    id?: number;
+    name: string;
+    url: string;
+}
+export interface ProductImage {
+    id?: number;
+    url?: string;
+    alt?: string;
+    video_url?: string;
+    type?: 'image' | 'video';
+    three_d_image_url?: string;
+    main?: boolean;
+    sort?: number;
+}
+export interface ProductOption {
+    id: number;
+    name: string;
+    type: 'text' | 'textarea' | 'radio' | 'checkbox' | 'select' | 'image' | 'color' | string;
+    required: boolean;
+    values: ProductOptionValue[];
+}
+export interface ProductOptionValue {
+    id: number;
+    name: string;
+    price?: number;
+    image_url?: string;
+    image?: string;
+    is_selected?: boolean;
+}
+export interface NotifyAvailability {
+    channels: ('sms' | 'email' | string)[];
+    subscribed: boolean;
+    subscribed_options?: number[] | JsonObject;
+    options?: boolean;
+}
+export interface ProductDonation {
+    target_message?: string;
+    collected_amount: number;
+    target_amount: number;
+    target_percent: number;
+    target_end_date?: string;
+    can_donate: boolean;
+}
+export interface Cart {
+    /** 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 */
+    count: number;
+    items: CartItem[];
+    sub_total: number;
+    total: number | string;
+    discount: number;
+    coupon?: string | null;
+    tax_amount: number;
+    is_require_shipping?: boolean;
+    has_shipping: boolean;
+    real_shipping_cost: number;
+    free_shipping_bar?: FreeShippingBar | null;
+    options: CartOption[];
+    options_total?: number | null;
+    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.
+     */
+    gift?: {
+        enabled: boolean;
+        text?: string;
+        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.
+     */
+    loyalty?: {
+        prize: {
+            points: number;
+            title: string;
+        };
+    } | null;
+}
+export interface CartItem {
+    /** Twig docblock says `int`; API returns numeric string IDs — kept as string for safe attribute binding */
+    id: string;
+    product_id: number;
+    product_name: string;
+    product_image: string;
+    url: string;
+    quantity: number;
+    max_quantity?: number;
+    type: ProductType | string;
+    price: number | Money;
+    product_price: number | Money;
+    original_price?: number | Money;
+    total: number | Money;
+    total_special_price?: number | Money;
+    weight_label?: string;
+    notes?: string;
+    is_available: boolean;
+    is_hidden_quantity: boolean;
+    is_on_sale?: boolean;
+    has_discount?: boolean;
+    can_add_note: boolean;
+    can_upload_file: boolean;
+    offer?: CartItemOffer | null;
+    detailed_offers?: JsonObject[] | null;
+    donation?: JsonObject | null;
+    attachments?: CartItemAttachment[];
+    options?: CartItemOption[];
+    /** TODO: add to API response — indicates item has an active pre-order campaign */
+    has_pre_order_campaign?: boolean;
+}
+export interface CartItemOption {
+    id: number;
+    name?: string;
+    value?: string;
+    quantity?: number;
+    options?: Record<string, string | number | boolean>[];
+}
+export interface CartItemOffer {
+    discount: number;
+    is_free: boolean;
+    names?: string;
+}
+export interface CartItemAttachment {
+    id: number;
+    url: string;
+    product_id: number;
+    item_id: number;
+    /** Twig docblock incorrectly types this as `int` — it is a filename string */
+    name: string;
+}
+export interface FreeShippingBar {
+    minimum_amount: number;
+    has_free_shipping: boolean;
+    percent: number;
+    remaining: number;
+}
+export interface CartOption {
+    id: number;
+    name?: string;
+    value?: string;
+    quantity?: number;
+    options?: Record<string, string | number | boolean>[];
+}
+export interface Money {
+    amount: number;
+    currency: string;
+    formatted?: string;
+}
+export interface Breadcrumb {
+    name: string;
+    url: string;
+}
+export interface Page {
+    title: string;
+    slug: string;
+    description?: string;
+    /** Entity ID associated with the page (e.g. category ID on a category page). */
+    id?: string | number;
+    /** URL of the current page. */
+    url?: string;
+    /** Parent entity, if any. */
+    parent?: {
+        id: string | number;
+        name: string;
+        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: number | string;
+    /** Raw numeric ID, e.g. 868669273 */
+    id_?: number;
+    name: string;
+    description?: string;
+    url: string;
+    /** 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.
+     */
+    image?: string | null;
+    products_count?: number;
+    sub_categories?: Category[];
+    /** Always null from the API; reserved for future use */
+    items?: null;
+}
+export interface Slider {
+    id: number;
+    image: string;
+    link?: string;
+    title?: string;
+    description?: string;
+}
+export interface HomeComponentConfig {
+    key: string;
+    title?: string;
+    path: string;
+    position: number;
+    data: JsonObject;
+}
+/**
+ * Home component data from Salla API
+ * Used by HomePage to render dynamic components
+ */
+export interface HomeComponentData {
+    path: string;
+    key?: string | number | null;
+    view_style?: string | null;
+    component?: JsonObject;
+    [key: string]: string | number | boolean | null | JsonObject | undefined;
+}
+export interface TranslationMap {
+    [key: string]: string | TranslationMap;
+}
+export type ComponentType<P = Record<string, unknown>> = React.ComponentType<P>;
+export interface ComponentDefinition {
+    component: ComponentType;
+    displayName?: string;
+    original?: ComponentDefinition;
+}
+export * from './hooks';
+export interface Brand {
+    id: number;
+    name: string;
+    logo: string;
+    url: string;
+}
+export interface Feature {
+    icon: string;
+    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`.
+     */
+    description?: string;
+}
+export interface Testimonial {
+    id: number;
+    name: string;
+    content: string;
+    rating?: number;
+    image?: string;
+}
+import type { ReactNode } from 'react';
+export interface HomeComponent {
+    background?: string;
+    title?: string;
+    description?: string;
+    products?: Product[];
+    display_all_url?: string;
+}
+export interface LayoutProps {
+    children: ReactNode;
+}
+/**
+ * Menu item structure from Salla API
+ */
+export interface MenuItem {
+    id: number | string;
+    title: string;
+    url: string;
+    children?: MenuItem[];
+    has_children?: boolean;
+}
+//# sourceMappingURL=index.d.ts.map