@thorprovider/adapters 4.2.0 → 4.3.0

package/src/providers/medusa/index.ts

@@ -49,6 +49,7 @@ import { validatePaymentId } from '../../utils/payment-utils';
 import { transformProduct, transformCart, transformCollection, transformCategory, transformOrder, transformCustomer, transformStockLocation, transformInventoryLevel, transformAddress, transformStorefrontConfig } from './transforms';
 import { MedusaAuthProvider } from './auth';
 import { getPaymentMethods } from './payment';
+import { MedusaAdminClient } from './admin';
 import {
   buildChannelScopeMetadata,
   filterByChannel,
@@ -163,6 +164,19 @@ export class MedusaProvider implements CommerceProvider {
    * Only created when adminConfig.apiKey is provided.
    */
   private sdkAdmin?: Medusa;
+
+  /**
+   * Admin client for Thor multi-tenant endpoints (`/admin/thor/`).
+   * Available when `adminConfig.apiKey` is provided.
+   *
+   * @example
+   * ```typescript
+   * const { customers } = await commerce.admin.getChannelCustomers('sc_01JXXXXX');
+   * const { api_keys } = await commerce.admin.getChannelApiKeys('sc_01JXXXXX');
+   * await commerce.admin.updateStorefrontConfig('sc_01JXXXXX', { theme_accent_color: '#EF4444', ... });
+   * ```
+   */
+  public readonly admin?: MedusaAdminClient;
   /** Cached distinct product status values — rarely changes, cached for process lifetime */
   private _cachedProductStatuses: string[] | null = null;
 
@@ -253,12 +267,18 @@ export class MedusaProvider implements CommerceProvider {
         debug: config.debug ?? false,
         // No publishableKey or auth config: this instance is admin-only, no JWT needed
       });
+      // Admin client for Thor multi-tenant custom endpoints (/admin/thor/)
+      (this as any).admin = new MedusaAdminClient({
+        baseUrl: config.baseUrl,
+        apiKey: config.adminConfig.apiKey,
+        debug: config.debug,
+      });
       this.logger.info('[Admin Auth] Dedicated admin SDK instance created with API key');
     }
 
     // Initialize auth provider if config is provided
     if (config.auth) {
-      this.auth = new MedusaAuthProvider(this.sdk, config.auth, config.debug);
+      this.auth = new MedusaAuthProvider(this.sdk, config.auth, config.debug, config.baseUrl, config.publishableKey);
       this.logger.info('Auth provider initialized');
     }
 

package/src/providers/shopify/auth.ts

@@ -399,4 +399,10 @@ export class ShopifyAuthProvider implements AuthProvider {
   async deleteCustomerAccount(): Promise<void> {
     throw new ProviderAPIError('Shopify customer self-service deletion requires Admin API and is not supported.', 'shopify', 501);
   }
+
+  async linkCustomerToChannel(): Promise<{ linked: boolean; reason?: string }> {
+    // Shopify does not have the concept of Thor sales channels.
+    // Return a no-op response so multi-tenant flows don't break when running against Shopify.
+    return { linked: false, reason: 'not_applicable' };
+  }
 }

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,
+    })
+  })
+})