shopify_api 13.1.0 → 13.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330b033c35e9b3b421a89e937cd50f80cd9439cdfc344c9809ef16746971a6e0
-  data.tar.gz: 522ce45ee19bc4208b3ee29eb95f620cfc473757507075da9fcb679ba63946a8
+  metadata.gz: b83eabed3d0c78f619d6061eb4bb92c389e1d15afca55225c243c0200a73f1f9
+  data.tar.gz: 2d6858dda679bb4a65f2eddbbc3d746f6177eda1808109a1ebcce943ae5cb9b9
 SHA512:
-  metadata.gz: 884e25968587509d4c7643e128939832613dfc3c335936b517c574b5d4ad2f83e0a7ddb19af55214a04b27a72a4eb9fa1e23e7bf992031120e5c4bb96e67f934
-  data.tar.gz: b163f2f6290fdf41ca6a5f10c3b4732f1e9f9404d56d560a83db657f70b55f39edc2916660ce0ddf4e24bb8faf4049b6ce55b93dc651ef7fe6f2842483482c2a
+  metadata.gz: fb175ef43080cec7459eff1a7a40c3d0c48aabc8b69bd8fe10fba1bdcfb3c3ca9a9d4e5e5bd6184421a0639f06b18097efa151c912439198f28838a6f60b5b67
+  data.tar.gz: 121a72ef9cc5b608b96d5be67a9404f739598708e9649fd720b21fa7614f2d53f162d2e12872441bf4419318d5cb7f13721606239ce21f9bbfa3868e1c4153f8

data/BREAKING_CHANGES_FOR_V10.md

@@ -0,0 +1,231 @@
+# Breaking change notice for version 10.0.0
+
+We've rewritten this library for v10, so that it provides all essential features for a Shopify app without depending on the [Active Resource](https://github.com/rails/activeresource) or [graphql-client](https://github.com/github/graphql-client) libraries.
+
+#### Table of Contents
+- [New Features](#new-features)
+- [Upgrade Guide](#upgrade-guide)
+  - [1. Configuration Changes](#1-configuration-changes)
+  - [2. Session Changes](#2-session-changes)
+    - [ShopifyAPI::Auth::Session](#shopifyapiauthsession)
+  - [3. API Client Changes](#3-api-client-changes)
+    - [GraphQL](#graphql)
+    - [Rest](#rest)
+      - [Using Rest Resources](#using-rest-resources)
+      - [Using Rest Admin Client](#using-rest-admin-client)
+    - [Generic HTTP Client](#generic-http-client)
+- [Useful References](#useful-references)
+
+## New Features
+Here are the main features version 10 provides:
+
+- OAuth support, both with online and offline tokens.
+- Full, transparent support for JWT sessions for embedded apps and cookies for non-embedded ones.
+  - Removal of support for 3rd party cookies which are increasingly more difficult to use with modern browsers.
+- Admin API support
+  - Auto-generated, version-specific REST resources which are similar to `ActiveResource` (though not identical), that provide methods for all endpoints defined in our [REST API reference](https://shopify.dev/docs/api/admin-rest), as well as direct definition of known attributes.
+  - A GraphQL client that doesn't rely on the ActiveResource implementation for REST.
+- Webhook management, with features for adding handlers and registering them with Shopify.
+- Storefront GraphQL API support
+
+Please refer to the [Getting Started](docs/getting_started.md) guide in this repository for instructions on how to use each of these components.
+
+### Reasoning
+- Browsers stopped allowing 3rd party cookies, even after jumping through several [ITP](https://webkit.org/tracking-prevention-policy/) hoops, which made the code
+even more more complex and error prone.
+    - Session tokens and `authenticatedFetch` were introduced to make it possible for apps to authenticate requests without depending on cookies.
+    - The gem was too closely tied to rails on how it sets up sessions (which worked for cookies), so we had to detach the library from rails
+  in order to be able to work with both cookies and session tokens.
+- We previously relied on an `omniauth-oauth2` strategy that worked fine when cookies were the only option. But it became increasingly
+awkward when we moved towards session tokens, which meant re-writing the OAuth process in the gem as a whole.
+  - Introducing a DB stored session persistence rather than cookie stored.
+- Most feedback we got previously was due to the `ActiveResource` classes failing out of sync with the API because:
+  1. We have some endpoints that didn't 100% follow REST convention;
+  2. We had a single class for each resource and manually maintained custom methods that didn't work across API versions.
+
+- To solve the REST problems:
+    - We were adding support for auto-generated, version-specific resources for other languages, we decided to add them for Ruby too.
+  But those same instances where the API doesn't follow convention would become problematic. Thus we opted for the most explicit option where **every** method was "custom" rather than just some, so that the resources were always consistent.
+
+## Upgrade Guide
+With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10:
+
+### 1. Configuration Changes
+#### Removed ShopifyAPI::Base
+`ShopifyAPI::Base` class has been removed. Previous versions of this gem used this class to configure API request setting like:
+  - **API request version**
+    - **Previously**: Set by `ShopifyAPI::Base.api_version = "xxxx"`
+    - **Change**: Configured `api_version` in [ShopifyAPI::Context.setup](#shopifyapicontextsetup)
+  - **Set `User-Agent` on API request header**
+    - **Previously**: Set by `ShopifyAPI::Base.header["User-Agent"] = "xxxxx"`
+    - **Change**: Configured `user_agent_prefix` in [ShopifyAPI::Context.setup](#shopifyapicontextsetup)
+  - **Set custom headers on API requests**
+    - **Previously**: Set by `ShopifyAPI::Base.header["User-Agent"] = "xxxxx"`
+    - **Change**: Custom headers can be added to requests when you use [`ShopifyAPI::Clients::HttpRequest`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_request.rb#L14)
+
+#### ShopifyAPI::Context.setup
+Initializing the `ShopifyAPI::Context` with the parameters of your app by calling `ShopifyAPI::Context.setup` (example below) when your app starts (e.g `application.rb` in a Rails app).
+This class holds global configurations for your app and defines how the library behaves.
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host_name: "<application-host-name>",
+  scope: "read_orders,read_products,etc",
+  is_embedded: true, # Set to true if you are building an embedded app
+  is_private: false, # Set to true if you are building a private app
+  api_version: "2021-01" # The version of the API you would like to use
+  user_agent_prefix: "<user_agent_prefix>" # Set a custom prefix for "User-Agent" header when making API requests
+  ###
+)
+```
+
+See other fields accepted during `ShopifyAPI::Context` setup in [context.rb](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/context.rb).
+
+### 2. Session Changes
+`ShopifyAPI::Base` class has been removed, you can no longer activate session using `ShopifyAPI::Base.activate_session`. Instead, you can use
+`ShopifyAPI::Context.activate_session` to set the active session ([`ShopifyAPI::Auth::Session`](#shopifyapiauthsesion)).
+If you're using the [ShopifyApp](https://github.com/Shopify/shopify_app) gem in a Rails app, you don't have to manually set the active session if you use the included `ActiveSupport` concerns. See [Session Docs](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md) from ShopifyApp gem.
+
+You can also manually specify the session to use without setting the active session by passing in the session object ([`ShopifyAPI::Auth::Session`](#shopifyapiauthsesion)) when instantiating new `ShopifyAPI::Clients` objects.
+If session is `nil`, it'll default to use active session from `ShopifyAPI::Context.active_session`.
+
+```ruby
+# Manually specifying a session (ShopifyAPI::Auth::Session) in API clients.
+
+# GraphQL Client
+graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
+# REST Client
+rest_client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Using REST Resources
+rest_resource = ShopifyAPI::Shop.new(session: session)
+```
+
+##### ShopifyAPI::Auth::Session
+If you're building a Rails app, it is highly recommended for you to use the [`ShopifyApp` gem to perform OAuth and session storage](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md).
+
+If you're not using Rails, please see the [Performing OAuth](./docs/usage/oauth.md) guide on how to perform OAuth to retrieve and store sessions.
+
+### 3. API Client Changes
+
+#### GraphQL
+- We deprecated the dependency of [graphql-client](https://rubygems.org/gems/graphql-client) gem. You must refactor your existing query and response parsing to use our new GraphQL HTTP Client classes.
+  - [Admin API Client](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/admin.rb)
+  - [Storefront API Client](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/storefront.rb)
+- There is no need to dump the schema to a local JSON file before using it anymore.
+- The api version used to be set on `ShopifyAPI::Base.api_version`, however that's now deprecated.
+You may specify a specific version when initializing your client, or it'll infer to `ShopifyAPI::Context.api_version` as default.
+
+⚠️ See other Admin API usage in ["Make a GraphQL API call" documentation](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md).
+
+⚠️ See Storefront API client usage in ["Make a Storefront API call" documentation](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md).
+
+###### Example refactor
+ShopifyAPI Client v9
+```ruby
+ShopifyAPI::Base.api_version = "2023-04"
+client = ShopifyAPI::GraphQL.client
+
+SHOP_NAME_QUERY = client.parse <<-'GRAPHQL'
+  {
+    shop {
+      name
+    }
+  }
+GRAPHQL
+
+result = client.query(SHOP_NAME_QUERY)
+shop_name = result.data.shop.name
+```
+
+ShopifyAPI Client v10+
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "2023-04")
+# session must be an instance of ShopifyAPI::Auth::Session, see Section - [2. Session Changes]
+
+SHOP_NAME_QUERY =<<~QUERY
+  {
+    shop {
+      name
+    }
+  }
+QUERY
+
+response = client.query(query: query)
+shop_name = response.body["data"]["shop"]["name"]
+```
+
+#### REST
+##### Using REST Resources
+- The use of `ActiveResource` has been deprecated, REST API requests must now be refactored to use the new format that better represents our REST API schema.
+- Previously the api_version is specified in `ShopifyAPI::Base.api_version`, that has been deprecated. It's now configured in [`ShopifyAPI::Context.setup`](#shopifyapicontextsetup).
+
+###### Example refactor
+⚠️ You can find detailed examples on how each of the resource endpoints work in our [REST reference documentation](https://shopify.dev/docs/api/admin-rest).
+
+Please see below a (non-exhaustive) list of common replacements to guide you in your updates, using the `Order` resource as an example.
+For more detail, see [`order` reference documentation's](https://shopify.dev/docs/api/admin-rest/2023-07/resources/order#top) ruby example.
+
+|Usage | Before| After |
+| -----| --- | --- |
+|Find partially paid orders| `Order.find(:all, params: {financial_status: "partially_paid"})`| `Order.all(financial_status: "partially_paid")` |
+|Find order by ID `<id>` | `Order.find(<id>)` | `Order.find(id: <id>)` |
+|Update an order's fulfillment status|`order = Order.find<id>`<br/>`order.fulfillment_status = "fulfilled"`<br/>`order.note = "Fulfilled on September 6, 2023"`<br/>`order.save`|`order = Order.find(id: <id>)`<br/>`order.fulfillment_status = "fulfilled"`<br/>`order.note = "Fulfilled on September 6, 2023"`<br/>`order.save!`|
+|Close an order| `order = Order.new(<id>)`<br/>`order.post(:close)` | `order = Order.find(id: <id>)`<br/>`order.close` |
+|Delete an order| `order = Order.new(<id>)`<br/>`order.delete`       | `Order.delete(id: <id>)` |
+
+###### Note on resource connections
+Previously we added helper methods to load related resource connections like [`orders.transactions`](https://github.com/Shopify/shopify-api-ruby/blob/97eec35fb76afbce1d948cee2963791457e934da/lib/shopify_api/resources/order.rb#L20).
+After the upgrade, only connected properties listed in the REST API will be supported.
+
+For example:
+- `order.transactions` is not supported because `transactions` is not a property of the `Order` resource.
+- `order.customer` is supported because `customer` is a property of the `Order` resource.
+
+[See the full list of `Order` properties here.](https://shopify.dev/docs/api/admin-rest/2023-07/resources/order#resource-object)
+
+##### Using REST Admin Client
+If you do not want to use the REST resource classes, you can use our REST Admin client directly to make HTTP requests.
+
+⚠️ See other REST client usage in ["Make a REST API call" documentation](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md).
+
+Example:
+```ruby
+# Create a new client.
+client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+
+# Update title for product with ID <id>
+body = {
+  product: {
+    title: "My cool product"
+  }
+}
+
+# Use `client.put` to send your request to the specified Shopify Admin REST API endpoint.
+client.put(path: "products/<id>.json", body: body)
+```
+
+#### Generic HTTP Client
+We added a new generic [HttpClient](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_client.rb) wrapper to make requests and handle Shopify specific errors. All of the REST and GraphQL Clients use this HTTP Client in its foundation.
+You can use this to make direct HTTP API calls easily.
+See how the GraphQL Client makes a request with this HttpClient class in its [implementation here](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/client.rb#L33-L45).
+
+## Useful references
+
+ShopifyAPI:
+- [Performing OAuth](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/oauth.md)
+- [Make a GraphQL API Call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md)
+- [Make a Storefront API Call (GraphQL)](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql_storefront.md)
+- [Make a REST API Call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md)
+- [Webhooks](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/webhooks.md)
+
+ShopifyApp Gem (Rails):
+- [Authentication](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/authentication.md)
+- [Sessions](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md)
+
+Shopify API:
+- [Admin GraphQL Reference](https://shopify.dev/docs/api/admin-graphql)
+- [Admin REST Reference](https://shopify.dev/docs/api/admin-rest)

data/CHANGELOG.md

@@ -4,6 +4,13 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 
 ## Unreleased
 
+## 13.2.0
+
+- [#1183](https://github.com/Shopify/shopify-api-ruby/pull/1189) Added string array support for fields parameter in Webhook::Registry
+- [1208](https://github.com/Shopify/shopify-api-ruby/pull/1208) Fix CustomerAddress and FulfillmentRequest methods
+- [1225](https://github.com/Shopify/shopify-api-ruby/pull/1225) Support for 2023_10 API version
+- [#1186](https://github.com/Shopify/shopify-api-ruby/pull/1186) Extend webhook registration to support metafield_namespaces
+
 ## 13.1.0
 
 - [#1183](https://github.com/Shopify/shopify-api-ruby/pull/1183) Added support for API version 2023-07
@@ -14,7 +21,7 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 
 - [#1140](https://github.com/Shopify/shopify-api-ruby/pull/1140) ⚠️ [Breaking] Reformat Http error messages to be JSON parsable.
 - [#1142](https://github.com/Shopify/shopify-api-ruby/issues/1142) Restore API version 2022-04, in alignment with [this](https://shopify.dev/changelog/action-required-support-for-api-version-2022-04-extended-to-june-30-2023) changelog notice.
-- [#1155](https://github.com/Shopify/shopify-api-ruby/pull/1155) ⚠️ [Breaking] Remove session storage that was deprecated with [#1055](https://github.com/Shopify/shopify-api-ruby/pull/1055). ⚠️ [Breaking] GraphQL Proxy now requires `session` to be passed as an argument.
+- [#1155](https://github.com/Shopify/shopify-api-ruby/pull/1155) ⚠️ [Breaking] Remove session storage that was deprecated with [#1055](https://github.com/Shopify/shopify-api-ruby/pull/1055). To upgrade, remove `session_storage` from your API context block. ⚠️ [Breaking] GraphQL Proxy now requires `session` to be passed as an argument.
 - [#1150](https://github.com/Shopify/shopify-api-ruby/pull/1150) [Patch] Add support for Event topic names.
 
 ## 12.5.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shopify_api (13.1.0)
+    shopify_api (13.2.0)
       activesupport
       concurrent-ruby
       hash_diff
@@ -16,7 +16,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.6)
+    activesupport (7.0.7.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -42,12 +42,12 @@ GEM
     jwt (2.7.1)
     language_server-protocol (3.17.0.1)
     method_source (1.0.0)
-    mini_mime (1.1.2)
+    mini_mime (1.1.5)
     minitest (5.15.0)
     mocha (1.13.0)
     multi_xml (0.6.0)
     netrc (0.11.0)
-    oj (3.15.0)
+    oj (3.16.0)
     openssl (3.1.0)
     parallel (1.22.1)
     parser (3.1.2.1)
@@ -133,7 +133,7 @@ GEM
     yard-sorbet (0.7.0)
       sorbet-runtime (>= 0.5)
       yard (>= 0.9)
-    zeitwerk (2.6.8)
+    zeitwerk (2.6.11)
 
 PLATFORMS
   arm64-darwin-21

data/README.md

@@ -17,6 +17,9 @@ You can use this library in any application that has a Ruby backend, since it do
 
 **Note**: These instructions apply to v10 or later of this package. If you're running v9 in your app, you can find the documentation [in this branch](https://github.com/Shopify/shopify-api-ruby/tree/v9).
 
+## Use with Rails
+If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to interact with this gem. Authentication, session storage, webhook registration, and other frequently implemented paths are managed in that gem with easy to use configurations.
+
 ## Requirements
 
 To follow these usage guides, you will need to:
@@ -67,46 +70,19 @@ The Shopify API gem tries to make this easy by providing functions to begin and
 
 If you intend to use webhooks in your application follow the steps in the [Webhooks doc](docs/usage/webhooks.md) for instructions on registering and handling webhooks.
 
-### Start Making Authenticated Shopify Requests
+### Start Making Authenticated Shopify API Requests
 
-Once your app can perform OAuth, it can now make authenticated Shopify API calls using the Admin [REST](docs/usage/rest.md) or [GraphQL](docs/usage/graphql.md) Clients, or the [Storefront API GraphQL Client](docs/usage/graphql_storefront.md).
+Once your app can perform OAuth, it can now make authenticated Shopify API calls, see docs for:
+* Making [Admin REST API](docs/usage/rest.md) requests
+* Making [Admin GraphQL API](docs/usage/graphql.md) requests
+* Making [Storefront GraphQL API](docs/usage/graphql_storefront.md) requests
 
 ## Breaking Change Notices
 
 ### Breaking change notice for version 10.0.0
+See [BREAKING_CHANGES_FOR_V10](BREAKING_CHANGES_FOR_V10.md)
 
-We've rewritten this library for v10, so that it provides all essential features for a Shopify app without depending on the [Active Resource](https://github.com/rails/activeresource) or [graphql-client](https://github.com/github/graphql-client) libraries.
-
-Here are the main features it provides:
-
-- OAuth support, both with online and offline tokens.
-- Full, transparent support for JWT sessions for embedded apps and cookies for non-embedded ones.
-  - Removal of support for 3rd party cookies which are increasingly more difficult to use with modern browsers.
-- Admin API support
-  - Auto-generated, version-specific REST resources which are similar to `ActiveResource` (though not identical), that provide methods for all endpoints defined in our [REST API reference](https://shopify.dev/docs/api/admin-rest), as well as direct definition of known attributes.
-  - A GraphQL client that doesn't rely on the ActiveResource implementation for REST.
-- Webhook management, with features for adding handlers and registering them with Shopify.
-- Storefront GraphQL API support
-
-Please refer to [the documentation](docs/getting_started.md) in this repository for instructions on how to use each of these components.
-
-With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10:
-
-- Call `ShopifyAPI::Context.setup` when setting up your app. This class holds global configurations for your app and defines how the library behaves.
-- If not using the `shopify_app` gem, your app needs to provide an implementation of `ShopifyAPI::Auth::SessionStorage` for production. Read more about this [in our documentation](docs/usage/session_storage.md).
-- To change the `User-Agent` header, use `user_agent_prefix` in `ShopifyAPI::Context.setup`.
-- Usages of the `ActiveResource` classes for REST API requests need to be refactored into the new format. You can find detailed examples on how each of the endpoints work in our [reference documentation](https://shopify.dev/docs/api/admin-rest).
-
-    Please see below a (non-exhaustive) list of common replacements to guide you in your updates, using the `Order` resource as an example.
-
-    | Before                                             | After |
-    | ---                                                | --- |
-    | `Order.find(:all, params: {param1: value1})`       | `Order.all(param1: value1)` |
-    | `Order.find(<id>)`                                 | `Order.find(id: <id>)` |
-    | `order = Order.new(<id>)`<br/>`order.post(:close)` | `order = Order.new`<br/>`order.close` |
-    | `order = Order.new(<id>)`<br/>`order.delete`       | `Order.delete(id: <id>)` |
-
-## Breaking changes for older versions
+### Breaking changes for older versions
 
 See [BREAKING_CHANGES_FOR_OLDER_VERSIONS](BREAKING_CHANGES_FOR_OLDER_VERSIONS.md)
 

data/docs/README.md

@@ -10,4 +10,3 @@ You can follow our getting started guide to learn how to use this library.
 - [Make a GraphQL API call](usage/graphql.md)
 - [Make a Storefront API call](usage/graphql_storefront.md)
 - [Webhooks](usage/webhooks.md)
-- [Known issues and caveats](issues.md)

data/docs/getting_started.md

@@ -37,10 +37,27 @@ ShopifyAPI::Context.setup(
 Next, unless you are making a private app, you need to go through OAuth as described [here](https://shopify.dev/docs/apps/auth/oauth) to create sessions for shops using your app.
 The Shopify API gem tries to make this easy by providing functions to begin and complete the OAuth process. See the [Oauth doc](usage/oauth.md) for instructions on how to use these.
 
-### Register Webhooks and a Webhook Handler
+### Sessions
 
-If you intend to use webhooks in your application follow the steps in the [Webhooks doc](usage/webhooks.md) for instructions on registering and handling webhooks.
+Sessions are required to make requests with the REST or GraphQL clients. This Library provides helpers for creating sessions via OAuth. Helpers are provided to retrieve session ID from a HTTP request from an embedded Shopify app or cookies from non-embedded apps.
+
+Session persistence is handled by the [ShopifyApp](https://github.com/Shopify/shopify_app) gem and is recommended for use in the Rails context. See that gem for documentation on how to use it.
+
+#### Cookie
+Cookie based authentication is not supported for embedded apps due to browsers dropping support for third party cookies due to security concerns. Non-embedded apps are able to use cookies for session storage/retrieval.
+
+For *non-embedded* apps, you can pass the cookies into `ShopifyAPI::Utils::SessionUtils.current_session_id(nil, cookies, true)` for online (user) sessions or `ShopifyAPI::Utils::SessionUtils.current_session_id(nil, cookies, false)` for offline (store) sessions.
+
+#### Getting Session ID From Embedded Requests
+For *embedded* apps, you can pass the auth header into `ShopifyAPI::Utils::SessionUtils.current_session_id(auth_header, nil, true)` for online (user) sessions or `ShopifyAPI::Utils::SessionUtils.current_session_id(auth_header, nil, false)` for offline (store) sessions. This function needs an `auth_header` which is the `HTTP_AUTHORIZATION` header.
 
-### Start Making Authenticated Shopify Requests
+If your app uses client side rendering instead of server side rendering, you will need to use App Bridge's [authenticatedFetch](https://shopify.dev/docs/apps/auth/oauth/session-tokens/getting-started) to make authenticated API requests from the client.
+
+#### Start Making Authenticated Shopify Requests
 
 You can now start making authenticated Shopify API calls using the Admin [REST](usage/rest.md) or [GraphQL](usage/graphql.md) Clients or the [Storefront GraphQL Client](usage/graphql_storefront.md).
+
+### Register Webhooks and a Webhook Handler
+
+If you intend to use webhooks in your application follow the steps in the [Webhooks doc](usage/webhooks.md) for instructions on registering and handling webhooks.
+

data/docs/usage/custom_apps.md

@@ -0,0 +1,75 @@
+# Custom Apps
+
+If you have followed instructions on creating [custom apps](https://help.shopify.com/current/manual/apps/app-types/custom-apps), you should be able to access your API token without having to go through the OAuth flow.
+
+You can follow instructions for [initializing the session object](#initializing-the-session-object) to construct the session object to be used in authenticated API calls to your store.  There are 2 methods to use the session object to make API calls:
+1. [Passing `session` object into each client request](#passing-session-object-into-each-client-request)
+2. [Setting `active_session` in `ShopifyAPI::Context`](#setting-active-session-in-shopifyapicontext)
+
+## Initializing the Session object
+Following is a basic example to construct a simple Session object. You can see full list of parameters for this object in the [class definition](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/session.rb)
+```ruby
+session = ShopifyAPI::Auth::Session.new(
+  shop: "#{your_shop_name}.myshopify.com"
+  access_token: "the_token_for_your_custom_app_found_in_admin"
+)
+
+```
+## Using `Session` to make API calls
+
+### Passing `session` object into each client request
+Example:
+```ruby
+def make_api_request(shop)
+  # 1. create session object
+    session = ShopifyAPI::Auth::Session.new(
+      shop: "#{your_shop_name}.myshopify.com"
+      access_token: "the_token_for_your_custom_app_found_in_admin"
+    )
+
+  # 2a. Create API client with the session information
+  # session must be type `ShopifyAPI::Auth::Session`
+  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+  response = graphql_client.query(query: MY_API_QUERY)
+
+  # 2b. REST example
+  product_count = ShopifyAPI::Product.count(session: session)
+
+  ...
+end
+```
+
+### Setting `active_session` in `ShopifyAPI::Context`
+Alternatively, if you don't want to keep having to create/retrieve a Session object for a shop, you may set [`ShopifyAPI::Context.active_session`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/context.rb#L144).
+All of the API client classes will [use the `active_session`](https://github.com/Shopify/shopify-api-ruby/blob/c3bb9d8f8b6053756149a4cf9299e059ec337544/lib/shopify_api/clients/http_client.rb#L13) if the `session` passed in is `nil`.
+
+Example:
+```ruby
+#### Configuration
+def configure_app
+  # This method is called before making authenticated API calls
+  session = ShopifyAPI::Auth::Session.new(
+      shop: "#{your_shop_name}.myshopify.com"
+      access_token: "the_token_for_your_custom_app_found_in_admin"
+    )
+
+  # Activate session to be used in all API calls
+  # session must be type `ShopifyAPI::Auth::Session`
+  ShopifyAPI::Context.activate_session(session)
+end
+
+#### Using clients to make authenticated API calls
+def make_api_request
+  # 1. Create API client without session information
+  # The graphql_client will use `ShopifyAPI::Context.active_session` when making API calls
+  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new
+
+  # 2. Use API client to make queries
+  ...
+end
+
+```
+
+⚠️ See following docs on how to use the API clients:
+- [Make a GraphQL API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md)
+- [Make a REST API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md)

data/docs/usage/graphql.md

@@ -1,17 +1,37 @@
 # Make a GraphQL API call
 
-Once you have a [session](oauth.md#fetching-sessions) after completing oauth, you can make GraphQL queries to the Admin API with `ShopifyAPI::Clients::Graphql::Admin`
+Once OAuth is complete, we can use `ShopifyAPI::Clients::Graphql::Admin` to make authenticated API calls to the Shopify Admin GraphQL API.
+#### Required Session
+Every API request requires a valid
+[ShopifyAPI::Auth::Session](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/session.rb).
+
+To instantiate a session, we recommend you either use the `shopify_app` if working in Rails, or refer to our OAuth docs on constructing a session:
+ - ["Custom Apps"](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/custom_apps.md) - documentation on how to create Session from a custom app API token.
+ - ["Performing OAuth"](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/oauth.md) - documentation on how to create new sessions
+ - [[ShopifyApp] - "Session"](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md) - documentation on session handling if you're using the [`ShopifyApp`](https://github.com/Shopify/shopify_app) gem.
+
+### Instantiation
+Create an instance of [`ShopifyAPI::Clients::Graphql::Admin`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/admin.rb) using the current session to make requests to the Admin API.
+
+#### Constructor parameters
+| Parameter | Type | Notes |
+| ----------|------|-------|
+| `session` | `ShopifyAPI::Auth::Session` | Default value is `nil`. <br><br>When `nil` is passed in, active session information is inferred from `ShopifyAPI::Context.active_session`. <br>To set active session, use `ShopifyAPI::Context.activate_session`. <br><br>This is handled automatically behind the scenes if you use ShopifyApp's [session controllers](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md). |
+| `api_version` | `String` | Default value is `nil`. When `nil` is passed in, api version is inferred from [`ShopifyAPI::Context.setup`](https://github.com/Shopify/shopify-api-ruby/blob/main/README.md#setup-shopify-context).|
+
+Usage:
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "unstable")
+```
 
-Below is an example
+### Making Authenticated API calls
+#### Basic example
 
 ```ruby
-# load the current session with SessionUtils.load_current_session
-session = ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: <auth-header>, cookies: <cookies>, is_online: <true|false>)
-
-# initalize the client
+# Initialize the client
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
 
-# make the GraphQL query string
+# Make the GraphQL query string
 query =<<~QUERY
   {
     products(first: 10) {
@@ -28,10 +48,13 @@ query =<<~QUERY
 QUERY
 
 response = client.query(query: query)
+
 # do something with the response data
+product = response.body["data"]["products"]["edges"][0]
+my_function(product)
 ```
 
-You can also make GraphQL calls that take in variables
+#### Example GraphQL query with variables
 
 ```ruby
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
@@ -50,18 +73,19 @@ query = <<~QUERY
     }
   }
 QUERY
+
 variables = {
   first: 3
 }
 
 response = client.query(query: query, variables: variables)
-
 ```
 
-Here is an example of how you might use fragments as part of the client
+#### Example GraphQL query with fragments
 
 ```ruby
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
 # define the fragment as part of the query
 query = <<~QUERY
   fragment ProductStuff on Product {
@@ -81,29 +105,47 @@ query = <<~QUERY
     }
   }
 QUERY
+
 variables = {
   first: 3
 }
+
 response = client.query(query: query, variables: variables)
-# do something with the reponse
+# do something with the response
 ```
 
-By default, the client uses the API version configured in `ShopifyAPI`.  To use a different API version, set the optional `api_version` parameter.  To experiment with prerelease API features, use `"unstable"` for the API version.
 
-```ruby
-client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "unstable")
-```
+### Output
+#### Success
+If the request is successful these methods will all return a [`ShopifyAPI::Clients::HttpResponse`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_response.rb) object, which has the following methods: 
+| Methods | Type | Notes |
+|---------|------|-------|
+| `code`  |`Integer`| HTTP Response code, e.g. `200`|
+| `header` |`Hash{String, [String]}` | HTTP Response headers |
+| `body`  | `Hash{String, Untyped}`  | HTTP Response body |
+| `prev_page_info` | `String` | See [Pagination](#pagination)|
+| `next_page_info` | `String` | See [Pagination](#pagination)|
 
-Want to make calls to the Storefront API? Click [here](graphql_storefront.md)
+#### Failure
+If the request has failed, an error will be raised describing what went wrong.
+You can rescue [`ShopifyAPI::Errors::HttpResponseError`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/errors/http_response_error.rb)
+and output error messages with `errors.full_messages`
 
-# Proxy a GraphQL Query
+## Pagination
 
-If you would like to give your front end the ability to make authenticated graphql queries to the Shopify Admin API, the `shopify_api` gem makes proxying a graphql request easy! The gem provides a utility function which will accept the raw request body (a GraphQL query), the headers, and the cookies (optional). It will add authentication to the request, proxy it to the Shopify Admin API, and return a `ShopifyAPI::Clients::HttpResponse`. An example utilization of this in Rails is shown below:
+This library also supports cursor-based pagination for GraphQL Admin API requests. [Learn more about GraphQL request pagination](https://shopify.dev/docs/api/usage/pagination-graphql).
+
+After making a request, the `next_page_info` and `prev_page_info` can be found on the response object and be used in the query param in other requests.
+
+## Proxy a GraphQL Query
+
+If you would like to give your front end the ability to make authenticated graphql queries to the Shopify Admin API, the `shopify_api` gem makes proxy-ing a graphql request easy! The gem provides a utility function which will accept the raw request body (a GraphQL query), the headers, and the cookies (optional). It will add authentication to the request, proxy it to the Shopify Admin API, and return a `ShopifyAPI::Clients::HttpResponse`. An example utilization of this in Rails is shown below:
 
 ```ruby
 def proxy
   begin
     response = ShopifyAPI::Utils::GraphqlProxy.proxy_query(
+      session: session,
       headers: request.headers.to_h,
       body: request.raw_post,
       cookies: request.cookies.to_h
@@ -119,3 +161,6 @@ end
 ```
 
 **Note:** GraphQL proxying is only supported for online sessions for non-private apps, the utility will raise a `ShopifyAPI::Errors::SessionNotFoundError` if there are no existing online tokens for the provided credentials, and a `ShopifyAPI::Errors::PrivateAppError` if called from a private app.
+
+## Storefront API
+⚠️ Want to make calls to the Storefront API? [Read this](graphql_storefront.md).