CommerceAdapter

interface CommerceAdapter {
  name: string
  capabilities: AdapterDomain[]

  // Catalog
  getProduct(params: GetProductParams): Promise<Product>
  getProducts(params: SearchParams): Promise<PaginatedResult<Product>>
  getCategories(params?: GetCategoriesParams): Promise<Category[]>

  // Cart
  createCart(): Promise<Cart>
  getCart(cartId: string): Promise<Cart>
  addToCart(cartId: string, item: AddToCartInput): Promise<Cart>
  updateCartItem(cartId: string, itemId: string, quantity: number): Promise<Cart>
  removeFromCart(cartId: string, itemId: string): Promise<Cart>
  applyCoupon(cartId: string, code: string): Promise<Cart>
  removeCoupon(cartId: string): Promise<Cart>

  // Checkout, Orders, Customers, Store, etc.
  // ... (see individual sections below)
}

interface CatalogAdapter {
  /** Fetch a single product by ID or slug */
  getProduct(params: GetProductParams): Promise<Product>
  /** Search/list products with filters and pagination */
  getProducts(params: SearchParams): Promise<PaginatedResult<Product>>
  /** Fetch category tree */
  getCategories(params?: GetCategoriesParams): Promise<Category[]>
}

interface GetProductParams {
  id?: string
  slug?: string
}

interface CartAdapter {
  /** Create a new empty cart */
  createCart(): Promise<Cart>
  /** Get an existing cart by ID */
  getCart(cartId: string): Promise<Cart>
  /** Add an item to the cart */
  addToCart(cartId: string, item: AddToCartInput): Promise<Cart>
  /** Update cart item quantity */
  updateCartItem(cartId: string, itemId: string, quantity: number): Promise<Cart>
  /** Remove an item from the cart */
  removeFromCart(cartId: string, itemId: string): Promise<Cart>
  /** Apply a coupon code to the cart */
  applyCoupon(cartId: string, code: string): Promise<Cart>
  /** Remove a coupon from the cart */
  removeCoupon(cartId: string): Promise<Cart>
}

interface AddToCartInput {
  productId: string
  variantId?: string
  quantity: number
}

interface CheckoutAdapter {
  /** List available shipping methods for a cart */
  getShippingMethods(cartId: string): Promise<ShippingMethod[]>
  /** Set the shipping address */
  setShippingAddress(cartId: string, address: Omit<Address, 'id' | 'isDefault'>): Promise<Cart>
  /** Set the billing address */
  setBillingAddress(cartId: string, address: Omit<Address, 'id' | 'isDefault'>): Promise<Cart>
  /** Select a shipping method */
  setShippingMethod(cartId: string, methodId: string): Promise<Cart>
  /** List available payment methods */
  getPaymentMethods(cartId: string): Promise<PaymentMethod[]>
  /** Select a payment method */
  setPaymentMethod(cartId: string, methodId: string): Promise<Cart>
  /** Place the order (finalize checkout) */
  placeOrder(cartId: string): Promise<Order>
}

interface CustomerAdapter {
  /** Authenticate a customer */
  login(email: string, password: string): Promise<Customer>
  /** Register a new customer */
  register(input: RegisterInput): Promise<Customer>
  /** Get the currently authenticated customer */
  getCustomer(): Promise<Customer>
  /** Update customer profile */
  updateCustomer(input: UpdateCustomerInput): Promise<Customer>
  /** Logout the current customer */
  logout(): Promise<void>
  /** Send a password reset email/OTP */
  forgotPassword(email: string): Promise<void>
  /** Reset password using a token/OTP */
  resetPassword(token: string, newPassword: string): Promise<void>
  /** Get all saved addresses */
  getAddresses(): Promise<Address[]>
  /** Add a new address */
  addAddress(address: Omit<Address, 'id'>): Promise<Address>
  /** Update an existing address */
  updateAddress(addressId: string, address: Partial<Omit<Address, 'id'>>): Promise<Address>
  /** Delete an address */
  deleteAddress(addressId: string): Promise<void>
}

interface OrderAdapter {
  /** Create a new order from structured input */
  createOrder(input: CreateOrderInput): Promise<Order>
  /** Get a single order by ID */
  getOrder(orderId: string): Promise<Order>
  /** Get paginated list of orders */
  getCustomerOrders(params?: PaginationParams): Promise<PaginatedResult<Order>>
  /** Get all available order statuses */
  getOrderStatuses(): Promise<OrderStatusInfo[]>
  /** Update an order's status */
  updateOrderStatus(orderId: string, input: UpdateOrderStatusInput): Promise<void>
  /** Cancel an order */
  cancelOrder(orderId: string, note?: string): Promise<void>
  /** Duplicate an existing order (reorder) */
  duplicateOrder(orderId: string): Promise<Order>
  /** Get order status change history */
  getOrderHistory(orderId: string): Promise<OrderHistoryEntry[]>
}

interface StoreAdapter {
  /** Get store information (name, logo, currencies, locales) */
  getStoreInfo(): Promise<StoreInfo>
}

interface WishlistAdapter {
  /** Get the authenticated customer's wishlist */
  getWishlist(): Promise<Wishlist>
  /** Add a product to the wishlist */
  addToWishlist(productId: string, variantId?: string): Promise<Wishlist>
  /** Remove an item from the wishlist */
  removeFromWishlist(itemId: string): Promise<Wishlist>
}

interface ReviewAdapter {
  /** Get paginated reviews for a product */
  getProductReviews(productId: string, params?: PaginationParams): Promise<PaginatedResult<Review>>
  /** Get review summary (average rating, star distribution) */
  getReviewSummary(productId: string): Promise<ReviewSummary>
  /** Submit a new review */
  submitReview(input: ReviewInput): Promise<Review>
}

interface ReviewSummary {
  productId: string
  averageRating: number
  totalCount: number
  /** Counts for [1★, 2★, 3★, 4★, 5★] */
  distribution: [number, number, number, number, number]
}

interface PromotionAdapter {
  /** Get all currently active promotions */
  getActivePromotions(): Promise<Promotion[]>
  /** Validate a coupon code and return coupon details */
  validateCoupon(code: string): Promise<Coupon | null>
}

interface ReturnAdapter {
  /** Create a return request for an order */
  createReturn(input: CreateReturnInput): Promise<ReturnRequest>
  /** Get paginated list of return requests */
  getReturns(params?: PaginationParams): Promise<PaginatedResult<ReturnRequest>>
  /** Get a single return request by ID */
  getReturn(returnId: string): Promise<ReturnRequest>
  /** Get all returns for a specific order */
  getOrderReturns(orderId: string): Promise<ReturnRequest[]>
  /** Cancel a return request (only if status is 'requested') */
  cancelReturn(returnId: string): Promise<ReturnRequest>
}

interface BrandAdapter {
  /** Get all product brands */
  getBrands(): Promise<Brand[]>
}

interface CountryAdapter {
  /** Get all available countries */
  getCountries(): Promise<Country[]>
}

interface LocationAdapter {
  /** Get all store locations */
  getLocations(): Promise<StoreLocation[]>
  /** Get a single location by ID */
  getLocation(locationId: string): Promise<StoreLocation>
}

type AdapterDomain =
  | 'catalog' | 'cart' | 'checkout' | 'orders' | 'customers'
  | 'store' | 'brands' | 'countries' | 'wishlist' | 'reviews'
  | 'promotions' | 'returns' | 'wholesale' | 'auctions'
  | 'rentals' | 'gift-cards' | 'locations'