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,43 @@ 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)
+    - [Updating Gift Card Codes](#updating-gift-card-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)
 - [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 +84,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 +115,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 +136,7 @@ const clientWithTranslatedContent = Client.buildClient({
 ```
 
 ### Fetching Products
+
 ```javascript
 // Fetch all products in your shop
 client.product.fetchAll().then((products) => {
@@ -145,6 +162,7 @@ client.product.fetchByHandle(handle).then((product) => {
 ```
 
 ### Fetching Collections
+
 ```javascript
 // Fetch all collections, including their products
 client.collection.fetchAllWithProducts().then((collections) => {
@@ -164,136 +182,144 @@ client.collection.fetchWithProducts(collectionId, {productsFirst: 10}).then((col
 });
 ```
 
-### Creating a Checkout
+## Carts
+
+### Creating a Cart
+
 ```javascript
-// Create an empty checkout
-client.checkout.create().then((checkout) => {
-  // Do something with the checkout
-  console.log(checkout);
+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
 });
 ```
 
-### Updating checkout attributes
+### Fetching a Cart
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8';
-const input = {customAttributes: [{key: "MyKey", value: "MyValue"}]};
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR'
 
-client.checkout.updateAttributes(checkoutId, input).then((checkout) => {
-  // Do something with the updated checkout
+client.cart.fetch(cartId).then((cart) => {
+  // Do something with the cart
 });
 ```
 
-### Adding Line Items
+### Updating Cart Attributes
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
-const lineItemsToAdd = [
-  {
-    variantId: 'gid://shopify/ProductVariant/29106064584',
-    quantity: 5,
-    customAttributes: [{key: "MyKey", value: "MyValue"}]
-  }
-];
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const attributes = [{key: "MyKey", value: "MyValue"}];
 
-// Add an item to the checkout
-client.checkout.addLineItems(checkoutId, lineItemsToAdd).then((checkout) => {
-  // Do something with the updated checkout
-  console.log(checkout.lineItems); // Array with one additional line item
+client.cart.updateAttributes(cartId, attributes).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Updating Line Items
+### Updating Buyer Identity
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
-const lineItemsToUpdate = [
-  {id: 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef', quantity: 2}
-];
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const buyerIdentity = {email: "[email protected]"};
 
-// Update the line item on the checkout (change the quantity or variant)
-client.checkout.updateLineItems(checkoutId, lineItemsToUpdate).then((checkout) => {
-  // Do something with the updated checkout
-  console.log(checkout.lineItems); // Quantity of line item 'gid://shopify/Product/7857989384' updated to 2
+client.cart.updateBuyerIdentity(cartId, buyerIdentity).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Removing Line Items
+### Updating Discount Codes
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
-const lineItemIdsToRemove = [
-  'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef'
-];
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const discountCodes = [{code: "MyCode"}];
 
-// Remove an item from the checkout
-client.checkout.removeLineItems(checkoutId, lineItemIdsToRemove).then((checkout) => {
-  // Do something with the updated checkout
-  console.log(checkout.lineItems); // Checkout with line item 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef' removed
+client.cart.updateDiscountCodes(cartId, discountCodes).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Fetching a Checkout
+### Updating Gift Card Codes
+
+```javascript
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const giftCardCodes = ["jmfxf9wmmmhgq379"];
+
+client.cart.updateGiftCardCodes(cartId, giftCardCodes).then((cart) => {
+  // Do something with the updated cart
+});
+
+### Adding Cart Line Items
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const lines = [{merchandiseId: 'gid://shopify/Product/123456', quantity: 5}];
 
-client.checkout.fetch(checkoutId).then((checkout) => {
-  // Do something with the checkout
-  console.log(checkout);
+client.cart.addLineItems(cartId, lines).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Adding a Discount
+### Removing Cart Line Items
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
-const discountCode = 'best-discount-ever';
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const lineIdsToRemove = ['gid://shopify/CartLineItem/123456'];
 
-// Add a discount code to the checkout
-client.checkout.addDiscount(checkoutId, discountCode).then(checkout => {
-  // Do something with the updated checkout
-  console.log(checkout);
+client.cart.addLineItems(cartId, lineIdsToRemove).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Removing a Discount
+### Updating Cart Line Items
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const lines = [{id: 'gid://shopify/CartLineItem/123456', quantity: 5}];
 
-// Removes the applied discount from an existing checkout.
-client.checkout.removeDiscount(checkoutId).then(checkout => {
-  // Do something with the updated checkout
-  console.log(checkout);
+client.cart.updateLineItems(cartId, lines).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Updating a Shipping Address
+### 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
+}
+```
+
+### Updating Cart Selected Delivery Options
+
 ```javascript
-const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
-
-const shippingAddress = {
-   address1: 'Chestnut Street 92',
-   address2: 'Apartment 2',
-   city: 'Louisville',
-   company: null,
-   country: 'United States',
-   firstName: 'Bob',
-   lastName: 'Norman',
-   phone: '555-625-1199',
-   province: 'Kentucky',
-   zip: '40202'
- };
-
-// Update the shipping address for an existing checkout.
-client.checkout.updateShippingAddress(checkoutId, shippingAddress).then(checkout => {
-  // Do something with the updated checkout
+const cartId = 'gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSE5WWTAyVjlETjFDNVowVFZEWVMwMVJR';
+const selectedDeliveryOptions = [{deliveryGroupId: 'gid://shopify/CartDeliveryGroup/269ea2856c41d63937d1ba5212c29713', deliveryOptionHandle: 'standard'}];
+
+client.cart.updateSelectedDeliveryOptions(cartId, selectedDeliveryOptions).then((cart) => {
+  // Do something with the updated cart
 });
 ```
 
-### Completing a checkout
+### Redirecting to Checkout
 
-The simplest way to complete a checkout is to use the [webUrl](https://help.shopify.com/en/api/storefront-api/reference/object/checkout) property that is returned when creating a checkout. This URL redirects the customer to Shopify's [online checkout](https://help.shopify.com/en/manual/checkout-settings) to complete the purchase.
+To complete the purchase, redirect customers to the `checkoutUrl` property attached to the cart.
 
 ## Expanding the SDK
 
 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 +331,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 +360,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).