@thorprovider/adapters 5.0.9 → 5.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "5.0.9",
+  "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",
@@ -45,4 +45,4 @@
     "directory": "packages/adapters"
   },
   "license": "MIT"
-}
+}

package/publish.log

@@ -0,0 +1,93 @@
+npm warn Unknown project config "network-concurrency". This will stop working in the next major version of npm.
+npm warn publish npm auto-corrected some errors in your package.json when publishing.  Please run "npm pkg fix" to address these errors.
+npm warn publish errors corrected:
+npm warn publish "repository.url" was normalized to "git+https://github.com/thorprovider/thor-commerce.git"
+npm notice
+npm notice 📦  @thor/adapters@3.0.1
+npm notice Tarball Contents
+npm notice 629B AGENTS.md
+npm notice 9.1kB CHANGELOG.md
+npm notice 19.2kB README.md
+npm notice 73.6kB dist/index.d.mts
+npm notice 73.6kB dist/index.d.ts
+npm notice 191.6kB dist/index.js
+npm notice 377.7kB dist/index.js.map
+npm notice 187.4kB dist/index.mjs
+npm notice 377.4kB dist/index.mjs.map
+npm notice 4.7kB docs/authentication.md
+npm notice 4.3kB docs/capabilities-system.md
+npm notice 9.9kB docs/category-customization.md
+npm notice 11.0kB docs/fetch-reliability-solution.md
+npm notice 4.4kB docs/getting-started.md
+npm notice 7.8kB docs/multi-tenant-channel-scoping.md
+npm notice 4.5kB docs/profile-management.md
+npm notice 3.7kB docs/providers-overview.md
+npm notice 2.1kB docs/RETRY_SOLUTION_SUMMARY.md
+npm notice 5.2kB docs/services-overview.md
+npm notice 4.0kB docs/update-documentation.md
+npm notice 1.2kB package.json
+npm notice 6.3kB quick-reference.md
+npm notice 2.5kB src/admin/AdminAuthService.ts
+npm notice 2.4kB src/admin/AdminSessionService.ts
+npm notice 414B src/admin/index.ts
+npm notice 4.2kB src/admin/MetricsService.ts
+npm notice 2.5kB src/backend/BackendMetadataAdapter.ts
+npm notice 3.5kB src/backend/factory.ts
+npm notice 312B src/backend/index.ts
+npm notice 3.9kB src/backend/medusa/MedusaMetadataAdapter.ts
+npm notice 6.3kB src/core/errors.js
+npm notice 3.5kB src/core/errors.ts
+npm notice 11.3kB src/core/fetch-utils.js
+npm notice 6.0kB src/core/fetch-utils.ts
+npm notice 141B src/core/index.ts
+npm notice 2.3kB src/core/logger.js
+npm notice 1.1kB src/core/logger.ts
+npm notice 2.0kB src/factory/index.ts
+npm notice 4.5kB src/index.ts
+npm notice 2.7kB src/lib/money-transform.ts
+npm notice 6.2kB src/metadata/channel-scope-validation.js
+npm notice 5.1kB src/metadata/channel-scope-validation.ts
+npm notice 7.6kB src/metadata/channel-scope.js
+npm notice 8.2kB src/metadata/channel-scope.ts
+npm notice 3.3kB src/metadata/index.js
+npm notice 810B src/metadata/index.ts
+npm notice 148B src/providers/index.ts
+npm notice 30.0kB src/providers/medusa/auth.js
+npm notice 15.1kB src/providers/medusa/auth.ts
+npm notice 6.2kB src/providers/medusa/fulfillment-planner.ts
+npm notice 151.8kB src/providers/medusa/index.js
+npm notice 147.6kB src/providers/medusa/index.ts
+npm notice 184B src/providers/medusa/medusa.ts
+npm notice 11.0kB src/providers/medusa/payment.js
+npm notice 7.2kB src/providers/medusa/payment.ts
+npm notice 25.8kB src/providers/medusa/transforms.js
+npm notice 19.8kB src/providers/medusa/transforms.ts
+npm notice 5.5kB src/resilience/circuit-breaker.ts
+npm notice 238B src/resilience/index.ts
+npm notice 7.6kB src/resilience/README.md
+npm notice 4.8kB src/types/capabilities.types.js
+npm notice 4.7kB src/types/capabilities.types.ts
+npm notice 513B src/types/index.ts
+npm notice 350B src/types/provider.js
+npm notice 365B src/types/provider.ts
+npm notice 6.5kB src/types/ui-responses.ts
+npm notice 1.1kB src/utils/city-coordinates.ts
+npm notice 1.3kB src/utils/geolocation.ts
+npm notice 5.6kB src/utils/payment-utils.js
+npm notice 6.5kB src/utils/payment-utils.ts
+npm notice 357B tsconfig.json
+npm notice 370B tsup.config.ts
+npm notice Tarball Details
+npm notice name: @thor/adapters
+npm notice version: 3.0.1
+npm notice filename: thor-adapters-3.0.1.tgz
+npm notice package size: 413.9 kB
+npm notice unpacked size: 1.9 MB
+npm notice shasum: 696c58c4b5629ad1ec09336238ea157aad015e3d
+npm notice integrity: sha512-tIweHlz73prg8[...]3KYkFTyNlUX4w==
+npm notice total files: 72
+npm notice
+npm notice Publishing to https://npm.pkg.github.com with tag latest and restricted access
+npm error code E401
+npm error 401 Unauthorized - PUT https://npm.pkg.github.com/@thor%2fadapters - unauthenticated: User cannot be authenticated with the token provided.
+npm error A complete log of this run can be found in: /home/nelson/.npm/_logs/2026-04-16T15_45_37_415Z-debug-0.log

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';