Multi-device support for customer cart in GraphQL

Author: paliarush

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

@@ -1,5 +1,7 @@
 **Overview**
 
+:warning: Current proposal is deprecated in favor of [add-items-to-cart-single-mutation.md](add-items-to-cart-single-mutation.md)
+
 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.
@@ -31,13 +33,13 @@ GraphQL needs to provide sufficient mutations (ways to create/update/delete data
 
 **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)
+- [AddSimpleProductToCart](add-items-to-cart/AddSimpleProductToCart.graphqls)
+- [AddBundleProductToCart](add-items-to-cart/AddBundleProductToCart.graphqls)
+- [AddConfigurableProductToCart](add-items-to-cart/AddConfigurableProductToCart.graphqls)
+- [AddDownloadableProductToCart](add-items-to-cart/AddDownloadableProductToCart.graphqls)
+- [AddGiftCardProductToCart](add-items-to-cart/AddGiftCardProductToCart.graphqls)
+- [AddGroupedProductToCart](add-items-to-cart/AddGroupedProductToCart.graphqls)
+- [AddVirtualProductToCart](add-items-to-cart/AddVirtualProductToCart.graphqls)
 
 
 **My Account area impacted:** 

design-documents/graph-ql/coverage/shared-cart.md

@@ -0,0 +1,30 @@
+ ## Problem statement   
+ 
+Registered customer should be able to work with the same shopping cart using multiple devices. For example, add products to cart using a laptop and complete checkout using a smartphone.
+
+
+ ## Proposed solution
+
+To achieve desired behavior there should be a way to retrieve active customer cart ID from the server. Based on the assumption that there could be only one active cart per customer at any given moment this can be done as follows:
+```graphql
+getMyCartId(): String!
+```
+This operation will only work for registered customers (valid customer token must be provided in headers).
+
+ ### Scenario
+ 
+ In the following scenario a logged in user adds a product to the cart. After logging in to his account from the smartphone the cart still contains added product (actual GraphQL queries are replaced with pseudocode for simplicity): 
+ 
+| Step | Device     | Operation                                                                     | Headers        | Response                                          |
+|------|------------|-------------------------------------------------------------------------------|----------------|---------------------------------------------------|
+| 1    | Laptop     | getMyCartId()                                                                 | customer-token | 123e4567              |
+| 2    | Laptop     | addProductsToCart("123e4567", [{"sku": "productA", "quantity": 2}]) {cart_id} | customer-token | 123e4567              |
+| 3    | Smartphone | getMyCartId()                                                                 | customer-token | 123e4567              |
+| 4    | Smartphone | getCart("123e4567") {cart_items {sku, quantity}}                              | customer-token | {cart_items: [{"sku": "productA", "quantity": 2]} |
+
+
+ ## Alternatives
+ 
+ - It is possible to make `cartId` optional argument and rely on `getCart {cart_id}` query for fetching customer cart ID. When used by customer, ID is not required. When used by guest - ID is required.
+    - guest still need to use `createEmptyCart` to obtain cart ID
+    - `optional` argument makes semantics less clear