@thorprovider/adapters 4.2.0 → 4.3.0

package/src/providers/stelorder/index.ts

@@ -0,0 +1,685 @@
+import type {
+  BackendCapabilities,
+  Cart,
+  CartLineInput,
+  CartLineUpdate,
+  Collection,
+  CollectionProductsOptions,
+  Country,
+  Customer,
+  FulfillmentOption,
+  GetCategoriesOptions,
+  GetCollectionsOptions,
+  GetCustomersOptions,
+  GetOrdersOptions,
+  GetProductsOptions,
+  InventoryLevel,
+  Order,
+  PaymentMethod,
+  PaymentMethodsOptions,
+  Product,
+  ProductCategory,
+  ShippingMethod,
+  StockLocation,
+  StockValidation,
+  StorefrontContext,
+} from '@thorprovider/types';
+import type { CommerceProvider } from '../../types/provider';
+import { STELORDER_CAPABILITIES } from '../../types/capabilities.types';
+import { ProviderAPIError } from '../../core/errors';
+import { createLogger } from '../../core/logger';
+import { StelOrderClient, type StelOrderProviderConfig } from './client';
+import {
+  buildStelHandle,
+  transformStelCategory,
+  transformStelCategoryToCollection,
+  transformStelClient,
+  transformStelDeliveryOption,
+  transformStelPaymentOption,
+  transformStelProduct,
+  transformStelProductWarehouseToInventoryLevel,
+  transformStelSalesOrder,
+  transformStelWarehouseToStockLocation,
+  type StelClient,
+  type StelDeliveryOption,
+  type StelPaymentOption,
+  type StelProduct,
+  type StelProductCategory,
+  type StelSalesOrder,
+  type StelWarehouse,
+} from './transforms';
+
+export type { StelOrderProviderConfig } from './client';
+export { StelOrderClient } from './client';
+export * from './transforms';
+
+export class StelOrderProvider implements CommerceProvider {
+  readonly name = 'stelorder';
+  readonly version = '1.0.0';
+  readonly capabilities: BackendCapabilities = STELORDER_CAPABILITIES;
+
+  private readonly client: StelOrderClient;
+  private readonly logger: ReturnType<typeof createLogger>;
+  private readonly currencyCode: string;
+  private readonly storefrontId: string;
+  private readonly companyName: string;
+
+  constructor(config: StelOrderProviderConfig) {
+    this.client = new StelOrderClient(config);
+    this.logger = createLogger('StelOrderProvider', config.debug);
+    this.currencyCode = config.currencyCode ?? 'USD';
+    this.storefrontId = config.storefrontId ?? 'stelorder-primary';
+    this.companyName = config.companyName ?? 'Stel Order';
+
+    this.logger.info('Initializing Stel Order provider', {
+      storefrontId: this.storefrontId,
+      companyName: this.companyName,
+      currencyCode: this.currencyCode,
+    });
+  }
+
+  // ============================================
+  // Product Operations
+  // ============================================
+
+  async getProduct(handle: string, _options?: { regionId?: string }): Promise<Product | undefined> {
+    this.logger.debug('getProduct', { handle });
+
+    try {
+      // Attempt direct ID lookup if handle looks numeric
+      if (/^\d+$/.test(handle)) {
+        const raw = await this.client.getOne<StelProduct>('products', handle);
+        return raw ? transformStelProduct(raw, this.currencyCode) : undefined;
+      }
+
+      // Otherwise scan products to match by handle (slugified full-reference)
+      const rawProducts = await this.client.list<StelProduct>('products', { limit: 100 });
+
+      for (const raw of rawProducts) {
+        const productHandle = buildStelHandle(raw['full-reference'], raw.reference, raw.name, raw.id);
+        if (productHandle === handle) {
+          return transformStelProduct(raw, this.currencyCode);
+        }
+      }
+
+      return undefined;
+    } catch (error) {
+      this.logger.error('getProduct failed', { handle, error });
+      throw this.wrapError('getProduct', error);
+    }
+  }
+
+  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
+    this.logger.debug('getProducts', { options });
+
+    try {
+      const query: Record<string, string | number | boolean> = {};
+
+      if (options?.first) {
+        query.limit = options.first;
+      }
+      if (options?.skip) {
+        query.start = options.skip;
+      }
+      if (typeof options?.after === 'number') {
+        query.start = options.after;
+      }
+      if (options?.sortKey) {
+        query.sort = options.reverse ? `-${options.sortKey}` : options.sortKey;
+      }
+      if (options?.categoryIds?.length) {
+        query['product-category-id'] = `in:${options.categoryIds.join(',')}`;
+      }
+
+      const rawProducts = await this.client.list<StelProduct>('products', query);
+
+      let products = rawProducts
+        .filter((p) => !p.deleted && !p.inactive)
+        .map((p) => transformStelProduct(p, this.currencyCode));
+
+      // Client-side text search (STEL has no fulltext search)
+      if (options?.query) {
+        const needle = options.query.toLowerCase();
+        products = products.filter(
+          (p) =>
+            p.title.toLowerCase().includes(needle) ||
+            p.description.toLowerCase().includes(needle) ||
+            p.handle.includes(needle),
+        );
+      }
+
+      return products;
+    } catch (error) {
+      this.logger.error('getProducts failed', { options, error });
+      throw this.wrapError('getProducts', error);
+    }
+  }
+
+  async getProductRecommendations(_productId: string): Promise<Product[]> {
+    // STEL has no recommendation engine — return empty array
+    return [];
+  }
+
+  // ============================================
+  // Category Operations
+  // ============================================
+
+  async getCategory(idOrHandle: string): Promise<ProductCategory | undefined> {
+    this.logger.debug('getCategory', { idOrHandle });
+
+    try {
+      // Direct ID lookup
+      if (/^\d+$/.test(idOrHandle)) {
+        const raw = await this.client.getOne<StelProductCategory>('productCategories', idOrHandle);
+        return raw ? transformStelCategory(raw) : undefined;
+      }
+
+      // Scan by handle
+      const rawCategories = await this.client.list<StelProductCategory>('productCategories');
+
+      for (const raw of rawCategories) {
+        const catHandle = buildStelHandle(raw.slug, raw.name, raw.id);
+        if (catHandle === idOrHandle) {
+          return transformStelCategory(raw);
+        }
+      }
+
+      return undefined;
+    } catch (error) {
+      this.logger.error('getCategory failed', { idOrHandle, error });
+      throw this.wrapError('getCategory', error);
+    }
+  }
+
+  async getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]> {
+    this.logger.debug('getCategories', { options });
+
+    try {
+      if (options?.customFetcher) {
+        return options.customFetcher(options);
+      }
+
+      const query: Record<string, string | number> = {};
+
+      if (options?.limit) {
+        query.limit = options.limit;
+      }
+      if (options?.parentCategoryId) {
+        query['parent-category-id'] = options.parentCategoryId;
+      }
+
+      const rawCategories = await this.client.list<StelProductCategory>('productCategories', query);
+      let categories = rawCategories
+        .filter((c) => !c.deleted)
+        .map(transformStelCategory);
+
+      if (options?.query) {
+        const needle = options.query.toLowerCase();
+        categories = categories.filter(
+          (c) =>
+            c.name.toLowerCase().includes(needle) ||
+            c.handle.includes(needle),
+        );
+      }
+
+      return categories;
+    } catch (error) {
+      this.logger.error('getCategories failed', { options, error });
+      throw this.wrapError('getCategories', error);
+    }
+  }
+
+  async getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    this.logger.debug('getCategoryProducts', { handle, options });
+
+    try {
+      const category = await this.getCategory(handle);
+
+      if (!category) {
+        return [];
+      }
+
+      return this.getProducts({
+        categoryIds: [category.id],
+        first: options?.first,
+        sortKey: options?.sortKey,
+        reverse: options?.reverse,
+        after: options?.after,
+      });
+    } catch (error) {
+      this.logger.error('getCategoryProducts failed', { handle, error });
+      throw this.wrapError('getCategoryProducts', error);
+    }
+  }
+
+  // ============================================
+  // Collection Operations (alias categories)
+  // ============================================
+
+  async getCollection(handle: string): Promise<Collection | undefined> {
+    this.logger.debug('getCollection', { handle });
+
+    try {
+      if (/^\d+$/.test(handle)) {
+        const raw = await this.client.getOne<StelProductCategory>('productCategories', handle);
+        return raw ? transformStelCategoryToCollection(raw) : undefined;
+      }
+
+      const rawCategories = await this.client.list<StelProductCategory>('productCategories');
+
+      for (const raw of rawCategories) {
+        const catHandle = buildStelHandle(raw.slug, raw.name, raw.id);
+        if (catHandle === handle) {
+          return transformStelCategoryToCollection(raw);
+        }
+      }
+
+      return undefined;
+    } catch (error) {
+      this.logger.error('getCollection failed', { handle, error });
+      throw this.wrapError('getCollection', error);
+    }
+  }
+
+  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
+    this.logger.debug('getCollections', { options });
+
+    try {
+      const query: Record<string, string | number> = {};
+
+      if (options?.limit) {
+        query.limit = options.limit;
+      }
+
+      const rawCategories = await this.client.list<StelProductCategory>('productCategories', query);
+      let collections = rawCategories
+        .filter((c) => !c.deleted)
+        .map(transformStelCategoryToCollection);
+
+      if (options?.query) {
+        const needle = options.query.toLowerCase();
+        collections = collections.filter(
+          (c) =>
+            c.title.toLowerCase().includes(needle) ||
+            c.handle.includes(needle),
+        );
+      }
+
+      return collections;
+    } catch (error) {
+      this.logger.error('getCollections failed', { options, error });
+      throw this.wrapError('getCollections', error);
+    }
+  }
+
+  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    return this.getCategoryProducts(handle, options);
+  }
+
+  // ============================================
+  // Inventory Operations
+  // ============================================
+
+  async getStockLocations(_params?: { salesChannelId?: string }): Promise<StockLocation[]> {
+    this.logger.debug('getStockLocations');
+
+    try {
+      const rawWarehouses = await this.client.list<StelWarehouse>('warehouses');
+      return rawWarehouses
+        .filter((w) => !w.deleted)
+        .map(transformStelWarehouseToStockLocation);
+    } catch (error) {
+      this.logger.error('getStockLocations failed', { error });
+      throw this.wrapError('getStockLocations', error);
+    }
+  }
+
+  async checkInventoryLevels(variantId: string, _salesChannelId?: string): Promise<InventoryLevel[]> {
+    this.logger.debug('checkInventoryLevels', { variantId });
+
+    try {
+      // variantId is the product ID (single synthetic variant per product)
+      const raw = await this.client.getOne<StelProduct>('products', variantId);
+
+      if (!raw?.['product-warehouses']?.length) {
+        return [];
+      }
+
+      return raw['product-warehouses'].map(transformStelProductWarehouseToInventoryLevel);
+    } catch (error) {
+      this.logger.error('checkInventoryLevels failed', { variantId, error });
+      throw this.wrapError('checkInventoryLevels', error);
+    }
+  }
+
+  validateCartStock(_cartId: string): Promise<StockValidation> {
+    return this.notSupported('validateCartStock');
+  }
+
+  getFulfillmentOptions(_cartId: string, _salesChannelId: string): Promise<FulfillmentOption[]> {
+    return this.notSupported('getFulfillmentOptions');
+  }
+
+  // ============================================
+  // Cart Operations (unsupported — STEL is ERP, not storefront)
+  // ============================================
+
+  createCart(_options?: { regionId?: string }): Promise<Cart> {
+    return this.notSupported('createCart');
+  }
+
+  getCart(_cartId: string): Promise<Cart | undefined> {
+    return this.notSupported('getCart');
+  }
+
+  addToCart(_cartId: string, _lines: CartLineInput[]): Promise<Cart> {
+    return this.notSupported('addToCart');
+  }
+
+  removeFromCart(_cartId: string, _lineIds: string[]): Promise<Cart> {
+    return this.notSupported('removeFromCart');
+  }
+
+  updateCart(_cartId: string, _lines: CartLineUpdate[]): Promise<Cart> {
+    return this.notSupported('updateCart');
+  }
+
+  // ============================================
+  // Checkout Operations (unsupported)
+  // ============================================
+
+  completeCheckout(_cartId: string): Promise<Order> {
+    return this.notSupported('completeCheckout');
+  }
+
+  getRegionCountries(_regionId: string): Promise<Country[]> {
+    return this.notSupported('getRegionCountries');
+  }
+
+  addShippingMethod(_cartId: string, _methodId: string): Promise<Cart> {
+    return this.notSupported('addShippingMethod');
+  }
+
+  initiatePaymentSession(_cartId: string, _providerId: string): Promise<void> {
+    return this.notSupported('initiatePaymentSession');
+  }
+
+  applyDiscountCode(_cartId: string, _code: string): Promise<Cart> {
+    return this.notSupported('applyDiscountCode');
+  }
+
+  removeDiscountCode(_cartId: string, _code: string): Promise<Cart> {
+    return this.notSupported('removeDiscountCode');
+  }
+
+  // ============================================
+  // Payment Methods
+  // ============================================
+
+  async getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
+    this.logger.debug('getPaymentMethods');
+
+    try {
+      const rawOptions = await this.client.list<StelPaymentOption>('paymentOptions');
+      return rawOptions
+        .filter((o) => !o.deleted)
+        .map(transformStelPaymentOption);
+    } catch (error) {
+      this.logger.error('getPaymentMethods failed', { error });
+      throw this.wrapError('getPaymentMethods', error);
+    }
+  }
+
+  // ============================================
+  // Shipping / Delivery Methods
+  // ============================================
+
+  async getShippingMethods(_cartId: string): Promise<ShippingMethod[]> {
+    this.logger.debug('getShippingMethods (delivery options listing)');
+
+    try {
+      const rawOptions = await this.client.list<StelDeliveryOption>('deliveryOptions');
+      return rawOptions
+        .filter((o) => !o.deleted)
+        .map((o) => transformStelDeliveryOption(o, this.currencyCode));
+    } catch (error) {
+      this.logger.error('getShippingMethods failed', { error });
+      throw this.wrapError('getShippingMethods', error);
+    }
+  }
+
+  // ============================================
+  // Customer Operations (optional)
+  // ============================================
+
+  async getCustomer(customerId: string): Promise<Customer | undefined> {
+    this.logger.debug('getCustomer', { customerId });
+
+    try {
+      const raw = await this.client.getOne<StelClient>('clients', customerId);
+      return raw ? transformStelClient(raw) : undefined;
+    } catch (error) {
+      this.logger.error('getCustomer failed', { customerId, error });
+      throw this.wrapError('getCustomer', error);
+    }
+  }
+
+  async getCustomers(options?: GetCustomersOptions): Promise<Customer[]> {
+    this.logger.debug('getCustomers', { options });
+
+    try {
+      if (options?.customFetcher) {
+        return options.customFetcher(options);
+      }
+
+      const query: Record<string, string | number> = {};
+
+      if (options?.limit) {
+        query.limit = options.limit;
+      }
+      if (options?.offset) {
+        query.start = options.offset;
+      }
+
+      const rawClients = await this.client.list<StelClient>('clients', query);
+      let customers = rawClients
+        .filter((c) => !c.deleted)
+        .map(transformStelClient);
+
+      // Client-side search (STEL has no fulltext search for clients)
+      if (options?.search) {
+        const needle = options.search.toLowerCase();
+        customers = customers.filter(
+          (c) =>
+            c.email.toLowerCase().includes(needle) ||
+            (c.firstName ?? '').toLowerCase().includes(needle) ||
+            (c.lastName ?? '').toLowerCase().includes(needle),
+        );
+      }
+
+      return customers;
+    } catch (error) {
+      this.logger.error('getCustomers failed', { options, error });
+      throw this.wrapError('getCustomers', error);
+    }
+  }
+
+  async updateCustomer(
+    customerId: string,
+    data: Partial<Omit<Customer, 'id' | 'createdAt'>>,
+  ): Promise<Customer> {
+    this.logger.debug('updateCustomer', { customerId, data });
+
+    try {
+      const stelPayload: Record<string, unknown> = {};
+
+      if (data.firstName || data.lastName) {
+        stelPayload.name = [data.firstName, data.lastName].filter(Boolean).join(' ');
+      }
+      if (data.email) {
+        stelPayload.email = data.email;
+      }
+      if (data.phone) {
+        stelPayload.phone = data.phone;
+      }
+
+      const raw = await this.client.update<StelClient>('clients', customerId, stelPayload);
+      return transformStelClient(raw);
+    } catch (error) {
+      this.logger.error('updateCustomer failed', { customerId, error });
+      throw this.wrapError('updateCustomer', error);
+    }
+  }
+
+  // ============================================
+  // Order Operations (optional)
+  // ============================================
+
+  async getOrder(orderId: string): Promise<Order | undefined> {
+    this.logger.debug('getOrder', { orderId });
+
+    try {
+      const raw = await this.client.getOne<StelSalesOrder>('salesOrders', orderId);
+      return raw ? transformStelSalesOrder(raw, this.currencyCode) : undefined;
+    } catch (error) {
+      this.logger.error('getOrder failed', { orderId, error });
+      throw this.wrapError('getOrder', error);
+    }
+  }
+
+  async getOrders(options: GetOrdersOptions): Promise<Order[]> {
+    this.logger.debug('getOrders', { options });
+
+    try {
+      if (options?.customFetcher) {
+        return options.customFetcher(options);
+      }
+
+      const query: Record<string, string | number> = {};
+
+      if (options?.limit) {
+        query.limit = options.limit;
+      }
+      if (options?.offset) {
+        query.start = options.offset;
+      }
+      if (options?.customerId) {
+        query['client-id'] = options.customerId;
+      }
+
+      const rawOrders = await this.client.list<StelSalesOrder>('salesOrders', query);
+      return rawOrders
+        .filter((o) => !o.deleted)
+        .map((o) => transformStelSalesOrder(o, this.currencyCode));
+    } catch (error) {
+      this.logger.error('getOrders failed', { options, error });
+      throw this.wrapError('getOrders', error);
+    }
+  }
+
+  async getAdminOrders(options?: {
+    search?: string;
+    status?: string | string[];
+    limit?: number;
+    offset?: number;
+  }): Promise<{ orders: Order[]; count: number }> {
+    this.logger.debug('getAdminOrders', { options });
+
+    try {
+      const query: Record<string, string | number> = {};
+
+      if (options?.limit) {
+        query.limit = options.limit;
+      }
+      if (options?.offset) {
+        query.start = options.offset;
+      }
+
+      const rawOrders = await this.client.list<StelSalesOrder>('salesOrders', query);
+      let orders = rawOrders
+        .filter((o) => !o.deleted)
+        .map((o) => transformStelSalesOrder(o, this.currencyCode));
+
+      if (options?.search) {
+        const needle = options.search.toLowerCase();
+        orders = orders.filter(
+          (o) =>
+            o.orderNumber.toLowerCase().includes(needle) ||
+            o.email.toLowerCase().includes(needle),
+        );
+      }
+
+      if (options?.status) {
+        const statuses = Array.isArray(options.status) ? options.status : [options.status];
+        orders = orders.filter((o) => statuses.includes(o.status));
+      }
+
+      return { orders, count: orders.length };
+    } catch (error) {
+      this.logger.error('getAdminOrders failed', { options, error });
+      throw this.wrapError('getAdminOrders', error);
+    }
+  }
+
+  cancelOrder(_orderId: string): Promise<Order> {
+    return this.notSupported('cancelOrder');
+  }
+
+  createFulfillment(_orderId: string, _items?: Array<{ id: string; quantity: number }>): Promise<void> {
+    return this.notSupported('createFulfillment');
+  }
+
+  createRefund(_orderId: string, _amount?: number, _reason?: string): Promise<void> {
+    return this.notSupported('createRefund');
+  }
+
+  // ============================================
+  // Storefront Context
+  // ============================================
+
+  async getStorefrontContext(): Promise<StorefrontContext> {
+    return {
+      id: this.storefrontId,
+      name: this.companyName,
+      platformType: 'stelorder',
+      requiresProductScoping: false,
+      currencyCode: this.currencyCode,
+      metadata: {
+        apiBaseUrl: this.client.apiBaseUrl,
+        singleCompany: true,
+        providerVersion: this.version,
+      },
+    };
+  }
+
+  isStorefrontRequired(): boolean {
+    return false;
+  }
+
+  // ============================================
+  // Internal helpers
+  // ============================================
+
+  private notSupported<T>(operation: string): Promise<T> {
+    return Promise.reject(
+      new ProviderAPIError(
+        `Stel Order does not support \`${operation}\`. STEL is an ERP adapter without cart/checkout/auth capabilities.`,
+        'stelorder',
+        501,
+      ),
+    );
+  }
+
+  private wrapError(operation: string, error: unknown): Error {
+    if (error instanceof ProviderAPIError) {
+      return error;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    return new ProviderAPIError(
+      `Stel Order \`${operation}\` failed: ${message}`,
+      'stelorder',
+      500,
+    );
+  }
+}