@thorprovider/adapters 5.0.10 → 5.0.12

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 {
@@ -156,10 +179,11 @@ const categoryFixtures: MockCategoryFixture[] = [
   },
 ];
 
-const productFixtures: MockProductFixture[] = [
+const heroProductFixtures: 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',
@@ -285,6 +312,180 @@ const productFixtures: MockProductFixture[] = [
   },
 ];
 
+/**
+ * Deterministic blueprint for a generated demo category.
+ *
+ * Every field is a fixed literal so the factory below produces the same ids,
+ * handles, titles, prices, and ordering on every load (no `Math.random`, no
+ * clock reads). `names` are unique within the category and the `noun`
+ * distinguishes categories, so `${name} ${noun}` yields globally distinct
+ * titles and `${name}-${noun}` yields globally unique handles.
+ */
+interface MockProductBlueprint {
+  categoryHandle: string;
+  noun: string;
+  productType: string;
+  vendor: string;
+  tags: string[];
+  variantName: string;
+  variantValues: string[];
+  names: string[];
+  description: string;
+  basePrice: number;
+  baseHue: number;
+}
+
+/**
+ * Fixed per-category pools for the generated demo products.
+ *
+ * Copy deliberately avoids the substrings "light" and "helios" so the existing
+ * CU-09 text-search assertions (which pin the only "light"/"HELIOS" matches to
+ * the fixture heroes) keep holding.
+ */
+const generatedBlueprints: MockProductBlueprint[] = [
+  {
+    categoryHandle: 'jackets',
+    noun: 'Jacket',
+    productType: 'outerwear',
+    vendor: 'Thor Atelier',
+    tags: ['outerwear', 'layer'],
+    variantName: 'Size',
+    variantValues: ['S', 'M'],
+    names: ['Alpine', 'Boreal', 'Cinder', 'Drift', 'Ember', 'Fjord', 'Harbor', 'Meridian', 'Nomad', 'Tundra', 'Vantage'],
+    description: 'A considered layering piece in a brushed weave.',
+    basePrice: 118,
+    baseHue: 210,
+  },
+  {
+    categoryHandle: 'dresses',
+    noun: 'Dress',
+    productType: 'dress',
+    vendor: 'Thor Atelier',
+    tags: ['dress', 'editorial'],
+    variantName: 'Size',
+    variantValues: ['S', 'M'],
+    names: ['Amber', 'Camille', 'Dahlia', 'Elara', 'Iris', 'Lumen', 'Nova', 'Rosalind', 'Vera'],
+    description: 'Cut from a fluid cloth for editorial styling.',
+    basePrice: 142,
+    baseHue: 330,
+  },
+  {
+    categoryHandle: 'home',
+    noun: 'Lamp',
+    productType: 'decor',
+    vendor: 'Thor Home',
+    tags: ['home', 'decor', 'interior'],
+    variantName: 'Finish',
+    variantValues: ['Brass'],
+    names: ['Atlas', 'Copper', 'Dune', 'Onyx', 'Quill', 'Slate', 'Terra', 'Verdant'],
+    description: 'A calm sculptural accent for modern interiors.',
+    basePrice: 74,
+    baseHue: 40,
+  },
+  {
+    categoryHandle: 'accessories',
+    noun: 'Bag',
+    productType: 'bag',
+    vendor: 'Thor Atelier',
+    tags: ['accessory', 'everyday'],
+    variantName: 'Color',
+    variantValues: ['Juniper'],
+    names: ['Cove', 'Fable', 'Juniper', 'Kestrel', 'Marlowe', 'Piper', 'Rune'],
+    description: 'An everyday carry with a textured finish.',
+    basePrice: 68,
+    baseHue: 280,
+  },
+];
+
+/** Oldest anchor for generated `createdAt` values; all stay before the heroes. */
+const GENERATED_CREATED_AT_BASE = Date.parse('2025-12-30T00:00:00.000Z');
+
+/** Deterministic collection order the generated products are assigned across. */
+const GENERATED_COLLECTION_POOL = ['new-arrivals', 'best-sellers', 'studio-essentials'];
+
+/**
+ * Build the generated demo products, one pool per seeded category.
+ *
+ * Deterministic by construction: the trailing `globalIndex` drives collection
+ * membership, pricing step, stock, hue, and `createdAt` so the whole seed is a
+ * pure function of fixed literals.
+ */
+function buildGeneratedProductFixtures(): MockProductFixture[] {
+  const fixtures: MockProductFixture[] = [];
+  let globalIndex = 0;
+
+  for (const blueprint of generatedBlueprints) {
+    const noun = blueprint.noun.toLowerCase();
+
+    blueprint.names.forEach((name, localIndex) => {
+      const handle = `${name.toLowerCase()}-${noun}`;
+      const title = `${name} ${blueprint.noun}`;
+      const price = blueprint.basePrice + localIndex * 7 + (localIndex % 3) * 0.5;
+      const quantityAvailable = (globalIndex * 5) % 17;
+
+      const primaryCollection =
+        GENERATED_COLLECTION_POOL[globalIndex % GENERATED_COLLECTION_POOL.length];
+      const collectionHandles = [primaryCollection];
+      if (globalIndex % 5 === 0) {
+        const secondary =
+          GENERATED_COLLECTION_POOL[(globalIndex + 1) % GENERATED_COLLECTION_POOL.length];
+        if (secondary !== primaryCollection) {
+          collectionHandles.push(secondary);
+        }
+      }
+
+      const createdAt = new Date(GENERATED_CREATED_AT_BASE - globalIndex * 86_400_000).toISOString();
+
+      const variants: MockVariantFixture[] = blueprint.variantValues.map((value, variantIndex) => ({
+        id: `mock-variant-${handle}-${value.toLowerCase()}`,
+        title: value,
+        price,
+        quantityAvailable: Math.max(0, quantityAvailable - variantIndex),
+        selectedOptions: [{ name: blueprint.variantName, value }],
+      }));
+
+      fixtures.push({
+        id: `mock-product-${handle}`,
+        handle,
+        title,
+        description: `${title} - ${blueprint.description}`,
+        imageLabel: title,
+        imageHue: (blueprint.baseHue + localIndex * 13) % 360,
+        collectionHandles,
+        categoryHandle: blueprint.categoryHandle,
+        productType: blueprint.productType,
+        vendor: blueprint.vendor,
+        tags: [...blueprint.tags],
+        options: [
+          {
+            id: `${handle}-${blueprint.variantName.toLowerCase()}`,
+            name: blueprint.variantName,
+            values: [...blueprint.variantValues],
+          },
+        ],
+        variants,
+        createdAt,
+      });
+
+      globalIndex += 1;
+    });
+  }
+
+  return fixtures;
+}
+
+/**
+ * The full mock product seed.
+ *
+ * The four fixture heroes stay first so the canonical `featured` order and the
+ * home hero (`slice(0, 4)`) remain representative; the generated demo products
+ * follow and populate every category with a credible multi-item grid.
+ */
+const productFixtures: MockProductFixture[] = [
+  ...heroProductFixtures,
+  ...buildGeneratedProductFixtures(),
+];
+
 const stockLocationFixture: StockLocation = {
   id: 'mock-stock-primary',
   name: 'Mock Main Warehouse',
@@ -422,10 +623,24 @@ function buildProducts(currencyCode: string): Product[] {
           title: collection.title,
           handle: collection.handle,
         })),
+      categories: (() => {
+        const category = categoryFixtures.find(
+          (item) => item.handle === product.categoryHandle,
+        );
+        if (!category) return undefined;
+        return [
+          {
+            id: category.id,
+            name: category.name,
+            handle: category.handle,
+            parentCategoryId: category.parentCategoryId,
+          },
+        ];
+      })(),
       productType: product.productType,
       vendor: product.vendor,
       tags: product.tags,
-      createdAt: FIXTURE_TIMESTAMP,
+      createdAt: product.createdAt,
       updatedAt: FIXTURE_TIMESTAMP,
       metadata: {
         categoryHandle: product.categoryHandle,
@@ -517,6 +732,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 +971,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 +1061,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 +1312,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';

package/.turbo/turbo-build.log

@@ -1,18 +0,0 @@
-CLI Building entry: {"index":"src/index.ts"}
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/nelson/dev/active/thorprovider/repos/thorcommerce/packages/adapters/tsup.config.ts
-CLI Target: esnext
-CLI Cleaning output folder
-CJS Build start
-ESM Build start
-ESM dist/index.mjs     343.86 KB
-ESM dist/index.mjs.map 702.37 KB
-ESM ⚡️ Build success in 150ms
-CJS dist/index.js     348.70 KB
-CJS dist/index.js.map 702.75 KB
-CJS ⚡️ Build success in 151ms
-DTS Build start
-DTS ⚡️ Build success in 11687ms
-DTS dist/index.d.ts  99.44 KB
-DTS dist/index.d.mts 99.44 KB