shopify_api 13.0.0 → 14.0.0

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:
@@ -52,19 +55,12 @@ ShopifyAPI::Context.setup(
   api_secret_key: "<api-secret-key>",
   host: "<https://application-host-name.com>",
   scope: "read_orders,read_products,etc",
-  session_storage: ShopifyAPI::Auth::FileSessionStorage.new, # See more details below
   is_embedded: true, # Set to true if you are building an embedded app
   api_version: "2022-01", # The version of the API you would like to use
   is_private: false, # Set to true if you have an existing private app
 )
 ```
 
-### Setup a Session Store
-
-In order for the Shopify API gem to properly store sessions it needs an implementation of `ShopifyAPI::Auth::SessionStorage`. We provide one implementation in the gem, `ShopifyAPI::Auth::FileSessionStorage`, which is suitable for testing/development, but isn't intended for production apps. See the [Session Storage doc](docs/usage/session_storage.md) for instructions on how to create a custom session store for a production application.
-
-Session information would is typically stored in cookies on the browser. However, due to restrictions with modern browsers we highly discourage using cookies for embedded apps. For this reason, an app needs to define a storage implementation that the library can use to store and retrieve a session given its ID. In a non-embedded app this ID will come from a cookie, whereas in an embedded app this ID will come from [App Bridge](https://shopify.dev/docs/apps/tools/app-bridge).
-
 ### Performing OAuth
 
 You need to go through OAuth as described [here](https://shopify.dev/docs/apps/auth/oauth) to create sessions for shops using your app.
@@ -74,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/ROADMAP.md

@@ -0,0 +1,10 @@
+# Roadmap
+
+|Priority|Description|Delivery Time frame|
+|---|---|---|
+|P0|Respond timely to open issues/Pull Requests|Ongoing|
+|P1|Minor API release with support for 10-23 API version|Oct 6 - 13|
+|P2|Restore dot notation access to GraphQL responses|Oct 26 - Dec 7|
+|P2|Restrospection GQL queries to define types for GQL resources|October 26- Dec 7|
+|P2|New token exchange authentication via optional feature flag|October 26- Dec 7|
+|P3|[Extract REST resources into their own gem](https://github.com/Shopify/shopify-api-ruby/issues/1194)|Oct 26 - Dec 7|

data/dev.yml

@@ -3,8 +3,9 @@ name: shopify-api
 type: ruby
 
 up:
-  - ruby: 3.0.3
-  - bundler
+  - ruby: 3.0.6
+  - bundler:
+      gemfile: Gemfile
 
 commands:
   console:

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

@@ -26,28 +26,38 @@ ShopifyAPI::Context.setup(
   api_secret_key: "<api-secret-key>",
   host_name: "<application-host-name>",
   scope: "read_orders,read_products,etc",
-  session_storage: ShopifyAPI::Auth::FileSessionStorage.new, # This is only to be used for testing, more information in session docs
   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 vesion of the API you would like to use
+  api_version: "2021-01" # The version of the API you would like to use
 )
 ```
 
-### Setup a Session Store
-
-In order for the Shopify API gem to properly store sessions it needs an implementation of `ShopifyAPI::Auth::SessionStorage`. There is one provided in the gem, `ShopifyAPI::Auth::FileSessionStorage`, this is suitable for testing, however it is not intended for production apps. See the [Session Storage doc](usage/session_storage.md) for instructions on how to create a custom session store for a production application.
-
-Normally session information would be stored in cookies on the browser. However, due to restrictions with modern browsers we highly discourage using cookies for embedded apps. For this reason, an app needs to define a storage implementation that can be used to store and retrieve a session given an ID. In a non embedded app this ID will come from a cookie however, in an embedded app this ID will come from [App Bridge](https://shopify.dev/docs/apps/tools/app-bridge)
-
 ### Performing OAuth
 
 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.
 
-### Start Making Authenticated Shopify Requests
+#### 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.
+
+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,76 @@ 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.
+
+### 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)|
+
+#### 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`
+
+## Pagination
+
+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.
+
+## Response as Struct
+By default the response body is returned as a `Hash{String, Untyped}`. If you would like to return the response body as a `Struct`, you can pass `response_as_struct: true` to the `ShopifyAPI::Context.setup` method.
+Then you can access the object with both dot and hash notation.
 
 ```ruby
-client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "unstable")
-```
+    ShopifyAPI::Context.setup(
+      api_key: ShopifyApp.configuration.api_key,
+      api_secret_key: ShopifyApp.configuration.secret,
+      ...
+      response_as_struct: true
+    )
 
-Want to make calls to the Storefront API? Click [here](graphql_storefront.md)
+    # Make a graphql query
+      response = client.query(
+        query: CREATE_PRODUCTS_MUTATION,
+        variables: {
+          input: {
+            title: random_title,
+            variants: [{ price: random_price }],
+          },
+        },
+      )
+      # Access result with dot notation
+      created_product2 = response.body.data.productCreate.product
+      # Access result with hash notation
+      created_product = response.body["data"]["productCreate"]["product"]
 
-# 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 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:
+## 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 +190,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).