@thorprovider/adapters 3.0.2

package/src/providers/magento/index.ts

@@ -0,0 +1,387 @@
+/**
+ * @thorprovider/adapters — Magento (Adobe Commerce) Provider
+ * Implements CommerceProvider for Magento 2 GraphQL + REST APIs
+ *
+ * Uses GraphQL Storefront for read operations (products, categories, cart).
+ * REST API for customer/order operations requiring auth tokens.
+ * PaaS-first approach (not Adobe IMS/SaaS).
+ */
+
+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 { MAGENTO_CAPABILITIES } from '../../types/capabilities.types';
+import { createLogger } from '../../core/logger';
+import { ProviderAPIError } from '../../core/errors';
+import { transformProduct, transformCart, transformCollection, transformOrder, transformCustomer } from './transforms';
+import {
+  GET_PRODUCTS,
+  GET_PRODUCT_BY_URL_KEY,
+  GET_CATEGORIES,
+  GET_CATEGORY_BY_URL_KEY,
+  GET_CATEGORY_PRODUCTS,
+  GET_CART,
+  CREATE_EMPTY_CART,
+  ADD_TO_CART,
+  REMOVE_FROM_CART,
+  UPDATE_CART_ITEMS,
+  APPLY_COUPON,
+  REMOVE_COUPON,
+  GET_CUSTOMER,
+  GET_CUSTOMER_ORDERS,
+} from './queries';
+
+/**
+ * Magento provider configuration
+ */
+export interface MagentoProviderConfig extends ProviderConfig {
+  /** Magento base URL (e.g., 'https://mymagento.com') */
+  baseUrl: string;
+  /** Store code for multi-tenant (default: 'default') */
+  storeCode?: string;
+  /** Customer bearer token (for authenticated operations) */
+  customerToken?: string;
+  /** Integration access token (for admin-level operations) */
+  accessToken?: string;
+  /** Default currency code (default: 'USD') */
+  currencyCode?: string;
+}
+
+export class MagentoProvider implements CommerceProvider {
+  readonly name = 'magento';
+  readonly version = '1.0.0';
+  readonly capabilities: BackendCapabilities = MAGENTO_CAPABILITIES;
+
+  private logger: ReturnType<typeof createLogger>;
+  private baseUrl: string;
+  private storeCode: string;
+  private currencyCode: string;
+  private graphqlEndpoint: string;
+  private customerToken?: string;
+  private accessToken?: string;
+
+  constructor(config: MagentoProviderConfig) {
+    this.logger = createLogger('MagentoProvider', config.debug);
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.storeCode = config.storeCode ?? 'default';
+    this.currencyCode = config.currencyCode ?? 'USD';
+    this.graphqlEndpoint = `${this.baseUrl}/graphql`;
+    this.customerToken = config.customerToken;
+    this.accessToken = config.accessToken;
+
+    this.logger.info('Initializing Magento Provider', {
+      baseUrl: this.baseUrl,
+      storeCode: this.storeCode,
+    });
+  }
+
+  private async graphql<T = any>(query: string, variables?: Record<string, any>): Promise<T> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Store': this.storeCode,
+    };
+
+    if (this.customerToken) {
+      headers['Authorization'] = `Bearer ${this.customerToken}`;
+    }
+
+    const response = await fetch(this.graphqlEndpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ query, variables }),
+    });
+
+    if (!response.ok) {
+      throw new ProviderAPIError(
+        `Magento GraphQL error: ${response.status}`,
+        'MAGENTO_API_ERROR',
+        response.status,
+      );
+    }
+
+    const json = await response.json() as { data?: T; errors?: Array<{ message: string }> };
+
+    if (json.errors?.length) {
+      const message = json.errors.map((e) => e.message).join('; ');
+      throw new ProviderAPIError(`Magento GraphQL error: ${message}`, 'MAGENTO_GRAPHQL_ERROR');
+    }
+
+    return json.data as T;
+  }
+
+  // ============================================
+  // Product Operations (GraphQL)
+  // ============================================
+
+  async getProduct(handle: string): Promise<Product | undefined> {
+    try {
+      const data = await this.graphql<{ products: { items: any[] } }>(GET_PRODUCT_BY_URL_KEY, { urlKey: handle });
+      return data.products.items[0] ? transformProduct(data.products.items[0], this.currencyCode) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
+    const variables: Record<string, any> = {
+      pageSize: options?.first ?? 20,
+      currentPage: 1,
+    };
+
+    if (options?.query) variables.search = options.query;
+    if (options?.sortKey) {
+      const sortMap: Record<string, Record<string, string>> = {
+        'price-asc': { price: 'ASC' },
+        'price-desc': { price: 'DESC' },
+        'title-asc': { name: 'ASC' },
+        'title-desc': { name: 'DESC' },
+        'created-desc': { created_at: 'DESC' },
+        'relevance': { relevance: 'DESC' },
+      };
+      variables.sort = sortMap[options.sortKey] ?? { relevance: 'DESC' };
+    }
+
+    const data = await this.graphql<{ products: { items: any[] } }>(GET_PRODUCTS, variables);
+    return (data.products?.items ?? []).map((p) => transformProduct(p, this.currencyCode));
+  }
+
+  async getProductRecommendations(_productId: string): Promise<Product[]> {
+    return [];
+  }
+
+  // ============================================
+  // Collection/Category Operations (GraphQL)
+  // ============================================
+
+  async getCollection(handle: string): Promise<Collection | undefined> {
+    try {
+      const data = await this.graphql<{ categories: { items: any[] } }>(GET_CATEGORY_BY_URL_KEY, { urlKey: handle });
+      return data.categories.items[0] ? transformCollection(data.categories.items[0]) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
+    const data = await this.graphql<{ categories: { items: any[] } }>(GET_CATEGORIES, {
+      pageSize: options?.limit ?? 50,
+    });
+    return (data.categories?.items ?? []).map(transformCollection);
+  }
+
+  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    const data = await this.graphql<{ products: { items: any[] } }>(GET_CATEGORY_PRODUCTS, {
+      urlKey: handle,
+      pageSize: options?.first ?? 20,
+    });
+    return (data.products?.items ?? []).map((p) => transformProduct(p, 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 (GraphQL)
+  // ============================================
+
+  async createCart(): Promise<Cart> {
+    const data = await this.graphql<{ createEmptyCart: string }>(CREATE_EMPTY_CART);
+    const cartId = data.createEmptyCart;
+    const cartData = await this.graphql<{ cart: any }>(GET_CART, { cartId });
+    return transformCart(cartData.cart ?? { id: cartId, items: [], prices: {} }, this.currencyCode);
+  }
+
+  async getCart(cartId: string): Promise<Cart | undefined> {
+    try {
+      const data = await this.graphql<{ cart: any }>(GET_CART, { cartId });
+      return data.cart ? transformCart(data.cart, this.currencyCode) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart> {
+    const cartItems = lines.map((l) => ({
+      sku: l.merchandiseId,
+      quantity: l.quantity,
+    }));
+
+    const data = await this.graphql<{ addProductsToCart: { cart: any; user_errors: any[] } }>(ADD_TO_CART, {
+      cartId,
+      cartItems,
+    });
+
+    if (data.addProductsToCart.user_errors?.length) {
+      throw new ProviderAPIError(
+        `Add to cart failed: ${data.addProductsToCart.user_errors.map((e: any) => e.message).join('; ')}`,
+        'MAGENTO_CART_ERROR',
+      );
+    }
+
+    return transformCart(data.addProductsToCart.cart, this.currencyCode);
+  }
+
+  async removeFromCart(cartId: string, lineIds: string[]): Promise<Cart> {
+    let cart: any;
+    for (const itemUid of lineIds) {
+      const data = await this.graphql<{ removeItemFromCart: { cart: any } }>(REMOVE_FROM_CART, {
+        cartId,
+        cartItemUid: itemUid,
+      });
+      cart = data.removeItemFromCart.cart;
+    }
+    return transformCart(cart ?? { id: cartId, items: [], prices: {} }, this.currencyCode);
+  }
+
+  async updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart> {
+    const cartItems = lines.map((l) => ({
+      cart_item_uid: l.id,
+      quantity: l.quantity,
+    }));
+
+    const data = await this.graphql<{ updateCartItems: { cart: any } }>(UPDATE_CART_ITEMS, {
+      cartId,
+      cartItems,
+    });
+
+    return transformCart(data.updateCartItems.cart, this.currencyCode);
+  }
+
+  // ============================================
+  // Checkout Operations
+  // ============================================
+
+  async completeCheckout(_cartId: string): Promise<Order> {
+    throw new ProviderAPIError(
+      'Magento checkout requires multi-step process (set addresses, shipping, payment, place order). Use the Magento checkout flow.',
+      'MAGENTO_CHECKOUT_MULTI_STEP',
+    );
+  }
+
+  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(
+      'Magento shipping selection requires set-shipping-methods mutation.',
+      'MAGENTO_CHECKOUT_MULTI_STEP',
+    );
+  }
+
+  async initiatePaymentSession(_cartId: string, _providerId: string): Promise<void> {
+    // Magento handles payment via set-payment-method mutation
+  }
+
+  async applyDiscountCode(cartId: string, code: string): Promise<Cart> {
+    const data = await this.graphql<{ applyCouponToCart: { cart: any } }>(APPLY_COUPON, {
+      cartId,
+      couponCode: code,
+    });
+    return transformCart(data.applyCouponToCart.cart, this.currencyCode);
+  }
+
+  async removeDiscountCode(cartId: string, _code: string): Promise<Cart> {
+    const data = await this.graphql<{ removeCouponFromCart: { cart: any } }>(REMOVE_COUPON, {
+      cartId,
+    });
+    return transformCart(data.removeCouponFromCart.cart, this.currencyCode);
+  }
+
+  // ============================================
+  // Customer & Orders (GraphQL — requires customerToken)
+  // ============================================
+
+  async getOrders(_options: GetOrdersOptions): Promise<Order[]> {
+    if (!this.customerToken) return [];
+    try {
+      const data = await this.graphql<{ customer: { orders: { items: any[] } } }>(GET_CUSTOMER_ORDERS, {
+        pageSize: 20,
+        currentPage: 1,
+      });
+      return (data.customer?.orders?.items ?? []).map((o) => transformOrder(o, this.currencyCode));
+    } catch {
+      return [];
+    }
+  }
+
+  async getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
+    return [];
+  }
+
+  // ============================================
+  // Inventory
+  // ============================================
+
+  async getStockLocations(): Promise<StockLocation[]> { return []; }
+  async checkInventoryLevels(): Promise<InventoryLevel[]> { return []; }
+  async validateCartStock(): Promise<StockValidation> { return { allAvailable: true, unavailableItems: [] }; }
+  async getFulfillmentOptions(): Promise<FulfillmentOption[]> { return []; }
+
+  // ============================================
+  // Admin Operations
+  // ============================================
+
+  async cancelOrder(_orderId: string): Promise<Order> {
+    throw new ProviderAPIError('Order cancellation requires Magento Admin API.', 'MAGENTO_ADMIN_REQUIRED');
+  }
+  async createFulfillment(_orderId: string): Promise<void> {
+    throw new ProviderAPIError('Fulfillment requires Magento Admin API.', 'MAGENTO_ADMIN_REQUIRED');
+  }
+  async createRefund(_orderId: string): Promise<void> {
+    throw new ProviderAPIError('Refunds require Magento Admin API.', 'MAGENTO_ADMIN_REQUIRED');
+  }
+  async getAdminOrders(): Promise<{ orders: Order[]; count: number }> { return { orders: [], count: 0 }; }
+
+  // ============================================
+  // Storefront / Multi-Tenant
+  // ============================================
+
+  async getStorefrontContext(): Promise<StorefrontContext> {
+    return {
+      id: this.storeCode,
+      name: `Magento ${this.storeCode}`,
+      platformType: 'magento',
+      requiresProductScoping: true,
+      currencyCode: this.currencyCode,
+    };
+  }
+
+  isStorefrontRequired(): boolean { return true; }
+}

package/src/providers/magento/magento.ts

@@ -0,0 +1,5 @@
+/**
+ * Magento (Adobe Commerce) Provider — barrel exports
+ */
+export { MagentoProvider } from './index';
+export type { MagentoProviderConfig } from './index';

package/src/providers/magento/queries.ts

@@ -0,0 +1,267 @@
+/**
+ * Magento GraphQL Queries for Storefront
+ * Used by MagentoProvider to query products, categories, cart, and customer data.
+ */
+
+export const PRODUCT_FIELDS = `
+  id
+  uid
+  sku
+  name
+  url_key
+  stock_status
+  short_description { html }
+  description { html }
+  meta_title
+  meta_description
+  created_at
+  updated_at
+  price_range {
+    minimum_price {
+      regular_price { value currency }
+      final_price { value currency }
+    }
+    maximum_price {
+      regular_price { value currency }
+      final_price { value currency }
+    }
+  }
+  small_image { url label }
+  image { url label }
+  media_gallery {
+    url
+    label
+  }
+  ... on ConfigurableProduct {
+    configurable_options {
+      attribute_code
+      attribute_id
+      label
+      values {
+        label
+        value_index
+      }
+    }
+    variants {
+      product {
+        id uid sku name
+        stock_status
+        price_range {
+          minimum_price {
+            final_price { value currency }
+          }
+        }
+        small_image { url label }
+      }
+      attributes {
+        label
+        value_index
+      }
+    }
+  }
+`;
+
+export const GET_PRODUCTS = `
+  query GetProducts($search: String, $pageSize: Int, $currentPage: Int, $sort: ProductAttributeSortInput) {
+    products(search: $search, pageSize: $pageSize, currentPage: $currentPage, sort: $sort) {
+      items { ${PRODUCT_FIELDS} }
+      total_count
+    }
+  }
+`;
+
+export const GET_PRODUCT_BY_URL_KEY = `
+  query GetProductByUrlKey($urlKey: String!) {
+    products(filter: { url_key: { eq: $urlKey } }, pageSize: 1) {
+      items { ${PRODUCT_FIELDS} }
+    }
+  }
+`;
+
+export const GET_CATEGORIES = `
+  query GetCategories($pageSize: Int) {
+    categories(pageSize: $pageSize) {
+      items {
+        id uid name url_key url_path description meta_title meta_description
+      }
+    }
+  }
+`;
+
+export const GET_CATEGORY_BY_URL_KEY = `
+  query GetCategoryByUrlKey($urlKey: String!) {
+    categories(filters: { url_key: { eq: $urlKey } }, pageSize: 1) {
+      items {
+        id uid name url_key url_path description meta_title meta_description
+      }
+    }
+  }
+`;
+
+export const GET_CATEGORY_PRODUCTS = `
+  query GetCategoryProducts($urlKey: String!, $pageSize: Int) {
+    products(filter: { category_url_key: { eq: $urlKey } }, pageSize: $pageSize) {
+      items { ${PRODUCT_FIELDS} }
+      total_count
+    }
+  }
+`;
+
+export const GET_CART = `
+  query GetCart($cartId: String!) {
+    cart(cart_id: $cartId) {
+      id
+      items {
+        id uid quantity
+        product {
+          id uid sku name url_key
+          small_image { url }
+          thumbnail { url }
+          price_range {
+            minimum_price {
+              final_price { value currency }
+            }
+          }
+        }
+        prices {
+          price { value currency }
+          row_total { value currency }
+        }
+        ... on ConfigurableCartItem {
+          configurable_options {
+            option_label
+            value_label
+          }
+        }
+      }
+      prices {
+        grand_total { value currency }
+        subtotal_excluding_tax { value currency }
+        subtotal_including_tax { value currency }
+        applied_taxes {
+          amount { value currency }
+          label
+        }
+      }
+    }
+  }
+`;
+
+export const CREATE_EMPTY_CART = `
+  mutation CreateEmptyCart {
+    createEmptyCart
+  }
+`;
+
+export const ADD_TO_CART = `
+  mutation AddToCart($cartId: String!, $cartItems: [CartItemInput!]!) {
+    addProductsToCart(cartId: $cartId, cartItems: $cartItems) {
+      cart {
+        id
+        items { id uid quantity product { sku name } prices { price { value currency } row_total { value currency } } }
+        prices { grand_total { value currency } subtotal_excluding_tax { value currency } }
+      }
+      user_errors { code message }
+    }
+  }
+`;
+
+export const REMOVE_FROM_CART = `
+  mutation RemoveFromCart($cartId: String!, $cartItemUid: ID!) {
+    removeItemFromCart(input: { cart_id: $cartId, cart_item_uid: $cartItemUid }) {
+      cart {
+        id
+        items { id uid quantity product { sku name } prices { price { value currency } row_total { value currency } } }
+        prices { grand_total { value currency } subtotal_excluding_tax { value currency } }
+      }
+    }
+  }
+`;
+
+export const UPDATE_CART_ITEMS = `
+  mutation UpdateCartItems($cartId: String!, $cartItems: [CartItemUpdateInput!]!) {
+    updateCartItems(input: { cart_id: $cartId, cart_items: $cartItems }) {
+      cart {
+        id
+        items { id uid quantity product { sku name } prices { price { value currency } row_total { value currency } } }
+        prices { grand_total { value currency } subtotal_excluding_tax { value currency } }
+      }
+    }
+  }
+`;
+
+export const APPLY_COUPON = `
+  mutation ApplyCoupon($cartId: String!, $couponCode: String!) {
+    applyCouponToCart(input: { cart_id: $cartId, coupon_code: $couponCode }) {
+      cart {
+        id
+        prices { grand_total { value currency } subtotal_excluding_tax { value currency } }
+      }
+    }
+  }
+`;
+
+export const REMOVE_COUPON = `
+  mutation RemoveCoupon($cartId: String!) {
+    removeCouponFromCart(input: { cart_id: $cartId }) {
+      cart {
+        id
+        prices { grand_total { value currency } subtotal_excluding_tax { value currency } }
+      }
+    }
+  }
+`;
+
+export const GET_CUSTOMER = `
+  query GetCustomer {
+    customer {
+      id
+      email
+      firstname
+      lastname
+      addresses {
+        id
+        firstname lastname company
+        street city
+        region { region region_code }
+        postcode
+        country_code
+        telephone
+        default_shipping
+        default_billing
+      }
+    }
+  }
+`;
+
+export const GET_CUSTOMER_ORDERS = `
+  query GetCustomerOrders($pageSize: Int, $currentPage: Int) {
+    customer {
+      orders(pageSize: $pageSize, currentPage: $currentPage) {
+        items {
+          id order_number order_date status
+          total {
+            grand_total { value currency }
+            subtotal { value currency }
+            total_tax { value currency }
+            total_shipping { value currency }
+          }
+          items {
+            id product_name product_sku
+            quantity_ordered
+            product_sale_price { value currency }
+          }
+          shipping_address {
+            firstname lastname street city
+            region postcode country_code telephone
+          }
+          billing_address {
+            firstname lastname street city
+            region postcode country_code telephone
+          }
+        }
+        total_count
+      }
+    }
+  }
+`;