@thorprovider/adapters 5.0.10 → 5.0.12

package/AGENTS.md

@@ -1 +1 @@
-<!-- ADAPTERS-AGENTS-MD-START -->[@thorprovider/adapters Docs]|root: ./adapters|CRITICAL: Framework-agnostic business logic only. Never import Next.js or React. Check README.md and docs/getting-started.md before making changes.|To regenerate: yarn workspace @thorprovider/adapters generate:agent-index|.:{PROVIDER_IMPLEMENTATION_ANALYSIS.md,README.md,quick-reference.md}|docs:{RETRY_SOLUTION_SUMMARY.md,authentication.md,capabilities-system.md,category-customization.md,fetch-reliability-solution.md,getting-started.md,multi-tenant-channel-scoping.md,profile-management.md,providers-overview.md,services-overview.md,update-documentation.md}|src/resilience:{README.md}<!-- ADAPTERS-AGENTS-MD-END -->
+<!-- ADAPTERS-AGENTS-MD-START -->[@thorprovider/adapters Docs]|root: ./adapters|CRITICAL: Framework-agnostic business logic only. Never import Next.js or React. Check README.md and docs/getting-started.md before making changes. Electrostore MVP: see director roadmap.|To regenerate: yarn workspace @thorprovider/adapters generate:agent-index|.:{PROVIDER_IMPLEMENTATION_ANALYSIS.md,README.md,quick-reference.md}|docs:{RETRY_SOLUTION_SUMMARY.md,authentication.md,capabilities-system.md,category-customization.md,fetch-reliability-solution.md,getting-started.md,multi-tenant-channel-scoping.md,profile-management.md,providers-overview.md,services-overview.md,update-documentation.md}|src/resilience:{README.md}<!-- ADAPTERS-AGENTS-MD-END -->

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 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, Country } from '@thorprovider/types';
+import { Order, Cart, BackendCapabilities, Money, PaymentMethod, FulfillmentOption, CartItem, StockLocation, InventoryLevel, StorefrontConfig, DashboardMetrics, ProviderTypeString, CommerceProvider, AuthProvider, ProviderConfig, AuthConfig, Product, GetProductsOptions, CatalogQuery, CatalogQueryOutcome, FacetSupport, AdvancedSearchProductsOptions, SearchResultMeta, FilterConfig, Collection, GetCollectionsOptions, CollectionProductsOptions, ProductCategory, GetCategoriesOptions, CartLineInput, CartLineUpdate, GetOrdersOptions, GetCustomerOrdersPageOptions, CustomerOrdersPage, GetCustomersOptions, Customer, Address, Region, AdminProduct, PaymentMethodsOptions, StockValidation, StorefrontContext, DesignerConfig, DesignerHistoryEntry, ShippingMethod, Country } from '@thorprovider/types';
 export * from '@thorprovider/types';
-export { BackendCapabilities, CommerceProvider, DesignerConfig, DesignerHistoryEntry, DesignerNavItem, DesignerThemeConfig, DesignerThemePreset, ProviderConfig, StorefrontConfig, StorefrontConfigError, StorefrontContext, StorefrontPlatformType, StorefrontSeoDefaults } from '@thorprovider/types';
+export { BackendCapabilities, CommerceProvider, DesignerConfig, DesignerHistoryEntry, DesignerNavItem, DesignerThemeConfig, DesignerThemePreset, ProviderConfig, StorefrontConfig, StorefrontContext, StorefrontPlatformType, StorefrontSeoDefaults } from '@thorprovider/types';
 import Medusa from '@medusajs/js-sdk';
 
 /**
@@ -211,6 +211,64 @@ interface UIPaymentMethod {
     description?: string;
 }
 
+/**
+ * @thorprovider/adapters — Cart completion contract
+ *
+ * Completion of a backend cart is discriminated (change B, decision 11): a
+ * native complete may return an order, a cart carrying a structured error, or
+ * an ambiguous/unresolved result whose outcome must be reconciled before any
+ * retry. This type is provider-agnostic and lives in adapters (not
+ * `@thorprovider/types`, which stays type-only and frozen).
+ */
+
+/**
+ * Structured completion error. `raw` carries the backend's own error object
+ * when one was supplied so the discriminator and details are preserved.
+ */
+interface CartCompletionError {
+    /** Human-readable message. */
+    message: string;
+    /** Stable error code when the backend or transport supplies one. */
+    code?: string;
+    /** HTTP/transport status when one is known. */
+    status?: number;
+    /** Backend error details, carried through unchanged. */
+    raw?: unknown;
+}
+/**
+ * The discriminated result of completing a cart.
+ *
+ * - `order` — the cart was completed and an order was placed.
+ * - `cart` — the backend returned a cart with a structured error (the native
+ *   HTTP 200 `type: "cart"` discriminator is preserved).
+ * - `unresolved` — the mutation's outcome is unknown (timeout/transport/5xx).
+ *   Never blindly retry: reconcile the committed cart before another attempt.
+ */
+type CartCompletionResult = {
+    type: 'order';
+    order: Order;
+} | {
+    type: 'cart';
+    cart: Cart;
+    error: CartCompletionError;
+} | {
+    type: 'unresolved';
+    error: CartCompletionError;
+};
+/**
+ * Optional capability a provider may implement to expose the discriminated
+ * completion and reconciliation protocol. Providers that do not implement it
+ * still satisfy `CommerceProvider`; the runtime falls back to
+ * `completeCheckout` for them.
+ */
+interface CartCompletionCapable {
+    /**
+     * Complete the cart once, preserving the native discriminator. Must not
+     * retry an ambiguous mutation.
+     */
+    completeCart?(cartId: string): Promise<CartCompletionResult>;
+}
+
 /**
  * @thorprovider/adapters v2.0
  * Backend Capabilities System
@@ -309,6 +367,26 @@ declare class ProviderNotFoundError extends CommerceError {
 declare class ConfigurationError extends CommerceError {
     constructor(message: string);
 }
+/**
+ * Storefront validation error.
+ * Thrown when storefront configuration is invalid or missing.
+ *
+ * Moved here from `@thorprovider/types` so that package stays type-only.
+ *
+ * @example
+ * ```typescript
+ * throw new StorefrontConfigError(
+ *   'Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID',
+ *   'medusa',
+ *   'NEXT_PUBLIC_SALES_CHANNEL_ID',
+ * );
+ * ```
+ */
+declare class StorefrontConfigError extends Error {
+    readonly platformType: string;
+    readonly requiredEnvVar?: string;
+    constructor(message: string, platformType: string, requiredEnvVar?: string);
+}
 /**
  * Resource not found error
  */
@@ -1442,6 +1520,12 @@ interface MedusaProviderConfig extends ProviderConfig {
      * Region ID (optional, will use default region if not provided)
      */
     regionId?: string;
+    /**
+     * Per-request catalog listing bound. Listing is paginated with this bound
+     * instead of an unbounded scan; it is a configured safety bound, not a
+     * backend maximum. Defaults to `MEDUSA_CATALOG_PAGE_SIZE` or 50.
+     */
+    catalogPageSize?: number;
     /**
      * Authentication configuration (optional)
      * If not provided, auth methods will not be available
@@ -1480,9 +1564,21 @@ interface MedusaProviderConfig extends ProviderConfig {
  *
  * Implements CommerceProvider interface for Medusa.js v2
  */
-declare class MedusaProvider implements CommerceProvider {
+declare class MedusaProvider implements CommerceProvider, CartCompletionCapable {
     readonly name = "medusa";
     readonly version = "2.0.0";
+    /**
+     * Canonical catalog sort keys this provider applies at the query level.
+     *
+     * Advertises only the backend-verified orderings (E2 Decision 6). `price-asc`,
+     * `price-desc`, and `rating` are intentionally absent: they are not applied at
+     * the query level, so the listing never offers them as global sorts.
+     *
+     * The literal tuple is assignable to `CommerceProvider['supportedCatalogSortKeys']`
+     * (`readonly CatalogSortKey[]`); it is written structurally here so the adapter
+     * compiles against the published `@thorprovider/types` declaration.
+     */
+    readonly supportedCatalogSortKeys: readonly ["featured", "name", "newest"];
     /**
      * Medusa backend capabilities.
      * Starts with static defaults, replaced by dynamic values from
@@ -1502,6 +1598,14 @@ declare class MedusaProvider implements CommerceProvider {
     private baseUrl;
     private publishableKey;
     private regionId?;
+    /** Configured per-request catalog listing bound (never an unbounded scan). */
+    private catalogPageSize;
+    /**
+     * Per-scope cache of the truthful facet-support descriptor. The optional
+     * advanced endpoint is probed once per demonstrated scope/query rather than on
+     * every listing request (E2 task 2.4).
+     */
+    private facetSupportCache;
     /** Secret API key for admin operations (if configured). */
     private adminApiKey?;
     /**
@@ -1547,12 +1651,120 @@ declare class MedusaProvider implements CommerceProvider {
      * Handles network failures and temporary backend issues
      */
     private withRetry;
+    /** Fields needed to price a product variant for the current region. */
+    private buildProductFields;
+    /** Scope a store query to the configured storefront sales channel, if any. */
+    private applySalesChannelScope;
+    /**
+     * Directed single-product lookup by a supported native filter (`handle` or
+     * `id`). This is independent of catalog listing pagination, so a known
+     * product beyond the first listing page still resolves without scanning.
+     *
+     * Medusa's store API supports `handle` and `id` on `/store/products`; it
+     * does not expose a variant filter there, so a variant is resolved from the
+     * product once the product is known (see `getProductDetailByHandle` in the
+     * runtime). No `limit` beyond 1 is issued.
+     */
+    private fetchSingleProduct;
     getProduct(handle: string, options?: {
         regionId?: string;
     }): Promise<Product | undefined>;
+    /**
+     * Directed product lookup by backend product ID. Independent of the first
+     * listing page, mirroring `getProduct` for handle-based resolution.
+     */
+    getProductById(id: string, options?: {
+        regionId?: string;
+    }): Promise<Product | undefined>;
     getProducts(options?: GetProductsOptions & {
         regionId?: string;
     }): Promise<Product[]>;
+    /**
+     * Canonical catalog query path (E2 task 2.2).
+     *
+     * Accepts a validated `CatalogQuery`, translates it into Medusa Store
+     * `/store/products` parameters, and returns a truthful `CatalogQueryOutcome`.
+     * The route category scope is always retained and intersected with the
+     * `categories` filter; `categories`/`collections` handles are resolved to
+     * backend IDs through the existing directed lookups (`getCategory`/
+     * `getCollection`). Any requested filter this provider cannot apply
+     * (price/`inStock`/attributes) is rejected as a typed `unsupported-query`
+     * outcome naming the fields — never a partial success and never a silent
+     * drop. Pagination is `offset = (page - 1) * pageSize`, defaulting to the
+     * canonical page size.
+     *
+     * Legacy `getProducts`/`getCategoryProducts` are unchanged; this additive
+     * method is the typed seam the runtime query bridge (E2 task 3.1) consumes.
+     */
+    getCatalogProducts(query: CatalogQuery): Promise<CatalogQueryOutcome>;
+    /**
+     * Execute a basic-only canonical query against the equivalent basic endpoint
+     * `/store/products`, reporting the filters it actually applied.
+     */
+    private queryBasicCatalog;
+    /**
+     * Execute an advanced canonical query against the real optional endpoint
+     * `/store/search`, then re-validate that the response applied every requested
+     * filter. A response that does not confirm a requested field, or an endpoint
+     * failure, yields a typed `unsupported-query` error — never a partial result
+     * labelled success and never a silent fallback to the basic endpoint.
+     */
+    private queryAdvancedCatalog;
+    /** Resolve category handles to Medusa category IDs via directed lookups. */
+    private resolveCategoryIds;
+    /** Resolve collection handles to Medusa collection IDs via directed lookups. */
+    private resolveCollectionIds;
+    /**
+     * Truthful facet-support descriptor for a scope (E2 task 2.4).
+     *
+     * Basic facets (`categories`, `collections`) are always offered: they are
+     * applied by the canonical basic endpoint `/store/products`, and the
+     * descriptor records that endpoint with the applied query and scope as their
+     * demonstration source.
+     *
+     * Optional advanced facets (`price`, `inStock`, and advertised `attr.<name>`)
+     * are offered only when the real optional `/store/search` endpoint has been
+     * demonstrated with the applied query for the current scope AND the response
+     * echoes the filter as applied. Otherwise they are held with the real probe
+     * status/reason — a capability boolean or returned facet metadata is never
+     * accepted as proof (E2 Decisions 4–5; spec "Backend support is proven against
+     * the real endpoint, not assumed").
+     *
+     * The descriptor carries no counts or ranges and no invented timestamp; every
+     * offered facet has an actual `{ endpoint, appliedQuery, scope }` source.
+     */
+    getCatalogFacetSupport(options?: {
+        query?: CatalogQuery;
+        categoryIds?: string[];
+        collectionIds?: string[];
+        scope?: string;
+    }): Promise<FacetSupport>;
+    private resolveCatalogFacetSupport;
+    /**
+     * Demonstrate the optional advanced endpoint with the applied query for the
+     * current scope. A non-2xx response (including the HTTP 404/500 an absent
+     * plugin returns), an unparseable body, or a response that does not echo the
+     * applied filters all mean the facet is not demonstrated — never a silent
+     * assumption of support. Uses a single SDK request (no retry): a support probe
+     * must not amplify a broken optional endpoint into repeated requests.
+     */
+    private probeAdvancedSearchSupport;
+    /**
+     * Build the advanced-endpoint query parameters from the canonical query. The
+     * SDK serializes the plain object, so no manual stringification is needed.
+     */
+    private buildAdvancedSearchQuery;
+    /** Resolve the effective category scope of a query to backend IDs. */
+    private resolveScopeCategoryIds;
+    /**
+     * Advertised filterable attribute handles for the scope. The custom-attributes
+     * endpoint is facet *metadata* (which attributes exist), not proof that a
+     * filter can be applied; these handles are candidates only, and each still
+     * requires the advanced endpoint to echo it as applied before it is offered.
+     */
+    private resolveFilterableAttributeHandles;
+    /** Build a typed `unsupported-query` outcome naming the offending fields. */
+    private unsupportedCatalogOutcome;
     getProductRecommendations(productId: string): Promise<Product[]>;
     /**
      * Advanced product search using /store/search endpoint
@@ -1568,6 +1780,14 @@ declare class MedusaProvider implements CommerceProvider {
         products: Product[];
         meta?: SearchResultMeta;
     }>;
+    /**
+     * Faithful fallback for `searchProductsAdvanced`. A basic-only request is
+     * served by `getProducts`; a request that depends on the optional advanced
+     * endpoint is rejected as a typed `ProviderAPIError` naming the unappliable
+     * fields, so a failed advanced search never returns an unfiltered result
+     * labelled success (E2 task 2.4).
+     */
+    private fallbackAdvancedSearch;
     /**
      * Get available filter options for product filtering
      *
@@ -1685,13 +1905,17 @@ declare class MedusaProvider implements CommerceProvider {
         }>;
     }>>;
     /**
-     * Get all orders for a customer (storefront).
+     * Get all orders for a customer (storefront) as an array (legacy surface).
      *
-     * Note: This retrieves orders from the storefront API (store.order.list),
-     * which returns orders only for the authenticated customer in the JWT.
+     * Delegates to the channel-scoped paginated contract
+     * ({@link customerOrdersPage}) and returns that window's orders. The backend
+     * (`GET /store/thor/orders`) scopes by BOTH the authenticated customer and
+     * the sales channel resolved from the publishable key, so cross-channel
+     * orders are excluded by the backend before pagination and **no client-side
+     * channel filter runs**.
      *
-     * @param options - Order query options (supports callbacks for custom backends)
-     * @returns Array of orders for the authenticated customer
+     * @param options - Order query options (supports a custom fetcher)
+     * @returns Array of orders for the authenticated customer on the store channel
      *
      * @example
      * ```typescript
@@ -1700,6 +1924,25 @@ declare class MedusaProvider implements CommerceProvider {
      * ```
      */
     getOrders(options?: GetOrdersOptions): Promise<Order[]>;
+    /**
+     * Channel-scoped, paginated order history for the authenticated customer.
+     *
+     * Calls the backend route `GET /store/thor/orders`, which requires the
+     * customer session and scopes `order` by `customer_id` **and** the
+     * `sales_channel_id` resolved from the publishable key, returning
+     * `{ orders, count, limit, offset }` with the backend's real total computed
+     * before pagination.
+     *
+     * The `salesChannelId` option is the store's explicitly configured channel.
+     * When supplied, every returned order is asserted to belong to it; a
+     * foreign-channel order (for example from a multi-channel publishable key that
+     * silently resolved an arbitrary first id) fails closed with a typed error
+     * rather than being presented as the customer's history.
+     *
+     * @param options - Bounded pagination window and the store's sales channel
+     * @returns The backend's `{ orders, count, limit, offset }`
+     */
+    customerOrdersPage(options?: GetCustomerOrdersPageOptions): Promise<CustomerOrdersPage>;
     /**
      * Get a single order by ID
      *
@@ -1991,6 +2234,20 @@ declare class MedusaProvider implements CommerceProvider {
      * @throws {ProviderAPIError} If checkout fails
      */
     completeCheckout(cartId: string): Promise<Order>;
+    /**
+     * Complete a cart exactly once and preserve the native discriminator
+     * (change B, decision 11).
+     *
+     * Medusa's `POST /store/carts/:id/complete` returns HTTP 200 whose body is
+     * either `{ type: 'order', order }` or `{ type: 'cart', cart, error }`. This
+     * method never retries: a thrown transport/timeout/5xx failure becomes an
+     * `unresolved` result so the caller reconciles the committed cart before any
+     * further attempt. The Medusa JS SDK performs no implicit retry of its own,
+     * so there is no blind retry beneath this call either.
+     */
+    completeCart(cartId: string): Promise<CartCompletionResult>;
+    /** Normalize any thrown/returned completion failure into a structured error. */
+    private toCompletionError;
     /**
      * Get available shipping methods for cart
      *
@@ -2636,15 +2893,24 @@ declare class StelOrderProvider implements CommerceProvider {
     private wrapError;
 }
 
+/**
+ * Stable sales channel the fixture cart is scoped to. Exported so a host can
+ * build a matching `StoreContext` for the mock data source; the runtime
+ * context check compares against it like a real backend channel.
+ */
+declare const MOCK_SALES_CHANNEL_ID = "mock-sales-channel";
+
 interface MockProviderConfig extends ProviderConfig {
     currencyCode?: string;
     siteUrl?: string;
 }
-declare class MockProvider implements CommerceProvider {
+
+declare class MockProvider implements CommerceProvider, CartCompletionCapable {
     readonly name = "mock";
     readonly version = "1.0.0";
     readonly capabilities: Readonly<_thorprovider_types.BackendCapabilities>;
     readonly isMock = true;
+    readonly supportedCatalogSortKeys: readonly _thorprovider_types.CatalogSortKey[];
     private readonly currencyCode;
     private readonly siteUrl;
     constructor(config?: MockProviderConfig);
@@ -2653,6 +2919,16 @@ declare class MockProvider implements CommerceProvider {
         regionId?: string;
     }): Promise<Product | undefined>;
     getProducts(options?: GetProductsOptions): Promise<Product[]>;
+    /**
+     * Canonical catalog query path (E2 task 2.5).
+     *
+     * Delegates to the fixture-backed canonical implementation so mock mode is a
+     * faithful stand-in for the same contract the Medusa adapter honors: scope ∩
+     * categories, collection resolution, global ordering before pagination, the
+     * real full match count, and a typed `unsupported-query` for advanced filters
+     * the mock does not implement.
+     */
+    getCatalogProducts(query: CatalogQuery): Promise<CatalogQueryOutcome>;
     getProductRecommendations(productId: string): Promise<Product[]>;
     getCollection(handle: string): Promise<Collection | undefined>;
     getCollections(options?: GetCollectionsOptions): Promise<Collection[]>;
@@ -2679,6 +2955,15 @@ declare class MockProvider implements CommerceProvider {
         }>;
     }>>;
     completeCheckout(cartId: string): Promise<Order>;
+    /**
+     * Discriminated completion for the fixture provider.
+     *
+     * Completion is idempotent by construction (the fixture order id derives from
+     * the cart id), so completing an already-completed cart returns the same
+     * persisted order — mirroring the native reconcile path without a second
+     * order.
+     */
+    completeCart(cartId: string): Promise<CartCompletionResult>;
     getShippingMethods(cartId: string): Promise<ShippingMethod[]>;
     getRegionCountries(regionId: string): Promise<_thorprovider_types.Country[]>;
     addShippingMethod(cartId: string, methodId: string): Promise<Cart>;
@@ -2706,20 +2991,95 @@ declare class MockProvider implements CommerceProvider {
     isStorefrontRequired(): boolean;
 }
 
+/**
+ * @thorprovider/adapters — Provider registry (runtime)
+ *
+ * Runtime owner of the provider registry: the `SupportedProviderType` enum,
+ * its metadata, and the guards. The provider-type union contract
+ * (`ProviderTypeString`) stays type-only in `@thorprovider/types`.
+ *
+ * When adding a new provider:
+ * 1. Add the string to `ProviderTypeString` in packages/types/src/provider.ts.
+ * 2. Add the enum member + metadata entry here.
+ * 3. Create packages/adapters/src/providers/[platform]/.
+ */
+
+/**
+ * All supported commerce platform providers.
+ * `mock` is the backend-optional runtime provider used for layout/design mode.
+ * `medusa` is fully implemented for real backend usage; others are placeholders for future expansion.
+ *
+ * @remarks Implementation status:
+ * - ✅ mock: Fixture-backed provider for backend-optional storefronts
+ * - ✅ medusa: Fully implemented
+ * - 🟡 stelorder: In progress (ERP adapter v1)
+ * - 🟡 shopify: Planned (Phase 2)
+ * - 🟡 bigcommerce: Planned (Phase 2)
+ * - 🟡 woocommerce: Planned (Phase 3)
+ * - 🟡 spree: Planned (Phase 3)
+ * - 🟡 magento: Planned (Phase 3)
+ */
+declare enum SupportedProviderType {
+    Mock = "mock",
+    Medusa = "medusa",
+    StelOrder = "stelorder",
+    Shopify = "shopify",
+    BigCommerce = "bigcommerce",
+    WooCommerce = "woocommerce",
+    Spree = "spree",
+    Magento = "magento"
+}
+/**
+ * Metadata about each provider.
+ * Useful for UI, error messages, validation, and documentation.
+ */
+declare const PROVIDER_METADATA: Record<ProviderTypeString, {
+    name: string;
+    description: string;
+    requiresStorefront: boolean;
+    requiredEnvVars: string[];
+    maxRetries: number;
+}>;
+/**
+ * Check if a string is a valid provider type.
+ *
+ * @example
+ * ```typescript
+ * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {
+ *   // type is narrowed to ProviderTypeString
+ * }
+ * ```
+ */
+declare function isSupportedProviderType(value: unknown): value is ProviderTypeString;
+/**
+ * Get metadata for a provider type.
+ * Useful for validation, error messages, and logging.
+ *
+ * @example
+ * ```typescript
+ * const meta = getProviderMetadata('medusa');
+ * console.log(`Using ${meta.name} with max ${meta.maxRetries} retries`);
+ * ```
+ */
+declare function getProviderMetadata(type: ProviderTypeString): (typeof PROVIDER_METADATA)[ProviderTypeString];
+
 /**
  * @thorprovider/adapters v2.0
  * Provider Factory - Create commerce providers dynamically
  *
- * This factory is bound to SupportedProviderType from @thorprovider/types (L1).
+ * This factory owns the runtime provider registry (SupportedProviderType +
+ * metadata + guards) and is bound to the type-only ProviderTypeString union
+ * 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
+ * 1. Update ProviderTypeString in packages/types/src/provider.ts
+ * 2. Add the enum member + metadata in ./provider-types.ts
+ * 3. Add new discriminated union case here
+ * 4. Create packages/adapters/src/providers/[platform]/
+ * 5. Implement CommerceProvider interface
  */
 
 /**
- * Supported provider types (imported from @thorprovider/types L1)
+ * Supported provider types (type-only union owned by @thorprovider/types L1)
  * Kept for backward compatibility; prefer ProviderTypeString from @thorprovider/types
  */
 type ProviderType = ProviderTypeString;
@@ -2780,4 +3140,4 @@ declare function createProvider(options: ProviderFactoryConfig | RuntimeProvider
  */
 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, MOCK_CAPABILITIES, MagentoProvider, type MagentoProviderConfig, MedusaMetadataAdapter, MedusaProvider, type MedusaProviderConfig, type MetricsOrderInput, type MetricsProductInput, MetricsService, MockProvider, type MockProviderConfig, type PlanFulfillmentShippingAddress, ProviderAPIError, type ProviderFactoryConfig, ProviderNotFoundError, type ProviderType, ResourceNotFoundError, type RetryConfig, SHOPIFY_CAPABILITIES, SPREE_CAPABILITIES, STELORDER_CAPABILITIES, ShopifyProvider, type ShopifyProviderConfig, SpreeProvider, type SpreeProviderConfig, StelOrderProvider, type StelOrderProviderConfig, type UICartItem, type UICartTotals, type UIDiscountCode, type UIPaymentMethod, type UIShippingMethod, WOOCOMMERCE_CAPABILITIES, WooCommerceProvider, type WooCommerceProviderConfig, assertEntityBelongsToChannel, backendCircuitBreaker, buildChannelScopeMetadata, calculateDistance, createBackendMetadataAdapter, createFetchWithRetry, createLogger, createProvider, extractErrorMessage, fetchWithRetry, filterByChannel, filterGlobalOnly, geocodeAddress, getBackendProviderId, getCapabilityDescription, getChannelScope, isBackendCapabilities, isGlobalEntity, isProviderType, isScopedToChannel, moneyToNumber, moneyToNumberSafe, numberToMoney, partitionByChannel, planFulfillment, transformFulfillmentOption, transformInventoryLevel, transformStockLocation, transformStorefrontConfig, validateAssignedBy, validateChannelId, validateChannelScopeAssignment, validateEntityId, validatePaymentId };
+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 CartCompletionCapable, type CartCompletionError, type CartCompletionResult, 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, MOCK_CAPABILITIES, MOCK_SALES_CHANNEL_ID, MagentoProvider, type MagentoProviderConfig, MedusaMetadataAdapter, MedusaProvider, type MedusaProviderConfig, type MetricsOrderInput, type MetricsProductInput, MetricsService, MockProvider, type MockProviderConfig, PROVIDER_METADATA, type PlanFulfillmentShippingAddress, ProviderAPIError, type ProviderFactoryConfig, ProviderNotFoundError, type ProviderType, ResourceNotFoundError, type RetryConfig, SHOPIFY_CAPABILITIES, SPREE_CAPABILITIES, STELORDER_CAPABILITIES, ShopifyProvider, type ShopifyProviderConfig, SpreeProvider, type SpreeProviderConfig, StelOrderProvider, type StelOrderProviderConfig, StorefrontConfigError, SupportedProviderType, type UICartItem, type UICartTotals, type UIDiscountCode, type UIPaymentMethod, type UIShippingMethod, WOOCOMMERCE_CAPABILITIES, WooCommerceProvider, type WooCommerceProviderConfig, assertEntityBelongsToChannel, backendCircuitBreaker, buildChannelScopeMetadata, calculateDistance, createBackendMetadataAdapter, createFetchWithRetry, createLogger, createProvider, extractErrorMessage, fetchWithRetry, filterByChannel, filterGlobalOnly, geocodeAddress, getBackendProviderId, getCapabilityDescription, getChannelScope, getProviderMetadata, isBackendCapabilities, isGlobalEntity, isProviderType, isScopedToChannel, isSupportedProviderType, moneyToNumber, moneyToNumberSafe, numberToMoney, partitionByChannel, planFulfillment, transformFulfillmentOption, transformInventoryLevel, transformStockLocation, transformStorefrontConfig, validateAssignedBy, validateChannelId, validateChannelScopeAssignment, validateEntityId, validatePaymentId };