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

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

@@ -0,0 +1,30 @@
+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 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,49 @@
+**Overview**
+
+As a Magento developer, I need to manipulate the shopping cart via GraphQL so that I can build basic ecommerce experiences for shoppers on the front-end using only GraphQL.
+
+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)
+
+
+**Open questions:**
+
+- Do we want to implement server-side asynchronous mutations by default?
+
+**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,48 @@
+type Mutation {
+    addBundleProductsToCart(input: AddBundleProductsToCartInput): AddBundleProductsToCartOutput
+}
+
+input AddBundleProductsToCartInput {
+    cart_id: String!
+    cartItems: [BundleProductCartItemInput!]!
+}
+
+input BundleProductCartItemInput {
+    sku: String!
+    quantity: Float!
+    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!
+}
+

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

@@ -0,0 +1,37 @@
+type Mutation {
+    addConfigurableProductsToCart(input: AddConfigurableProductsToCartInput): AddConfigurableProductsToCartOutput
+}
+
+input AddConfigurableProductsToCartInput {
+    cart_id: String!
+    cartItems: [ConfigurableProductCartItemInput!]!
+}
+
+input ConfigurableProductCartItemInput {
+    sku: String!
+    quantity: Float!
+    configurable_options:[ConfigurableOptionInput!]!
+    customizable_options:[CustomizableOptionInput!]
+}
+
+input ConfigurableOptionInput {
+    id: Int!
+    value: Int!
+}
+
+type AddConfigurableProductsToCartOutput {
+    cart: Cart!
+}
+
+type ConfigurableCartItem implements CartItemInterface {
+    customizable_options: [SelectedCustomizableOption]!
+    configurable_options: [SelectedConfigurableOption!]!
+}
+
+type SelectedConfigurableOption {
+    id: Int!
+    option_label: String!
+    value_id: Int!
+    value_label: String!
+}
+

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

@@ -0,0 +1,34 @@
+type Mutation {
+    addDownloadableProductsToCart(input: AddDownloadableProductsToCartInput): AddDownloadableProductsToCartOutput
+}
+
+input AddDownloadableProductsToCartInput {
+    cart_id: String!
+    cartItems: [DownloadableProductCartItemInput!]!
+}
+
+input DownloadableProductCartItemInput {
+    sku: String!
+    quantity: Int!
+    downloadable_links: [DownloadableLinksInput!]
+    customizable_options:[CustomizableOptionInput!]
+}
+
+input DownloadableLinksInput {
+    id: [Int!]!
+}
+
+type AddDownloadableProductsToCartOutput {
+    cart: Cart!
+}
+
+type DownloadableCartItem implements CartItemInterface {
+    links_label: String!
+    links: [DownloadableCartItemLink!]!
+    configurable_options: [SelectedConfigurableOption!]!
+}
+
+type DownloadableCartItemLink {
+    id: Int!
+    label: String!
+}

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

@@ -0,0 +1,30 @@
+type Mutation {
+    addGiftCardProductsToCart(input: AddGiftCardProductsToCartInput): AddGiftCardProductsToCartOutput
+}
+
+input AddGiftCardProductsToCartInput {
+    cart_id: String!
+    cartItems: [GiftCardProductCartItemInput!]!
+}
+
+input GiftCardProductCartItemInput {
+    sku: String!
+    quantity: Float!
+    sender_name: String!
+    recepient_name: String!
+    amount: Money!
+    message: String
+    customizable_options:[CustomizableOptionInput!]
+}
+
+type AddGiftCardProductsToCartOutput {
+    cart: Cart!
+}
+
+type GiftCardCartItem implements CartItemInterface {
+    sender_name: String!
+    recepient_name: String!
+    amount: Money!
+    message: String
+    customizable_options: [SelectedCustomizableOption]!
+}

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

@@ -0,0 +1,18 @@
+type Mutation {
+    addGroupedProductsToCart(input: AddGroupedProductsToCartInput): AddGroupedProductsToCartOutput
+}
+
+input AddGroupedProductsToCartInput {
+    cart_id: String!
+    cartItems: [GroupedProductCartItemInput!]!
+}
+
+input GroupedProductCartItemInput {
+    sku: String!
+    quantity: Float!
+    # the difference from simple products is that grouped products do not support customizable options
+}
+
+type AddGroupedProductsToCartOutput {
+    cart: Cart!
+}

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

@@ -0,0 +1,65 @@
+type Mutation {
+    addSimpleProductsToCart(input: AddSimpleProductsToCartInput): AddSimpleProductsToCartOutput
+}
+
+input AddSimpleProductsToCartInput {
+    cart_id: String!
+    cartItems: [SimpleProductCartItemInput!]!
+}
+
+input SimpleProductCartItemInput {
+    sku: String!
+    quantity: Float!
+    customizable_options:[CustomizableOptionInput!]
+}
+
+input CustomizableOptionInput {
+    id: Int!
+    value: String!
+}
+
+type AddSimpleProductsToCartOutput {
+    cart: Cart!
+}
+
+type Cart {
+    id: String
+    items: [CartItemInterface]
+}
+
+interface CartItemInterface @typeResolver(class: "Magento\\CatalogCheckoutGraphQl\\Model\\CartItemInterfaceTypeResolverComposite") {
+    id: Int!
+    qty: Float!
+    product: ProductInterface!
+    prices: CartItemPrices!
+}
+
+type CartItemPrices {
+    price: Money!
+    subtotal: Money!
+}
+
+type SimpleCartItem implements CartItemInterface {
+    customizable_options: [SelectedCustomizableOption]
+}
+
+type SelectedCustomizableOption {
+    id: Int!
+    label: String!
+    type: String!
+    values: [SelectedCustomizableOptionValue!]!
+    sort_order: Int!
+}
+
+type SelectedCustomizableOptionValue {
+    id: Int
+    label: String!
+    price: CartItemSelectedOptionValuePrice!
+    sort_order: Int!
+}
+
+type CartItemSelectedOptionValuePrice {
+    value: Float!
+    units: String!
+    type: PriceTypeEnum!
+}

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

@@ -0,0 +1,24 @@
+type Mutation {
+    # for now this mutation is identical to addSimpleProductsToCart and exists as a syntax sugar. Also it allows product type based customizations
+    addVirtualProductsToCart(input: AddVirtualProductsToCartInput): AddVirtualProductsToCartOutput
+}
+
+input AddVirtualProductsToCartInput {
+    cart_id: String!
+    cartItems: [VirtualProductCartItemInput!]!
+}
+
+input VirtualProductCartItemInput {
+    sku: String!
+    quantity: Float!
+    customizable_options:[CustomizableOptionInput!]
+}
+
+type AddVirtualProductsToCartOutput {
+    cart: Cart!
+}
+
+# Custom cart item type can be used to customize rendering when there are no physical producs available, e.g. skip shipping
+type VirtualCartItem implements CartItemInterface {
+    customizable_options: [SelectedCustomizableOption]
+}