@thorprovider/adapters 3.0.2

package/src/providers/medusa/transforms.ts

@@ -0,0 +1,625 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Medusa Provider - Transform functions
+ * 
+ * These functions convert Medusa-specific types to our unified types
+ */
+
+// Note: We use 'any' for Medusa types because the SDK returns different types
+// than what's in @medusajs/types (StoreProduct vs ProductDTO)
+
+import type {
+  Product,
+  ProductVariant,
+  ProductOption,
+  Cart,
+  CartItem,
+  Collection,
+  ProductCategory,
+  Money,
+  Image,
+  StockLocation,
+  InventoryLevel,
+  FulfillmentOption,
+  Order,
+  OrderItem,
+  OrderStatus,
+  PaymentStatus,
+  FulfillmentStatus,
+  Address,
+  Customer,
+  StorefrontConfig,
+} from '@thorprovider/types';
+
+/**
+ * Transform Medusa Money to unified Money
+ *
+ * Medusa v2 stores and returns monetary amounts in MAJOR units (dollars, euros, etc.).
+ * Reference: https://docs.medusajs.com/resources/commerce-modules/pricing/concepts
+ * "The Price data model has an `amount` property...It's stored as an integer in major units.
+ *  For example, $20.00 is stored as 20, and $20.5 is stored as 20.5."
+ *
+ * Money.amount in @thorprovider/types is a decimal string in major units (e.g., "45.00").
+ * No division by 100 is needed — the value comes through as-is.
+ */
+function transformMoney(amount: number | null | undefined, currencyCode: string = 'USD'): Money {
+  return {
+    amount: (amount ?? 0).toFixed(2), // Medusa v2 sends major units (dollars/euros), not cents
+    currencyCode: currencyCode.toUpperCase(),
+  };
+}
+
+/**
+ * Transform Medusa image to unified Image
+ */
+function transformImage(url: string, alt: string = ''): Image {
+  return {
+    url,
+    altText: alt,
+    width: 800,
+    height: 800,
+  };
+}
+
+// ============================================
+// Inventory & Fulfillment Transforms
+// ============================================
+
+export function transformStockLocation(raw: any): StockLocation {
+  return {
+    id: raw.id,
+    name: raw.name,
+    address: raw.address
+      ? {
+          address1: raw.address.address_1,
+          address2: raw.address.address_2,
+          city: raw.address.city,
+          countryCode: raw.address.country_code,
+          postalCode: raw.address.postal_code,
+          province: raw.address.province,
+        }
+      : undefined,
+    metadata: raw.metadata,
+  };
+}
+
+export function transformInventoryLevel(raw: any, locationName: string): InventoryLevel {
+  return {
+    locationId: raw.location_id,
+    locationName,
+    availableQuantity: raw.available_quantity ?? 0,
+    reservedQuantity: raw.reserved_quantity ?? 0,
+    incomingQuantity: raw.incoming_quantity,
+    stockedQuantity: raw.stocked_quantity ?? 0,
+  };
+}
+
+export function transformFulfillmentOption(
+  shippingOption: any,
+  location: StockLocation,
+  currencyCode: string,
+): FulfillmentOption {
+  return {
+    id: shippingOption.id,
+    providerId: shippingOption.provider_id,
+    name: shippingOption.name,
+    description: shippingOption.description,
+    price: transformMoney(shippingOption.amount, currencyCode),
+    estimatedDays: shippingOption.metadata?.estimated_days,
+    stockLocation: location,
+  };
+}
+
+/**
+ * Transform Medusa ProductOption to unified ProductOption
+ */
+export function transformProductOption(option: any): ProductOption {
+  return {
+    id: option.id!,
+    name: option.title ?? '',
+    values: option.values?.map((v: any) => v.value ?? '') ?? [],
+  };
+}
+
+/**
+ * Transform Medusa ProductVariant to unified ProductVariant
+ */
+export function transformProductVariant(
+  variant: any,
+  currencyCode: string = 'USD'
+): ProductVariant {
+  let priceAmount: number | null | undefined;
+  let priceCurrency: string = currencyCode;
+  
+  // Priority 1: Use calculated_price if available (from region-based pricing)
+  if (variant.calculated_price) {
+    priceAmount = variant.calculated_price.calculated_amount;
+    priceCurrency = variant.calculated_price.currency_code || currencyCode;
+  } 
+  // Priority 2: Fallback to prices array
+  else if (variant.prices && variant.prices.length > 0) {
+    const price = variant.prices.find((p: any) => p.currency_code === currencyCode.toLowerCase());
+    priceAmount = price?.amount;
+    priceCurrency = price?.currency_code || currencyCode;
+  }
+  
+  // Determine if variant is available for sale
+  // Following Medusa docs: https://docs.medusajs.com/resources/storefront-development/products/inventory
+  // A variant is in stock if:
+  // 1. manage_inventory is false (inventory not tracked) - always in stock
+  // 2. inventory_quantity > 0 (has stock)
+  // 3. allow_backorder is true (can order even without stock)
+  const isAvailable = variant.manage_inventory === false
+    ? true
+    : (variant.inventory_quantity ?? 0) > 0 || variant.allow_backorder === true;
+  
+  return {
+    id: variant.id!,
+    title: variant.title ?? 'Default',
+    sku: variant.sku ?? undefined,
+    availableForSale: isAvailable,
+    selectedOptions: variant.options?.map((opt: any) => ({
+      name: (opt as any).option?.title ?? '',
+      value: opt.value ?? '',
+    })) ?? [],
+    price: transformMoney(priceAmount, priceCurrency),
+    compareAtPrice: undefined,  // Medusa doesn't have compare-at pricing
+    quantityAvailable: variant.manage_inventory ? variant.inventory_quantity : undefined,
+    image: variant.thumbnail
+      ? transformImage(variant.thumbnail, variant.title ?? '')
+      : undefined,
+  };
+}
+
+/**
+ * Transform Medusa Product to unified Product
+ */
+export function transformProduct(
+  product: any,
+  currencyCode: string = 'USD'
+): Product {
+  const variants = product.variants?.map((v: any) => transformProductVariant(v, currencyCode)) ?? [];
+  
+  // Calculate price range
+  const prices = variants.map((v: any) => parseFloat(v.price.amount));
+  const minPrice = Math.min(...prices);
+  const maxPrice = Math.max(...prices);
+  
+  return {
+    id: product.id!,
+    handle: product.handle ?? '',
+    title: product.title ?? '',
+    description: product.description ?? '',
+    descriptionHtml: product.description ?? '',
+    // Medusa v2 /store/products API doesn't return 'status' field (it's null)
+    // Products returned by Store API are already published, so we check if any variant is available
+    availableForSale: variants.length > 0 && variants.some((v: ProductVariant) => v.availableForSale),
+    
+    options: product.options?.map(transformProductOption) ?? [],
+    variants,
+    
+    featuredImage: product.thumbnail
+      ? transformImage(product.thumbnail, product.title ?? '')
+      : undefined,
+    
+    images: product.images?.map((img: any) => transformImage(img.url ?? '', product.title ?? '')) ?? [],
+    
+    priceRange: {
+      // Build Money directly from already-resolved major-unit prices.
+      // Do NOT pass through transformMoney (which would call toFixed on already-correct values)
+      // and do NOT multiply by 100 (that was a compensatory hack for the old /100 bug).
+      minVariantPrice: { amount: (Number.isFinite(minPrice) ? minPrice : 0).toFixed(2), currencyCode: currencyCode.toUpperCase() },
+      maxVariantPrice: { amount: (Number.isFinite(maxPrice) ? maxPrice : 0).toFixed(2), currencyCode: currencyCode.toUpperCase() },
+    },
+    
+    collections: product.collection ? [{
+      id: product.collection.id,
+      title: product.collection.title ?? '',
+      handle: product.collection.handle ?? '',
+    }] : undefined,
+    
+    productType: product.type?.value ?? undefined,
+    vendor: undefined,  // Medusa doesn't have vendor field
+    tags: product.tags?.map((t: any) => t.value ?? '') ?? [],
+    
+    seo: {
+      title: product.title ?? '',
+      description: product.description ?? '',
+    },
+    
+    createdAt: typeof product.created_at === 'string' 
+      ? product.created_at 
+      : product.created_at?.toISOString() ?? new Date().toISOString(),
+    updatedAt: typeof product.updated_at === 'string' 
+      ? product.updated_at 
+      : product.updated_at?.toISOString() ?? new Date().toISOString(),
+    
+    metadata: product.metadata ?? undefined,
+  };
+}
+
+/**
+ * Transform Medusa LineItem to unified CartItem
+ */
+function resolveMedusaCartItemCurrencyCode(item: any, cartCurrencyCode?: string): string {
+  return (
+    item?.cart?.currency_code ??
+    cartCurrencyCode ??
+    'usd'
+  );
+}
+
+/**
+ * Resolve the total amount for a Medusa cart item.
+ * All amounts from Medusa v2 are in major units (dollars, euros).
+ */
+function resolveMedusaCartItemTotal(item: any): number {
+  const quantity = item?.quantity ?? 1;
+  const safeQuantity = typeof quantity === 'number' && quantity > 0 ? quantity : 1;
+
+  const totalCandidates = [
+    item?.total,
+    item?.item_total,
+    item?.original_total,
+    item?.subtotal,
+    item?.item_subtotal,
+    item?.original_subtotal,
+  ];
+
+  for (const candidate of totalCandidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0) {
+      return candidate;
+    }
+  }
+
+  const unitCandidates = [
+    item?.unit_price,
+    item?.original_unit_price,
+  ];
+
+  for (const candidate of unitCandidates) {
+    if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0) {
+      return candidate * safeQuantity;
+    }
+  }
+
+  return 0;
+}
+
+export function transformCartItem(item: any, cartCurrencyCode?: string): CartItem {
+  const variant = item.variant;
+  const product = variant?.product;
+  const currencyCode = resolveMedusaCartItemCurrencyCode(item, cartCurrencyCode);
+  const totalCents = resolveMedusaCartItemTotal(item);
+  
+  return {
+    id: item.id,
+    quantity: item.quantity ?? 1,
+    cost: {
+      totalAmount: transformMoney(totalCents, currencyCode),
+    },
+    merchandise: {
+      id: variant?.id ?? '',
+      title: variant?.title ?? '',
+      selectedOptions: variant?.options?.map((opt: any) => ({
+        name: (opt as any).option?.title ?? '',
+        value: opt.value ?? '',
+      })) ?? [],
+      product: {
+        id: product?.id ?? '',
+        handle: product?.handle ?? '',
+        title: product?.title ?? '',
+        featuredImage: product?.thumbnail
+          ? transformImage(product.thumbnail, product.title ?? '')
+          : transformImage('', ''),
+      },
+    },
+  };
+}
+
+/**
+ * Transform Medusa Cart to unified Cart
+ */
+export function transformCart(cart: any): Cart {
+  const currencyCode = cart.currency_code ?? 'usd';
+  
+  return {
+    id: cart.id,
+    checkoutUrl: `/checkout/${cart.id}`, // Medusa doesn't have a direct checkout URL
+    cost: {
+      subtotalAmount: transformMoney(cart.subtotal, currencyCode),
+      totalAmount: transformMoney(cart.total, currencyCode),
+      totalTaxAmount: transformMoney(cart.tax_total, currencyCode),
+    },
+    lines: cart.items?.map((item: any) => transformCartItem(item, currencyCode)) ?? [],
+    totalQuantity: cart.items?.reduce((sum: any, item: any) => sum + (item.quantity ?? 0), 0) ?? 0,
+    completedAt: cart.completed_at
+      ? (typeof cart.completed_at === 'string'
+        ? cart.completed_at
+        : cart.completed_at?.toISOString())
+      : undefined,
+  };
+}
+
+/**
+ * Transform Medusa Collection to unified Collection
+ */
+export function transformCollection(collection: any): Collection {
+  return {
+    id: collection.id!,
+    handle: collection.handle!,
+    title: collection.title ?? '',
+    description: collection.metadata?.description as string ?? '',
+    seo: {
+      title: collection.title ?? '',
+      description: collection.metadata?.description as string ?? '',
+    },
+    path: `/collections/${collection.handle}`,
+    updatedAt: typeof collection.updated_at === 'string'
+      ? collection.updated_at
+      : collection.updated_at?.toISOString() ?? new Date().toISOString(),
+  };
+}
+
+/**
+ * Transform Medusa ProductCategory to unified ProductCategory
+ */
+export function transformCategory(category: any): ProductCategory {
+  return {
+    id: category.id,
+    name: category.name ?? '',
+    handle: category.handle ?? '',
+    description: category.description ?? undefined,
+    parentCategoryId: category.parent_category_id ?? undefined,
+    productCount: category.product_count ?? undefined,
+    image: category.metadata?.image as string ?? undefined,
+    metadata: category.metadata ?? undefined,
+  };
+}
+
+/**
+ * Transform Medusa order status to unified OrderStatus
+ */
+function transformOrderStatus(status: string): OrderStatus {
+  // Medusa order statuses: pending, completed, archived, canceled, requires_action, draft
+  switch (status) {
+    case 'pending':
+    case 'requires_action':
+    case 'draft':
+      return 'pending';
+    case 'completed':
+      return 'completed';
+    case 'canceled':
+      return 'cancelled';
+    case 'archived':
+      // Archived could be completed or refunded, default to completed
+      return 'completed';
+    default:
+      return 'processing';
+  }
+}
+
+/**
+ * Transform Medusa payment status to unified PaymentStatus
+ */
+function transformPaymentStatus(status: string | undefined): PaymentStatus {
+  // Medusa payment statuses: not_paid, awaiting, captured, partially_refunded, refunded, canceled, requires_action
+  if (!status || status === 'not_paid' || status === 'requires_action') {
+    return 'pending';
+  }
+  
+  if (status === 'awaiting') {
+    return 'authorized';
+  }
+  
+  if (status === 'captured') {
+    return 'paid';
+  }
+  
+  if (status === 'partially_refunded') {
+    return 'partially_refunded';
+  }
+  
+  if (status === 'refunded') {
+    return 'refunded';
+  }
+  
+  return 'pending';
+}
+
+/**
+ * Transform Medusa fulfillment status to unified FulfillmentStatus
+ */
+function transformFulfillmentStatus(status: string | undefined): FulfillmentStatus {
+  // Medusa fulfillment statuses: not_fulfilled, partially_fulfilled, fulfilled, 
+  // partially_shipped, shipped, partially_returned, returned, canceled, requires_action
+  if (!status || status === 'not_fulfilled' || status === 'canceled') {
+    return 'unfulfilled';
+  }
+  
+  if (status === 'partially_fulfilled' || status === 'partially_shipped') {
+    return 'partially_fulfilled';
+  }
+  
+  if (status === 'fulfilled' || status === 'shipped') {
+    return 'fulfilled';
+  }
+  
+  if (status === 'returned' || status === 'partially_returned') {
+    return 'returned';
+  }
+  
+  return 'unfulfilled';
+}
+
+/**
+ * Transform Medusa LineItem to unified OrderItem
+ */
+export function transformOrderItem(item: any, currencyCode: string): OrderItem {
+  // Defensive checks for null/undefined item or variant
+  if (!item) {
+    throw new Error('Invalid order item: item is null or undefined');
+  }
+  
+  const variant = item.variant ?? null;
+  const product = variant?.product;
+  
+  return {
+    id: item.id,
+    title: item.product_title ?? item.title ?? '',
+    variantTitle: item.variant_title ?? variant?.title ?? undefined,
+    quantity: item.quantity ?? 1,
+    price: transformMoney(item.unit_price, currencyCode),
+    total: transformMoney(item.total, currencyCode),
+    sku: variant?.sku ?? undefined,
+    image: product?.thumbnail || item.thumbnail
+      ? transformImage(product?.thumbnail || item.thumbnail, item.product_title ?? '')
+      : undefined,
+    productId: item.product_id ?? product?.id ?? undefined,
+    variantId: item.variant_id ?? variant?.id ?? undefined,
+  };
+}
+
+/**
+ * Transform Medusa Address (snake_case) to unified Address (camelCase)
+ */
+export function transformAddress(address: any): Address {
+  return {
+    id: address.id ?? undefined,
+    firstName: address.first_name ?? '',
+    lastName: address.last_name ?? '',
+    company: address.company ?? undefined,
+    address1: address.address_1 ?? '',
+    address2: address.address_2 ?? undefined,
+    city: address.city ?? '',
+    province: address.province ?? '',
+    postalCode: address.postal_code ?? '',
+    countryCode: address.country_code ?? '',
+    phone: address.phone ?? undefined,
+    isDefault: address.is_default ?? address.is_default_shipping ?? undefined,
+  };
+}
+
+/**
+ * Transform Medusa Customer (snake_case) to unified Customer (camelCase)
+ */
+export function transformCustomer(customer: any, email?: string): Customer {
+  return {
+    id: customer.id,
+    email: customer.email ?? email ?? '',
+    firstName: customer.first_name ?? '',
+    lastName: customer.last_name ?? '',
+    phone: customer.phone ?? undefined,
+    hasAccount: customer.has_account ?? false,
+    createdAt: typeof customer.created_at === 'string'
+      ? customer.created_at
+      : customer.created_at?.toISOString() ?? undefined,
+    updatedAt: typeof customer.updated_at === 'string'
+      ? customer.updated_at
+      : customer.updated_at?.toISOString() ?? undefined,
+    metadata: customer.metadata ?? undefined,
+  };
+}
+
+/**
+ * Transform Medusa Order to unified Order
+ */
+export function transformOrder(order: any): Order {
+  const currencyCode = order.currency_code ?? 'usd';
+  
+  return {
+    id: order.id,
+    orderNumber: order.display_id?.toString() ?? order.id,
+    email: order.email ?? '',
+    
+    // Status (3 separate statuses)
+    status: transformOrderStatus(order.status),
+    paymentStatus: transformPaymentStatus(order.payment_status),
+    fulfillmentStatus: transformFulfillmentStatus(order.fulfillment_status),
+    
+    // Customer
+    customerId: order.customer_id ?? undefined,
+    customer: order.customer
+      ? transformCustomer(order.customer, order.email)
+      : undefined,
+    
+    // Items
+    items: (order.items ?? [])
+      .filter((item: any) => item != null) // Filter out null/undefined items
+      .map((item: any) => transformOrderItem(item, currencyCode)) ?? [],
+    
+    // Pricing
+    subtotal: transformMoney(order.subtotal, currencyCode),
+    total: transformMoney(order.total, currencyCode),
+    tax: transformMoney(order.tax_total, currencyCode),
+    shipping: transformMoney(order.shipping_total, currencyCode),
+    discount: transformMoney(order.discount_total, currencyCode),
+    
+    // Addresses (transformed to camelCase)
+    shippingAddress: order.shipping_address
+      ? transformAddress(order.shipping_address)
+      : undefined,
+    billingAddress: order.billing_address
+      ? transformAddress(order.billing_address)
+      : undefined,
+    
+    // Dates
+    createdAt: typeof order.created_at === 'string'
+      ? order.created_at
+      : order.created_at?.toISOString() ?? new Date().toISOString(),
+    updatedAt: typeof order.updated_at === 'string'
+      ? order.updated_at
+      : order.updated_at?.toISOString() ?? new Date().toISOString(),
+    completedAt: order.completed_at
+      ? (typeof order.completed_at === 'string'
+        ? order.completed_at
+        : order.completed_at?.toISOString())
+      : undefined,
+    cancelledAt: order.canceled_at
+      ? (typeof order.canceled_at === 'string'
+        ? order.canceled_at
+        : order.canceled_at?.toISOString())
+      : undefined,
+    
+    // Platform-specific metadata
+    metadata: order.metadata ?? undefined,
+  };
+}
+
+// ============================================
+// Storefront Configuration Transforms
+// ============================================
+
+/**
+ * Transform backend `storefront_config` (snake_case) to `StorefrontConfig` (camelCase).
+ *
+ * Backend response shape:
+ * ```json
+ * {
+ *   "id": "sfc_01J...",
+ *   "sales_channel_id": "sc_01J...",
+ *   "theme_accent_color": "indigo",
+ *   "logo_url": "https://...",
+ *   "currency_code": "EUR",
+ *   "seo_defaults": { "title": "...", "description": "...", "ogImage": "..." },
+ *   "created_at": "...",
+ *   "updated_at": "..."
+ * }
+ * ```
+ */
+export function transformStorefrontConfig(raw: any): StorefrontConfig {
+  return {
+    id: raw.id ?? '',
+    salesChannelId: raw.sales_channel_id ?? '',
+    themeAccentColor: raw.theme_accent_color ?? '',
+    logoUrl: raw.logo_url ?? '',
+    currencyCode: raw.currency_code ?? 'USD',
+    seoDefaults: {
+      title: raw.seo_defaults?.title ?? '',
+      description: raw.seo_defaults?.description ?? '',
+      ogImage: raw.seo_defaults?.ogImage ?? raw.seo_defaults?.og_image,
+    },
+    createdAt: raw.created_at ?? '',
+    updatedAt: raw.updated_at ?? '',
+  };
+}