@thorprovider/adapters 5.0.10 → 5.0.11

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

@@ -0,0 +1,422 @@
+/**
+ * Adapter canonical query forwarding — E2 `storefront-catalog-search-filters`
+ * task 2.2.
+ *
+ * `getCatalogProducts` must accept a validated `CatalogQuery` and forward its
+ * scope, text, collections, sort, and pagination to the Medusa Store
+ * `/store/products` endpoint, reporting only the filters it actually applied.
+ * Any requested filter the backend cannot apply (price/stock/attributes) must
+ * return a typed `unsupported-query` outcome naming the fields, never a partial
+ * success, and must not issue a provider query. An empty route-scope ∩
+ * `categories` intersection is a valid zero-result query, never an unfiltered
+ * request.
+ *
+ * The HTTP boundary is intercepted with msw against a controlled fixture, so the
+ * emitted query parameters are asserted directly — the meaningful SDK seam.
+ */
+import { describe, expect, it } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { server } from '../stelorder/client.test-helpers'
+import { MedusaProvider } from './index'
+
+const BASE = 'https://medusa.example.com'
+const PUB_KEY = 'pk_test_abc123'
+const CURRENCY = 'usd'
+
+const CATEGORIES = [
+  {
+    id: 'pcat_x',
+    name: 'Category X',
+    handle: 'x',
+    description: null,
+    parent_category_id: null,
+    product_count: 3,
+    metadata: null,
+  },
+  {
+    id: 'pcat_y',
+    name: 'Category Y',
+    handle: 'y',
+    description: null,
+    parent_category_id: null,
+    product_count: 2,
+    metadata: null,
+  },
+]
+
+const COLLECTIONS = [
+  { id: 'pcol_c1', handle: 'c1', title: 'Collection One', metadata: null },
+  { id: 'pcol_c2', handle: 'c2', title: 'Collection Two', metadata: null },
+]
+
+const MEDUSA_PRODUCT = {
+  id: 'prod_01',
+  handle: 'test-product',
+  title: 'Test Product',
+  subtitle: null,
+  description: 'A test product',
+  status: 'published',
+  thumbnail: 'https://example.com/thumb.jpg',
+  images: [{ id: 'img_01', url: 'https://example.com/img.jpg', metadata: null }],
+  tags: [],
+  collection: null,
+  categories: [{ id: 'pcat_x', name: 'Category X', handle: 'x' }],
+  options: [],
+  variants: [
+    {
+      id: 'variant_01',
+      title: 'Default',
+      product_id: 'prod_01',
+      sku: 'SKU-001',
+      inventory_quantity: 10,
+      prices: [{ id: 'price_01', amount: 2500, currency_code: 'usd' }],
+      calculated_price: { calculated_amount: 2500, currency_code: 'usd' },
+      options: [],
+    },
+  ],
+  metadata: null,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+}
+
+function makeProvider() {
+  return new MedusaProvider({
+    baseUrl: BASE,
+    publishableKey: PUB_KEY,
+    currencyCode: CURRENCY,
+    debug: false,
+  })
+}
+
+/**
+ * Read a query parameter regardless of how the SDK serializes it: a scalar as
+ * `key`, or a list as `key[0]`/`key[]` (qs default array format).
+ */
+function getParam(url: string, key: string): string | null {
+  const params = new URL(url).searchParams
+  if (params.has(key)) return params.get(key)
+  for (const [k, v] of params.entries()) {
+    if (k === `${key}[]` || k.startsWith(`${key}[`)) return v
+  }
+  return null
+}
+
+function getParamValues(url: string, key: string): string[] {
+  const out: string[] = []
+  for (const [k, v] of new URL(url).searchParams.entries()) {
+    if (k === key || k === `${key}[]` || k.startsWith(`${key}[`)) out.push(v)
+  }
+  return out
+}
+
+interface Fixture {
+  /** Every `/store/products` request URL (the provider query under test). */
+  productListUrls: string[]
+  /** Whether the backend supplies a total count on the product list. */
+  withCount: boolean
+}
+
+function installFixture(options: { withCount?: boolean } = {}): Fixture {
+  const fixture: Fixture = {
+    productListUrls: [],
+    withCount: options.withCount ?? true,
+  }
+  server.use(
+    // Thor capability probe is unrelated to the product listing; answer 404 so
+    // the fixture stays quiet and only product-list calls are captured.
+    http.get(`${BASE}/store/thor/capabilities`, () =>
+      HttpResponse.json({}, { status: 404 }),
+    ),
+    http.get(`${BASE}/store/product-categories`, ({ request }) => {
+      const handle = getParam(request.url, 'handle')
+      const match = handle
+        ? CATEGORIES.filter((c) => c.handle === handle)
+        : CATEGORIES
+      return HttpResponse.json({
+        product_categories: match,
+        count: match.length,
+        offset: 0,
+        limit: 1,
+      })
+    }),
+    http.get(`${BASE}/store/collections`, ({ request }) => {
+      const handle = getParam(request.url, 'handle')
+      const match = handle
+        ? COLLECTIONS.filter((c) => c.handle === handle)
+        : COLLECTIONS
+      return HttpResponse.json({
+        collections: match,
+        count: match.length,
+        offset: 0,
+        limit: 1,
+      })
+    }),
+    http.get(`${BASE}/store/products`, ({ request }) => {
+      fixture.productListUrls.push(request.url)
+      return HttpResponse.json({
+        products: [MEDUSA_PRODUCT],
+        ...(fixture.withCount ? { count: 42 } : {}),
+        offset: 0,
+        limit: 50,
+      })
+    }),
+    // The optional advanced endpoint is absent on this fixture: the facet
+    // support probe must hold price/stock/attribute filters.
+    http.get(`${BASE}/store/search`, () =>
+      HttpResponse.json(
+        { error: 'Failed to search products', message: 'search unavailable' },
+        { status: 500 },
+      ),
+    ),
+    http.get(`${BASE}/store/custom-attributes/category/:categoryId`, () =>
+      HttpResponse.json({ attributes: [], count: 0 }),
+    ),
+  )
+  return fixture
+}
+
+describe('MedusaProvider.getCatalogProducts — canonical query forwarding', () => {
+  it('forwards text as q and reports it as an applied filter', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      text: 'taladro',
+      sort: 'featured',
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(fixture.productListUrls).toHaveLength(1)
+    expect(getParam(fixture.productListUrls[0], 'q')).toBe('taladro')
+    expect(outcome.results.appliedFilters.text).toBe('taladro')
+    expect(outcome.results.products).toHaveLength(1)
+    expect(outcome.results.total).toBe(42)
+  })
+
+  it('retains the route category scope and resolves its handle to a backend ID', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'x',
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(getParamValues(fixture.productListUrls[0], 'category_id')).toEqual([
+      'pcat_x',
+    ])
+    expect(outcome.results.appliedFilters.categories).toEqual(['x'])
+  })
+
+  it('intersects the categories filter with the route scope', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'x',
+      categories: ['x', 'y'],
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(getParamValues(fixture.productListUrls[0], 'category_id')).toEqual([
+      'pcat_x',
+    ])
+    expect(outcome.results.appliedFilters.categories).toEqual(['x'])
+  })
+
+  it('treats an empty route-scope ∩ categories intersection as zero results with no unfiltered request', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'x',
+      categories: ['y'],
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(outcome.results.products).toEqual([])
+    expect(outcome.results.appliedFilters.categories).toEqual([])
+    expect(fixture.productListUrls).toHaveLength(0)
+  })
+
+  it('resolves collection handles to backend IDs and reports them applied', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      collections: ['c1'],
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(getParamValues(fixture.productListUrls[0], 'collection_id')).toEqual([
+      'pcol_c1',
+    ])
+    expect(outcome.results.appliedFilters.collections).toEqual(['c1'])
+  })
+
+  it('translates canonical sort keys to the backend order and omits featured', async () => {
+    const cases: Array<[string, string | null]> = [
+      ['name', 'title'],
+      ['newest', '-created_at'],
+      ['featured', null],
+    ]
+
+    for (const [sort, order] of cases) {
+      const fixture = installFixture()
+      const outcome = await makeProvider().getCatalogProducts({
+        sort: sort as 'name' | 'newest' | 'featured',
+        page: 1,
+        pageSize: 50,
+      })
+      expect(outcome.ok).toBe(true)
+      expect(getParam(fixture.productListUrls[0], 'order')).toBe(order)
+    }
+  })
+
+  it('maps page/pageSize to limit and offset = (page - 1) * pageSize', async () => {
+    const fixture = installFixture()
+    await makeProvider().getCatalogProducts({ page: 3, pageSize: 20 })
+
+    const params = new URL(fixture.productListUrls[0]).searchParams
+    expect(params.get('limit')).toBe('20')
+    expect(params.get('offset')).toBe('40')
+  })
+
+  it('defaults pagination to the canonical page size and first page', async () => {
+    const fixture = installFixture()
+    await makeProvider().getCatalogProducts({})
+
+    const params = new URL(fixture.productListUrls[0]).searchParams
+    expect(params.get('limit')).toBe('50')
+    expect(params.get('offset')).toBe('0')
+  })
+
+  it('reflects every applied requested filter (text + categories + collections)', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      text: 'term',
+      categoryScope: 'x',
+      categories: ['x'],
+      collections: ['c1'],
+      sort: 'name',
+      page: 2,
+      pageSize: 10,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(outcome.results.appliedFilters).toEqual({
+      text: 'term',
+      categories: ['x'],
+      collections: ['c1'],
+    })
+    const params = new URL(fixture.productListUrls[0]).searchParams
+    expect(params.get('q')).toBe('term')
+    expect(getParamValues(fixture.productListUrls[0], 'category_id')).toEqual([
+      'pcat_x',
+    ])
+    expect(getParamValues(fixture.productListUrls[0], 'collection_id')).toEqual([
+      'pcol_c1',
+    ])
+    expect(params.get('limit')).toBe('10')
+    expect(params.get('offset')).toBe('10')
+  })
+
+  it('requests the product thumbnail so a listing can resolve a featured image', async () => {
+    const fixture = installFixture()
+    await makeProvider().getCatalogProducts({ page: 1, pageSize: 50 })
+
+    const fields = getParam(fixture.productListUrls[0], 'fields')
+    expect(fields).not.toBeNull()
+    // `+thumbnail` ADDS to Medusa's defaults (a bare `thumbnail` would replace
+    // every default field, dropping variants/prices).
+    expect(fields).toContain('+thumbnail')
+  })
+
+  it('maps a returned thumbnail to featuredImage on a basic catalog product', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(fixture.productListUrls).toHaveLength(1)
+    const product = outcome.results.products[0]
+    expect(product.featuredImage?.url).toBe('https://example.com/thumb.jpg')
+    expect(product.images?.map((img) => img.url)).toEqual([
+      'https://example.com/img.jpg',
+    ])
+  })
+
+  it('omits total when the backend supplies none (never manufactured)', async () => {
+    const fixture = installFixture({ withCount: false })
+    const outcome = await makeProvider().getCatalogProducts({ page: 1, pageSize: 50 })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(fixture.productListUrls).toHaveLength(1)
+    expect(outcome.results.total).toBeUndefined()
+  })
+
+  it('rejects an unadvertised sort instead of silently defaulting', async () => {
+    const fixture = installFixture()
+    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(fixture.productListUrls).toHaveLength(0)
+  })
+
+  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 provider query',
+    async (field, partial) => {
+      const fixture = installFixture()
+      const outcome = await makeProvider().getCatalogProducts({
+        page: 1,
+        pageSize: 50,
+        ...(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)
+      // No partial success and no provider query call at all.
+      expect(fixture.productListUrls).toHaveLength(0)
+    },
+  )
+
+  it('rejects when several unsupported filters are requested, naming every field', async () => {
+    const fixture = installFixture()
+    const outcome = await makeProvider().getCatalogProducts({
+      priceMin: 10,
+      inStock: true,
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(false)
+    if (outcome.ok) return
+    expect(outcome.error.fields).toEqual(
+      expect.arrayContaining(['priceMin', 'inStock']),
+    )
+    expect(fixture.productListUrls).toHaveLength(0)
+  })
+})

package/src/providers/medusa/catalog-sort.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Adapter sort truthfulness — E2 `storefront-catalog-search-filters` task 2.1.
+ *
+ * `getCategoryProducts` must translate canonical Thor sort keys through the
+ * same mapping `getProducts` uses (`name → title`, `newest → -created_at`,
+ * `featured → default`), never pass the raw canonical key to Medusa's `order`
+ * field (the Store API rejects a disallowed field with a 400). The adapter must
+ * advertise exactly the sorts it can apply, with no global price/rating sort.
+ *
+ * The HTTP boundary is intercepted with msw, so the emitted `order` query
+ * parameter is asserted directly — the meaningful SDK seam.
+ */
+import { describe, expect, it } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { server } from '../stelorder/client.test-helpers'
+import { MedusaProvider } from './index'
+
+const BASE = 'https://medusa.example.com'
+const PUB_KEY = 'pk_test_abc123'
+const CURRENCY = 'usd'
+
+const MEDUSA_CATEGORY = {
+  id: 'pcat_01',
+  name: 'Electronics',
+  handle: 'electronics',
+  description: null,
+  parent_category_id: null,
+  product_count: 1,
+  metadata: null,
+}
+
+const MEDUSA_PRODUCT = {
+  id: 'prod_01',
+  handle: 'test-product',
+  title: 'Test Product',
+  subtitle: null,
+  description: 'A test product',
+  status: 'published',
+  thumbnail: 'https://example.com/thumb.jpg',
+  images: [{ id: 'img_01', url: 'https://example.com/img.jpg', metadata: null }],
+  tags: [],
+  collection: null,
+  categories: [{ id: 'pcat_01', name: 'Electronics', handle: 'electronics' }],
+  options: [],
+  variants: [
+    {
+      id: 'variant_01',
+      title: 'Default',
+      product_id: 'prod_01',
+      sku: 'SKU-001',
+      inventory_quantity: 10,
+      prices: [{ id: 'price_01', amount: 2500, currency_code: 'usd' }],
+      calculated_price: { calculated_amount: 2500, currency_code: 'usd' },
+      options: [],
+    },
+  ],
+  metadata: null,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+}
+
+function makeProvider() {
+  return new MedusaProvider({
+    baseUrl: BASE,
+    publishableKey: PUB_KEY,
+    currencyCode: CURRENCY,
+    debug: false,
+  })
+}
+
+/**
+ * Intercept category lookup + product listing and capture the emitted `order`
+ * query parameter of the product-list request.
+ */
+function captureProductListOrder(): { orders: (string | null)[] } {
+  const orders: (string | null)[] = []
+  server.use(
+    http.get(`${BASE}/store/product-categories`, () =>
+      HttpResponse.json({
+        product_categories: [MEDUSA_CATEGORY],
+        count: 1,
+        offset: 0,
+        limit: 1,
+      }),
+    ),
+    http.get(`${BASE}/store/products`, ({ request }) => {
+      const url = new URL(request.url)
+      orders.push(url.searchParams.get('order'))
+      return HttpResponse.json({
+        products: [MEDUSA_PRODUCT],
+        count: 1,
+        offset: 0,
+        limit: 50,
+      })
+    }),
+  )
+  return { orders }
+}
+
+describe('MedusaProvider — catalog sort translation and 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(provider.supportedCatalogSortKeys).not.toContain('price-asc')
+    expect(provider.supportedCatalogSortKeys).not.toContain('price-desc')
+    expect(provider.supportedCatalogSortKeys).not.toContain('rating')
+  })
+
+  it('getCategoryProducts maps name → title', async () => {
+    const { orders } = captureProductListOrder()
+    await makeProvider().getCategoryProducts('electronics', { sortKey: 'name' })
+    expect(orders).toEqual(['title'])
+  })
+
+  it('getCategoryProducts maps newest → -created_at', async () => {
+    const { orders } = captureProductListOrder()
+    await makeProvider().getCategoryProducts('electronics', { sortKey: 'newest' })
+    expect(orders).toEqual(['-created_at'])
+  })
+
+  it('getCategoryProducts omits order for featured (server default)', async () => {
+    const { orders } = captureProductListOrder()
+    await makeProvider().getCategoryProducts('electronics', { sortKey: 'featured' })
+    expect(orders).toEqual([null])
+  })
+
+  it('never emits a raw canonical key as the Medusa order field', async () => {
+    for (const sortKey of ['featured', 'name', 'newest'] as const) {
+      const { orders } = captureProductListOrder()
+      await makeProvider().getCategoryProducts('electronics', { sortKey })
+      expect(orders[0]).not.toBe('featured')
+      expect(orders[0]).not.toBe('name')
+      expect(orders[0]).not.toBe('newest')
+    }
+  })
+
+  it('omits a page-local price/rating sort instead of sending it as a global order (no default price sort, not mislabelled)', async () => {
+    // The legacy `SortOption` price/rating keys are page-local orderings the
+    // backend cannot apply globally. Pre-change `getCategoryProducts` forwarded
+    // the raw key to `order` (`order=price-asc`), presenting a page-local price
+    // sort as a global backend sort. They must be omitted (server default).
+    for (const sortKey of ['price-asc', 'price-desc', 'rating'] as const) {
+      const { orders } = captureProductListOrder()
+      await makeProvider().getCategoryProducts('electronics', { sortKey })
+      expect(orders).toEqual([null])
+      expect(orders[0]).not.toBe(sortKey)
+    }
+  })
+
+  it('getProducts maps the same canonical keys through the same mapping', async () => {
+    const expected: Record<string, string | null> = {
+      featured: null,
+      name: 'title',
+      newest: '-created_at',
+    }
+
+    for (const [sortKey, order] of Object.entries(expected)) {
+      const orders: (string | null)[] = []
+      server.use(
+        http.get(`${BASE}/store/products`, ({ request }) => {
+          orders.push(new URL(request.url).searchParams.get('order'))
+          return HttpResponse.json({
+            products: [MEDUSA_PRODUCT],
+            count: 1,
+            offset: 0,
+            limit: 50,
+          })
+        }),
+      )
+      await makeProvider().getProducts({ sortKey })
+      expect(orders).toEqual([order])
+    }
+  })
+})