Add cart API methods

README.md

@@ -1,4 +1,5 @@
 # [Shopify](https://www.shopify.com) JavaScript Buy SDK
+
 ![Build](https://github.com/shopify/js-buy-sdk/actions/workflows/ci.yml/badge.svg)
 
 **Note**: For help with migrating from v0 of JS Buy SDK to v1 check out the
@@ -23,36 +24,53 @@ Each version of the JS Buy SDK uses a specific Storefront API version and the su
 - [Installation](#installation)
 - [Builds](#builds)
 - [Examples](#examples)
-  + [Initializing the Client](#initializing-the-client)
-  + [Fetching Products](#fetching-products)
-  + [Fetching Collections](#fetching-collections)
-  + [Creating a Checkout](#creating-a-checkout)
-  + [Updating Checkout Attributes](#updating-checkout-attributes)
-  + [Adding Line Items](#adding-line-items)
-  + [Updating Line Items](#updating-line-items)
-  + [Removing Line Items](#removing-line-items)
-  + [Fetching a Checkout](#fetching-a-checkout)
-  + [Adding a Discount](#adding-a-discount)
-  + [Removing a Discount](#removing-a-discount)
-  + [Updating a Shipping Address](#updating-a-shipping-address)
-  + [Completing a checkout](#completing-a-checkout)
+  - [Initializing the Client](#initializing-the-client)
+  - [Fetching Products](#fetching-products)
+  - [Fetching Collections](#fetching-collections)
+  - [Carts](#carts)
+    - [Creating a Cart](#creating-a-cart)
+    - [Fetching a Cart](#fetching-a-cart)
+    - [Updating Cart Attributes](#updating-cart-attributes)
+    - [Updating Buyer Identity](#updating-buyer-identity)
+    - [Updating Discount Codes](#updating-discount-codes)
+    - [Adding Cart Line Items](#adding-cart-line-items)
+    - [Removing Cart Line Items](#removing-cart-line-items)
+    - [Updating Cart Line Items](#updating-cart-line-items)
+    - [Updating Cart Notes](#updating-cart-notes)
+    - [Updating Cart Selected Delivery Options](#updating-cart-selected-delivery-options)
+    - [Redirecting to Checkout](#redirecting-to-checkout)
+  - [Checkouts](#checkouts)
+    - [Creating a Checkout](#creating-a-checkout)
+    - [Updating Checkout Attributes](#updating-checkout-attributes)
+    - [Adding Line Items](#adding-line-items)
+    - [Updating Line Items](#updating-line-items)
+    - [Removing Line Items](#removing-line-items)
+    - [Fetching a Checkout](#fetching-a-checkout)
+    - [Adding a Discount](#adding-a-discount)
+    - [Removing a Discount](#removing-a-discount)
+    - [Updating a Shipping Address](#updating-a-shipping-address)
+    - [Completing a checkout](#completing-a-checkout)
 - [Expanding the SDK](#expanding-the-sdk)
-  + [Initializing the Client](#initializing-the-client-1)
-  + [Fetching Products](#fetching-products-1)
+  - [Initializing the Client](#initializing-the-client-1)
+  - [Fetching Products](#fetching-products-1)
 - [Example Apps](#example-apps)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
 - [Code of Conduct](#code-of-conduct)
 - [License](#license)
 
 ## Installation
+
 **With Yarn:**
+
 ```bash
-$ yarn add shopify-buy
+yarn add shopify-buy
 ```
+
 **With NPM:**
+
 ```bash
-$ npm install shopify-buy
+npm install shopify-buy
 ```
 
 **CDN:**
@@ -76,20 +94,27 @@ You can also fetch the unoptimized release for a version (2.0.1 and above). This
 ```
 
 ## Builds
+
 The JS Buy SDK has four build versions: ES, CommonJS, AMD, and UMD.
 
 **ES, CommonJS:**
+
 ```javascript
 import Client from 'shopify-buy';
 ```
+
 **AMD:**
+
 ```javascript
 import Client from 'shopify-buy/index.amd';
 ```
+
 **UMD:**
+
 ```javascript
 import Client from 'shopify-buy/index.umd';
 ```
+
 **UMD Unoptimized:**
 This will be larger than the optimized version, as it will contain all fields that are available in the [Storefront API](https://help.shopify.com/en/api/custom-storefronts/storefront-api/reference). This should only be used when you need to add custom queries to supplement the JS Buy SDK queries.
 
@@ -100,6 +125,7 @@ import Client from 'shopify-buy/index.unoptimized.umd';
 ## Examples
 
 ### Initializing the Client
+
 If your store supports multiple languages, Storefront API can return translated resource types and fields. Learn more about [translating content](https://help.shopify.com/en/api/guides/multi-language/translating-content-api).
 
 ```javascript
@@ -120,6 +146,7 @@ const clientWithTranslatedContent = Client.buildClient({
 ```
 
 ### Fetching Products
+
 ```javascript
 // Fetch all products in your shop
 client.product.fetchAll().then((products) => {
@@ -145,6 +172,7 @@ client.product.fetchByHandle(handle).then((product) => {
 ```
 
 ### Fetching Collections
+
 ```javascript
 // Fetch all collections, including their products
 client.collection.fetchAllWithProducts().then((collections) => {
@@ -164,7 +192,124 @@ client.collection.fetchWithProducts(collectionId, {productsFirst: 10}).then((col
 });
 ```
 
+## Carts
+
+### Creating a Cart
+
+```javascript
+const input = {
+  lines: {
+    merchandiseId: 'gid://shopify/ProductVariant/13666012889144',
+    quantity: 5,
+    attributes: [{key: "MyKey", value: "MyValue"}]
+  },
+  note: 'This is a cart note!'
+];
+
+// Create a cart
+client.cart.create(input).then((cart) => {
+  // Do something with the cart
+});
+```
+
+### Fetching a Cart
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLWV1cm9wZS13ZXN0NDowMUhOTTI0QVZYV1NOSEVNOUVCQ1JSNUhSVg'
+
+client.cart.fetch(cartId).then((cart) => {
+  // Do something with the cart
+});
+```
+
+### Updating Cart Attributes
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const attributes = [{key: "MyKey", value: "MyValue"}];
+
+client.cart.updateAttributes(cartId, attributes).then((cart) => {
+  // Do something with the updated cart
+});
+```
+
+### Updating Buyer Identity
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const buyerIdentity = {email: "[email protected]"};
+
+client.cart.updateBuyerIdentity(cartId, buyerIdentity).then((cart) => {
+  // Do something with the updated cart
+});
+```
+
+### Updating Discount Codes
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const discountCodes = [{code: "MyCode"}];
+
+client.cart.updateDiscountCodes(cartId, discountCodes).then((cart) => {
+  // Do something with the updated cart
+});
+```
+
+### Adding Cart Line Items
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const lines = [{merchandiseId: 'gid://shopify/Product/123456', quantity: 5}];
+
+client.cart.addLineItems(cartId, lines).then((cart) => {
+  // Do something with the updated cart
+});
+```
+
+### Removing Cart Line Items
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const lineIdsToRemove = ['gid://shopify/CartLineItem/123456'];
+
+client.cart.addLineItems(cartId, lineIdsToRemove).then((cart) => {
+  // Do something with the updated cart
+});
+```
+
+### Updating Cart Line Items
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const lines = [{id: 'gid://shopify/CartLineItem/123456', quantity: 5}];
+
+client.cart.updateLineItems(cartId, lines).then((cart) => {
+  // Do something with the updated cart
+});
+```
+
+### Updating Cart Notes
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const note = 'A note for the cart';
+
+client.cart.updateNote(cartId, note).then((cart) => {
+  // Do something with the updated cart
+}
+```
+
+### Redirecting to Checkout
+
+To complete the purchase, redirect customers to the `checkoutUrl` property attached to the cart.
+
+## Checkouts
+
+> [!WARNING]
+> Checkouts will [soon be deprecated](https://github.com/Shopify/storefront-api-feedback/discussions/225). Use [Carts](#carts) instead.
+
 ### Creating a Checkout
+
 ```javascript
 // Create an empty checkout
 client.checkout.create().then((checkout) => {
@@ -174,6 +319,7 @@ client.checkout.create().then((checkout) => {
 ```
 
 ### Updating checkout attributes
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8';
 const input = {customAttributes: [{key: "MyKey", value: "MyValue"}]};
@@ -184,6 +330,7 @@ client.checkout.updateAttributes(checkoutId, input).then((checkout) => {
 ```
 
 ### Adding Line Items
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
 const lineItemsToAdd = [
@@ -202,6 +349,7 @@ client.checkout.addLineItems(checkoutId, lineItemsToAdd).then((checkout) => {
 ```
 
 ### Updating Line Items
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
 const lineItemsToUpdate = [
@@ -216,6 +364,7 @@ client.checkout.updateLineItems(checkoutId, lineItemsToUpdate).then((checkout) =
 ```
 
 ### Removing Line Items
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
 const lineItemIdsToRemove = [
@@ -230,6 +379,7 @@ client.checkout.removeLineItems(checkoutId, lineItemIdsToRemove).then((checkout)
 ```
 
 ### Fetching a Checkout
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'
 
@@ -240,6 +390,7 @@ client.checkout.fetch(checkoutId).then((checkout) => {
 ```
 
 ### Adding a Discount
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
 const discountCode = 'best-discount-ever';
@@ -252,6 +403,7 @@ client.checkout.addDiscount(checkoutId, discountCode).then(checkout => {
 ```
 
 ### Removing a Discount
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
 
@@ -263,6 +415,7 @@ client.checkout.removeDiscount(checkoutId).then(checkout => {
 ```
 
 ### Updating a Shipping Address
+
 ```javascript
 const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
 
@@ -294,6 +447,7 @@ The simplest way to complete a checkout is to use the [webUrl](https://help.shop
 Not all fields that are available on the [Storefront API](https://help.shopify.com/en/api/custom-storefronts/storefront-api/reference) are exposed through the SDK. If you use the unoptimized version of the SDK, you can easily build your own queries. In order to do this, use the UMD Unoptimized build.
 
 ### Initializing the Client
+
 ```javascript
 // fetch the large, unoptimized version of the SDK
 import Client from 'shopify-buy/index.unoptimized.umd';
@@ -305,6 +459,7 @@ const client = Client.buildClient({
 ```
 
 ### Fetching Products
+
 ```javascript
 // Build a custom products query using the unoptimized version of the SDK
 const productsQuery = client.graphQLClient.query((root) => {
@@ -333,10 +488,12 @@ There are JS Buy SDK specific example apps in Node, Ember, and React. You can us
 - [API documentation](https://shopify.github.io/js-buy-sdk).
 
 ## Contributing
+
 For help on setting up the repo locally, building, testing, and contributing
 please see [CONTRIBUTING.md](https://github.com/Shopify/js-buy-sdk/blob/main/CONTRIBUTING.md).
 
 ## Code of Conduct
+
 All developers who wish to contribute through code or issues, take a look at the
 [CODE_OF_CONDUCT.md](https://github.com/Shopify/js-buy-sdk/blob/main/CODE_OF_CONDUCT.md).
 

fixtures/cart-create-fixture.js

@@ -0,0 +1,51 @@
+export default {
+  data: {
+    cartCreate: {
+      userErrors: [],
+      cart: {
+        attributes: [
+          {
+            key: 'cart_attribute',
+            value: 'This is a cart attribute'
+          }
+        ],
+        checkoutUrl: 'https://secure-us.gcds.com/cart/c/Z2NwLWV1cm9wZS13ZXN0NDowMUhOSERHWUNTNDlSMUtQNk1HUjlZOTdDSA?key=73de96370dea19c18996cebea3b31a1b',
+        discountCodes: [],
+        id: 'gid://shopify/Cart/Z2NwLWV1cm9wZS13ZXN0NDowMUhOSERHWUNTNDlSMUtQNk1HUjlZOTdDSA',
+        createdAt: '2024-02-01T04:06:11Z',
+        updatedAt: '2024-02-01T04:06:11Z',
+        lines: {
+          pageInfo: {
+            hasNextPage: false,
+            hasPreviousPage: false
+          },
+          edges: [
+            {
+              node: {
+                id: 'gid://shopify/CartLine/a07f5410-ea7a-41ac-a794-839c1e0d599c?cart=Z2NwLWV1cm9wZS13ZXN0NDowMUhOSERHWUNTNDlSMUtQNk1HUjlZOTdDSA',
+                merchandise: {
+                  id: 'gid://shopify/ProductVariant/43162292814051'
+                }
+              }
+            }
+          ]
+        },
+        cost: {
+          totalAmount: {
+            amount: '0.0',
+            currencyCode: 'USD'
+          },
+          subtotalAmount: {
+            amount: '0.0',
+            currencyCode: 'USD'
+          },
+          totalTaxAmount: {
+            amount: '0.0',
+            currencyCode: 'USD'
+          },
+          totalDutyAmount: null
+        }
+      }
+    }
+  }
+};