@thorprovider/adapters 4.1.0 → 4.2.1

package/docs/capabilities-system.md

@@ -141,3 +141,33 @@ Capabilities are calculated once during provider initialization. Accessing `comm
 
 - [Providers Overview](providers-overview.md)
 - [Services Overview](services-overview.md)
+
+## Per-Provider Capability Matrix
+
+### Stel Order (ERP Adapter)
+
+| Capability | Value | Notes |
+|------------|-------|-------|
+| `fetchOrders` | ✅ true | Read sales orders via `/salesOrders` |
+| `listPaymentProviders` | ✅ true | List STEL payment options via `/paymentOptions` |
+| `manageAddresses` | ✅ true | Via client main-address (PUT /clients) |
+| `updateProfile` | ❌ false | No customer self-service (ERP admin only) |
+| `updateEmail` | ❌ false | — |
+| `changePasswordDirect` | ❌ false | No auth system |
+| `changePasswordViaEmail` | ❌ false | No auth system |
+| `deleteAccount` | ❌ false | — |
+| `uploadAvatar` | ❌ false | — |
+| `avatarViaMetadata` | ❌ false | — |
+| `customAttributes` | ❌ false | — |
+| `cancelOrder` | ❌ false | ERP orders are read-only from adapter |
+| `defaultAddress` | ❌ false | — |
+| `applyDiscounts` | ❌ false | No cart/checkout |
+| `shippingCalculation` | ❌ false | No cart/checkout |
+| `guestCheckout` | ❌ false | No cart/checkout |
+| `savedPaymentMethods` | ❌ false | — |
+| `regionSpecificPayments` | ❌ false | Single-company ERP |
+| `wishlist` | ❌ false | — |
+| `advancedSearch` | ❌ false | Client-side text filter only |
+| `facetedFilters` | ❌ false | — |
+| `productReviews` | ❌ false | — |
+| `loyaltyProgram` | ❌ false | — |

package/docs/getting-started.md

@@ -1,23 +1,25 @@
-# Getting Started
-
 ---
+title: "Getting started"
+purpose: "Provide a quick setup guide for integrating Thor adapters in mock or live backend mode"
+lastReviewed: "2026-05-01"
 type: how-to
 tags: [setup, installation, adapters, medusa, configuration]
 related:
   - services-overview.md
   - providers-overview.md
   - authentication.md
-updated: 2026-02-28
 ---
 
-Quick setup guide for integrating Thor adapters into our project.
+# Getting Started
+
+Quick setup guide for integrating Thor adapters into our project. Start with `mock` for backend-optional development, or configure a real backend immediately.
 
 ## Prerequisites
 
 - Node.js 18+
 - Yarn 4+ (PnP mode)
-- Access to a Medusa.js v2 backend
-- Medusa Publishable API Key
+- Optional: access to a Medusa.js v2 backend
+- Optional: Medusa Publishable API Key
 
 ## Quick Example
 
@@ -25,6 +27,14 @@ Quick setup guide for integrating Thor adapters into our project.
 import { createProvider } from '@thorprovider/adapters';
 
 const commerce = createProvider({
+  provider: 'mock',
+  config: {
+    currencyCode: 'USD',
+  },
+});
+
+// Or use a real backend
+const liveCommerce = createProvider({
   provider: 'medusa',
   config: {
     baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
@@ -53,6 +63,14 @@ Create a shared instance for our application.
 import { createProvider } from '@thorprovider/adapters';
 
 export const commerce = createProvider({
+  provider: 'mock',
+  config: {
+    debug: process.env.NODE_ENV === 'development',
+  },
+});
+
+// Switch to a real backend when ready
+export const liveCommerce = createProvider({
   provider: 'medusa',
   config: {
     baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
@@ -64,14 +82,17 @@ export const commerce = createProvider({
 
 ### Step 3: Configure Environment Variables
 
-Create `.env.local` to store backend credentials.
+Create `.env.local` to store runtime configuration.
 
 ```env
-# Backend Configuration
-NEXT_PUBLIC_COMMERCE_PROVIDER=medusa
+# Mock-first configuration
+NEXT_PUBLIC_COMMERCE_PROVIDER=mock
+NEXT_PUBLIC_DEFAULT_CURRENCY=USD
+
+# Live backend configuration (only required for real providers)
+# NEXT_PUBLIC_COMMERCE_PROVIDER=medusa
 NEXT_PUBLIC_COMMERCE_API_URL=http://localhost:9000
 NEXT_PUBLIC_COMMERCE_API_KEY=your_publishable_key_here
-NEXT_PUBLIC_DEFAULT_CURRENCY=USD
 ```
 
 ### Step 4: Use in Server Components (Next.js)
@@ -96,7 +117,7 @@ export default async function ProductsPage() {
 ## ✅ DO's
 
 1. **Use Singleton Pattern:** Create one instance of the provider and export it.
-2. **Handle Environment Variables:** Always use `!` or validation to ensure `baseUrl` exists.
+2. **Handle Environment Variables:** Require `baseUrl` only for real backends.
 3. **Prefer Server-Side:** Fetch data in Server Components whenever possible.
 4. **Use TypeScript Types:** Leverage the exported types from `@thorprovider/adapters` for better DX.
 5. **Configure Debug Mode:** Enable `debug: true` during development to trace API issues.

package/docs/providers-overview.md

@@ -1,15 +1,17 @@
-# Providers Overview
-
 ---
+title: "Providers overview"
+purpose: "Describe the supported commerce providers and how Thor Adapters abstracts them behind a unified interface"
+lastReviewed: "2026-05-01"
 type: guide
 tags: [architecture, providers, medusa, shopify, roadmap]
 related:
   - capabilities-system.md
   - services-overview.md
   - getting-started.md
-updated: 2026-02-28
 ---
 
+# Providers Overview
+
 Overview of the e-commerce platforms supported by Thor Adapters and how they are abstracted into a unified interface.
 
 ## Overview
@@ -28,6 +30,10 @@ Thor Adapters eliminate these problems by wrapping the data layer in a consisten
 
 ## Current Support Matrix
 
+### Mock
+**Status:** ✅ Production Ready
+Fixture-backed provider for local development, previews, design-mode storefront work, and backend-optional scaffolds.
+
 ### Medusa (v2.0)
 **Status:** ✅ Production Ready
 Our primary integration, highly optimized for headless performance.
@@ -36,6 +42,18 @@ Our primary integration, highly optimized for headless performance.
 **Status:** 🚧 In Development (Phase 1)
 Focusing on Storefront API integration for product discovery and cart.
 
+### Stel Order
+**Status:** ✅ ERP Adapter (v1)
+Single-company ERP integration for catalog, categories, inventory visibility, customers (STEL clients), sales orders, and payment/delivery option listing.
+
+**Scope & Limitations:**
+- **Supported:** Products, categories (aliased as collections), warehouses/inventory, customers, orders, payment methods, delivery options, storefront context
+- **Unsupported:** Cart, checkout, customer auth/profile self-service, discount codes, fulfillment orchestration, recommendations, advanced search
+- **Rate limits:** 60 req/min + low daily limits — designed to minimize API round-trips
+- **Single-company:** No multi-tenant/storefront channel assumptions; `requiresStorefront: false`
+- **No variants:** STEL products are single-SKU; the adapter creates one synthetic variant per product
+- **Client-side search:** STEL has no fulltext search; `getProducts({ query })` filters in-memory after fetch
+
 ### WooCommerce
 **Status:** 🗓️ Planned
 Targeting the REST API for hybrid headless setups.
@@ -56,9 +74,11 @@ graph TD
   B --> C[Medusa Provider]
   B --> D[Shopify Provider]
   B --> E[Mock Provider]
+  B --> F2[Stel Order Provider]
   C --> F[Unified Commerce Interface]
   D --> F
   E --> F
+  F2 --> F
 ```
 
 ## Design Decisions

package/docs/services-overview.md

@@ -63,6 +63,22 @@ Handles customer account management and secure sessions.
 - Profile and address management
 - Metadata extensions
 
+### 5. ERP Adapters (Stel Order)
+Not all providers are full storefronts. ERP adapters like **Stel Order** expose a subset of services:
+
+| Service | Stel Order Support |
+|---------|-------------------|
+| Products & Categories | ✅ Read-only catalog with inventory visibility |
+| Collections | ✅ Aliased from categories |
+| Cart & Checkout | ❌ Not supported (ERP has no cart concept) |
+| Authentication | ❌ Not supported (API-key auth only, no customer login) |
+| Customers (CRM) | ✅ Read + update via STEL clients endpoint |
+| Orders | ✅ Read sales orders; no create/cancel from adapter |
+| Payment Methods | ✅ List STEL payment options |
+| Shipping/Delivery | ✅ List STEL delivery options |
+
+Unsupported methods throw `ProviderAPIError` (501) with a clear message explaining the ERP limitation.
+
 ## Service Interactions
 
 ```mermaid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -11,16 +11,18 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "development": "./src/index.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "development": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
     }
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
-    "test": "echo \"No tests yet\" && exit 0",
+    "test": "vitest run --config vitest.config.ts",
+    "test:live": "vitest run --config vitest.config.ts src/providers/stelorder/live-smoke.test.ts",
     "generate:agent-index": "node ../../scripts/generate-package-agents-index.cjs packages/adapters @thorprovider/adapters"
   },
   "dependencies": {
@@ -31,8 +33,10 @@
     "jose": "^6.2.2"
   },
   "devDependencies": {
+    "msw": "^2.12.3",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
   },
   "repository": {
     "type": "git",

package/quick-reference.md

@@ -57,6 +57,7 @@ Framework-agnostic business logic SDK for e-commerce operations. Provides unifie
 ```
 createProvider() → Provider instance
 ├── MedusaProvider (complete implementation)
+├── StelOrderProvider (ERP: catalog, CRM, orders — no cart/checkout/auth)
 ├── ShopifyProvider (planned)
 └── Custom providers (extensible)
 ```

package/src/factory/index.ts

@@ -17,6 +17,8 @@ import { BigCommerceProvider, type BigCommerceProviderConfig } from '../provider
 import { WooCommerceProvider, type WooCommerceProviderConfig } from '../providers/woocommerce';
 import { SpreeProvider, type SpreeProviderConfig } from '../providers/spree';
 import { MagentoProvider, type MagentoProviderConfig } from '../providers/magento';
+import { StelOrderProvider, type StelOrderProviderConfig } from '../providers/stelorder';
+import { MockProvider, type MockProviderConfig } from '../providers/mock';
 import { ProviderNotFoundError, ConfigurationError } from '../core/errors';
 import type { ProviderTypeString } from '@thorprovider/types';
 
@@ -30,7 +32,9 @@ export type ProviderType = ProviderTypeString;
  * Provider configuration discriminated union
  */
 export type ProviderFactoryConfig =
+  | { provider: 'mock'; config: MockProviderConfig }
   | { provider: 'medusa'; config: MedusaProviderConfig }
+  | { provider: 'stelorder'; config: StelOrderProviderConfig }
   | { provider: 'shopify'; config: ShopifyProviderConfig }
   | { provider: 'bigcommerce'; config: BigCommerceProviderConfig }
   | { provider: 'woocommerce'; config: WooCommerceProviderConfig }
@@ -73,8 +77,12 @@ export function createProvider(options: ProviderFactoryConfig | RuntimeProviderC
   const config = options.config as any;
   
   switch (options.provider) {
+    case 'mock':
+      return new MockProvider(config);
     case 'medusa':
       return new MedusaProvider(config);
+    case 'stelorder':
+      return new StelOrderProvider(config);
     case 'shopify':
       return new ShopifyProvider(config);
     case 'bigcommerce':

package/src/index.ts

@@ -38,7 +38,9 @@ export {
 // Capabilities
 // ============================================
 export {
+  MOCK_CAPABILITIES,
   MEDUSA_CAPABILITIES,
+  STELORDER_CAPABILITIES,
   SHOPIFY_CAPABILITIES,
   BIGCOMMERCE_CAPABILITIES,
   WOOCOMMERCE_CAPABILITIES,
@@ -192,6 +194,10 @@ export {
 export {
   MedusaProvider,
   type MedusaProviderConfig,
+  StelOrderProvider,
+  type StelOrderProviderConfig,
+  MockProvider,
+  type MockProviderConfig,
   ShopifyProvider,
   type ShopifyProviderConfig,
   BigCommerceProvider,

package/src/providers/index.ts

@@ -6,6 +6,9 @@
 export { MedusaProvider } from './medusa';
 export type { MedusaProviderConfig } from './medusa';
 
+export { StelOrderProvider } from './stelorder';
+export type { StelOrderProviderConfig } from './stelorder';
+
 export { ShopifyProvider } from './shopify';
 export type { ShopifyProviderConfig } from './shopify';
 
@@ -20,3 +23,6 @@ export type { SpreeProviderConfig } from './spree';
 
 export { MagentoProvider } from './magento';
 export type { MagentoProviderConfig } from './magento';
+
+export { MockProvider } from './mock';
+export type { MockProviderConfig } from './mock';