@thorprovider/adapters 5.0.10 → 5.0.11

package/src/providers/mock/mock.ts

@@ -18,10 +18,25 @@ import type {
   StockStatus,
   StockValidation,
 } from '@thorprovider/types';
+import type {
+  CatalogAppliedFilters,
+  CatalogFacetId,
+  CatalogQuery,
+  CatalogQueryOutcome,
+  CatalogSortKey,
+  FacetSupport,
+} from '@thorprovider/types';
 
 const FIXTURE_TIMESTAMP = '2026-01-01T00:00:00.000Z';
 const DEFAULT_SITE_URL = 'https://mock.thorcommerce.local';
 
+/**
+ * Stable sales channel the fixture cart is scoped to. Exported so a host can
+ * build a matching `StoreContext` for the mock data source; the runtime
+ * context check compares against it like a real backend channel.
+ */
+export const MOCK_SALES_CHANNEL_ID = 'mock-sales-channel';
+
 interface MockRegionFixture {
   id: string;
   name: string;
@@ -69,6 +84,14 @@ interface MockProductFixture {
   tags: string[];
   options: Array<{ id: string; name: string; values: string[] }>;
   variants: MockVariantFixture[];
+  /**
+   * Fixture-supplied creation timestamp (ISO-8601).
+   *
+   * Declared explicitly per product rather than derived from the id, so the
+   * canonical `newest` ordering is truthful and deterministic. Products keep
+   * distinct values so global ordering before pagination is observable.
+   */
+  createdAt: string;
 }
 
 export interface MockCartState {
@@ -160,6 +183,7 @@ const productFixtures: MockProductFixture[] = [
   {
     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',
@@ -201,6 +225,7 @@ const productFixtures: MockProductFixture[] = [
   {
     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',
@@ -240,6 +265,7 @@ const productFixtures: MockProductFixture[] = [
   {
     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',
@@ -263,6 +289,7 @@ const productFixtures: MockProductFixture[] = [
   {
     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',
@@ -425,7 +452,7 @@ function buildProducts(currencyCode: string): Product[] {
       productType: product.productType,
       vendor: product.vendor,
       tags: product.tags,
-      createdAt: FIXTURE_TIMESTAMP,
+      createdAt: product.createdAt,
       updatedAt: FIXTURE_TIMESTAMP,
       metadata: {
         categoryHandle: product.categoryHandle,
@@ -517,6 +544,167 @@ function paginateProducts(products: Product[], skip?: number, first?: number): P
   return products.slice(start, end);
 }
 
+/**
+ * Canonical sort keys the mock catalog can truthfully apply (E2 task 2.5).
+ *
+ * Mirrors the Medusa advertisement: `featured` (stable fixture order, the
+ * canonical default), `name` (title ascending), and `newest` (fixture-supplied
+ * `createdAt` descending). No global price or rating ordering is advertised.
+ */
+export const MOCK_CATALOG_SORT_KEYS: readonly CatalogSortKey[] = [
+  'featured',
+  'name',
+  'newest',
+];
+
+/**
+ * The mock catalog's demonstration endpoint identity.
+ *
+ * Explicitly mock-scoped so a support descriptor can never be mistaken for a
+ * live Medusa endpoint. The mock is the basic fixture listing; advanced facets
+ * are held.
+ */
+const MOCK_CATALOG_ENDPOINT = 'mock://catalog/products';
+
+/** Canonical default page size, matching the Medusa configured bound. */
+const MOCK_CATALOG_PAGE_SIZE = 50;
+
+/**
+ * Effective category scope for a canonical query.
+ *
+ * Mirrors the Medusa contract: the route `categoryScope` is always retained and
+ * the `categories` filter narrows within it. Returns `undefined` when no
+ * category filter is requested, `[]` for an explicit empty intersection (a valid
+ * zero-result query), or the handles to resolve against the fixtures.
+ */
+function resolveEffectiveCategoryHandles(
+  query: CatalogQuery
+): string[] | undefined {
+  const { categoryScope, categories } = query;
+  if (categoryScope === undefined) return categories;
+  if (categories === undefined) return [categoryScope];
+  return categories.filter((handle) => handle === categoryScope);
+}
+
+/** Canonical query fields that require advanced filtering the mock does not implement. */
+function collectRequestedAdvancedFields(query: CatalogQuery): string[] {
+  const fields: string[] = [];
+  if (query.priceMin !== undefined) fields.push('priceMin');
+  if (query.priceMax !== undefined) fields.push('priceMax');
+  if (query.inStock !== undefined) fields.push('inStock');
+  for (const name of Object.keys(query.attributes ?? {})) {
+    fields.push(`attr.${name}`);
+  }
+  return fields;
+}
+
+/** Map a requested advanced field name to the canonical facet id it needs. */
+function advancedFieldToFacet(field: string): CatalogFacetId {
+  if (field === 'priceMin' || field === 'priceMax') return 'price';
+  return field as CatalogFacetId;
+}
+
+/**
+ * Filters a successful (or explicitly-empty) canonical result reports as
+ * applied. The mock implements only the basic filters (text/categories/
+ * collections); requested advanced filters never reach a success path.
+ */
+function buildAppliedCatalogFilters(
+  query: CatalogQuery,
+  effectiveCategoryHandles: string[] | undefined
+): CatalogAppliedFilters {
+  return {
+    ...(query.text ? { text: query.text } : {}),
+    ...(effectiveCategoryHandles !== undefined
+      ? { categories: effectiveCategoryHandles }
+      : {}),
+    ...(query.collections !== undefined
+      ? { collections: query.collections }
+      : {}),
+  };
+}
+
+/** Basic fields the mock listing actually accepts, recorded on the demonstration. */
+function buildBasicDemonstratedQuery(query: CatalogQuery): CatalogQuery {
+  return {
+    ...(query.text !== undefined ? { text: query.text } : {}),
+    ...(query.categoryScope !== undefined
+      ? { categoryScope: query.categoryScope }
+      : {}),
+    ...(query.categories !== undefined ? { categories: query.categories } : {}),
+    ...(query.collections !== undefined
+      ? { collections: query.collections }
+      : {}),
+  };
+}
+
+/**
+ * Truthful facet-support descriptor for the mock.
+ *
+ * `categories`/`collections` are offered with the mock listing as their
+ * demonstration source; `price`/`inStock` are held with a real reason because
+ * the mock does not implement advanced filtering. No count or range is
+ * synthesized and the endpoint is explicitly mock-scoped.
+ */
+function buildMockFacetSupport(query: CatalogQuery): FacetSupport {
+  const appliedQuery = buildBasicDemonstratedQuery(query);
+  const scopeField =
+    query.categoryScope !== undefined ? { 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`,
+    },
+  };
+}
+
+/** Build a typed `unsupported-query` outcome naming the offending fields. */
+function unsupportedMockCatalogOutcome(fields: string[]): CatalogQueryOutcome {
+  return {
+    ok: false,
+    error: {
+      code: 'unsupported-query',
+      fields,
+      message: `Unsupported catalog query in mock mode: ${fields.join(', ')}`,
+      repair: { remove: fields },
+    },
+  };
+}
+
+/**
+ * Apply the canonical ordering globally, before pagination.
+ *
+ * `featured` preserves the stable fixture order; `name` sorts by title
+ * ascending; `newest` sorts by the fixture-supplied `createdAt` descending.
+ */
+function sortMockCatalogProducts(
+  products: Product[],
+  sortKey?: CatalogSortKey
+): Product[] {
+  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: string, merchandiseId: string): {
   product: Product;
   variant: Product['variants'][number];
@@ -595,11 +783,22 @@ function buildExternalCart(state: MockCartState, currencyCode: string, siteUrl:
     checkoutUrl: `${siteUrl}/checkout?cart=${state.id}`,
     cost: {
       subtotalAmount: createMoney(subtotal, regionCurrency),
-      totalAmount: createMoney(total, 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,
   };
 }
@@ -674,6 +873,118 @@ export function getMockProducts(options?: {
   return paginateProducts(sorted, options?.skip, options?.first);
 }
 
+/**
+ * Canonical catalog query for the mock provider — E2 `storefront-catalog-search-filters`
+ * task 2.5.
+ *
+ * A faithful stand-in for the Medusa canonical contract so mock mode exercises
+ * the same behavior:
+ *
+ * - The route `categoryScope` is always retained and intersected with the
+ *   `categories` filter; an explicit empty intersection (or a requested
+ *   category/collection handle that matches no fixture) is a valid zero-result
+ *   query, never an unfiltered request.
+ * - Requested category/collection handles resolve against the fixtures by id or
+ *   handle; text matching is case-insensitive over title, description, and tags.
+ * - Ordering is global, before pagination: `featured` preserves the stable
+ *   fixture order, `name` sorts by title ascending, and `newest` sorts by the
+ *   fixture-supplied `createdAt` descending. Only the advertised
+ *   `MOCK_CATALOG_SORT_KEYS` are accepted; any other sort is a typed
+ *   `unsupported-query`.
+ * - `total` is the full matching fixture count (never the page length) and is
+ *   present whenever a listing is returned.
+ * - Advanced filters (price/stock/attributes) are held and rejected as a typed
+ *   `unsupported-query` **before** any zero-result short-circuit, so a requested
+ *   filter is never silently dropped and a partial result is never labelled
+ *   success. The attached `facetSupport` marks its demonstration endpoint as
+ *   mock-scoped and never claims Medusa support.
+ */
+export function getMockCatalogProducts(
+  query: CatalogQuery,
+  options: { currencyCode?: string; regionId?: string } = {}
+): CatalogQueryOutcome {
+  if (
+    query.sort !== undefined &&
+    !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);
+
+  // Reject every requested advanced field before the zero-result short-circuit,
+  // so an unsupported filter is never hidden behind an empty intersection.
+  const requestedAdvanced = collectRequestedAdvancedFields(query);
+  const heldAdvanced = requestedAdvanced.filter(
+    (field) => !facetSupport.offered.includes(advancedFieldToFacet(field))
+  );
+  if (heldAdvanced.length > 0) {
+    return unsupportedMockCatalogOutcome(heldAdvanced);
+  }
+
+  const effectiveCategoryHandles = resolveEffectiveCategoryHandles(query);
+  const emptyIntersection =
+    effectiveCategoryHandles !== undefined &&
+    effectiveCategoryHandles.length === 0;
+  const categoryFilterEmpty =
+    effectiveCategoryHandles !== undefined &&
+    !effectiveCategoryHandles.some((handle) =>
+      categoryFixtures.some(
+        (category) => category.handle === handle || category.id === handle
+      )
+    );
+  const collectionFilterEmpty =
+    query.collections !== undefined &&
+    !query.collections.some((handle) =>
+      collectionFixtures.some(
+        (collection) =>
+          collection.handle === handle || collection.id === handle
+      )
+    );
+
+  if (emptyIntersection || categoryFilterEmpty || collectionFilterEmpty) {
+    return {
+      ok: true,
+      results: {
+        products: [],
+        appliedFilters: buildAppliedCatalogFilters(
+          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: buildAppliedCatalogFilters(
+        query,
+        effectiveCategoryHandles
+      ),
+      facetSupport,
+    },
+  };
+}
+
 export function getMockProduct(handle: string, regionId?: string): Product | undefined {
   const region = getRegionFixture(regionId);
   return buildProducts(region.currencyCode).find(
@@ -813,6 +1124,17 @@ export function getMockPaymentMethods(currencyCode: string): PaymentMethod[] {
       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).',
+    },
   ];
 }
 

package/src/types/completion.ts

@@ -0,0 +1,57 @@
+/**
+ * @thorprovider/adapters — Cart completion contract
+ *
+ * Completion of a backend cart is discriminated (change B, decision 11): a
+ * native complete may return an order, a cart carrying a structured error, or
+ * an ambiguous/unresolved result whose outcome must be reconciled before any
+ * retry. This type is provider-agnostic and lives in adapters (not
+ * `@thorprovider/types`, which stays type-only and frozen).
+ */
+
+import type { Cart, Order } from '@thorprovider/types';
+
+/**
+ * Structured completion error. `raw` carries the backend's own error object
+ * when one was supplied so the discriminator and details are preserved.
+ */
+export interface CartCompletionError {
+  /** Human-readable message. */
+  message: string;
+
+  /** Stable error code when the backend or transport supplies one. */
+  code?: string;
+
+  /** HTTP/transport status when one is known. */
+  status?: number;
+
+  /** Backend error details, carried through unchanged. */
+  raw?: unknown;
+}
+
+/**
+ * The discriminated result of completing a cart.
+ *
+ * - `order` — the cart was completed and an order was placed.
+ * - `cart` — the backend returned a cart with a structured error (the native
+ *   HTTP 200 `type: "cart"` discriminator is preserved).
+ * - `unresolved` — the mutation's outcome is unknown (timeout/transport/5xx).
+ *   Never blindly retry: reconcile the committed cart before another attempt.
+ */
+export type CartCompletionResult =
+  | { type: 'order'; order: Order }
+  | { type: 'cart'; cart: Cart; error: CartCompletionError }
+  | { type: 'unresolved'; error: CartCompletionError };
+
+/**
+ * Optional capability a provider may implement to expose the discriminated
+ * completion and reconciliation protocol. Providers that do not implement it
+ * still satisfy `CommerceProvider`; the runtime falls back to
+ * `completeCheckout` for them.
+ */
+export interface CartCompletionCapable {
+  /**
+   * Complete the cart once, preserving the native discriminator. Must not
+   * retry an ambiguous mutation.
+   */
+  completeCart?(cartId: string): Promise<CartCompletionResult>;
+}

package/src/types/index.ts

@@ -22,3 +22,10 @@ export type {
   UIDiscountCode,
   UIPaymentMethod,
 } from './ui-responses';
+
+// Cart completion contract (discriminated native completion)
+export type {
+  CartCompletionResult,
+  CartCompletionError,
+  CartCompletionCapable,
+} from './completion';