@thorprovider/types 2.0.2

package/src/commerce-provider.ts

@@ -0,0 +1,1139 @@
+/**
+ * @thorprovider/types v1.0
+ * Commerce Provider Interfaces
+ * 
+ * Defines the unified interface that all commerce providers must implement.
+ * This ensures @thorprovider/components (L3) can depend on abstractions, not implementations.
+ * 
+ * @see SOLID Dependency Inversion Principle
+ */
+
+import type { 
+  Product, 
+  GetProductsOptions,
+  AdvancedSearchProductsOptions,
+  SearchResultMeta,
+  FilterConfig,
+  AdminProduct,
+} from './product';
+import type { 
+  Cart, 
+  CartLineInput, 
+  CartLineUpdate,
+  ShippingMethod 
+} from './cart';
+import type { 
+  Collection, 
+  CollectionProductsOptions,
+  GetCollectionsOptions 
+} from './collection';
+import type {
+  ProductCategory,
+  GetCategoriesOptions
+} from './category';
+import type { Customer, Address, GetCustomersOptions } from './customer';
+import type { Order, GetOrdersOptions } from './order';
+import type { Region } from './region';
+import type { PaymentMethod, PaymentMethodsOptions } from './payment';
+import type { AuthProvider } from './auth';
+import type { StorefrontContext } from './storefront';
+import type { StockLocation, InventoryLevel, StockValidation, FulfillmentOption } from './stock-location';
+import type { StorefrontConfig } from './storefront-config';
+import type { DesignerConfig, DesignerHistoryEntry } from './designer-config';
+
+/**
+ * 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 />;
+ * }
+ * ```
+ */
+export 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
+ */
+export 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;
+  
+  // ============================================
+  // Product Operations (Required)
+  // ============================================
+  
+  /**
+   * 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 Search Operations (Optional)
+  // ============================================
+  
+  /**
+   * 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[]>;
+  
+  // ============================================
+  // Collection Operations (Required)
+  // ============================================
+  
+  /**
+   * 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[]>;
+  
+  // ============================================
+  // Category Operations (Required for taxonomy-based navigation)
+  // ============================================
+  
+  /**
+   * 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[]>;
+  
+  // ============================================
+  // Cart Operations (Required)
+  // ============================================
+  
+  /**
+   * 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 
+    }> 
+  }>>;
+  
+  // ============================================  // Checkout Operations (Required)
+  // ============================================
+  
+  /**
+   * 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<import('./common').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>;
+  
+  // ============================================  // Customer Operations (Optional)
+  // ============================================
+  
+  /**
+   * 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>;
+  
+  // ============================================
+  // Order Operations (Optional)
+  // ============================================
+  
+  /**
+   * 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[]>;
+  
+  // ============================================
+  // Payment Operations
+  // ============================================
+  
+  /**
+   * 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[]>;
+
+  // ============================================
+  // Inventory Operations (Admin API — Optional)
+  // ============================================
+
+  /**
+   * 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 }>;
+
+  // ============================================
+  // Admin Order Operations (Admin API — Optional)
+  // ============================================
+
+  /**
+   * 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>;
+
+  // ============================================
+  // Admin Customer Operations (Admin API — Optional)
+  // ============================================
+
+  /**
+   * 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[]>;
+
+  // ============================================
+  // Admin Region Operations (Admin API — Optional)
+  // ============================================
+
+  /**
+   * List all regions configured in the backend.
+   * Used by admin dashboard for order creation (region selection).
+   *
+   * @returns Array of regions
+   */
+  getAdminRegions?(): Promise<Region[]>;
+
+  // ============================================
+  // Storefront / Multi-Tenant Operations
+  // ============================================
+
+  /**
+   * 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;
+
+  // ============================================
+  // Thor Plugin — Storefront Configuration (Optional)
+  // ============================================
+
+  /**
+   * 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>;
+
+  // ============================================
+  // Thor Plugin — Admin Site Designer (Optional)
+  // ============================================
+
+  /**
+   * 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
+ */
+export interface ProviderConfig {
+  /**
+   * Enable debug mode (verbose logging)
+   */
+  debug?: boolean;
+  
+  /**
+   * Custom fetch implementation (for server-side use)
+   */
+  customFetch?: typeof fetch;
+}