@thorprovider/adapters 4.2.0 → 4.2.2

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