@thorprovider/adapters 3.0.2

package/dist/index.d.ts

@@ -0,0 +1,2524 @@
+import * as _thorprovider_types from '@thorprovider/types';
+import { BackendCapabilities, Money, PaymentMethod, FulfillmentOption, CartItem, StockLocation, InventoryLevel, StorefrontConfig, DashboardMetrics, ProviderTypeString, CommerceProvider, AuthProvider, ProviderConfig, AuthConfig, Product, GetProductsOptions, AdvancedSearchProductsOptions, SearchResultMeta, FilterConfig, Collection, GetCollectionsOptions, CollectionProductsOptions, ProductCategory, GetCategoriesOptions, Cart, CartLineInput, CartLineUpdate, GetOrdersOptions, Order, GetCustomersOptions, Customer, Address, Region, AdminProduct, PaymentMethodsOptions, StockValidation, StorefrontContext, DesignerConfig, DesignerHistoryEntry, ShippingMethod } from '@thorprovider/types';
+export * from '@thorprovider/types';
+export { BackendCapabilities, CommerceProvider, DesignerConfig, DesignerHistoryEntry, DesignerNavItem, DesignerThemeConfig, DesignerThemePreset, ProviderConfig, StorefrontConfig, StorefrontConfigError, StorefrontContext, StorefrontPlatformType, StorefrontSeoDefaults } from '@thorprovider/types';
+import Medusa from '@medusajs/js-sdk';
+
+/**
+ * @thorprovider/adapters
+ * UI-ready response types
+ *
+ * These types extend domain types from @thorprovider/types (L1) but with transformations
+ * applied for direct UI consumption. This is where Money→number conversions happen.
+ *
+ * L3 (@thorprovider/components) should import these types, not the raw domain types.
+ */
+
+/**
+ * UI-ready cart item with prices as numbers
+ *
+ * Simplified cart item for UI consumption with prices in major currency units (e.g., dollars, euros).
+ * Transformed from domain CartItem by adapter services.
+ * Values come from Money.amount (decimal string in major units) parsed to number.
+ *
+ * This is a flattened structure optimized for UI display, unlike the nested
+ * domain CartItem which follows the Shopify/Medusa structure.
+ *
+ * @example
+ * ```typescript
+ * const uiItem: UICartItem = {
+ *   id: 'item_123',
+ *   productId: 'prod_abc',
+ *   variantId: 'var_xyz',
+ *   name: 'T-Shirt',
+ *   variant: 'Red / Large',
+ *   image: 'https://...',
+ *   price: 19.99,  // $19.99 in major units
+ *   quantity: 2,
+ *   total: 39.98,  // $39.98 in major units
+ *   isAvailable: true
+ * }
+ * ```
+ */
+interface UICartItem {
+    /** Unique item identifier */
+    id: string;
+    /** Product ID */
+    productId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Product name */
+    name: string;
+    /** Product description (optional) */
+    description?: string;
+    /** Variant description (e.g., 'Red / Large') */
+    variant: string;
+    /** Product image URL */
+    image: string;
+    /** Unit price in major currency units (e.g., dollars, euros) */
+    price: number;
+    /** Quantity in cart */
+    quantity: number;
+    /** Total price (price × quantity) in major currency units */
+    total: number;
+    /** Whether item is available for purchase */
+    isAvailable?: boolean;
+    /** Maximum quantity available in stock */
+    maxQuantity?: number;
+}
+/**
+ * UI-ready cart totals with amounts as numbers
+ *
+ * All monetary values are in major currency units (e.g., dollars, euros).
+ * Values come from Money.amount (decimal string in major units) parsed to number.
+ * Transformed from domain CartCost by adapter services.
+ *
+ * @example
+ * ```typescript
+ * const totals: UICartTotals = {
+ *   subtotal: 59.97,    // $59.97
+ *   discount: 10.00,    // $10.00
+ *   shipping: 5.00,     // $5.00
+ *   tax: 5.39,          // $5.39
+ *   total: 60.36,       // $60.36
+ *   currency: 'USD',
+ *   itemCount: 3
+ * }
+ * ```
+ */
+interface UICartTotals {
+    /** Subtotal before discounts/shipping/tax (in major currency units) */
+    subtotal: number;
+    /** Discount amount if any (in major currency units) */
+    discount?: number;
+    /** Discount code applied */
+    discountCode?: string;
+    /** Shipping cost (in major currency units) */
+    shipping?: number;
+    /** Tax amount (in major currency units) */
+    tax?: number;
+    /** Final total amount (in major currency units) */
+    total: number;
+    /** Currency code (ISO 4217, e.g., 'USD', 'EUR') */
+    currency: string;
+    /** Total number of items in cart */
+    itemCount: number;
+}
+/**
+ * UI-ready shipping method with price as number
+ *
+ * Price is in the currency's smallest unit.
+ * Transformed from domain ShippingMethod by adapter services.
+ *
+ * Includes alias fields for compatibility with existing checkout components.
+ *
+ * @example
+ * ```typescript
+ * const method: UIShippingMethod = {
+ *   id: 'ship_standard',
+ *   methodId: 'ship_standard',  // alias for id
+ *   name: 'Standard Shipping',
+ *   price: 500,  // $5.00 as 500 cents
+ *   amount: 500, // alias for price
+ *   estimatedDays: '3-5 business days'
+ * }
+ * ```
+ */
+interface UIShippingMethod {
+    /** Unique identifier */
+    id: string;
+    /** Alias for id (for compatibility with checkout components) */
+    methodId: string;
+    /** Display name */
+    name: string;
+    /** Shipping price in smallest currency unit */
+    price: number;
+    /** Alias for price (for compatibility with checkout components) */
+    amount: number;
+    /** Optional description */
+    description?: string;
+    /** Estimated delivery time (human-readable string) */
+    estimatedDays?: string;
+}
+/**
+ * UI-ready discount code with value as number
+ *
+ * Transformed from domain DiscountCode by adapter services.
+ * Value is in the currency's smallest unit for fixed discounts,
+ * or a percentage (0-100) for percentage discounts.
+ *
+ * @example
+ * ```typescript
+ * // Fixed discount
+ * const fixedDiscount: UIDiscountCode = {
+ *   code: 'SAVE10',
+ *   value: 1000,  // $10.00 as 1000 cents
+ *   isPercentage: false,
+ *   description: 'Save $10 on your order'
+ * }
+ *
+ * // Percentage discount
+ * const percentDiscount: UIDiscountCode = {
+ *   code: 'SAVE20',
+ *   value: 20,  // 20%
+ *   isPercentage: true,
+ *   description: 'Save 20% on your order'
+ * }
+ * ```
+ */
+interface UIDiscountCode {
+    /** Discount code */
+    code: string;
+    /** Discount value - either amount in smallest currency unit or percentage (0-100) */
+    value: number;
+    /** Whether value is a percentage (true) or fixed amount (false) */
+    isPercentage: boolean;
+    /** Human-readable description of the discount */
+    description?: string;
+    /** Minimum purchase amount required (in smallest currency unit) */
+    minimumAmount?: number;
+    /** Expiration date */
+    expiresAt?: Date;
+    /** Maximum number of uses allowed */
+    maxUses?: number;
+    /** Current usage count */
+    usageCount?: number;
+}
+/**
+ * UI-ready payment method for checkout selection
+ *
+ * Simplified version of domain PaymentMethod with additional
+ * providerId field for backend-specific provider identification.
+ *
+ * @example
+ * ```typescript
+ * const payment: UIPaymentMethod = {
+ *   id: 'pp_stripe_stripe',
+ *   providerId: 'stripe',
+ *   name: 'Credit Card',
+ *   description: 'Visa, Mastercard, American Express'
+ * }
+ * ```
+ */
+interface UIPaymentMethod {
+    /** Unique identifier */
+    id: string;
+    /** Provider identifier (e.g., 'stripe', 'paypal', 'manual') */
+    providerId: string;
+    /** Display name for UI */
+    name: string;
+    /** Optional description */
+    description?: string;
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Backend Capabilities System
+ *
+ * Defines what operations each backend platform supports.
+ * This is a compile-time capability detection system, NOT runtime feature flags.
+ *
+ * NOTE: BackendCapabilities interface is defined in @thorprovider/types (L1: Foundation).
+ * This file re-exports it and provides platform-specific implementations.
+ *
+ * @see packages/core/docs/BACKEND_CAPABILITIES_ANALYSIS.md
+ * @see packages/core/docs/COMMERCE_PROVIDER_ARCHITECTURE.md
+ */
+
+/**
+ * Medusa backend capabilities
+ *
+ * @see https://docs.medusajs.com/api/store
+ */
+declare const MEDUSA_CAPABILITIES: Readonly<BackendCapabilities>;
+/**
+ * Shopify backend capabilities
+ *
+ * @see https://shopify.dev/docs/api/storefront
+ */
+declare const SHOPIFY_CAPABILITIES: Readonly<BackendCapabilities>;
+/**
+ * BigCommerce backend capabilities
+ *
+ * @see https://developer.bigcommerce.com/docs/rest-storefront
+ */
+declare const BIGCOMMERCE_CAPABILITIES: Readonly<BackendCapabilities>;
+/**
+ * WooCommerce backend capabilities
+ *
+ * @see https://developer.woocommerce.com/docs/apis/store-api
+ */
+declare const WOOCOMMERCE_CAPABILITIES: Readonly<BackendCapabilities>;
+/**
+ * Spree Commerce backend capabilities
+ *
+ * @see https://docs.spreecommerce.org/api-reference
+ */
+declare const SPREE_CAPABILITIES: Readonly<BackendCapabilities>;
+/**
+ * Adobe Commerce / Magento backend capabilities
+ *
+ * @see https://developer.adobe.com/commerce/webapi/graphql/
+ */
+declare const MAGENTO_CAPABILITIES: Readonly<BackendCapabilities>;
+/**
+ * Type guard to check if an object is a valid BackendCapabilities
+ */
+declare function isBackendCapabilities(obj: unknown): obj is BackendCapabilities;
+/**
+ * Get capability description for UI display
+ */
+declare function getCapabilityDescription(capability: keyof BackendCapabilities): string;
+
+/**
+ * @thorprovider/adapters v2.0
+ * Core errors
+ */
+/**
+ * Base error class for commerce providers
+ */
+declare class CommerceError extends Error {
+    readonly code?: string | undefined;
+    readonly status?: number | undefined;
+    constructor(message: string, code?: string | undefined, status?: number | undefined);
+}
+/**
+ * Provider not found error
+ */
+declare class ProviderNotFoundError extends CommerceError {
+    constructor(providerName: string);
+}
+/**
+ * Configuration error
+ */
+declare class ConfigurationError extends CommerceError {
+    constructor(message: string);
+}
+/**
+ * Resource not found error
+ */
+declare class ResourceNotFoundError extends CommerceError {
+    constructor(resource: string, identifier: string);
+}
+/**
+ * API error from provider
+ */
+declare class ProviderAPIError extends CommerceError {
+    readonly provider: string;
+    constructor(message: string, provider: string, status?: number);
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Core logger utility
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Create a logger instance
+ */
+declare function createLogger(namespace: string, enabled?: boolean): Logger;
+
+/**
+ * @thorprovider/adapters v2.0
+ * Fetch Utilities - Retry logic, timeouts, and error handling
+ *
+ * This module provides enhanced fetch capabilities with:
+ * - Automatic retries with exponential backoff
+ * - Configurable timeouts
+ * - Better error handling for network failures
+ */
+/**
+ * Configuration for fetch retry behavior
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (default: 3)
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before first retry (default: 300ms)
+     */
+    initialDelayMs?: number;
+    /**
+     * Multiplier for exponential backoff (default: 2)
+     */
+    backoffMultiplier?: number;
+    /**
+     * Maximum delay between retries in milliseconds (default: 5000ms)
+     */
+    maxDelayMs?: number;
+    /**
+     * Timeout for each fetch attempt in milliseconds (default: 10000ms - 10 seconds)
+     */
+    timeoutMs?: number;
+    /**
+     * HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504])
+     */
+    retryableStatusCodes?: number[];
+}
+
+/**
+ * Circuit Breaker Pattern Implementation
+ *
+ * Prevents cascading failures when the backend is unavailable.
+ * Implements the Circuit Breaker pattern as described by Martin Fowler.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Too many failures, requests fail fast
+ * - HALF_OPEN: Testing if backend has recovered
+ *
+ * @see https://martinfowler.com/bliki/CircuitBreaker.html
+ */
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time in ms to wait before attempting recovery */
+    resetTimeout: number;
+    /** Name for logging/monitoring */
+    name?: string;
+}
+interface CircuitBreakerStats {
+    state: CircuitState;
+    failureCount: number;
+    lastFailureTime: number | null;
+    totalRequests: number;
+    totalFailures: number;
+    totalSuccesses: number;
+}
+/**
+ * Circuit Breaker Class
+ *
+ * Monitors backend calls and prevents cascading failures by
+ * failing fast when the backend is unhealthy.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 3,
+ *   resetTimeout: 60000, // 1 minute
+ *   name: 'backend-api'
+ * });
+ *
+ * const result = await breaker.execute(
+ *   () => fetch('/api/data'),
+ *   fallbackData
+ * );
+ * ```
+ */
+declare class CircuitBreaker {
+    private config;
+    private failureCount;
+    private lastFailureTime;
+    private totalRequests;
+    private totalFailures;
+    private totalSuccesses;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Get current circuit state
+     */
+    get state(): CircuitState;
+    /**
+     * Get circuit breaker statistics
+     */
+    get stats(): CircuitBreakerStats;
+    /**
+     * Execute a function with circuit breaker protection
+     *
+     * @param fn - Function to execute
+     * @param fallback - Fallback value if circuit is open
+     * @returns Result from fn or fallback
+     */
+    execute<T>(fn: () => Promise<T>, fallback?: T): Promise<T>;
+    /**
+     * Check if circuit should attempt to reset
+     */
+    private shouldAttemptReset;
+    /**
+     * Record a successful call
+     */
+    private onSuccess;
+    /**
+     * Record a failed call
+     */
+    private onFailure;
+    /**
+     * Reset circuit to CLOSED state
+     */
+    private reset;
+    /**
+     * Manually reset the circuit breaker
+     */
+    manualReset(): void;
+    /**
+     * Log messages (only in development)
+     */
+    private log;
+}
+/**
+ * Custom error for when circuit is open
+ */
+declare class CircuitBreakerOpenError extends Error {
+    constructor(message: string);
+}
+/**
+ * Global circuit breaker instance for backend API calls
+ *
+ * Can be imported and used throughout the application
+ */
+declare const backendCircuitBreaker: CircuitBreaker;
+
+/**
+ * @thorprovider/adapters
+ * Money transformation utilities
+ *
+ * Handles conversion between domain Money types (string decimals) and
+ * UI-ready number representations (smallest currency unit, e.g., cents).
+ */
+
+/**
+ * Converts Money object to number in smallest currency unit
+ *
+ * Money.amount is a decimal string (e.g., "45.99").
+ * This function converts it to smallest unit (e.g., 4599 cents).
+ *
+ * @param money - Money object with decimal string amount
+ * @returns Amount in smallest currency unit (e.g., cents for USD)
+ *
+ * @example
+ * ```typescript
+ * moneyToNumber({ amount: "45.99", currencyCode: "USD" })  // => 4599
+ * moneyToNumber({ amount: "100.00", currencyCode: "EUR" }) // => 10000
+ * moneyToNumber({ amount: "0.50", currencyCode: "USD" })   // => 50
+ * ```
+ */
+declare function moneyToNumber(money: Money): number;
+/**
+ * Converts number (smallest unit) to Money object
+ *
+ * Takes an amount in smallest currency unit (e.g., cents) and
+ * converts it to a Money object with decimal string amount.
+ *
+ * @param amount - Amount in smallest currency unit (e.g., cents)
+ * @param currency - ISO 4217 currency code (e.g., 'USD', 'EUR')
+ * @returns Money object with decimal string amount
+ *
+ * @example
+ * ```typescript
+ * numberToMoney(4599, 'USD')  // => { amount: "45.99", currencyCode: "USD" }
+ * numberToMoney(10000, 'EUR') // => { amount: "100.00", currencyCode: "EUR" }
+ * numberToMoney(50, 'USD')    // => { amount: "0.50", currencyCode: "USD" }
+ * ```
+ */
+declare function numberToMoney(amount: number, currency: string): Money;
+/**
+ * Safely converts Money to number, returning 0 for null/undefined
+ *
+ * Useful for optional Money fields that might not always be present.
+ *
+ * @param money - Money object or null/undefined
+ * @returns Amount in smallest unit, or 0 if money is null/undefined
+ *
+ * @example
+ * ```typescript
+ * moneyToNumberSafe({ amount: "10.00", currencyCode: "USD" }) // => 1000
+ * moneyToNumberSafe(undefined) // => 0
+ * moneyToNumberSafe(null)      // => 0
+ * ```
+ */
+declare function moneyToNumberSafe(money: Money | null | undefined): number;
+
+/**
+ * @thorprovider/adapters - Payment Utilities
+ *
+ * Backend-agnostic utilities for extracting backend provider IDs from
+ * normalized PaymentMethod objects using metadata.
+ *
+ * This solves the problem of losing backend-specific provider IDs during
+ * transformation to frontend-friendly formats.
+ *
+ * @module payment-utils
+ * @since 2.0.0
+ */
+
+/**
+ * Backend mapping metadata stored in PaymentMethod.metadata
+ *
+ * This metadata is added during payment method transformation
+ * to preserve the original backend-specific identifier.
+ *
+ * @example
+ * ```typescript
+ * const metadata = {
+ *   _backendMapping: {
+ *     backend: 'medusa',
+ *     originalId: 'pp_stripe_stripe',
+ *     normalizedType: 'card'
+ *   }
+ * };
+ * ```
+ */
+interface BackendMapping {
+    /**
+     * Backend type (e.g., 'medusa', 'shopify', 'woocommerce')
+     */
+    backend: string;
+    /**
+     * Original backend-specific provider ID
+     *
+     * Examples:
+     * - Medusa: 'pp_stripe_stripe', 'pp_paypal_paypal', 'pp_system_default'
+     * - Shopify: 'shopify_payments', 'paypal_express'
+     * - WooCommerce: 'stripe', 'paypal', 'cod'
+     */
+    originalId: string;
+    /**
+     * Normalized payment method type
+     *
+     * The frontend-friendly type we inferred from the backend ID
+     * (e.g., 'card', 'wallet', 'bank_transfer', 'cash_on_delivery')
+     */
+    normalizedType: string;
+}
+/**
+ * Extract backend provider ID from PaymentMethod
+ *
+ * Uses the `_backendMapping` metadata to retrieve the original
+ * backend-specific provider ID that should be sent to API calls.
+ *
+ * **Why this exists:**
+ * During transformation, we normalize backend IDs to friendly types:
+ * - Backend: 'pp_stripe_stripe' → Frontend: type 'card'
+ * - Backend: 'pp_system_default' → Frontend: type 'cash_on_delivery'
+ *
+ * But when making API calls, we need the ORIGINAL backend ID, not the type.
+ * This function extracts it from metadata.
+ *
+ * @param method - PaymentMethod with _backendMapping metadata
+ * @returns Backend provider ID (e.g., 'pp_stripe_stripe', 'pp_system_default')
+ * @throws {Error} If _backendMapping metadata is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * // PaymentMethod from backend with metadata
+ * const method = {
+ *   id: 'pp_system_default',
+ *   type: 'cash_on_delivery',
+ *   name: 'Cash on Delivery',
+ *   metadata: {
+ *     _backendMapping: {
+ *       backend: 'medusa',
+ *       originalId: 'pp_system_default',
+ *       normalizedType: 'cash_on_delivery'
+ *     }
+ *   }
+ * };
+ *
+ * const providerId = getBackendProviderId(method);
+ * // Returns: 'pp_system_default'
+ *
+ * // Now safe to use with backend API:
+ * await commerce.initiatePaymentSession(cartId, providerId);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handling missing metadata
+ * try {
+ *   const providerId = getBackendProviderId(methodWithoutMetadata);
+ * } catch (error) {
+ *   console.error('Payment method missing backend mapping:', error.message);
+ *   // Error: PaymentMethod 'stripe' is missing _backendMapping metadata.
+ *   // This is required to extract the backend provider ID.
+ * }
+ * ```
+ */
+declare function getBackendProviderId(method: PaymentMethod): string;
+/**
+ * Validate payment provider ID format
+ *
+ * Checks if the provider ID is a valid backend-specific identifier,
+ * not a normalized type like 'card', 'wallet', etc.
+ *
+ * **Why this exists:**
+ * Common bug: Accidentally sending normalized types to backend APIs:
+ * ❌ `initiatePaymentSession(cartId, 'card')` → Backend error
+ * ✅ `initiatePaymentSession(cartId, 'pp_stripe_stripe')` → Success
+ *
+ * This validation catches the bug at runtime with a helpful error message.
+ *
+ * @param id - Provider ID to validate
+ * @throws {Error} If ID appears to be a normalized type instead of backend ID
+ *
+ * @example
+ * ```typescript
+ * // Valid backend IDs - pass validation:
+ * validatePaymentId('pp_stripe_stripe');    // ✅ OK (Medusa)
+ * validatePaymentId('pp_system_default');   // ✅ OK (Medusa)
+ * validatePaymentId('shopify_payments');    // ✅ OK (Shopify)
+ * validatePaymentId('stripe');              // ✅ OK (WooCommerce)
+ * validatePaymentId('paypal_express');      // ✅ OK (generic)
+ *
+ * // Invalid (normalized types) - throw error:
+ * validatePaymentId('card');                // ❌ Throws error
+ * validatePaymentId('wallet');              // ❌ Throws error
+ * validatePaymentId('cash_on_delivery');    // ❌ Throws error
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use before API calls:
+ * async function initiatePayment(cartId: string, providerId: string) {
+ *   // Validate before sending to backend
+ *   validatePaymentId(providerId);
+ *
+ *   return await sdk.payment.initiatePaymentSession(cart, {
+ *     provider_id: providerId
+ *   });
+ * }
+ *
+ * // Catches bugs early:
+ * await initiatePayment(cartId, 'card');
+ * // ❌ Error: Invalid payment provider ID: 'card'.
+ * // This appears to be a normalized payment type, not a backend provider ID.
+ * // Use getBackendProviderId() to extract the correct backend ID from PaymentMethod.
+ * ```
+ */
+declare function validatePaymentId(id: string): void;
+
+/**
+ * Geolocation utilities
+ *
+ * Framework-agnostic helpers for proximity-based fulfillment.
+ */
+interface Coordinates {
+    lat: number;
+    lng: number;
+}
+/**
+ * Calculate distance between two coordinates using the Haversine formula.
+ * @returns Distance in kilometers
+ */
+declare function calculateDistance(from: Coordinates, to: Coordinates): number;
+/**
+ * Geocode an address to coordinates.
+ *
+ * This is intentionally a best-effort approximation (city + country lookup).
+ * For production-grade accuracy, integrate a real geocoding provider.
+ */
+declare function geocodeAddress(address: {
+    city?: string;
+    countryCode?: string;
+    postalCode?: string;
+}): Promise<Coordinates | null>;
+
+/**
+ * Fulfillment planner
+ *
+ * Plans an optimal fulfillment strategy for cart items given:
+ * - available stock locations
+ * - inventory levels per variant
+ * - an optional shipping address (for proximity sorting)
+ */
+
+interface FulfillmentGroup {
+    locationId: string;
+    locationName: string;
+    items: Array<{
+        variantId: string;
+        quantity: number;
+        productName: string;
+    }>;
+    shippingOptions: FulfillmentOption[];
+}
+interface FulfillmentPlan {
+    canFulfill: boolean;
+    groups: FulfillmentGroup[];
+    shippingAddress?: Coordinates;
+}
+interface PlanFulfillmentShippingAddress {
+    city?: string;
+    countryCode?: string;
+    postalCode?: string;
+}
+interface InventoryMap {
+    [variantId: string]: InventoryLevel[];
+}
+declare function planFulfillment(cartItems: CartItem[], stockLocations: StockLocation[], inventoryLevels: InventoryMap, shippingAddress?: PlanFulfillmentShippingAddress): Promise<FulfillmentPlan>;
+
+/**
+ * @thorprovider/adapters v2.0
+ * Medusa Provider - Transform functions
+ *
+ * These functions convert Medusa-specific types to our unified types
+ */
+
+declare function transformStockLocation(raw: any): StockLocation;
+declare function transformInventoryLevel(raw: any, locationName: string): InventoryLevel;
+declare function transformFulfillmentOption(shippingOption: any, location: StockLocation, currencyCode: string): FulfillmentOption;
+/**
+ * Transform backend `storefront_config` (snake_case) to `StorefrontConfig` (camelCase).
+ *
+ * Backend response shape:
+ * ```json
+ * {
+ *   "id": "sfc_01J...",
+ *   "sales_channel_id": "sc_01J...",
+ *   "theme_accent_color": "indigo",
+ *   "logo_url": "https://...",
+ *   "currency_code": "EUR",
+ *   "seo_defaults": { "title": "...", "description": "...", "ogImage": "..." },
+ *   "created_at": "...",
+ *   "updated_at": "..."
+ * }
+ * ```
+ */
+declare function transformStorefrontConfig(raw: any): StorefrontConfig;
+
+/**
+ * Admin Authentication Service
+ *
+ * Framework-agnostic authentication logic for admin dashboard.
+ * Uses bcryptjs for password hashing and jose for JWT operations.
+ *
+ * @remarks
+ * - L2: No Next.js imports, no env var access
+ * - Edge-compatible JWT via jose library
+ * - Password verification via bcryptjs
+ *
+ * @module admin/AdminAuthService
+ */
+/**
+ * Admin Auth Service
+ *
+ * Provides password verification and JWT management for admin authentication.
+ * All methods are framework-agnostic and can be used in any runtime.
+ */
+declare class AdminAuthService {
+    /**
+     * Verify password against bcrypt hash
+     *
+     * @param password - Plain text password from login form
+     * @param hash - Bcrypt hash stored in environment
+     * @returns true if password matches hash
+     */
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    /**
+     * Generate a bcrypt hash for a password
+     *
+     * @param password - Plain text password
+     * @param rounds - Bcrypt cost factor (default: 10)
+     * @returns Bcrypt hash string
+     */
+    hashPassword(password: string, rounds?: number): Promise<string>;
+    /**
+     * Generate JWT token (Edge-compatible via jose)
+     *
+     * @param payload - Token payload data
+     * @param secret - JWT secret string (min 32 chars recommended)
+     * @param expiresIn - Token expiration (default: '8h')
+     * @returns Signed JWT token string
+     */
+    generateJWT(payload: Record<string, unknown>, secret: string, expiresIn?: string): Promise<string>;
+    /**
+     * Verify JWT token (Edge-compatible via jose)
+     *
+     * @param token - JWT token string
+     * @param secret - JWT secret string
+     * @returns Decoded payload or null if invalid/expired
+     */
+    verifyJWT(token: string, secret: string): Promise<Record<string, unknown> | null>;
+}
+
+/**
+ * Admin Session Service
+ *
+ * Framework-agnostic session verification for admin routes.
+ * Extracts and verifies JWT tokens from HTTP requests.
+ *
+ * @remarks
+ * - L2: No Next.js imports, no env var access
+ * - Uses standard Request API (works in Edge, Node.js, etc.)
+ * - JWT secret injected via constructor (no env var reading)
+ *
+ * @module admin/AdminSessionService
+ */
+/**
+ * Admin Session payload decoded from JWT
+ */
+interface AdminSession {
+    /** Admin user identifier */
+    adminId: string;
+    /** Token type (always 'admin') */
+    type: 'admin';
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+}
+/**
+ * Admin Session Service
+ *
+ * Verifies admin sessions by extracting and validating JWT tokens
+ * from HTTP request cookies or Authorization headers.
+ */
+declare class AdminSessionService {
+    private jwtSecret;
+    private authService;
+    /**
+     * @param jwtSecret - JWT secret for token verification
+     */
+    constructor(jwtSecret: string);
+    /**
+     * Verify admin session from HTTP request
+     *
+     * Checks for JWT token in:
+     * 1. `admin_token` cookie
+     * 2. `Authorization: Bearer <token>` header
+     *
+     * @param request - Standard HTTP Request object
+     * @returns AdminSession if valid, null otherwise
+     */
+    verifySession(request: Request): Promise<AdminSession | null>;
+    /**
+     * Extract JWT token from request (cookie or Authorization header)
+     */
+    private extractToken;
+}
+
+/**
+ * Metrics Calculation Service
+ *
+ * Framework-agnostic business logic for calculating dashboard metrics
+ * from raw order and product data.
+ *
+ * @remarks
+ * - L2: Pure business logic, no framework dependencies
+ * - Works with @thorprovider/types Order and Product interfaces
+ * - Stateless static methods for easy testing
+ *
+ * @module admin/MetricsService
+ */
+
+/**
+ * Raw order data for metrics calculation
+ *
+ * @remarks
+ * Minimal interface to avoid coupling to specific Order type fields.
+ * Accepts the common fields available across all commerce providers.
+ */
+interface MetricsOrderInput {
+    total?: number;
+    status?: string;
+    created_at?: string;
+    createdAt?: string;
+}
+/**
+ * Raw product data for metrics calculation
+ */
+interface MetricsProductInput {
+    id: string;
+    variants?: Array<{
+        quantityAvailable?: number;
+    }>;
+}
+/**
+ * Metrics Service
+ *
+ * Calculates dashboard analytics from raw commerce data.
+ * All methods are static and pure (no side effects).
+ */
+declare class MetricsService {
+    /** Threshold for low stock alerts */
+    static readonly LOW_STOCK_THRESHOLD = 10;
+    /**
+     * Calculate complete dashboard metrics from orders and products
+     *
+     * @param orders - Array of order data
+     * @param products - Array of product data
+     * @returns Calculated DashboardMetrics
+     */
+    static calculate(orders: MetricsOrderInput[], products: MetricsProductInput[]): DashboardMetrics;
+    /**
+     * Generate chart data for the last 7 days
+     */
+    private static generateChartData;
+}
+
+/**
+ * Backend Metadata Adapter Interface
+ *
+ * Framework-agnostic interface for storing configuration in backend metadata fields.
+ * This replaces the need for a separate database (SQLite/Supabase).
+ *
+ * Each backend (Medusa, Shopify, WordPress) implements this interface
+ * using their native metadata/metafields/postmeta capabilities.
+ *
+ * @module backend/BackendMetadataAdapter
+ */
+/**
+ * Backend Metadata Adapter
+ *
+ * @remarks
+ * Supported resource types by backend:
+ * - Medusa: `'sales_channel'`, `'customer'`, `'order'` (via admin API)
+ * - Shopify: Uses metafields API (TBD)
+ * - WordPress: Uses post_meta or user_meta (TBD)
+ *
+ * Multi-tenant channel scoping:
+ * Use with `'customer'` / `'order'` resource types and the well-known key
+ * `'sales_channel_id'` to tag entities to a specific sales channel.
+ * See `@thorprovider/adapters/metadata/channel-scope` for helper utilities.
+ *
+ * @example
+ * ```typescript
+ * // Store site configuration in Medusa sales channel metadata
+ * await adapter.setMetadata(
+ *   'sales_channel',
+ *   'sc_01HXXX',
+ *   'site_config',
+ *   { version: '2026-03-25', config: {...} }
+ * );
+ *
+ * // Tag a customer to a sales channel (multi-tenant)
+ * await adapter.setMetadata(
+ *   'customer',
+ *   'cus_01HXXX',
+ *   'sales_channel_id',
+ *   'sc_01HXXX'
+ * );
+ * ```
+ */
+interface BackendMetadataAdapter {
+    /**
+     * Get metadata value from backend resource
+     *
+     * @param resourceType - Type of resource (`'sales_channel'` | `'customer'` | `'order'` | `'store'`)
+     * @param resourceId - ID of the resource
+     * @param key - Metadata key (e.g., `'site_config'`, `'sales_channel_id'`)
+     * @returns Metadata value or null if not found
+     */
+    getMetadata(resourceType: string, resourceId: string, key: string): Promise<any | null>;
+    /**
+     * Set metadata value on backend resource
+     *
+     * @param resourceType - Type of resource
+     * @param resourceId - ID of the resource
+     * @param key - Metadata key
+     * @param value - Metadata value (will be JSON serialized)
+     */
+    setMetadata(resourceType: string, resourceId: string, key: string, value: any): Promise<void>;
+    /**
+     * Delete metadata key from backend resource
+     *
+     * @param resourceType - Type of resource
+     * @param resourceId - ID of the resource
+     * @param key - Metadata key
+     */
+    deleteMetadata(resourceType: string, resourceId: string, key: string): Promise<void>;
+}
+
+/**
+ * Backend Metadata Adapter Factory
+ *
+ * Framework-agnostic factory to create backend metadata adapters for admin/dashboard.
+ * Keeps vendor-specific code in L2, prevents lock-in in L5.
+ *
+ * @remarks
+ * This factory is distinct from the main provider factory (createProvider).
+ * It's used for admin operations that require metadata/catalog access.
+ * Provider types are imported from @thorprovider/types (L1) to maintain sync.
+ *
+ * @module backend/factory
+ */
+
+/**
+ * Configuration for creating a backend metadata adapter
+ *
+ * @remarks
+ * Currently only 'medusa' is implemented. When adding Shopify/WooCommerce metadata adapters:
+ * 1. Uncomment the provider type in packages/types/src/provider.ts
+ * 2. Update this interface to accept the new provider type
+ * 3. Implement ShopifyMetadataAdapter, WooCommerceMetadataAdapter
+ * 4. Add cases to createBackendMetadataAdapter() switch
+ */
+interface BackendMetadataAdapterConfig {
+    /** Backend provider type (from @thorprovider/types L1) */
+    provider: ProviderTypeString;
+    /** Backend base URL */
+    baseUrl: string;
+    /** Publishable API key (for storefront access) */
+    publishableKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Secret admin API key (from COMMERCE_ADMIN_API_KEY).
+     * When provided, the metadata adapter SDK instance will send
+     * `x-medusa-access-token` header on all admin requests.
+     * Required for getMetadata/setMetadata to work after removing email/password auth.
+     */
+    adminApiKey?: string;
+}
+/**
+ * Create a backend metadata adapter (Factory Pattern)
+ *
+ * Keeps vendor-specific code in L2, prevents lock-in in L5.
+ * L5 only provides configuration from env vars.
+ *
+ * @param config - Adapter configuration
+ * @returns BackendMetadataAdapter instance
+ *
+ * @example
+ * ```typescript
+ * // In L5 (starters)
+ * import { createBackendMetadataAdapter } from '@thorprovider/adapters';
+ *
+ * export const metadataAdapter = createBackendMetadataAdapter({
+ *   provider: process.env.NEXT_PUBLIC_COMMERCE_PROVIDER as any,
+ *   baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
+ *   publishableKey: process.env.NEXT_PUBLIC_COMMERCE_API_KEY!,
+ * });
+ * ```
+ *
+ * @throws {Error} If provider is not supported
+ */
+declare function createBackendMetadataAdapter(config: BackendMetadataAdapterConfig): BackendMetadataAdapter;
+
+/**
+ * Medusa Metadata Adapter
+ *
+ * Implementation of BackendMetadataAdapter for Medusa.js v2.
+ * Uses Medusa's native metadata fields on sales_channel, customer, and order resources.
+ *
+ * Supported resource types:
+ * - `'sales_channel'` — site config, channel-level settings
+ * - `'customer'`       — multi-tenant scoping (`sales_channel_id` key)
+ * - `'order'`          — multi-tenant scoping (`sales_channel_id` key)
+ *
+ * All operations require admin-level JWT authentication.
+ *
+ * @module backend/medusa/MedusaMetadataAdapter
+ */
+
+/**
+ * Medusa Metadata Adapter
+ *
+ * @remarks
+ * - Supports 'sales_channel' and 'store' resource types
+ * - Uses Medusa admin API (requires admin token)
+ * - Metadata is stored as JSON in the metadata field
+ *
+ * @example
+ * ```typescript
+ * const adapter = new MedusaMetadataAdapter(medusaClient);
+ *
+ * // Store site configuration
+ * await adapter.setMetadata(
+ *   'sales_channel',
+ *   'sc_01HXXX',
+ *   'site_config',
+ *   { version: '2026-03-25', config: {...} }
+ * );
+ * ```
+ */
+declare class MedusaMetadataAdapter implements BackendMetadataAdapter {
+    private sdk;
+    constructor(sdk: Medusa);
+    /**
+     * Get metadata value from Medusa resource
+     */
+    getMetadata(resourceType: string, resourceId: string, key: string): Promise<any | null>;
+    /**
+     * Set metadata value on Medusa resource
+     */
+    setMetadata(resourceType: string, resourceId: string, key: string, value: any): Promise<void>;
+    /**
+     * Delete metadata key from Medusa resource
+     *
+     * @remarks
+     * Medusa deletes metadata keys by setting them to undefined or null
+     */
+    deleteMetadata(resourceType: string, resourceId: string, key: string): Promise<void>;
+}
+
+/**
+ * Channel Scope — Backend-Agnostic Multi-Tenant Helpers
+ *
+ * Provides utilities for tagging, reading and filtering entity metadata by
+ * sales-channel (or any future tenant key). Works with any backend that
+ * exposes a writable `metadata: Record<string, unknown>` field on its
+ * entities (Medusa, Shopify metafields, WooCommerce meta, etc.).
+ *
+ * ## Design decisions
+ *
+ * | Decision | Rationale |
+ * |----------|-----------|
+ * | Flat key (`sales_channel_id`) | Simpler queries, no prefix parsing required |
+ * | Metadata, not custom fields | Zero DB migrations; works across backends |
+ * | Pure functions | No side effects → easily testable; usable in any layer |
+ * | `assigned_at` timestamp | Audit trail for dropshipper / admin assignment |
+ *
+ * @module metadata/channel-scope
+ */
+/**
+ * Well-known metadata key used to store the owning sales-channel on any
+ * entity that Medusa (or the backend) does not natively scope.
+ *
+ * Convention: every entity whose metadata contains this key is
+ * considered "owned" by the referenced channel. Entities without it
+ * are global / unscoped.
+ */
+declare const CHANNEL_SCOPE_KEY: "sales_channel_id";
+/**
+ * Optional audit key — ISO-8601 timestamp of when the channel was assigned.
+ */
+declare const CHANNEL_ASSIGNED_AT_KEY: "channel_assigned_at";
+/**
+ * Optional audit key — who assigned the entity to the channel.
+ * Value is a free-form string (admin email, user id, "system", etc.).
+ */
+declare const CHANNEL_ASSIGNED_BY_KEY: "channel_assigned_by";
+/**
+ * Minimal shape any entity must satisfy in order to participate in
+ * channel-scope filtering.  Compatible with @thorprovider/types Customer,
+ * Order, ProductCategory, etc.
+ */
+interface ChannelScopeable {
+    id: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Payload produced by `buildChannelScopeMetadata()`.
+ * Can be spread directly into an `updateCustomer` / `updateOrder` call.
+ */
+interface ChannelScopeMetadata {
+    [CHANNEL_SCOPE_KEY]: string;
+    [CHANNEL_ASSIGNED_AT_KEY]: string;
+    [CHANNEL_ASSIGNED_BY_KEY]?: string;
+}
+/**
+ * Build channel-scope metadata payload.
+ *
+ * The returned object should be **merged** into the entity's existing
+ * `metadata` field when calling `updateCustomer`, `updateOrder`, etc.
+ *
+ * @param channelId  - Sales-channel ID (e.g. `"sc_01HXXX"`)
+ * @param assignedBy - Optional identifier of who performed the assignment
+ * @returns Metadata fragment ready to spread into an update payload
+ *
+ * @example
+ * ```typescript
+ * const scope = buildChannelScopeMetadata('sc_01HXXX', 'admin@store.com');
+ * await commerce.updateCustomer(customerId, {
+ *   metadata: { ...existingMeta, ...scope },
+ * });
+ * ```
+ */
+declare function buildChannelScopeMetadata(channelId: string, assignedBy?: string): ChannelScopeMetadata;
+/**
+ * Read the channel-scope value from an entity's metadata.
+ *
+ * @returns The channel ID string, or `null` if the entity has no scope set.
+ */
+declare function getChannelScope(entity: ChannelScopeable): string | null;
+/**
+ * Check if an entity is scoped to a specific channel.
+ *
+ * @param entity    - Any entity with optional `metadata`
+ * @param channelId - Channel ID to match against
+ * @returns `true` if entity's metadata contains a matching scope key
+ */
+declare function isScopedToChannel(entity: ChannelScopeable, channelId: string): boolean;
+/**
+ * Check if an entity has **no** channel scope (i.e. it is "global").
+ */
+declare function isGlobalEntity(entity: ChannelScopeable): boolean;
+/**
+ * Filter an array of entities to only those belonging to a channel.
+ *
+ * If `channelId` is `undefined` or empty, returns the full array unfiltered.
+ * This preserves backward compatibility for admin views that intentionally
+ * list all entities regardless of tenant.
+ *
+ * @param entities  - Array of channel-scopeable entities
+ * @param channelId - Optional channel ID to filter by
+ * @returns Filtered (or unfiltered) array
+ *
+ * @example
+ * ```typescript
+ * const allCustomers = await commerce.getCustomers();
+ * const myCustomers = filterByChannel(allCustomers, salesChannelId);
+ * ```
+ */
+declare function filterByChannel<T extends ChannelScopeable>(entities: T[], channelId?: string): T[];
+/**
+ * Filter an array of entities to only those that are global (unscoped).
+ *
+ * Useful for admin views that want to list entities not yet assigned to
+ * any channel.
+ */
+declare function filterGlobalOnly<T extends ChannelScopeable>(entities: T[]): T[];
+/**
+ * Partition entities into `{ scoped, global }` groups.
+ *
+ * @param entities  - Array of channel-scopeable entities
+ * @param channelId - Channel ID to partition against
+ * @returns Object with `scoped` (matching channel) and `global` (no scope) arrays
+ *
+ * @example
+ * ```typescript
+ * const { scoped, global } = partitionByChannel(customers, 'sc_123');
+ * // scoped → customers assigned to sc_123
+ * // global → customers not assigned to any channel
+ * ```
+ */
+declare function partitionByChannel<T extends ChannelScopeable>(entities: T[], channelId: string): {
+    scoped: T[];
+    global: T[];
+};
+
+/**
+ * Channel Scope Validation — Pure TypeScript (no external deps)
+ *
+ * Validates channel-scope metadata before it is written to the backend.
+ * Keeps all validation logic in L2 so that L5 starters don't duplicate checks.
+ *
+ * @module metadata/channel-scope-validation
+ */
+
+/**
+ * Thrown when channel-scope validation fails.
+ *
+ * Consumers can catch this specific type to provide user-friendly feedback
+ * without leaking internal details.
+ */
+declare class ChannelScopeValidationError extends Error {
+    readonly field: string;
+    readonly value: unknown;
+    constructor(message: string, field: string, value?: unknown);
+}
+/**
+ * Validate that a channel ID is a non-empty string.
+ *
+ * Does **not** enforce a specific prefix (e.g. `"sc_"`) because different
+ * backends use different conventions:
+ * - Medusa: `"sc_01HXXX"`
+ * - Shopify: `"gid://shopify/Channel/789"`
+ * - WooCommerce: `"1"` (numeric string)
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+declare function validateChannelId(channelId: unknown): asserts channelId is string;
+/**
+ * Validate that an entity ID is a non-empty string.
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+declare function validateEntityId(entityId: unknown, label?: string): asserts entityId is string;
+/**
+ * Validate that the `assignedBy` value (if provided) is a reasonable string.
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+declare function validateAssignedBy(assignedBy: unknown): asserts assignedBy is string | undefined;
+/**
+ * Full validation for a channel-scope assignment operation.
+ *
+ * Call before writing channel scope metadata to any entity.
+ *
+ * @throws {ChannelScopeValidationError} with descriptive field + value
+ *
+ * @example
+ * ```typescript
+ * validateChannelScopeAssignment('cus_123', 'sc_01HXXX', 'admin@store.com');
+ * // If no error, safe to proceed
+ * ```
+ */
+declare function validateChannelScopeAssignment(entityId: string, channelId: string, assignedBy?: string): void;
+/**
+ * Validate that an entity is currently scoped to the expected channel.
+ *
+ * Useful as a guard before performing operations that should only
+ * affect entities within the caller's channel (e.g. a dropshipper editing
+ * a customer that must belong to their channel).
+ *
+ * @throws {ChannelScopeValidationError} if entity does not belong to expectedChannelId
+ */
+declare function assertEntityBelongsToChannel(entity: ChannelScopeable, expectedChannelId: string): void;
+
+/**
+ * Medusa provider configuration
+ */
+interface MedusaProviderConfig extends ProviderConfig {
+    /**
+     * Medusa backend URL
+     */
+    baseUrl: string;
+    /**
+     * Publishable API key (for storefront access)
+     */
+    publishableKey: string;
+    /**
+     * Default currency code (default: USD)
+     */
+    /**
+     * Default currency code (default: USD)
+     */
+    currencyCode?: string;
+    /**
+     * Region ID (optional, will use default region if not provided)
+     */
+    regionId?: string;
+    /**
+     * Authentication configuration (optional)
+     * If not provided, auth methods will not be available
+     */
+    auth?: AuthConfig;
+    /**
+     * Retry configuration for fetch requests (optional)
+     * Configure automatic retries, timeouts, and backoff strategy
+     *
+     * @example
+     * ```typescript
+     * {
+     *   maxRetries: 3,        // Retry up to 3 times
+     *   timeoutMs: 10000,     // 10 second timeout per request
+     *   initialDelayMs: 300,  // Start with 300ms delay
+     * }
+     * ```
+     */
+    retry?: RetryConfig;
+    /**
+     * Admin API configuration (optional).
+     * Required for inventory operations (stock locations, inventory levels).
+     * When not provided, admin-only methods will throw with a descriptive error.
+     */
+    adminConfig?: {
+        /**
+         * Secret API key created in Medusa Admin → Settings → API Keys → Secret.
+         * Sent as `x-medusa-access-token` on every request of the dedicated admin SDK instance.
+         * Never use a Publishable key here.
+         */
+        apiKey: string;
+    };
+}
+/**
+ * Medusa commerce provider
+ *
+ * Implements CommerceProvider interface for Medusa.js v2
+ */
+declare class MedusaProvider implements CommerceProvider {
+    readonly name = "medusa";
+    readonly version = "2.0.0";
+    /**
+     * Medusa backend capabilities.
+     * Starts with static defaults, replaced by dynamic values from
+     * `GET /store/thor/capabilities` once the fetch completes.
+     */
+    private _dynamicCapabilities;
+    /** Promise that resolves when capabilities fetch completes (success or failure) */
+    private _capabilitiesPromise;
+    /**
+     * Getter returns dynamic capabilities if available, otherwise static fallback.
+     */
+    get capabilities(): BackendCapabilities;
+    private sdk;
+    private logger;
+    private currencyCode;
+    private retryConfig;
+    private baseUrl;
+    private publishableKey;
+    /** Secret API key for admin operations (if configured). */
+    private adminApiKey?;
+    /**
+     * Dedicated SDK instance for admin calls.
+     * Separate from `this.sdk` to prevent the admin API key from being overwritten
+     * by customer JWT tokens set during storefront authentication.
+     * Only created when adminConfig.apiKey is provided.
+     */
+    private sdkAdmin?;
+    /** Cached distinct product status values — rarely changes, cached for process lifetime */
+    private _cachedProductStatuses;
+    /**
+     * In-memory cache for region countries
+     * Structure: Map<regionId, { countries: Country[], expiresAt: number }>
+     */
+    private regionCountriesCache;
+    /**
+     * Cache TTL for region countries (5 minutes)
+     */
+    private readonly REGION_COUNTRIES_CACHE_TTL;
+    /**
+     * In-memory cache for storefront context (60 second TTL)
+     */
+    private storefrontContextCache;
+    /**
+     * Cache TTL for storefront context (60 seconds)
+     */
+    private readonly STOREFRONT_CONTEXT_CACHE_TTL;
+    /**
+     * Authentication provider (available if auth config is provided)
+     */
+    readonly auth?: AuthProvider;
+    private retrieveCartWithLineDetails;
+    constructor(config: MedusaProviderConfig);
+    /**
+     * Fetch capabilities dynamically from `GET /store/thor/capabilities`.
+     * Non-blocking — called in constructor. On failure, static fallback is used.
+     * Cache: process-lifetime (per provider instance).
+     */
+    private _fetchCapabilities;
+    /**
+     * Wrapper for SDK calls with retry logic
+     * Handles network failures and temporary backend issues
+     */
+    private withRetry;
+    getProduct(handle: string, options?: {
+        regionId?: string;
+    }): Promise<Product | undefined>;
+    getProducts(options?: GetProductsOptions & {
+        regionId?: string;
+    }): Promise<Product[]>;
+    getProductRecommendations(productId: string): Promise<Product[]>;
+    /**
+     * Advanced product search using /store/search endpoint
+     *
+     * Uses hybrid MeiliSearch + Qdrant search with advanced filtering:
+     * - Price range filtering
+     * - Stock availability
+     * - Custom product attributes
+     *
+     * Falls back to getProducts() if advanced search fails
+     */
+    searchProductsAdvanced(options?: AdvancedSearchProductsOptions): Promise<{
+        products: Product[];
+        meta?: SearchResultMeta;
+    }>;
+    /**
+     * Get available filter options for product filtering
+     *
+     * Aggregates filters from:
+     * - Basic filters: categories, collections (always available)
+     * - Advanced filters: price range, stock (if useAdvancedSearch=true)
+     * - Custom attributes: category-specific attributes from backend
+     *
+     * Returns empty array if backend doesn't support dynamic filters
+     */
+    getAvailableFilters(options: {
+        categoryId?: string;
+        useAdvancedSearch?: boolean;
+        includeBasicFilters?: boolean;
+        includeFacetCounts?: boolean;
+    }): Promise<FilterConfig[]>;
+    /**
+     * Convert a human-readable string to a URL-safe slug.
+     * Used to produce SEO-friendly filter values (option.value) that go into the URL.
+     *
+     * Examples:
+     *   "8GB RAM"   → "8gb-ram"
+     *   "Red Color" → "red-color"
+     *   "16 GB"     → "16-gb"
+     */
+    private toSlug;
+    /**
+     * Map backend attribute type to filter type
+     */
+    private mapAttributeTypeToFilterType;
+    getCollection(handle: string): Promise<Collection | undefined>;
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    getCategory(idOrHandle: string): Promise<ProductCategory | undefined>;
+    /**
+     * Returns the set of product-category IDs that have at least one product
+     * available in the given sales channel.
+     *
+     * Because Medusa's store/product-categories endpoint does not accept a
+     * `sales_channel_id` filter, we derive the active category IDs by querying
+     * store/products with the sales-channel scope and collecting the category
+     * relations from the response. Pagination is handled internally so the
+     * result is always complete regardless of catalog size.
+     *
+     * @deprecated Use `_getChannelCategories()` instead (backed by Thor Commerce plugin).
+     * Kept as fallback for backends without the plugin installed.
+     */
+    private _getActiveCategoryIds;
+    /**
+     * Fetch channel-scoped categories from Thor Commerce plugin.
+     * Uses `GET /store/thor/categories` — a single indexed query.
+     * Falls back to `_getActiveCategoryIds()` if the plugin is not available.
+     */
+    private _getChannelCategories;
+    getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]>;
+    getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    createCart(options?: {
+        regionId?: string;
+    }): Promise<Cart>;
+    getCart(cartId: string): Promise<Cart | undefined>;
+    addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    removeFromCart(cartId: string, lineIds: string[]): Promise<Cart>;
+    updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    /**
+     * Get available regions from Medusa
+     * Returns region information including id, name, and currency
+     */
+    getRegions(): Promise<Array<{
+        id: string;
+        name: string;
+        currency_code: string;
+        countries?: Array<{
+            id: string;
+            iso_2: string;
+            name: string;
+            display_name?: string;
+        }>;
+    }>>;
+    /**
+     * Get all orders for a customer (storefront).
+     *
+     * Note: This retrieves orders from the storefront API (store.order.list),
+     * which returns orders only for the authenticated customer in the JWT.
+     *
+     * @param options - Order query options (supports callbacks for custom backends)
+     * @returns Array of orders for the authenticated customer
+     *
+     * @example
+     * ```typescript
+     * const orders = await provider.getOrders();
+     * console.log(`Found ${orders.length} orders`);
+     * ```
+     */
+    getOrders(options?: GetOrdersOptions): Promise<Order[]>;
+    /**
+     * Get a single order by ID
+     *
+     * @param orderId - Order ID
+     * @returns Order or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const order = await provider.getOrder('order_123');
+     * if (order) {
+     *   console.log(`Order ${order.orderNumber} - ${order.status}`);
+     * }
+     * ```
+     */
+    getOrder(orderId: string): Promise<Order | undefined>;
+    /**
+     * List customers with optional filtering and pagination.
+     *
+     * Uses the Medusa admin API — requires admin-level JWT.
+     *
+     * @param options - Query options (search, sort, pagination)
+     * @returns Array of customers
+     *
+     * @example
+     * ```typescript
+     * const customers = await provider.getCustomers({ search: 'john', limit: 20, offset: 0 });
+     * ```
+     */
+    getCustomers(options?: GetCustomersOptions): Promise<Customer[]>;
+    /**
+     * Get a single customer by ID.
+     *
+     * Uses the Medusa admin API.
+     *
+     * @param customerId - Customer ID
+     * @returns Customer or undefined if not found
+     */
+    getCustomer(customerId: string): Promise<Customer | undefined>;
+    /**
+     * Update customer information.
+     *
+     * Uses the Medusa admin API.
+     *
+     * @param customerId - Customer ID
+     * @param data - Fields to update
+     * @returns Updated customer
+     */
+    updateCustomer(customerId: string, data: Partial<Omit<Customer, 'id' | 'createdAt'>>): Promise<Customer>;
+    /**
+     * Get orders placed by a specific customer (admin view).
+     *
+     * @param customerId - Customer ID
+     * @param limit - Max number of orders (default: 10)
+     * @returns Array of orders
+     */
+    getCustomerOrders(customerId: string, limit?: number): Promise<Order[]>;
+    /**
+     * List customers for admin dashboard.
+     *
+     * Uses makeAdminRequest() to ensure proper admin authentication.
+     * Unlike getCustomers() (which currently lacks admin auth), this method
+     * properly awaits admin initialization and authenticates via SDK admin session.
+     *
+     * Gracefully degrades to empty result when adminConfig is not provided.
+     *
+     * @param options - Query options (search, limit, offset, salesChannelId)
+     * @returns Object with customers array and count
+     */
+    getAdminCustomers(options?: {
+        search?: string;
+        limit?: number;
+        offset?: number;
+        salesChannelId?: string;
+    }): Promise<{
+        customers: Customer[];
+        count: number;
+    }>;
+    /**
+     * Get a single customer by ID for admin dashboard.
+     *
+     * Uses makeAdminRequest() for proper admin authentication.
+     * Returns undefined (not an error) when the customer is not found (404).
+     *
+     * @param customerId - Customer ID
+     * @returns Customer or undefined if not found
+     */
+    getAdminCustomer(customerId: string): Promise<Customer | undefined>;
+    /**
+     * Get all addresses for a customer (admin operation).
+     * Uses sdk.admin.customer.listAddresses() for proper admin authentication.
+     *
+     * @param customerId - The customer's ID
+     * @returns Array of addresses
+     */
+    getAdminCustomerAddresses(customerId: string): Promise<Address[]>;
+    /**
+     * Get all orders for admin dashboard listing.
+     *
+     * Unlike getCustomerOrders() (which filters by a specific customerId via
+     * sdk.admin.order.list with storefront JWT), this method:
+     * - Lists ALL orders across the store
+     * - Uses fetchAdminAPI() with proper admin credentials
+     * - Applies multi-tenant channel scoping via filterByChannel()
+     * - Gracefully degrades to empty result when adminConfig is not provided
+     *
+     * IMPORTANT: Do NOT use sdk.admin.order.list() here — it uses storefront
+     * JWT auth which is insufficient for Medusa Admin API.
+     */
+    getAdminOrders(options?: {
+        search?: string;
+        status?: string | string[];
+        limit?: number;
+        offset?: number;
+        /** Medusa field name for sorting, e.g. 'created_at', 'total' */
+        order?: string;
+        direction?: 'asc' | 'desc';
+        /** Filter by sales channel — uses Medusa native `sales_channel_id` query. */
+        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 and do NOT appear
+         * in GET /admin/orders.
+         */
+        includeDrafts?: boolean;
+    }): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    /**
+     * Cancel an order (admin operation).
+     * Uses sdk.admin.order.cancel() for proper SDK integration.
+     * Throws ProviderAPIError if adminConfig is not provided.
+     */
+    cancelOrder(orderId: string): Promise<Order>;
+    /**
+     * Create a fulfillment for an order (admin operation).
+     * Uses sdk.admin.order.createFulfillment() for proper SDK integration.
+     * Throws ProviderAPIError if adminConfig is not provided.
+     *
+     * @param items - Optional specific line-items + quantities.
+     *                When omitted, Medusa fulfills all unfulfilled items.
+     */
+    createFulfillment(orderId: string, items?: Array<{
+        id: string;
+        quantity: number;
+    }>): Promise<void>;
+    /**
+     * Create a refund for an order (admin operation).
+     *
+     * Uses fetchAdminAPI() — NOT sdk.admin.refund.create().
+     * Throws ProviderAPIError if adminConfig is not provided.
+     *
+     * @param amount - Amount in cents. Omit to refund the full order total.
+     * @param reason - Reason string (default: 'admin_refund').
+     */
+    createRefund(orderId: string, amount?: number, reason?: string): Promise<void>;
+    /**
+     * List all regions for admin dashboard (used in Create Order dialog).
+     *
+     * Returns Region[] compatible with CommerceProvider contract.
+     * Maps Medusa's currency_code → currency and provides empty countryCodes array
+     * when country detail is not required for the admin region picker.
+     */
+    getAdminRegions(): Promise<Region[]>;
+    /**
+     * Get a single order by ID for admin dashboard detail view.
+     *
+     * Uses makeAdminRequest() for proper admin authentication.
+     * Returns full order with items, addresses, customer.
+     *
+     * @returns Order or undefined if not found
+     */
+    getAdminOrder(orderId: string): Promise<Order | undefined>;
+    /**
+     * Get a single product by ID for admin dashboard detail view.
+     *
+     * Uses makeAdminRequest() for proper admin authentication.
+     * Returns full product with variants and prices.
+     *
+     * @returns AdminProduct or undefined if not found
+     */
+    getAdminProduct(productId: string): Promise<AdminProduct | undefined>;
+    /**
+     * Create a draft order.
+     *
+     * Uses Medusa v2 `sdk.admin.draftOrder.create()` API.
+     * Draft orders have `is_draft_order = true` and can be converted to regular orders.
+     *
+     * @param params - Draft order parameters
+     * @returns Created draft order as a transformed Order
+     */
+    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>;
+    /**
+     * Convert a draft order into a regular (pending) order.
+     *
+     * Uses `sdk.admin.draftOrder.convertToOrder()` which maps to
+     * `POST /admin/draft-orders/{id}/convert-to-order`.
+     * Returns the newly created order transformed into `@thorprovider/types.Order`.
+     */
+    undraftOrder(draftOrderId: string): Promise<Order>;
+    /**
+     * Assign a customer to a sales channel via metadata.
+     *
+     * This is the primary mechanism for multi-tenant isolation of entities
+     * that the backend does not natively scope to a sales channel
+     * (e.g. customers in Medusa).
+     *
+     * Writes `sales_channel_id` + audit fields into `customer.metadata`.
+     * After assignment, `getCustomers({ salesChannelId })` will include
+     * this customer in its results.
+     *
+     * @param customerId  - Customer to assign
+     * @param channelId   - Target sales channel
+     * @param assignedBy  - Optional: who triggered the assignment
+     * @returns Updated customer with new metadata
+     *
+     * @example
+     * ```typescript
+     * // Dropshipper creates customer → assign to their channel
+     * const customer = await commerce.assignCustomerToChannel(
+     *   'cus_01HXXX',
+     *   process.env.NEXT_PUBLIC_SALES_CHANNEL_ID!,
+     *   'admin@mystore.com',
+     * );
+     * ```
+     */
+    assignCustomerToChannel(customerId: string, channelId: string, assignedBy?: string): Promise<Customer>;
+    /**
+     * Assign an order to a sales channel via metadata.
+     *
+     * Same pattern as `assignCustomerToChannel` but for orders.
+     * Useful when orders are created through flows that don't automatically
+     * link them to a channel.
+     *
+     * @param orderId    - Order to assign
+     * @param channelId  - Target sales channel
+     * @param assignedBy - Optional: who triggered the assignment
+     */
+    assignOrderToChannel(orderId: string, channelId: string, assignedBy?: string): Promise<void>;
+    /**
+     * Get available payment methods
+     *
+     * Queries Medusa for payment providers available in a specific region.
+     * Region is determined either from options.regionId or from the cart.
+     *
+     * @param options - Payment methods query options (regionId or cartId required)
+     * @returns Array of available payment methods
+     *
+     * @example
+     * ```typescript
+     * // Get payment methods for a region
+     * const methods = await provider.getPaymentMethods({
+     *   regionId: 'reg_123',
+     *   enabledOnly: true
+     * });
+     *
+     * // Get payment methods for a cart
+     * const methods = await provider.getPaymentMethods({
+     *   cartId: 'cart_123'
+     * });
+     * ```
+     */
+    getPaymentMethods(options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    /**
+     * Complete checkout and create order from cart
+     *
+     * Finalizes the checkout process and converts the cart into an order.
+     * Cart must have shipping address, shipping method, and payment session.
+     *
+     * @param cartId - Cart ID to checkout
+     * @returns Created order
+     * @throws {ProviderAPIError} If checkout fails
+     */
+    completeCheckout(cartId: string): Promise<Order>;
+    /**
+     * Get available shipping methods for cart
+     *
+     * Fetches shipping options based on cart region and shipping address.
+     *
+     * @param cartId - Cart ID
+     * @returns List of shipping methods with prices
+     * @throws {ProviderAPIError} If cart not found or region not configured
+     */
+    getShippingMethods(cartId: string): Promise<_thorprovider_types.ShippingMethod[]>;
+    /**
+     * Check if admin API is configured
+     */
+    private get isAdminConfigured();
+    /**
+     * Ensure admin is configured.
+     * Synchronous check — API key auth has no async initialization.
+     * @throws ProviderAPIError if admin configuration is missing
+     */
+    private ensureAdminConfigured;
+    /**
+     * Make an authenticated request to the Medusa Admin API via SDK
+     * SDK automatically includes Bearer token in all admin requests
+     * Awaits auth initialization before executing the operation
+     */
+    private makeAdminRequest;
+    /**
+     * Fetch stock locations, optionally filtered by sales channel.
+     * Returns empty array when admin config is not provided (graceful degradation).
+     */
+    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).
+     */
+    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).
+     */
+    validateCartStock(cartId: string): Promise<StockValidation>;
+    /**
+     * Get fulfillment options enriched with stock location data.
+     * Not yet implemented — requires fulfillment planning + Admin inventory.
+     */
+    getFulfillmentOptions(cartId: string, salesChannelId: string): Promise<FulfillmentOption[]>;
+    /**
+     * Get a map of product IDs → admin status ('published' | 'draft' | etc.)
+     * Returns {} when admin config is not provided (graceful degradation).
+     */
+    getAdminProductStatuses(options?: {
+        limit?: number;
+    }): Promise<Record<string, string>>;
+    /**
+     * Get the distinct product status values available in Medusa.
+     * Derives values from getAdminProductStatuses and caches them for the process lifetime.
+     * Returns [] when admin credentials are not configured.
+     */
+    getAvailableProductStatuses(): Promise<string[]>;
+    /**
+     * List ALL products from the admin API (including non-published).
+     * Returns real backend status values and variant-level price/inventory data.
+     * Gracefully degrades to empty result when admin credentials are not configured.
+     */
+    getAdminProducts(options?: {
+        query?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        products: AdminProduct[];
+        count: number;
+    }>;
+    /**
+     * Get available countries for a region
+     *
+     * Returns list of countries that can be used for shipping addresses
+     * in the specified region. Results are cached for 5 minutes.
+     *
+     * @param regionId - Region ID
+     * @returns Array of countries with codes and names
+     * @throws {ProviderAPIError} If region not found or API error
+     *
+     * @example
+     * ```typescript
+     * const countries = await medusa.getRegionCountries('reg_01KHCJQ5YXYRWWCKSTYQ4SCM8V');
+     * // [{ code: 'ES', name: 'Spain' }, { code: 'FR', name: 'France' }, ...]
+     * ```
+     */
+    getRegionCountries(regionId: string): Promise<_thorprovider_types.Country[]>;
+    /**
+     * Add shipping method to cart
+     *
+     * Applies a shipping method to the cart and updates totals.
+     *
+     * @param cartId - Cart ID
+     * @param methodId - Shipping method ID (from getShippingMethods)
+     * @returns Updated cart with shipping
+     * @throws {ProviderAPIError} If method invalid or cart not ready
+     */
+    addShippingMethod(cartId: string, methodId: string): Promise<Cart>;
+    /**
+     * Initiate payment session with provider
+     *
+     * Creates a payment session for the cart with the specified provider.
+     *
+     * @param cartId - Cart ID
+     * @param providerId - Payment provider ID (from getPaymentMethods)
+     * @throws {ProviderAPIError} If provider invalid or cart not ready
+     */
+    initiatePaymentSession(cartId: string, providerId: string): Promise<void>;
+    /**
+     * Apply discount code to cart
+     *
+     * Validates and applies a discount/promo code to the cart.
+     *
+     * @param cartId - Cart ID
+     * @param code - Discount code
+     * @returns Updated cart with discount
+     * @throws {ProviderAPIError} If code invalid or expired
+     */
+    applyDiscountCode(cartId: string, code: string): Promise<Cart>;
+    /**
+     * Remove discount code from cart
+     *
+     * Removes a previously applied discount code.
+     *
+     * @param cartId - Cart ID
+     * @param code - Discount code to remove
+     * @returns Updated cart without discount
+     * @throws {ProviderAPIError} If cart not found
+     */
+    removeDiscountCode(cartId: string, code: string): Promise<Cart>;
+    /**
+     * Update cart shipping address
+     * @param cartId - Cart ID
+     * @param address - Shipping address details
+     * @returns Updated cart
+     *
+     * **CRITICAL**: Must be called BEFORE initiatePaymentSession
+     * Medusa requires shipping_address on cart before creating payment session
+     */
+    updateShippingAddress(cartId: string, address: {
+        email: string;
+        firstName: string;
+        lastName: string;
+        address1: string;
+        address2?: string;
+        company?: string;
+        city: string;
+        province: string;
+        postalCode: string;
+        countryCode: string;
+        phone: string;
+    }): Promise<void>;
+    /**
+     * Update cart billing address
+     * @param cartId - Cart ID
+     * @param address - Billing address details
+     * @returns Updated cart
+     *
+     * **Usage**: Call when billing address differs from shipping address
+     * Recommended to call BEFORE initiatePaymentSession
+     */
+    updateBillingAddress(cartId: string, address: {
+        firstName: string;
+        lastName: string;
+        address1: string;
+        address2?: string;
+        company?: string;
+        city: string;
+        province: string;
+        postalCode: string;
+        countryCode: string;
+        phone?: string;
+    }): Promise<Cart>;
+    /**
+     * Get the current storefront/sales channel context.
+     *
+     * Validates that NEXT_PUBLIC_SALES_CHANNEL_ID is set and that the
+     * corresponding sales channel exists in the Medusa backend.
+     * Results are cached for 60 seconds.
+     *
+     * @returns StorefrontContext for the current storefront
+     * @throws {StorefrontConfigError} if NEXT_PUBLIC_SALES_CHANNEL_ID is missing or invalid
+     * @throws {ProviderAPIError} if the backend request fails
+     */
+    getStorefrontContext(): Promise<StorefrontContext>;
+    /**
+     * Medusa always requires storefront configuration for multi-tenant support.
+     */
+    isStorefrontRequired(): boolean;
+    /** In-memory cache for storefront config (60s TTL) */
+    private _storefrontConfigCache;
+    /** In-memory cache for designer config (60s TTL) */
+    private _designerConfigCache;
+    /** Cache TTL for Thor plugin configs (60 seconds) */
+    private readonly THOR_CONFIG_CACHE_TTL;
+    /**
+     * Get per-channel storefront configuration from Thor Commerce plugin.
+     * Calls `GET /store/thor/config`.
+     *
+     * @returns StorefrontConfig or null if plugin is not installed / config not set
+     */
+    getStorefrontConfig(): Promise<StorefrontConfig | null>;
+    /**
+     * Get active Site Designer configuration from Thor Commerce plugin.
+     * Calls `GET /store/thor/site-config`.
+     *
+     * @returns Versioned DesignerConfig or null if plugin is not installed / config not set
+     */
+    getDesignerConfig(): Promise<{
+        version: string;
+        config: DesignerConfig;
+    } | null>;
+    /**
+     * Get admin Site Designer config + history for a sales channel.
+     * Calls `GET /admin/thor/site-config/:salesChannelId`.
+     */
+    getAdminDesignerConfig(salesChannelId: string): Promise<{
+        version: string;
+        config: DesignerConfig;
+        history?: DesignerHistoryEntry[];
+    } | null>;
+    /**
+     * Update the Site Designer config for a sales channel.
+     * Calls `PUT /admin/thor/site-config/:salesChannelId`.
+     */
+    updateAdminDesignerConfig(salesChannelId: string, config: DesignerConfig): Promise<{
+        version: string;
+        config: DesignerConfig;
+    }>;
+    /**
+     * Restore a previous Site Designer config version.
+     * Calls `POST /admin/thor/site-config/:salesChannelId/restore/:version`.
+     */
+    restoreAdminDesignerConfig(salesChannelId: string, version: string): Promise<{
+        version: string;
+        config: DesignerConfig;
+    }>;
+}
+
+/**
+ * Shopify provider configuration
+ */
+interface ShopifyProviderConfig extends ProviderConfig {
+    /** Store domain (e.g., 'your-store.myshopify.com') */
+    storeDomain: string;
+    /** Public Storefront API access token */
+    publicAccessToken: string;
+    /** Private Storefront API access token (server-side only) */
+    privateAccessToken?: string;
+    /** API version (default: '2026-04') */
+    apiVersion?: string;
+}
+/**
+ * Shopify commerce provider
+ *
+ * Implements CommerceProvider for Shopify Storefront API.
+ * Uses raw fetch + GraphQL queries (no SDK dependency to stay L2-pure).
+ */
+declare class ShopifyProvider implements CommerceProvider {
+    readonly name = "shopify";
+    readonly version = "1.0.0";
+    readonly capabilities: BackendCapabilities;
+    private logger;
+    private storeDomain;
+    private apiVersion;
+    private endpoint;
+    private headers;
+    constructor(config: ShopifyProviderConfig);
+    private query;
+    getProduct(handle: string): Promise<Product | undefined>;
+    getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    getProductRecommendations(productId: string): Promise<Product[]>;
+    getCollection(handle: string): Promise<Collection | undefined>;
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    getCategory(): Promise<ProductCategory | undefined>;
+    getCategories(): Promise<ProductCategory[]>;
+    getCategoryProducts(): Promise<Product[]>;
+    createCart(): Promise<Cart>;
+    getCart(cartId: string): Promise<Cart | undefined>;
+    addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    removeFromCart(cartId: string, lineIds: string[]): Promise<Cart>;
+    updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    completeCheckout(_cartId: string): Promise<Order>;
+    getShippingMethods(_cartId: string): Promise<ShippingMethod[]>;
+    getRegionCountries(): Promise<_thorprovider_types.Country[]>;
+    addShippingMethod(_cartId: string, _methodId: string): Promise<Cart>;
+    initiatePaymentSession(_cartId: string, _providerId: string): Promise<void>;
+    applyDiscountCode(cartId: string, code: string): Promise<Cart>;
+    removeDiscountCode(cartId: string, _code: string): Promise<Cart>;
+    getOrders(options: GetOrdersOptions): Promise<Order[]>;
+    getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    getStockLocations(): Promise<StockLocation[]>;
+    checkInventoryLevels(): Promise<InventoryLevel[]>;
+    validateCartStock(): Promise<StockValidation>;
+    getFulfillmentOptions(): Promise<FulfillmentOption[]>;
+    cancelOrder(_orderId: string): Promise<Order>;
+    createFulfillment(_orderId: string): Promise<void>;
+    createRefund(_orderId: string): Promise<void>;
+    getAdminOrders(): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    getStorefrontContext(): Promise<StorefrontContext>;
+    isStorefrontRequired(): boolean;
+}
+
+/**
+ * BigCommerce provider configuration
+ */
+interface BigCommerceProviderConfig extends ProviderConfig {
+    /** BigCommerce store hash */
+    storeHash: string;
+    /** Storefront API token (JWT) */
+    storefrontApiToken: string;
+    /** Storefront API URL (usually https://store-{hash}.mybigcommerce.com) */
+    storefrontApiUrl: string;
+    /** Channel ID */
+    channelId: string;
+    /** Default currency code (default: 'USD') */
+    currencyCode?: string;
+}
+declare class BigCommerceProvider implements CommerceProvider {
+    readonly name = "bigcommerce";
+    readonly version = "1.0.0";
+    readonly capabilities: BackendCapabilities;
+    private logger;
+    private storefrontApiUrl;
+    private storeHash;
+    private channelId;
+    private currencyCode;
+    private headers;
+    constructor(config: BigCommerceProviderConfig);
+    private fetchApi;
+    getProduct(handle: string): Promise<Product | undefined>;
+    getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    getProductRecommendations(_productId: string): Promise<Product[]>;
+    getCollection(handle: string): Promise<Collection | undefined>;
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    getCategory(idOrHandle: string): Promise<ProductCategory | undefined>;
+    getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]>;
+    getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    createCart(): Promise<Cart>;
+    getCart(cartId: string): Promise<Cart | undefined>;
+    addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    removeFromCart(cartId: string, lineIds: string[]): Promise<Cart>;
+    updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    completeCheckout(_cartId: string): Promise<Order>;
+    getShippingMethods(_cartId: string): Promise<ShippingMethod[]>;
+    getRegionCountries(): Promise<_thorprovider_types.Country[]>;
+    addShippingMethod(_cartId: string, _methodId: string): Promise<Cart>;
+    initiatePaymentSession(_cartId: string, _providerId: string): Promise<void>;
+    applyDiscountCode(cartId: string, code: string): Promise<Cart>;
+    removeDiscountCode(cartId: string, code: string): Promise<Cart>;
+    getOrders(_options: GetOrdersOptions): Promise<Order[]>;
+    getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    getStockLocations(): Promise<StockLocation[]>;
+    checkInventoryLevels(): Promise<InventoryLevel[]>;
+    validateCartStock(): Promise<StockValidation>;
+    getFulfillmentOptions(): Promise<FulfillmentOption[]>;
+    cancelOrder(_orderId: string): Promise<Order>;
+    createFulfillment(_orderId: string): Promise<void>;
+    createRefund(_orderId: string): Promise<void>;
+    getAdminOrders(): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    getStorefrontContext(): Promise<StorefrontContext>;
+    isStorefrontRequired(): boolean;
+}
+
+/**
+ * WooCommerce provider configuration
+ */
+interface WooCommerceProviderConfig extends ProviderConfig {
+    /** WordPress site URL (e.g., 'https://mystore.com') */
+    url: string;
+    /** WooCommerce REST API consumer key (for authenticated operations) */
+    consumerKey?: string;
+    /** WooCommerce REST API consumer secret (for authenticated operations) */
+    consumerSecret?: string;
+    /** Default currency code (default: 'USD') */
+    currencyCode?: string;
+}
+declare class WooCommerceProvider implements CommerceProvider {
+    readonly name = "woocommerce";
+    readonly version = "1.0.0";
+    readonly capabilities: BackendCapabilities;
+    private logger;
+    private baseUrl;
+    private storeApiBase;
+    private restApiBase;
+    private currencyCode;
+    private authHeader?;
+    constructor(config: WooCommerceProviderConfig);
+    private storeApiFetch;
+    private restApiFetch;
+    getProduct(handle: string): Promise<Product | undefined>;
+    getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    getProductRecommendations(_productId: string): Promise<Product[]>;
+    getCollection(handle: string): Promise<Collection | undefined>;
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    getCategory(idOrHandle: string): Promise<ProductCategory | undefined>;
+    getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]>;
+    getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    createCart(): Promise<Cart>;
+    getCart(_cartId: string): Promise<Cart | undefined>;
+    addToCart(_cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    removeFromCart(_cartId: string, lineIds: string[]): Promise<Cart>;
+    updateCart(_cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    completeCheckout(_cartId: string): Promise<Order>;
+    getShippingMethods(_cartId: string): Promise<ShippingMethod[]>;
+    getRegionCountries(): Promise<_thorprovider_types.Country[]>;
+    addShippingMethod(_cartId: string, methodId: string): Promise<Cart>;
+    initiatePaymentSession(_cartId: string, _providerId: string): Promise<void>;
+    applyDiscountCode(_cartId: string, code: string): Promise<Cart>;
+    removeDiscountCode(_cartId: string, code: string): Promise<Cart>;
+    getOrders(_options: GetOrdersOptions): Promise<Order[]>;
+    getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    getStockLocations(): Promise<StockLocation[]>;
+    checkInventoryLevels(): Promise<InventoryLevel[]>;
+    validateCartStock(): Promise<StockValidation>;
+    getFulfillmentOptions(): Promise<FulfillmentOption[]>;
+    cancelOrder(_orderId: string): Promise<Order>;
+    createFulfillment(_orderId: string): Promise<void>;
+    createRefund(_orderId: string): Promise<void>;
+    getAdminOrders(): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    getStorefrontContext(): Promise<StorefrontContext>;
+    isStorefrontRequired(): boolean;
+}
+
+/**
+ * Spree provider configuration
+ */
+interface SpreeProviderConfig extends ProviderConfig {
+    /** Spree store base URL (e.g., 'https://myspreestore.com') */
+    baseUrl: string;
+    /** Bearer token for authenticated operations (customer or OAuth) */
+    bearerToken?: string;
+    /** Default currency code (default: 'USD') */
+    currencyCode?: string;
+}
+declare class SpreeProvider implements CommerceProvider {
+    readonly name = "spree";
+    readonly version = "1.0.0";
+    readonly capabilities: BackendCapabilities;
+    private logger;
+    private baseUrl;
+    private apiBase;
+    private currencyCode;
+    private bearerToken?;
+    private orderToken?;
+    constructor(config: SpreeProviderConfig);
+    private apiFetch;
+    getProduct(handle: string): Promise<Product | undefined>;
+    getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    getProductRecommendations(_productId: string): Promise<Product[]>;
+    getCollection(handle: string): Promise<Collection | undefined>;
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    getCategory(handle: string): Promise<ProductCategory | undefined>;
+    getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]>;
+    getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    createCart(): Promise<Cart>;
+    getCart(_cartId: string): Promise<Cart | undefined>;
+    addToCart(_cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    removeFromCart(_cartId: string, lineIds: string[]): Promise<Cart>;
+    updateCart(_cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    completeCheckout(_cartId: string): Promise<Order>;
+    getShippingMethods(_cartId: string): Promise<ShippingMethod[]>;
+    getRegionCountries(): Promise<_thorprovider_types.Country[]>;
+    addShippingMethod(_cartId: string, methodId: string): Promise<Cart>;
+    initiatePaymentSession(_cartId: string, _providerId: string): Promise<void>;
+    applyDiscountCode(_cartId: string, code: string): Promise<Cart>;
+    removeDiscountCode(_cartId: string, code: string): Promise<Cart>;
+    getOrders(_options: GetOrdersOptions): Promise<Order[]>;
+    getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    getStockLocations(): Promise<StockLocation[]>;
+    checkInventoryLevels(): Promise<InventoryLevel[]>;
+    validateCartStock(): Promise<StockValidation>;
+    getFulfillmentOptions(): Promise<FulfillmentOption[]>;
+    cancelOrder(_orderId: string): Promise<Order>;
+    createFulfillment(_orderId: string): Promise<void>;
+    createRefund(_orderId: string): Promise<void>;
+    getAdminOrders(): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    getStorefrontContext(): Promise<StorefrontContext>;
+    isStorefrontRequired(): boolean;
+}
+
+/**
+ * Magento provider configuration
+ */
+interface MagentoProviderConfig extends ProviderConfig {
+    /** Magento base URL (e.g., 'https://mymagento.com') */
+    baseUrl: string;
+    /** Store code for multi-tenant (default: 'default') */
+    storeCode?: string;
+    /** Customer bearer token (for authenticated operations) */
+    customerToken?: string;
+    /** Integration access token (for admin-level operations) */
+    accessToken?: string;
+    /** Default currency code (default: 'USD') */
+    currencyCode?: string;
+}
+declare class MagentoProvider implements CommerceProvider {
+    readonly name = "magento";
+    readonly version = "1.0.0";
+    readonly capabilities: BackendCapabilities;
+    private logger;
+    private baseUrl;
+    private storeCode;
+    private currencyCode;
+    private graphqlEndpoint;
+    private customerToken?;
+    private accessToken?;
+    constructor(config: MagentoProviderConfig);
+    private graphql;
+    getProduct(handle: string): Promise<Product | undefined>;
+    getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    getProductRecommendations(_productId: string): Promise<Product[]>;
+    getCollection(handle: string): Promise<Collection | undefined>;
+    getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
+    getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    getCategory(handle: string): Promise<ProductCategory | undefined>;
+    getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]>;
+    getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]>;
+    createCart(): Promise<Cart>;
+    getCart(cartId: string): Promise<Cart | undefined>;
+    addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    removeFromCart(cartId: string, lineIds: string[]): Promise<Cart>;
+    updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart>;
+    completeCheckout(_cartId: string): Promise<Order>;
+    getShippingMethods(_cartId: string): Promise<ShippingMethod[]>;
+    getRegionCountries(): Promise<_thorprovider_types.Country[]>;
+    addShippingMethod(_cartId: string, _methodId: string): Promise<Cart>;
+    initiatePaymentSession(_cartId: string, _providerId: string): Promise<void>;
+    applyDiscountCode(cartId: string, code: string): Promise<Cart>;
+    removeDiscountCode(cartId: string, _code: string): Promise<Cart>;
+    getOrders(_options: GetOrdersOptions): Promise<Order[]>;
+    getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]>;
+    getStockLocations(): Promise<StockLocation[]>;
+    checkInventoryLevels(): Promise<InventoryLevel[]>;
+    validateCartStock(): Promise<StockValidation>;
+    getFulfillmentOptions(): Promise<FulfillmentOption[]>;
+    cancelOrder(_orderId: string): Promise<Order>;
+    createFulfillment(_orderId: string): Promise<void>;
+    createRefund(_orderId: string): Promise<void>;
+    getAdminOrders(): Promise<{
+        orders: Order[];
+        count: number;
+    }>;
+    getStorefrontContext(): Promise<StorefrontContext>;
+    isStorefrontRequired(): boolean;
+}
+
+/**
+ * @thorprovider/adapters v2.0
+ * Provider Factory - Create commerce providers dynamically
+ *
+ * This factory is bound to SupportedProviderType from @thorprovider/types (L1).
+ * When adding a new provider:
+ * 1. Update SupportedProviderType enum in packages/types/src/provider.ts
+ * 2. Add new discriminated union case here
+ * 3. Create packages/adapters/src/providers/[platform]/
+ * 4. Implement CommerceProvider interface
+ */
+
+/**
+ * Supported provider types (imported from @thorprovider/types L1)
+ * Kept for backward compatibility; prefer ProviderTypeString from @thorprovider/types
+ */
+type ProviderType = ProviderTypeString;
+/**
+ * Provider configuration discriminated union
+ */
+type ProviderFactoryConfig = {
+    provider: 'medusa';
+    config: MedusaProviderConfig;
+} | {
+    provider: 'shopify';
+    config: ShopifyProviderConfig;
+} | {
+    provider: 'bigcommerce';
+    config: BigCommerceProviderConfig;
+} | {
+    provider: 'woocommerce';
+    config: WooCommerceProviderConfig;
+} | {
+    provider: 'spree';
+    config: SpreeProviderConfig;
+} | {
+    provider: 'magento';
+    config: MagentoProviderConfig;
+};
+/**
+ * Runtime provider configuration (accepts any ProviderTypeString from env vars)
+ */
+type RuntimeProviderConfig = {
+    provider: ProviderTypeString;
+    config: Record<string, unknown>;
+};
+/**
+ * Create a commerce provider instance
+ *
+ * @example
+ * ```ts
+ * const commerce = createProvider({
+ *   provider: 'medusa',
+ *   config: {
+ *     baseUrl: process.env.MEDUSA_BACKEND_URL,
+ *     publishableKey: process.env.MEDUSA_PUBLISHABLE_KEY,
+ *   }
+ * });
+ *
+ * const products = await commerce.getProducts();
+ * ```
+ */
+declare function createProvider(options: ProviderFactoryConfig | RuntimeProviderConfig): CommerceProvider;
+/**
+ * Type guard to check if a provider is of a specific type
+ */
+declare function isProviderType<T extends ProviderType>(provider: CommerceProvider, type: T): boolean;
+
+export { AdminAuthService, type AdminSession, AdminSessionService, BIGCOMMERCE_CAPABILITIES, type BackendMapping, type BackendMetadataAdapter, type BackendMetadataAdapterConfig, BigCommerceProvider, type BigCommerceProviderConfig, CHANNEL_ASSIGNED_AT_KEY, CHANNEL_ASSIGNED_BY_KEY, CHANNEL_SCOPE_KEY, type ChannelScopeMetadata, ChannelScopeValidationError, type ChannelScopeable, CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitBreakerStats, type CircuitState, CommerceError, ConfigurationError, type Coordinates, type FulfillmentGroup, type FulfillmentPlan, type LogLevel, type Logger, MAGENTO_CAPABILITIES, MEDUSA_CAPABILITIES, MagentoProvider, type MagentoProviderConfig, MedusaMetadataAdapter, MedusaProvider, type MedusaProviderConfig, type MetricsOrderInput, type MetricsProductInput, MetricsService, type PlanFulfillmentShippingAddress, ProviderAPIError, type ProviderFactoryConfig, ProviderNotFoundError, type ProviderType, ResourceNotFoundError, SHOPIFY_CAPABILITIES, SPREE_CAPABILITIES, ShopifyProvider, type ShopifyProviderConfig, SpreeProvider, type SpreeProviderConfig, type UICartItem, type UICartTotals, type UIDiscountCode, type UIPaymentMethod, type UIShippingMethod, WOOCOMMERCE_CAPABILITIES, WooCommerceProvider, type WooCommerceProviderConfig, assertEntityBelongsToChannel, backendCircuitBreaker, buildChannelScopeMetadata, calculateDistance, createBackendMetadataAdapter, createLogger, createProvider, filterByChannel, filterGlobalOnly, geocodeAddress, getBackendProviderId, getCapabilityDescription, getChannelScope, isBackendCapabilities, isGlobalEntity, isProviderType, isScopedToChannel, moneyToNumber, moneyToNumberSafe, numberToMoney, partitionByChannel, planFulfillment, transformFulfillmentOption, transformInventoryLevel, transformStockLocation, transformStorefrontConfig, validateAssignedBy, validateChannelId, validateChannelScopeAssignment, validateEntityId, validatePaymentId };