@thorprovider/adapters 4.2.0 → 4.2.1

package/src/providers/stelorder/transforms.ts

@@ -0,0 +1,631 @@
+import type {
+  Collection,
+  Customer,
+  Address,
+  FulfillmentStatus,
+  Image,
+  InventoryLevel,
+  Money,
+  Order,
+  OrderItem,
+  OrderStatus,
+  PaymentMethod,
+  PaymentMethodType,
+  PaymentStatus,
+  Product,
+  ProductCategory,
+  ProductVariant,
+  ShippingMethod,
+  StockLocation,
+} from '@thorprovider/types';
+
+export interface StelResource {
+  id?: number;
+  path?: string;
+  deleted?: boolean;
+  'utc-last-modification-date'?: string;
+}
+
+export interface StelItemImage {
+  'item-image-path'?: string;
+  order?: number;
+}
+
+export interface StelItemRate {
+  'rate-id'?: number;
+  'rate-path'?: string;
+  price?: number;
+}
+
+export interface StelProductWarehouse {
+  'warehouse-id'?: number;
+  'warehouse-path'?: string;
+  'minimum-stock'?: number;
+  'real-stock'?: number;
+  'virtual-stock'?: number;
+  location?: string;
+}
+
+export interface StelProduct extends StelResource {
+  name?: string;
+  description?: string;
+  reference?: string;
+  'full-reference'?: string;
+  barcode?: string;
+  'sales-price'?: number;
+  'purchase-price'?: number;
+  'product-category-id'?: number;
+  'product-category-path'?: string;
+  'real-stock'?: number;
+  'virtual-stock'?: number;
+  'minimum-stock'?: number;
+  'stock-enabled'?: boolean;
+  inactive?: boolean;
+  promotional?: boolean;
+  'creation-date'?: string;
+  'item-images'?: StelItemImage[];
+  'item-rates'?: StelItemRate[];
+  'product-warehouses'?: StelProductWarehouse[];
+}
+
+export interface StelProductCategory extends StelResource {
+  name?: string;
+  description?: string;
+  slug?: string;
+  'parent-category-id'?: number;
+}
+
+export interface StelClient extends StelResource {
+  name?: string;
+  'business-name'?: string;
+  email?: string;
+  phone?: string;
+  mobile?: string;
+  'rate-id'?: number;
+  'payment-option-id'?: number;
+  'payment-term-id'?: number;
+  'delivery-option-id'?: number;
+  'main-address'?: StelAddress;
+}
+
+export interface StelAddress extends StelResource {
+  name?: string;
+  'first-name'?: string;
+  'last-name'?: string;
+  company?: string;
+  'address-data'?: string;
+  'postal-code'?: string;
+  'city-town'?: string;
+  province?: string;
+  'country-code'?: string;
+  phone?: string;
+  email?: string;
+}
+
+export interface StelDocumentLine {
+  'item-id'?: number;
+  'item-name'?: string;
+  'item-description'?: string;
+  'item-base-price'?: number;
+  'primary-tax-percentage'?: number;
+  'discount-percentage'?: number;
+  units?: number;
+  'line-type'?: 'ITEM' | 'DOCUMENT' | 'SECTION' | 'COMPONENT';
+}
+
+export interface StelSalesOrder extends StelResource {
+  reference?: string;
+  status?: string;
+  email?: string;
+  'client-id'?: number;
+  'payment-option-id'?: number;
+  'payment-term-id'?: number;
+  'delivery-option-id'?: number;
+  'creation-date'?: string;
+  'total-base'?: number;
+  'total-tax'?: number;
+  total?: number;
+  'document-lines'?: StelDocumentLine[];
+}
+
+export interface StelPaymentOption extends StelResource {
+  name?: string;
+  description?: string;
+}
+
+export interface StelPaymentTerm extends StelResource {
+  name?: string;
+  description?: string;
+}
+
+export interface StelDeliveryOption extends StelResource {
+  name?: string;
+  description?: string;
+}
+
+export interface StelWarehouse extends StelResource {
+  name?: string;
+  description?: string;
+}
+
+export function normalizeStelCollection<T>(payload: T | T[] | null | undefined): T[] {
+  if (!payload) {
+    return [];
+  }
+
+  return Array.isArray(payload) ? payload : [payload];
+}
+
+export function normalizeStelEntity<T>(payload: T | T[] | null | undefined): T | undefined {
+  if (!payload) {
+    return undefined;
+  }
+
+  return Array.isArray(payload) ? payload[0] : payload;
+}
+
+export function transformStelMoney(
+  amount: number | string | null | undefined,
+  currencyCode: string = 'USD',
+): Money {
+  const normalizedAmount = typeof amount === 'string' ? Number.parseFloat(amount) : amount ?? 0;
+
+  return {
+    amount: Number.isFinite(normalizedAmount) ? normalizedAmount.toFixed(2) : '0.00',
+    currencyCode: currencyCode.toUpperCase(),
+  };
+}
+
+export function transformStelImage(url: string | null | undefined, altText: string = ''): Image | undefined {
+  const normalizedUrl = url?.trim();
+
+  if (!normalizedUrl) {
+    return undefined;
+  }
+
+  return {
+    url: normalizedUrl,
+    altText,
+    width: 800,
+    height: 800,
+  };
+}
+
+export function normalizeStelDate(value: string | null | undefined): string {
+  if (!value) {
+    return new Date().toISOString();
+  }
+
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? new Date().toISOString() : parsed.toISOString();
+}
+
+export function extractStelIdFromPath(path: string | null | undefined): string | undefined {
+  if (!path) {
+    return undefined;
+  }
+
+  const match = path.match(/\/([^/]+)$/);
+  return match?.[1];
+}
+
+export function toStelStringId(value: string | number | null | undefined): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  return String(value);
+}
+
+function slugify(value: string): string {
+  return value
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function buildStelHandle(...candidates: Array<string | number | null | undefined>): string {
+  for (const candidate of candidates) {
+    if (candidate === null || candidate === undefined) {
+      continue;
+    }
+
+    const normalized = slugify(String(candidate).trim());
+    if (normalized) {
+      return normalized;
+    }
+  }
+
+  return 'stel-item';
+}
+
+// ---------------------------------------------------------------------------
+// Product transforms
+// ---------------------------------------------------------------------------
+
+function transformStelProductImages(product: StelProduct): Image[] {
+  const images: Image[] = [];
+
+  if (!product['item-images']) {
+    return images;
+  }
+
+  const sorted = [...product['item-images']].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+
+  for (const img of sorted) {
+    const transformed = transformStelImage(img['item-image-path'], product.name ?? '');
+    if (transformed) {
+      images.push(transformed);
+    }
+  }
+
+  return images;
+}
+
+function deriveStelStockStatus(product: StelProduct): 'in_stock' | 'out_of_stock' | 'low_stock' {
+  if (!product['stock-enabled']) {
+    return 'in_stock';
+  }
+
+  const realStock = product['real-stock'] ?? 0;
+  const minimumStock = product['minimum-stock'] ?? 0;
+
+  if (realStock <= 0) {
+    return 'out_of_stock';
+  }
+
+  if (realStock <= minimumStock) {
+    return 'low_stock';
+  }
+
+  return 'in_stock';
+}
+
+/**
+ * Build a single synthetic variant from a STEL product.
+ * STEL products have no variant concept — every product is a single SKU.
+ */
+function buildSyntheticVariant(product: StelProduct, currencyCode: string): ProductVariant {
+  const price = transformStelMoney(product['sales-price'], currencyCode);
+  const stockStatus = deriveStelStockStatus(product);
+  const quantityAvailable = product['stock-enabled'] ? (product['real-stock'] ?? 0) : undefined;
+  const image = product['item-images']?.[0]
+    ? transformStelImage(product['item-images'][0]['item-image-path'], product.name ?? '')
+    : undefined;
+
+  return {
+    id: toStelStringId(product.id),
+    title: 'Default',
+    sku: product.barcode ?? product['full-reference'] ?? undefined,
+    availableForSale: stockStatus !== 'out_of_stock',
+    selectedOptions: [],
+    price,
+    compareAtPrice: undefined,
+    quantityAvailable,
+    stockStatus,
+    image,
+  };
+}
+
+export function transformStelProduct(raw: StelProduct, currencyCode: string): Product {
+  const id = toStelStringId(raw.id);
+  const handle = buildStelHandle(raw['full-reference'], raw.reference, raw.name, raw.id);
+  const price = transformStelMoney(raw['sales-price'], currencyCode);
+  const images = transformStelProductImages(raw);
+  const variant = buildSyntheticVariant(raw, currencyCode);
+  const now = new Date().toISOString();
+
+  return {
+    id,
+    handle,
+    title: raw.name ?? '',
+    description: raw.description ?? '',
+    availableForSale: variant.availableForSale,
+    options: [],
+    variants: [variant],
+    featuredImage: images[0],
+    images,
+    priceRange: {
+      minVariantPrice: price,
+      maxVariantPrice: price,
+    },
+    productType: undefined,
+    vendor: undefined,
+    tags: raw.promotional ? ['promotional'] : [],
+    createdAt: normalizeStelDate(raw['creation-date']),
+    updatedAt: normalizeStelDate(raw['utc-last-modification-date']) || now,
+    metadata: {
+      stelFullReference: raw['full-reference'],
+      stelReference: raw.reference,
+      stelBarcode: raw.barcode,
+      stelCategoryId: raw['product-category-id'],
+      stelInactive: raw.inactive,
+      stelPromotional: raw.promotional,
+      stelPurchasePrice: raw['purchase-price'],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Category transforms
+// ---------------------------------------------------------------------------
+
+export function transformStelCategory(raw: StelProductCategory): ProductCategory {
+  const id = toStelStringId(raw.id);
+  const handle = buildStelHandle(raw.slug, raw.name, raw.id);
+
+  return {
+    id,
+    name: raw.name ?? '',
+    handle,
+    description: raw.description ?? undefined,
+    parentCategoryId: raw['parent-category-id']
+      ? toStelStringId(raw['parent-category-id'])
+      : undefined,
+    metadata: {
+      stelSlug: raw.slug,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Collection transforms (alias categories as collections)
+// ---------------------------------------------------------------------------
+
+export function transformStelCategoryToCollection(raw: StelProductCategory): Collection {
+  const id = toStelStringId(raw.id);
+  const handle = buildStelHandle(raw.slug, raw.name, raw.id);
+
+  return {
+    id,
+    handle,
+    title: raw.name ?? '',
+    description: raw.description ?? '',
+    path: `/collections/${handle}`,
+    updatedAt: normalizeStelDate(raw['utc-last-modification-date']),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Inventory / warehouse transforms
+// ---------------------------------------------------------------------------
+
+export function transformStelWarehouseToStockLocation(raw: StelWarehouse): StockLocation {
+  return {
+    id: toStelStringId(raw.id),
+    name: raw.name ?? 'Warehouse',
+  };
+}
+
+export function transformStelProductWarehouseToInventoryLevel(
+  pw: StelProductWarehouse,
+): InventoryLevel {
+  return {
+    locationId: toStelStringId(pw['warehouse-id']),
+    locationName: pw['warehouse-path'] ?? `Warehouse ${pw['warehouse-id'] ?? 'unknown'}`,
+    availableQuantity: pw['real-stock'] ?? 0,
+    reservedQuantity: Math.max(0, (pw['virtual-stock'] ?? 0) - (pw['real-stock'] ?? 0)),
+    stockedQuantity: pw['virtual-stock'] ?? pw['real-stock'] ?? 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Customer / Address transforms
+// ---------------------------------------------------------------------------
+
+function splitStelName(fullName: string | null | undefined): { firstName: string; lastName: string } {
+  if (!fullName?.trim()) {
+    return { firstName: '', lastName: '' };
+  }
+
+  const parts = fullName.trim().split(/\s+/);
+  const firstName = parts[0] ?? '';
+  const lastName = parts.length > 1 ? parts.slice(1).join(' ') : '';
+  return { firstName, lastName };
+}
+
+export function transformStelAddress(raw: StelAddress): Address {
+  const firstName = raw['first-name'] ?? '';
+  const lastName = raw['last-name'] ?? '';
+
+  // If first/last not present, attempt to split the 'name' field
+  const nameParts = !firstName && !lastName ? splitStelName(raw.name) : { firstName, lastName };
+
+  return {
+    id: raw.id ? toStelStringId(raw.id) : undefined,
+    firstName: nameParts.firstName,
+    lastName: nameParts.lastName,
+    company: raw.company ?? undefined,
+    address1: raw['address-data'] ?? '',
+    city: raw['city-town'] ?? '',
+    province: raw.province ?? undefined,
+    postalCode: raw['postal-code'] ?? '',
+    countryCode: raw['country-code'] ?? '',
+    phone: raw.phone ?? undefined,
+    isDefault: true,
+    metadata: {
+      stelEmail: raw.email,
+    },
+  };
+}
+
+export function transformStelClient(raw: StelClient): Customer {
+  const { firstName, lastName } = splitStelName(raw.name ?? raw['business-name']);
+
+  return {
+    id: toStelStringId(raw.id),
+    email: raw.email ?? '',
+    firstName: firstName || null,
+    lastName: lastName || null,
+    phone: raw.phone ?? raw.mobile ?? null,
+    hasAccount: true,
+    createdAt: normalizeStelDate(raw['utc-last-modification-date']),
+    updatedAt: normalizeStelDate(raw['utc-last-modification-date']),
+    metadata: {
+      stelBusinessName: raw['business-name'],
+      stelRateId: raw['rate-id'],
+      stelPaymentOptionId: raw['payment-option-id'],
+      stelPaymentTermId: raw['payment-term-id'],
+      stelDeliveryOptionId: raw['delivery-option-id'],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Order transforms
+// ---------------------------------------------------------------------------
+
+function deriveStelOrderStatus(raw: StelSalesOrder): OrderStatus {
+  if (raw.deleted) {
+    return 'cancelled';
+  }
+
+  const status = (raw.status ?? '').toLowerCase();
+
+  if (status.includes('cancel') || status.includes('anulad')) {
+    return 'cancelled';
+  }
+  if (status.includes('complet') || status.includes('cerrad') || status.includes('settled')) {
+    return 'completed';
+  }
+  if (status.includes('process') || status.includes('confirm')) {
+    return 'processing';
+  }
+
+  return 'pending';
+}
+
+function deriveStelPaymentStatus(raw: StelSalesOrder): PaymentStatus {
+  const orderStatus = deriveStelOrderStatus(raw);
+
+  if (orderStatus === 'completed') {
+    return 'paid';
+  }
+  if (orderStatus === 'cancelled') {
+    return 'pending';
+  }
+
+  return 'pending';
+}
+
+function deriveStelFulfillmentStatus(raw: StelSalesOrder): FulfillmentStatus {
+  const orderStatus = deriveStelOrderStatus(raw);
+
+  if (orderStatus === 'completed') {
+    return 'fulfilled';
+  }
+
+  return 'unfulfilled';
+}
+
+function transformStelDocumentLine(
+  line: StelDocumentLine,
+  index: number,
+  currencyCode: string,
+): OrderItem {
+  const unitPrice = line['item-base-price'] ?? 0;
+  const quantity = line.units ?? 1;
+  const lineTotal = unitPrice * quantity;
+
+  return {
+    id: toStelStringId(line['item-id'] ?? index),
+    title: line['item-name'] ?? '',
+    variantTitle: undefined,
+    quantity,
+    price: transformStelMoney(unitPrice, currencyCode),
+    total: transformStelMoney(lineTotal, currencyCode),
+    sku: undefined,
+    productId: line['item-id'] ? toStelStringId(line['item-id']) : undefined,
+  };
+}
+
+export function transformStelSalesOrder(raw: StelSalesOrder, currencyCode: string): Order {
+  const id = toStelStringId(raw.id);
+  const now = new Date().toISOString();
+  const items = (raw['document-lines'] ?? [])
+    .filter((line) => line['line-type'] === 'ITEM' || !line['line-type'])
+    .map((line, i) => transformStelDocumentLine(line, i, currencyCode));
+
+  const status = deriveStelOrderStatus(raw);
+
+  return {
+    id,
+    orderNumber: raw.reference ?? id,
+    email: raw.email ?? '',
+    status,
+    paymentStatus: deriveStelPaymentStatus(raw),
+    fulfillmentStatus: deriveStelFulfillmentStatus(raw),
+    customerId: raw['client-id'] ? toStelStringId(raw['client-id']) : undefined,
+    items,
+    subtotal: transformStelMoney(raw['total-base'], currencyCode),
+    total: transformStelMoney(raw.total, currencyCode),
+    tax: raw['total-tax'] != null ? transformStelMoney(raw['total-tax'], currencyCode) : undefined,
+    createdAt: normalizeStelDate(raw['creation-date']),
+    updatedAt: normalizeStelDate(raw['utc-last-modification-date']) || now,
+    cancelledAt: status === 'cancelled' ? normalizeStelDate(raw['utc-last-modification-date']) : undefined,
+    completedAt: status === 'completed' ? normalizeStelDate(raw['utc-last-modification-date']) : undefined,
+    metadata: {
+      stelReference: raw.reference,
+      stelStatus: raw.status,
+      stelPaymentOptionId: raw['payment-option-id'],
+      stelPaymentTermId: raw['payment-term-id'],
+      stelDeliveryOptionId: raw['delivery-option-id'],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Payment / delivery transforms
+// ---------------------------------------------------------------------------
+
+function inferPaymentMethodType(name: string | null | undefined): PaymentMethodType {
+  if (!name) {
+    return 'other';
+  }
+
+  const lower = name.toLowerCase();
+
+  if (lower.includes('transfer') || lower.includes('bank') || lower.includes('sepa') || lower.includes('iban')) {
+    return 'bank_transfer';
+  }
+  if (lower.includes('card') || lower.includes('tarjeta') || lower.includes('visa') || lower.includes('master')) {
+    return 'card';
+  }
+  if (lower.includes('paypal') || lower.includes('wallet') || lower.includes('apple') || lower.includes('google')) {
+    return 'wallet';
+  }
+  if (lower.includes('cash') || lower.includes('contrar') || lower.includes('efectivo') || lower.includes('cod')) {
+    return 'cash_on_delivery';
+  }
+  if (lower.includes('crypto') || lower.includes('bitcoin')) {
+    return 'crypto';
+  }
+
+  return 'other';
+}
+
+export function transformStelPaymentOption(raw: StelPaymentOption): PaymentMethod {
+  return {
+    id: toStelStringId(raw.id),
+    name: raw.name ?? 'Payment Option',
+    type: inferPaymentMethodType(raw.name),
+    isEnabled: !raw.deleted,
+    requiresSetup: false,
+    description: raw.description ?? undefined,
+    metadata: {
+      stelPath: raw.path,
+      source: 'paymentOption',
+    },
+  };
+}
+
+export function transformStelDeliveryOption(raw: StelDeliveryOption, currencyCode: string): ShippingMethod {
+  return {
+    id: toStelStringId(raw.id),
+    name: raw.name ?? 'Delivery Option',
+    price: transformStelMoney(0, currencyCode),
+    description: raw.description ?? undefined,
+  };
+}

package/src/types/capabilities.types.ts

@@ -99,6 +99,57 @@ export const MEDUSA_CAPABILITIES: Readonly<BackendCapabilities> = {
   loyaltyProgram: false,  // Requires custom implementation
 };
 
+/**
+ * Stel Order backend capabilities
+ *
+ * ERP/document API with catalog, CRM, inventory visibility, and sales documents,
+ * but without cart, checkout, customer auth, or storefront-native payment flows.
+ */
+export const STELORDER_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // Profile Management
+  updateProfile: false,
+  updateEmail: false,
+  changePasswordDirect: false,
+  changePasswordViaEmail: false,
+  deleteAccount: false,
+
+  // Avatar
+  uploadAvatar: false,
+  avatarViaMetadata: false,
+
+  // Custom Attributes
+  customAttributes: false,
+
+  // Orders
+  fetchOrders: true,
+  cancelOrder: false,
+
+  // Addresses
+  manageAddresses: true,
+  defaultAddress: false,
+
+  // Cart/Checkout
+  applyDiscounts: false,
+  shippingCalculation: false,
+  guestCheckout: false,
+  savedPaymentMethods: false,
+  listPaymentProviders: true,
+  regionSpecificPayments: false,
+
+  // Wishlist
+  wishlist: false,
+
+  // Search
+  advancedSearch: false,
+  facetedFilters: false,
+
+  // Reviews
+  productReviews: false,
+
+  // Loyalty
+  loyaltyProgram: false,
+};
+
 /**
  * Shopify backend capabilities
  * 

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: true,
+    setupFiles: ['./vitest.setup.ts'],
+    include: ['src/**/*.test.ts'],
+    restoreMocks: true,
+    clearMocks: true,
+    mockReset: true,
+  },
+})

package/vitest.setup.ts

@@ -0,0 +1,6 @@
+import { afterAll, afterEach, beforeAll } from 'vitest'
+import { server } from './src/providers/stelorder/client.test-helpers'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())