@thorprovider/adapters 5.0.0 → 5.0.1

package/src/providers/bigcommerce/index.ts

@@ -0,0 +1,315 @@
+/**
+ * @thorprovider/adapters — BigCommerce Provider
+ * Implements CommerceProvider for BigCommerce REST Storefront API
+ *
+ * Uses raw fetch against BigCommerce Storefront REST API.
+ * The official `@bigcommerce/storefront-data-hooks` is deprecated (3 years unmaintained).
+ */
+
+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 { BIGCOMMERCE_CAPABILITIES } from '../../types/capabilities.types';
+import { createLogger } from '../../core/logger';
+import { ProviderAPIError } from '../../core/errors';
+import {
+  transformProduct,
+  transformCart,
+  transformCollection,
+  transformCustomer,
+  transformOrder,
+} from './transforms';
+
+/**
+ * BigCommerce provider configuration
+ */
+export interface BigCommerceProviderConfig extends ProviderConfig {
+  /** BigCommerce store hash */
+  storeHash: string;
+  /** Storefront API token (JWT) */
+  storefrontApiToken: string;
+  /** Storefront API URL (usually https://store-{hash}.mybigcommerce.com) */
+  storefrontApiUrl: string;
+  /** Channel ID */
+  channelId: string;
+  /** Default currency code (default: 'USD') */
+  currencyCode?: string;
+}
+
+export class BigCommerceProvider implements CommerceProvider {
+  readonly name = 'bigcommerce';
+  readonly version = '1.0.0';
+  readonly capabilities: BackendCapabilities = BIGCOMMERCE_CAPABILITIES;
+
+  private logger: ReturnType<typeof createLogger>;
+  private storefrontApiUrl: string;
+  private storeHash: string;
+  private channelId: string;
+  private currencyCode: string;
+  private headers: Record<string, string>;
+
+  constructor(config: BigCommerceProviderConfig) {
+    this.logger = createLogger('BigCommerceProvider', config.debug);
+    this.storefrontApiUrl = config.storefrontApiUrl.replace(/\/$/, '');
+    this.storeHash = config.storeHash;
+    this.channelId = config.channelId;
+    this.currencyCode = config.currencyCode ?? 'USD';
+    this.headers = {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.storefrontApiToken}`,
+    };
+    this.logger.info('Initializing BigCommerce Provider', { storeHash: this.storeHash, channelId: this.channelId });
+  }
+
+  private async fetchApi<T = any>(path: string, init?: RequestInit): Promise<T> {
+    const url = `${this.storefrontApiUrl}${path}`;
+    const response = await fetch(url, {
+      ...init,
+      headers: { ...this.headers, ...init?.headers },
+    });
+
+    if (!response.ok) {
+      throw new ProviderAPIError(
+        `BigCommerce API error: ${response.status} ${response.statusText}`,
+        'BIGCOMMERCE_API_ERROR',
+        response.status,
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  // ============================================
+  // Product Operations
+  // ============================================
+
+  async getProduct(handle: string): Promise<Product | undefined> {
+    try {
+      const data = await this.fetchApi<{ data: any[] }>(`/api/storefront/products?include=variants,options,images&keyword=${encodeURIComponent(handle)}`);
+      const product = data.data?.[0];
+      return product ? transformProduct(product, this.currencyCode) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
+    const limit = options?.first ?? 20;
+    let path = `/api/storefront/products?include=variants,options,images&limit=${limit}`;
+    if (options?.query) path += `&keyword=${encodeURIComponent(options.query)}`;
+
+    const data = await this.fetchApi<{ data: any[] }>(path);
+    return (data.data ?? []).map((p) => transformProduct(p, this.currencyCode));
+  }
+
+  async getProductRecommendations(_productId: string): Promise<Product[]> {
+    return []; // BigCommerce doesn't have a Storefront recommendation API
+  }
+
+  // ============================================
+  // Collection Operations (BigCommerce Categories)
+  // ============================================
+
+  async getCollection(handle: string): Promise<Collection | undefined> {
+    try {
+      const data = await this.fetchApi<{ data: any[] }>(`/api/storefront/categories?url=/${handle}/`);
+      const cat = data.data?.[0];
+      return cat ? transformCollection(cat) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
+    const limit = options?.limit ?? 50;
+    const data = await this.fetchApi<{ data: any[] }>(`/api/storefront/categories?limit=${limit}`);
+    return (data.data ?? []).map(transformCollection);
+  }
+
+  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    const limit = options?.first ?? 20;
+    const data = await this.fetchApi<{ data: any[] }>(
+      `/api/storefront/products?include=variants,options,images&categories:in=${handle}&limit=${limit}`,
+    );
+    return (data.data ?? []).map((p) => transformProduct(p, this.currencyCode));
+  }
+
+  // ============================================
+  // Category Operations
+  // ============================================
+
+  async getCategory(idOrHandle: string): Promise<ProductCategory | undefined> {
+    return this.getCollection(idOrHandle) 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.fetchApi<{ data: any }>('/api/storefront/carts', {
+      method: 'POST',
+      body: JSON.stringify({ line_items: [] }),
+    });
+    return transformCart(data.data ?? data, this.currencyCode);
+  }
+
+  async getCart(cartId: string): Promise<Cart | undefined> {
+    try {
+      const data = await this.fetchApi<{ data: any }>(`/api/storefront/carts/${cartId}?include=line_items.physical_items.options`);
+      return transformCart(data.data ?? data, this.currencyCode);
+    } catch {
+      return undefined;
+    }
+  }
+
+  async addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart> {
+    const lineItems = lines.map((l) => ({
+      product_id: parseInt(l.merchandiseId, 10),
+      quantity: l.quantity,
+    }));
+
+    const data = await this.fetchApi<{ data: any }>(`/api/storefront/carts/${cartId}/items`, {
+      method: 'POST',
+      body: JSON.stringify({ line_items: lineItems }),
+    });
+
+    return transformCart(data.data ?? data, this.currencyCode);
+  }
+
+  async removeFromCart(cartId: string, lineIds: string[]): Promise<Cart> {
+    for (const lineId of lineIds) {
+      await this.fetchApi(`/api/storefront/carts/${cartId}/items/${lineId}`, { method: 'DELETE' });
+    }
+
+    const cart = await this.getCart(cartId);
+    if (!cart) throw new ProviderAPIError('Cart not found after removal', 'BIGCOMMERCE_CART_ERROR');
+    return cart;
+  }
+
+  async updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart> {
+    for (const line of lines) {
+      await this.fetchApi(`/api/storefront/carts/${cartId}/items/${line.id}`, {
+        method: 'PUT',
+        body: JSON.stringify({ line_item: { quantity: line.quantity } }),
+      });
+    }
+
+    const cart = await this.getCart(cartId);
+    if (!cart) throw new ProviderAPIError('Cart not found after update', 'BIGCOMMERCE_CART_ERROR');
+    return cart;
+  }
+
+  // ============================================
+  // Checkout Operations (Hosted)
+  // ============================================
+
+  async completeCheckout(_cartId: string): Promise<Order> {
+    throw new ProviderAPIError(
+      'BigCommerce uses Embedded Checkout. Redirect the buyer to cart.checkoutUrl.',
+      'BIGCOMMERCE_HOSTED_CHECKOUT',
+    );
+  }
+
+  async getShippingMethods(_cartId: string): Promise<ShippingMethod[]> {
+    return [];
+  }
+
+  async getRegionCountries(): Promise<import('@thorprovider/types').Country[]> {
+    return [];
+  }
+
+  async addShippingMethod(_cartId: string, _methodId: string): Promise<Cart> {
+    throw new ProviderAPIError('BigCommerce handles shipping in Embedded Checkout.', 'BIGCOMMERCE_HOSTED_CHECKOUT');
+  }
+
+  async initiatePaymentSession(_cartId: string, _providerId: string): Promise<void> {
+    throw new ProviderAPIError('BigCommerce handles payment in Embedded Checkout.', 'BIGCOMMERCE_HOSTED_CHECKOUT');
+  }
+
+  async applyDiscountCode(cartId: string, code: string): Promise<Cart> {
+    const data = await this.fetchApi<{ data: any }>(`/api/storefront/carts/${cartId}/coupons`, {
+      method: 'POST',
+      body: JSON.stringify({ coupon_code: code }),
+    });
+    return transformCart(data.data ?? data, this.currencyCode);
+  }
+
+  async removeDiscountCode(cartId: string, code: string): Promise<Cart> {
+    await this.fetchApi(`/api/storefront/carts/${cartId}/coupons/${encodeURIComponent(code)}`, { method: 'DELETE' });
+    const cart = await this.getCart(cartId);
+    if (!cart) throw new ProviderAPIError('Cart not found after coupon removal', 'BIGCOMMERCE_CART_ERROR');
+    return cart;
+  }
+
+  // ============================================
+  // Customer, Order, Payment, Inventory, Admin
+  // ============================================
+
+  async getOrders(_options: GetOrdersOptions): Promise<Order[]> {
+    return [];
+  }
+
+  async getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
+    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 BigCommerce Management API.', 'BIGCOMMERCE_ADMIN_REQUIRED');
+  }
+  async createFulfillment(_orderId: string): Promise<void> {
+    throw new ProviderAPIError('Fulfillment requires BigCommerce Management API.', 'BIGCOMMERCE_ADMIN_REQUIRED');
+  }
+  async createRefund(_orderId: string): Promise<void> {
+    throw new ProviderAPIError('Refunds require BigCommerce Management API.', 'BIGCOMMERCE_ADMIN_REQUIRED');
+  }
+  async getAdminOrders(): Promise<{ orders: Order[]; count: number }> { return { orders: [], count: 0 }; }
+
+  async getStorefrontContext(): Promise<StorefrontContext> {
+    return {
+      id: this.channelId,
+      name: `BigCommerce Store ${this.storeHash}`,
+      platformType: 'bigcommerce',
+      requiresProductScoping: false,
+      currencyCode: this.currencyCode,
+    };
+  }
+
+  isStorefrontRequired(): boolean { return false; }
+}

package/src/providers/bigcommerce/transforms.ts

@@ -0,0 +1,227 @@
+/**
+ * @thorprovider/adapters — BigCommerce Provider
+ * Transform functions: BigCommerce REST API → @thorprovider/types
+ */
+
+import type {
+  Product,
+  ProductVariant,
+  ProductOption,
+  Cart,
+  CartItem,
+  Collection,
+  Money,
+  Image,
+  Order,
+  OrderItem,
+  OrderStatus,
+  PaymentStatus,
+  FulfillmentStatus,
+  Customer,
+  Address,
+} from '@thorprovider/types';
+
+// ============================================
+// Money & Image Transforms
+// ============================================
+
+function transformMoney(amount: number | string | null | undefined, currencyCode: string = 'USD'): Money {
+  const numAmount = typeof amount === 'string' ? parseFloat(amount) : (amount ?? 0);
+  return {
+    amount: numAmount.toFixed(2),
+    currencyCode: currencyCode.toUpperCase(),
+  };
+}
+
+function transformImage(url: string, alt: string = ''): Image {
+  return { url, altText: alt, width: 800, height: 800 };
+}
+
+// ============================================
+// Product Transforms
+// ============================================
+
+export function transformProduct(raw: any, currencyCode: string = 'USD'): Product {
+  const images: Image[] = (raw.images ?? []).map((img: any) =>
+    transformImage(img.url_standard ?? img.url_thumbnail ?? '', img.description ?? ''),
+  );
+
+  const variants: ProductVariant[] = (raw.variants ?? []).map((v: any) => ({
+    id: String(v.id),
+    title: v.option_display_name ?? `Variant ${v.id}`,
+    availableForSale: (v.purchasing_disabled !== true),
+    price: transformMoney(v.price ?? raw.price, currencyCode),
+    compareAtPrice: v.sale_price ? transformMoney(v.sale_price, currencyCode) : undefined,
+    selectedOptions: (v.option_values ?? []).map((ov: any) => ({
+      name: ov.option_display_name ?? '',
+      value: ov.label ?? '',
+    })),
+  }));
+
+  const options: ProductOption[] = (raw.options ?? []).map((opt: any) => ({
+    id: String(opt.id),
+    name: opt.display_name ?? '',
+    values: (opt.option_values ?? []).map((val: any) => val.label ?? ''),
+  }));
+
+  const price = raw.price ?? raw.calculated_price?.as_entered ?? 0;
+
+  return {
+    id: String(raw.id),
+    handle: raw.custom_url?.url?.replace(/^\//, '').replace(/\/$/, '') ?? String(raw.id),
+    title: raw.name ?? '',
+    description: raw.plain_text_description ?? raw.description ?? '',
+    descriptionHtml: raw.description ?? '',
+    availableForSale: raw.availability === 'available' || raw.is_visible !== false,
+    featuredImage: images[0] ?? { url: '', altText: '', width: 800, height: 800 },
+    images,
+    options,
+    variants,
+    priceRange: {
+      minVariantPrice: transformMoney(price, currencyCode),
+      maxVariantPrice: transformMoney(price, currencyCode),
+    },
+    seo: {
+      title: raw.page_title ?? raw.name ?? '',
+      description: raw.meta_description ?? '',
+    },
+    tags: [],
+    createdAt: raw.date_created ?? new Date().toISOString(),
+    updatedAt: raw.date_modified ?? new Date().toISOString(),
+  };
+}
+
+// ============================================
+// Collection Transforms (BigCommerce "Categories" or "Brands")
+// ============================================
+
+export function transformCollection(raw: any): Collection {
+  return {
+    id: String(raw.id ?? ''),
+    handle: raw.custom_url?.url?.replace(/^\//, '').replace(/\/$/, '') ?? String(raw.id),
+    title: raw.name ?? '',
+    description: raw.description ?? '',
+    seo: {
+      title: raw.page_title ?? raw.name ?? '',
+      description: raw.meta_description ?? '',
+    },
+    updatedAt: raw.date_modified ?? new Date().toISOString(),
+    path: `/collections/${raw.custom_url?.url?.replace(/^\//, '').replace(/\/$/, '') ?? raw.id}`,
+  };
+}
+
+// ============================================
+// Cart Transforms
+// ============================================
+
+export function transformCart(raw: any, currencyCode: string = 'USD'): Cart {
+  const lineItems = Object.values(raw.line_items ?? {}).flat() as any[];
+
+  const lines: CartItem[] = lineItems.map((item: any) => ({
+    id: item.id,
+    quantity: item.quantity ?? 1,
+    cost: {
+      totalAmount: transformMoney(item.extended_sale_price ?? item.sale_price ?? 0, currencyCode),
+    },
+    merchandise: {
+      id: String(item.variant_id ?? item.product_id),
+      title: item.name ?? '',
+      selectedOptions: (item.options ?? []).map((opt: any) => ({
+        name: opt.name ?? '',
+        value: opt.value ?? '',
+      })),
+      product: {
+        id: String(item.product_id),
+        handle: String(item.product_id),
+        title: item.name ?? '',
+        featuredImage: item.image_url
+          ? transformImage(item.image_url)
+          : { url: '', altText: '', width: 800, height: 800 },
+      },
+    },
+  }));
+
+  return {
+    id: raw.id,
+    checkoutUrl: raw.redirect_urls?.checkout_url ?? '',
+    totalQuantity: lines.reduce((sum, l) => sum + l.quantity, 0),
+    cost: {
+      subtotalAmount: transformMoney(raw.base_amount ?? 0, currencyCode),
+      totalAmount: transformMoney(raw.cart_amount ?? 0, currencyCode),
+    },
+    lines,
+  };
+}
+
+// ============================================
+// Customer Transforms
+// ============================================
+
+export function transformCustomer(raw: any): Customer {
+  return {
+    id: String(raw.id),
+    email: raw.email ?? '',
+    firstName: raw.first_name ?? '',
+    lastName: raw.last_name ?? '',
+    phone: raw.phone ?? '',
+    hasAccount: true,
+  };
+}
+
+export function transformAddress(raw: any): Address {
+  return {
+    id: String(raw.id ?? ''),
+    firstName: raw.first_name ?? '',
+    lastName: raw.last_name ?? '',
+    address1: raw.address1 ?? '',
+    address2: raw.address2 ?? '',
+    city: raw.city ?? '',
+    province: raw.state_or_province ?? '',
+    countryCode: raw.country_code ?? '',
+    postalCode: raw.postal_code ?? '',
+    phone: raw.phone ?? '',
+    company: raw.company ?? '',
+  };
+}
+
+// ============================================
+// Order Transforms
+// ============================================
+
+export function transformOrder(raw: any, currencyCode: string = 'USD'): Order {
+  const items: OrderItem[] = (raw.products ?? []).map((p: any) => ({
+    id: String(p.id),
+    title: p.name ?? '',
+    variantTitle: p.sku ?? '',
+    quantity: p.quantity ?? 1,
+    price: transformMoney(p.base_price ?? 0, currencyCode),
+    total: transformMoney(p.base_total ?? 0, currencyCode),
+    productId: String(p.product_id),
+  }));
+
+  const statusMap: Record<string, OrderStatus> = {
+    'Incomplete': 'pending',
+    'Pending': 'pending',
+    'Shipped': 'completed',
+    'Partially Shipped': 'processing',
+    'Refunded': 'refunded',
+    'Cancelled': 'cancelled',
+    'Completed': 'completed',
+  };
+
+  return {
+    id: String(raw.id),
+    orderNumber: String(raw.id),
+    email: raw.billing_address?.email ?? '',
+    status: statusMap[raw.status] ?? 'pending',
+    paymentStatus: raw.payment_status === 'paid' ? 'paid' : 'pending',
+    fulfillmentStatus: raw.status === 'Shipped' ? 'fulfilled' : 'unfulfilled',
+    items,
+    total: transformMoney(raw.total_inc_tax ?? 0, currencyCode),
+    subtotal: transformMoney(raw.subtotal_inc_tax ?? 0, currencyCode),
+    tax: transformMoney(raw.total_tax ?? 0, currencyCode),
+    shipping: transformMoney(raw.shipping_cost_inc_tax ?? 0, currencyCode),
+    createdAt: raw.date_created ?? new Date().toISOString(),
+    updatedAt: raw.date_modified ?? new Date().toISOString(),
+  };
+}

package/src/providers/index.ts

@@ -1,5 +1,5 @@
 /**
- * @thorprovider/adapters v5.0
+ * @thorprovider/adapters v2.0
  * Providers index
  */
 
@@ -9,5 +9,20 @@ export type { MedusaProviderConfig } from './medusa';
 export { StelOrderProvider } from './stelorder';
 export type { StelOrderProviderConfig } from './stelorder';
 
+export { ShopifyProvider } from './shopify';
+export type { ShopifyProviderConfig } from './shopify';
+
+export { BigCommerceProvider } from './bigcommerce';
+export type { BigCommerceProviderConfig } from './bigcommerce';
+
+export { WooCommerceProvider } from './woocommerce';
+export type { WooCommerceProviderConfig } from './woocommerce';
+
+export { SpreeProvider } from './spree';
+export type { SpreeProviderConfig } from './spree';
+
+export { MagentoProvider } from './magento';
+export type { MagentoProviderConfig } from './magento';
+
 export { MockProvider } from './mock';
 export type { MockProviderConfig } from './mock';