@thorprovider/adapters 5.0.10 → 5.0.12

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "5.0.10",
+  "version": "5.0.12",
   "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",
@@ -44,4 +45,4 @@
     "directory": "packages/adapters"
   },
   "license": "MIT"
-}
+}

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/auth.test.ts

@@ -1,5 +1,13 @@
 /**
  * @fileoverview Tests for MedusaAuthProvider
+ *
+ * Covers the channel-linked registration/login workflow
+ * (change: storefront-live-auth-orders-acceptance, task 2.4):
+ * - the registration token is persisted in the request-scoped MUTABLE custom
+ *   storage before the customer-linking call, and that call carries it;
+ * - an auth identity without a linked customer is not treated as complete;
+ * - the channel-linking route being unavailable fails closed with a typed error;
+ * - login links the customer's channel idempotently.
  */
 
 import { describe, expect, it, vi } from 'vitest'
@@ -17,6 +25,9 @@ function makeSdkStub() {
       resetPassword: vi.fn(),
       updateProvider: vi.fn(),
     },
+    client: {
+      fetch: vi.fn(),
+    },
     store: {
       customer: {
         retrieve: vi.fn(),
@@ -31,20 +42,49 @@ function makeSdkStub() {
   } as unknown as Medusa
 }
 
-function makeStorageWithToken(token: string | null) {
+/** Access the stubbed SDK client fetch as a vitest mock. */
+function mockFetch(sdk: Medusa): ReturnType<typeof vi.fn> {
+  return sdk.client.fetch as unknown as ReturnType<typeof vi.fn>
+}
+
+/** A mutable request-scoped storage that records the order of its operations. */
+function makeRecordingStorage(
+  token: string | null,
+  events: string[] = [],
+): {
+  storage: {
+    getItem: (key: string) => Promise<string | null>
+    setItem: (key: string, value: string) => Promise<void>
+    removeItem: () => Promise<void>
+  }
+  peek: () => string | null
+} {
   let stored: string | null = token
   return {
-    getItem: () => Promise.resolve(stored),
-    setItem: (_key: string, value: string) => { stored = value; return Promise.resolve() },
-    removeItem: () => { stored = null; return Promise.resolve() },
+    storage: {
+      getItem: () => Promise.resolve(stored),
+      setItem: (_key: string, value: string) => {
+        stored = value
+        events.push(`set:${value}`)
+        return Promise.resolve()
+      },
+      removeItem: () => {
+        stored = null
+        events.push('remove')
+        return Promise.resolve()
+      },
+    },
+    peek: () => stored,
   }
 }
 
-function makeAuthConfig(token: string | null = 'jwt-bearer-token') {
+function makeAuthConfig(token: string | null = 'jwt-bearer-token', customStorage?: unknown) {
   return {
     method: 'jwt' as const,
     storage: 'memory' as const,
-    customStorage: makeStorageWithToken(token),
+    customStorage:
+      (customStorage as ReturnType<typeof makeRecordingStorage>['storage']) ??
+      makeRecordingStorage(token).storage,
   }
 }
 
@@ -56,7 +96,10 @@ describe('MedusaAuthProvider', () => {
   it('stores jwt token and returns customer on login', async () => {
     const sdk = makeSdkStub()
     sdk.auth.login = vi.fn().mockResolvedValue('jwt-bearer-token')
-    sdk.store.customer.retrieve = vi.fn().mockResolvedValue({ customer: { id: 'cus_1', email: 'test@example.com' } })
+    mockFetch(sdk).mockResolvedValue({ linked: true })
+    sdk.store.customer.retrieve = vi
+      .fn()
+      .mockResolvedValue({ customer: { id: 'cus_1', email: 'test@example.com' } })
 
     const provider = new MedusaAuthProvider(sdk, makeAuthConfig('jwt-bearer-token'), false)
 
@@ -70,13 +113,45 @@ describe('MedusaAuthProvider', () => {
     })
   })
 
+  it('links the customer channel idempotently on login', async () => {
+    const sdk = makeSdkStub()
+    sdk.auth.login = vi.fn().mockResolvedValue('jwt-bearer-token')
+    mockFetch(sdk).mockResolvedValue({ linked: false, reason: 'already_linked' })
+    sdk.store.customer.retrieve = vi
+      .fn()
+      .mockResolvedValue({ customer: { id: 'cus_1', email: 'test@example.com' } })
+
+    const provider = new MedusaAuthProvider(sdk, makeAuthConfig('jwt-bearer-token'), false)
+    const result = await provider.login({ email: 'test@example.com', password: 'secret' })
+
+    expect(sdk.client.fetch).toHaveBeenCalledWith(
+      '/store/thor/customers/me/channels',
+      expect.objectContaining({ method: 'POST' }),
+    )
+    expect(result.customer?.id).toBe('cus_1')
+  })
+
+  it('fails closed with a typed error when the channel link route is unavailable on login', async () => {
+    const sdk = makeSdkStub()
+    sdk.auth.login = vi.fn().mockResolvedValue('jwt-bearer-token')
+    mockFetch(sdk).mockRejectedValue(Object.assign(new Error('not found'), { status: 404 }))
+
+    const provider = new MedusaAuthProvider(sdk, makeAuthConfig('jwt-bearer-token'), false)
+
+    await expect(
+      provider.login({ email: 'test@example.com', password: 'secret' }),
+    ).rejects.toMatchObject({ provider: 'CUSTOMER_LINK_UNAVAILABLE' })
+  })
+
   it('throws ProviderAPIError with login code on auth failure', async () => {
     const sdk = makeSdkStub()
     sdk.auth.login = vi.fn().mockRejectedValue(new Error('bad credentials'))
 
     const provider = new MedusaAuthProvider(sdk, makeAuthConfig(), false)
 
-    await expect(provider.login({ email: 'test@example.com', password: 'secret' })).rejects.toMatchObject({
+    await expect(
+      provider.login({ email: 'test@example.com', password: 'secret' }),
+    ).rejects.toMatchObject({
       name: 'ProviderAPIError',
       code: 'PROVIDER_API_ERROR',
       provider: 'LOGIN_FAILED',
@@ -86,7 +161,9 @@ describe('MedusaAuthProvider', () => {
 
   it('returns requiresAction when login requires verification (v2.16.0)', async () => {
     const sdk = makeSdkStub()
-    sdk.auth.login = vi.fn().mockResolvedValue({ verification_required: true, token: 'verify-token' })
+    sdk.auth.login = vi
+      .fn()
+      .mockResolvedValue({ verification_required: true, token: 'verify-token' })
 
     const provider = new MedusaAuthProvider(sdk, makeAuthConfig(), false)
     const result = await provider.login({ email: 'test@example.com', password: 'secret' })
@@ -95,19 +172,22 @@ describe('MedusaAuthProvider', () => {
     expect(result.token).toBe('verify-token')
   })
 
-  it('stores jwt token and returns customer on register (v2.16.0)', async () => {
+  it('persists the registration token before the channel-linking call and returns the linked customer', async () => {
     const sdk = makeSdkStub()
-    sdk.auth.register = vi.fn().mockResolvedValue(undefined)
-    sdk.auth.login = vi.fn().mockResolvedValue('jwt-bearer-token')
-    sdk.store.customer.create = vi.fn().mockResolvedValue({
-      customer: { id: 'cus_1', email: 'test@example.com', first_name: 'Test', last_name: 'User' },
-    })
-    sdk.store.customer.retrieve = vi.fn().mockResolvedValue({
-      customer: { id: 'cus_1', email: 'test@example.com', first_name: 'Test', last_name: 'User' },
+    const events: string[] = []
+    const { storage } = makeRecordingStorage(null, events)
+    sdk.auth.register = vi.fn().mockResolvedValue('registration-token')
+    sdk.auth.login = vi.fn().mockResolvedValue('session-token')
+    mockFetch(sdk).mockImplementation(async (path: string) => {
+      events.push(`fetch:${path}`)
+      if (path === '/store/thor/customers') return { customer: { id: 'cus_1' } }
+      throw new Error(`unexpected ${path}`)
     })
+    sdk.store.customer.retrieve = vi
+      .fn()
+      .mockResolvedValue({ customer: { id: 'cus_1', email: 'test@example.com' } })
 
-    const provider = new MedusaAuthProvider(sdk, makeAuthConfig('jwt-bearer-token'), false)
-
+    const provider = new MedusaAuthProvider(sdk, makeAuthConfig(null, storage), false)
     const result = await provider.register({
       email: 'test@example.com',
       password: 'secret',
@@ -119,12 +199,55 @@ describe('MedusaAuthProvider', () => {
       email: 'test@example.com',
       password: 'secret',
     })
-    expect(sdk.auth.login).toHaveBeenCalledWith('customer', 'emailpass', {
-      email: 'test@example.com',
-      password: 'secret',
-    })
-    expect(result.token).toBe('jwt-bearer-token')
-    expect(result.customer?.email).toBe('test@example.com')
+    // The registration token was written to the request-scoped mutable storage
+    // BEFORE the linking call carried it.
+    expect(events.indexOf('set:registration-token')).toBeGreaterThanOrEqual(0)
+    expect(events.indexOf('set:registration-token')).toBeLessThan(
+      events.indexOf('fetch:/store/thor/customers'),
+    )
+    // The linking call goes through the channel-linking route, not native create.
+    expect(sdk.client.fetch).toHaveBeenCalledWith(
+      '/store/thor/customers',
+      expect.objectContaining({ method: 'POST' }),
+    )
+    expect(sdk.store.customer.create).not.toHaveBeenCalled()
+    expect(result.token).toBe('session-token')
+    expect(result.customer?.id).toBe('cus_1')
+  })
+
+  it('does not treat an auth identity without a linked customer as complete', async () => {
+    const sdk = makeSdkStub()
+    sdk.auth.register = vi.fn().mockResolvedValue('registration-token')
+    // The linking route returns no customer id -> incomplete.
+    mockFetch(sdk).mockResolvedValue({ customer: {} })
+
+    const provider = new MedusaAuthProvider(sdk, makeAuthConfig(null), false)
+
+    await expect(
+      provider.register({
+        email: 'test@example.com',
+        password: 'secret',
+        first_name: 'Test',
+        last_name: 'User',
+      }),
+    ).rejects.toMatchObject({ provider: 'CUSTOMER_LINK_INCOMPLETE' })
+  })
+
+  it('fails closed with a typed unavailable error when the linking route is missing', async () => {
+    const sdk = makeSdkStub()
+    sdk.auth.register = vi.fn().mockResolvedValue('registration-token')
+    mockFetch(sdk).mockRejectedValue(Object.assign(new Error('not found'), { status: 404 }))
+
+    const provider = new MedusaAuthProvider(sdk, makeAuthConfig(null), false)
+
+    await expect(
+      provider.register({
+        email: 'test@example.com',
+        password: 'secret',
+        first_name: 'Test',
+        last_name: 'User',
+      }),
+    ).rejects.toMatchObject({ provider: 'CUSTOMER_LINK_UNAVAILABLE' })
   })
 
   it('requires email when resetting password', async () => {