@thorprovider/adapters 3.0.2

package/src/providers/shopify/index.ts

@@ -0,0 +1,444 @@
+/**
+ * @thorprovider/adapters — Shopify Provider
+ * Implements CommerceProvider for Shopify Storefront API (GraphQL)
+ *
+ * Uses @shopify/storefront-api-client for type-safe GraphQL operations.
+ * Authentication via public/private access tokens (legacy Storefront tokens).
+ */
+
+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 { SHOPIFY_CAPABILITIES } from '../../types/capabilities.types';
+import { createLogger } from '../../core/logger';
+import { ProviderAPIError, ResourceNotFoundError } from '../../core/errors';
+import { transformProduct, transformCart, transformCollection, transformCustomer, transformOrder } from './transforms';
+import {
+  GET_PRODUCT_BY_HANDLE,
+  GET_PRODUCTS,
+  GET_PRODUCT_RECOMMENDATIONS,
+  GET_COLLECTION_BY_HANDLE,
+  GET_COLLECTIONS,
+  GET_COLLECTION_PRODUCTS,
+  GET_CART,
+  GET_CUSTOMER,
+} from './queries';
+import {
+  CART_CREATE,
+  CART_LINES_ADD,
+  CART_LINES_UPDATE,
+  CART_LINES_REMOVE,
+  CART_DISCOUNT_CODES_UPDATE,
+} from './mutations';
+
+/**
+ * Shopify provider configuration
+ */
+export interface ShopifyProviderConfig extends ProviderConfig {
+  /** Store domain (e.g., 'your-store.myshopify.com') */
+  storeDomain: string;
+  /** Public Storefront API access token */
+  publicAccessToken: string;
+  /** Private Storefront API access token (server-side only) */
+  privateAccessToken?: string;
+  /** API version (default: '2026-04') */
+  apiVersion?: string;
+}
+
+/**
+ * Shopify commerce provider
+ *
+ * Implements CommerceProvider for Shopify Storefront API.
+ * Uses raw fetch + GraphQL queries (no SDK dependency to stay L2-pure).
+ */
+export class ShopifyProvider implements CommerceProvider {
+  readonly name = 'shopify';
+  readonly version = '1.0.0';
+  readonly capabilities: BackendCapabilities = SHOPIFY_CAPABILITIES;
+
+  private logger: ReturnType<typeof createLogger>;
+  private storeDomain: string;
+  private apiVersion: string;
+  private endpoint: string;
+  private headers: Record<string, string>;
+
+  constructor(config: ShopifyProviderConfig) {
+    this.logger = createLogger('ShopifyProvider', config.debug);
+    this.storeDomain = config.storeDomain.replace(/^https?:\/\//, '').replace(/\/$/, '');
+    this.apiVersion = config.apiVersion ?? '2026-04';
+    this.endpoint = `https://${this.storeDomain}/api/${this.apiVersion}/graphql.json`;
+
+    this.headers = {
+      'Content-Type': 'application/json',
+      ...(config.privateAccessToken
+        ? { 'Shopify-Storefront-Private-Token': config.privateAccessToken }
+        : { 'X-Shopify-Storefront-Access-Token': config.publicAccessToken }),
+    };
+
+    this.logger.info('Initializing Shopify Provider', {
+      storeDomain: this.storeDomain,
+      apiVersion: this.apiVersion,
+      authType: config.privateAccessToken ? 'private' : 'public',
+    });
+  }
+
+  // ============================================
+  // GraphQL Client
+  // ============================================
+
+  private async query<T = any>(gql: string, variables?: Record<string, any>): Promise<T> {
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: this.headers,
+      body: JSON.stringify({ query: gql, variables }),
+    });
+
+    if (!response.ok) {
+      throw new ProviderAPIError(
+        `Shopify API error: ${response.status} ${response.statusText}`,
+        'SHOPIFY_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(`Shopify GraphQL error: ${message}`, 'SHOPIFY_GRAPHQL_ERROR');
+    }
+
+    return json.data as T;
+  }
+
+  // ============================================
+  // Product Operations
+  // ============================================
+
+  async getProduct(handle: string): Promise<Product | undefined> {
+    const data = await this.query<{ product: any }>(GET_PRODUCT_BY_HANDLE, { handle });
+    return data.product ? transformProduct(data.product) : undefined;
+  }
+
+  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
+    const first = options?.first ?? 20;
+    const sortKeyMap: Record<string, string> = {
+      'title-asc': 'TITLE',
+      'title-desc': 'TITLE',
+      'price-asc': 'PRICE',
+      'price-desc': 'PRICE',
+      'best-selling': 'BEST_SELLING',
+      'created-desc': 'CREATED_AT',
+      'relevance': 'RELEVANCE',
+    };
+    const sortKey = options?.sortKey ? (sortKeyMap[options.sortKey] ?? 'RELEVANCE') : 'RELEVANCE';
+    const reverse = options?.sortKey?.endsWith('-desc') ?? false;
+
+    const data = await this.query<{ products: { edges: Array<{ node: any }> } }>(GET_PRODUCTS, {
+      first,
+      query: options?.query,
+      sortKey,
+      reverse,
+    });
+
+    return data.products.edges.map((edge) => transformProduct(edge.node));
+  }
+
+  async getProductRecommendations(productId: string): Promise<Product[]> {
+    const data = await this.query<{ productRecommendations: any[] }>(GET_PRODUCT_RECOMMENDATIONS, {
+      productId,
+    });
+    return (data.productRecommendations ?? []).map(transformProduct);
+  }
+
+  // ============================================
+  // Collection Operations
+  // ============================================
+
+  async getCollection(handle: string): Promise<Collection | undefined> {
+    const data = await this.query<{ collection: any }>(GET_COLLECTION_BY_HANDLE, { handle });
+    return data.collection ? transformCollection(data.collection) : undefined;
+  }
+
+  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
+    const data = await this.query<{ collections: { edges: Array<{ node: any }> } }>(GET_COLLECTIONS, {
+      first: options?.limit ?? 50,
+    });
+    return data.collections.edges.map((edge) => transformCollection(edge.node));
+  }
+
+  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    const data = await this.query<{ collection: { products: { edges: Array<{ node: any }> } } }>(
+      GET_COLLECTION_PRODUCTS,
+      {
+        handle,
+        first: options?.first ?? 20,
+        sortKey: options?.sortKey === 'price-asc' || options?.sortKey === 'price-desc' ? 'PRICE' : 'BEST_SELLING',
+        reverse: options?.sortKey?.endsWith('-desc') ?? false,
+      },
+    );
+    return (data.collection?.products?.edges ?? []).map((edge) => transformProduct(edge.node));
+  }
+
+  // ============================================
+  // Category Operations (Shopify does not have native categories)
+  // ============================================
+
+  async getCategory(): Promise<ProductCategory | undefined> {
+    this.logger.warn('Shopify does not support native categories. Use collections instead.');
+    return undefined;
+  }
+
+  async getCategories(): Promise<ProductCategory[]> {
+    return [];
+  }
+
+  async getCategoryProducts(): Promise<Product[]> {
+    return [];
+  }
+
+  // ============================================
+  // Cart Operations
+  // ============================================
+
+  async createCart(): Promise<Cart> {
+    const data = await this.query<{ cartCreate: { cart: any; userErrors: any[] } }>(CART_CREATE, {
+      input: {},
+    });
+
+    if (data.cartCreate.userErrors?.length) {
+      throw new ProviderAPIError(
+        `Cart creation failed: ${data.cartCreate.userErrors.map((e: any) => e.message).join('; ')}`,
+        'SHOPIFY_CART_ERROR',
+      );
+    }
+
+    return transformCart(data.cartCreate.cart);
+  }
+
+  async getCart(cartId: string): Promise<Cart | undefined> {
+    const data = await this.query<{ cart: any }>(GET_CART, { cartId });
+    return data.cart ? transformCart(data.cart) : undefined;
+  }
+
+  async addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart> {
+    const data = await this.query<{ cartLinesAdd: { cart: any; userErrors: any[] } }>(CART_LINES_ADD, {
+      cartId,
+      lines: lines.map((l) => ({ merchandiseId: l.merchandiseId, quantity: l.quantity })),
+    });
+
+    if (data.cartLinesAdd.userErrors?.length) {
+      throw new ProviderAPIError(
+        `Add to cart failed: ${data.cartLinesAdd.userErrors.map((e: any) => e.message).join('; ')}`,
+        'SHOPIFY_CART_ERROR',
+      );
+    }
+
+    return transformCart(data.cartLinesAdd.cart);
+  }
+
+  async removeFromCart(cartId: string, lineIds: string[]): Promise<Cart> {
+    const data = await this.query<{ cartLinesRemove: { cart: any; userErrors: any[] } }>(CART_LINES_REMOVE, {
+      cartId,
+      lineIds,
+    });
+
+    if (data.cartLinesRemove.userErrors?.length) {
+      throw new ProviderAPIError(
+        `Remove from cart failed: ${data.cartLinesRemove.userErrors.map((e: any) => e.message).join('; ')}`,
+        'SHOPIFY_CART_ERROR',
+      );
+    }
+
+    return transformCart(data.cartLinesRemove.cart);
+  }
+
+  async updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart> {
+    const data = await this.query<{ cartLinesUpdate: { cart: any; userErrors: any[] } }>(CART_LINES_UPDATE, {
+      cartId,
+      lines: lines.map((l) => ({ id: l.id, quantity: l.quantity })),
+    });
+
+    if (data.cartLinesUpdate.userErrors?.length) {
+      throw new ProviderAPIError(
+        `Update cart failed: ${data.cartLinesUpdate.userErrors.map((e: any) => e.message).join('; ')}`,
+        'SHOPIFY_CART_ERROR',
+      );
+    }
+
+    return transformCart(data.cartLinesUpdate.cart);
+  }
+
+  // ============================================
+  // Checkout Operations
+  // ============================================
+
+  async completeCheckout(_cartId: string): Promise<Order> {
+    // Shopify checkout is hosted — redirect to cart.checkoutUrl
+    // This method cannot programmatically complete checkout
+    throw new ProviderAPIError(
+      'Shopify uses hosted checkout. Redirect the buyer to cart.checkoutUrl instead of calling completeCheckout().',
+      'SHOPIFY_HOSTED_CHECKOUT',
+    );
+  }
+
+  async getShippingMethods(_cartId: string): Promise<ShippingMethod[]> {
+    // Shopify handles shipping selection in hosted checkout
+    return [];
+  }
+
+  async getRegionCountries(): Promise<import('@thorprovider/types').Country[]> {
+    return [];
+  }
+
+  async addShippingMethod(_cartId: string, _methodId: string): Promise<Cart> {
+    throw new ProviderAPIError(
+      'Shopify handles shipping selection in hosted checkout.',
+      'SHOPIFY_HOSTED_CHECKOUT',
+    );
+  }
+
+  async initiatePaymentSession(_cartId: string, _providerId: string): Promise<void> {
+    throw new ProviderAPIError(
+      'Shopify handles payment in hosted checkout.',
+      'SHOPIFY_HOSTED_CHECKOUT',
+    );
+  }
+
+  async applyDiscountCode(cartId: string, code: string): Promise<Cart> {
+    const currentCart = await this.getCart(cartId);
+    const existingCodes: string[] = []; // Shopify replaces all codes
+    existingCodes.push(code);
+
+    const data = await this.query<{ cartDiscountCodesUpdate: { cart: any; userErrors: any[] } }>(
+      CART_DISCOUNT_CODES_UPDATE,
+      { cartId, discountCodes: existingCodes },
+    );
+
+    if (data.cartDiscountCodesUpdate.userErrors?.length) {
+      throw new ProviderAPIError(
+        `Discount code failed: ${data.cartDiscountCodesUpdate.userErrors.map((e: any) => e.message).join('; ')}`,
+        'SHOPIFY_DISCOUNT_ERROR',
+      );
+    }
+
+    return transformCart(data.cartDiscountCodesUpdate.cart);
+  }
+
+  async removeDiscountCode(cartId: string, _code: string): Promise<Cart> {
+    const data = await this.query<{ cartDiscountCodesUpdate: { cart: any; userErrors: any[] } }>(
+      CART_DISCOUNT_CODES_UPDATE,
+      { cartId, discountCodes: [] },
+    );
+
+    return transformCart(data.cartDiscountCodesUpdate.cart);
+  }
+
+  // ============================================
+  // Customer Operations
+  // ============================================
+
+  async getOrders(options: GetOrdersOptions): Promise<Order[]> {
+    this.logger.warn('Shopify orders require Customer Account API (planned upgrade path).');
+    return [];
+  }
+
+  // ============================================
+  // Payment Operations
+  // ============================================
+
+  async getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
+    // Shopify payment selection happens in hosted checkout
+    return [];
+  }
+
+  // ============================================
+  // Inventory Operations (not available via Storefront API)
+  // ============================================
+
+  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 (not available via Storefront API)
+  // ============================================
+
+  async cancelOrder(_orderId: string): Promise<Order> {
+    throw new ProviderAPIError(
+      'Order cancellation requires Shopify Admin API (not available in Storefront API).',
+      'SHOPIFY_ADMIN_REQUIRED',
+    );
+  }
+
+  async createFulfillment(_orderId: string): Promise<void> {
+    throw new ProviderAPIError(
+      'Fulfillment requires Shopify Admin API.',
+      'SHOPIFY_ADMIN_REQUIRED',
+    );
+  }
+
+  async createRefund(_orderId: string): Promise<void> {
+    throw new ProviderAPIError(
+      'Refunds require Shopify Admin API.',
+      'SHOPIFY_ADMIN_REQUIRED',
+    );
+  }
+
+  async getAdminOrders(): Promise<{ orders: Order[]; count: number }> {
+    return { orders: [], count: 0 };
+  }
+
+  // ============================================
+  // Storefront / Multi-Tenant
+  // ============================================
+
+  async getStorefrontContext(): Promise<StorefrontContext> {
+    return {
+      id: this.storeDomain,
+      name: this.storeDomain,
+      platformType: 'shopify',
+      requiresProductScoping: false,
+      currencyCode: 'USD',
+    };
+  }
+
+  isStorefrontRequired(): boolean {
+    return false;
+  }
+}

package/src/providers/shopify/mutations.ts

@@ -0,0 +1,102 @@
+/**
+ * @thorprovider/adapters — Shopify Provider
+ * GraphQL mutation definitions for Storefront API
+ */
+
+import { CART_FRAGMENT } from './queries';
+
+export const CART_CREATE = `
+  mutation CartCreate($input: CartInput!) {
+    cartCreate(input: $input) {
+      cart {
+        ...CartFields
+      }
+      userErrors {
+        field
+        message
+        code
+      }
+    }
+  }
+  ${CART_FRAGMENT}
+`;
+
+export const CART_LINES_ADD = `
+  mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+    cartLinesAdd(cartId: $cartId, lines: $lines) {
+      cart {
+        ...CartFields
+      }
+      userErrors {
+        field
+        message
+        code
+      }
+    }
+  }
+  ${CART_FRAGMENT}
+`;
+
+export const CART_LINES_UPDATE = `
+  mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+    cartLinesUpdate(cartId: $cartId, lines: $lines) {
+      cart {
+        ...CartFields
+      }
+      userErrors {
+        field
+        message
+        code
+      }
+    }
+  }
+  ${CART_FRAGMENT}
+`;
+
+export const CART_LINES_REMOVE = `
+  mutation CartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
+    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+      cart {
+        ...CartFields
+      }
+      userErrors {
+        field
+        message
+        code
+      }
+    }
+  }
+  ${CART_FRAGMENT}
+`;
+
+export const CART_DISCOUNT_CODES_UPDATE = `
+  mutation CartDiscountCodesUpdate($cartId: ID!, $discountCodes: [String!]!) {
+    cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
+      cart {
+        ...CartFields
+      }
+      userErrors {
+        field
+        message
+        code
+      }
+    }
+  }
+  ${CART_FRAGMENT}
+`;
+
+export const CUSTOMER_ACCESS_TOKEN_CREATE = `
+  mutation CustomerAccessTokenCreate($input: CustomerAccessTokenCreateInput!) {
+    customerAccessTokenCreate(input: $input) {
+      customerAccessToken {
+        accessToken
+        expiresAt
+      }
+      customerUserErrors {
+        field
+        message
+        code
+      }
+    }
+  }
+`;