@thorprovider/adapters 5.0.10 → 5.0.12

package/src/providers/medusa/catalog-facet-support.test.ts

@@ -0,0 +1,715 @@
+/**
+ * Adapter optional-filter proof — E2 `storefront-catalog-search-filters`
+ * task 2.4.
+ *
+ * Optional filters (price, attributes, `/store/search`) must be proven against
+ * the real endpoint with the applied query for the current scope, never from a
+ * capability boolean or returned facet metadata. When the optional endpoint is
+ * absent, the filter is held, a basic-only request is served by the equivalent
+ * basic endpoint `/store/products`, and an advanced request is rejected as a
+ * typed `unsupported-query` error — never silently served by the basic endpoint
+ * and never a partial success.
+ *
+ * The HTTP boundary is intercepted with msw against a controlled fixture, so the
+ * real request/response evidence is asserted directly.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { beforeAll, describe, expect, it } from 'vitest'
+import { http, HttpResponse, passthrough } 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 CATEGORY_X = {
+  id: 'pcat_x',
+  name: 'Category X',
+  handle: 'x',
+  description: null,
+  parent_category_id: null,
+  product_count: 3,
+  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',
+}
+
+const FILTERABLE_ATTRIBUTE = {
+  attribute_id: 'attr_brand',
+  attribute: {
+    name: 'Brand',
+    handle: 'brand',
+    type: 'multi-select',
+    is_filterable: true,
+    is_active: true,
+    ranking: 40,
+    values: [{ id: 'val_acme', value: 'Acme', count: 3 }],
+  },
+}
+
+/** A distinct product returned only by the advanced endpoint. */
+const ADVANCED_PRODUCT = {
+  ...MEDUSA_PRODUCT,
+  id: 'prod_advanced',
+  handle: 'advanced-product',
+  title: 'Advanced Product',
+}
+
+function makeProvider() {
+  return new MedusaProvider({
+    baseUrl: BASE,
+    publishableKey: PUB_KEY,
+    currencyCode: CURRENCY,
+    debug: false,
+  })
+}
+
+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 {
+  productListUrls: string[]
+  searchUrls: string[]
+  customAttributeUrls: string[]
+}
+
+/**
+ * Install the basic endpoint, category/collection lookups, custom-attributes
+ * metadata, and a configurable `/store/search` response.
+ */
+function installFixture(
+  search: { status: number; body?: unknown } = { status: 500 },
+  attributes: Array<Record<string, unknown>> = [],
+): Fixture {
+  const fixture: Fixture = {
+    productListUrls: [],
+    searchUrls: [],
+    customAttributeUrls: [],
+  }
+  server.use(
+    http.get(`${BASE}/store/thor/capabilities`, () =>
+      HttpResponse.json({}, { status: 404 }),
+    ),
+    http.get(`${BASE}/store/product-categories`, () =>
+      HttpResponse.json({
+        product_categories: [CATEGORY_X],
+        count: 1,
+        offset: 0,
+        limit: 1,
+      }),
+    ),
+    http.get(`${BASE}/store/collections`, () =>
+      HttpResponse.json({ collections: [], count: 0, offset: 0, limit: 1 }),
+    ),
+    http.get(`${BASE}/store/custom-attributes/category/:categoryId`, ({ request }) => {
+      fixture.customAttributeUrls.push(request.url)
+      return HttpResponse.json({ attributes, count: attributes.length })
+    }),
+    http.get(`${BASE}/store/search`, ({ request }) => {
+      fixture.searchUrls.push(request.url)
+      // Mirror the backend route contract (`src/api/store/search/route.ts`):
+      // `attributes` must be a JSON string of an ARRAY of `{ id, values }`.
+      // A JSON object (or any non-array) is rejected with a 500, exactly as
+      // the real backend does, so a wrong request shape cannot pass silently.
+      const rawAttributes = new URL(request.url).searchParams.get('attributes')
+      if (rawAttributes !== null) {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(rawAttributes)
+        } catch {
+          return HttpResponse.json(
+            { message: 'Invalid attributes format. Expected JSON array.' },
+            { status: 500 },
+          )
+        }
+        if (!Array.isArray(parsed)) {
+          return HttpResponse.json(
+            { message: 'Invalid attributes format. Expected JSON array.' },
+            { status: 500 },
+          )
+        }
+      }
+      return HttpResponse.json(search.body ?? {}, { status: search.status })
+    }),
+    http.get(`${BASE}/store/products`, ({ request }) => {
+      fixture.productListUrls.push(request.url)
+      return HttpResponse.json({
+        products: [MEDUSA_PRODUCT],
+        count: 1,
+        offset: 0,
+        limit: 50,
+      })
+    }),
+  )
+  return fixture
+}
+
+describe('MedusaProvider.getCatalogFacetSupport — optional endpoint absent', () => {
+  it('holds price/inStock/attr and offers only the basic facets, proven by /store/products', async () => {
+    const fixture = installFixture({ status: 500 })
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x' },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+
+    // The optional endpoint was really probed (with the applied query + scope).
+    expect(fixture.searchUrls).toHaveLength(1)
+    const probe = new URL(fixture.searchUrls[0])
+    expect(getParamValues(fixture.searchUrls[0], 'categories')).toEqual([
+      'pcat_x',
+    ])
+    expect(probe.searchParams.get('limit')).toBe('1')
+
+    // Basic facets are offered with a real /store/products demonstration.
+    expect(support.offered).toEqual(
+      expect.arrayContaining(['categories', 'collections']),
+    )
+    expect(support.demonstrations?.categories).toMatchObject({
+      endpoint: '/store/products',
+      scope: 'x',
+    })
+    expect(support.demonstrations?.categories?.appliedQuery).toMatchObject({
+      categoryScope: 'x',
+    })
+
+    // No advanced facet is offered from a capability boolean.
+    expect(support.offered).not.toContain('price')
+    expect(support.offered).not.toContain('inStock')
+
+    // Held advanced facets carry the real probe reason, not a declaration.
+    expect(support.held).toEqual(expect.arrayContaining(['price', 'inStock']))
+    expect(support.heldReasons?.price).toContain('/store/search')
+    expect(support.heldReasons?.price).toContain('500')
+  })
+
+  it('never invents a demonstration timestamp', async () => {
+    installFixture({ status: 500 })
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x' },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+    for (const source of Object.values(support.demonstrations ?? {})) {
+      expect(source).not.toHaveProperty('demonstratedAt')
+    }
+  })
+})
+
+describe('MedusaProvider.getCatalogProducts — optional endpoint absent', () => {
+  it('serves a basic-only request through /store/products with held advanced facets', async () => {
+    const fixture = installFixture({ status: 500 })
+    const outcome = await makeProvider().getCatalogProducts({
+      text: 'taladro',
+      categoryScope: 'x',
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(fixture.productListUrls).toHaveLength(1)
+    expect(outcome.results.products).toHaveLength(1)
+    expect(outcome.results.facetSupport?.offered).toEqual(
+      expect.arrayContaining(['categories', 'collections']),
+    )
+    expect(outcome.results.facetSupport?.held).toEqual(
+      expect.arrayContaining(['price', 'inStock']),
+    )
+  })
+
+  it('rejects an advanced request as a typed unsupported-query with no basic fallback', async () => {
+    const fixture = installFixture({ status: 500 })
+    const outcome = await makeProvider().getCatalogProducts({
+      priceMin: 10,
+      priceMax: 99,
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(false)
+    if (outcome.ok) return
+    expect(outcome.error.code).toBe('unsupported-query')
+    expect(outcome.error.fields).toEqual(
+      expect.arrayContaining(['priceMin', 'priceMax']),
+    )
+    expect(outcome.error.repair.remove).toEqual(
+      expect.arrayContaining(['priceMin', 'priceMax']),
+    )
+    // The basic endpoint is never used to silently serve an advanced request.
+    expect(fixture.productListUrls).toHaveLength(0)
+  })
+})
+
+describe('MedusaProvider.getCatalogFacetSupport — optional endpoint present', () => {
+  it('offers price and inStock from the real applied_filters keys, holding attributes', async () => {
+    installFixture(
+      {
+        status: 200,
+        body: {
+          hits: [],
+          // The real backend emits `price_range` (object) and `is_available`
+          // (boolean), and never echoes `attributes`.
+          applied_filters: {
+            price_range: { min: 1, max: 100 },
+            is_available: true,
+          },
+        },
+      },
+      [FILTERABLE_ATTRIBUTE],
+    )
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x' },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+
+    expect(support.offered).toEqual(
+      expect.arrayContaining(['categories', 'collections', 'price', 'inStock']),
+    )
+    expect(support.demonstrations?.price?.endpoint).toBe('/store/search')
+    expect(support.demonstrations?.inStock?.endpoint).toBe('/store/search')
+    expect(support.held).not.toContain('price')
+    expect(support.held).not.toContain('inStock')
+
+    // The advertised attribute facet is not echoed as applied, so it stays held
+    // with a reason instead of being fabricated (E2 D3).
+    expect(support.offered).not.toContain('attr.brand')
+    expect(support.held).toContain('attr.brand')
+    expect(support.heldReasons?.['attr.brand']).toContain('not echoed')
+  })
+
+  it('still recognizes the legacy price_min/price_max and isAvailable aliases', async () => {
+    installFixture(
+      {
+        status: 200,
+        body: {
+          hits: [],
+          applied_filters: {
+            price_min: 1,
+            price_max: 100,
+            isAvailable: true,
+            attributes: { brand: ['acme'] },
+          },
+        },
+      },
+      [FILTERABLE_ATTRIBUTE],
+    )
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x' },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+
+    expect(support.offered).toEqual(
+      expect.arrayContaining(['categories', 'collections', 'price', 'inStock', 'attr.brand']),
+    )
+    expect(support.demonstrations?.price?.endpoint).toBe('/store/search')
+    expect(support.demonstrations?.['attr.brand']?.endpoint).toBe('/store/search')
+    expect(support.held).not.toContain('price')
+  })
+
+  it('records only the basic fields as applied by /store/products (never price/stock/attrs)', async () => {
+    installFixture({ status: 500 })
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x', priceMin: 10, inStock: true },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+    const basicQuery = support.demonstrations?.categories?.appliedQuery
+    expect(basicQuery).toEqual({ categoryScope: 'x' })
+    expect(basicQuery).not.toHaveProperty('priceMin')
+    expect(basicQuery).not.toHaveProperty('inStock')
+  })
+
+  it('marks support unverified when the endpoint returns no applied-filter evidence', async () => {
+    installFixture({ status: 200, body: { hits: [] } })
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x' },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+
+    expect(support.offered).not.toContain('price')
+    expect(support.offered).not.toContain('inStock')
+    expect(support.held).toEqual(expect.arrayContaining(['price', 'inStock']))
+    expect(support.heldReasons?.price).toContain('did not echo applied filters')
+  })
+})
+
+describe('MedusaProvider.getCatalogProducts — advanced endpoint executes', () => {
+  it('requests price and returns the advanced product set, with the basic endpoint never called', async () => {
+    const fixture = installFixture({
+      status: 200,
+      body: {
+        hits: [ADVANCED_PRODUCT],
+        count: 1,
+        applied_filters: { price_range: { min: 10, max: 99 } },
+      },
+    })
+    const outcome = await makeProvider().getCatalogProducts({
+      priceMin: 10,
+      priceMax: 99,
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    // The result comes from the advanced endpoint, not the basic one.
+    expect(outcome.results.products.map((p) => p.id)).toEqual(['prod_advanced'])
+    expect(outcome.results.total).toBe(1)
+    expect(outcome.results.appliedFilters).toMatchObject({
+      priceMin: 10,
+      priceMax: 99,
+    })
+    // The basic endpoint is never used to serve an advanced request.
+    expect(fixture.productListUrls).toHaveLength(0)
+    // The advanced endpoint received the requested values (the execution call,
+    // not just the support probe).
+    const execution = fixture.searchUrls.find(
+      (url) => new URL(url).searchParams.get('limit') === '50',
+    )
+    expect(execution).toBeDefined()
+    const params = new URL(execution as string).searchParams
+    expect(params.get('price_min')).toBe('10')
+    expect(params.get('price_max')).toBe('99')
+  })
+
+  it('resolves a thumbnail carried by an advanced hit to featuredImage', async () => {
+    installFixture({
+      status: 200,
+      body: {
+        hits: [ADVANCED_PRODUCT],
+        count: 1,
+        applied_filters: { price_range: { min: 10, max: 99 } },
+      },
+    })
+    const outcome = await makeProvider().getCatalogProducts({
+      priceMin: 10,
+      priceMax: 99,
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    const product = outcome.results.products[0]
+    expect(product.id).toBe('prod_advanced')
+    expect(product.featuredImage?.url).toBe('https://example.com/thumb.jpg')
+  })
+
+  it('requests an attribute and returns the advanced product set with the attribute forwarded', async () => {
+    const fixture = installFixture(
+      {
+        status: 200,
+        body: {
+          hits: [ADVANCED_PRODUCT],
+          count: 1,
+          applied_filters: { attributes: { brand: ['acme'] } },
+        },
+      },
+      [FILTERABLE_ATTRIBUTE],
+    )
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'x',
+      attributes: { brand: ['acme'] },
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(outcome.results.products.map((p) => p.id)).toEqual(['prod_advanced'])
+    expect(outcome.results.appliedFilters.attributes).toEqual({ brand: ['acme'] })
+    expect(fixture.productListUrls).toHaveLength(0)
+    const execution = fixture.searchUrls.find(
+      (url) => new URL(url).searchParams.get('limit') === '50',
+    )
+    // The emitted request parameter is the backend's ARRAY shape
+    // (`Array<{ id, values }>`), not the canonical `Record` object.
+    const emitted = new URL(execution as string).searchParams.get('attributes')
+    expect(emitted).not.toBeNull()
+    const parsed = JSON.parse(emitted as string)
+    expect(Array.isArray(parsed)).toBe(true)
+    expect(parsed).toEqual([{ id: 'brand', values: ['acme'] }])
+  })
+
+  it('rejects when the executed response did not apply the requested filter (no partial success)', async () => {
+    const fixture = installFixture({ status: 200, body: {} })
+    // Probe (limit=1) echoes the filter, so support is offered; the execution
+    // (limit=50) does not apply it, so the result must be a typed rejection.
+    server.use(
+      http.get(`${BASE}/store/search`, ({ request }) => {
+        fixture.searchUrls.push(request.url)
+        const limit = new URL(request.url).searchParams.get('limit')
+        if (limit === '1') {
+          return HttpResponse.json({ hits: [], applied_filters: { price_range: { min: 10, max: 100 } } })
+        }
+        return HttpResponse.json({ hits: [ADVANCED_PRODUCT], applied_filters: {} })
+      }),
+    )
+
+    const outcome = await makeProvider().getCatalogProducts({
+      priceMin: 10,
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(false)
+    if (outcome.ok) return
+    expect(outcome.error.code).toBe('unsupported-query')
+    expect(outcome.error.fields).toContain('priceMin')
+    expect(fixture.productListUrls).toHaveLength(0)
+  })
+})
+
+describe('MedusaProvider.getCatalogProducts — held advanced with empty scope', () => {
+  it('rejects a held advanced filter even when the category intersection is empty', async () => {
+    const fixture = installFixture({ status: 500 })
+    const outcome = await makeProvider().getCatalogProducts({
+      categoryScope: 'x',
+      categories: ['y'],
+      priceMin: 10,
+      page: 1,
+      pageSize: 50,
+    })
+
+    expect(outcome.ok).toBe(false)
+    if (outcome.ok) return
+    expect(outcome.error.code).toBe('unsupported-query')
+    expect(outcome.error.fields).toContain('priceMin')
+    expect(fixture.productListUrls).toHaveLength(0)
+  })
+})
+
+describe('MedusaProvider.searchProductsAdvanced — faithful fallback', () => {
+  it('rejects an advanced request instead of silently returning unfiltered products', async () => {
+    installFixture({ status: 404 })
+    await expect(
+      makeProvider().searchProductsAdvanced({ query: 'taladro', priceMin: 10 }),
+    ).rejects.toMatchObject({
+      message: expect.stringContaining('priceMin'),
+    })
+  })
+
+  it('still serves a basic-only caller through the getProducts fallback', async () => {
+    const fixture = installFixture({ status: 404 })
+    const result = await makeProvider().searchProductsAdvanced({
+      query: 'taladro',
+      first: 5,
+    })
+    expect(fixture.productListUrls).toHaveLength(1)
+    expect(result.products).toHaveLength(1)
+    expect(result.meta?.hybridSearchUsed).toBe(false)
+  })
+})
+
+describe('MedusaProvider.getCatalogFacetSupport — HTTP 404 absence is surfaced', () => {
+  it('holds advanced facets with a reason naming the 404, never swallowing it', async () => {
+    installFixture({ status: 404 })
+    const support = await makeProvider().getCatalogFacetSupport({
+      query: { categoryScope: 'x' },
+      categoryIds: ['pcat_x'],
+      scope: 'x',
+    })
+    expect(support.offered).not.toContain('price')
+    expect(support.held).toEqual(expect.arrayContaining(['price', 'inStock']))
+    expect(support.heldReasons?.price).toContain('404')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Live-gated: real Medusa + Meilisearch backend (E2 advanced facets).
+//
+// Mirrors the E2 gating pattern used by
+// `packages/storefront/tests/category-filter-integration.contract.test.ts`:
+// auto-live when the private fixture env exists, otherwise skipped cleanly. It
+// only reads; it never seeds, resets, or writes to the backend.
+// ---------------------------------------------------------------------------
+
+// `yarn workspace @thorprovider/adapters test` runs with cwd at the package
+// root (`packages/adapters`); `import.meta` is not permitted by the adapters
+// tsconfig, so the repo root is derived from the process cwd.
+const pkgRoot = process.cwd()
+const repoRoot = resolve(pkgRoot, '..', '..')
+
+function resolveFixtureEnvPath(): string {
+  const explicit = process.env.ELECTROSTORE_FIXTURE_ENV
+  if (explicit && existsSync(explicit)) return explicit
+  const acceptanceRoot =
+    process.env.ELECTROSTORE_ACCEPTANCE_ROOT ??
+    resolve(repoRoot, '..', '..', 'electrostore-mvp-acceptance')
+  return join(acceptanceRoot, 'extended-e2', 'task-7.1', 'fixture.env')
+}
+
+function readEnvFile(path: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    let value = trimmed.slice(eq + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    out[trimmed.slice(0, eq).trim()] = value
+  }
+  return out
+}
+
+const fixtureEnvPath = resolveFixtureEnvPath()
+
+describe.skipIf(process.env.RUN_MEDUSA_CATALOG_LIVE !== '1')(
+  'real Medusa + Meilisearch: advanced facets reflect backend truth',
+  () => {
+    beforeAll(() => {
+      if (!existsSync(fixtureEnvPath)) {
+        throw new Error(
+          `RUN_MEDUSA_CATALOG_LIVE=1 but the fixture env file is missing or unreadable: ${fixtureEnvPath}`,
+        )
+      }
+      let env: Record<string, string>
+      try {
+        env = readEnvFile(fixtureEnvPath)
+      } catch {
+        throw new Error(
+          `RUN_MEDUSA_CATALOG_LIVE=1 but the fixture env file is unreadable: ${fixtureEnvPath}`,
+        )
+      }
+      for (const name of ['MEDUSA_BASE_URL', 'MEDUSA_PUBLISHABLE_KEY', 'MEDUSA_REGION_ID']) {
+        if (!env[name]) {
+          throw new Error(
+            `RUN_MEDUSA_CATALOG_LIVE=1 but the fixture is missing required name: ${name}`,
+          )
+        }
+      }
+    })
+    it('price narrows the result set and echoes price_range; inStock offered; attributes held', async () => {
+      // Read the private fixture env inside the test so the skipped suite never
+      // touches the file (mirrors the E2 gating pattern).
+      const env = readEnvFile(fixtureEnvPath)
+      const baseUrl = (env.MEDUSA_BASE_URL ?? '').replace(/\/$/, '')
+
+      const provider = new MedusaProvider({
+        baseUrl,
+        publishableKey: env.MEDUSA_PUBLISHABLE_KEY,
+        currencyCode: env.MEDUSA_CURRENCY_CODE ?? 'usd',
+        regionId: env.MEDUSA_REGION_ID,
+        debug: false,
+      })
+
+      const searchRaw = async (query: string): Promise<Record<string, any>> => {
+        const response = await fetch(`${baseUrl}/store/search?${query}`, {
+          headers: { 'x-publishable-api-key': env.MEDUSA_PUBLISHABLE_KEY },
+        }).catch((cause) => {
+          throw new Error(`live backend unreachable at ${baseUrl}: ${String(cause)}`)
+        })
+        expect(response.status).toBe(200)
+        return (await response.json()) as Record<string, any>
+      }
+
+      // Let the real backend through msw (the suite intercepts with
+      // `onUnhandledRequest: 'error'`); no fixture handler is installed here.
+      server.use(http.all(`${baseUrl}/*`, () => passthrough()))
+
+      // Raw evidence: baseline vs price request, and the echoed applied_filters.
+      const baseline = await searchRaw('limit=100')
+      const priced = await searchRaw('limit=100&price_min=5&price_max=20')
+      expect(baseline.count).toBe(100)
+      expect(priced.count).toBe(32)
+      expect(priced.count).toBeLessThan(baseline.count)
+      expect(priced.applied_filters?.price_range).toEqual({ min: 5, max: 20 })
+      // The backend never echoes `attributes`; no attribute facet can be proven.
+      expect(
+        Object.prototype.hasOwnProperty.call(
+          priced.applied_filters ?? {},
+          'attributes',
+        ),
+      ).toBe(false)
+
+      // `is_available` is echoed when requested.
+      const available = await searchRaw('limit=1&isAvailable=true')
+      expect(available.applied_filters?.is_available).toBe(true)
+
+      // The adapter executes the price request and returns a narrowed, non-empty
+      // set (pageSize 50; the backend's hit count at limit=50 is 29 while the
+      // canonical limit=100 probe above is 32, a Meilisearch pagination quirk).
+      const outcome = await provider.getCatalogProducts({
+        priceMin: 5,
+        priceMax: 20,
+        page: 1,
+        pageSize: 50,
+      })
+      expect(outcome.ok).toBe(true)
+      if (!outcome.ok) return
+      expect(outcome.results.products.length).toBeGreaterThan(0)
+      expect(outcome.results.products.length).toBeLessThan(50)
+
+      // The support probe offers price + inStock from the real keys and holds
+      // attributes (no `attr.*` is offered because the response does not echo it).
+      const support = await provider.getCatalogFacetSupport({
+        query: { priceMin: 5, priceMax: 20, inStock: true },
+      })
+      expect(support.offered).toEqual(
+        expect.arrayContaining(['price', 'inStock']),
+      )
+      expect(support.held).not.toContain('price')
+      expect(support.held).not.toContain('inStock')
+      expect(support.offered.some((facet) => facet.startsWith('attr.'))).toBe(
+        false,
+      )
+
+      // An attribute request is never silently dropped: the backend does not
+      // demonstrate it, so the adapter rejects it as unsupported-query.
+      const attributeOutcome = await provider.getCatalogProducts({
+        attributes: { brand: ['acme'] },
+        page: 1,
+        pageSize: 50,
+      })
+      expect(attributeOutcome.ok).toBe(false)
+      if (attributeOutcome.ok) return
+      expect(attributeOutcome.error.code).toBe('unsupported-query')
+      expect(attributeOutcome.error.fields).toContain('attr.brand')
+    })
+  },
+)