@thorprovider/types 5.7.10 → 5.8.0

package/src/provider.ts

@@ -1,47 +1,22 @@
 /**
- * @thorprovider/types — Supported Providers
+ * @thorprovider/types — Supported Providers (type-only)
  *
- * Centralized list of all supported commerce providers.
- * This is the single source of truth for provider types across the monorepo.
+ * Defines the provider-type union contract shared across the monorepo.
  *
  * @remarks
- * - L1 (Foundation): Defines the contract
- * - L2 (@thorprovider/adapters) imports from here to build the factory
- * - L5 (Starters) uses the factory which is bound to this enum
- *
- * When adding a new provider (e.g., Stel Order):
- * 1. Add to SupportedProviderType enum below
- * 2. Update @thorprovider/adapters factory/index.ts with discriminated union
- * 3. Create packages/adapters/src/providers/shopify/
- * 4. Implement CommerceProvider interface
- * 5. Update StorefrontPlatformType in storefront.ts
- */
-
-/**
- * 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)
+ * - L1 (Foundation): owns the `ProviderTypeString` union type only.
+ * - L2 (@thorprovider/adapters) owns the runtime provider registry
+ *   (`SupportedProviderType`, `PROVIDER_METADATA`, `isSupportedProviderType`,
+ *   `getProviderMetadata`) in `@thorprovider/adapters`.
+ *
+ * When adding a new provider:
+ * 1. Add the string to `ProviderTypeString` below.
+ * 2. Add it to `SupportedProviderType` + `PROVIDER_METADATA` in
+ *    packages/adapters/src/factory/provider-types.ts.
+ * 3. Create packages/adapters/src/providers/[platform]/ and implement the
+ *    `CommerceProvider` interface.
+ * 4. Update `StorefrontPlatformType` in storefront.ts.
  */
-export enum SupportedProviderType {
-  Mock = 'mock',
-  Medusa = 'medusa',
-  StelOrder = 'stelorder',
-  Shopify = 'shopify',
-  BigCommerce = 'bigcommerce',
-  WooCommerce = 'woocommerce',
-  Spree = 'spree',
-  Magento = 'magento',
-}
 
 /**
  * Union type of all supported provider string values.
@@ -55,142 +30,3 @@ export enum SupportedProviderType {
  * ```
  */
 export type ProviderTypeString = 'mock' | 'medusa' | 'stelorder' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
-
-/**
- * Metadata about each provider.
- * Useful for UI, error messages, validation, and documentation.
- *
- * @internal
- */
-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).includes(value as SupportedProviderType)
-  );
-}
-
-/**
- * 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/storefront.ts

@@ -15,9 +15,11 @@
  * Supported commerce platform types for storefront identification.
  *
  * @remarks
- * Keep this type in sync with SupportedProviderType from provider.ts.
- * When adding a new provider, update both packages/types/src/provider.ts
- * and this type.
+ * Keep this type in sync with ProviderTypeString from provider.ts and the
+ * runtime registry in @thorprovider/adapters
+ * (packages/adapters/src/factory/provider-types.ts).
+ * When adding a new provider, update packages/types/src/provider.ts, this
+ * type, and the adapters registry.
  *
  * Currently supported:
  * - ✅ 'mock': Backend-optional layout/design mode using fixture data
@@ -98,32 +100,3 @@ export interface StorefrontContext {
    */
   metadata?: Record<string, unknown>;
 }
-
-/**
- * Storefront validation error.
- * Thrown when storefront configuration is invalid or missing.
- *
- * @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;
-  }
-}