@thorprovider/types 2.0.2

package/dist/index.d.ts

@@ -0,0 +1,3341 @@
+/**
+ * @thorprovider/types v3.0
+ * Common types shared across all commerce providers
+ * Universal interfaces compatible with: Shopify, Medusa.js, WooCommerce, Magento, BigCommerce
+ */
+/**
+ * Monetary value with currency
+ *
+ * Using string for amount prevents float precision errors.
+ * Compatible with:
+ * - Shopify: MoneyV2 (amount: Decimal, currencyCode: CurrencyCode)
+ * - Medusa: numbers (converted to string)
+ * - WooCommerce: strings ("21.99")
+ * - Magento: Float (converted to string)
+ */
+interface Money {
+    amount: string;
+    currencyCode: string;
+}
+/**
+ * Image with metadata
+ *
+ * Universal format for product/variant images.
+ * Compatible with all platforms (URLs are normalized in adapters).
+ */
+interface Image {
+    id?: string;
+    url: string;
+    altText: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * SEO metadata
+ */
+interface SEO {
+    title: string;
+    description: string;
+}
+/**
+ * Generic connection type for paginated data
+ */
+interface Connection<T> {
+    edges: Array<Edge<T>>;
+}
+interface Edge<T> {
+    node: T;
+}
+/**
+ * Pagination options
+ */
+interface PaginationOptions {
+    first?: number;
+    after?: string;
+    last?: number;
+    before?: string;
+}
+/**
+ * Sort options
+ */
+interface SortOptions {
+    sortKey?: string;
+    reverse?: boolean;
+}
+/**
+ * Country information
+ *
+ * Represents a country available in a region.
+ * Used for shipping address validation and checkout forms.
+ * Compatible with:
+ * - Medusa: Country entity with iso_2, name, display_name
+ * - Shopify: CountryCode enum
+ * - WooCommerce: WC_Countries
+ */
+interface Country {
+    /** ISO 3166-1 alpha-2 country code (e.g., "US", "ES", "DE") */
+    code: string;
+    /** Human-readable country name (e.g., "United States", "Spain") */
+    name: string;
+    /** ISO 3166-1 alpha-3 country code (optional, e.g., "USA", "ESP") */
+    iso3?: string;
+    /** ISO 3166-1 numeric code (optional, e.g., "840", "724") */
+    numCode?: string;
+}
+
+/**
+ * Header Configuration Types
+ *
+ * Type definitions for configurable header navigation system.
+ * Supports static links, mega menus, preset components (cart, account),
+ * dynamic data injection, and hybrid icon system.
+ */
+/**
+ * Icon configuration with hybrid support
+ * - Lucide: Reference by string name for lucide-react icons
+ * - Custom: Provide React component/element directly
+ */
+type IconConfig = {
+    type: 'lucide';
+    name: string;
+} | {
+    type: 'custom';
+    component: React.ReactNode;
+};
+/**
+ * Navigation callout item (featured content in dropdown)
+ */
+interface NavigationCalloutItem {
+    logo?: string;
+    image?: string;
+    heading: string;
+    description: string;
+    href: string;
+}
+/**
+ * Navigation link item
+ */
+interface NavigationLinkItem {
+    title: string;
+    description?: string;
+    href: string;
+    badge?: {
+        content: number | string;
+        variant?: 'solid' | 'soft';
+        color?: string;
+    };
+}
+/**
+ * Dynamic data source for navigation content
+ * - 'categories': Fetch and inject categories from backend
+ * - 'collections': Fetch and inject collections from backend
+ */
+type DynamicSource = 'categories' | 'collections';
+/**
+ * Header link item - extends NavigationMenuItem with additional features
+ */
+type HeaderLinkItem = {
+    /** Simple direct link */
+    type: 'link';
+    label: string;
+    href: string;
+    icon?: IconConfig;
+    badge?: {
+        content: number | string;
+        variant?: 'solid' | 'soft';
+        color?: string;
+    };
+} | {
+    /** Dropdown menu with content */
+    type: 'dropdown';
+    label: string;
+    icon?: IconConfig;
+    badge?: {
+        content: number | string;
+        variant?: 'solid' | 'soft';
+        color?: string;
+    };
+    /** Optional dynamic data injection */
+    dynamicSource?: DynamicSource;
+    content: {
+        callout?: NavigationCalloutItem;
+        links: NavigationLinkItem[];
+        sideBanner?: NavigationCalloutItem;
+        columns?: number;
+        layout?: 'one' | 'two';
+    };
+} | {
+    /** Preset component (cart, account) */
+    type: 'preset';
+    preset: 'cart' | 'account';
+    /** Override default config for preset */
+    config?: Record<string, any>;
+};
+/**
+ * Account dropdown menu item
+ */
+type AccountMenuItem = {
+    /** Menu item label */
+    label: string;
+    /** Navigation href */
+    href?: string;
+    /** Icon configuration */
+    icon?: IconConfig;
+    /** Click handler (for actions like logout) */
+    onClick?: () => void;
+    /** Destructive action styling (e.g., logout, delete) */
+    destructive?: boolean;
+    divider?: never;
+} | {
+    /** Render as divider */
+    divider: true;
+    label?: never;
+    href?: never;
+    icon?: never;
+    onClick?: never;
+    destructive?: never;
+};
+/**
+ * Account dropdown configuration
+ */
+interface AccountDropdownConfig {
+    /** Enable account dropdown */
+    enabled: boolean;
+    /** Trigger label (e.g., "Mi cuenta") */
+    label?: string;
+    /** Trigger icon */
+    icon?: IconConfig;
+    /** Dropdown menu items */
+    items: AccountMenuItem[];
+    /** Logout handler */
+    onLogout?: () => void;
+}
+/**
+ * Search bar configuration
+ */
+interface SearchBarConfig {
+    /** Enable search bar */
+    enabled?: boolean;
+    /** Fixed width in pixels */
+    width?: number;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Minimum characters to trigger search */
+    minChars?: number;
+}
+/**
+ * Main header navigation configuration
+ */
+interface HeaderNavigationConfig {
+    /** Logo configuration */
+    logo?: {
+        /** Logo image path */
+        src: string;
+        /** Logo alt text */
+        alt: string;
+        /** Logo width (px) */
+        width?: number;
+        /** Logo height (px) */
+        height?: number;
+        /** Logo link href */
+        href?: string;
+    };
+    /** Left navigation group (before search bar) */
+    leftLinks?: HeaderLinkItem[];
+    /** Right navigation group (after search bar) */
+    rightLinks?: HeaderLinkItem[];
+    /** Search bar configuration */
+    search?: SearchBarConfig;
+    /** Account dropdown configuration (if not using preset in rightLinks) */
+    account?: AccountDropdownConfig;
+    /** Cart configuration (if not using preset in rightLinks) */
+    cart?: {
+        /** Optional label rendered next to the cart icon in header (e.g., "Carrito") */
+        label?: string;
+        variant?: 'mini' | 'drawer';
+        composition?: 'compact' | 'detailed';
+        showBadge?: boolean;
+    };
+    /** Maximum container width (px) */
+    maxWidth?: number;
+    /** Enable overflow menu for excess links */
+    enableOverflow?: boolean;
+}
+
+/**
+ * Site Configuration Types
+ *
+ * Foundation for multi-tenant, framework-agnostic site configuration.
+ * Defines the structure for branding, metadata, navigation, and module presets.
+ *
+ * @module site-config
+ */
+
+/**
+ * Brand Information
+ */
+interface BrandConfig {
+    name: string;
+    title: string;
+    description: string;
+    tagline?: string;
+    logo?: string;
+    logoDark?: string;
+    preset?: string;
+}
+/**
+ * Site Metadata & Authorship
+ */
+interface AuthorConfig {
+    /** Name of the author or organization */
+    name: string;
+    /** Primary contact email */
+    email: string;
+}
+/**
+ * Social Media Links
+ */
+type SocialConfig = Record<string, string>;
+/**
+ * Navigation Item (Simple)
+ */
+interface NavigationItem {
+    /** Display name of the link or button */
+    name: string;
+    /** URL or anchor for the link */
+    href: string;
+}
+/**
+ * Footer link categorization
+ */
+interface FooterLinksConfig {
+    /** Customer shopping shortcuts */
+    shop: NavigationItem[];
+    /** Customer service and support links */
+    support: NavigationItem[];
+    /** Corporate and information links */
+    company: NavigationItem[];
+    /** Legal, privacy, and policy links */
+    legal: NavigationItem[];
+}
+/**
+ * Copyright information for the site
+ */
+interface CopyrightConfig {
+    /** Current year or range (e.g., "2024" or "2023-2024") */
+    year: string | number;
+    /** Legal text following the year */
+    text: string;
+}
+/**
+ * Module-specific configurations
+ */
+interface ModulesConfig {
+    cart: {
+        mini: {
+            variant: 'mini';
+            composition: 'compact' | 'full' | 'separate-pages';
+        };
+        page: {
+            variant: 'page';
+            composition: 'compact' | 'full';
+        };
+    };
+    checkout: {
+        default: {
+            variant: 'simple' | 'standard' | 'complete';
+            composition: 'accordion' | 'wizard' | 'single-page';
+        };
+    };
+    profile: {
+        default: {
+            variant: 'basic' | 'standard' | 'complete';
+            composition: 'tabs' | 'accordion' | 'separate-pages' | 'side';
+        };
+    };
+}
+/**
+ * Complete Site Configuration
+ *
+ * Centralized interface for site-wide settings.
+ * Supports merging with database-stored overrides via Developer Dashboard.
+ */
+interface SiteConfig {
+    /** Brand identity and basic info */
+    name: string;
+    title: string;
+    description: string;
+    tagline?: string;
+    logo?: string;
+    logoDark?: string;
+    preset?: string;
+    /** URLs and social */
+    url?: string;
+    author?: AuthorConfig;
+    social?: SocialConfig;
+    /** Navigation structures */
+    navigation?: NavigationItem[];
+    header?: HeaderNavigationConfig;
+    /** Footer content and links */
+    footerLinks: FooterLinksConfig;
+    /** Copyright statement */
+    copyright: CopyrightConfig;
+    /** Module behavior & UI variants */
+    modules: ModulesConfig;
+    /**
+     * Extension point for custom properties
+     * Necessary for experimental features before they are formally typed
+     */
+    [key: string]: any;
+}
+
+/**
+ * SiteConfigLabels - All translatable strings from site-config
+ *
+ * Maps to messages/siteConfig.* namespace in next-intl.
+ * Used in L5 to provide i18n-aware labels to components that otherwise use siteConfig.
+ *
+ * IMPORTANT: This interface contains ONLY translatable text — no hrefs, images, or structural config.
+ * Structural config (hrefs, images, module presets) stays in site-config.ts.
+ *
+ * Footer/featuredCategories labels are simple string arrays mapped by index to
+ * the corresponding entries in siteConfig.footerLinks / siteConfig.featuredCategories.
+ *
+ * @see packages/core/messages/en.json (siteConfig namespace)
+ * @see packages/core/hooks/use-site-config-labels.ts
+ */
+interface SiteConfigLabels {
+    title: string;
+    description: string;
+    tagline: string;
+    header: {
+        products: {
+            label: string;
+            newArrivals: {
+                heading: string;
+                description: string;
+            };
+            summerSale: {
+                heading: string;
+                description: string;
+            };
+            links: {
+                allProducts: string;
+                allProductsDescription: string;
+                newArrivals: string;
+                newArrivalsDescription: string;
+                bestSellers: string;
+                bestSellersDescription: string;
+                sale: string;
+                saleDescription: string;
+            };
+        };
+        categories: {
+            label: string;
+        };
+        account: {
+            label: string;
+            items: {
+                profile: string;
+                orders: string;
+                logout: string;
+            };
+        };
+        cart: {
+            label: string;
+        };
+        search: {
+            placeholder: string;
+        };
+    };
+    footer: {
+        shopTitle: string;
+        supportTitle: string;
+        companyTitle: string;
+        shop: string[];
+        support: string[];
+        company: string[];
+        legal: string[];
+    };
+    hero: {
+        badge: string;
+        title: string;
+        description: string;
+        primaryCta: string;
+        secondaryCta: string;
+    };
+    promo: {
+        badge: string;
+        title: string;
+        description: string;
+        emailPlaceholder: string;
+        ctaText: string;
+    };
+    featuredCategories: string[];
+    copyright: {
+        text: string;
+    };
+}
+
+/**
+ * Inventory & fulfillment types
+ *
+ * Foundation layer (L1) types used by adapters, UI, and starters.
+ */
+
+interface StockLocation {
+    id: string;
+    name: string;
+    address?: {
+        address1: string;
+        address2?: string;
+        city: string;
+        countryCode: string;
+        postalCode: string;
+        province?: string;
+    };
+    metadata?: {
+        lat?: number;
+        lng?: number;
+        timezone?: string;
+    };
+}
+interface InventoryLevel {
+    locationId: string;
+    locationName: string;
+    availableQuantity: number;
+    reservedQuantity: number;
+    incomingQuantity?: number;
+    stockedQuantity: number;
+}
+interface FulfillmentSet {
+    id: string;
+    name: string;
+    type: 'shipping' | 'pickup' | 'return';
+    location: StockLocation;
+}
+interface FulfillmentOption {
+    id: string;
+    providerId: string;
+    name: string;
+    description?: string;
+    price: Money;
+    estimatedDays?: string;
+    stockLocation: StockLocation;
+    fulfillmentSet?: FulfillmentSet;
+    distance?: number;
+}
+type StockStatus = 'in_stock' | 'out_of_stock' | 'low_stock';
+interface StockValidation {
+    allAvailable: boolean;
+    unavailableItems: Array<{
+        variantId: string;
+        productName: string;
+        requestedQuantity: number;
+        availableQuantity: number;
+    }>;
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Product types - unified interface for all commerce providers
+ */
+
+/**
+ * Product variant option (e.g., Size: Large, Color: Red)
+ */
+interface ProductOption {
+    id: string;
+    name: string;
+    values: string[];
+}
+/**
+ * Selected option for a variant
+ */
+interface SelectedOption {
+    name: string;
+    value: string;
+}
+/**
+ * Product variant (SKU)
+ *
+ * Universal format compatible with:
+ * - Shopify: ProductVariant with price/compareAtPrice as MoneyV2
+ * - Medusa: StoreProductVariant with calculated_price
+ * - WooCommerce: Variation with price/regular_price
+ * - Magento: ConfigurableProductOptions
+ */
+interface ProductVariant {
+    id: string;
+    title: string;
+    sku?: string;
+    availableForSale: boolean;
+    selectedOptions: SelectedOption[];
+    price: Money;
+    compareAtPrice?: Money;
+    quantityAvailable?: number;
+    stockStatus?: StockStatus;
+    inventoryLevels?: InventoryLevel[];
+    image?: Image;
+}
+/**
+ * Price range for product
+ */
+interface PriceRange {
+    minVariantPrice: Money;
+    maxVariantPrice: Money;
+}
+/**
+ * Main product type - normalized across all providers
+ *
+ * Universal format compatible with:
+ * - Shopify: Product (Storefront API 2024-01)
+ * - Medusa.js: StoreProduct (v2)
+ * - WooCommerce: Product (REST API v3)
+ * - Magento/Adobe Commerce: ProductInterface (GraphQL)
+ *
+ * Platform-specific fields are stored in metadata.
+ */
+interface Product {
+    id: string;
+    handle: string;
+    title: string;
+    description: string;
+    descriptionHtml?: string;
+    availableForSale: boolean;
+    options: ProductOption[];
+    variants: ProductVariant[];
+    featuredImage?: Image;
+    images: Image[];
+    priceRange: PriceRange;
+    collections?: Array<{
+        id: string;
+        title: string;
+        handle: string;
+    }>;
+    productType?: string;
+    vendor?: string;
+    tags?: string[];
+    seo?: SEO;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for fetching products
+ */
+interface GetProductsOptions {
+    query?: string;
+    sortKey?: string;
+    reverse?: boolean;
+    first?: number;
+    skip?: number;
+    /** Cursor (string) or offset (number) for pagination */
+    after?: string | number;
+    regionId?: string;
+    /** Basic category filtering — backend IDs resolved from URL slugs */
+    categoryIds?: string[];
+    /** Basic collection filtering — backend IDs resolved from URL slugs */
+    collectionIds?: string[];
+}
+/**
+ * Represents a single active filter displayed as a chip
+ * Used in ActiveFiltersChips component
+ */
+interface ActiveFilter {
+    /** Unique identifier (e.g., "material-wood") */
+    id: string;
+    /** Display category (e.g., "Material") */
+    category: string;
+    /** Display value (e.g., "Wood") */
+    label: string;
+    /** Raw value for tracking */
+    value: string | string[];
+}
+/**
+ * Sort options available for product listing
+ */
+type SortOption = 'featured' | 'price-asc' | 'price-desc' | 'name' | 'newest' | 'rating';
+/**
+ * A single option within a filter section (e.g., "Wood" under "Material")
+ */
+interface FilterOption {
+    /** URL-friendly slug (human-readable). This is what goes in the URL. */
+    value: string;
+    /** Display label shown in the UI. */
+    label: string;
+    /**
+     * Backend identifier (e.g., database ID).
+     * Present when `value` is a human-readable slug that differs from the
+     * backend ID. Used by L5 page.tsx to resolve slug → ID before querying
+     * the adapter. Optional: when absent, `value` is used as the backend ID.
+     */
+    id?: string;
+    /** Optional facet count */
+    count?: number;
+}
+/**
+ * Represents a collapsible filter section in the sidebar
+ */
+interface FilterSection {
+    id: string;
+    label: string;
+    type: 'checkbox' | 'range' | 'radio' | 'select';
+    options?: FilterOption[];
+    min?: number;
+    max?: number;
+    defaultExpanded?: boolean;
+}
+/**
+ * Simplified product preview for e-commerce patterns
+ * Used in ProductCard, QuickView, etc.
+ */
+interface ProductPreview {
+    id: string;
+    name: string;
+    price: number;
+    originalPrice?: number;
+    image: string;
+    rating: number;
+    reviewCount: number;
+    isNew?: boolean;
+    isOnSale?: boolean;
+    isOutOfStock?: boolean;
+    discountPercent?: number;
+    stock?: number;
+    category?: string;
+    description?: string;
+}
+/**
+ * Product review type
+ */
+interface Review {
+    id: string;
+    author: string;
+    rating: number;
+    date: string;
+    title: string;
+    body: string;
+    verified?: boolean;
+}
+/**
+ * Product compare item structure
+ */
+interface CompareProduct {
+    id: string;
+    name: string;
+    image: string;
+    price: number;
+    attributes: Record<string, string>;
+}
+/**
+ * Product variant as returned by the admin API.
+ *
+ * Distinct from `ProductVariant` (storefront API) because admin variants
+ * carry backend-specific fields like inventory counts and raw prices.
+ */
+interface AdminProductVariant {
+    id: string;
+    title: string;
+    sku?: string;
+    /** Total inventory quantity across all stock locations */
+    quantityAvailable?: number;
+    /** Prices available for this variant */
+    prices?: Array<{
+        amount: number;
+        currencyCode: string;
+    }>;
+}
+/**
+ * Product as returned by the admin API.
+ *
+ * Intentionally separate from `Product` (storefront API) because:
+ * - The storefront API only returns published products and derives
+ *   `availableForSale` from stock/sales-channel rules — no explicit status.
+ * - The admin API returns ALL products (including draft, proposed, rejected)
+ *   with the backend-native `status` field.
+ *
+ * Use this type exclusively in admin dashboard contexts.
+ */
+interface AdminProduct {
+    id: string;
+    handle: string;
+    title: string;
+    /** Optional product description */
+    description?: string;
+    /**
+     * Backend-native status string.
+     * Values are provider-specific — e.g. 'published' | 'draft' | 'proposed' | 'rejected'.
+     */
+    status: string;
+    variants: AdminProductVariant[];
+    /** URL of the product thumbnail image */
+    thumbnail?: string;
+    /** URLs of all product images */
+    images?: string[];
+}
+/**
+ * Options for advanced product search (requires backend search engine support).
+ * Extends GetProductsOptions so it can be passed as a fallback to getProducts().
+ * Used with CommerceProvider.searchProductsAdvanced().
+ */
+interface AdvancedSearchProductsOptions extends GetProductsOptions {
+    /** Filter by category IDs */
+    categoryIds?: string[];
+    /** Filter by collection IDs */
+    collectionIds?: string[];
+    /** Filter by tag IDs */
+    tagIds?: string[];
+    /** Minimum price (in major currency units) */
+    priceMin?: number;
+    /** Maximum price (in major currency units) */
+    priceMax?: number;
+    /** Currency code for price filtering */
+    currencyCode?: string;
+    /** Only include products with stock available */
+    inStockOnly?: boolean;
+    /** Attribute filters (e.g. RAM, brand) */
+    attributes?: Array<{
+        id: string;
+        values: string[];
+    }>;
+    /** Include variant-level data in results */
+    includeVariants?: boolean;
+}
+/**
+ * Metadata returned alongside advanced search results.
+ */
+interface SearchResultMeta {
+    /** Total number of matching products */
+    total?: number;
+    /** Max results requested */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Backend search processing time in milliseconds */
+    processingTimeMs?: number;
+    /** Whether hybrid (vector + keyword) search was used */
+    hybridSearchUsed?: boolean;
+    /** Filters that were actually applied by the backend search engine */
+    appliedFilters?: Record<string, unknown>;
+    /** Price context used for price filtering */
+    priceContext?: {
+        currencyCode: string;
+        regionId?: string;
+    };
+}
+/**
+ * Filter configuration returned by CommerceProvider.getAvailableFilters().
+ * Represents one filterable dimension (e.g. Color, RAM, Price range).
+ *
+ * Types:
+ * - `checkbox` / `multi`  → multiple selectable options
+ * - `select` / `single`   → single selectable option
+ * - `range`               → numeric min/max range
+ * - `boolean`             → on/off toggle (e.g. "In Stock")
+ */
+interface FilterConfig {
+    /** Unique filter identifier */
+    id: string;
+    /** Display label for the filter group */
+    label: string;
+    /** Filter UI type */
+    type: 'checkbox' | 'multi' | 'select' | 'single' | 'range' | 'boolean';
+    /** Selectable options (for checkbox/multi/select/single types) */
+    options?: FilterOption[];
+    /** Min value (for range type) */
+    min?: number;
+    /** Max value (for range type) */
+    max?: number;
+    /** Whether this filter is currently applied */
+    isActive?: boolean;
+    /** Sort priority — lower number = displayed first */
+    ranking?: number;
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Cart types - unified interface for all commerce providers
+ */
+
+/**
+ * Product reference in cart
+ */
+interface CartProduct {
+    id: string;
+    handle: string;
+    title: string;
+    featuredImage: Image;
+}
+/**
+ * Cart line item
+ */
+interface CartItem {
+    id: string | undefined;
+    quantity: number;
+    stockStatus?: StockStatus;
+    cost: {
+        totalAmount: Money;
+    };
+    merchandise: {
+        id: string;
+        title: string;
+        selectedOptions: SelectedOption[];
+        product: CartProduct;
+    };
+}
+/**
+ * Cart cost breakdown
+ */
+interface CartCost {
+    subtotalAmount: Money;
+    totalAmount: Money;
+    totalTaxAmount?: Money;
+}
+/**
+ * Shipping method option
+ * Used during checkout to display available shipping methods
+ */
+interface ShippingMethod {
+    /** Unique identifier for the shipping method */
+    id: string;
+    /** Display name (e.g., 'Standard Shipping', 'Express') */
+    name: string;
+    /** Price for this shipping method */
+    price: Money;
+    /** Optional description */
+    description?: string;
+    /** Estimated delivery time (e.g., '3-5 business days') */
+    estimatedDays?: string;
+}
+/**
+ * Main cart type - normalized across all providers
+ */
+interface Cart {
+    id: string | undefined;
+    checkoutUrl: string;
+    cost: CartCost;
+    lines: CartItem[];
+    totalQuantity: number;
+    fulfillmentOptions?: FulfillmentOption[];
+    stockValidation?: StockValidation;
+    /** ISO timestamp when cart was completed/converted to order (undefined if active) */
+    completedAt?: string;
+}
+/**
+ * Input for adding items to cart
+ */
+interface CartLineInput {
+    merchandiseId: string;
+    quantity: number;
+}
+/**
+ * Input for updating cart items
+ */
+interface CartLineUpdate {
+    id: string;
+    merchandiseId: string;
+    quantity: number;
+}
+/**
+ * Discount code applied to the cart
+ *
+ * Universal format for discount/promo codes across all providers.
+ * Adapters transform platform-specific discount formats to this interface.
+ */
+interface DiscountCode {
+    /** Discount code string (e.g., "SUMMER2024") */
+    code: string;
+    /** Discount value (amount or percentage) */
+    value: number;
+    /** Whether the value is a percentage (true) or fixed amount (false) */
+    isPercentage: boolean;
+    /** Human-readable description of the discount */
+    description?: string;
+    /** Minimum purchase amount required */
+    minimumAmount?: Money;
+    /** Expiration date */
+    expiresAt?: Date;
+    /** Maximum number of uses allowed */
+    maxUses?: number;
+    /** Current number of times this code has been used */
+    usageCount?: number;
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Collection types - unified interface for all commerce providers
+ */
+
+/**
+ * Product collection/category
+ */
+interface Collection {
+    id: string;
+    handle: string;
+    title: string;
+    description: string;
+    seo?: SEO;
+    path: string;
+    updatedAt: string;
+}
+/**
+ * Options for fetching collections
+ */
+interface GetCollectionsOptions {
+    /** Maximum number of collections to return */
+    limit?: number;
+    /** Search query to filter collections by title */
+    query?: string;
+}
+/**
+ * Options for fetching collection products
+ */
+interface CollectionProductsOptions {
+    sortKey?: string;
+    reverse?: boolean;
+    first?: number;
+    after?: string;
+}
+
+/**
+ * @thorprovider/types v2.0
+ * Product Category types - unified interface for all commerce providers
+ */
+/**
+ * Product category (hierarchical taxonomy)
+ */
+interface ProductCategory {
+    /** Unique identifier */
+    id: string;
+    /** Category name */
+    name: string;
+    /** URL-safe handle/slug */
+    handle: string;
+    /** Category description */
+    description?: string;
+    /** Parent category ID (null for root categories) */
+    parentCategoryId?: string;
+    /** Number of products in category */
+    productCount?: number;
+    /** Category image URL */
+    image?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Custom fetcher callback for advanced category queries.
+ *
+ * When provided, this callback replaces the default SDK logic entirely.
+ * Useful for: custom API endpoints, backend-specific filters, Module Link queries.
+ *
+ * @example
+ * ```typescript
+ * // Custom endpoint that filters categories by channel server-side
+ * const customFetcher = async (options: GetCategoriesOptions) => {
+ *   const response = await fetch(`/api/admin/sales-channels/${options.salesChannelId}/categories`);
+ *   return response.json();
+ * };
+ *
+ * const categories = await provider.getCategories({
+ *   salesChannelId: 'sc_123',
+ *   customFetcher,
+ * });
+ * ```
+ */
+type GetCategoriesCallback = (options: GetCategoriesOptions) => Promise<ProductCategory[]>;
+/**
+ * Options for fetching categories
+ */
+interface GetCategoriesOptions {
+    /** Include child categories */
+    includeDescendants?: boolean;
+    /** Parent category ID to filter by */
+    parentCategoryId?: string;
+    /** Maximum number of categories to return */
+    limit?: number;
+    /** Search query to filter categories by name/handle */
+    query?: string;
+    /**
+     * Scope results to a specific sales channel / storefront channel.
+     * When provided, only categories that contain at least one product available
+     * in the given channel will be returned.
+     *
+     * Maps to: Medusa `sales_channel_id`, Shopify Sales Channel, etc.
+     * Adapters that support native server-side filtering should prefer it;
+     * others may fall back to a client-side post-filter pass.
+     */
+    salesChannelId?: string;
+    /**
+     * Custom fetcher callback (optional).
+     *
+     * When provided, this callback is invoked instead of the default SDK logic.
+     * Allows backends to implement custom filters, Module Link queries, or
+     * call alternative endpoints (e.g., `/api/admin/sales-channels/{id}/categories`).
+     *
+     * This option enables:
+     * - **Medusa Module Link**: Query categories via custom module API
+     * - **Custom endpoints**: Call `/api/admin/sales-channels/{id}/categories` for server-side filtering
+     * - **Backend-specific optimizations**: Shopify/WooCommerce adapters can implement their own logic
+     *
+     * @default undefined (uses default SDK + in-memory filter)
+     * @see {@link GetCategoriesCallback} for callback signature
+     */
+    customFetcher?: GetCategoriesCallback;
+}
+
+/**
+ * @thorprovider/types v3.0
+ * Customer types - unified interface for all commerce providers
+ * Universal interfaces compatible with: Shopify, Medusa.js, WooCommerce, Magento, BigCommerce
+ */
+/**
+ * Customer address
+ *
+ * Universal format using camelCase (JavaScript convention).
+ *
+ * Platform mapping:
+ * - Shopify: MailingAddress (firstName, address1, zip, province, countryCodeV2)
+ * - Medusa: Address (first_name, address_1, postal_code, province, country_code)
+ * - WooCommerce: Address (first_name, address_1, postcode, state, country)
+ * - Magento: Address (firstname, street, postcode, region, country_id)
+ *
+ * Adapters transform platform-specific snake_case to universal camelCase.
+ */
+interface Address {
+    id?: string;
+    firstName: string;
+    lastName: string;
+    company?: string;
+    address1: string;
+    address2?: string;
+    city: string;
+    province?: string;
+    postalCode: string;
+    countryCode: string;
+    phone?: string;
+    isDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Customer
+ *
+ * Universal customer format using camelCase.
+ * Adapters transform platform-specific naming to this format.
+ */
+interface Customer {
+    id: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    phone?: string | null;
+    hasAccount?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    /**
+     * Flexible metadata storage.
+     *
+     * Multi-tenant convention: when `metadata.sales_channel_id` is present the
+     * customer is scoped to that channel.  See `@thorprovider/adapters/metadata` helpers.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Custom fetcher callback for advanced customer queries.
+ *
+ * When provided, this callback replaces the default SDK logic entirely.
+ * Useful for: custom API endpoints, backend-specific filters, Module Link queries.
+ *
+ * @example
+ * ```typescript
+ * // Custom endpoint that filters by channel server-side
+ * const customFetcher = async (options: GetCustomersOptions) => {
+ *   const response = await fetch(`/api/admin/sales-channels/${options.salesChannelId}/customers`);
+ *   return response.json();
+ * };
+ *
+ * const customers = await provider.getCustomers({
+ *   salesChannelId: 'sc_123',
+ *   customFetcher,
+ * });
+ * ```
+ */
+type GetCustomersCallback = (options: GetCustomersOptions) => Promise<Customer[]>;
+/**
+ * Options for querying a list of customers.
+ *
+ * Used by CommerceProvider.getCustomers() and admin list endpoints.
+ */
+interface GetCustomersOptions {
+    /** Full-text search by name or email */
+    search?: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Zero-based offset for pagination */
+    offset?: number;
+    /** Field to sort results by */
+    sortBy?: 'createdAt' | 'email' | 'firstName';
+    /**
+     * Filter customers to a specific sales channel.
+     *
+     * When set, only customers whose `metadata.sales_channel_id` matches
+     * this value are returned.  Enables multi-tenant isolation for
+     * dropshippers who should only see their own customers.
+     *
+     * If omitted, all customers are returned (admin/super-admin view).
+     */
+    salesChannelId?: string;
+    /**
+     * Custom fetcher callback (optional).
+     *
+     * When provided, this callback is invoked instead of the default SDK logic.
+     * Allows backends to implement custom filters, Module Link queries, or
+     * call alternative endpoints (e.g., `/api/admin/sales-channels/{id}/customers`).
+     *
+     * This option enables:
+     * - **Medusa Module Link**: Query customers via custom module API
+     * - **Custom endpoints**: Call `/api/admin/sales-channels/{id}/customers` for server-side filtering
+     * - **Backend-specific optimizations**: Shopify/WooCommerce adapters can implement their own logic
+     *
+     * @default undefined (uses default SDK + in-memory filter)
+     * @see {@link GetCustomersCallback} for callback signature
+     */
+    customFetcher?: GetCustomersCallback;
+}
+
+/**
+ * @thorprovider/types v3.0
+ * Region types - geographic region configuration
+ * Universal interfaces compatible with: Shopify Markets, Medusa Regions, WooCommerce Zones
+ */
+/**
+ * Geographic region configuration
+ *
+ * Represents a regional market with specific currency, tax, and payment settings.
+ *
+ * Platform mapping:
+ * - Shopify: Market (primaryDomain, regions, currencySettings)
+ * - Medusa: Region (currency_code, countries, payment_providers, tax_rate)
+ * - WooCommerce: Shipping Zone + Tax Settings (combined concept)
+ *
+ * Adapters transform platform-specific region data to this universal format.
+ */
+interface Region {
+    /** Unique region identifier */
+    id: string;
+    /** Region name (e.g., "United States", "Europe", "North America") */
+    name: string;
+    /** ISO 3166-1 alpha-2 country codes included in this region (e.g., ["US", "CA"]) */
+    countryCodes: string[];
+    /** Default currency for this region (ISO 4217 code, e.g., "USD", "EUR") */
+    currency: string;
+    /** Available payment provider IDs in this region */
+    paymentProviders?: string[];
+    /** Tax rate for this region (as decimal, e.g., 0.08 for 8%) */
+    taxRate?: number;
+    /** Whether this region is enabled and available for customers */
+    isEnabled?: boolean;
+    /** Additional region metadata for platform-specific features */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * @thorprovider/types v3.0
+ * Order types - unified interface for all commerce providers
+ * Universal interfaces compatible with: Shopify, Medusa.js, WooCommerce, Magento, BigCommerce
+ */
+
+/**
+ * Order status (overall)
+ *
+ * Platform mapping:
+ * - Shopify: Derived from financialStatus + fulfillmentStatus
+ * - Medusa: status field
+ * - WooCommerce: status (pending/processing/completed/cancelled/refunded)
+ * - Magento: status
+ */
+type OrderStatus = 'pending' | 'processing' | 'completed' | 'cancelled' | 'refunded';
+/**
+ * Payment status (separate from order status)
+ *
+ * Platform mapping:
+ * - Shopify: financialStatus (PENDING, AUTHORIZED, PAID, REFUNDED, etc.)
+ * - Medusa: payment_status
+ * - WooCommerce: Derived from order status
+ * - Magento: payment status
+ */
+type PaymentStatus = 'pending' | 'authorized' | 'paid' | 'partially_refunded' | 'refunded';
+/**
+ * Fulfillment status
+ *
+ * Platform mapping:
+ * - Shopify: fulfillmentStatus (FULFILLED, UNFULFILLED, etc.)
+ * - Medusa: fulfillment_status
+ * - WooCommerce: Derived from order status
+ * - Magento: shipping_status
+ */
+type FulfillmentStatus = 'unfulfilled' | 'partially_fulfilled' | 'fulfilled' | 'returned';
+/**
+ * Order line item
+ *
+ * Universal format for order items across platforms.
+ */
+interface OrderItem {
+    id: string;
+    title: string;
+    variantTitle?: string;
+    quantity: number;
+    price: Money;
+    total: Money;
+    sku?: string;
+    image?: Image;
+    productId?: string;
+    variantId?: string;
+}
+/**
+ * Order
+ *
+ * Universal format compatible with:
+ * - Shopify: Order (Storefront API)
+ * - Medusa: StoreOrder (v2)
+ * - WooCommerce: Order (REST API)
+ * - Magento: Order (GraphQL)
+ */
+interface Order {
+    id: string;
+    orderNumber: string;
+    email: string;
+    status: OrderStatus;
+    paymentStatus: PaymentStatus;
+    fulfillmentStatus: FulfillmentStatus;
+    customerId?: string;
+    customer?: Customer;
+    items: OrderItem[];
+    subtotal: Money;
+    total: Money;
+    tax?: Money;
+    shipping?: Money;
+    discount?: Money;
+    shippingAddress?: Address;
+    billingAddress?: Address;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    cancelledAt?: string;
+    isDraft?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Custom fetcher callback for advanced order queries.
+ *
+ * When provided, this callback replaces the default SDK logic entirely.
+ * Useful for: custom API endpoints, backend-specific filters, Module Link queries.
+ *
+ * @example
+ * ```typescript
+ * // Custom endpoint that filters orders by channel server-side
+ * const customFetcher = async (options: GetOrdersOptions) => {
+ *   const response = await fetch(
+ *     `/api/admin/sales-channels/${options.salesChannelId}/orders`
+ *   );
+ *   return response.json();
+ * };
+ *
+ * const orders = await provider.getOrders({
+ *   salesChannelId: 'sc_123',
+ *   customFetcher,
+ * });
+ * ```
+ */
+type GetOrdersCallback = (options: GetOrdersOptions) => Promise<Order[]>;
+/**
+ * Options for querying a list of orders.
+ *
+ * Used by CommerceProvider.getOrders() and admin list endpoints.
+ */
+interface GetOrdersOptions {
+    /** Customer ID to filter orders by */
+    customerId?: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Zero-based offset for pagination */
+    offset?: number;
+    /**
+     * Filter orders to a specific sales channel.
+     *
+     * When set, only orders whose `metadata.sales_channel_id` matches
+     * this value are returned.  Enables multi-tenant isolation.
+     *
+     * If omitted, orders are returned unfiltered (admin view).
+     */
+    salesChannelId?: string;
+    /**
+     * Custom fetcher callback (optional).
+     *
+     * When provided, this callback is invoked instead of the default SDK logic.
+     * Allows backends to implement custom filters, Module Link queries, or
+     * call alternative endpoints (e.g., `/api/admin/sales-channels/{id}/orders`).
+     *
+     * This option enables:
+     * - **Medusa Module Link**: Query orders via custom module API
+     * - **Custom endpoints**: Call `/api/admin/sales-channels/{id}/orders` for server-side filtering
+     * - **Backend-specific optimizations**: Shopify/WooCommerce adapters can implement their own logic
+     *
+     * @default undefined (uses default SDK + in-memory filter)
+     * @see {@link GetOrdersCallback} for callback signature
+     */
+    customFetcher?: GetOrdersCallback;
+}
+
+/**
+ * Union type of all supported provider string values.
+ * Use this for type annotations when a provider type is expected.
+ *
+ * @example
+ * ```typescript
+ * function getProviderName(type: ProviderTypeString): string {
+ *   // type is 'medusa'
+ * }
+ * ```
+ */
+type ProviderTypeString = 'medusa' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
+/**
+ * Metadata about each provider.
+ * Useful for UI, error messages, validation, and documentation.
+ *
+ * @internal
+ */
+declare const PROVIDER_METADATA: Record<ProviderTypeString, {
+    name: string;
+    description: string;
+    requiresStorefront: boolean;
+    requiredEnvVars: string[];
+    maxRetries: number;
+}>;
+/**
+ * Check if a string is a valid provider type.
+ *
+ * @example
+ * ```typescript
+ * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {
+ *   // type is narrowed to ProviderTypeString
+ * }
+ * ```
+ */
+declare function isSupportedProviderType(value: unknown): value is ProviderTypeString;
+/**
+ * Get metadata for a provider type.
+ * Useful for validation, error messages, and logging.
+ *
+ * @example
+ * ```typescript
+ * const meta = getProviderMetadata('medusa');
+ * console.log(`Using ${meta.name} with max ${meta.maxRetries} retries`);
+ * ```
+ */
+declare function getProviderMetadata(type: ProviderTypeString): (typeof PROVIDER_METADATA)[ProviderTypeString];
+
+/**
+ * @thorprovider/types — Storefront Context
+ *
+ * Platform-agnostic representation of a "sales channel" or equivalent.
+ * Abstracts differences between Medusa sales_channel, Shopify publications,
+ * BigCommerce channels, WooCommerce sites, Spree stores, and Magento store views.
+ *
+ * @remarks
+ * - Required for all multi-tenant deployments
+ * - Returned by `CommerceProvider.getStorefrontContext()`
+ * - MUST be validated on startup; errors should NOT be silently ignored
+ */
+/**
+ * Supported commerce platform types for storefront identification.
+ *
+ * @remarks
+ * This type is automatically synced with SupportedProviderType from provider.ts.
+ * When adding a new provider, update packages/types/src/provider.ts,
+ * and this type will automatically reflect the new provider.
+ *
+ * Currently supported:
+ * - ✅ 'medusa': Fully implemented
+ *
+ * Planned (not yet implemented):
+ * - 🟡 'shopify': Phase 2
+ * - 🟡 'bigcommerce': Phase 2
+ * - 🟡 'woocommerce': Phase 3
+ * - 🟡 'spree': Phase 3
+ * - 🟡 'magento': Phase 3
+ */
+type StorefrontPlatformType = 'medusa' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
+/**
+ * StorefrontContext
+ *
+ * Platform-agnostic representation of a "sales channel" or equivalent.
+ *
+ * @example
+ * ```typescript
+ * const ctx: StorefrontContext = {
+ *   id: 'sc_01J...',
+ *   name: 'B2C Storefront',
+ *   platformType: 'medusa',
+ *   requiresProductScoping: true,
+ *   currencyCode: 'USD',
+ * };
+ * ```
+ */
+interface StorefrontContext {
+    /**
+     * Unique identifier for this storefront across the system.
+     * Examples: "sc_123" (Medusa), "gid://shopify/Channel/789" (Shopify), "1" (WooCommerce)
+     */
+    id: string;
+    /**
+     * Human-readable name for logging and debugging.
+     */
+    name: string;
+    /**
+     * Platform this storefront belongs to.
+     */
+    platformType: StorefrontPlatformType;
+    /**
+     * Whether products must be explicitly linked/published to this storefront.
+     *
+     * @remarks
+     * - Medusa: true (products must be linked to sales channel)
+     * - Shopify: false (products visible by default unless unlisted)
+     * - WooCommerce: false (no scoping concept)
+     * - BigCommerce: false (products visible by default unless delisted)
+     * - Spree: true (products must be assigned per store)
+     * - Magento: true (products must be assigned per website)
+     */
+    requiresProductScoping: boolean;
+    /**
+     * Primary currency code for this storefront.
+     * Examples: "USD", "EUR", "GBP"
+     */
+    currencyCode: string;
+    /**
+     * Optional region or locale code.
+     * Examples: "US", "EU", "en-US", "es-ES"
+     */
+    locale?: string;
+    /**
+     * Optional: Store/Channel metadata from platform.
+     * @internal
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Storefront validation error.
+ * Thrown when storefront configuration is invalid or missing.
+ *
+ * @example
+ * ```typescript
+ * throw new StorefrontConfigError(
+ *   'Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID',
+ *   'medusa',
+ *   'NEXT_PUBLIC_SALES_CHANNEL_ID',
+ * );
+ * ```
+ */
+declare class StorefrontConfigError extends Error {
+    readonly platformType: string;
+    readonly requiredEnvVar?: string;
+    constructor(message: string, platformType: string, requiredEnvVar?: string);
+}
+
+/**
+ * @thorprovider/types — Storefront Configuration
+ *
+ * Type definitions for per-channel storefront configuration
+ * returned by the Thor Commerce backend plugin.
+ *
+ * Consumed by `CommerceProvider.getStorefrontConfig()` in L2 adapters.
+ * Replaces legacy environment variables: NEXT_PUBLIC_ACCENT_COLOR,
+ * NEXT_PUBLIC_LOGO_URL, NEXT_PUBLIC_CURRENCY_CODE.
+ *
+ * @module storefront-config
+ */
+/**
+ * SEO default values for a storefront channel.
+ */
+interface StorefrontSeoDefaults {
+    /** Default page title */
+    title: string;
+    /** Default meta description */
+    description: string;
+    /** Default Open Graph image URL */
+    ogImage?: string;
+}
+/**
+ * Per-channel storefront configuration.
+ *
+ * Returned by `GET /store/thor/config` (resolved via publishable API key).
+ *
+ * @example
+ * ```typescript
+ * const config = await commerce.getStorefrontConfig();
+ * if (config) {
+ *   console.log(config.logoUrl, config.themeAccentColor);
+ * }
+ * ```
+ */
+interface StorefrontConfig {
+    /** Unique identifier for this storefront config entry */
+    id: string;
+    /** Sales channel this config belongs to */
+    salesChannelId: string;
+    /** Theme accent color name (e.g., "indigo", "blue", "red") */
+    themeAccentColor: string;
+    /** Logo image URL */
+    logoUrl: string;
+    /** Default currency code (e.g., "EUR", "USD") */
+    currencyCode: string;
+    /** SEO default values */
+    seoDefaults: StorefrontSeoDefaults;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+    /** ISO 8601 last update timestamp */
+    updatedAt: string;
+}
+
+/**
+ * @thorprovider/types — Site Designer Configuration
+ *
+ * Type definitions for the Site Designer feature.
+ * Describes the visual theme, navigation, and identity configuration
+ * managed through the admin Site Designer and served to storefronts
+ * via `GET /store/thor/site-config`.
+ *
+ * These types are the source of truth (L1) so that both L2 adapters
+ * and L3 components can depend on them without circular imports.
+ *
+ * @module designer-config
+ */
+/**
+ * Available theme presets for the Site Designer.
+ */
+type DesignerThemePreset = 'electro' | 'midnight' | 'sunset' | 'forest' | 'custom';
+/**
+ * Theme configuration managed by the Site Designer.
+ */
+interface DesignerThemeConfig {
+    /** Active theme preset */
+    preset: DesignerThemePreset;
+    /** Accent color name (e.g., "indigo", "blue", "crimson") */
+    accentColor: string;
+    /** Gray scale family */
+    grayColor: 'auto' | 'gray' | 'mauve' | 'slate' | 'sage' | 'olive' | 'sand';
+    /** Border radius scale */
+    radius: 'none' | 'small' | 'medium' | 'large' | 'full';
+    /** Color scheme */
+    appearance: 'light' | 'dark';
+    /** UI scaling factor */
+    scaling: '90%' | '95%' | '100%' | '105%' | '110%';
+}
+/**
+ * A single navigation item in the Site Designer menu.
+ */
+interface DesignerNavItem {
+    /** Unique identifier for this nav entry */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Target URL or path */
+    href: string;
+    /** Whether this item is visible to storefront visitors */
+    visible: boolean;
+}
+/**
+ * A version history entry for the Site Designer config.
+ */
+interface DesignerHistoryEntry {
+    /** Version identifier (typically ISO 8601 timestamp) */
+    version: string;
+    /** ISO 8601 timestamp of when this version was created */
+    createdAt: string;
+}
+/**
+ * Complete Site Designer configuration.
+ *
+ * Persisted per sales channel in the backend and served to the
+ * storefront via `GET /store/thor/site-config`.
+ *
+ * @example
+ * ```typescript
+ * const result = await commerce.getDesignerConfig();
+ * if (result) {
+ *   const { config } = result;
+ *   console.log(config.theme.preset, config.siteName);
+ * }
+ * ```
+ */
+interface DesignerConfig {
+    /** Theme visual settings */
+    theme: DesignerThemeConfig;
+    /** Navigation menu items */
+    navigation: DesignerNavItem[];
+    /** Storefront display name */
+    siteName: string;
+    /** Storefront description */
+    siteDescription: string;
+    /** Logo URL (optional, overrides StorefrontConfig.logoUrl) */
+    logo?: string;
+}
+
+/**
+ * @fileoverview Authentication types for Thor Commerce adapters
+ * @module @thorprovider/adapters/types/auth
+ *
+ * Framework-agnostic authentication types that work across all commerce providers.
+ * Follows Thor Commerce principles: decoupling, agnostic configuration.
+ */
+
+/**
+ * Authentication method configuration
+ */
+type AuthMethod = 'jwt' | 'session';
+/**
+ * Authentication storage strategy
+ */
+type AuthStorage = 'cookie' | 'localStorage' | 'sessionStorage' | 'memory';
+/**
+ * Authentication configuration
+ */
+interface AuthConfig {
+    /**
+     * Authentication method to use
+     * - 'jwt': JWT token in Authorization header (good for mobile, SPAs)
+     * - 'session': Cookie-based session (good for server-side rendering)
+     */
+    method: AuthMethod;
+    /**
+     * Where to store authentication tokens/session
+     * - 'cookie': Browser cookies (automatic with fetch)
+     * - 'localStorage': Browser localStorage (manual management)
+     * - 'sessionStorage': Browser sessionStorage (clears on tab close)
+     * - 'memory': In-memory only (for server-side or testing)
+     */
+    storage: AuthStorage;
+    /**
+     * Custom storage implementation (optional)
+     * Useful for React Native or non-browser environments
+     */
+    customStorage?: {
+        getItem: (key: string) => Promise<string | null> | string | null;
+        setItem: (key: string, value: string) => Promise<void> | void;
+        removeItem: (key: string) => Promise<void> | void;
+    };
+}
+/**
+ * Login credentials for email/password authentication
+ */
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+/**
+ * Registration data for new customer
+ */
+interface RegisterData {
+    email: string;
+    password: string;
+    first_name: string;
+    last_name: string;
+    phone?: string;
+}
+/**
+ * Authentication response from login/register
+ */
+interface AuthResponse {
+    /**
+     * JWT token (if using JWT authentication)
+     */
+    token?: string;
+    /**
+     * Customer object (if registration was successful)
+     */
+    customer?: Customer;
+    /**
+     * Whether authentication requires additional steps (e.g., OAuth)
+     */
+    requiresAction?: boolean;
+    /**
+     * Redirect URL for OAuth flows
+     */
+    redirectUrl?: string;
+}
+/**
+ * Authentication response (used internally by providers)
+ */
+interface AuthResponse {
+    customer?: Customer;
+    token?: string;
+}
+
+/**
+ * Update customer data
+ */
+interface UpdateCustomerData {
+    first_name?: string;
+    last_name?: string;
+    phone?: string | null;
+    email?: string;
+    password?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create address data (camelCase for universal compatibility)
+ */
+interface CreateAddressData {
+    firstName: string;
+    lastName: string;
+    company?: string;
+    address1: string;
+    address2?: string;
+    city: string;
+    province?: string;
+    postalCode: string;
+    countryCode: string;
+    phone?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Password reset request
+ */
+interface PasswordResetRequest {
+    email: string;
+}
+/**
+ * Password reset confirmation
+ */
+interface PasswordResetConfirm {
+    token: string;
+    password: string;
+}
+/**
+ * Authentication provider interface
+ *
+ * All commerce providers must implement this interface to support authentication.
+ * This enables framework-agnostic auth across Medusa, Shopify, WooCommerce, etc.
+ */
+interface AuthProvider {
+    /**
+     * Login customer with email and password
+     * @param credentials - Email and password
+     * @returns Authentication response with token/customer
+     */
+    login(credentials: LoginCredentials): Promise<AuthResponse>;
+    /**
+     * Register new customer
+     * @param data - Registration data
+     * @returns Authentication response
+     */
+    register(data: RegisterData): Promise<AuthResponse>;
+    /**
+     * Logout current customer
+     * Clears authentication token/session
+     */
+    logout(): Promise<void>;
+    /**
+     * Request password reset email
+     * @param email - Customer email
+     */
+    requestPasswordReset(email: string): Promise<void>;
+    /**
+     * Reset password with token
+     * @param token - Password reset token from email (provider-specific format)
+     * @param password - New password
+     * @param metadata - Optional metadata for provider-specific requirements
+     */
+    resetPassword(token: string, password: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Get current authenticated customer
+     * @returns Customer object or null if not authenticated
+     */
+    getCurrentCustomer(): Promise<Customer | null>;
+    /**
+     * Update current customer profile
+     * @param data - Fields to update
+     * @returns Updated customer
+     */
+    updateCustomer(data: UpdateCustomerData): Promise<Customer>;
+    /**
+     * Check if customer is authenticated
+     * @returns true if authenticated, false otherwise
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Get current authentication token (if using JWT)
+     * @returns JWT token or null
+     */
+    getAuthToken(): string | null;
+    /**
+     * Delete current customer account
+     *
+     * WARNING: This is a permanent action and cannot be undone.
+     * Only implemented if capabilities.deleteAccount is true.
+     */
+    deleteCustomerAccount(): Promise<void>;
+    /**
+     * Get customer addresses
+     * @returns List of customer addresses
+     */
+    getAddresses(): Promise<Address[]>;
+    /**
+     * Create new address for current customer
+     * @param data - Address data
+     * @returns Created address
+     */
+    createAddress(data: CreateAddressData): Promise<Address>;
+    /**
+     * Update customer address
+     * @param addressId - Address ID
+     * @param data - Fields to update
+     * @returns Updated address
+     */
+    updateAddress(addressId: string, data: Partial<CreateAddressData>): Promise<Address>;
+    /**
+     * Delete customer address
+     * @param addressId - Address ID
+     */
+    deleteAddress(addressId: string): Promise<void>;
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Payment Types - Unified payment method interface
+ *
+ * Provides backend-agnostic types for payment methods and providers.
+ * Each backend transforms its payment providers to this common format.
+ *
+ * @see packages/adapters/PAYMENT_METHODS_ARCHITECTURE.md
+ */
+/**
+ * Payment method type identifier
+ * Normalized across all backends
+ *
+ * @example
+ * ```typescript
+ * // Medusa transforms:
+ * 'pp_stripe_stripe' → type: 'card'
+ * 'pp_paypal_paypal' → type: 'wallet'
+ * 'pp_system_default' → type: 'cash_on_delivery'
+ * ```
+ */
+type PaymentMethodType = 'card' | 'wallet' | 'bank_transfer' | 'buy_now_pay_later' | 'cash_on_delivery' | 'crypto' | 'other';
+/**
+ * Payment method features and capabilities
+ * Describes what a payment method supports
+ */
+interface PaymentMethodFeatures {
+    /**
+     * Supports saving payment method for future use
+     *
+     * Example: Stripe allows saving cards, PayPal allows vaulting
+     */
+    saveForLater?: boolean;
+    /**
+     * Requires 3D Secure authentication
+     *
+     * Important for SCA compliance in EU
+     */
+    requires3DS?: boolean;
+    /**
+     * Supports refunds
+     *
+     * Some methods like COD may not support automatic refunds
+     */
+    supportsRefunds?: boolean;
+    /**
+     * Minimum transaction amount (in smallest currency unit, e.g., cents)
+     *
+     * Example: Stripe has minimum amounts per currency
+     */
+    minAmount?: number;
+    /**
+     * Maximum transaction amount (in smallest currency unit, e.g., cents)
+     *
+     * Example: Some BNPL providers have maximum limits
+     */
+    maxAmount?: number;
+    /**
+     * Supported currencies (ISO 4217 codes)
+     *
+     * If undefined, assumes all currencies supported
+     */
+    supportedCurrencies?: string[];
+    /**
+     * Requires additional customer verification
+     *
+     * Example: Bank transfers may require identity verification
+     */
+    requiresVerification?: boolean;
+}
+/**
+ * Payment method information
+ * Backend-agnostic representation of a payment provider
+ *
+ * This is the normalized format that all backends transform their
+ * payment providers into, allowing the storefront to work with
+ * any backend without knowing provider-specific details.
+ *
+ * @example
+ * ```typescript
+ * // Medusa Stripe provider:
+ * {
+ *   id: 'pp_stripe_stripe',
+ *   name: 'Stripe',
+ *   type: 'card',
+ *   isEnabled: true,
+ *   requiresSetup: true,
+ *   features: {
+ *     saveForLater: true,
+ *     requires3DS: true,
+ *     supportsRefunds: true
+ *   }
+ * }
+ * ```
+ */
+interface PaymentMethod {
+    /**
+     * Unique identifier from backend
+     *
+     * Format varies by backend:
+     * - Medusa: "pp_stripe_stripe", "pp_paypal_paypal", "pp_system_default"
+     * - Shopify: "shopify_payments", "paypal_express"
+     * - WooCommerce: "stripe", "paypal", "cod"
+     */
+    id: string;
+    /**
+     * Display name for UI
+     *
+     * Human-readable name shown to customers
+     * Example: "Credit Card", "PayPal", "Cash on Delivery"
+     */
+    name: string;
+    /**
+     * Payment method type (normalized)
+     *
+     * Used for categorization and UI rendering
+     */
+    type: PaymentMethodType;
+    /**
+     * Whether this provider is currently enabled
+     *
+     * Backend administrators control this setting
+     */
+    isEnabled: boolean;
+    /**
+     * Whether this provider requires additional setup
+     *
+     * Examples:
+     * - Card payments: requires entering card details
+     * - Wallets: requires authorizing wallet connection
+     * - COD: no setup required (false)
+     */
+    requiresSetup: boolean;
+    /**
+     * Optional description for display
+     *
+     * Additional information shown to customer
+     */
+    description?: string;
+    /**
+     * Metadata from backend (provider-specific)
+     *
+     * Contains original backend data for advanced use cases
+     * Structure varies by backend
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Supported features and capabilities
+     */
+    features?: PaymentMethodFeatures;
+    /**
+     * Logo URL or icon identifier
+     *
+     * Optional visual representation
+     */
+    logo?: string;
+}
+/**
+ * Payment methods query options
+ *
+ * Used to filter/query available payment methods
+ * Different backends support different filters
+ */
+interface PaymentMethodsOptions {
+    /**
+     * Region ID (for backends that support regional payments)
+     *
+     * Example: Medusa requires region_id
+     * Required for: Medusa
+     * Optional for: Shopify (global), WooCommerce (may use)
+     */
+    regionId?: string;
+    /**
+     * Cart ID (for cart-specific payment methods)
+     *
+     * Some backends determine available methods based on cart contents
+     * Example: Certain methods only for high-value carts
+     */
+    cartId?: string;
+    /**
+     * Currency code filter (ISO 4217)
+     *
+     * Filter methods that support this currency
+     * Example: 'USD', 'EUR', 'GBP'
+     */
+    currencyCode?: string;
+    /**
+     * Filter by enabled status
+     *
+     * If true, only return enabled payment methods
+     * Default: true (recommended for checkout)
+     */
+    enabledOnly?: boolean;
+    /**
+     * Force refresh from backend (ignore cache)
+     *
+     * Set to true to bypass client-side cache
+     * Default: false
+     */
+    forceRefresh?: boolean;
+}
+/**
+ * Cached payment methods data
+ *
+ * Used for client-side caching with TTL
+ */
+interface CachedPaymentMethods {
+    /**
+     * Cache key (stringified options)
+     */
+    key: string;
+    /**
+     * Cached payment methods
+     */
+    methods: PaymentMethod[];
+    /**
+     * Timestamp when cached (milliseconds since epoch)
+     */
+    cachedAt: number;
+    /**
+     * Time-to-live in milliseconds
+     *
+     * Default: 5 minutes (300000ms)
+     */
+    ttl: number;
+}
+
+/**
+ * Backend capabilities interface
+ *
+ * Defines what operations a backend commerce platform supports.
+ * Each capability is a boolean flag indicating support.
+ *
+ * This enables adaptive UI that adjusts based on backend capabilities.
+ *
+ * @example
+ * ```typescript
+ * const { capabilities } = useCommerce();
+ *
+ * // Adaptive UI based on backend capabilities
+ * if (capabilities.updateEmail) {
+ *   return <EmailField />;
+ * } else {
+ *   return <EmailField disabled />;
+ * }
+ * ```
+ */
+interface BackendCapabilities {
+    /**
+     * Profile Management Capabilities
+     */
+    /** Can update customer profile (name, phone) */
+    updateProfile: boolean;
+    /** Can update customer email address */
+    updateEmail: boolean;
+    /** Can change password directly (current + new password) */
+    changePasswordDirect: boolean;
+    /** Can request password reset via email */
+    changePasswordViaEmail: boolean;
+    /** Can delete customer account (self-service) */
+    deleteAccount: boolean;
+    /**
+     * Avatar/Profile Picture Capabilities
+     */
+    /** Has native avatar/profile picture upload API */
+    uploadAvatar: boolean;
+    /** Can store avatar URL in customer metadata/attributes */
+    avatarViaMetadata: boolean;
+    /**
+     * Custom Attributes/Metadata Capabilities
+     */
+    /** Supports custom customer attributes/metadata */
+    customAttributes: boolean;
+    /**
+     * Order Management Capabilities
+     */
+    /** Can fetch customer order history */
+    fetchOrders: boolean;
+    /** Can cancel orders (before fulfillment) */
+    cancelOrder: boolean;
+    /**
+     * Address Management Capabilities
+     */
+    /** Can add/update/delete shipping addresses */
+    manageAddresses: boolean;
+    /** Can set default shipping address */
+    defaultAddress: boolean;
+    /**
+     * Cart/Checkout Capabilities
+     */
+    /** Can apply discount codes to cart */
+    applyDiscounts: boolean;
+    /** Can calculate shipping rates before checkout */
+    shippingCalculation: boolean;
+    /**
+     * Payment/Checkout Capabilities
+     */
+    /** Supports guest checkout (no account required) */
+    guestCheckout: boolean;
+    /** Can save payment methods for future use */
+    savedPaymentMethods: boolean;
+    /** Can list available payment providers dynamically */
+    listPaymentProviders: boolean;
+    /** Payment providers are region-specific */
+    regionSpecificPayments: boolean;
+    /**
+     * Wishlist/Favorites Capabilities
+     */
+    /** Has native wishlist/favorites feature */
+    wishlist: boolean;
+    /**
+     * Search/Filter Capabilities
+     */
+    /** Supports advanced product search (full-text, filters) */
+    advancedSearch: boolean;
+    /** Supports faceted filtering (by attributes) */
+    facetedFilters: boolean;
+    /**
+     * Review/Rating Capabilities
+     */
+    /** Has native product reviews/ratings system */
+    productReviews: boolean;
+    /**
+     * Loyalty/Rewards Capabilities
+     */
+    /** Has native loyalty/rewards program */
+    loyaltyProgram: boolean;
+}
+/**
+ * Main provider interface that all commerce providers must implement
+ *
+ * This interface defines a unified API for interacting with different
+ * e-commerce platforms (Medusa, Shopify, WooCommerce, etc.)
+ *
+ * @thorprovider/adapters (L2) implements this interface
+ * @thorprovider/components (L3) depends on this abstraction
+ */
+interface CommerceProvider {
+    /**
+     * Provider metadata
+     */
+    readonly name: string;
+    readonly version: string;
+    /**
+     * Backend capabilities
+     *
+     * Defines what operations this backend supports.
+     * Used for adaptive UI that adjusts based on platform features.
+     *
+     * @example
+     * ```typescript
+     * const { capabilities } = useCommerce();
+     *
+     * if (capabilities.updateEmail) {
+     *   return <EmailField />;
+     * } else {
+     *   return <EmailField disabled />;
+     * }
+     * ```
+     */
+    readonly capabilities: BackendCapabilities;
+    /**
+     * Authentication provider
+     *
+     * Available if the backend supports authentication and is configured.
+     */
+    readonly auth?: AuthProvider;
+    /**
+     * Get a single product by handle/slug
+     * @param handle - Product handle (slug)
+     * @param options - Query options (e.g., regionId)
+     * @returns Product or undefined if not found
+     */
+    getProduct(handle: string, options?: {
+        regionId?: string;
+    }): Promise<Product | undefined>;
+    /**
+     * Get multiple products with optional filtering and sorting
+     * @param options - Query options (search, sort, pagination)
+     * @returns Array of products
+     */
+    getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    /**
+     * Get product recommendations for a given product
+     * @param productId - Product ID
+     * @returns Array of recommended products
+     */
+    getProductRecommendations(productId: string): Promise<Product[]>;
+    /**
+     * Advanced product search with filtering (OPTIONAL)
+     *
+     * Performs enhanced product search using backend-specific search engines
+     * (e.g., MeiliSearch, Algolia, Elasticsearch) with advanced filtering:
+     * - Price range filtering
+     * - Stock availability
+     * - Custom product attributes (category-specific)
+     * - Faceted search with metadata
+     *
+     * **Check `capabilities.advancedSearch` before calling.**
+     * Falls back to getProducts() if not supported.
+     *
+     * Only available if backend supports advanced search endpoint.
+     * Backends without this capability should NOT implement this method.
+     *
+     * @param options - Advanced search options with filters
+     * @returns Products matching criteria with search metadata
+     *
+     * @example
+     * ```typescript
+     * // Check capability first
+     * if (!commerce.capabilities.advancedSearch || !commerce.searchProductsAdvanced) {
+     *   // Fallback to basic search
+     *   const products = await commerce.getProducts({ query: 'laptop' });
+     *   return { products, meta: { limit: 20, offset: 0 } };
+     * }
+     *
+     * // Use advanced search
+     * const result = await commerce.searchProductsAdvanced({
+     *   query: 'gaming laptop',
+     *   categoryIds: ['cat_electronics'],
+     *   priceMin: 500,
+     *   priceMax: 1500,
+     *   currencyCode: 'EUR',
+     *   inStockOnly: true,
+     *   attributes: [
+     *     { id: 'att_ram', values: ['att_val_16gb', 'att_val_32gb'] },
+     *     { id: 'att_brand', values: ['att_val_dell'] }
+     *   ],
+     *   includeVariants: true,
+     *   regionId: 'reg_europe',
+     *   first: 20,
+     *   after: 0
+     * });
+     *
+     * console.log(`Found ${result.meta?.total} products`);
+     * console.log(`Search took ${result.meta?.processingTimeMs}ms`);
+     * console.log(`Hybrid search: ${result.meta?.hybridSearchUsed}`);
+     *
+     * result.products.forEach(product => {
+     *   console.log(product.title, product.priceRange);
+     *   if (product.variants) {
+     *     product.variants.forEach(v => console.log('  -', v.title, v.price));
+     *   }
+     * });
+     * ```
+     *
+     * @throws {ProviderAPIError} If backend search service fails
+     * @throws {Error} If required parameters missing (e.g., regionId for price filtering)
+     *
+     * @see AdvancedSearchProductsOptions for all available filter options
+     * @see SearchResultMeta for metadata structure
+     * @see BackendCapabilities.advancedSearch to check if supported
+     */
+    searchProductsAdvanced?(options?: AdvancedSearchProductsOptions): Promise<{
+        products: Product[];
+        meta?: SearchResultMeta;
+    }>;
+    /**
+     * Get available filter options for product filtering (OPTIONAL)
+     *
+     * Returns dynamic filter configuration based on:
+     * - Backend capabilities (basic vs advanced filters)
+     * - Category context (category-specific custom attributes)
+     * - Current product set (facet counts if supported)
+     *
+     * Enables building adaptive filter UI that shows only relevant filters
+     * for the current context. For example:
+     * - Electronics category: RAM, Storage, Brand filters
+     * - Clothing category: Size, Color, Material filters
+     * - No category: Only basic filters (price, availability)
+     *
+     * **Check `capabilities.facetedFilters` before calling.**
+     * Returns empty array if not supported.
+     *
+     * @param options - Filter query options
+     * @param options.categoryId - Optional category ID for category-specific attributes
+     * @param options.useAdvancedSearch - Enable advanced filters (price, stock, attributes)
+     * @param options.includeBasicFilters - Include basic filters (categories, collections)
+     * @param options.includeFacetCounts - Include product counts per filter value (e.g., "Red (23)")
+     * @returns Array of filter configurations sorted by ranking
+     *
+     * @example
+     * ```typescript
+     * // Get filters for electronics category
+     * const filters = await commerce.getAvailableFilters({
+     *   categoryId: 'cat_electronics',
+     *   useAdvancedSearch: true,
+     *   includeBasicFilters: true,
+     *   includeFacetCounts: false
+     * });
+     *
+     * filters.forEach(filter => {
+     *   console.log(`${filter.label} (${filter.type})`);
+     *
+     *   if (filter.type === 'multi' && filter.options) {
+     *     filter.options.forEach(opt => {
+     *       console.log(`  - ${opt.label}${opt.count ? ` (${opt.count})` : ''}`);
+     *     });
+     *   } else if (filter.type === 'range') {
+     *     console.log(`  Range: ${filter.min} - ${filter.max}`);
+     *   }
+     * });
+     *
+     * // Output:
+     * // Price (range)
+     * //   Range: 0 - 5000
+     * // RAM (multi)
+     * //   - 8GB (15)
+     * //   - 16GB (23)
+     * //   - 32GB (8)
+     * // Brand (multi)
+     * //   - Dell (12)
+     * //   - HP (8)
+     * // In Stock (boolean)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use in React component
+     * function FilterSidebar({ categoryId }: { categoryId?: string }) {
+     *   const [filters, setFilters] = useState<FilterConfig[]>([]);
+     *
+     *   useEffect(() => {
+     *     if (!commerce.getAvailableFilters) return;
+     *
+     *     commerce.getAvailableFilters({
+     *       categoryId,
+     *       useAdvancedSearch: true,
+     *       includeBasicFilters: true
+     *     }).then(setFilters);
+     *   }, [categoryId]);
+     *
+     *   return (
+     *     <div>
+     *       {filters.map(filter => (
+     *         <FilterComponent key={filter.id} filter={filter} />
+     *       ))}
+     *     </div>
+     *   );
+     * }
+     * ```
+     *
+     * @throws {ProviderAPIError} If backend fails to fetch attributes
+     * @throws {Error} If category ID invalid
+     *
+     * @see FilterConfig for filter structure
+     * @see BackendCapabilities.facetedFilters to check if supported
+     */
+    getAvailableFilters?(options: {
+        categoryId?: string;
+        useAdvancedSearch?: boolean;
+        includeBasicFilters?: boolean;
+        includeFacetCounts?: boolean;
+    }): Promise<FilterConfig[]>;
+    /**
+     * Get a single collection by handle/slug
+     * @param handle - Collection handle (slug)
+     * @returns Collection or undefined if not found
+     */
+    getCollection(handle: string): Promise<Collection | undefined>;
+    /**
+     * Get all collections
+     * @param options - Query options (limit, search)
+     * @returns Array of collections
+     */
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    /**
+     * Get products in a collection
+     * @param handle - Collection handle
+     * @param options - Query options (sort, pagination)
+     * @returns Array of products in the collection
+     */
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    /**
+     * Get a single product category by ID or handle
+     * @param idOrHandle - Category ID or handle (slug)
+     * @returns Category or undefined if not found
+     */
+    getCategory(idOrHandle: string): Promise<ProductCategory | undefined>;
+    /**
+     * Get all product categories
+     * @param options - Query options (parent filter, descendants)
+     * @returns Array of categories
+     */
+    getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]>;
+    /**
+     * Get products in a category
+     * @param handle - Category handle (slug)
+     * @param options - Query options (sort, pagination)
+     * @returns Array of products in the category
+     */
+    getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    /**
+     * Create a new empty cart
+     * @param options - Optional cart creation options
+     * @param options.regionId - Region ID for the cart (required for some providers like Medusa)
+     * @returns New cart instance
+     */
+    createCart(options?: {
+        regionId?: string;
+    }): Promise<Cart>;
+    /**
+     * Get an existing cart by ID
+     * @param cartId - Cart ID
+     * @returns Cart or undefined if not found
+     */
+    getCart(cartId: string): Promise<Cart | undefined>;
+    /**
+     * Add items to cart
+     * @param cartId - Cart ID
+     * @param lines - Items to add
+     * @returns Updated cart
+     */
+    addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    /**
+     * Remove items from cart
+     * @param cartId - Cart ID
+     * @param lineIds - Line item IDs to remove
+     * @returns Updated cart
+     */
+    removeFromCart(cartId: string, lineIds: string[]): Promise<Cart>;
+    /**
+     * Update cart items
+     * @param cartId - Cart ID
+     * @param lines - Items to update
+     * @returns Updated cart
+     */
+    updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    /**
+     * Get available regions from the backend
+     * @returns Array of regions with id, name, and currency information
+     */
+    getRegions?(): Promise<Array<{
+        id: string;
+        name: string;
+        currency_code: string;
+        countries?: Array<{
+            id: string;
+            iso_2: string;
+            name: string;
+            display_name?: string;
+        }>;
+    }>>;
+    /**
+     * Complete checkout and create order from cart
+     *
+     * This is the final step in the checkout process that converts
+     * a cart into an order. The cart must have:
+     * - Valid shipping address
+     * - Selected shipping method (via addShippingMethod)
+     * - Initiated payment session (via initiatePaymentSession)
+     *
+     * @param cartId - Cart ID to checkout
+     * @returns Created order
+     * @throws {ProviderAPIError} If checkout fails (invalid cart, payment failure, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Complete checkout flow:
+     * // 1. Add shipping address (via cart update)
+     * // 2. Select shipping method
+     * await commerce.addShippingMethod(cartId, 'shipping_standard');
+     * // 3. Initiate payment
+     * await commerce.initiatePaymentSession(cartId, 'stripe');
+     * // 4. Complete checkout
+     * const order = await commerce.completeCheckout(cartId);
+     * ```
+     */
+    completeCheckout(cartId: string): Promise<Order>;
+    /**
+     * Get available shipping methods for cart
+     *
+     * Fetches shipping options based on cart contents, shipping address,
+     * and region. Returns empty array if no methods available.
+     *
+     * @param cartId - Cart ID
+     * @returns List of shipping methods with prices
+     * @throws {ProviderAPIError} If cart not found or region not configured
+     *
+     * @example
+     * ```typescript
+     * const methods = await commerce.getShippingMethods(cartId);
+     *
+     * methods.forEach(method => {
+     *   console.log(`${method.name}: ${method.price.amount} ${method.price.currencyCode}`);
+     * });
+     * ```
+     */
+    getShippingMethods(cartId: string): Promise<ShippingMethod[]>;
+    /**
+     * Get available countries for a region
+     *
+     * Returns list of countries that are available for shipping
+     * in the specified region. Used for checkout address validation.
+     *
+     * @param regionId - Region ID
+     * @returns Array of countries with codes and names
+     * @throws {ProviderAPIError} If region not found
+     *
+     * @example
+     * ```typescript
+     * const countries = await commerce.getRegionCountries('reg_europe');
+     *
+     * countries.forEach(country => {
+     *   console.log(`${country.code}: ${country.name}`);
+     * });
+     * // Output:
+     * // ES: Spain
+     * // FR: France
+     * // DE: Germany
+     * ```
+     */
+    getRegionCountries(regionId: string): Promise<Country[]>;
+    /**
+     * Add shipping method to cart
+     *
+     * Selects a shipping method from getShippingMethods() and applies it
+     * to the cart. This updates cart totals to include shipping cost.
+     *
+     * @param cartId - Cart ID
+     * @param methodId - Shipping method ID (from getShippingMethods)
+     * @returns Updated cart with shipping method and updated totals
+     * @throws {ProviderAPIError} If method ID invalid or cart not ready
+     *
+     * @example
+     * ```typescript
+     * const methods = await commerce.getShippingMethods(cartId);
+     * const standardShipping = methods.find(m => m.name === 'Standard');
+     *
+     * const updatedCart = await commerce.addShippingMethod(cartId, standardShipping.id);
+     * console.log('New total:', updatedCart.cost.totalAmount);
+     * ```
+     */
+    addShippingMethod(cartId: string, methodId: string): Promise<Cart>;
+    /**
+     * Initiate payment session with provider
+     *
+     * Creates a payment session with the selected payment provider.
+     * This is required before completeCheckout() can be called.
+     *
+     * Some providers (like Stripe) may return client secret for
+     * client-side payment confirmation.
+     *
+     * @param cartId - Cart ID
+     * @param providerId - Payment provider ID (from getPaymentMethods)
+     * @throws {ProviderAPIError} If provider invalid or cart not ready
+     *
+     * @example
+     * ```typescript
+     * const paymentMethods = await commerce.getPaymentMethods({ regionId });
+     * const stripeMethod = paymentMethods.find(m => m.id === 'stripe');
+     *
+     * await commerce.initiatePaymentSession(cartId, stripeMethod.id);
+     * // Payment session ready, can now complete checkout
+     * ```
+     */
+    initiatePaymentSession(cartId: string, providerId: string): Promise<void>;
+    /**
+     * Apply discount code to cart
+     *
+     * Validates and applies a discount/promo code to the cart.
+     * Updates cart totals to reflect discount.
+     *
+     * @param cartId - Cart ID
+     * @param code - Discount code (case-insensitive)
+     * @returns Updated cart with discount applied
+     * @throws {ProviderAPIError} If code invalid, expired, or not applicable
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const updatedCart = await commerce.applyDiscountCode(cartId, 'SUMMER2026');
+     *   console.log('Discount applied! New total:', updatedCart.cost.totalAmount);
+     * } catch (error) {
+     *   console.error('Invalid code:', error.message);
+     * }
+     * ```
+     */
+    applyDiscountCode(cartId: string, code: string): Promise<Cart>;
+    /**
+     * Remove discount code from cart
+     *
+     * Removes a previously applied discount code.
+     * Updates cart totals to remove discount.
+     *
+     * @param cartId - Cart ID
+     * @param code - Discount code to remove
+     * @returns Updated cart without discount
+     * @throws {ProviderAPIError} If cart not found
+     *
+     * @example
+     * ```typescript
+     * const updatedCart = await commerce.removeDiscountCode(cartId, 'SUMMER2026');
+     * console.log('Discount removed. New total:', updatedCart.cost.totalAmount);
+     * ```
+     */
+    removeDiscountCode(cartId: string, code: string): Promise<Cart>;
+    /**
+     * Update billing address for cart (optional)
+     *
+     * Sets or updates the billing address on the cart.
+     * Use when billing address differs from shipping address.
+     *
+     * Recommended to call BEFORE initiatePaymentSession() as some
+     * payment providers may require billing address.
+     *
+     * @param cartId - Cart ID
+     * @param address - Billing address to set
+     * @returns Updated cart with billing address
+     * @throws {ProviderAPIError} If cart not found or address invalid
+     *
+     * @example
+     * ```typescript
+     * await commerce.updateBillingAddress(cartId, {
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   address1: '123 Billing St',
+     *   city: 'Madrid',
+     *   province: 'Madrid',
+     *   postalCode: '28001',
+     *   countryCode: 'ES',
+     *   phone: '+34 600 000 000'
+     * });
+     * ```
+     */
+    updateBillingAddress?(cartId: string, address: Address): Promise<Cart>;
+    /**
+     * Get customer by ID (optional)
+     * @param customerId - Customer ID
+     * @returns Customer or undefined if not found
+     */
+    getCustomer?(customerId: string): Promise<Customer | undefined>;
+    /**
+     * List customers with optional filtering and pagination (optional)
+     * @param options - Query options (search, sort, pagination)
+     * @returns Array of customers
+     */
+    getCustomers?(options?: GetCustomersOptions): Promise<Customer[]>;
+    /**
+     * Update customer information (optional)
+     * @param customerId - Customer ID
+     * @param data - Fields to update
+     * @returns Updated customer
+     */
+    updateCustomer?(customerId: string, data: Partial<Omit<Customer, 'id' | 'createdAt'>>): Promise<Customer>;
+    /**
+     * Get order by ID (optional)
+     * @param orderId - Order ID
+     * @returns Order or undefined if not found
+     */
+    getOrder?(orderId: string): Promise<Order | undefined>;
+    /**
+     * Get all orders for a customer (optional)
+     *
+     * @param options - Order query options (supports callbacks for custom backends)
+     * @returns Array of orders
+     */
+    getOrders?(options: GetOrdersOptions): Promise<Order[]>;
+    /**
+     * Get available payment methods
+     *
+     * This method queries the backend for available payment providers
+     * based on region, cart, or other contextual factors.
+     *
+     * Backends that don't support dynamic payment method listing
+     * (capabilities.listPaymentProviders === false) should throw
+     * an error or return empty array.
+     *
+     * @param options - Payment methods query options
+     * @returns Array of available payment methods
+     *
+     * @example
+     * ```typescript
+     * // Get payment methods for a specific region
+     * const methods = await provider.getPaymentMethods({
+     *   regionId: 'reg_123',
+     *   enabledOnly: true
+     * });
+     *
+     * // Display to user
+     * methods.forEach(method => {
+     *   console.log(method.name, method.type);
+     * });
+     * ```
+     *
+     * @throws {Error} If backend request fails
+     * @throws {Error} If required options are missing (e.g., regionId for Medusa)
+     */
+    getPaymentMethods(options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    /**
+     * Fetch stock locations, optionally filtered by sales channel.
+     * Returns empty array when admin config is not provided (graceful degradation).
+     *
+     * @param params - Optional filter parameters
+     * @returns Array of stock locations
+     */
+    getStockLocations(params?: {
+        salesChannelId?: string;
+    }): Promise<StockLocation[]>;
+    /**
+     * Check inventory levels for a variant across locations.
+     * Returns empty array when admin config is not provided (graceful degradation).
+     *
+     * @param variantId - Variant ID to check
+     * @param salesChannelId - Optional sales channel filter
+     * @returns Array of inventory levels per location
+     */
+    checkInventoryLevels(variantId: string, salesChannelId?: string): Promise<InventoryLevel[]>;
+    /**
+     * Validate cart stock availability across all items.
+     * Returns all-available when admin config is not provided (graceful degradation).
+     *
+     * @param cartId - Cart ID to validate
+     * @returns Stock validation result with unavailable items (if any)
+     */
+    validateCartStock(cartId: string): Promise<StockValidation>;
+    /**
+     * Get fulfillment options enriched with stock location data.
+     *
+     * @param cartId - Cart ID
+     * @param salesChannelId - Sales channel ID for filtering
+     * @returns Array of fulfillment options
+     */
+    getFulfillmentOptions(cartId: string, salesChannelId: string): Promise<FulfillmentOption[]>;
+    /**
+     * Get a map of product IDs to their admin-level status.
+     * Only available when admin credentials are configured.
+     * Returns empty object when admin config is not provided (graceful degradation).
+     *
+     * Medusa statuses: 'published' | 'draft' | 'proposed' | 'rejected'
+     *
+     * @param options - Optional pagination (default limit: 1000)
+     * @returns Record mapping productId → status string
+     */
+    getAdminProductStatuses?(options?: {
+        limit?: number;
+    }): Promise<Record<string, string>>;
+    /**
+     * List ALL products from the admin API, including non-published ones.
+     * Returns real backend status values (provider-specific strings).
+     * Gracefully degrades to empty result when admin credentials are not configured.
+     *
+     * Unlike `getProducts()` (storefront API, published only), this method
+     * uses admin credentials to list products of any status.
+     *
+     * @param options.query   - Optional full-text search
+     * @param options.limit   - Max products to fetch (default: 1000)
+     * @param options.offset  - Pagination offset (default: 0)
+     * @returns { products: AdminProduct[]; count: number }
+     */
+    getAdminProducts?(options?: {
+        query?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        products: AdminProduct[];
+        count: number;
+    }>;
+    /**
+     * List all orders for admin dashboard.
+     * Gracefully degrades to empty result when adminConfig is not provided.
+     */
+    getAdminOrders(options?: {
+        search?: string;
+        status?: string | string[];
+        limit?: number;
+        offset?: number;
+        order?: string;
+        direction?: 'asc' | 'desc';
+        salesChannelId?: string;
+        /**
+         * When true, also fetches draft orders from /admin/draft-orders and merges
+         * them into the result sorted by created_at desc. Draft orders are stored
+         * as a separate entity from regular orders in Medusa v2.
+         */
+        includeDrafts?: boolean;
+    }): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    /**
+     * Get a single order by ID for admin detail view.
+     */
+    getAdminOrder?(orderId: string): Promise<Order | undefined>;
+    /**
+     * Get a single product by ID for admin detail view.
+     */
+    getAdminProduct?(productId: string): Promise<AdminProduct | undefined>;
+    /**
+     * Create a draft order (admin operation).
+     */
+    createDraftOrder?(params: {
+        email: string;
+        regionId: string;
+        salesChannelId?: string;
+        items: Array<{
+            variantId: string;
+            quantity: number;
+        }>;
+        shippingAddress?: {
+            firstName?: string;
+            lastName?: string;
+            address1?: string;
+            city?: string;
+            countryCode?: string;
+            postalCode?: string;
+        };
+    }): Promise<Order>;
+    /**
+     * Cancel an order (admin operation).
+     * Throws ProviderAPIError when adminConfig is not provided.
+     */
+    cancelOrder(orderId: string): Promise<Order>;
+    /**
+     * Create a fulfillment for an order (admin operation).
+     * Throws ProviderAPIError when adminConfig is not provided.
+     */
+    createFulfillment(orderId: string, items?: Array<{
+        id: string;
+        quantity: number;
+    }>): Promise<void>;
+    /**
+     * Convert a draft order into a regular pending order (admin operation).
+     * Throws ProviderAPIError when adminConfig is not provided.
+     */
+    undraftOrder?(draftOrderId: string): Promise<Order>;
+    /**
+     * Create a refund for an order (admin operation).
+     * Throws ProviderAPIError when adminConfig is not provided.
+     */
+    createRefund(orderId: string, amount?: number, reason?: string): Promise<void>;
+    /**
+     * List customers via admin API with search and pagination.
+     * Requires admin credentials. Gracefully degrades to empty result when
+     * admin config is not provided.
+     *
+     * @param options - Query options (search, limit, salesChannelId)
+     * @returns Paginated customer list
+     */
+    getAdminCustomers?(options?: GetCustomersOptions): Promise<{
+        customers: Customer[];
+        count: number;
+    }>;
+    /**
+     * Get a single customer by ID via admin API.
+     * Requires admin credentials.
+     *
+     * @param customerId - Customer ID
+     * @returns Customer or undefined if not found
+     */
+    getAdminCustomer?(customerId: string): Promise<Customer | undefined>;
+    /**
+     * Get addresses for a specific customer via admin API.
+     * Requires admin credentials.
+     *
+     * @param customerId - Customer ID
+     * @returns Array of customer addresses
+     */
+    getAdminCustomerAddresses?(customerId: string): Promise<Address[]>;
+    /**
+     * Get orders belonging to a specific customer.
+     * Uses admin API to list orders filtered by customer ID.
+     *
+     * @param customerId - Customer ID
+     * @param limit - Max orders to return (default: 10)
+     * @returns Array of orders
+     */
+    getCustomerOrders?(customerId: string, limit?: number): Promise<Order[]>;
+    /**
+     * List all regions configured in the backend.
+     * Used by admin dashboard for order creation (region selection).
+     *
+     * @returns Array of regions
+     */
+    getAdminRegions?(): Promise<Region[]>;
+    /**
+     * Get the current storefront/sales channel context.
+     *
+     * @returns StorefrontContext for the current storefront
+     * @throws StorefrontConfigError if storefront is required but not configured
+     * @throws ProviderAPIError if storefront lookup fails
+     *
+     * @remarks
+     * - Called on every request that accesses scoped data
+     * - Should throw EARLY if configuration is invalid
+     * - NOT optional — must always return a valid context or throw
+     *
+     * @example
+     * ```typescript
+     * const storefront = await commerce.getStorefrontContext();
+     * console.log(storefront.name, storefront.platformType);
+     * ```
+     */
+    getStorefrontContext(): Promise<StorefrontContext>;
+    /**
+     * Check if this provider requires storefront configuration.
+     *
+     * @returns true if storefront is mandatory for correct operation
+     *
+     * @remarks
+     * - Medusa: true
+     * - Shopify: false (optional for single storefront)
+     * - WooCommerce: false (not supported natively)
+     * - BigCommerce: false (optional)
+     * - Spree: false (optional for single store)
+     * - Magento: true (always required)
+     */
+    isStorefrontRequired(): boolean;
+    /**
+     * Get per-channel storefront configuration (logo, accent color, currency, SEO).
+     *
+     * Calls `GET /store/thor/config` (resolved via publishable API key).
+     * Returns `null` if the Thor Commerce plugin is not installed or
+     * no config exists for the current channel.
+     *
+     * @returns StorefrontConfig or null
+     */
+    getStorefrontConfig?(): Promise<StorefrontConfig | null>;
+    /**
+     * Get the active Site Designer configuration for the current channel.
+     *
+     * Calls `GET /store/thor/site-config` (resolved via publishable API key).
+     * Returns `null` if the Thor Commerce plugin is not installed or
+     * no config exists for the current channel.
+     *
+     * @returns Versioned DesignerConfig or null
+     */
+    getDesignerConfig?(): Promise<{
+        version: string;
+        config: DesignerConfig;
+    } | null>;
+    /**
+     * Get admin Site Designer config + history for a sales channel.
+     *
+     * @param salesChannelId - Target sales channel ID
+     * @returns Config with version history, or null if not found
+     */
+    getAdminDesignerConfig?(salesChannelId: string): Promise<{
+        version: string;
+        config: DesignerConfig;
+        history?: DesignerHistoryEntry[];
+    } | null>;
+    /**
+     * Update the Site Designer config for a sales channel.
+     *
+     * @param salesChannelId - Target sales channel ID
+     * @param config - New designer configuration
+     * @returns Updated config with new version
+     */
+    updateAdminDesignerConfig?(salesChannelId: string, config: DesignerConfig): Promise<{
+        version: string;
+        config: DesignerConfig;
+    }>;
+    /**
+     * Restore a previous Site Designer config version.
+     *
+     * @param salesChannelId - Target sales channel ID
+     * @param version - Version string to restore
+     * @returns Restored config with new version
+     */
+    restoreAdminDesignerConfig?(salesChannelId: string, version: string): Promise<{
+        version: string;
+        config: DesignerConfig;
+    }>;
+}
+/**
+ * Provider configuration base type
+ */
+interface ProviderConfig {
+    /**
+     * Enable debug mode (verbose logging)
+     */
+    debug?: boolean;
+    /**
+     * Custom fetch implementation (for server-side use)
+     */
+    customFetch?: typeof fetch;
+}
+
+/**
+ * Admin User Types
+ *
+ * Defines the structure for admin user accounts.
+ * MVP uses single password (no email), but prepared for multi-admin.
+ *
+ * @module admin/AdminUser
+ */
+/**
+ * Admin User Account
+ *
+ * @remarks
+ * - MVP: email and passwordHash are optional (uses global password)
+ * - Future: Required fields for multi-admin system
+ */
+interface AdminUser {
+    /** Unique identifier */
+    id: string;
+    /** Email address (optional in MVP, required for multi-admin) */
+    email?: string;
+    /** Bcrypt password hash (optional in MVP, required for multi-admin) */
+    passwordHash?: string;
+    /** Account creation timestamp */
+    createdAt: Date;
+    /** Last update timestamp */
+    updatedAt: Date;
+}
+
+/**
+ * Audit Log Types
+ *
+ * Defines the structure for audit logging of admin actions.
+ * Tracks all critical operations for security and compliance.
+ *
+ * @module admin/AuditLog
+ */
+/**
+ * Audit Log Entry
+ *
+ * @remarks
+ * Records all admin actions for security auditing and compliance
+ */
+interface AuditLog {
+    /** Unique identifier */
+    id: string;
+    /** ID of the admin who performed the action */
+    adminId: string;
+    /** Action performed (e.g., 'login_success', 'update_order_status') */
+    action: string;
+    /** Type of resource affected (e.g., 'auth', 'order', 'product') */
+    resourceType: string;
+    /** ID of the specific resource (optional) */
+    resourceId?: string;
+    /** Additional context data */
+    metadata?: Record<string, unknown>;
+    /** IP address of the requester */
+    ipAddress?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Timestamp of the action */
+    createdAt: Date;
+}
+
+/**
+ * Dashboard Metrics Types
+ *
+ * Defines the structure for dashboard analytics and metrics.
+ * Used by the DashboardModule to display key business indicators.
+ *
+ * @module admin/DashboardMetrics
+ */
+/**
+ * Sales Metrics
+ */
+interface SalesMetrics {
+    /** Total sales amount (all time) */
+    total: number;
+    /** Sales amount today */
+    today: number;
+    /** Sales amount in the last 7 days */
+    week: number;
+    /** Sales amount in the last 30 days */
+    month: number;
+}
+/**
+ * Orders Metrics
+ */
+interface OrdersMetrics {
+    /** Total number of orders */
+    total: number;
+    /** Number of pending orders */
+    pending: number;
+    /** Number of orders being processed */
+    processing: number;
+    /** Number of completed orders */
+    completed: number;
+}
+/**
+ * Products Metrics
+ */
+interface ProductsMetrics {
+    /** Total number of products */
+    total: number;
+    /** Number of products with low stock */
+    lowStock: number;
+}
+/**
+ * Chart Data Point
+ */
+interface ChartDataPoint {
+    /** Date in ISO format (YYYY-MM-DD) */
+    date: string;
+    /** Sales amount for this date */
+    sales: number;
+}
+/**
+ * Complete Dashboard Metrics
+ */
+interface DashboardMetrics {
+    /** Sales metrics */
+    sales: SalesMetrics;
+    /** Orders metrics */
+    orders: OrdersMetrics;
+    /** Products metrics */
+    products: ProductsMetrics;
+    /** Chart data for visualization (last 7 days) */
+    chartData: ChartDataPoint[];
+}
+
+/**
+ * Dashboard Configuration Types
+ *
+ * Defines the configuration structure for the DashboardModule.
+ * Uses adapters pattern for maximum flexibility and testability.
+ *
+ * @module admin/DashboardConfig
+ */
+
+/**
+ * Adapter for fetching dashboard metrics
+ *
+ * @remarks
+ * L3 components use this interface, L5 provides HTTP implementation
+ */
+interface DashboardMetricsAdapter {
+    getMetrics(): Promise<DashboardMetrics>;
+}
+/**
+ * Adapter for fetching and managing orders
+ */
+interface DashboardOrdersAdapter {
+    getOrders(params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+    }): Promise<{
+        orders: Order[];
+        total: number;
+    }>;
+    getOrderById(id: string): Promise<Order>;
+    updateOrderStatus?(id: string, status: string): Promise<Order>;
+}
+/**
+ * Adapter for fetching and managing products
+ */
+interface DashboardProductsAdapter {
+    getProducts(params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+    }): Promise<{
+        products: Product[];
+        total: number;
+    }>;
+    getProductById(id: string): Promise<Product>;
+}
+/**
+ * Adapter for fetching audit logs
+ */
+interface AuditLogAdapter {
+    getLogs(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        logs: any[];
+        total: number;
+    }>;
+}
+/**
+ * Complete Dashboard Configuration
+ *
+ * @remarks
+ * Passed to DashboardModule component
+ */
+interface DashboardConfig {
+    /** Storefront identifier */
+    storefrontId: string;
+    /** Metrics adapter (required for all variants) */
+    metrics: DashboardMetricsAdapter;
+    /** Orders adapter (required for standard and complete variants) */
+    orders: DashboardOrdersAdapter;
+    /** Products adapter (optional, for complete variant) */
+    products?: DashboardProductsAdapter;
+    /** Audit logs adapter (optional, for complete variant) */
+    auditLogs?: AuditLogAdapter;
+}
+
+/**
+ * Site Config Metadata Types
+ *
+ * Defines the structure for versioned site configuration storage.
+ * Uses Stripe-style date-based versioning for configuration history.
+ * Stored in backend metadata (no separate database).
+ *
+ * @module admin/SiteConfigMetadata
+ */
+
+/**
+ * Configuration History Entry
+ */
+interface ConfigHistoryEntry {
+    /** Version identifier (date-based: YYYY-MM-DD) */
+    version: string;
+    /** The site configuration at this version */
+    config: SiteConfig;
+    /** ISO 8601 timestamp when this version was created */
+    createdAt: string;
+    /** Admin ID who created this version (for future RBAC) */
+    createdBy?: string;
+}
+/**
+ * Site Configuration Metadata
+ *
+ * @remarks
+ * Stored in backend metadata field (e.g., sales_channel.metadata['site_config'])
+ * Uses date-based versioning inspired by Stripe API versioning
+ */
+interface SiteConfigMetadata {
+    /** Current version (date-based: YYYY-MM-DD) */
+    version: string;
+    /** The current active site configuration */
+    config: SiteConfig;
+    /** Configuration history (last 10 versions) */
+    history?: ConfigHistoryEntry[];
+}
+
+/**
+ * @thorprovider/types v1.0
+ * Shared TypeScript types for Thor Commerce ecosystem
+ *
+ * Pure type definitions with zero runtime dependencies.
+ * Foundation for type-safe commerce operations following SOLID principles.
+ */
+
+declare enum SupportedProviderType {
+    Medusa = "medusa"
+}
+
+export { type AccountDropdownConfig, type AccountMenuItem, type ActiveFilter, type Address, type AdminProduct, type AdminProductVariant, type AdminUser, type AdvancedSearchProductsOptions, type AuditLog, type AuditLogAdapter, type AuthConfig, type AuthMethod, type AuthProvider, type AuthResponse, type AuthStorage, type AuthorConfig, type BackendCapabilities, type BrandConfig, type CachedPaymentMethods, type Cart, type CartCost, type CartItem, type CartLineInput, type CartLineUpdate, type CartProduct, type ChartDataPoint, type Collection, type CollectionProductsOptions, type CommerceProvider, type CompareProduct, type ConfigHistoryEntry, type Connection, type Country, type CreateAddressData, type Customer, type DashboardConfig, type DashboardMetrics, type DashboardMetricsAdapter, type DashboardOrdersAdapter, type DashboardProductsAdapter, type DesignerConfig, type DesignerHistoryEntry, type DesignerNavItem, type DesignerThemeConfig, type DesignerThemePreset, type DiscountCode, type DynamicSource, type Edge, type FilterConfig, type FilterOption, type FilterSection, type FulfillmentOption, type FulfillmentSet, type FulfillmentStatus, type GetCategoriesCallback, type GetCategoriesOptions, type GetCollectionsOptions, type GetCustomersCallback, type GetCustomersOptions, type GetOrdersCallback, type GetOrdersOptions, type GetProductsOptions, type HeaderLinkItem, type HeaderNavigationConfig, type IconConfig, type Image, type InventoryLevel, type LoginCredentials, type ModulesConfig, type Money, type NavigationCalloutItem, type NavigationItem, type NavigationLinkItem, type Order, type OrderItem, type OrderStatus, type OrdersMetrics, PROVIDER_METADATA, type PaginationOptions, type PasswordResetConfirm, type PasswordResetRequest, type PaymentMethod, type PaymentMethodFeatures, type PaymentMethodType, type PaymentMethodsOptions, type PaymentStatus, type PriceRange, type Product, type ProductCategory, type ProductOption, type ProductPreview, type ProductVariant, type ProductsMetrics, type ProviderConfig, type ProviderTypeString, type Region, type RegisterData, type Review, type SEO, type SalesMetrics, type SearchBarConfig, type SearchResultMeta, type SelectedOption, type ShippingMethod, type SiteConfig, type SiteConfigLabels, type SiteConfigMetadata, type SocialConfig, type SortOption, type SortOptions, type StockLocation, type StockStatus, type StockValidation, type StorefrontConfig, StorefrontConfigError, type StorefrontContext, type StorefrontPlatformType, type StorefrontSeoDefaults, SupportedProviderType, type UpdateCustomerData, getProviderMetadata, isSupportedProviderType };