[ongoing discussion] Draft for cart operations and other GraphQL improvements

design-documents/graph-ql/coverage/Cart.graphqls

@@ -0,0 +1,59 @@
+type Query {
+    cart(input: CartQueryInput): CartQueryOutput
+}
+
+input CartQueryInput {
+    cart_id: String!
+}
+
+type CartQueryOutput {
+    cart: Cart
+}
+
+type Cart {
+    id: String!
+
+    line_items_count: Int!
+    items_quantity: Float!
+
+    selected_payment_method: CheckoutPaymentMethod
+    available_payment_methods: [CheckoutPaymentMethod]!
+
+    customer: CheckoutCustomer
+    customer_notes: String
+
+    gift_cards_amount_used: Money
+    applied_gift_cards: [CartGiftCard]
+
+    is_multishipping: Boolean!
+    is_virtual: Boolean!
+}
+
+type CheckoutCustomer {
+    is_guest: Boolean!
+    email: String!
+    prefix: String
+    first_name: String!
+    last_name: String!
+    middle_name: String
+    suffix: String
+    gender: GenderEnum
+    date_of_birth: String
+    vat_number: String # Do we need it at all on storefront? Do we need more details
+}
+
+enum GenderEnum {
+    MALE
+    FEMALE
+}
+
+type CheckoutPaymentMethod {
+    code: String!
+    label: String!
+    balance: Money
+    sort_order: Int
+}
+
+type CartGiftCard {
+    code: String!
+}

design-documents/graph-ql/coverage/CartAddressOperations.graphqls

@@ -0,0 +1,110 @@
+type Query {
+    setBillingAddressOnCart(input: SetBillingAddressOnCartInput): SetBillingAddressOnCartOutput
+    setShippingAddressesOnCart(input: SetShippingAddressesOnCartInput): SetShippingAddressesOnCartOutput
+    setShippingMethodsOnCart(input: SetShippingMethodsOnCartInput): SetShippingMethodsOnCartOutput
+}
+
+input SetShippingMethodsOnCartInput {
+    shipping_methods: [ShippingMethodForAddressInput!]!
+}
+
+input ShippingMethodForAddressInput {
+    cart_address_id: String!
+    shipping_method_code: String!
+}
+
+input SetBillingAddressOnCartInput {
+    customer_address_id: Int
+    address: CartAddressInput
+}
+
+input SetShippingAddressesOnCartInput {
+    customer_address_id: Int # Can be provided in one-page checkout and is required for multi-shipping checkout
+    address: CartAddressInput
+    cart_items: [CartItemQuantityInput!]
+}
+
+input CartItemQuantityInput {
+    cart_item_id: String!
+    quantity: Float!
+}
+
+input CartAddressInput {
+    firstname: String!
+    lastname: String!
+    company: String
+    street: [String!]!
+    city: String!
+    region: String
+    postcode: String
+    country_code: String!
+    telephone: String!
+    save_in_address_book: Boolean!
+}
+
+type SetShippingAddressesOnCartOutput {
+    cart: Cart!
+}
+
+type SetShippingMethodsOnCartOutput {
+    cart: Cart!
+}
+
+type SetBillingAddressOnCartOutput {
+    cart: Cart!
+}
+
+type Cart {
+    addresses: [CartAddress]!
+}
+
+type CartAddress {
+    firstname: String!
+    lastname: String!
+    company: String
+    street: [String!]!
+    city: String!
+    region: CartAddressRegion
+    postcode: String
+    country: CartAddressCountry!
+    telephone: String!
+    address_type: AdressTypeEnum!
+
+    selected_shipping_method: CheckoutShippingMethod
+    available_shipping_methods: [CheckoutShippingMethod]!
+
+    items_weight: Float
+    customer_notes: String
+    gift_cards_amount_used: Money
+    applied_gift_cards: [CartGiftCard]
+
+    cart_items: [CartItemQuantity]
+}
+
+type CartItemQuantity {
+    cart_item_id: String!
+    quantity: Float!
+}
+
+type CartAddressCountry {
+    code: String
+    label: String
+}
+
+type CartAddressRegion {
+    code: String
+    label: String
+}
+
+enum AdressTypeEnum {
+    SHIPPING
+    BILLING
+}
+
+type CheckoutShippingMethod {
+    code: String
+    label: String
+    free_shipping: Boolean!
+    error_message: String
+    # TODO: Add more complex structure for shipping rates
+}

design-documents/graph-ql/coverage/CartPrices.graphqls

@@ -0,0 +1,55 @@
+interface CartItemInterface {
+    prices: CartItemPrices
+}
+
+type Cart {
+    prices: CartPrices
+}
+
+type CartAddress {
+    prices: CartAddressPrices
+    # additional fields will be added later
+}
+
+interface CartPricesInterface {
+    grand_total: Money
+
+    # price display settings should be requested via store config query
+    subtotal_including_tax: Money
+    subtotal_excluding_tax: Money
+
+    subtotal_with_discount_excluding_tax: Money
+    discount_tax_compensation: Money #Should we have subtotal with discount including tax instead, is it different from grand_total?
+
+    applied_taxes: [CartTaxItem]! # Should include regular taxes and WEEE taxes
+    applied_discounts: [CartDiscountItem]!
+}
+
+type CartItemPrices implements CartPricesInterface {
+    price_including_tax: Money
+    price_excluding_tax: Money
+
+    custom_price: Money
+}
+
+type CartAddressPrices implements CartPricesInterface {
+
+    shipping_including_tax: Money
+    shipping_excluding_tax: Money
+
+    shipping_discount: Money # Do we need shipping_with_discount_including_tax?
+    shipping_discount_tax_compensation: Money
+}
+
+type CartPrices implements CartPricesInterface {
+}
+
+type CartTaxItem {
+    amount: Money!
+    label: String!
+}
+
+type CartDiscountItem {
+    amount: Money!
+    label: String!
+}

design-documents/graph-ql/coverage/CouponOperations.graphqls

@@ -0,0 +1,34 @@
+type Mutation {
+    applyCouponToCart(input: ApplyCouponToCartInput): ApplyCouponToCartOutput
+    removeCouponFromCart(input: RemoveCouponFromCartInput): RemoveCouponFromCartOutput
+}
+
+input ApplyCouponToCartInput {
+    cart_id: String!
+    coupon_code: String!
+}
+
+type ApplyCouponToCartOutput {
+    cart: Cart!
+}
+
+type Cart {
+    applied_coupon: AppliedCoupon
+}
+
+type CartAddress {
+    applied_coupon: AppliedCoupon
+}
+
+type AppliedCoupon {
+    # Wrapper allows for future extension of coupon info
+    code: String!
+}
+
+input RemoveCouponFromCartInput {
+    cart_id: String!
+}
+
+type RemoveCouponFromCartOutput {
+    cart: Cart
+}

design-documents/graph-ql/coverage/add-items-to-cart.md

@@ -0,0 +1,45 @@
+**Overview**
+
+As a Magento developer, I need to manipulate the shopping cart via GraphQL so that I can programmatically create orders on behalf of a shopper.
+
+GraphQL needs to provide sufficient mutations (ways to create/update/delete data) for a developer to build out the storefront checkout experience for a shopper.
+
+**Use cases:**
+- Both guest and registered shoppers can add new items to cart
+- Both guest and registered shoppers can update item qty in cart 
+- Both guest and registered shoppers can remove items from cart
+- Both guest and registered shoppers can update the configuration (for a configurable product) or quantity of a previously added configurable product in cart
+    - Edit Item link > Product page > Update configuration or qty > Update Cart 
+
+**Main decision points:**
+
+- Separate mutations for each product type while adding items to cart. Each operation will be supporting bulk use case
+- Uniform interface for guest vs customer
+- Separate mutations for each checkout step
+    - Create empty cart
+    - Add items to cart
+    - Set shipment method
+    - Set payment method
+    - Set addresses
+    - Same granularity for updates and removals
+- Possibility to combine mutations for checkout steps
+- Can create "order in one call" mutation in the future if needed
+- Hashed IDs for cart items
+- Single input object
+- Async nature of the flow must be supported on the client side (via AJAX calls)
+- Server-side asynchronous mutations can be supported in the future on framework level in a way similar to Async REST.
+
+**Proposed schema for adding items to cart:**
+
+- [AddSimpleProductToCart](AddSimpleProductToCart.graphqls)
+- [AddBundleProductToCart](AddBundleProductToCart.graphqls)
+- [AddConfigurableProductToCart](AddConfigurableProductToCart.graphqls)
+- [AddDownloadableProductToCart](AddDownloadableProductToCart.graphqls)
+- [AddGiftCardProductToCart](AddGiftCardProductToCart.graphqls)
+- [AddGroupedProductToCart](AddGroupedProductToCart.graphqls)
+- [AddVirtualProductToCart](AddVirtualProductToCart.graphqls)
+
+
+**My Account area impacted:** 
+- Cart
+- Minicart

design-documents/graph-ql/coverage/add-items-to-cart/AddBundleProductToCart.graphqls

@@ -0,0 +1,59 @@
+type Mutation {
+    addBundleProductsToCart(input: AddBundleProductsToCartInput): AddBundleProductsToCartOutput
+    updateBundleProductsInCart(input: UpdateBundleProductsInCartInput): UpdateBundleProductsInCartOutput
+}
+
+input UpdateBundleProductsInCartInput {
+    cart_id: String!
+    cartItems: [UpdateBundleProductCartItemInput!]!
+}
+
+input UpdateBundleProductCartItemInput {
+    details: UpdateCartItemDetailsInput!
+    bundle_options:[BundleOptionInput!]
+    customizable_options:[CustomizableOptionInput]
+}
+
+input AddBundleProductsToCartInput {
+    cart_id: String!
+    cartItems: [BundleProductCartItemInput!]!
+}
+
+input BundleProductCartItemInput {
+    details: CartItemDetailsInput!
+    bundle_options:[BundleOptionInput!]!
+    customizable_options:[CustomizableOptionInput!]
+}
+
+input BundleOptionInput {
+    id: Int!
+    quantity: Float!
+    value: [String!]!
+}
+
+type AddBundleProductsToCartOutput {
+    cart: Cart!
+}
+
+type BundleCartItem implements CartItemInterface {
+    customizable_options: [SelectedCustomizableOption]!
+    bundle_options: [SelectedBundleOption!]!
+}
+
+type SelectedBundleOption {
+    id: Int!
+    label: String!
+    type: String!
+    # No quantity here even though it is set on option level in the input
+    values: [SelectedBundleOptionValue!]!
+    sort_order: Int!
+}
+
+type SelectedBundleOptionValue {
+    id: Int!
+    label: String!
+    quantity: Float! # Quantity is displayed on option value level, while is set on option level
+    price: CartItemSelectedOptionValuePrice!
+    sort_order: Int!
+}
+