@thorprovider/adapters 5.0.10 → 5.0.11

package/dist/index.js

@@ -45,11 +45,13 @@ __export(src_exports, {
   MAGENTO_CAPABILITIES: () => MAGENTO_CAPABILITIES,
   MEDUSA_CAPABILITIES: () => MEDUSA_CAPABILITIES,
   MOCK_CAPABILITIES: () => MOCK_CAPABILITIES,
+  MOCK_SALES_CHANNEL_ID: () => MOCK_SALES_CHANNEL_ID,
   MagentoProvider: () => MagentoProvider,
   MedusaMetadataAdapter: () => MedusaMetadataAdapter,
   MedusaProvider: () => MedusaProvider,
   MetricsService: () => MetricsService,
   MockProvider: () => MockProvider,
+  PROVIDER_METADATA: () => PROVIDER_METADATA,
   ProviderAPIError: () => ProviderAPIError,
   ProviderNotFoundError: () => ProviderNotFoundError,
   ResourceNotFoundError: () => ResourceNotFoundError,
@@ -59,7 +61,8 @@ __export(src_exports, {
   ShopifyProvider: () => ShopifyProvider,
   SpreeProvider: () => SpreeProvider,
   StelOrderProvider: () => StelOrderProvider,
-  StorefrontConfigError: () => import_types2.StorefrontConfigError,
+  StorefrontConfigError: () => StorefrontConfigError,
+  SupportedProviderType: () => SupportedProviderType,
   WOOCOMMERCE_CAPABILITIES: () => WOOCOMMERCE_CAPABILITIES,
   WooCommerceProvider: () => WooCommerceProvider,
   assertEntityBelongsToChannel: () => assertEntityBelongsToChannel,
@@ -78,10 +81,12 @@ __export(src_exports, {
   getBackendProviderId: () => getBackendProviderId,
   getCapabilityDescription: () => getCapabilityDescription,
   getChannelScope: () => getChannelScope,
+  getProviderMetadata: () => getProviderMetadata,
   isBackendCapabilities: () => isBackendCapabilities,
   isGlobalEntity: () => isGlobalEntity,
   isProviderType: () => isProviderType,
   isScopedToChannel: () => isScopedToChannel,
+  isSupportedProviderType: () => isSupportedProviderType,
   moneyToNumber: () => moneyToNumber,
   moneyToNumberSafe: () => moneyToNumberSafe,
   numberToMoney: () => numberToMoney,
@@ -98,7 +103,6 @@ __export(src_exports, {
   validatePaymentId: () => validatePaymentId
 });
 module.exports = __toCommonJS(src_exports);
-var import_types2 = require("@thorprovider/types");
 
 // src/types/capabilities.types.ts
 var MOCK_CAPABILITIES = {
@@ -463,6 +467,16 @@ var ConfigurationError = class extends CommerceError {
     this.name = "ConfigurationError";
   }
 };
+var StorefrontConfigError = class extends Error {
+  platformType;
+  requiredEnvVar;
+  constructor(message, platformType, requiredEnvVar) {
+    super(message);
+    this.name = "StorefrontConfigError";
+    this.platformType = platformType;
+    this.requiredEnvVar = requiredEnvVar;
+  }
+};
 var ResourceNotFoundError = class extends CommerceError {
   constructor(resource, identifier) {
     super(`${resource} not found: ${identifier}`, "RESOURCE_NOT_FOUND", 404);
@@ -997,6 +1011,16 @@ function transformMoney(amount, currencyCode = "USD") {
     currencyCode: currencyCode.toUpperCase()
   };
 }
+function transformAmount(amount, currencyCode) {
+  const currencyCodeUpper = (currencyCode ?? "").toUpperCase();
+  if (typeof amount !== "number" || !Number.isFinite(amount)) {
+    return { amount: "", currencyCode: currencyCodeUpper };
+  }
+  return { amount: amount.toFixed(2), currencyCode: currencyCodeUpper };
+}
+function transformProductPrice(amount, currencyCode) {
+  return transformAmount(amount, currencyCode);
+}
 function transformImage(url, alt = "") {
   return {
     url,
@@ -1048,39 +1072,42 @@ function transformProductOption(option) {
     values: option.values?.map((v) => v.value ?? "") ?? []
   };
 }
-function transformProductVariant(variant, currencyCode = "USD") {
+function transformProductVariant(variant, currencyCode) {
   let priceAmount;
   let priceCurrency = currencyCode;
   if (variant.calculated_price) {
     priceAmount = variant.calculated_price.calculated_amount;
-    priceCurrency = variant.calculated_price.currency_code || currencyCode;
+    priceCurrency = variant.calculated_price.currency_code ?? currencyCode;
   } else if (variant.prices && variant.prices.length > 0) {
-    const price = variant.prices.find((p) => p.currency_code === currencyCode.toLowerCase());
+    const target = currencyCode?.toLowerCase();
+    const price = (target ? variant.prices.find((p) => p.currency_code === target) : void 0) ?? variant.prices[0];
     priceAmount = price?.amount;
-    priceCurrency = price?.currency_code || currencyCode;
+    priceCurrency = price?.currency_code ?? currencyCode;
   }
   const isAvailable = variant.manage_inventory === false ? true : (variant.inventory_quantity ?? 0) > 0 || variant.allow_backorder === true;
   return {
     id: variant.id,
     title: variant.title ?? "Default",
+    // SKU is optional descriptive data only — never API/purchase identity.
     sku: variant.sku ?? void 0,
     availableForSale: isAvailable,
     selectedOptions: variant.options?.map((opt) => ({
       name: opt.option?.title ?? "",
       value: opt.value ?? ""
     })) ?? [],
-    price: transformMoney(priceAmount, priceCurrency),
+    price: transformProductPrice(priceAmount, priceCurrency),
     compareAtPrice: void 0,
     // Medusa doesn't have compare-at pricing
     quantityAvailable: variant.manage_inventory ? variant.inventory_quantity : void 0,
     image: variant.thumbnail ? transformImage(variant.thumbnail, variant.title ?? "") : void 0
   };
 }
-function transformProduct(product, currencyCode = "USD") {
+function transformProduct(product, currencyCode) {
   const variants = product.variants?.map((v) => transformProductVariant(v, currencyCode)) ?? [];
-  const prices = variants.map((v) => parseFloat(v.price.amount));
-  const minPrice = Math.min(...prices);
-  const maxPrice = Math.max(...prices);
+  const validPrices = variants.map((v) => v.price).filter((money) => money.amount !== "" && Number.isFinite(Number(money.amount))).map((money) => Number(money.amount));
+  const rangeCurrency = variants.find((v) => v.price.currencyCode)?.price.currencyCode ?? (currencyCode ?? "").toUpperCase();
+  const minPrice = validPrices.length > 0 ? Math.min(...validPrices) : void 0;
+  const maxPrice = validPrices.length > 0 ? Math.max(...validPrices) : void 0;
   return {
     id: product.id,
     handle: product.handle ?? "",
@@ -1096,10 +1123,16 @@ function transformProduct(product, currencyCode = "USD") {
     images: product.images?.map((img) => transformImage(img.url ?? "", product.title ?? "")) ?? [],
     priceRange: {
       // Build Money directly from already-resolved major-unit prices.
-      // Do NOT pass through transformMoney (which would call toFixed on already-correct values)
-      // and do NOT multiply by 100 (that was a compensatory hack for the old /100 bug).
-      minVariantPrice: { amount: (Number.isFinite(minPrice) ? minPrice : 0).toFixed(2), currencyCode: currencyCode.toUpperCase() },
-      maxVariantPrice: { amount: (Number.isFinite(maxPrice) ? maxPrice : 0).toFixed(2), currencyCode: currencyCode.toUpperCase() }
+      // Do NOT multiply by 100 (that was a compensatory hack for the old /100
+      // bug) and do NOT fabricate a zero for an unresolved price.
+      minVariantPrice: {
+        amount: minPrice !== void 0 ? minPrice.toFixed(2) : "",
+        currencyCode: rangeCurrency
+      },
+      maxVariantPrice: {
+        amount: maxPrice !== void 0 ? maxPrice.toFixed(2) : "",
+        currencyCode: rangeCurrency
+      }
     },
     collections: product.collection ? [{
       id: product.collection.id,
@@ -1122,38 +1155,19 @@ function transformProduct(product, currencyCode = "USD") {
 function resolveMedusaCartItemCurrencyCode(item, cartCurrencyCode) {
   return item?.cart?.currency_code ?? cartCurrencyCode ?? "usd";
 }
-function resolveMedusaCartItemTotal(item) {
-  const quantity = item?.quantity ?? 1;
-  const safeQuantity = typeof quantity === "number" && quantity > 0 ? quantity : 1;
-  const totalCandidates = [
-    item?.total,
-    item?.item_total,
-    item?.original_total,
-    item?.subtotal,
-    item?.item_subtotal,
-    item?.original_subtotal
-  ];
-  for (const candidate of totalCandidates) {
-    if (typeof candidate === "number" && Number.isFinite(candidate) && candidate > 0) {
+function resolveAuthoritativeLineTotal(item) {
+  const candidates = [item?.total, item?.item_total, item?.subtotal];
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
       return candidate;
     }
   }
-  const unitCandidates = [
-    item?.unit_price,
-    item?.original_unit_price
-  ];
-  for (const candidate of unitCandidates) {
-    if (typeof candidate === "number" && Number.isFinite(candidate) && candidate > 0) {
-      return candidate * safeQuantity;
-    }
-  }
-  return 0;
+  return void 0;
 }
 function transformCartItem(item, cartCurrencyCode) {
   const variant = item.variant;
   const product = variant?.product;
   const currencyCode = resolveMedusaCartItemCurrencyCode(item, cartCurrencyCode);
-  const totalCents = resolveMedusaCartItemTotal(item);
   const merchandiseId = variant?.id ?? item.variant_id ?? "";
   const merchandiseTitle = variant?.title ?? item.variant_title ?? "";
   const productId = product?.id ?? item.product_id ?? "";
@@ -1164,7 +1178,9 @@ function transformCartItem(item, cartCurrencyCode) {
     id: item.id,
     quantity: item.quantity ?? 1,
     cost: {
-      totalAmount: transformMoney(totalCents, currencyCode)
+      totalAmount: transformAmount(resolveAuthoritativeLineTotal(item), currencyCode),
+      // Backend unit price, carried so the display never derives it locally.
+      unitPrice: transformAmount(item?.unit_price, currencyCode)
     },
     merchandise: {
       id: merchandiseId,
@@ -1183,19 +1199,30 @@ function transformCartItem(item, cartCurrencyCode) {
   };
 }
 function transformCart(cart) {
-  const currencyCode = cart.currency_code ?? "usd";
+  const currencyCode = cart.currency_code;
   return {
     id: cart.id,
     checkoutUrl: `/checkout/${cart.id}`,
     // Medusa doesn't have a direct checkout URL
     cost: {
-      subtotalAmount: transformMoney(cart.subtotal, currencyCode),
-      totalAmount: transformMoney(cart.total, currencyCode),
-      totalTaxAmount: transformMoney(cart.tax_total, currencyCode)
+      subtotalAmount: transformAmount(
+        typeof cart.item_subtotal === "number" ? cart.item_subtotal : cart.subtotal,
+        currencyCode
+      ),
+      discountAmount: transformAmount(cart.discount_total, currencyCode),
+      totalTaxAmount: transformAmount(cart.tax_total, currencyCode),
+      shippingAmount: transformAmount(cart.shipping_total, currencyCode),
+      totalAmount: transformAmount(cart.total, currencyCode)
     },
     lines: cart.items?.map((item) => transformCartItem(item, currencyCode)) ?? [],
     totalQuantity: cart.items?.reduce((sum, item) => sum + (item.quantity ?? 0), 0) ?? 0,
-    completedAt: cart.completed_at ? typeof cart.completed_at === "string" ? cart.completed_at : cart.completed_at?.toISOString() : void 0
+    salesChannelId: cart.sales_channel_id ?? void 0,
+    regionId: cart.region_id ?? void 0,
+    currencyCode: typeof currencyCode === "string" ? currencyCode.toUpperCase() : void 0,
+    selectedShippingMethodId: cart.shipping_methods?.[0]?.id ?? void 0,
+    selectedShippingOptionId: cart.shipping_methods?.[0]?.shipping_option_id ?? void 0,
+    completedAt: cart.completed_at ? typeof cart.completed_at === "string" ? cart.completed_at : cart.completed_at?.toISOString() : void 0,
+    metadata: cart.metadata ?? void 0
   };
 }
 function transformCollection(collection) {
@@ -1284,8 +1311,8 @@ function transformOrderItem(item, currencyCode) {
     title: item.product_title ?? item.title ?? "",
     variantTitle: item.variant_title ?? variant?.title ?? void 0,
     quantity: item.quantity ?? 1,
-    price: transformMoney(item.unit_price, currencyCode),
-    total: transformMoney(item.total, currencyCode),
+    price: transformAmount(item.unit_price, currencyCode),
+    total: transformAmount(item.total, currencyCode),
     sku: variant?.sku ?? void 0,
     image: product?.thumbnail || item.thumbnail ? transformImage(product?.thumbnail || item.thumbnail, item.product_title ?? "") : void 0,
     productId: item.product_id ?? product?.id ?? void 0,
@@ -1336,12 +1363,19 @@ function transformOrder(order) {
     customer: order.customer ? transformCustomer(order.customer, order.email) : void 0,
     // Items
     items: (order.items ?? []).filter((item) => item != null).map((item) => transformOrderItem(item, currencyCode)) ?? [],
-    // Pricing
-    subtotal: transformMoney(order.subtotal, currencyCode),
-    total: transformMoney(order.total, currencyCode),
-    tax: transformMoney(order.tax_total, currencyCode),
-    shipping: transformMoney(order.shipping_total, currencyCode),
-    discount: transformMoney(order.discount_total, currencyCode),
+    // Pricing — backend-authoritative; a legitimate zero is preserved and no
+    // amount is derived locally. `subtotal` prefers the backend's
+    // `item_subtotal` (lines only, excluding shipping/tax); Medusa's native
+    // `subtotal` folds in `shipping_subtotal`, so falling back to it is only
+    // for installs that do not supply `item_subtotal`.
+    subtotal: transformAmount(
+      typeof order.item_subtotal === "number" ? order.item_subtotal : order.subtotal,
+      currencyCode
+    ),
+    total: transformAmount(order.total, currencyCode),
+    tax: transformAmount(order.tax_total, currencyCode),
+    shipping: transformAmount(order.shipping_total, currencyCode),
+    discount: transformAmount(order.discount_total, currencyCode),
     // Addresses (transformed to camelCase)
     shippingAddress: order.shipping_address ? transformAddress(order.shipping_address) : void 0,
     billingAddress: order.billing_address ? transformAddress(order.billing_address) : void 0,
@@ -1760,7 +1794,6 @@ function assertEntityBelongsToChannel(entity, expectedChannelId) {
 
 // src/providers/medusa/index.ts
 var import_js_sdk2 = __toESM(require("@medusajs/js-sdk"));
-var import_types = require("@thorprovider/types");
 
 // src/providers/medusa/auth.ts
 var AuthStorageManager = class {
@@ -2290,10 +2323,156 @@ async function getPaymentMethods(sdk, options) {
 }
 
 // src/providers/medusa/index.ts
-var MEDUSA_CART_RETRIEVE_FIELDS = "+items,+items.variant,+items.variant.product,+items.variant.product.thumbnail,+items.variant.options,+items.variant.options.option";
+var MEDUSA_CART_RETRIEVE_FIELDS = "+items,+items.variant,+items.variant.product,+items.variant.product.thumbnail,+items.variant.options,+items.variant.options.option,+items.total,+items.unit_price,+items.item_subtotal,+items.item_total,+shipping_methods,+shipping_methods.id,+shipping_methods.shipping_option_id";
+var MEDUSA_ORDER_COMPLETION_FIELDS = "*items";
+var DEFAULT_CATALOG_PAGE_SIZE = 50;
+function resolveCatalogPageSize(configured) {
+  const fromEnv = process.env.MEDUSA_CATALOG_PAGE_SIZE !== void 0 ? Number(process.env.MEDUSA_CATALOG_PAGE_SIZE) : void 0;
+  const raw = configured ?? fromEnv;
+  if (raw === void 0 || !Number.isFinite(raw) || raw < 1) {
+    return DEFAULT_CATALOG_PAGE_SIZE;
+  }
+  return Math.floor(raw);
+}
+function resolveConfiguredSalesChannelId() {
+  return process.env.MEDUSA_SALES_CHANNEL_ID ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+}
+var MEDUSA_SORT_KEY_MAP = {
+  featured: null,
+  name: "title",
+  newest: "-created_at",
+  "price-asc": null,
+  "price-desc": null,
+  rating: null
+};
+function resolveEffectiveCategoryHandles(query) {
+  const { categoryScope, categories } = query;
+  if (categoryScope === void 0) return categories;
+  if (categories === void 0) return [categoryScope];
+  return categories.filter((handle) => handle === categoryScope);
+}
+function buildAppliedCatalogFilters(query, effectiveCategoryHandles, includeAdvanced = false) {
+  return {
+    ...query.text ? { text: query.text } : {},
+    ...effectiveCategoryHandles !== void 0 ? { categories: effectiveCategoryHandles } : {},
+    ...query.collections !== void 0 ? { collections: query.collections } : {},
+    ...includeAdvanced && query.priceMin !== void 0 ? { priceMin: query.priceMin } : {},
+    ...includeAdvanced && query.priceMax !== void 0 ? { priceMax: query.priceMax } : {},
+    ...includeAdvanced && query.inStock !== void 0 ? { inStock: query.inStock } : {},
+    ...includeAdvanced && query.attributes !== void 0 ? { attributes: query.attributes } : {}
+  };
+}
+function buildBasicDemonstratedQuery(query) {
+  return {
+    ...query.text !== void 0 ? { text: query.text } : {},
+    ...query.categoryScope !== void 0 ? { categoryScope: query.categoryScope } : {},
+    ...query.categories !== void 0 ? { categories: query.categories } : {},
+    ...query.collections !== void 0 ? { collections: query.collections } : {}
+  };
+}
+var ADVANCED_SEARCH_ENDPOINT = "/store/search";
+var BASIC_LISTING_ENDPOINT = "/store/products";
+function collectRequestedAdvancedFields(query) {
+  const fields = [];
+  if (query.priceMin !== void 0) fields.push("priceMin");
+  if (query.priceMax !== void 0) fields.push("priceMax");
+  if (query.inStock !== void 0) fields.push("inStock");
+  for (const name of Object.keys(query.attributes ?? {})) {
+    fields.push(`attr.${name}`);
+  }
+  return fields;
+}
+function advancedFieldToFacet(field) {
+  if (field === "priceMin" || field === "priceMax") return "price";
+  return field;
+}
+function collectAdvancedSearchRequestFields(options) {
+  const fields = [];
+  if (options?.priceMin !== void 0) fields.push("priceMin");
+  if (options?.priceMax !== void 0) fields.push("priceMax");
+  if (options?.inStockOnly === true) fields.push("inStock");
+  if (options?.attributes && options.attributes.length > 0) {
+    fields.push("attributes");
+  }
+  return fields;
+}
+function toFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : void 0;
+  }
+  return void 0;
+}
+function readAppliedPriceRange(applied) {
+  const range = applied.price_range;
+  if (!range || typeof range !== "object" || Array.isArray(range)) return {};
+  const record = range;
+  return { min: toFiniteNumber(record.min), max: toFiniteNumber(record.max) };
+}
+function mapAppliedFiltersToFacets(applied) {
+  const facets = /* @__PURE__ */ new Set();
+  const priceRange = readAppliedPriceRange(applied);
+  const hasAppliedPriceRange = priceRange.min !== void 0 && priceRange.max !== void 0;
+  if (hasAppliedPriceRange || "price" in applied || "price_min" in applied || "price_max" in applied) {
+    facets.add("price");
+  }
+  if (typeof applied.is_available === "boolean" || "inStock" in applied || "isAvailable" in applied || "available" in applied) {
+    facets.add("inStock");
+  }
+  const attributes = applied.attributes;
+  if (attributes && typeof attributes === "object" && !Array.isArray(attributes)) {
+    for (const name of Object.keys(attributes)) {
+      facets.add(`attr.${name}`);
+    }
+  }
+  return facets;
+}
+function collectUnappliedAdvancedFields(applied, query) {
+  const unapplied = [];
+  const priceRange = readAppliedPriceRange(applied);
+  if (query.priceMin !== void 0) {
+    const echoed = toFiniteNumber(
+      priceRange.min ?? applied.price_min ?? applied.priceMin
+    );
+    if (echoed !== query.priceMin) unapplied.push("priceMin");
+  }
+  if (query.priceMax !== void 0) {
+    const echoed = toFiniteNumber(
+      priceRange.max ?? applied.price_max ?? applied.priceMax
+    );
+    if (echoed !== query.priceMax) unapplied.push("priceMax");
+  }
+  if (query.inStock === true) {
+    const echoed = applied.is_available ?? applied.isAvailable ?? applied.inStock ?? applied.available;
+    if (echoed !== true && echoed !== "true") unapplied.push("inStock");
+  }
+  const requestedAttributes = query.attributes ?? {};
+  const appliedAttributes = applied.attributes;
+  for (const name of Object.keys(requestedAttributes)) {
+    const hasName = !!appliedAttributes && typeof appliedAttributes === "object" && !Array.isArray(appliedAttributes) && name in appliedAttributes;
+    if (!hasName) unapplied.push(`attr.${name}`);
+  }
+  return unapplied;
+}
+function readFiniteFacetNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
 var MedusaProvider = class {
   name = "medusa";
   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.
+   */
+  supportedCatalogSortKeys = ["featured", "name", "newest"];
   /**
    * Medusa backend capabilities.
    * Starts with static defaults, replaced by dynamic values from
@@ -2315,6 +2494,14 @@ var MedusaProvider = class {
   baseUrl;
   publishableKey;
   regionId;
+  /** Configured per-request catalog listing bound (never an unbounded scan). */
+  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).
+   */
+  facetSupportCache = /* @__PURE__ */ new Map();
   /** Secret API key for admin operations (if configured). */
   adminApiKey;
   /**
@@ -2359,6 +2546,7 @@ var MedusaProvider = class {
     this.baseUrl = config.baseUrl;
     this.publishableKey = config.publishableKey;
     this.regionId = config.regionId;
+    this.catalogPageSize = resolveCatalogPageSize(config.catalogPageSize);
     this.retryConfig = {
       maxRetries: config.retry?.maxRetries ?? 3,
       timeoutMs: config.retry?.timeoutMs ?? 1e4,
@@ -2380,7 +2568,16 @@ var MedusaProvider = class {
       debug: config.debug ?? false,
       // Always use JWT mode for auth - SDK needs to send Bearer tokens
       // Configure storage method for JWT tokens (browser only)
-      auth: config.auth ? {
+      auth: config.auth ? config.auth.customStorage ? {
+        type: "jwt",
+        // Request-scoped custom storage: the caller supplies a per-request
+        // token holder (for example a server request's customer JWT). The
+        // SDK reads the token on every request and writes the login /
+        // registration token back into the same holder, so a fresh
+        // provider per request is authenticated without shared state.
+        jwtTokenStorageMethod: "custom",
+        storage: config.auth.customStorage
+      } : {
         type: "jwt",
         // Use localStorage in browser, memory storage on server
         jwtTokenStorageMethod: typeof window !== "undefined" ? "local" : "memory"
@@ -2488,35 +2685,52 @@ var MedusaProvider = class {
     }
     throw lastError;
   }
+  /** Fields needed to price a product variant for the current region. */
+  buildProductFields(regionId) {
+    const baseFields = "+variants,+variants.inventory_quantity,+options,+images,+tags";
+    const pricingFields = ",+variants.calculated_price,+variants.prices";
+    return regionId ? baseFields + pricingFields : baseFields;
+  }
+  /** Scope a store query to the configured storefront sales channel, if any. */
+  applySalesChannelScope(queryParams) {
+    const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+    if (salesChannelId) {
+      queryParams.sales_channel_id = [salesChannelId];
+    }
+  }
+  /**
+   * 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.
+   */
+  async fetchSingleProduct(filter, options) {
+    const regionId = options?.regionId ?? this.regionId;
+    const queryParams = {
+      ...filter,
+      limit: 1,
+      fields: this.buildProductFields(regionId)
+    };
+    if (regionId) {
+      queryParams.region_id = regionId;
+    }
+    this.applySalesChannelScope(queryParams);
+    const { products } = await this.sdk.store.product.list(queryParams);
+    if (!products || products.length === 0) {
+      this.logger.debug("Product not found", filter);
+      return void 0;
+    }
+    return transformProduct(products[0], this.currencyCode);
+  }
   async getProduct(handle, options) {
     this.logger.debug("getProduct", { handle, regionId: options?.regionId });
     try {
       return await this.withRetry(
-        async () => {
-          const regionId = options?.regionId ?? this.regionId;
-          const baseFields = "+variants,+variants.inventory_quantity,+options,+images,+tags";
-          const pricingFields = ",+variants.calculated_price,+variants.prices";
-          const fields = regionId ? baseFields + pricingFields : baseFields;
-          const queryParams = {
-            handle,
-            limit: 1,
-            fields
-          };
-          if (regionId) {
-            queryParams.region_id = regionId;
-          }
-          const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
-          if (salesChannelId) {
-            queryParams.sales_channel_id = [salesChannelId];
-          }
-          const { products } = await this.sdk.store.product.list(queryParams);
-          if (!products || products.length === 0) {
-            this.logger.debug("Product not found", { handle });
-            return void 0;
-          }
-          const transformedProduct = transformProduct(products[0], this.currencyCode);
-          return transformedProduct;
-        },
+        () => this.fetchSingleProduct({ handle }, options),
         "getProduct",
         { handle, regionId: options?.regionId }
       );
@@ -2528,6 +2742,26 @@ var MedusaProvider = class {
       );
     }
   }
+  /**
+   * Directed product lookup by backend product ID. Independent of the first
+   * listing page, mirroring `getProduct` for handle-based resolution.
+   */
+  async getProductById(id, options) {
+    this.logger.debug("getProductById", { id, regionId: options?.regionId });
+    try {
+      return await this.withRetry(
+        () => this.fetchSingleProduct({ id }, options),
+        "getProductById",
+        { id, regionId: options?.regionId }
+      );
+    } catch (error) {
+      throw new ProviderAPIError(
+        `Failed to fetch product by id: ${error.message}`,
+        "medusa",
+        error.status
+      );
+    }
+  }
   async getProducts(options = {}) {
     this.logger.debug("getProducts", options);
     try {
@@ -2537,28 +2771,14 @@ var MedusaProvider = class {
           const baseFields = "+variants,+variants.inventory_quantity,+options,+images,+tags";
           const pricingFields = ",+variants.calculated_price,+variants.prices";
           const fields = regionId ? baseFields + pricingFields : baseFields;
-          const SORT_KEY_MAP = {
-            featured: null,
-            // server default order
-            name: "title",
-            // A→Z by product title
-            newest: "-created_at",
-            // newest products first
-            "price-asc": null,
-            // not supported by native endpoint → client-side
-            "price-desc": null,
-            // not supported by native endpoint → client-side
-            rating: null
-            // not supported → server default
-          };
           const queryParams = {
             q: options.query,
-            limit: options.first ?? 100,
-            offset: options.after ? parseInt(String(options.after), 10) : void 0,
+            limit: options.first ?? this.catalogPageSize,
+            offset: options.after !== void 0 ? parseInt(String(options.after), 10) : options.skip,
             fields
           };
           if (options.sortKey) {
-            const mappedOrder = SORT_KEY_MAP[options.sortKey] ?? null;
+            const mappedOrder = MEDUSA_SORT_KEY_MAP[options.sortKey] ?? null;
             if (mappedOrder !== null) {
               queryParams.order = mappedOrder;
             }
@@ -2598,6 +2818,468 @@ var MedusaProvider = class {
       );
     }
   }
+  /**
+   * 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.
+   */
+  async getCatalogProducts(query) {
+    this.logger.debug("getCatalogProducts", query);
+    if (query.sort !== void 0 && !this.supportedCatalogSortKeys.includes(query.sort)) {
+      return this.unsupportedCatalogOutcome(["sort"]);
+    }
+    const effectiveCategoryHandles = resolveEffectiveCategoryHandles(query);
+    try {
+      const categoryIds = effectiveCategoryHandles !== void 0 ? await this.resolveCategoryIds(effectiveCategoryHandles) : void 0;
+      const collectionIds = query.collections ? await this.resolveCollectionIds(query.collections) : void 0;
+      const facetSupport = await this.getCatalogFacetSupport({
+        query,
+        categoryIds,
+        collectionIds,
+        scope: query.categoryScope
+      });
+      const requestedAdvanced = collectRequestedAdvancedFields(query);
+      const heldAdvanced = requestedAdvanced.filter(
+        (field) => !facetSupport.offered.includes(advancedFieldToFacet(field))
+      );
+      if (heldAdvanced.length > 0) {
+        return this.unsupportedCatalogOutcome(heldAdvanced);
+      }
+      const emptyIntersection = effectiveCategoryHandles !== void 0 && effectiveCategoryHandles.length === 0;
+      const categoryFilterEmpty = effectiveCategoryHandles !== void 0 && (categoryIds?.length ?? 0) === 0;
+      const collectionFilterEmpty = query.collections !== void 0 && (collectionIds?.length ?? 0) === 0;
+      if (emptyIntersection || categoryFilterEmpty || collectionFilterEmpty) {
+        return {
+          ok: true,
+          results: {
+            products: [],
+            appliedFilters: buildAppliedCatalogFilters(
+              query,
+              effectiveCategoryHandles,
+              requestedAdvanced.length > 0
+            ),
+            facetSupport
+          }
+        };
+      }
+      if (requestedAdvanced.length > 0) {
+        return this.queryAdvancedCatalog(
+          query,
+          categoryIds,
+          collectionIds,
+          facetSupport
+        );
+      }
+      return await this.queryBasicCatalog(
+        query,
+        effectiveCategoryHandles,
+        categoryIds,
+        collectionIds,
+        facetSupport
+      );
+    } catch (error) {
+      this.logger.error("getCatalogProducts error details", {
+        message: error.message,
+        status: error.status
+      });
+      throw new ProviderAPIError(
+        `Failed to run catalog query: ${error.message || "Unknown error"}`,
+        "medusa",
+        error.status
+      );
+    }
+  }
+  /**
+   * Execute a basic-only canonical query against the equivalent basic endpoint
+   * `/store/products`, reporting the filters it actually applied.
+   */
+  async queryBasicCatalog(query, effectiveCategoryHandles, categoryIds, collectionIds, facetSupport) {
+    const pageSize = query.pageSize ?? this.catalogPageSize;
+    const page = query.page ?? 1;
+    const regionId = this.regionId;
+    const baseFields = "+variants,+variants.inventory_quantity,+options,+images,+thumbnail,+tags";
+    const pricingFields = ",+variants.calculated_price,+variants.prices";
+    const queryParams = {
+      limit: pageSize,
+      offset: (page - 1) * pageSize,
+      fields: regionId ? baseFields + pricingFields : baseFields
+    };
+    if (query.text) {
+      queryParams.q = query.text;
+    }
+    if (categoryIds && categoryIds.length > 0) {
+      queryParams.category_id = categoryIds;
+    }
+    if (collectionIds && collectionIds.length > 0) {
+      queryParams.collection_id = collectionIds;
+    }
+    if (query.sort) {
+      const mappedOrder = MEDUSA_SORT_KEY_MAP[query.sort] ?? null;
+      if (mappedOrder !== null) {
+        queryParams.order = mappedOrder;
+      }
+    }
+    if (regionId) {
+      queryParams.region_id = regionId;
+    }
+    const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+    if (salesChannelId) {
+      queryParams.sales_channel_id = [salesChannelId];
+    }
+    const response = await this.sdk.store.product.list(queryParams);
+    const products = (response.products ?? []).map(
+      (p) => transformProduct(p, this.currencyCode)
+    );
+    const count = response.count;
+    return {
+      ok: true,
+      results: {
+        products,
+        // Total is only the backend's actual count; never manufactured.
+        ...typeof count === "number" ? { total: count } : {},
+        appliedFilters: buildAppliedCatalogFilters(
+          query,
+          effectiveCategoryHandles
+        ),
+        facetSupport
+      }
+    };
+  }
+  /**
+   * 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.
+   */
+  async queryAdvancedCatalog(query, categoryIds, collectionIds, facetSupport) {
+    const pageSize = query.pageSize ?? this.catalogPageSize;
+    const page = query.page ?? 1;
+    const advancedQuery = this.buildAdvancedSearchQuery(
+      query,
+      categoryIds ?? [],
+      collectionIds ?? []
+    );
+    advancedQuery.limit = pageSize;
+    advancedQuery.offset = (page - 1) * pageSize;
+    let data;
+    try {
+      data = await this.sdk.client.fetch(ADVANCED_SEARCH_ENDPOINT, {
+        query: advancedQuery
+      });
+    } catch (error) {
+      this.logger.error("Advanced catalog listing failed", {
+        message: error?.message,
+        status: error?.status
+      });
+      return this.unsupportedCatalogOutcome(
+        collectRequestedAdvancedFields(query)
+      );
+    }
+    const appliedRaw = data?.applied_filters ?? data?.appliedFilters;
+    if (!appliedRaw || typeof appliedRaw !== "object") {
+      this.logger.warn("Advanced endpoint did not echo applied filters", {
+        endpoint: ADVANCED_SEARCH_ENDPOINT
+      });
+      return this.unsupportedCatalogOutcome(
+        collectRequestedAdvancedFields(query)
+      );
+    }
+    const unapplied = collectUnappliedAdvancedFields(
+      appliedRaw,
+      query
+    );
+    if (unapplied.length > 0) {
+      this.logger.warn("Advanced endpoint did not apply requested filters", {
+        endpoint: ADVANCED_SEARCH_ENDPOINT,
+        fields: unapplied
+      });
+      return this.unsupportedCatalogOutcome(unapplied);
+    }
+    const products = (data.hits ?? []).map(
+      (hit) => transformProduct(hit, this.currencyCode)
+    );
+    const total = typeof data.estimatedTotalHits === "number" ? data.estimatedTotalHits : typeof data.count === "number" ? data.count : void 0;
+    return {
+      ok: true,
+      results: {
+        products,
+        ...total !== void 0 ? { total } : {},
+        appliedFilters: buildAppliedCatalogFilters(
+          query,
+          resolveEffectiveCategoryHandles(query),
+          true
+        ),
+        facetSupport
+      }
+    };
+  }
+  /** Resolve category handles to Medusa category IDs via directed lookups. */
+  async resolveCategoryIds(handles) {
+    const ids = [];
+    for (const handle of handles) {
+      const category = await this.getCategory(handle);
+      if (category) ids.push(category.id);
+    }
+    return ids;
+  }
+  /** Resolve collection handles to Medusa collection IDs via directed lookups. */
+  async resolveCollectionIds(handles) {
+    const ids = [];
+    for (const handle of handles) {
+      const collection = await this.getCollection(handle);
+      if (collection) ids.push(collection.id);
+    }
+    return ids;
+  }
+  /**
+   * 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.
+   */
+  async getCatalogFacetSupport(options = {}) {
+    const query = options.query ?? {};
+    const scope = options.scope ?? query.categoryScope;
+    const key = JSON.stringify({
+      scope: scope ?? null,
+      categoryIds: options.categoryIds ?? null,
+      collectionIds: options.collectionIds ?? null,
+      categories: query.categories ?? null,
+      text: query.text ?? null,
+      collections: query.collections ?? null,
+      priceMin: query.priceMin ?? null,
+      priceMax: query.priceMax ?? null,
+      inStock: query.inStock ?? null,
+      attributes: query.attributes ?? null
+    });
+    const cached = this.facetSupportCache.get(key);
+    if (cached) return cached;
+    const pending = this.resolveCatalogFacetSupport(
+      query,
+      options.categoryIds,
+      options.collectionIds,
+      scope
+    );
+    this.facetSupportCache.set(key, pending);
+    return pending;
+  }
+  async resolveCatalogFacetSupport(query, providedCategoryIds, providedCollectionIds, scope) {
+    const advancedDemonstratedQuery = {
+      ...query.text !== void 0 ? { text: query.text } : {},
+      ...query.categoryScope !== void 0 ? { categoryScope: query.categoryScope } : {},
+      ...query.categories !== void 0 ? { categories: query.categories } : {},
+      ...query.collections !== void 0 ? { collections: query.collections } : {},
+      ...query.priceMin !== void 0 ? { priceMin: query.priceMin } : {},
+      ...query.priceMax !== void 0 ? { priceMax: query.priceMax } : {},
+      ...query.inStock !== void 0 ? { inStock: query.inStock } : {},
+      ...query.attributes !== void 0 ? { attributes: query.attributes } : {}
+    };
+    const basicDemonstratedQuery = buildBasicDemonstratedQuery(query);
+    const scopeField = scope !== void 0 ? { scope } : {};
+    const offered = ["categories", "collections"];
+    const demonstrations = {
+      categories: {
+        endpoint: BASIC_LISTING_ENDPOINT,
+        appliedQuery: basicDemonstratedQuery,
+        ...scopeField
+      },
+      collections: {
+        endpoint: BASIC_LISTING_ENDPOINT,
+        appliedQuery: basicDemonstratedQuery,
+        ...scopeField
+      }
+    };
+    const held = [];
+    const heldReasons = {};
+    const categoryIds = providedCategoryIds ?? await this.resolveScopeCategoryIds(query);
+    const collectionIds = providedCollectionIds ?? (query.collections ? await this.resolveCollectionIds(query.collections) : []);
+    const candidates = ["price", "inStock"];
+    for (const handle of await this.resolveFilterableAttributeHandles(
+      categoryIds
+    )) {
+      const facet = `attr.${handle}`;
+      if (!candidates.includes(facet)) candidates.push(facet);
+    }
+    const probe = await this.probeAdvancedSearchSupport(
+      query,
+      categoryIds,
+      collectionIds
+    );
+    if (probe.available) {
+      for (const facet of candidates) {
+        if (probe.applied.has(facet)) {
+          offered.push(facet);
+          demonstrations[facet] = {
+            endpoint: ADVANCED_SEARCH_ENDPOINT,
+            appliedQuery: advancedDemonstratedQuery,
+            ...scopeField
+          };
+        } else {
+          held.push(facet);
+          heldReasons[facet] = `not echoed as applied by ${ADVANCED_SEARCH_ENDPOINT}`;
+        }
+      }
+    } else {
+      for (const facet of candidates) {
+        held.push(facet);
+        heldReasons[facet] = probe.reason;
+      }
+    }
+    return {
+      offered,
+      held,
+      demonstrations,
+      ...Object.keys(heldReasons).length > 0 ? { heldReasons } : {}
+    };
+  }
+  /**
+   * 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.
+   */
+  async probeAdvancedSearchSupport(query, categoryIds, collectionIds) {
+    const advancedQuery = this.buildAdvancedSearchQuery(
+      query,
+      categoryIds,
+      collectionIds
+    );
+    advancedQuery.limit = 1;
+    try {
+      const data = await this.sdk.client.fetch(ADVANCED_SEARCH_ENDPOINT, {
+        query: advancedQuery
+      });
+      const appliedRaw = data?.applied_filters ?? data?.appliedFilters;
+      if (!appliedRaw || typeof appliedRaw !== "object") {
+        return {
+          available: false,
+          applied: /* @__PURE__ */ new Set(),
+          reason: `${ADVANCED_SEARCH_ENDPOINT} did not echo applied filters; support unverified`
+        };
+      }
+      return {
+        available: true,
+        applied: mapAppliedFiltersToFacets(
+          appliedRaw
+        ),
+        reason: `${ADVANCED_SEARCH_ENDPOINT} demonstrated with the applied query`
+      };
+    } catch (error) {
+      const status = typeof error?.status === "number" ? error.status : void 0;
+      this.logger.warn("Optional advanced search endpoint not demonstrated", {
+        endpoint: ADVANCED_SEARCH_ENDPOINT,
+        status,
+        message: error?.message
+      });
+      return {
+        available: false,
+        applied: /* @__PURE__ */ new Set(),
+        reason: status !== void 0 ? `${ADVANCED_SEARCH_ENDPOINT} returned ${status}; optional advanced endpoint not demonstrated` : `${ADVANCED_SEARCH_ENDPOINT} unavailable: ${extractErrorMessage(error)}`,
+        ...status !== void 0 ? { status } : {}
+      };
+    }
+  }
+  /**
+   * Build the advanced-endpoint query parameters from the canonical query. The
+   * SDK serializes the plain object, so no manual stringification is needed.
+   */
+  buildAdvancedSearchQuery(query, categoryIds, collectionIds) {
+    const advancedQuery = {};
+    if (query.text) advancedQuery.q = query.text;
+    if (categoryIds.length > 0) advancedQuery.categories = categoryIds.join(",");
+    if (collectionIds.length > 0) {
+      advancedQuery.collections = collectionIds.join(",");
+    }
+    if (query.priceMin !== void 0) advancedQuery.price_min = query.priceMin;
+    if (query.priceMax !== void 0) advancedQuery.price_max = query.priceMax;
+    if (query.inStock === true) advancedQuery.isAvailable = true;
+    if (query.attributes) {
+      const attributes = Object.entries(query.attributes).map(([id, values]) => ({
+        id,
+        values
+      }));
+      advancedQuery.attributes = JSON.stringify(attributes);
+    }
+    if (query.sort) {
+      const mappedOrder = MEDUSA_SORT_KEY_MAP[query.sort] ?? null;
+      if (mappedOrder !== null) advancedQuery.order = mappedOrder;
+    }
+    if (this.regionId) advancedQuery.region_id = this.regionId;
+    if (this.currencyCode) {
+      advancedQuery.currency_code = this.currencyCode.toLowerCase();
+    }
+    return advancedQuery;
+  }
+  /** Resolve the effective category scope of a query to backend IDs. */
+  async resolveScopeCategoryIds(query) {
+    const handles = resolveEffectiveCategoryHandles(query);
+    if (handles === void 0 || handles.length === 0) return [];
+    return this.resolveCategoryIds(handles);
+  }
+  /**
+   * 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.
+   */
+  async resolveFilterableAttributeHandles(categoryIds) {
+    const handles = [];
+    for (const categoryId of categoryIds) {
+      try {
+        const data = await this.sdk.client.fetch(
+          `/store/custom-attributes/category/${categoryId}`
+        );
+        for (const item of data?.attributes ?? []) {
+          const attr = item.attribute ?? item;
+          if (attr?.is_filterable && attr?.is_active && typeof attr.handle === "string" && attr.handle.length > 0) {
+            handles.push(attr.handle);
+          }
+        }
+      } catch {
+      }
+    }
+    return handles;
+  }
+  /** Build a typed `unsupported-query` outcome naming the offending fields. */
+  unsupportedCatalogOutcome(fields) {
+    return {
+      ok: false,
+      error: {
+        code: "unsupported-query",
+        fields,
+        message: `Unsupported catalog query: ${fields.join(", ")}`,
+        repair: { remove: fields }
+      }
+    };
+  }
   async getProductRecommendations(productId) {
     this.logger.debug("getProductRecommendations", { productId });
     this.logger.warn("Product recommendations not yet implemented for Medusa");
@@ -2619,16 +3301,8 @@ var MedusaProvider = class {
   async searchProductsAdvanced(options) {
     this.logger.debug("searchProductsAdvanced", options);
     if (!this.capabilities.advancedSearch) {
-      this.logger.warn("Advanced search not available, falling back to getProducts()");
-      const products = await this.getProducts(options);
-      return {
-        products,
-        meta: {
-          limit: options?.first ?? 20,
-          offset: Number(options?.after ?? 0),
-          hybridSearchUsed: false
-        }
-      };
+      this.logger.warn("Advanced search capability disabled, using faithful fallback");
+      return this.fallbackAdvancedSearch(options);
     }
     try {
       const queryParams = {};
@@ -2728,20 +3402,39 @@ var MedusaProvider = class {
       });
       return { products, meta };
     } catch (error) {
-      this.logger.error("Advanced search failed, falling back to getProducts()", {
+      this.logger.error("Advanced search failed, using faithful fallback", {
         error: error.message,
         stack: error.stack
       });
-      const products = await this.getProducts(options);
-      return {
-        products,
-        meta: {
-          limit: options?.first ?? 20,
-          offset: Number(options?.after ?? 0),
-          hybridSearchUsed: false
-        }
-      };
+      return this.fallbackAdvancedSearch(options);
+    }
+  }
+  /**
+   * 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).
+   */
+  async fallbackAdvancedSearch(options) {
+    const requested = collectAdvancedSearchRequestFields(options);
+    if (requested.length > 0) {
+      throw new ProviderAPIError(
+        `Advanced search unavailable for requested fields: ${requested.join(", ")}`,
+        "medusa",
+        void 0,
+        { fields: requested, repair: { remove: requested } }
+      );
     }
+    const products = await this.getProducts(options);
+    return {
+      products,
+      meta: {
+        limit: options?.first ?? 20,
+        offset: Number(options?.after ?? 0),
+        hybridSearchUsed: false
+      }
+    };
   }
   /**
    * Get available filter options for product filtering
@@ -2796,23 +3489,20 @@ var MedusaProvider = class {
           });
         }
       }
-      if (options.useAdvancedSearch && this.capabilities.advancedSearch) {
-        filters.push({
-          id: "price",
-          label: "Price",
-          type: "range",
-          min: 0,
-          max: 1e4,
-          isActive: false,
-          ranking: 0
-        });
-        filters.push({
-          id: "isAvailable",
-          label: "In Stock",
-          type: "boolean",
-          isActive: false,
-          ranking: 5
+      if (options.useAdvancedSearch) {
+        const support = await this.getCatalogFacetSupport({
+          categoryIds: options.categoryId ? [options.categoryId] : [],
+          scope: options.categoryId
         });
+        if (support.offered.includes("inStock")) {
+          filters.push({
+            id: "isAvailable",
+            label: "In Stock",
+            type: "boolean",
+            isActive: false,
+            ranking: 5
+          });
+        }
       }
       if (options.categoryId && this.capabilities.customAttributes) {
         try {
@@ -2847,19 +3537,27 @@ var MedusaProvider = class {
                 // Custom attributes lower priority
               };
               if ((filterType === "single" || filterType === "multi") && attr.values) {
-                filter.options = attr.values.map((val) => ({
-                  value: this.toSlug(val.value),
-                  // URL slug: ?ram=8gb
-                  label: val.value,
-                  // Display: "8GB"
-                  id: val.id,
-                  // Backend ID: 01KN03N67V13K5S2E6B6695KRN
-                  count: options.includeFacetCounts ? val.count : void 0
-                }));
+                filter.options = attr.values.map((val) => {
+                  const count = options.includeFacetCounts ? readFiniteFacetNumber(val.count) : void 0;
+                  return {
+                    value: this.toSlug(val.value),
+                    // URL slug: ?ram=8gb
+                    label: val.value,
+                    // Display: "8GB"
+                    id: val.id,
+                    // Backend ID: 01KN03N67V13K5S2E6B6695KRN
+                    ...count !== void 0 ? { count } : {}
+                  };
+                });
               }
-              if (filterType === "range" && attr.metadata) {
-                filter.min = attr.metadata.min || 0;
-                filter.max = attr.metadata.max || 100;
+              if (filterType === "range") {
+                const min = readFiniteFacetNumber(attr.metadata?.min);
+                const max = readFiniteFacetNumber(attr.metadata?.max);
+                if (min === void 0 || max === void 0) {
+                  return;
+                }
+                filter.min = min;
+                filter.max = max;
               }
               filters.push(filter);
             });
@@ -3221,7 +3919,7 @@ var MedusaProvider = class {
       return customFetcher(options);
     }
     try {
-      const limit = options.query ? 1e3 : options.limit ?? 100;
+      const limit = options.limit ?? this.catalogPageSize;
       const queryParams = {
         limit,
         include_descendants_tree: options.includeDescendants ?? false
@@ -3261,11 +3959,15 @@ var MedusaProvider = class {
       }
       const categoryQueryParams = {
         category_id: [category.id],
-        order: options.sortKey,
-        limit: options.first ?? 100,
+        // Bounded, paginated listing (change B, decision 5).
+        limit: options.first ?? this.catalogPageSize,
         offset: options.after ? parseInt(options.after, 10) : void 0,
-        fields: "+variants,+variants.prices,+variants.calculated_prices,+variants.inventory_quantity,+options,+images,+tags"
+        fields: "+variants,+variants.prices,+variants.calculated_price,+variants.inventory_quantity,+options,+images,+tags"
       };
+      const mappedOrder = options.sortKey ? MEDUSA_SORT_KEY_MAP[options.sortKey] ?? null : null;
+      if (mappedOrder !== null) {
+        categoryQueryParams.order = mappedOrder;
+      }
       if (this.regionId) {
         categoryQueryParams.region_id = this.regionId;
       }
@@ -3300,7 +4002,7 @@ var MedusaProvider = class {
       } else {
         createPayload.currency_code = this.currencyCode.toLowerCase();
       }
-      const salesChannelId = options?.salesChannelId ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+      const salesChannelId = options?.salesChannelId ?? resolveConfiguredSalesChannelId();
       if (salesChannelId) {
         createPayload.sales_channel_id = salesChannelId;
       }
@@ -3371,7 +4073,7 @@ var MedusaProvider = class {
             fields: "+variants,+variants.calculated_price,+variants.prices,+variants.money_amounts",
             region_id: backendCart.region_id
           };
-          const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+          const salesChannelId = resolveConfiguredSalesChannelId();
           if (salesChannelId) {
             variantCheckParams.sales_channel_id = [salesChannelId];
           }
@@ -4487,31 +5189,84 @@ var MedusaProvider = class {
    * @throws {ProviderAPIError} If checkout fails
    */
   async completeCheckout(cartId) {
-    this.logger.debug("completeCheckout", { cartId });
-    try {
-      return await this.withRetry(
-        async () => {
-          const { order } = await this.sdk.store.cart.complete(cartId);
-          if (!order) {
-            throw new ProviderAPIError("Checkout completed but no order returned", "medusa", 500);
-          }
-          this.logger.info("Checkout completed successfully", {
-            orderId: order.id,
-            displayId: order.display_id
-          });
-          return transformOrder(order);
-        },
-        "completeCheckout",
-        { cartId }
-      );
-    } catch (error) {
-      this.logger.error("Failed to complete checkout", { cartId, error: error.message });
+    const result = await this.completeCart(cartId);
+    if (result.type === "order") {
+      return result.order;
+    }
+    if (result.type === "cart") {
       throw new ProviderAPIError(
-        `Failed to complete checkout: ${error.message}`,
+        `Failed to complete checkout: ${result.error.message}`,
         "medusa",
-        error.status
+        result.error.status
       );
     }
+    throw new ProviderAPIError(
+      `Checkout outcome is unresolved: ${result.error.message}`,
+      "medusa",
+      result.error.status
+    );
+  }
+  /**
+   * 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.
+   */
+  async completeCart(cartId) {
+    this.logger.debug("completeCart", { cartId });
+    try {
+      const response = await this.sdk.store.cart.complete(cartId, {
+        fields: MEDUSA_ORDER_COMPLETION_FIELDS
+      });
+      if (response?.type === "cart" || response?.cart && response?.error) {
+        const error = this.toCompletionError(response.error);
+        this.logger.warn("Cart completion returned a cart with an error", {
+          cartId,
+          code: error.code,
+          message: error.message
+        });
+        return { type: "cart", cart: transformCart(response.cart), error };
+      }
+      const order = response?.order;
+      if (!order) {
+        return {
+          type: "unresolved",
+          error: { message: "Checkout returned neither an order nor a cart error" }
+        };
+      }
+      this.logger.info("Checkout completed successfully", {
+        orderId: order.id,
+        displayId: order.display_id
+      });
+      return { type: "order", order: transformOrder(order) };
+    } catch (error) {
+      const completionError = this.toCompletionError(error);
+      this.logger.error("Cart completion failed (unresolved, not retried)", {
+        cartId,
+        status: completionError.status,
+        message: completionError.message
+      });
+      return { type: "unresolved", error: completionError };
+    }
+  }
+  /** Normalize any thrown/returned completion failure into a structured error. */
+  toCompletionError(error) {
+    if (error && typeof error === "object") {
+      const err = error;
+      const message = typeof err.message === "string" && err.message.length > 0 ? err.message : extractErrorMessage(error);
+      return {
+        message,
+        code: typeof err.code === "string" ? err.code : void 0,
+        status: err.status ?? err.statusCode,
+        raw: err
+      };
+    }
+    return { message: extractErrorMessage(error), raw: error };
   }
   /**
    * Get available shipping methods for cart
@@ -4523,130 +5278,66 @@ var MedusaProvider = class {
    * @throws {ProviderAPIError} If cart not found or region not configured
    */
   async getShippingMethods(cartId) {
-    this.logger.info("\u{1F69A} [DEBUG] getShippingMethods called", { cartId });
+    this.logger.debug("getShippingMethods", { cartId });
     try {
       return await this.withRetry(
         async () => {
-          this.logger.info("\u{1F69A} [DEBUG] Step 1: Retrieving cart from Medusa...", { cartId });
           const cartResponse = await this.sdk.store.cart.retrieve(cartId);
           const { cart } = cartResponse;
-          this.logger.info("\u{1F69A} [DEBUG] Step 2: Cart retrieved from backend", {
-            cartId,
-            hasCart: !!cart,
-            cartKeys: cart ? Object.keys(cart) : [],
-            regionId: cart?.region_id,
-            currencyCode: cart?.currency_code,
-            shippingAddress: cart?.shipping_address ? {
-              country: cart.shipping_address.country_code,
-              postal: cart.shipping_address.postal_code
-            } : null
-          });
           if (!cart) {
-            this.logger.error("\u{1F69A} [DEBUG] ERROR: Cart not found in response", {
-              cartId,
-              cartResponse
-            });
             throw new ResourceNotFoundError("Cart", cartId);
           }
           if (!cart.region_id) {
-            this.logger.error("\u{1F69A} [DEBUG] ERROR: Cart has no region_id", {
-              cartId,
-              cart: {
-                id: cart.id,
-                region_id: cart.region_id,
-                region: cart.region,
-                allKeys: Object.keys(cart)
-              }
-            });
             throw new ProviderAPIError("Cart has no region assigned", "medusa", 400);
           }
-          this.logger.info("\u{1F69A} [DEBUG] Step 3: Fetching shipping options from Medusa...", {
-            cartId,
-            regionId: cart.region_id,
-            endpoint: `${this.baseUrl}store/shipping-options?cart_id=${cartId}`,
-            note: "About to fetch shipping options (SDK when available, otherwise HTTP)"
-          });
-          let shippingResponse;
-          let shipping_options;
-          try {
-            const storeAny = this.sdk.store;
-            if (storeAny?.shippingOption?.list) {
-              shippingResponse = await storeAny.shippingOption.list({
-                cart_id: cartId
-              });
-            } else {
-              const baseUrl = this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`;
-              const url = new URL("store/shipping-options", baseUrl);
-              url.searchParams.set("cart_id", cartId);
-              const response = await fetchWithRetry(
-                url.toString(),
-                {
-                  method: "GET",
-                  headers: {
-                    "x-publishable-api-key": this.publishableKey,
-                    "content-type": "application/json"
-                  }
-                },
-                this.retryConfig
-              );
-              shippingResponse = await response.json();
-            }
-            shipping_options = shippingResponse.shipping_options;
-          } catch (sdkError) {
-            this.logger.error(
-              "\u{1F69A} [DEBUG] ERROR: Medusa SDK threw error when fetching shipping options",
+          let shippingOptions = [];
+          const storeAny = this.sdk.store;
+          if (storeAny?.fulfillment?.listCartOptions) {
+            const response = await storeAny.fulfillment.listCartOptions({
+              cart_id: cartId
+            });
+            shippingOptions = response?.shipping_options ?? [];
+          } else {
+            const baseUrl = this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`;
+            const url = new URL("store/shipping-options", baseUrl);
+            url.searchParams.set("cart_id", cartId);
+            const response = await fetchWithRetry(
+              url.toString(),
               {
-                cartId,
-                regionId: cart.region_id,
-                errorType: sdkError?.constructor?.name,
-                errorMessage: sdkError?.message,
-                errorStatus: sdkError?.status,
-                errorCode: sdkError?.code,
-                errorResponse: sdkError?.response ? JSON.stringify(sdkError.response, null, 2) : "N/A",
-                errorBody: sdkError?.body ? JSON.stringify(sdkError.body, null, 2) : "N/A",
-                fullError: JSON.stringify(sdkError, Object.getOwnPropertyNames(sdkError), 2)
-              }
+                method: "GET",
+                headers: {
+                  "x-publishable-api-key": this.publishableKey,
+                  "content-type": "application/json"
+                }
+              },
+              this.retryConfig
             );
-            throw sdkError;
+            shippingOptions = (await response.json())?.shipping_options ?? [];
           }
-          this.logger.info("\u{1F69A} [DEBUG] Step 4: Shipping options received from backend", {
-            cartId,
-            totalOptions: shipping_options?.length || 0,
-            rawResponse: JSON.stringify(shippingResponse, null, 2),
-            firstOption: shipping_options?.[0] ? {
-              id: shipping_options[0].id,
-              name: shipping_options[0].name,
-              allKeys: Object.keys(shipping_options[0]),
-              price_incl_tax: shipping_options[0].price_incl_tax,
-              amount: shipping_options[0].amount,
-              data: shipping_options[0].data
-            } : null
-          });
-          const methods = shipping_options.map((option) => ({
-            id: option.id,
-            name: option.name,
-            price: {
-              amount: option.price_incl_tax?.toString() || option.amount?.toString() || "0",
-              currencyCode: cart.currency_code?.toUpperCase() || this.currencyCode
-            },
-            description: option.data?.description,
-            estimatedDays: option.data?.estimated_days || "N/A"
-          }));
-          this.logger.info("\u{1F69A} [DEBUG] Step 5: Transformed methods for Thor types", {
-            cartId,
-            count: methods.length,
-            methods: JSON.stringify(methods, null, 2)
+          const currencyCode = cart.currency_code?.toUpperCase() ?? "";
+          return shippingOptions.map((option) => {
+            const amount = option?.amount ?? option?.price_incl_tax;
+            const estimatedDays = option?.data?.estimated_days != null ? String(option.data.estimated_days) : void 0;
+            return {
+              id: option.id,
+              name: option.name,
+              price: {
+                amount: typeof amount === "number" && Number.isFinite(amount) ? amount.toFixed(2) : "",
+                currencyCode
+              },
+              description: option?.data?.description,
+              estimatedDays,
+              fulfillmentSetType: option?.service_zone?.fulfillment_set?.type ?? null
+            };
           });
-          return methods;
         },
         "getShippingMethods",
         { cartId }
       );
     } catch (error) {
-      this.logger.error("\u{1F69A} [DEBUG] ERROR: Failed to fetch shipping methods", {
+      this.logger.error("Failed to fetch shipping methods", {
         cartId,
         errorMessage: error.message,
-        errorStack: error.stack,
         errorStatus: error.status
       });
       throw new ProviderAPIError(
@@ -5007,19 +5698,12 @@ var MedusaProvider = class {
   async addShippingMethod(cartId, methodId) {
     this.logger.debug("addShippingMethod", { cartId, methodId });
     try {
-      return await this.withRetry(
-        async () => {
-          const { cart } = await this.sdk.store.cart.addShippingMethod(cartId, {
-            option_id: methodId
-          });
-          this.logger.info("Shipping method added successfully", { cartId, methodId });
-          void cart;
-          const updatedCart = await this.retrieveCartWithLineDetails(cartId);
-          return transformCart(updatedCart);
-        },
-        "addShippingMethod",
-        { cartId, methodId }
-      );
+      await this.sdk.store.cart.addShippingMethod(cartId, {
+        option_id: methodId
+      });
+      this.logger.info("Shipping method added successfully", { cartId, methodId });
+      const updatedCart = await this.retrieveCartWithLineDetails(cartId);
+      return transformCart(updatedCart);
     } catch (error) {
       this.logger.error("Failed to add shipping method", {
         cartId,
@@ -5043,166 +5727,75 @@ var MedusaProvider = class {
    * @throws {ProviderAPIError} If provider invalid or cart not ready
    */
   async initiatePaymentSession(cartId, providerId) {
-    this.logger.info("\u{1F4B3} [DEBUG] initiatePaymentSession called", { cartId, providerId });
+    this.logger.debug("initiatePaymentSession", { cartId, providerId });
     try {
-      await this.withRetry(
-        async () => {
-          this.logger.info(
-            "\u{1F4B3} [DEBUG] Step 1: Retrieving RAW cart from Medusa for payment session...",
-            { cartId }
-          );
-          const { cart: rawCart } = await this.sdk.store.cart.retrieve(cartId, {
-            fields: "+shipping_methods,+shipping_address,+email,+region_id,+total,+items,+payment_collection,+payment_collection.payment_sessions,+billing_address"
-          });
-          this.logger.info("\u{1F4B3} [DEBUG] Step 2: RAW cart retrieved, checking state...", {
-            cartId: rawCart.id,
-            hasShippingMethod: !!rawCart.shipping_methods?.length,
-            shippingMethodIds: rawCart.shipping_methods?.map((sm) => sm.id) || [],
-            hasShippingAddress: !!rawCart.shipping_address,
-            shippingAddressCity: rawCart.shipping_address?.city || "N/A",
-            hasEmail: !!rawCart.email,
-            email: rawCart.email || "N/A",
-            hasBillingAddress: !!rawCart.billing_address,
-            hasPaymentCollection: !!rawCart.payment_collection,
-            existingSessionsCount: rawCart.payment_collection?.payment_sessions?.length || 0,
-            regionId: rawCart.region_id,
-            total: rawCart.total,
-            itemCount: rawCart.items?.length || 0
-          });
-          if (!rawCart.items || rawCart.items.length === 0) {
-            this.logger.error("\u{1F4B3} [DEBUG] ERROR: Cannot create payment session for empty cart", {
-              cartId,
-              itemCount: 0,
-              reason: "Cart has no items"
-            });
-            throw new ProviderAPIError(
-              "Cannot create payment session: cart is empty. Please add items to your cart before checking out.",
-              "medusa",
-              400
-            );
-          }
-          if (!rawCart.shipping_address) {
-            this.logger.error("\u{1F4B3} [DEBUG] ERROR: Shipping address required", { cartId });
-            throw new ProviderAPIError(
-              "Shipping address is required before initiating payment session",
-              "medusa",
-              400
-            );
-          }
-          if (!rawCart.shipping_methods?.length) {
-            this.logger.error("\u{1F4B3} [DEBUG] ERROR: Shipping method required", { cartId });
-            throw new ProviderAPIError(
-              "Shipping method is required before initiating payment session",
-              "medusa",
-              400
-            );
-          }
-          if (!rawCart.email) {
-            this.logger.error("\u{1F4B3} [DEBUG] ERROR: Email required", { cartId });
-            throw new ProviderAPIError(
-              "Email is required before initiating payment session",
-              "medusa",
-              400
-            );
-          }
-          if (!rawCart.billing_address) {
-            this.logger.warn(
-              "\u{1F4B3} [DEBUG] WARNING: Billing address not set, payment provider may require it",
-              {
-                cartId: rawCart.id,
-                shippingAddress: rawCart.shipping_address
-              }
-            );
-          }
-          const existingSessions = rawCart.payment_collection?.payment_sessions || [];
-          if (existingSessions.length > 0) {
-            this.logger.info("\u{1F4B3} [DEBUG] Payment session already exists, skipping creation", {
-              cartId: rawCart.id,
-              sessionCount: existingSessions.length,
-              sessionIds: existingSessions.map((s) => s.id)
-            });
-            return;
-          }
-          this.logger.info("\u{1F4B3} [DEBUG] Step 2.5: No existing payment sessions, will create new one", {
-            cartId: rawCart.id,
-            hasPaymentCollection: !!rawCart.payment_collection,
-            providerId
-          });
-          this.logger.info("\u{1F4B3} [DEBUG] Step 3: Calling Medusa SDK initiatePaymentSession...", {
-            cartId,
-            providerId,
-            endpoint: `${this.baseUrl}store/payment-collections`,
-            note: "About to call SDK method"
-          });
-          this.logger.info("\u{1F4B3} [DEBUG] Step 2.5: Validating provider ID...", {
-            providerId
-          });
-          try {
-            validatePaymentId(providerId);
-            this.logger.info("\u{1F4B3} [DEBUG] Provider ID validation passed", { providerId });
-          } catch (validationError) {
-            this.logger.error("\u{1F4B3} [DEBUG] ERROR: Invalid provider ID detected", {
-              providerId,
-              error: validationError.message,
-              hint: "Use getBackendProviderId(paymentMethod) to extract correct ID"
-            });
-            throw new ProviderAPIError(
-              validationError.message,
-              "medusa",
-              400
-            );
-          }
-          let paymentResponse;
-          try {
-            paymentResponse = await this.sdk.store.payment.initiatePaymentSession(rawCart, {
-              provider_id: providerId
-            });
-            this.logger.info("\u{1F4B3} [DEBUG] Step 4: Payment session response received", {
-              cartId,
-              providerId,
-              responseKeys: paymentResponse ? Object.keys(paymentResponse) : [],
-              response: JSON.stringify(paymentResponse, null, 2)
-            });
-          } catch (sdkError) {
-            this.logger.error(
-              "\u{1F4B3} [DEBUG] ERROR: Medusa SDK threw error when initiating payment session",
-              {
-                cartId,
-                providerId,
-                errorType: sdkError?.constructor?.name,
-                errorMessage: sdkError?.message,
-                errorStatus: sdkError?.status,
-                errorCode: sdkError?.code,
-                errorResponse: sdkError?.response ? JSON.stringify(sdkError.response, null, 2) : "N/A",
-                errorBody: sdkError?.body ? JSON.stringify(sdkError.body, null, 2) : "N/A",
-                fullError: JSON.stringify(sdkError, Object.getOwnPropertyNames(sdkError), 2),
-                // Include cart state in error for debugging
-                cartState: {
-                  hasShippingMethod: !!rawCart.shipping_methods?.length,
-                  hasShippingAddress: !!rawCart.shipping_address,
-                  hasBillingAddress: !!rawCart.billing_address,
-                  hasEmail: !!rawCart.email,
-                  total: rawCart.total,
-                  itemCount: rawCart.items?.length || 0
-                }
-              }
-            );
-            throw sdkError;
-          }
-          this.logger.info("\u{1F4B3} [DEBUG] Payment session initiated successfully", {
-            cartId,
-            providerId
-          });
-        },
-        "initiatePaymentSession",
-        { cartId, providerId }
-      );
+      const { cart: rawCart } = await this.sdk.store.cart.retrieve(cartId, {
+        fields: "+shipping_methods,+shipping_address,+email,+region_id,+total,+items,+payment_collection,+payment_collection.payment_sessions,+billing_address"
+      });
+      if (!rawCart.items || rawCart.items.length === 0) {
+        throw new ProviderAPIError(
+          "Cannot create payment session: cart is empty. Please add items to your cart before checking out.",
+          "medusa",
+          400
+        );
+      }
+      if (!rawCart.shipping_address) {
+        throw new ProviderAPIError(
+          "Shipping address is required before initiating payment session",
+          "medusa",
+          400
+        );
+      }
+      if (!rawCart.shipping_methods?.length) {
+        throw new ProviderAPIError(
+          "Shipping method is required before initiating payment session",
+          "medusa",
+          400
+        );
+      }
+      if (!rawCart.email) {
+        throw new ProviderAPIError(
+          "Email is required before initiating payment session",
+          "medusa",
+          400
+        );
+      }
+      validatePaymentId(providerId);
+      const existingSessions = rawCart.payment_collection?.payment_sessions ?? [];
+      const compatible = existingSessions.find((session) => {
+        const statusOk = ["pending", "requires_more", "authorized"].includes(session?.status);
+        return session?.provider_id === providerId && session?.amount === rawCart.total && statusOk;
+      });
+      if (compatible) {
+        this.logger.info("Reusing compatible payment session", {
+          cartId,
+          providerId,
+          sessionId: compatible.id,
+          amount: compatible.amount
+        });
+        return;
+      }
+      if (existingSessions.length > 0) {
+        this.logger.info("Existing payment session incompatible; replacing it", {
+          cartId,
+          providerId,
+          existing: existingSessions.map((session) => ({
+            id: session.id,
+            providerId: session.provider_id,
+            amount: session.amount,
+            status: session.status
+          }))
+        });
+      }
+      await this.sdk.store.payment.initiatePaymentSession(rawCart, {
+        provider_id: providerId
+      });
+      this.logger.info("Payment session initiated", { cartId, providerId });
     } catch (error) {
-      this.logger.error("\u{1F4B3} [DEBUG] ERROR: Failed to initiate payment session", {
+      this.logger.error("Failed to initiate payment session", {
         cartId,
         providerId,
         errorMessage: error.message,
-        errorStack: error.stack,
         errorStatus: error.status
       });
       throw new ProviderAPIError(
@@ -5225,31 +5818,23 @@ var MedusaProvider = class {
   async applyDiscountCode(cartId, code) {
     this.logger.debug("applyDiscountCode", { cartId, code });
     try {
-      return await this.withRetry(
-        async () => {
-          const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              "x-publishable-api-key": this.publishableKey || ""
-            },
-            body: JSON.stringify({
-              promo_codes: [code]
-            })
-          });
-          if (!response.ok) {
-            const error = await response.json();
-            throw new Error(error.message || "Failed to apply discount code");
-          }
-          const { cart: medusaCart } = await response.json();
-          this.logger.info("Discount code applied successfully", { cartId, code });
-          void medusaCart;
-          const updatedCart = await this.retrieveCartWithLineDetails(cartId);
-          return transformCart(updatedCart);
+      const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-publishable-api-key": this.publishableKey || ""
         },
-        "applyDiscountCode",
-        { cartId, code }
-      );
+        body: JSON.stringify({
+          promo_codes: [code]
+        })
+      });
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message || "Failed to apply discount code");
+      }
+      this.logger.info("Discount code applied successfully", { cartId, code });
+      const updatedCart = await this.retrieveCartWithLineDetails(cartId);
+      return transformCart(updatedCart);
     } catch (error) {
       this.logger.error("Failed to apply discount code", { cartId, code, error: error.message });
       throw new ProviderAPIError(
@@ -5272,31 +5857,23 @@ var MedusaProvider = class {
   async removeDiscountCode(cartId, code) {
     this.logger.debug("removeDiscountCode", { cartId, code });
     try {
-      return await this.withRetry(
-        async () => {
-          const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
-            method: "DELETE",
-            headers: {
-              "Content-Type": "application/json",
-              "x-publishable-api-key": this.publishableKey || ""
-            },
-            body: JSON.stringify({
-              promo_codes: [code]
-            })
-          });
-          if (!response.ok) {
-            const error = await response.json();
-            throw new Error(error.message || "Failed to remove discount code");
-          }
-          const { cart: medusaCart } = await response.json();
-          this.logger.info("Discount code removed successfully", { cartId, code });
-          void medusaCart;
-          const updatedCart = await this.retrieveCartWithLineDetails(cartId);
-          return transformCart(updatedCart);
+      const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
+        method: "DELETE",
+        headers: {
+          "Content-Type": "application/json",
+          "x-publishable-api-key": this.publishableKey || ""
         },
-        "removeDiscountCode",
-        { cartId, code }
-      );
+        body: JSON.stringify({
+          promo_codes: [code]
+        })
+      });
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message || "Failed to remove discount code");
+      }
+      this.logger.info("Discount code removed successfully", { cartId, code });
+      const updatedCart = await this.retrieveCartWithLineDetails(cartId);
+      return transformCart(updatedCart);
     } catch (error) {
       this.logger.error("Failed to remove discount code", { cartId, code, error: error.message });
       throw new ProviderAPIError(
@@ -5434,7 +6011,7 @@ var MedusaProvider = class {
     }
     const channelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
     if (!channelId) {
-      throw new import_types.StorefrontConfigError(
+      throw new StorefrontConfigError(
         "Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID to be configured. Each storefront must be linked to a sales channel. Set this in your .env file or environment variables.",
         "medusa",
         "NEXT_PUBLIC_SALES_CHANNEL_ID"
@@ -5463,7 +6040,7 @@ var MedusaProvider = class {
       });
       return context;
     } catch (error) {
-      if (error instanceof import_types.StorefrontConfigError) throw error;
+      if (error instanceof StorefrontConfigError) throw error;
       const errorMessage = extractErrorMessage(error);
       throw new ProviderAPIError(
         `Failed to initialize storefront context: ${errorMessage}`,
@@ -9291,6 +9868,7 @@ var StelOrderProvider = class {
 // src/providers/mock/mock.ts
 var FIXTURE_TIMESTAMP = "2026-01-01T00:00:00.000Z";
 var DEFAULT_SITE_URL = "https://mock.thorcommerce.local";
+var MOCK_SALES_CHANNEL_ID = "mock-sales-channel";
 var regionFixtures = [
   {
     id: "mock-region-us",
@@ -9363,6 +9941,7 @@ var productFixtures = [
   {
     id: "mock-product-aurora-jacket",
     handle: "aurora-jacket",
+    createdAt: "2026-01-05T00:00:00.000Z",
     title: "Aurora Quilted Jacket",
     description: "Lightweight quilted outerwear with tonal hardware and a soft structured collar.",
     imageLabel: "Aurora Jacket",
@@ -9404,6 +9983,7 @@ var productFixtures = [
   {
     id: "mock-product-solis-dress",
     handle: "solis-dress",
+    createdAt: "2026-01-03T00:00:00.000Z",
     title: "Solis Pleated Dress",
     description: "A fluid pleated dress with a clean neckline designed for hero storytelling.",
     imageLabel: "Solis Dress",
@@ -9443,6 +10023,7 @@ var productFixtures = [
   {
     id: "mock-product-helios-lamp",
     handle: "helios-lamp",
+    createdAt: "2026-01-04T00:00:00.000Z",
     title: "Helios Table Lamp",
     description: "Warm ambient lamp with sculptural proportions for lifestyle and home grids.",
     imageLabel: "Helios Lamp",
@@ -9466,6 +10047,7 @@ var productFixtures = [
   {
     id: "mock-product-luna-bag",
     handle: "luna-bag",
+    createdAt: "2026-01-02T00:00:00.000Z",
     title: "Luna Crossbody Bag",
     description: "Compact everyday bag for accessory rails, checkout add-ons, and bundle modules.",
     imageLabel: "Luna Bag",
@@ -9606,7 +10188,7 @@ function buildProducts(currencyCode) {
       productType: product.productType,
       vendor: product.vendor,
       tags: product.tags,
-      createdAt: FIXTURE_TIMESTAMP,
+      createdAt: product.createdAt,
       updatedAt: FIXTURE_TIMESTAMP,
       metadata: {
         categoryHandle: product.categoryHandle,
@@ -9675,6 +10257,92 @@ function paginateProducts(products, skip, first) {
   const end = first ? start + first : void 0;
   return products.slice(start, end);
 }
+var MOCK_CATALOG_SORT_KEYS = [
+  "featured",
+  "name",
+  "newest"
+];
+var MOCK_CATALOG_ENDPOINT = "mock://catalog/products";
+var MOCK_CATALOG_PAGE_SIZE = 50;
+function resolveEffectiveCategoryHandles2(query) {
+  const { categoryScope, categories } = query;
+  if (categoryScope === void 0) return categories;
+  if (categories === void 0) return [categoryScope];
+  return categories.filter((handle) => handle === categoryScope);
+}
+function collectRequestedAdvancedFields2(query) {
+  const fields = [];
+  if (query.priceMin !== void 0) fields.push("priceMin");
+  if (query.priceMax !== void 0) fields.push("priceMax");
+  if (query.inStock !== void 0) fields.push("inStock");
+  for (const name of Object.keys(query.attributes ?? {})) {
+    fields.push(`attr.${name}`);
+  }
+  return fields;
+}
+function advancedFieldToFacet2(field) {
+  if (field === "priceMin" || field === "priceMax") return "price";
+  return field;
+}
+function buildAppliedCatalogFilters2(query, effectiveCategoryHandles) {
+  return {
+    ...query.text ? { text: query.text } : {},
+    ...effectiveCategoryHandles !== void 0 ? { categories: effectiveCategoryHandles } : {},
+    ...query.collections !== void 0 ? { collections: query.collections } : {}
+  };
+}
+function buildBasicDemonstratedQuery2(query) {
+  return {
+    ...query.text !== void 0 ? { text: query.text } : {},
+    ...query.categoryScope !== void 0 ? { categoryScope: query.categoryScope } : {},
+    ...query.categories !== void 0 ? { categories: query.categories } : {},
+    ...query.collections !== void 0 ? { collections: query.collections } : {}
+  };
+}
+function buildMockFacetSupport(query) {
+  const appliedQuery = buildBasicDemonstratedQuery2(query);
+  const scopeField = query.categoryScope !== void 0 ? { scope: query.categoryScope } : {};
+  return {
+    offered: ["categories", "collections"],
+    held: ["price", "inStock"],
+    demonstrations: {
+      categories: {
+        endpoint: MOCK_CATALOG_ENDPOINT,
+        appliedQuery,
+        ...scopeField
+      },
+      collections: {
+        endpoint: MOCK_CATALOG_ENDPOINT,
+        appliedQuery,
+        ...scopeField
+      }
+    },
+    heldReasons: {
+      price: `${MOCK_CATALOG_ENDPOINT} is the mock basic listing; price filtering is not implemented in mock mode`,
+      inStock: `${MOCK_CATALOG_ENDPOINT} is the mock basic listing; stock filtering is not implemented in mock mode`
+    }
+  };
+}
+function unsupportedMockCatalogOutcome(fields) {
+  return {
+    ok: false,
+    error: {
+      code: "unsupported-query",
+      fields,
+      message: `Unsupported catalog query in mock mode: ${fields.join(", ")}`,
+      repair: { remove: fields }
+    }
+  };
+}
+function sortMockCatalogProducts(products, sortKey) {
+  const sorted = [...products];
+  if (sortKey === "name") {
+    sorted.sort((left, right) => left.title.localeCompare(right.title));
+  } else if (sortKey === "newest") {
+    sorted.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+  }
+  return sorted;
+}
 function resolveVariant(currencyCode, merchandiseId) {
   const products = buildProducts(currencyCode);
   for (const product of products) {
@@ -9739,11 +10407,22 @@ function buildExternalCart(state, currencyCode, siteUrl) {
     checkoutUrl: `${siteUrl}/checkout?cart=${state.id}`,
     cost: {
       subtotalAmount: createMoney(subtotal, regionCurrency),
-      totalAmount: createMoney(total, regionCurrency),
-      totalTaxAmount: createMoney(totalTax, regionCurrency)
+      discountAmount: createMoney(discount, regionCurrency),
+      totalTaxAmount: createMoney(totalTax, regionCurrency),
+      shippingAmount: createMoney(shipping, regionCurrency),
+      totalAmount: createMoney(total, regionCurrency)
     },
     lines,
     totalQuantity: lines.reduce((sum, line) => sum + line.quantity, 0),
+    salesChannelId: MOCK_SALES_CHANNEL_ID,
+    regionId: state.regionId,
+    currencyCode: regionCurrency.toUpperCase(),
+    selectedShippingMethodId: state.shippingMethodId,
+    // The mock method id IS the shipping option id (the value returned by
+    // `getMockShippingMethods` and accepted by `addShippingMethod`), so the
+    // canonical option identity mirrors the real adapter's `so_` field and the
+    // checkout UI can highlight the selected option.
+    selectedShippingOptionId: state.shippingMethodId,
     completedAt: state.completedAt
   };
 }
@@ -9799,6 +10478,69 @@ function getMockProducts(options) {
   const sorted = sortProducts(filtered, options?.sortKey, options?.reverse);
   return paginateProducts(sorted, options?.skip, options?.first);
 }
+function getMockCatalogProducts(query, options = {}) {
+  if (query.sort !== void 0 && !MOCK_CATALOG_SORT_KEYS.includes(query.sort)) {
+    return unsupportedMockCatalogOutcome(["sort"]);
+  }
+  const region = getRegionFixture(options.regionId);
+  const currencyCode = options.currencyCode ?? region.currencyCode;
+  const allProducts = buildProducts(currencyCode);
+  const facetSupport = buildMockFacetSupport(query);
+  const requestedAdvanced = collectRequestedAdvancedFields2(query);
+  const heldAdvanced = requestedAdvanced.filter(
+    (field) => !facetSupport.offered.includes(advancedFieldToFacet2(field))
+  );
+  if (heldAdvanced.length > 0) {
+    return unsupportedMockCatalogOutcome(heldAdvanced);
+  }
+  const effectiveCategoryHandles = resolveEffectiveCategoryHandles2(query);
+  const emptyIntersection = effectiveCategoryHandles !== void 0 && effectiveCategoryHandles.length === 0;
+  const categoryFilterEmpty = effectiveCategoryHandles !== void 0 && !effectiveCategoryHandles.some(
+    (handle) => categoryFixtures.some(
+      (category) => category.handle === handle || category.id === handle
+    )
+  );
+  const collectionFilterEmpty = query.collections !== void 0 && !query.collections.some(
+    (handle) => collectionFixtures.some(
+      (collection) => collection.handle === handle || collection.id === handle
+    )
+  );
+  if (emptyIntersection || categoryFilterEmpty || collectionFilterEmpty) {
+    return {
+      ok: true,
+      results: {
+        products: [],
+        appliedFilters: buildAppliedCatalogFilters2(
+          query,
+          effectiveCategoryHandles
+        ),
+        facetSupport
+      }
+    };
+  }
+  const filtered = filterProducts(allProducts, {
+    query: query.text,
+    categoryIds: effectiveCategoryHandles,
+    collectionIds: query.collections
+  });
+  const sorted = sortMockCatalogProducts(filtered, query.sort);
+  const pageSize = query.pageSize ?? MOCK_CATALOG_PAGE_SIZE;
+  const page = query.page ?? 1;
+  const offset = (page - 1) * pageSize;
+  return {
+    ok: true,
+    results: {
+      products: sorted.slice(offset, offset + pageSize),
+      // The full matching fixture count, never the page length.
+      total: filtered.length,
+      appliedFilters: buildAppliedCatalogFilters2(
+        query,
+        effectiveCategoryHandles
+      ),
+      facetSupport
+    }
+  };
+}
 function getMockProduct(handle, regionId) {
   const region = getRegionFixture(regionId);
   return buildProducts(region.currencyCode).find(
@@ -9911,6 +10653,17 @@ function getMockPaymentMethods(currencyCode) {
       isEnabled: true,
       requiresSetup: false,
       description: "Mock cash payment option for checkout prototypes."
+    },
+    {
+      // The single approved manual TEST provider used by the real Medusa
+      // backend, mirrored in mock mode so the guest TEST purchase path is
+      // exercisable without a backend.
+      id: "pp_system_default",
+      name: "Manual TEST payment",
+      type: "cash_on_delivery",
+      isEnabled: true,
+      requiresSetup: false,
+      description: "Manual system TEST provider (bookkeeping only; not external funds)."
     }
   ];
 }
@@ -10004,6 +10757,7 @@ var MockProvider = class {
   version = "1.0.0";
   capabilities = MOCK_CAPABILITIES;
   isMock = true;
+  supportedCatalogSortKeys = MOCK_CATALOG_SORT_KEYS;
   currencyCode;
   siteUrl;
   constructor(config = {}) {
@@ -10034,6 +10788,18 @@ var MockProvider = class {
       regionId: options?.regionId
     });
   }
+  /**
+   * 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.
+   */
+  async getCatalogProducts(query) {
+    return getMockCatalogProducts(query, { currencyCode: this.currencyCode });
+  }
   async getProductRecommendations(productId) {
     return getMockProductRecommendations(productId);
   }
@@ -10169,6 +10935,25 @@ var MockProvider = class {
     const order = completeMockCheckout(cart, this.currencyCode, this.siteUrl);
     return 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.
+   */
+  async completeCart(cartId) {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      return {
+        type: "unresolved",
+        error: { message: `Cart not found: ${cartId}`, code: "CART_NOT_FOUND", status: 404 }
+      };
+    }
+    const order = completeMockCheckout(cart, this.currencyCode, this.siteUrl);
+    return { type: "order", order };
+  }
   async getShippingMethods(cartId) {
     const cart = getMockCartState(cartId);
     return getMockShippingMethods(cart?.regionId);
@@ -10293,6 +11078,113 @@ var MockProvider = class {
   }
 };
 
+// src/factory/provider-types.ts
+var SupportedProviderType = /* @__PURE__ */ ((SupportedProviderType2) => {
+  SupportedProviderType2["Mock"] = "mock";
+  SupportedProviderType2["Medusa"] = "medusa";
+  SupportedProviderType2["StelOrder"] = "stelorder";
+  SupportedProviderType2["Shopify"] = "shopify";
+  SupportedProviderType2["BigCommerce"] = "bigcommerce";
+  SupportedProviderType2["WooCommerce"] = "woocommerce";
+  SupportedProviderType2["Spree"] = "spree";
+  SupportedProviderType2["Magento"] = "magento";
+  return SupportedProviderType2;
+})(SupportedProviderType || {});
+var PROVIDER_METADATA = {
+  mock: {
+    name: "Mock",
+    description: "Fixture-backed runtime provider for layout/design mode without a real backend",
+    requiresStorefront: false,
+    requiredEnvVars: [],
+    maxRetries: 0
+  },
+  medusa: {
+    name: "Medusa JS",
+    description: "Medusa v2 commerce engine",
+    requiresStorefront: true,
+    requiredEnvVars: [
+      "NEXT_PUBLIC_COMMERCE_API_URL",
+      "NEXT_PUBLIC_COMMERCE_API_KEY",
+      "NEXT_PUBLIC_SALES_CHANNEL_ID"
+    ],
+    maxRetries: 3
+  },
+  stelorder: {
+    name: "Stel Order",
+    description: "Stel Order ERP and sales document API",
+    requiresStorefront: false,
+    requiredEnvVars: [
+      "NEXT_PUBLIC_COMMERCE_API_URL",
+      "NEXT_PUBLIC_COMMERCE_API_KEY"
+    ],
+    maxRetries: 2
+  },
+  shopify: {
+    name: "Shopify",
+    description: "Shopify Storefront API (GraphQL)",
+    requiresStorefront: false,
+    requiredEnvVars: [
+      "NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN",
+      "NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN"
+    ],
+    maxRetries: 3
+  },
+  bigcommerce: {
+    name: "BigCommerce",
+    description: "BigCommerce REST Storefront API",
+    requiresStorefront: false,
+    requiredEnvVars: [
+      "BIGCOMMERCE_STORE_HASH",
+      "BIGCOMMERCE_STOREFRONT_API_TOKEN",
+      "BIGCOMMERCE_CHANNEL_ID"
+    ],
+    maxRetries: 3
+  },
+  woocommerce: {
+    name: "WooCommerce",
+    description: "WooCommerce Store API + REST API v3",
+    requiresStorefront: false,
+    requiredEnvVars: [
+      "WOOCOMMERCE_URL",
+      "WOOCOMMERCE_CONSUMER_KEY",
+      "WOOCOMMERCE_CONSUMER_SECRET"
+    ],
+    maxRetries: 3
+  },
+  spree: {
+    name: "Spree Commerce",
+    description: "Spree API v2 Storefront (JSON:API)",
+    requiresStorefront: false,
+    requiredEnvVars: [
+      "SPREE_API_URL"
+    ],
+    maxRetries: 3
+  },
+  magento: {
+    name: "Adobe Commerce (Magento)",
+    description: "Adobe Commerce GraphQL + REST API",
+    requiresStorefront: true,
+    requiredEnvVars: [
+      "MAGENTO_URL",
+      "MAGENTO_STORE_CODE"
+    ],
+    maxRetries: 3
+  }
+};
+function isSupportedProviderType(value) {
+  return typeof value === "string" && Object.values(SupportedProviderType).includes(value);
+}
+function getProviderMetadata(type) {
+  if (!isSupportedProviderType(type)) {
+    throw new Error(
+      `Unsupported provider: ${type}. Supported: ${Object.values(
+        SupportedProviderType
+      ).join(", ")}`
+    );
+  }
+  return PROVIDER_METADATA[type];
+}
+
 // src/factory/index.ts
 function createProvider(options) {
   if (!options || !options.provider) {
@@ -10343,11 +11235,13 @@ function isProviderType(provider, type) {
   MAGENTO_CAPABILITIES,
   MEDUSA_CAPABILITIES,
   MOCK_CAPABILITIES,
+  MOCK_SALES_CHANNEL_ID,
   MagentoProvider,
   MedusaMetadataAdapter,
   MedusaProvider,
   MetricsService,
   MockProvider,
+  PROVIDER_METADATA,
   ProviderAPIError,
   ProviderNotFoundError,
   ResourceNotFoundError,
@@ -10358,6 +11252,7 @@ function isProviderType(provider, type) {
   SpreeProvider,
   StelOrderProvider,
   StorefrontConfigError,
+  SupportedProviderType,
   WOOCOMMERCE_CAPABILITIES,
   WooCommerceProvider,
   assertEntityBelongsToChannel,
@@ -10376,10 +11271,12 @@ function isProviderType(provider, type) {
   getBackendProviderId,
   getCapabilityDescription,
   getChannelScope,
+  getProviderMetadata,
   isBackendCapabilities,
   isGlobalEntity,
   isProviderType,
   isScopedToChannel,
+  isSupportedProviderType,
   moneyToNumber,
   moneyToNumberSafe,
   numberToMoney,