@thorprovider/adapters 5.0.9 → 5.0.11

package/src/providers/mock/catalog-query.test.ts

@@ -0,0 +1,355 @@
+/**
+ * Mock provider canonical catalog query — E2 `storefront-catalog-search-filters`
+ * task 2.5.
+ *
+ * The mock must satisfy the same canonical query contract the Medusa adapter
+ * honors so mock mode is a faithful stand-in: route scope ∩ `categories`
+ * (an explicit empty intersection is a valid zero-result query), collection
+ * resolution by id or handle, case-insensitive text, global ordering before
+ * pagination, the real full match count (never the page length), a truthful
+ * facet-support descriptor, and a typed `unsupported-query` for any filter the
+ * mock cannot apply.
+ *
+ * These assert fixed expected fixture sets — not the implementation — so a
+ * regression in scope, ordering, pagination, or truthfulness fails them.
+ */
+import { describe, expect, it } from 'vitest'
+import type { CatalogQueryOutcome } from '@thorprovider/types'
+import { MockProvider } from './index'
+import { MOCK_CATALOG_SORT_KEYS } from './mock'
+
+const FIXTURE_ORDER = [
+  'aurora-jacket',
+  'solis-dress',
+  'helios-lamp',
+  'luna-bag',
+]
+
+const NAME_ORDER = [
+  'aurora-jacket',
+  'helios-lamp',
+  'luna-bag',
+  'solis-dress',
+]
+
+const NEWEST_ORDER = [
+  'aurora-jacket',
+  'helios-lamp',
+  'solis-dress',
+  'luna-bag',
+]
+
+function makeProvider() {
+  return new MockProvider({ currencyCode: 'USD' })
+}
+
+function handles(outcome: CatalogQueryOutcome): string[] {
+  if (!outcome.ok) {
+    throw new Error(`expected ok outcome, got: ${outcome.error.message}`)
+  }
+  return outcome.results.products.map((product) => product.handle)
+}
+
+describe('MockProvider — canonical catalog sort advertisement', () => {
+  it('advertises exactly the canonical sorts it can apply, with no price/rating sort', () => {
+    const provider = makeProvider()
+
+    expect(provider.supportedCatalogSortKeys).toEqual([
+      'featured',
+      'name',
+      'newest',
+    ])
+    expect(MOCK_CATALOG_SORT_KEYS).toEqual(['featured', 'name', 'newest'])
+    expect(provider.supportedCatalogSortKeys).not.toContain('price-asc')
+    expect(provider.supportedCatalogSortKeys).not.toContain('price-desc')
+    expect(provider.supportedCatalogSortKeys).not.toContain('rating')
+  })
+})
+
+describe('MockProvider.getCatalogProducts — scope', () => {
+  it('returns the full fixture catalog with no filters (no filter leak)', async () => {
+    const outcome = await makeProvider().getCatalogProducts({})
+
+    expect(handles(outcome)).toEqual(FIXTURE_ORDER)
+    if (!outcome.ok) return
+    expect(outcome.results.total).toBe(4)
+  })
+
+  it('retains the route category scope and resolves the handle to its products', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'jackets',
+    })
+
+    expect(handles(outcome)).toEqual(['aurora-jacket'])
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters.categories).toEqual(['jackets'])
+    expect(outcome.results.total).toBe(1)
+  })
+
+  it('intersects the categories filter with the route scope', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'jackets',
+      categories: ['jackets', 'dresses'],
+    })
+
+    expect(handles(outcome)).toEqual(['aurora-jacket'])
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters.categories).toEqual(['jackets'])
+  })
+
+  it('treats an empty route-scope ∩ categories intersection as zero results, not unfiltered', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'jackets',
+      categories: ['dresses'],
+    })
+
+    expect(handles(outcome)).toEqual([])
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters.categories).toEqual([])
+  })
+
+  it('treats an unknown category handle as zero results, not unfiltered', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      categories: ['does-not-exist'],
+    })
+
+    expect(handles(outcome)).toEqual([])
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters.categories).toEqual([
+      'does-not-exist',
+    ])
+  })
+
+  it('resolves collections by handle and by id and reports them applied', async () => {
+    const byHandle = await makeProvider().getCatalogProducts({
+      collections: ['best-sellers'],
+    })
+    const byId = await makeProvider().getCatalogProducts({
+      collections: ['mock-collection-best-sellers'],
+    })
+
+    expect(handles(byHandle)).toEqual(['aurora-jacket', 'helios-lamp'])
+    expect(handles(byId)).toEqual(['aurora-jacket', 'helios-lamp'])
+    if (!byHandle.ok) return
+    expect(byHandle.results.appliedFilters.collections).toEqual([
+      'best-sellers',
+    ])
+  })
+
+  it('treats an unknown collection handle as zero results, not unfiltered', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      collections: ['does-not-exist'],
+    })
+
+    expect(handles(outcome)).toEqual([])
+  })
+})
+
+describe('MockProvider.getCatalogProducts — text', () => {
+  it('matches text case-insensitively and reports it as applied', async () => {
+    const outcome = await makeProvider().getCatalogProducts({ text: 'HELIOS' })
+
+    expect(handles(outcome)).toEqual(['helios-lamp'])
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters.text).toBe('HELIOS')
+  })
+
+  it('keeps text search within the route category scope', async () => {
+    const unscoped = await makeProvider().getCatalogProducts({ text: 'dress' })
+    const scoped = await makeProvider().getCatalogProducts({
+      categoryScope: 'jackets',
+      text: 'dress',
+    })
+
+    expect(handles(unscoped)).toEqual(['solis-dress'])
+    expect(handles(scoped)).toEqual([])
+  })
+
+  it('excludes the other category for a term that matches two categories (CU-09)', async () => {
+    // "light" matches "Lightweight" (aurora-jacket, jackets) and "lighting"
+    // (helios-lamp, home): unscoped the term spans two categories, so the route
+    // scope must return only the current category's matches and never the other
+    // category's — the exact within-category-search exclusion of CU-09.
+    const unscoped = await makeProvider().getCatalogProducts({ text: 'light' })
+    const inJackets = await makeProvider().getCatalogProducts({
+      categoryScope: 'jackets',
+      text: 'light',
+    })
+    const inHome = await makeProvider().getCatalogProducts({
+      categoryScope: 'home',
+      text: 'light',
+    })
+
+    expect(handles(unscoped)).toEqual(['aurora-jacket', 'helios-lamp'])
+    expect(handles(inJackets)).toEqual(['aurora-jacket'])
+    expect(handles(inHome)).toEqual(['helios-lamp'])
+    if (!inJackets.ok || !inHome.ok) return
+    expect(inJackets.results.appliedFilters).toMatchObject({
+      text: 'light',
+      categories: ['jackets'],
+    })
+    expect(inHome.results.appliedFilters).toMatchObject({
+      text: 'light',
+      categories: ['home'],
+    })
+  })
+})
+
+describe('MockProvider.getCatalogProducts — global ordering before pagination', () => {
+  it('orders by name across pages and reports the full total, not the page length', async () => {
+    const page1 = await makeProvider().getCatalogProducts({
+      sort: 'name',
+      page: 1,
+      pageSize: 2,
+    })
+    const page2 = await makeProvider().getCatalogProducts({
+      sort: 'name',
+      page: 2,
+      pageSize: 2,
+    })
+
+    expect(handles(page1)).toEqual(['aurora-jacket', 'helios-lamp'])
+    expect(handles(page2)).toEqual(['luna-bag', 'solis-dress'])
+    if (!page1.ok || !page2.ok) return
+    expect(page1.results.total).toBe(4)
+    expect(page2.results.total).toBe(4)
+  })
+
+  it('orders by newest (fixture createdAt desc) across pages', async () => {
+    const page1 = await makeProvider().getCatalogProducts({
+      sort: 'newest',
+      page: 1,
+      pageSize: 2,
+    })
+    const page2 = await makeProvider().getCatalogProducts({
+      sort: 'newest',
+      page: 2,
+      pageSize: 2,
+    })
+
+    expect(handles(page1)).toEqual(['aurora-jacket', 'helios-lamp'])
+    expect(handles(page2)).toEqual(['solis-dress', 'luna-bag'])
+  })
+
+  it('keeps the stable fixture order for featured across pages', async () => {
+    const page1 = await makeProvider().getCatalogProducts({
+      sort: 'featured',
+      page: 1,
+      pageSize: 2,
+    })
+    const page2 = await makeProvider().getCatalogProducts({
+      sort: 'featured',
+      page: 2,
+      pageSize: 2,
+    })
+
+    expect(handles(page1)).toEqual(['aurora-jacket', 'solis-dress'])
+    expect(handles(page2)).toEqual(['helios-lamp', 'luna-bag'])
+  })
+
+  it('orders a collection listing globally before paginating', async () => {
+    const page1 = await makeProvider().getCatalogProducts({
+      collections: ['best-sellers'],
+      sort: 'name',
+      page: 1,
+      pageSize: 1,
+    })
+    const page2 = await makeProvider().getCatalogProducts({
+      collections: ['best-sellers'],
+      sort: 'name',
+      page: 2,
+      pageSize: 1,
+    })
+
+    expect(handles(page1)).toEqual(['aurora-jacket'])
+    expect(handles(page2)).toEqual(['helios-lamp'])
+    if (!page1.ok) return
+    expect(page1.results.total).toBe(2)
+  })
+
+  it('defaults to page 1 and the canonical page size of 50', async () => {
+    const outcome = await makeProvider().getCatalogProducts({})
+    expect(handles(outcome)).toEqual(FIXTURE_ORDER)
+  })
+})
+
+describe('MockProvider.getCatalogProducts — truthfulness', () => {
+  it('reflects every applied basic filter (text + categories + collections)', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      text: 'jacket',
+      categoryScope: 'jackets',
+      categories: ['jackets'],
+      collections: ['best-sellers'],
+    })
+
+    expect(handles(outcome)).toEqual(['aurora-jacket'])
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters).toEqual({
+      text: 'jacket',
+      categories: ['jackets'],
+      collections: ['best-sellers'],
+    })
+  })
+
+  it('attaches a mock-scoped facet-support descriptor that never claims Medusa support', async () => {
+    const outcome = await makeProvider().getCatalogProducts({})
+    if (!outcome.ok) return
+
+    const support = outcome.results.facetSupport
+    expect(support?.offered).toEqual(['categories', 'collections'])
+    expect(support?.held).toEqual(['price', 'inStock'])
+    expect(support?.demonstrations?.categories.endpoint).toBe(
+      'mock://catalog/products',
+    )
+    expect(support?.demonstrations?.collections.endpoint).toBe(
+      'mock://catalog/products',
+    )
+    expect(support?.heldReasons?.price).toBeTruthy()
+    expect(support?.heldReasons?.inStock).toBeTruthy()
+    expect(JSON.stringify(support)).not.toContain('medusa')
+  })
+
+  it('rejects an unadvertised sort with a typed unsupported-query', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      sort: 'price-asc',
+    } as never)
+
+    expect(outcome.ok).toBe(false)
+    if (outcome.ok) return
+    expect(outcome.error.code).toBe('unsupported-query')
+    expect(outcome.error.fields).toContain('sort')
+    expect(outcome.error.repair.remove).toContain('sort')
+  })
+
+  it.each([
+    ['priceMin', { priceMin: 10 }],
+    ['priceMax', { priceMax: 99 }],
+    ['inStock', { inStock: true }],
+    ['attr.brand', { attributes: { brand: ['acme'] } }],
+  ])(
+    'rejects an unsupported requested filter (%s) with a typed unsupported-query and no partial result',
+    async (field, partial) => {
+      const outcome = await makeProvider().getCatalogProducts({
+        ...(partial as Record<string, unknown>),
+      } as never)
+
+      expect(outcome.ok).toBe(false)
+      if (outcome.ok) return
+      expect(outcome.error.code).toBe('unsupported-query')
+      expect(outcome.error.fields).toContain(field)
+      expect(outcome.error.repair.remove).toContain(field)
+    },
+  )
+
+  it('rejects an unsupported filter even on an empty-intersection zero-result scope', async () => {
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'jackets',
+      categories: ['dresses'],
+      inStock: true,
+    } as never)
+
+    expect(outcome.ok).toBe(false)
+    if (outcome.ok) return
+    expect(outcome.error.fields).toContain('inStock')
+  })
+})

package/src/providers/mock/index.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Mock provider — selected shipping option identity.
+ *
+ * Regression for the host highlight: the mock cart must expose
+ * `selectedShippingOptionId` (the `so_` identity the checkout UI compares
+ * against `getShippingMethods()`), coherent with the mock method ids, while
+ * preserving the guard that rejects an unknown option.
+ */
+import { describe, expect, it } from 'vitest'
+import { MockProvider } from './index'
+import { getMockShippingMethods } from './mock'
+
+const REGION = 'mock-region-us'
+
+describe('MockProvider — selected shipping option', () => {
+  it('is absent before a method is applied', async () => {
+    const provider = new MockProvider({ currencyCode: 'USD' })
+    const cart = await provider.createCart({ regionId: REGION })
+    expect(cart.selectedShippingOptionId).toBeUndefined()
+  })
+
+  it('mirrors the applied method id on add and on retrieve', async () => {
+    const provider = new MockProvider({ currencyCode: 'USD' })
+    const cart = await provider.createCart({ regionId: REGION })
+    const methodId = getMockShippingMethods(REGION)[0].id
+
+    const updated = await provider.addShippingMethod(cart.id as string, methodId)
+
+    expect(updated.selectedShippingOptionId).toBe(methodId)
+    expect(updated.selectedShippingMethodId).toBe(methodId)
+
+    const fetched = await provider.getCart(cart.id as string)
+    expect(fetched?.selectedShippingOptionId).toBe(methodId)
+    expect(getMockShippingMethods(REGION).map((method) => method.id)).toContain(
+      updated.selectedShippingOptionId,
+    )
+  })
+
+  it('keeps the method guard: an unknown option is rejected', async () => {
+    const provider = new MockProvider({ currencyCode: 'USD' })
+    const cart = await provider.createCart({ regionId: REGION })
+
+    await expect(
+      provider.addShippingMethod(cart.id as string, 'so_not_allowed'),
+    ).rejects.toThrow()
+  })
+})

package/src/providers/mock/index.ts

@@ -2,6 +2,8 @@ import type {
   Cart,
   CartLineInput,
   CartLineUpdate,
+  CatalogQuery,
+  CatalogQueryOutcome,
   Collection,
   CollectionProductsOptions,
   GetCategoriesOptions,
@@ -22,6 +24,7 @@ import type {
   PaymentMethod,
 } from '@thorprovider/types';
 import type { CommerceProvider, ProviderConfig } from '../../types/provider';
+import type { CartCompletionCapable, CartCompletionResult } from '../../types/completion';
 import { ProviderAPIError, ResourceNotFoundError } from '../../core/errors';
 import { MOCK_CAPABILITIES } from '../../types/capabilities.types';
 import {
@@ -30,6 +33,7 @@ import {
   createMockCart,
   getMockAdminOrders,
   getMockAdminRegions,
+  getMockCatalogProducts,
   getMockCategories,
   getMockCategory,
   getMockCollection,
@@ -46,6 +50,7 @@ import {
   getMockRegions,
   getMockShippingMethods,
   getMockStockLocations,
+  MOCK_CATALOG_SORT_KEYS,
   saveMockCartState,
   saveMockOrder,
   validateMockCartStock,
@@ -56,11 +61,14 @@ export interface MockProviderConfig extends ProviderConfig {
   siteUrl?: string;
 }
 
-export class MockProvider implements CommerceProvider {
+export { MOCK_SALES_CHANNEL_ID } from './mock';
+
+export class MockProvider implements CommerceProvider, CartCompletionCapable {
   readonly name = 'mock';
   readonly version = '1.0.0';
   readonly capabilities = MOCK_CAPABILITIES;
   readonly isMock = true;
+  readonly supportedCatalogSortKeys = MOCK_CATALOG_SORT_KEYS;
 
   private readonly currencyCode: string;
   private readonly siteUrl: string;
@@ -97,6 +105,19 @@ export class MockProvider implements CommerceProvider {
     });
   }
 
+  /**
+   * 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: CatalogQuery): Promise<CatalogQueryOutcome> {
+    return getMockCatalogProducts(query, { currencyCode: this.currencyCode });
+  }
+
   async getProductRecommendations(productId: string): Promise<Product[]> {
     return getMockProductRecommendations(productId);
   }
@@ -274,6 +295,27 @@ export class MockProvider implements CommerceProvider {
     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: string): Promise<CartCompletionResult> {
+    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: string): Promise<ShippingMethod[]> {
     const cart = getMockCartState(cartId);
     return getMockShippingMethods(cart?.regionId);