@thorprovider/adapters 4.2.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/providers-overview.md

@@ -42,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.
@@ -62,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.2.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,7 @@ 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';
@@ -33,6 +34,7 @@ export type ProviderType = ProviderTypeString;
 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 }
@@ -79,6 +81,8 @@ export function createProvider(options: ProviderFactoryConfig | RuntimeProviderC
       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

@@ -40,6 +40,7 @@ export {
 export {
   MOCK_CAPABILITIES,
   MEDUSA_CAPABILITIES,
+  STELORDER_CAPABILITIES,
   SHOPIFY_CAPABILITIES,
   BIGCOMMERCE_CAPABILITIES,
   WOOCOMMERCE_CAPABILITIES,
@@ -193,6 +194,8 @@ export {
 export {
   MedusaProvider,
   type MedusaProviderConfig,
+  StelOrderProvider,
+  type StelOrderProviderConfig,
   MockProvider,
   type MockProviderConfig,
   ShopifyProvider,

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

package/src/providers/stelorder/client.test-helpers.ts

@@ -0,0 +1,3 @@
+import { setupServer } from 'msw/node'
+
+export const server = setupServer()

package/src/providers/stelorder/client.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { server } from './client.test-helpers'
+import { StelOrderClient } from './client'
+
+describe('StelOrderClient', () => {
+  it('normalizes base url and sends APIKEY header', async () => {
+    server.use(
+      http.get('https://stel.example.com/app/products', ({ request }) => {
+        expect(request.headers.get('APIKEY')).toBe('secret')
+        expect(request.headers.get('accept')).toBe('application/json')
+        return HttpResponse.json([{ id: 1, name: 'P1' }])
+      }),
+    )
+
+    const client = new StelOrderClient({
+      baseUrl: 'https://stel.example.com/api/openapi.json',
+      apiKey: 'secret',
+    })
+
+    const products = await client.list<{ id: number; name: string }>('products')
+    expect(products).toEqual([{ id: 1, name: 'P1' }])
+  })
+
+  it('supports create update and delete', async () => {
+    server.use(
+      http.post('https://stel.example.com/app/clients', async ({ request }) => {
+        expect(await request.json()).toEqual({ email: 'a@b.com' })
+        return HttpResponse.json({ id: 1, email: 'a@b.com' })
+      }),
+      http.put('https://stel.example.com/app/clients/1', async ({ request }) => {
+        expect(await request.json()).toEqual({ email: 'c@d.com' })
+        return HttpResponse.json({ id: 1, email: 'c@d.com' })
+      }),
+      http.delete('https://stel.example.com/app/clients/1', () => HttpResponse.text('', { status: 204 })),
+    )
+
+    const client = new StelOrderClient({ baseUrl: 'https://stel.example.com', apiKey: 'secret' })
+    await expect(client.create('clients', { email: 'a@b.com' })).resolves.toEqual({ id: 1, email: 'a@b.com' })
+    await expect(client.update('clients', 1, { email: 'c@d.com' })).resolves.toEqual({ id: 1, email: 'c@d.com' })
+    await expect(client.remove('clients', 1)).resolves.toBeUndefined()
+  })
+
+  it('throws provider api error on non-ok responses', async () => {
+    server.use(
+      http.get('https://stel.example.com/app/products/1', () =>
+        HttpResponse.json({ message: 'Not found' }, { status: 404 }),
+      ),
+    )
+
+    const client = new StelOrderClient({ baseUrl: 'https://stel.example.com', apiKey: 'secret' })
+
+    await expect(client.getOne('products', 1)).rejects.toMatchObject({
+      name: 'ProviderAPIError',
+      status: 404,
+    })
+  })
+})

package/src/providers/stelorder/client.ts

@@ -0,0 +1,326 @@
+import type { ProviderConfig } from '../../types/provider';
+import { ConfigurationError, ProviderAPIError, extractErrorMessage } from '../../core/errors';
+import { fetchWithRetry, type RetryConfig } from '../../core/fetch-utils';
+import { createLogger, type Logger } from '../../core/logger';
+import { normalizeStelCollection, normalizeStelEntity } from './transforms';
+
+type FetchImplementation = (url: string, init?: RequestInit) => Promise<Response>;
+type HttpMethod = 'DELETE' | 'GET' | 'POST' | 'PUT';
+
+export type StelQueryValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Array<string | number | boolean>;
+
+export type StelQueryParams = Record<string, StelQueryValue>;
+
+export interface StelOrderProviderConfig extends ProviderConfig {
+  baseUrl: string;
+  apiKey?: string;
+  publishableKey?: string;
+  currencyCode?: string;
+  companyName?: string;
+  storefrontId?: string;
+  retry?: RetryConfig;
+}
+
+type RequiredRetryConfig = Required<RetryConfig>;
+
+const DEFAULT_RETRY_CONFIG: RequiredRetryConfig = {
+  maxRetries: 2,
+  initialDelayMs: 300,
+  backoffMultiplier: 2,
+  maxDelayMs: 5000,
+  timeoutMs: 10000,
+  retryableStatusCodes: [408, 429, 500, 502, 503, 504],
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function calculateDelay(attempt: number, retryConfig: RequiredRetryConfig): number {
+  const delay = retryConfig.initialDelayMs * Math.pow(retryConfig.backoffMultiplier, attempt);
+  return Math.min(delay, retryConfig.maxDelayMs);
+}
+
+function isRetryableError(error: unknown, retryConfig: RequiredRetryConfig): boolean {
+  if (error instanceof ProviderAPIError) {
+    return typeof error.status === 'number' && retryConfig.retryableStatusCodes.includes(error.status);
+  }
+
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const message = error.message.toLowerCase();
+  return (
+    error.name === 'AbortError' ||
+    error.name === 'TimeoutError' ||
+    message.includes('fetch failed') ||
+    message.includes('timeout') ||
+    message.includes('econnrefused') ||
+    message.includes('etimedout')
+  );
+}
+
+function createRetryingFetch(
+  fetchImplementation: FetchImplementation,
+  retryConfig: RequiredRetryConfig,
+  logger: Logger,
+): FetchImplementation {
+  return async (url: string, init?: RequestInit): Promise<Response> => {
+    let lastError: unknown = new Error('Unknown STEL Order request error');
+
+    for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt += 1) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), retryConfig.timeoutMs);
+
+      try {
+        const response = await fetchImplementation(url, {
+          ...init,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok && retryConfig.retryableStatusCodes.includes(response.status)) {
+          throw new ProviderAPIError(
+            `STEL Order API error: ${response.status} ${response.statusText}`,
+            'stelorder',
+            response.status,
+          );
+        }
+
+        return response;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        lastError = error;
+
+        if (attempt >= retryConfig.maxRetries || !isRetryableError(error, retryConfig)) {
+          throw error;
+        }
+
+        const delay = calculateDelay(attempt, retryConfig);
+        logger.warn('STEL request failed, retrying.', {
+          url,
+          attempt: attempt + 1,
+          maxAttempts: retryConfig.maxRetries + 1,
+          nextRetryIn: delay,
+          error: extractErrorMessage(error),
+        });
+
+        await sleep(delay);
+      }
+    }
+
+    throw lastError;
+  };
+}
+
+async function parseErrorResponse(response: Response): Promise<string> {
+  const contentType = response.headers.get('content-type') ?? '';
+
+  try {
+    if (contentType.includes('application/json')) {
+      const body = (await response.json()) as unknown;
+      const message = extractErrorMessage(body);
+      if (message && message !== 'An unknown error occurred') {
+        return message;
+      }
+    }
+  } catch {
+    // Ignore body parsing issues and fall back to text/status.
+  }
+
+  try {
+    const text = await response.text();
+    if (text.trim()) {
+      return text.trim();
+    }
+  } catch {
+    // Ignore body parsing issues and fall back to status.
+  }
+
+  return `STEL Order API error: ${response.status} ${response.statusText}`;
+}
+
+export function normalizeStelApiBaseUrl(baseUrl: string): string {
+  const trimmed = baseUrl.trim();
+
+  if (!trimmed) {
+    throw new ConfigurationError('Stel Order baseUrl is required.');
+  }
+
+  const normalized = trimmed
+    .replace(/\/api\/openapi\.json$/i, '')
+    .replace(/\/+$/, '');
+
+  return normalized.endsWith('/app') ? normalized : `${normalized}/app`;
+}
+
+interface StelRequestOptions {
+  method: HttpMethod;
+  path: string;
+  query?: StelQueryParams;
+  body?: unknown;
+  headers?: HeadersInit;
+}
+
+export class StelOrderClient {
+  readonly apiBaseUrl: string;
+
+  private readonly apiKey: string;
+  private readonly logger: Logger;
+  private readonly retryConfig: RequiredRetryConfig;
+  private readonly fetchImplementation?: FetchImplementation;
+
+  constructor(config: StelOrderProviderConfig) {
+    const apiKey = config.apiKey ?? config.publishableKey;
+
+    if (!apiKey) {
+      throw new ConfigurationError(
+        'Stel Order API key is required. Pass `apiKey` or `publishableKey` to createProvider().',
+      );
+    }
+
+    this.apiBaseUrl = normalizeStelApiBaseUrl(config.baseUrl);
+    this.apiKey = apiKey;
+    this.logger = createLogger('StelOrderClient', config.debug);
+    this.retryConfig = {
+      ...DEFAULT_RETRY_CONFIG,
+      ...config.retry,
+    };
+    this.fetchImplementation = config.customFetch
+      ? createRetryingFetch(config.customFetch, this.retryConfig, this.logger)
+      : undefined;
+
+    this.logger.info('Initializing Stel Order client', {
+      apiBaseUrl: this.apiBaseUrl,
+      retryConfig: this.retryConfig,
+    });
+  }
+
+  async list<T>(resource: string, query?: StelQueryParams): Promise<T[]> {
+    const payload = await this.request<T | T[]>({
+      method: 'GET',
+      path: resource,
+      query,
+    });
+
+    return normalizeStelCollection(payload);
+  }
+
+  async getOne<T>(resource: string, id: string | number, query?: StelQueryParams): Promise<T | undefined> {
+    const payload = await this.request<T | T[]>({
+      method: 'GET',
+      path: `${resource}/${id}`,
+      query,
+    });
+
+    return normalizeStelEntity(payload);
+  }
+
+  async create<TResponse, TBody = unknown>(resource: string, body: TBody): Promise<TResponse> {
+    return this.request<TResponse>({
+      method: 'POST',
+      path: resource,
+      body,
+    });
+  }
+
+  async update<TResponse, TBody = unknown>(resource: string, id: string | number, body: TBody): Promise<TResponse> {
+    return this.request<TResponse>({
+      method: 'PUT',
+      path: `${resource}/${id}`,
+      body,
+    });
+  }
+
+  async remove(resource: string, id: string | number): Promise<void> {
+    await this.request<void>({
+      method: 'DELETE',
+      path: `${resource}/${id}`,
+    });
+  }
+
+  private buildUrl(path: string, query?: StelQueryParams): string {
+    const normalizedPath = path.replace(/^\/+/, '');
+    const url = new URL(`${this.apiBaseUrl}/${normalizedPath}`);
+
+    if (!query) {
+      return url.toString();
+    }
+
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null || value === '') {
+        continue;
+      }
+
+      if (Array.isArray(value)) {
+        url.searchParams.set(key, value.map(String).join(','));
+        continue;
+      }
+
+      url.searchParams.set(key, String(value));
+    }
+
+    return url.toString();
+  }
+
+  private buildHeaders(headers?: HeadersInit, hasBody: boolean = false): Headers {
+    const normalizedHeaders = new Headers(headers);
+
+    normalizedHeaders.set('Accept', 'application/json');
+    normalizedHeaders.set('APIKEY', this.apiKey);
+
+    if (hasBody && !normalizedHeaders.has('Content-Type')) {
+      normalizedHeaders.set('Content-Type', 'application/json');
+    }
+
+    return normalizedHeaders;
+  }
+
+  private async executeFetch(url: string, init: RequestInit): Promise<Response> {
+    if (this.fetchImplementation) {
+      return this.fetchImplementation(url, init);
+    }
+
+    return fetchWithRetry(url, init, this.retryConfig);
+  }
+
+  private async request<TResponse>(options: StelRequestOptions): Promise<TResponse> {
+    const url = this.buildUrl(options.path, options.query);
+    const hasBody = options.body !== undefined;
+
+    this.logger.debug('STEL request', {
+      method: options.method,
+      url,
+    });
+
+    const response = await this.executeFetch(url, {
+      method: options.method,
+      headers: this.buildHeaders(options.headers, hasBody),
+      body: hasBody ? JSON.stringify(options.body) : undefined,
+    });
+
+    if (!response.ok) {
+      const message = await parseErrorResponse(response);
+      throw new ProviderAPIError(message, 'stelorder', response.status);
+    }
+
+    if (response.status === 204) {
+      return undefined as TResponse;
+    }
+
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+      return (await response.json()) as TResponse;
+    }
+
+    return (await response.text()) as TResponse;
+  }
+}

package/src/providers/stelorder/index.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { server } from './client.test-helpers'
+import { StelOrderProvider } from './index'
+
+describe('StelOrderProvider', () => {
+  it('returns storefront context and supports read methods', async () => {
+    server.use(
+      http.get('https://stel.example.com/app/products', () =>
+        HttpResponse.json([{ id: 10, name: 'Test Product', 'full-reference': 'TP-10', 'sales-price': 10 }]),
+      ),
+      http.get('https://stel.example.com/app/productCategories', () =>
+        HttpResponse.json([{ id: 2, name: 'Hardware', slug: 'hardware' }]),
+      ),
+    )
+
+    const provider = new StelOrderProvider({
+      baseUrl: 'https://stel.example.com',
+      apiKey: 'secret',
+      companyName: 'Test Co',
+      storefrontId: 'stel-1',
+    })
+
+    const context = await provider.getStorefrontContext()
+    expect(context.platformType).toBe('stelorder')
+    expect(context.name).toBe('Test Co')
+
+    await expect(provider.getProducts()).resolves.toHaveLength(1)
+    await expect(provider.getCategories()).resolves.toHaveLength(1)
+  })
+
+  it('throws clear errors for unsupported workflows', async () => {
+    const provider = new StelOrderProvider({
+      baseUrl: 'https://stel.example.com',
+      apiKey: 'secret',
+    })
+
+    await expect(provider.createCart()).rejects.toMatchObject({
+      name: 'ProviderAPIError',
+      status: 501,
+    })
+
+    await expect(provider.completeCheckout('cart-1')).rejects.toMatchObject({
+      name: 'ProviderAPIError',
+      status: 501,
+    })
+  })
+})