<commit_before>**NOTE:** This is currently outdated and reflects the alpha branch. Method names are currently in flux on the beta branch.
# Migration Guide

This document provides a set of guidelines for migrating from v0.7 of the JS Buy SDK to v1 of the JS Buy SDK
which uses Shopify's GraphQL-based [Storefront API](https://help.shopify.com/api/storefront-api/reference).

## Table of Contents

- [Installation](#installation)
- [Updated Functions and Classes](#updated-functions-and-classes)
  + [Initialization](#initialization)
  + [Fetching Products and Collections](#fetching-products-and-collections)
  + [Carts/Checkouts](#cartscheckouts)

## Installation

**With Yarn:**

```bash
yarn add shopify-buy@beta
```
**With NPM:**

Remove the old version, then
```bash
npm install shopify-buy@beta
```

## Updated Functions and Classes

### Initialization

Rather than using a static function to create the client (`ShopifyBuy.buildClient()`), v1 exposes the `Client`
(previously `ShopClient`) and a `Config` class for the `Client` directly. An instance of `Client` can be created like so:
```js
import Client, {Config} from 'shopify-buy';

const config = new Config({
  domain: 'your-shop-name.myshopify.com',
  storefrontAccessToken: 'your-storefront-access-token'
});

const client = new Client(config);
```

### Fetching Products and Collections

The functions for fetching products and collections are mostly the same. Major differences are:

1. The v1 functions take in a `Storefront ID` for fetching a product or collection by ID. A `Storefront ID` can be found under
[the retrieving IDs section](https://help.shopify.com/api/storefront-api/getting-started#retrieving-ids) of the Storefront API docs.
`API details` will only be displayed if you have a private app with Storefront API access. For more details see the 
[Getting Started Guide](https://help.shopify.com/api/storefront-api/getting-started#authentication) for the Storefront API.

2. Collections can be fetched with products using `collection.fetchWithProducts()` and `collection.fetchAllWithProducts()`.
```js
const collectionId = 'Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzI1NzY5NzczMQ=='

// Use the built-in function
client.collection.fetchWithProducts(collectionId).then((collection) => {
  console.log(collection); // Collection with all default fields and products with all default fields.
  console.log(collection.products); // Products on the collection
});
```

3. `product.fetchQuery()` and `collection.fetchQuery()` query different fields and take an optional `query` argument.
See the [product connection field](https://help.shopify.com/api/storefront-api/reference/object/shop#products) and
[collection connection field](https://help.shopify.com/api/storefront-api/reference/object/shop#collections) docs
in the storefront API for more details.

**v0.7:**
```js
client.fetchQueryProducts({collection_id: '336903494', tag: ['hats']}).then((products) => {
  console.log(products); // An array of products in collection '336903494' having the tag 'hats'
});
```

**v1:**
```js
const query = {
  query: 'updated_at:>="2016-09-25T21:31:33"',
  sortBy: 'title'
};

client.products.fetchQuery(query).then((products) => {
  console.log(products); // An array of products updated after 2016-09-25T21:31:33 
                         // and sorted in ascending order by title.
});
```

### Carts/Checkouts

Carts are replaced with checkouts. Like the fetch functions, all checkout functions take an optional `query` argument that specifies fields to return on the checkout.

`fetchRecentCart()`, `updateModel()`, and `clearLineItems()` have been removed. `checkoutUrl` has been renamed to `webUrl`.

#### Creating a Checkout

To create a checkout, use `checkout.create()`. You are responsible for capturing the ID of the checkout for later usage. If you would like to persist the checkout between sessions, store the ID in a cookie or localStorage.

**v0.7:**
```js
client.createCart().then((cart) => {
  console.log(cart); // Empty cart
});
```

**v1:**
```js
client.checkout.create().then((checkout) => {
  console.log(checkout); // Empty checkout
  console.log(checkout.id); // The ID of the checkout. Store this for later usage.
});
```
The checkout can also be initialized with fields like line items and a shipping address. See the [API reference(update me)](https://github.com/Shopify/js-buy-sdk/blob/v1.0beta/docs/API_REFERENCE.md#Client+createCheckout) for more details.

#### Fetching a Checkout

To fetch a checkout, use `fetchCheckout()`.

**v0.7:**
```js
client.fetchRecentCart().then((cart) => {
  console.log(cart); // Most recently created cart
});<commit_msg>update link to api reference<commit_after>**NOTE:** This is currently outdated and reflects the alpha branch. Method names are currently in flux on the beta branch.
# Migration Guide

This document provides a set of guidelines for migrating from v0.7 of the JS Buy SDK to v1 of the JS Buy SDK
which uses Shopify's GraphQL-based [Storefront API](https://help.shopify.com/api/storefront-api/reference).

## Table of Contents

- [Installation](#installation)
- [Updated Functions and Classes](#updated-functions-and-classes)
  + [Initialization](#initialization)
  + [Fetching Products and Collections](#fetching-products-and-collections)
  + [Carts/Checkouts](#cartscheckouts)

## Installation

**With Yarn:**

```bash
yarn add shopify-buy@beta
```
**With NPM:**

Remove the old version, then
```bash
npm install shopify-buy@beta
```

## Updated Functions and Classes

### Initialization

Rather than using a static function to create the client (`ShopifyBuy.buildClient()`), v1 exposes the `Client`
(previously `ShopClient`) and a `Config` class for the `Client` directly. An instance of `Client` can be created like so:
```js
import Client, {Config} from 'shopify-buy';

const config = new Config({
  domain: 'your-shop-name.myshopify.com',
  storefrontAccessToken: '<PASSWORD>-storefront-access-token'
});

const client = new Client(config);
```

### Fetching Products and Collections

The functions for fetching products and collections are mostly the same. Major differences are:

1. The v1 functions take in a `Storefront ID` for fetching a product or collection by ID. A `Storefront ID` can be found under
[the retrieving IDs section](https://help.shopify.com/api/storefront-api/getting-started#retrieving-ids) of the Storefront API docs.
`API details` will only be displayed if you have a private app with Storefront API access. For more details see the 
[Getting Started Guide](https://help.shopify.com/api/storefront-api/getting-started#authentication) for the Storefront API.

2. Collections can be fetched with products using `collection.fetchWithProducts()` and `collection.fetchAllWithProducts()`.
```js
const collectionId = 'Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzI1NzY5NzczMQ=='

// Use the built-in function
client.collection.fetchWithProducts(collectionId).then((collection) => {
  console.log(collection); // Collection with all default fields and products with all default fields.
  console.log(collection.products); // Products on the collection
});
```

3. `product.fetchQuery()` and `collection.fetchQuery()` query different fields and take an optional `query` argument.
See the [product connection field](https://help.shopify.com/api/storefront-api/reference/object/shop#products) and
[collection connection field](https://help.shopify.com/api/storefront-api/reference/object/shop#collections) docs
in the storefront API for more details.

**v0.7:**
```js
client.fetchQueryProducts({collection_id: '336903494', tag: ['hats']}).then((products) => {
  console.log(products); // An array of products in collection '336903494' having the tag 'hats'
});
```

**v1:**
```js
const query = {
  query: 'updated_at:>="2016-09-25T21:31:33"',
  sortBy: 'title'
};

client.products.fetchQuery(query).then((products) => {
  console.log(products); // An array of products updated after 2016-09-25T21:31:33 
                         // and sorted in ascending order by title.
});
```

### Carts/Checkouts

Carts are replaced with checkouts. Like the fetch functions, all checkout functions take an optional `query` argument that specifies fields to return on the checkout.

`fetchRecentCart()`, `updateModel()`, and `clearLineItems()` have been removed. `checkoutUrl` has been renamed to `webUrl`.

#### Creating a Checkout

To create a checkout, use `checkout.create()`. You are responsible for capturing the ID of the checkout for later usage. If you would like to persist the checkout between sessions, store the ID in a cookie or localStorage.

**v0.7:**
```js
client.createCart().then((cart) => {
  console.log(cart); // Empty cart
});
```

**v1:**
```js
client.checkout.create().then((checkout) => {
  console.log(checkout); // Empty checkout
  console.log(checkout.id); // The ID of the checkout. Store this for later usage.
});
```
The checkout can also be initialized with fields like line items and a shipping address. See the [API reference](https://github.com/Shopify/js-buy-sdk/blob/v1.0beta/docs/API_REFERENCE.md#CheckoutResource+create) for more details.

#### Fetching a Checkout

To fetch a checkout, use `fetchCheckout()`.

**v0.7:**
```js
client.fetchRecentCart().then((cart) => {
  console.log(cart); // Most recently created cart
});
{'fraction_non_alphanumeric': 0.12647881264788127, 'fraction_numerical': 0.015702301570230157, 'mean_word_length': 4.9153944020356235, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 18, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3589713', 'n_tokens_mistral': 2905, 'n_tokens_neox': 2678, 'n_words': 943}