@thorprovider/adapters 4.3.0 → 5.0.0

package/src/providers/spree/index.ts

@@ -1,344 +0,0 @@
-/**
- * @thorprovider/adapters — Spree Commerce Provider
- * Implements CommerceProvider for Spree Commerce Storefront API v2
- *
- * Spree uses JSON:API format. Supports guest token + bearer token auth.
- * API base: /api/v2/storefront/
- */
-
-import type {
-  Product,
-  GetProductsOptions,
-  Cart,
-  CartLineInput,
-  CartLineUpdate,
-  Collection,
-  CollectionProductsOptions,
-  GetCollectionsOptions,
-  ProductCategory,
-  GetCategoriesOptions,
-  Order,
-  GetOrdersOptions,
-  Customer,
-  Address,
-  PaymentMethod,
-  PaymentMethodsOptions,
-  ShippingMethod,
-  StockLocation,
-  InventoryLevel,
-  StockValidation,
-  FulfillmentOption,
-  StorefrontContext,
-  BackendCapabilities,
-} from '@thorprovider/types';
-import type { CommerceProvider, ProviderConfig } from '../../types/provider';
-import { SPREE_CAPABILITIES } from '../../types/capabilities.types';
-import { createLogger } from '../../core/logger';
-import { ProviderAPIError } from '../../core/errors';
-import { transformProduct, transformCart, transformCollection, transformOrder } from './transforms';
-
-/**
- * Spree provider configuration
- */
-export interface SpreeProviderConfig extends ProviderConfig {
-  /** Spree store base URL (e.g., 'https://myspreestore.com') */
-  baseUrl: string;
-  /** Bearer token for authenticated operations (customer or OAuth) */
-  bearerToken?: string;
-  /** Default currency code (default: 'USD') */
-  currencyCode?: string;
-}
-
-export class SpreeProvider implements CommerceProvider {
-  readonly name = 'spree';
-  readonly version = '1.0.0';
-  readonly capabilities: BackendCapabilities = SPREE_CAPABILITIES;
-
-  private logger: ReturnType<typeof createLogger>;
-  private baseUrl: string;
-  private apiBase: string;
-  private currencyCode: string;
-  private bearerToken?: string;
-  private orderToken?: string; // guest cart token
-
-  constructor(config: SpreeProviderConfig) {
-    this.logger = createLogger('SpreeProvider', config.debug);
-    this.baseUrl = config.baseUrl.replace(/\/$/, '');
-    this.apiBase = `${this.baseUrl}/api/v2/storefront`;
-    this.currencyCode = config.currencyCode ?? 'USD';
-    this.bearerToken = config.bearerToken;
-
-    this.logger.info('Initializing Spree Provider', { baseUrl: this.baseUrl });
-  }
-
-  private async apiFetch<T = any>(path: string, init?: RequestInit): Promise<{ data: T; included?: any[] }> {
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/vnd.api+json',
-      'Accept': 'application/vnd.api+json',
-      ...((init?.headers as Record<string, string>) ?? {}),
-    };
-
-    if (this.bearerToken) {
-      headers['Authorization'] = `Bearer ${this.bearerToken}`;
-    }
-    if (this.orderToken) {
-      headers['X-Spree-Order-Token'] = this.orderToken;
-    }
-
-    const response = await fetch(`${this.apiBase}${path}`, {
-      ...init,
-      headers,
-    });
-
-    if (!response.ok) {
-      throw new ProviderAPIError(
-        `Spree API error: ${response.status}`,
-        'SPREE_API_ERROR',
-        response.status,
-      );
-    }
-
-    return response.json() as Promise<{ data: T; included?: any[] }>;
-  }
-
-  // ============================================
-  // Product Operations
-  // ============================================
-
-  async getProduct(handle: string): Promise<Product | undefined> {
-    try {
-      const { data, included } = await this.apiFetch<any>(
-        `/products/${encodeURIComponent(handle)}?include=images,variants,option_types`,
-      );
-      return transformProduct(data, included ?? [], this.currencyCode);
-    } catch {
-      return undefined;
-    }
-  }
-
-  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
-    let path = `/products?include=images,variants&per_page=${options?.first ?? 20}`;
-    if (options?.query) path += `&filter[name]=${encodeURIComponent(options.query)}`;
-    if (options?.sortKey) {
-      const sortMap: Record<string, string> = {
-        'price-asc': 'price',
-        'price-desc': '-price',
-        'title-asc': 'name',
-        'title-desc': '-name',
-        'created-desc': '-created_at',
-      };
-      if (sortMap[options.sortKey]) path += `&sort=${sortMap[options.sortKey]}`;
-    }
-
-    const { data, included } = await this.apiFetch<any[]>(path);
-    return (Array.isArray(data) ? data : []).map((p) => transformProduct(p, included ?? [], this.currencyCode));
-  }
-
-  async getProductRecommendations(_productId: string): Promise<Product[]> {
-    return [];
-  }
-
-  // ============================================
-  // Collection/Taxon Operations
-  // ============================================
-
-  async getCollection(handle: string): Promise<Collection | undefined> {
-    try {
-      const { data } = await this.apiFetch<any>(`/taxons/${encodeURIComponent(handle)}`);
-      return transformCollection(data);
-    } catch {
-      return undefined;
-    }
-  }
-
-  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
-    const { data } = await this.apiFetch<any[]>(`/taxons?per_page=${options?.limit ?? 50}`);
-    return (Array.isArray(data) ? data : []).map(transformCollection);
-  }
-
-  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
-    const { data, included } = await this.apiFetch<any[]>(
-      `/products?include=images,variants&filter[taxons]=${encodeURIComponent(handle)}&per_page=${options?.first ?? 20}`,
-    );
-    return (Array.isArray(data) ? data : []).map((p) => transformProduct(p, included ?? [], this.currencyCode));
-  }
-
-  async getCategory(handle: string): Promise<ProductCategory | undefined> {
-    return this.getCollection(handle) as any;
-  }
-
-  async getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]> {
-    return this.getCollections(options) as any;
-  }
-
-  async getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
-    return this.getCollectionProducts(handle, options);
-  }
-
-  // ============================================
-  // Cart Operations
-  // ============================================
-
-  async createCart(): Promise<Cart> {
-    const { data } = await this.apiFetch<any>('/cart', {
-      method: 'POST',
-      body: JSON.stringify({}),
-    });
-
-    // Store order token for guest operations
-    if (data.attributes?.token) {
-      this.orderToken = data.attributes.token;
-    }
-
-    return transformCart(data, this.currencyCode);
-  }
-
-  async getCart(_cartId: string): Promise<Cart | undefined> {
-    try {
-      const { data } = await this.apiFetch<any>('/cart?include=line_items');
-      return transformCart(data, this.currencyCode);
-    } catch {
-      return undefined;
-    }
-  }
-
-  async addToCart(_cartId: string, lines: CartLineInput[]): Promise<Cart> {
-    for (const line of lines) {
-      await this.apiFetch('/cart/add_item', {
-        method: 'POST',
-        body: JSON.stringify({ variant_id: line.merchandiseId, quantity: line.quantity }),
-      });
-    }
-    const { data } = await this.apiFetch<any>('/cart?include=line_items');
-    return transformCart(data, this.currencyCode);
-  }
-
-  async removeFromCart(_cartId: string, lineIds: string[]): Promise<Cart> {
-    for (const id of lineIds) {
-      await this.apiFetch(`/cart/remove_line_item/${id}`, { method: 'DELETE' });
-    }
-    const { data } = await this.apiFetch<any>('/cart?include=line_items');
-    return transformCart(data, this.currencyCode);
-  }
-
-  async updateCart(_cartId: string, lines: CartLineUpdate[]): Promise<Cart> {
-    for (const line of lines) {
-      await this.apiFetch(`/cart/set_quantity`, {
-        method: 'PATCH',
-        body: JSON.stringify({ line_item_id: line.id, quantity: line.quantity }),
-      });
-    }
-    const { data } = await this.apiFetch<any>('/cart?include=line_items');
-    return transformCart(data, this.currencyCode);
-  }
-
-  // ============================================
-  // Checkout Operations
-  // ============================================
-
-  async completeCheckout(_cartId: string): Promise<Order> {
-    const { data } = await this.apiFetch<any>('/checkout/complete', { method: 'PATCH' });
-    return transformOrder(data, this.currencyCode);
-  }
-
-  async getShippingMethods(_cartId: string): Promise<ShippingMethod[]> {
-    try {
-      const { data } = await this.apiFetch<any[]>('/checkout/shipping_rates');
-      return (Array.isArray(data) ? data : []).map((rate: any) => ({
-        id: String(rate.id),
-        name: rate.attributes?.name ?? rate.name ?? '',
-        price: { amount: String(parseFloat(rate.attributes?.final_price ?? rate.attributes?.cost ?? '0').toFixed(2)), currencyCode: this.currencyCode },
-      }));
-    } catch {
-      return [];
-    }
-  }
-
-  async getRegionCountries(): Promise<import('@thorprovider/types').Country[]> {
-    return [];
-  }
-
-  async addShippingMethod(_cartId: string, methodId: string): Promise<Cart> {
-    await this.apiFetch('/checkout', {
-      method: 'PATCH',
-      body: JSON.stringify({ order: { shipments_attributes: [{ selected_shipping_rate_id: methodId }] } }),
-    });
-    const { data } = await this.apiFetch<any>('/cart?include=line_items');
-    return transformCart(data, this.currencyCode);
-  }
-
-  async initiatePaymentSession(_cartId: string, _providerId: string): Promise<void> {
-    // Spree handles payments via checkout advance
-  }
-
-  async applyDiscountCode(_cartId: string, code: string): Promise<Cart> {
-    await this.apiFetch('/cart/apply_coupon_code', {
-      method: 'PATCH',
-      body: JSON.stringify({ coupon_code: code }),
-    });
-    const { data } = await this.apiFetch<any>('/cart?include=line_items');
-    return transformCart(data, this.currencyCode);
-  }
-
-  async removeDiscountCode(_cartId: string, code: string): Promise<Cart> {
-    await this.apiFetch(`/cart/remove_coupon_code/${encodeURIComponent(code)}`, { method: 'DELETE' });
-    const { data } = await this.apiFetch<any>('/cart?include=line_items');
-    return transformCart(data, this.currencyCode);
-  }
-
-  // ============================================
-  // Customer, Order, Payment, Inventory, Admin
-  // ============================================
-
-  async getOrders(_options: GetOrdersOptions): Promise<Order[]> {
-    try {
-      const { data } = await this.apiFetch<any[]>('/account/orders');
-      return (Array.isArray(data) ? data : []).map((o) => transformOrder(o, this.currencyCode));
-    } catch {
-      return [];
-    }
-  }
-
-  async getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
-    try {
-      const { data } = await this.apiFetch<any[]>('/checkout/payment_methods');
-      return (Array.isArray(data) ? data : []).map((pm: any) => ({
-        id: String(pm.id),
-        name: pm.attributes?.name ?? '',
-        type: 'other' as const,
-        isEnabled: true,
-        requiresSetup: false,
-      }));
-    } catch {
-      return [];
-    }
-  }
-
-  async getStockLocations(): Promise<StockLocation[]> { return []; }
-  async checkInventoryLevels(): Promise<InventoryLevel[]> { return []; }
-  async validateCartStock(): Promise<StockValidation> { return { allAvailable: true, unavailableItems: [] }; }
-  async getFulfillmentOptions(): Promise<FulfillmentOption[]> { return []; }
-
-  async cancelOrder(_orderId: string): Promise<Order> {
-    throw new ProviderAPIError('Order cancellation requires Spree Admin API.', 'SPREE_ADMIN_REQUIRED');
-  }
-  async createFulfillment(_orderId: string): Promise<void> {
-    throw new ProviderAPIError('Fulfillment requires Spree Admin API.', 'SPREE_ADMIN_REQUIRED');
-  }
-  async createRefund(_orderId: string): Promise<void> {
-    throw new ProviderAPIError('Refunds require Spree Admin API.', 'SPREE_ADMIN_REQUIRED');
-  }
-  async getAdminOrders(): Promise<{ orders: Order[]; count: number }> { return { orders: [], count: 0 }; }
-
-  async getStorefrontContext(): Promise<StorefrontContext> {
-    return {
-      id: this.baseUrl,
-      name: `Spree ${this.baseUrl}`,
-      platformType: 'spree',
-      requiresProductScoping: true,
-      currencyCode: this.currencyCode,
-    };
-  }
-
-  isStorefrontRequired(): boolean { return true; }
-}

package/src/providers/spree/spree.ts

@@ -1,5 +0,0 @@
-/**
- * Spree Commerce Provider — barrel exports
- */
-export { SpreeProvider } from './index';
-export type { SpreeProviderConfig } from './index';

package/src/providers/spree/transforms.ts

@@ -1,254 +0,0 @@
-/**
- * Spree Commerce Transform Functions
- * Converts Spree JSON:API responses to @thorprovider/types
- *
- * Spree uses JSON:API format with `data` arrays containing `id`, `type`, `attributes`, `relationships`.
- * Prices are stored as strings (e.g., "19.99").
- */
-
-import type { Product, ProductVariant, ProductOption, Image, Collection, Cart, CartItem, Order, OrderItem, Customer, Address, Money } from '@thorprovider/types';
-
-// ============================================
-// Money / Price Helpers
-// ============================================
-
-function toMoney(amount: string | number, currencyCode: string): Money {
-  const num = typeof amount === 'string' ? parseFloat(amount) || 0 : amount;
-  return { amount: num.toFixed(2), currencyCode };
-}
-
-// ============================================
-// Product Transforms
-// ============================================
-
-export function transformProduct(data: any, included: any[] = [], currencyCode: string = 'USD'): Product {
-  const attrs = data.attributes ?? data;
-  const id = String(data.id ?? '');
-
-  // Resolve images from relationships or included
-  const images: Image[] = [];
-  const imageRels = data.relationships?.images?.data ?? [];
-  for (const imgRef of imageRels) {
-    const imgIncluded = included.find((i: any) => i.type === 'image' && String(i.id) === String(imgRef.id));
-    if (imgIncluded) {
-      images.push({
-        url: imgIncluded.attributes?.original_url ?? imgIncluded.attributes?.styles?.[0]?.url ?? '',
-        altText: imgIncluded.attributes?.alt ?? attrs.name ?? '',
-        width: undefined,
-        height: undefined,
-      });
-    }
-  }
-
-  // If no resolved images, try attributes.images directly
-  if (images.length === 0 && Array.isArray(attrs.images)) {
-    for (const img of attrs.images) {
-      images.push({
-        url: img.original_url ?? img.url ?? '',
-        altText: img.alt ?? attrs.name ?? '',
-        width: undefined,
-        height: undefined,
-      });
-    }
-  }
-
-  // Resolve variants from relationships or included
-  const variants: ProductVariant[] = [];
-  const variantRels = data.relationships?.variants?.data ?? [];
-  for (const varRef of variantRels) {
-    const varIncluded = included.find((i: any) => i.type === 'variant' && String(i.id) === String(varRef.id));
-    if (varIncluded) {
-      const vAttrs = varIncluded.attributes ?? {};
-      variants.push({
-        id: String(varIncluded.id),
-        title: vAttrs.name ?? vAttrs.sku ?? `Variant ${varIncluded.id}`,
-        availableForSale: vAttrs.in_stock !== false && vAttrs.purchasable !== false,
-        price: toMoney(vAttrs.price ?? vAttrs.display_price ?? '0', currencyCode),
-        compareAtPrice: vAttrs.compare_at_price ? toMoney(vAttrs.compare_at_price, currencyCode) : undefined,
-        selectedOptions: (vAttrs.option_values ?? []).map((ov: any) => ({
-          name: ov.option_type_name ?? 'Option',
-          value: ov.name ?? ov.presentation ?? '',
-        })),
-      });
-    }
-  }
-
-  // Fallback to default variant if no relationships
-  if (variants.length === 0) {
-    variants.push({
-      id: attrs.default_variant_id ? String(attrs.default_variant_id) : id,
-      title: 'Default',
-      availableForSale: attrs.in_stock !== false && attrs.purchasable !== false,
-      price: toMoney(attrs.price ?? attrs.display_price ?? '0', currencyCode),
-      compareAtPrice: attrs.compare_at_price ? toMoney(attrs.compare_at_price, currencyCode) : undefined,
-      selectedOptions: [],
-    });
-  }
-
-  // Options from option_types
-  const options: ProductOption[] = (attrs.option_types ?? []).map((ot: any) => ({
-    id: String(ot.id ?? ot.name ?? ''),
-    name: ot.presentation ?? ot.name ?? '',
-    values: (ot.option_values ?? []).map((ov: any) => ov.presentation ?? ov.name ?? ''),
-  }));
-
-  return {
-    id,
-    handle: attrs.slug ?? id,
-    title: attrs.name ?? '',
-    description: attrs.description ?? '',
-    descriptionHtml: attrs.description ?? '',
-    availableForSale: attrs.in_stock !== false && attrs.purchasable !== false,
-    priceRange: {
-      minVariantPrice: variants.reduce(
-        (min, v) => (v.price.amount < min.amount ? v.price : min),
-        variants[0]?.price ?? toMoney('0', currencyCode),
-      ),
-      maxVariantPrice: variants.reduce(
-        (max, v) => (v.price.amount > max.amount ? v.price : max),
-        variants[0]?.price ?? toMoney('0', currencyCode),
-      ),
-    },
-    variants,
-    options,
-    images,
-    featuredImage: images[0] ?? { url: '', altText: attrs.name ?? '' },
-    tags: [],
-    seo: {
-      title: attrs.meta_title ?? attrs.name ?? '',
-      description: attrs.meta_description ?? '',
-    },
-    updatedAt: attrs.updated_at ?? new Date().toISOString(),
-    createdAt: attrs.created_at ?? new Date().toISOString(),
-  };
-}
-
-// ============================================
-// Collection Transforms (Spree Taxonomies/Taxons)
-// ============================================
-
-export function transformCollection(data: any): Collection {
-  const attrs = data.attributes ?? data;
-  return {
-    id: String(data.id ?? ''),
-    handle: attrs.permalink ?? attrs.slug ?? String(data.id ?? ''),
-    title: attrs.name ?? '',
-    description: attrs.description ?? '',
-    seo: {
-      title: attrs.meta_title ?? attrs.name ?? '',
-      description: attrs.meta_description ?? '',
-    },
-    updatedAt: attrs.updated_at ?? new Date().toISOString(),
-    path: `/collections/${attrs.permalink ?? attrs.slug ?? data.id}`,
-  };
-}
-
-// ============================================
-// Cart Transforms
-// ============================================
-
-export function transformCart(data: any, currencyCode: string = 'USD'): Cart {
-  const attrs = data.attributes ?? data;
-  const items: CartItem[] = (attrs.line_items ?? data.included?.filter((i: any) => i.type === 'line_item') ?? []).map(
-    (item: any): CartItem => {
-      const itemAttrs = item.attributes ?? item;
-      return {
-        id: String(item.id ?? itemAttrs.id ?? ''),
-        quantity: itemAttrs.quantity ?? 1,
-        cost: {
-          totalAmount: toMoney(itemAttrs.total ?? itemAttrs.display_total ?? '0', currencyCode),
-        },
-        merchandise: {
-          id: String(itemAttrs.variant_id ?? item.id ?? ''),
-          title: itemAttrs.name ?? '',
-          selectedOptions: [],
-          product: {
-            id: String(itemAttrs.product_id ?? ''),
-            handle: itemAttrs.slug ?? '',
-            title: itemAttrs.name ?? '',
-            featuredImage: { url: itemAttrs.image_url ?? '', altText: itemAttrs.name ?? '' },
-          },
-        },
-      };
-    },
-  );
-
-  return {
-    id: String(data.id ?? attrs.token ?? ''),
-    checkoutUrl: '',
-    totalQuantity: items.reduce((sum, i) => sum + i.quantity, 0),
-    cost: {
-      subtotalAmount: toMoney(attrs.item_total ?? attrs.display_item_total ?? '0', currencyCode),
-      totalAmount: toMoney(attrs.total ?? attrs.display_total ?? '0', currencyCode),
-      totalTaxAmount: toMoney(attrs.tax_total ?? attrs.display_tax_total ?? '0', currencyCode),
-    },
-    lines: items,
-  };
-}
-
-// ============================================
-// Customer Transforms
-// ============================================
-
-export function transformCustomer(data: any): Customer {
-  const attrs = data.attributes ?? data;
-  return {
-    id: String(data.id ?? ''),
-    email: attrs.email ?? '',
-    firstName: attrs.first_name ?? '',
-    lastName: attrs.last_name ?? '',
-    phone: attrs.phone ?? '',
-    hasAccount: true,
-  };
-}
-
-function transformAddress(addr: any): Address {
-  return {
-    id: String(addr.id ?? ''),
-    firstName: addr.first_name ?? addr.firstname ?? '',
-    lastName: addr.last_name ?? addr.lastname ?? '',
-    company: addr.company ?? '',
-    address1: addr.address1 ?? '',
-    address2: addr.address2 ?? '',
-    city: addr.city ?? '',
-    province: addr.state_name ?? addr.state ?? '',
-    postalCode: addr.zipcode ?? addr.zip ?? '',
-    countryCode: addr.country_iso ?? addr.country_code ?? '',
-    phone: addr.phone ?? '',
-  };
-}
-
-// ============================================
-// Order Transforms
-// ============================================
-
-export function transformOrder(data: any, currencyCode: string = 'USD'): Order {
-  const attrs = data.attributes ?? data;
-  const items: OrderItem[] = (attrs.line_items ?? []).map((item: any) => ({
-    id: String(item.id ?? ''),
-    title: item.name ?? '',
-    quantity: item.quantity ?? 1,
-    price: toMoney(item.price ?? '0', currencyCode),
-    total: toMoney(item.total ?? '0', currencyCode),
-    productId: String(item.product_id ?? ''),
-    variantId: String(item.variant_id ?? ''),
-  }));
-
-  return {
-    id: String(data.id ?? attrs.number ?? ''),
-    orderNumber: attrs.number ?? String(data.id ?? ''),
-    email: attrs.email ?? '',
-    status: (attrs.state === 'complete' ? 'completed' : attrs.state === 'canceled' ? 'cancelled' : 'pending') as any,
-    paymentStatus: (attrs.payment_state === 'paid' ? 'paid' : attrs.payment_state === 'balance_due' ? 'pending' : 'pending') as any,
-    fulfillmentStatus: (attrs.shipment_state === 'shipped' ? 'fulfilled' : attrs.shipment_state === 'partial' ? 'partially_fulfilled' : 'unfulfilled') as any,
-    items,
-    total: toMoney(attrs.total ?? '0', currencyCode),
-    subtotal: toMoney(attrs.item_total ?? '0', currencyCode),
-    tax: toMoney(attrs.tax_total ?? '0', currencyCode),
-    shipping: toMoney(attrs.ship_total ?? '0', currencyCode),
-    shippingAddress: attrs.ship_address ? transformAddress(attrs.ship_address) : undefined,
-    billingAddress: attrs.bill_address ? transformAddress(attrs.bill_address) : undefined,
-    createdAt: attrs.created_at ?? new Date().toISOString(),
-    updatedAt: attrs.updated_at ?? new Date().toISOString(),
-  };
-}