@thorprovider/adapters 5.0.10 → 5.0.11

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "5.0.10",
+  "version": "5.0.11",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
+    "registry": "https://registry.npmjs.org",
     "access": "public"
   },
   "main": "dist/index.js",

package/src/core/errors.ts

@@ -37,6 +37,37 @@ export class ConfigurationError extends CommerceError {
   }
 }
 
+/**
+ * Storefront validation error.
+ * Thrown when storefront configuration is invalid or missing.
+ *
+ * Moved here from `@thorprovider/types` so that package stays type-only.
+ *
+ * @example
+ * ```typescript
+ * throw new StorefrontConfigError(
+ *   'Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID',
+ *   'medusa',
+ *   'NEXT_PUBLIC_SALES_CHANNEL_ID',
+ * );
+ * ```
+ */
+export class StorefrontConfigError extends Error {
+  public readonly platformType: string;
+  public readonly requiredEnvVar?: string;
+
+  constructor(
+    message: string,
+    platformType: string,
+    requiredEnvVar?: string,
+  ) {
+    super(message);
+    this.name = 'StorefrontConfigError';
+    this.platformType = platformType;
+    this.requiredEnvVar = requiredEnvVar;
+  }
+}
+
 /**
  * Resource not found error
  */

package/src/factory/index.ts

@@ -2,12 +2,15 @@
  * @thorprovider/adapters v2.0
  * Provider Factory - Create commerce providers dynamically
  *
- * This factory is bound to SupportedProviderType from @thorprovider/types (L1).
+ * This factory owns the runtime provider registry (SupportedProviderType +
+ * metadata + guards) and is bound to the type-only ProviderTypeString union
+ * from @thorprovider/types (L1).
  * When adding a new provider:
- * 1. Update SupportedProviderType enum in packages/types/src/provider.ts
- * 2. Add new discriminated union case here
- * 3. Create packages/adapters/src/providers/[platform]/
- * 4. Implement CommerceProvider interface
+ * 1. Update ProviderTypeString in packages/types/src/provider.ts
+ * 2. Add the enum member + metadata in ./provider-types.ts
+ * 3. Add new discriminated union case here
+ * 4. Create packages/adapters/src/providers/[platform]/
+ * 5. Implement CommerceProvider interface
  */
 
 import type { CommerceProvider } from '../types';
@@ -22,8 +25,15 @@ import { MockProvider, type MockProviderConfig } from '../providers/mock';
 import { ProviderNotFoundError, ConfigurationError } from '../core/errors';
 import type { ProviderTypeString } from '@thorprovider/types';
 
+export {
+  SupportedProviderType,
+  PROVIDER_METADATA,
+  isSupportedProviderType,
+  getProviderMetadata,
+} from './provider-types';
+
 /**
- * Supported provider types (imported from @thorprovider/types L1)
+ * Supported provider types (type-only union owned by @thorprovider/types L1)
  * Kept for backward compatibility; prefer ProviderTypeString from @thorprovider/types
  */
 export type ProviderType = ProviderTypeString;

package/src/factory/provider-types.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import {
+  PROVIDER_METADATA,
+  SupportedProviderType,
+  getProviderMetadata,
+  isSupportedProviderType,
+} from './provider-types'
+
+describe('provider registry (moved from @thorprovider/types)', () => {
+  it('accepts supported provider strings and narrows the type', () => {
+    expect(isSupportedProviderType('medusa')).toBe(true)
+    expect(isSupportedProviderType('mock')).toBe(true)
+    expect(isSupportedProviderType('stelorder')).toBe(true)
+  })
+
+  it('rejects unsupported or non-string values', () => {
+    expect(isSupportedProviderType('bogus')).toBe(false)
+    expect(isSupportedProviderType(42)).toBe(false)
+    expect(isSupportedProviderType(undefined)).toBe(false)
+  })
+
+  it('has metadata for every enum member', () => {
+    for (const value of Object.values(SupportedProviderType)) {
+      expect(PROVIDER_METADATA[value]).toBeDefined()
+    }
+  })
+
+  it('returns metadata for a supported provider', () => {
+    expect(getProviderMetadata('medusa').name).toBe('Medusa JS')
+    expect(getProviderMetadata('mock').maxRetries).toBe(0)
+  })
+})

package/src/factory/provider-types.ts

@@ -0,0 +1,176 @@
+/**
+ * @thorprovider/adapters — Provider registry (runtime)
+ *
+ * Runtime owner of the provider registry: the `SupportedProviderType` enum,
+ * its metadata, and the guards. The provider-type union contract
+ * (`ProviderTypeString`) stays type-only in `@thorprovider/types`.
+ *
+ * When adding a new provider:
+ * 1. Add the string to `ProviderTypeString` in packages/types/src/provider.ts.
+ * 2. Add the enum member + metadata entry here.
+ * 3. Create packages/adapters/src/providers/[platform]/.
+ */
+import type { ProviderTypeString } from '@thorprovider/types';
+
+/**
+ * All supported commerce platform providers.
+ * `mock` is the backend-optional runtime provider used for layout/design mode.
+ * `medusa` is fully implemented for real backend usage; others are placeholders for future expansion.
+ *
+ * @remarks Implementation status:
+ * - ✅ mock: Fixture-backed provider for backend-optional storefronts
+ * - ✅ medusa: Fully implemented
+ * - 🟡 stelorder: In progress (ERP adapter v1)
+ * - 🟡 shopify: Planned (Phase 2)
+ * - 🟡 bigcommerce: Planned (Phase 2)
+ * - 🟡 woocommerce: Planned (Phase 3)
+ * - 🟡 spree: Planned (Phase 3)
+ * - 🟡 magento: Planned (Phase 3)
+ */
+export enum SupportedProviderType {
+  Mock = 'mock',
+  Medusa = 'medusa',
+  StelOrder = 'stelorder',
+  Shopify = 'shopify',
+  BigCommerce = 'bigcommerce',
+  WooCommerce = 'woocommerce',
+  Spree = 'spree',
+  Magento = 'magento',
+}
+
+/**
+ * Metadata about each provider.
+ * Useful for UI, error messages, validation, and documentation.
+ */
+export const PROVIDER_METADATA: Record<
+  ProviderTypeString,
+  {
+    name: string;
+    description: string;
+    requiresStorefront: boolean;
+    requiredEnvVars: string[];
+    maxRetries: number;
+  }
+> = {
+  mock: {
+    name: 'Mock',
+    description: 'Fixture-backed runtime provider for layout/design mode without a real backend',
+    requiresStorefront: false,
+    requiredEnvVars: [],
+    maxRetries: 0,
+  },
+  medusa: {
+    name: 'Medusa JS',
+    description: 'Medusa v2 commerce engine',
+    requiresStorefront: true,
+    requiredEnvVars: [
+      'NEXT_PUBLIC_COMMERCE_API_URL',
+      'NEXT_PUBLIC_COMMERCE_API_KEY',
+      'NEXT_PUBLIC_SALES_CHANNEL_ID',
+    ],
+    maxRetries: 3,
+  },
+  stelorder: {
+    name: 'Stel Order',
+    description: 'Stel Order ERP and sales document API',
+    requiresStorefront: false,
+    requiredEnvVars: [
+      'NEXT_PUBLIC_COMMERCE_API_URL',
+      'NEXT_PUBLIC_COMMERCE_API_KEY',
+    ],
+    maxRetries: 2,
+  },
+  shopify: {
+    name: 'Shopify',
+    description: 'Shopify Storefront API (GraphQL)',
+    requiresStorefront: false,
+    requiredEnvVars: [
+      'NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN',
+      'NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN',
+    ],
+    maxRetries: 3,
+  },
+  bigcommerce: {
+    name: 'BigCommerce',
+    description: 'BigCommerce REST Storefront API',
+    requiresStorefront: false,
+    requiredEnvVars: [
+      'BIGCOMMERCE_STORE_HASH',
+      'BIGCOMMERCE_STOREFRONT_API_TOKEN',
+      'BIGCOMMERCE_CHANNEL_ID',
+    ],
+    maxRetries: 3,
+  },
+  woocommerce: {
+    name: 'WooCommerce',
+    description: 'WooCommerce Store API + REST API v3',
+    requiresStorefront: false,
+    requiredEnvVars: [
+      'WOOCOMMERCE_URL',
+      'WOOCOMMERCE_CONSUMER_KEY',
+      'WOOCOMMERCE_CONSUMER_SECRET',
+    ],
+    maxRetries: 3,
+  },
+  spree: {
+    name: 'Spree Commerce',
+    description: 'Spree API v2 Storefront (JSON:API)',
+    requiresStorefront: false,
+    requiredEnvVars: [
+      'SPREE_API_URL',
+    ],
+    maxRetries: 3,
+  },
+  magento: {
+    name: 'Adobe Commerce (Magento)',
+    description: 'Adobe Commerce GraphQL + REST API',
+    requiresStorefront: true,
+    requiredEnvVars: [
+      'MAGENTO_URL',
+      'MAGENTO_STORE_CODE',
+    ],
+    maxRetries: 3,
+  },
+};
+
+/**
+ * Check if a string is a valid provider type.
+ *
+ * @example
+ * ```typescript
+ * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {
+ *   // type is narrowed to ProviderTypeString
+ * }
+ * ```
+ */
+export function isSupportedProviderType(
+  value: unknown
+): value is ProviderTypeString {
+  return (
+    typeof value === 'string' &&
+    (Object.values(SupportedProviderType) as string[]).includes(value)
+  );
+}
+
+/**
+ * Get metadata for a provider type.
+ * Useful for validation, error messages, and logging.
+ *
+ * @example
+ * ```typescript
+ * const meta = getProviderMetadata('medusa');
+ * console.log(`Using ${meta.name} with max ${meta.maxRetries} retries`);
+ * ```
+ */
+export function getProviderMetadata(
+  type: ProviderTypeString
+): (typeof PROVIDER_METADATA)[ProviderTypeString] {
+  if (!isSupportedProviderType(type)) {
+    throw new Error(
+      `Unsupported provider: ${type}. Supported: ${Object.values(
+        SupportedProviderType
+      ).join(', ')}`
+    );
+  }
+  return PROVIDER_METADATA[type];
+}

package/src/index.ts

@@ -30,10 +30,6 @@ export type {
   DesignerHistoryEntry,
 } from '@thorprovider/types';
 
-export {
-  StorefrontConfigError,
-} from '@thorprovider/types';
-
 // ============================================
 // Capabilities
 // ============================================
@@ -57,6 +53,7 @@ export {
   CommerceError,
   ProviderNotFoundError,
   ConfigurationError,
+  StorefrontConfigError,
   ResourceNotFoundError,
   ProviderAPIError,
   extractErrorMessage,
@@ -188,6 +185,10 @@ export type {
 export {
   createProvider,
   isProviderType,
+  SupportedProviderType,
+  PROVIDER_METADATA,
+  isSupportedProviderType,
+  getProviderMetadata,
   type ProviderType,
   type ProviderFactoryConfig,
 } from './factory';
@@ -201,6 +202,7 @@ export {
   StelOrderProvider,
   type StelOrderProviderConfig,
   MockProvider,
+  MOCK_SALES_CHANNEL_ID,
   type MockProviderConfig,
   ShopifyProvider,
   type ShopifyProviderConfig,

package/src/providers/index.ts

@@ -24,5 +24,5 @@ export type { SpreeProviderConfig } from './spree';
 export { MagentoProvider } from './magento';
 export type { MagentoProviderConfig } from './magento';
 
-export { MockProvider } from './mock';
+export { MockProvider, MOCK_SALES_CHANNEL_ID } from './mock';
 export type { MockProviderConfig } from './mock';

package/src/providers/medusa/available-filters.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Adapter facet truthfulness — E2 `storefront-catalog-search-filters` task 2.3.
+ *
+ * `getAvailableFilters` must never fabricate a numeric range or a per-option
+ * facet count. Medusa's Store `/store/products` returns matching products and a
+ * total count, not filterable values or their ranges, so no price range is read
+ * here and the control is omitted rather than defaulted to `0..10000`. A custom
+ * attribute range/count is emitted only when the backend actually supplies the
+ * finite metadata; a missing bound or count is omitted, never replaced by a
+ * `0`/`100` default or a synthesized `0`.
+ *
+ * The HTTP boundary is intercepted with msw against a controlled fixture, so
+ * the exact emitted filter shapes are asserted.
+ */
+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,
+  },
+]
+
+const COLLECTIONS = [
+  { id: 'pcol_c1', handle: 'c1', title: 'Collection One', metadata: null },
+]
+
+/** A `multi-select` attribute whose values carry real backend counts. */
+const MULTI_WITH_COUNTS = {
+  attribute_id: 'attr_ram',
+  attribute: {
+    name: 'RAM',
+    handle: 'ram',
+    type: 'multi-select',
+    is_filterable: true,
+    is_active: true,
+    ranking: 40,
+    values: [
+      { id: 'val_8', value: '8GB', count: 15 },
+      { id: 'val_16', value: '16GB', count: 23 },
+    ],
+  },
+}
+
+/** A `multi-select` attribute whose values carry no counts. */
+const MULTI_WITHOUT_COUNTS = {
+  attribute_id: 'attr_ram',
+  attribute: {
+    ...MULTI_WITH_COUNTS.attribute,
+    values: [
+      { id: 'val_8', value: '8GB' },
+      { id: 'val_16', value: '16GB' },
+    ],
+  },
+}
+
+/** A `number` attribute with a real backend range. */
+const RANGE_WITH_BOUNDS = {
+  attribute_id: 'attr_price',
+  attribute: {
+    name: 'Price',
+    handle: 'price-attr',
+    type: 'number',
+    is_filterable: true,
+    is_active: true,
+    ranking: 30,
+    metadata: { min: 5, max: 250 },
+  },
+}
+
+/** A `number` attribute with metadata but no real bounds. */
+const RANGE_WITHOUT_BOUNDS = {
+  attribute_id: 'attr_price',
+  attribute: {
+    ...RANGE_WITH_BOUNDS.attribute,
+    metadata: {},
+  },
+}
+
+function makeProvider() {
+  return new MedusaProvider({
+    baseUrl: BASE,
+    publishableKey: PUB_KEY,
+    currencyCode: CURRENCY,
+    debug: false,
+  })
+}
+
+interface Fixture {
+  /** Every `/store/custom-attributes/category/:id` request URL. */
+  customAttributeUrls: string[]
+}
+
+function installFixture(
+  attributes: Array<Record<string, unknown>> = [],
+): Fixture {
+  const fixture: Fixture = { customAttributeUrls: [] }
+  server.use(
+    // Thor plugin endpoints are absent; the static capability fallback applies
+    // (advancedSearch/customAttributes true) and channel scoping stays unscoped.
+    http.get(`${BASE}/store/thor/capabilities`, () =>
+      HttpResponse.json({}, { status: 404 }),
+    ),
+    http.get(`${BASE}/store/thor/categories`, () =>
+      HttpResponse.json({}, { status: 404 }),
+    ),
+    http.get(`${BASE}/store/thor/collections`, () =>
+      HttpResponse.json({}, { status: 404 }),
+    ),
+    // The optional advanced endpoint is absent: the facet-support probe must
+    // treat this as "not demonstrated" rather than reading a capability flag.
+    http.get(`${BASE}/store/search`, () =>
+      HttpResponse.json(
+        { error: 'Failed to search products', message: 'search unavailable' },
+        { status: 500 },
+      ),
+    ),
+    http.get(`${BASE}/store/product-categories`, () =>
+      HttpResponse.json({
+        product_categories: CATEGORIES,
+        count: CATEGORIES.length,
+        offset: 0,
+        limit: 50,
+      }),
+    ),
+    http.get(`${BASE}/store/collections`, () =>
+      HttpResponse.json({
+        collections: COLLECTIONS,
+        count: COLLECTIONS.length,
+        offset: 0,
+        limit: 100,
+      }),
+    ),
+    http.get(
+      `${BASE}/store/custom-attributes/category/:categoryId`,
+      ({ request }) => {
+        fixture.customAttributeUrls.push(request.url)
+        return HttpResponse.json({ attributes })
+      },
+    ),
+  )
+  return fixture
+}
+
+describe('MedusaProvider.getAvailableFilters — facet truthfulness', () => {
+  it('emits no price range when the backend supplies no price metadata (never 0..10000)', async () => {
+    installFixture()
+    const filters = await makeProvider().getAvailableFilters({
+      useAdvancedSearch: true,
+    })
+
+    // The call succeeded against the real backend: basic filters are present.
+    expect(filters.map((f) => f.id)).toContain('categories')
+    // No hardcoded price filter and no synthetic range anywhere.
+    expect(filters.find((f) => f.id === 'price')).toBeUndefined()
+    expect(
+      filters.some((f) => f.type === 'range' && f.min === 0 && f.max === 10000),
+    ).toBe(false)
+  })
+
+  it('does not offer the stock toggle when the optional endpoint is absent (a capability boolean is not proof)', async () => {
+    installFixture()
+    const filters = await makeProvider().getAvailableFilters({
+      useAdvancedSearch: true,
+    })
+    // `advancedSearch: true` is advertised by the backend, but the real
+    // `/store/search` endpoint returns 500, so `inStock` is held and no toggle
+    // is offered (E2 task 2.4).
+    expect(filters.find((f) => f.id === 'isAvailable')).toBeUndefined()
+  })
+
+  it('offers the stock toggle only when the optional endpoint demonstrates inStock', async () => {
+    installFixture()
+    server.use(
+      http.get(`${BASE}/store/search`, () =>
+        HttpResponse.json({ hits: [], applied_filters: { isAvailable: true } }),
+      ),
+    )
+    const filters = await makeProvider().getAvailableFilters({
+      useAdvancedSearch: true,
+    })
+    expect(filters.find((f) => f.id === 'isAvailable')).toMatchObject({
+      type: 'boolean',
+    })
+  })
+
+  it('returns basic category/collection options with no synthesized counts', async () => {
+    installFixture()
+    const filters = await makeProvider().getAvailableFilters({})
+
+    const categories = filters.find((f) => f.id === 'categories')
+    expect(categories?.options).toEqual([
+      { value: 'x', label: 'Category X', id: 'pcat_x' },
+    ])
+    expect(categories?.options?.[0]).not.toHaveProperty('count')
+
+    const collections = filters.find((f) => f.id === 'collections')
+    expect(collections?.options?.[0]).not.toHaveProperty('count')
+  })
+
+  it('omits attribute counts when the backend supplies none', async () => {
+    installFixture([MULTI_WITHOUT_COUNTS])
+    const filters = await makeProvider().getAvailableFilters({
+      categoryId: 'pcat_x',
+      includeBasicFilters: false,
+      includeFacetCounts: true,
+    })
+
+    const ram = filters.find((f) => f.id === 'ram')
+    expect(ram?.options).toHaveLength(2)
+    expect(ram?.options?.[0]).not.toHaveProperty('count')
+  })
+
+  it('emits attribute counts only from real backend-supplied numbers', async () => {
+    installFixture([MULTI_WITH_COUNTS])
+    const filters = await makeProvider().getAvailableFilters({
+      categoryId: 'pcat_x',
+      includeBasicFilters: false,
+      includeFacetCounts: true,
+    })
+
+    const ram = filters.find((f) => f.id === 'ram')
+    expect(ram?.options).toEqual([
+      { value: '8gb', label: '8GB', id: 'val_8', count: 15 },
+      { value: '16gb', label: '16GB', id: 'val_16', count: 23 },
+    ])
+  })
+
+  it('omits attribute counts when the caller did not request them', async () => {
+    installFixture([MULTI_WITH_COUNTS])
+    const filters = await makeProvider().getAvailableFilters({
+      categoryId: 'pcat_x',
+      includeBasicFilters: false,
+      includeFacetCounts: false,
+    })
+
+    const ram = filters.find((f) => f.id === 'ram')
+    expect(ram?.options?.[0]).not.toHaveProperty('count')
+  })
+
+  it('emits an attribute range only from real backend bounds', async () => {
+    installFixture([RANGE_WITH_BOUNDS])
+    const filters = await makeProvider().getAvailableFilters({
+      categoryId: 'pcat_x',
+      includeBasicFilters: false,
+    })
+
+    expect(filters.find((f) => f.id === 'price-attr')).toMatchObject({
+      type: 'range',
+      min: 5,
+      max: 250,
+    })
+  })
+
+  it('does not fabricate a 0/100 range when metadata bounds are missing', async () => {
+    installFixture([RANGE_WITHOUT_BOUNDS])
+    const filters = await makeProvider().getAvailableFilters({
+      categoryId: 'pcat_x',
+      includeBasicFilters: false,
+    })
+
+    // No fabricated range control at all.
+    expect(filters.find((f) => f.id === 'price-attr')).toBeUndefined()
+    expect(
+      filters.some((f) => f.type === 'range' && f.min === 0 && f.max === 100),
+    ).toBe(false)
+  })
+})