shopify_api 9.5.1 → 13.1.0

data/RELEASING.md

@@ -0,0 +1,19 @@
+# Releasing ShopifyAPI
+
+1. Before releasing, make sure `sorbet` and related gems are up to date:
+   `bundle update sorbet sorbet-runtime sorbet-static tapioca --conservative`
+1. Check the Semantic Versioning page for info on how to version the new release: http://semver.org
+1. Update the version of ShopifyAPI in lib/shopify_api/version.rb
+1. Run `bundle`
+1. Add a CHANGELOG entry for the new release
+1. Commit the changes with a commit message like "Packaging for release X.Y.Z"
+1. Tag the release with the version (Leave REV blank for HEAD or provide a SHA)
+   $ git tag vX.Y.Z REV
+1. Push out the changes
+   $ git push
+1. Push out the tags
+   $ git push --tags
+1. Publish the gem using Shipit
+1. Consider if the dependency in Shopify/shopify needs updated. It's used only by the tests so is a low risk change.
+   Also consider Shopify/shopify_app whose gemspec depends on this.
+   We don't need to do this for every release, but we should try to keep them relatively up to date.

data/Rakefile

@@ -1,55 +1,23 @@
+# typed: false
 # frozen_string_literal: true
-require 'rake'
-require "bundler/gem_tasks"
-require 'rake/testtask'
-require 'rubocop/rake_task'
-
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.warning = false
-end
 
-RuboCop::RakeTask.new
+require "rake/testtask"
+require "bundler/gem_tasks"
 
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task(:rcov) do
-    abort("RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov")
+namespace :test do
+  Rake::TestTask.new(:library) do |t|
+    t.test_files = FileList["test/**/*_test.rb"].exclude("test/rest/**/*.rb")
   end
-end
 
-task(default: [:test, :rubocop, :verify_docs])
+  Rake::TestTask.new(:rest_wrappers) do |t|
+    pattern = if ENV.key?("API_VERSION")
+      "test/rest/**/#{ENV.fetch("API_VERSION")}/*.rb"
+    else
+      "test/rest/**/*.rb"
+    end
 
-require 'verify_docs'
-task(:verify_docs) do
-  unless VerifyDocs.call
-    abort("\nWARNING: docs/index.md and README.md no longer have identical content. Please correct this.")
+    t.pattern = pattern
   end
 end
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "shopify_api #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-task(:docker) do
-  cmd = "docker-compose up -d && docker exec -i -t shopify_api bash"
-  exec(cmd, err: File::NULL)
-end
+task test: ["test:library"]

data/SECURITY.md

@@ -4,7 +4,7 @@
 
 ### New features
 
-New features will only be added to the master branch and will not be made available in point releases.
+New features will only be added to the main branch and will not be made available in point releases.
 
 ### Bug fixes
 
@@ -56,4 +56,4 @@ We look forward to working with all security researchers and strive to be respec
 
 ## Receiving Security Updates
 
-To recieve all general updates to vulnerabilities, please subscribe to our hackerone [Hacktivity](https://hackerone.com/shopify/hacktivity)
+To recieve all general updates to vulnerabilities, please subscribe to our hackerone [Hacktivity](https://hackerone.com/shopify/hacktivity)

data/bin/tapioca

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")

data/dev.yml

@@ -3,9 +3,30 @@ name: shopify-api
 type: ruby
 
 up:
-  - ruby: "3.0"
+  - ruby: 3.0.3
   - bundler
 
 commands:
+  console:
+    desc: 'start a ruby shell with ShopifyAPI already loaded'
+    aliases: ['c']
+    run: bundle exec irb -Ilib -rshopify_api
+  style:
+    desc: 'run rubocop'
+    run: bundle exec rubocop
+  typecheck:
+    desc: 'run Sorbet typechecking'
+    aliases: ['tc']
+    run: bundle exec srb tc
   test:
     run: bundle exec rake test
+  sanity:
+    desc: 'run all static checks against the codebase'
+    run: bundle exec rubocop && bundle exec srb tc && bundle exec rake test
+    subcommands:
+      all:
+        desc: 'run all checks regardless of the success states of previous checks'
+        run: bundle exec rubocop; bundle exec srb tc; bundle exec rake test
+  rbi:
+    desc: 'generate .rbi files for specified gem to the project'
+    run: bin/tapioca gem

data/docs/README.md

@@ -0,0 +1,13 @@
+<!-- Make sure this file is in sync with the Getting started section in README -->
+
+# Getting started
+
+You can follow our getting started guide to learn how to use this library.
+
+- [Getting started](getting_started.md)
+- [Performing OAuth](usage/oauth.md)
+- [REST Admin API](usage/rest.md)
+- [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

@@ -0,0 +1,46 @@
+# Getting started
+
+This page will outline everything you need to know and the steps you need to follow in order to start using the Shopify Ruby API gem in your app.
+
+## Requirements
+
+- A working knowledge of ruby and a web framework such as Rails or Sinatra
+- A custom app already set up in your test store or partner account
+- We recommend `ngrok` to tunnel traffic to your localhost for testing
+
+## Installation
+
+Add the following to your Gemfile:
+
+`gem "shopify_api"`
+
+## Steps to use the Gem
+
+### Setup Shopify Context
+
+Start by 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).
+
+```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
+)
+```
+
+### 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
+
+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.
+
+### 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).

data/docs/issues.md

@@ -0,0 +1,39 @@
+# Known issues and caveats
+
+By following this guide, you will have a fully functional Shopify app. However, there are some things you should be aware of before using your new app in a production environment.
+
+## Notes on session handling
+
+Before you start writing your application, please note that the Shopify library needs to store some information for OAuth in sessions. Since each application may choose a different strategy to store information, the library cannot dictate any specific storage strategy. When calling `ShopifyAPI::Context.setup`, you'll need to provide an instance of a class that implements the `ShopifyAPI::Auth::SessionStorage` interface.
+
+This library provides a very simple implementation of that interface which stores sessions in files, `ShopifyAPI::Auth::FileSessionStorage` ([source code](../lib/shopify_api/auth/file_session_storage.rb)). This class is meant to speed up development with this library, but it is not suitable for production use, because it will lead to disk build-up as old sessions are not cleaned up.
+
+Before you deploy your app to production, it should use your selected storage method for sessions. You can do that by creating a class that implements the `SessionStorage` interface and pass that in your `Context.setup` call. Your class will need to implement the methods below.
+
+**Note**: After you create your implementation of `SessionStorage`, you should make sure to clean up old sessions periodically in your data storage. The library will delete some sessions when they are no longer useful, but it cannot guarantee that expired sessions are deleted automatically.
+
+#### `SessionStorage.storeSession`
+
+Creates **or updates** a `Session` object in your storage. This function should return a `bool` indicating whether the operation was successful.
+
+| Param     | Type      | Notes                       |
+| --------- | --------- | --------------------------- |
+| `session` | `Session` | The session object to store |
+
+#### `SessionStorage.loadSession`
+
+Fetches a `Session` object from your storage. This function should return a `Session` object, or `null` if it was not found.
+
+| Param       | Type     | Notes                         |
+| ----------- | -------- | ----------------------------- |
+| `sessionId` | `string` | The id of the session to load |
+
+#### `SessionStorage.deleteSession`
+
+Deletes a session from your storage. This function should return a `bool` indicating whether the operation was successful.
+
+| Param       | Type     | Notes                           |
+| ----------- | -------- | ------------------------------- |
+| `sessionId` | `string` | The id of the session to delete |
+
+[Back to guide index](README.md)

data/docs/usage/graphql.md

@@ -0,0 +1,121 @@
+# 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`
+
+Below is an 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
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
+# make the GraphQL query string
+query =<<~QUERY
+  {
+    products(first: 10) {
+      edges {
+        cursor
+        node {
+          id
+          title
+          onlineStoreUrl
+        }
+      }
+    }
+  }
+QUERY
+
+response = client.query(query: query)
+# do something with the response data
+```
+
+You can also make GraphQL calls that take in variables
+
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
+query = <<~QUERY
+  query testQueryWithVariables($first: Int!){
+    products(first: $first) {
+      edges {
+        cursor
+        node {
+          id
+          title
+          onlineStoreUrl
+        }
+      }
+    }
+  }
+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
+
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+# define the fragment as part of the query
+query = <<~QUERY
+  fragment ProductStuff on Product {
+    id
+    title
+    description
+    onlineStoreUrl
+  }
+  query testQueryWithVariables($first: Int){
+    products(first: $first) {
+      edges {
+        cursor
+        node {
+          ...ProductStuff
+        }
+      }
+    }
+  }
+QUERY
+variables = {
+  first: 3
+}
+response = client.query(query: query, variables: variables)
+# do something with the reponse
+```
+
+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")
+```
+
+Want to make calls to the Storefront API? Click [here](graphql_storefront.md)
+
+# 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:
+
+```ruby
+def proxy
+  begin
+    response = ShopifyAPI::Utils::GraphqlProxy.proxy_query(
+      headers: request.headers.to_h,
+      body: request.raw_post,
+      cookies: request.cookies.to_h
+    )
+
+    render json: response.body, status: response.code
+  rescue ShopifyAPI::Errors::InvalidGraphqlRequestError
+    # Handle bad request
+  rescue ShopifyAPI::Errors::SessionNotFoundError
+    # Handle no session found
+  end
+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.

data/docs/usage/graphql_storefront.md

@@ -0,0 +1,48 @@
+# Make a Storefront API call
+
+The library also allows you to send GraphQL requests to the [Shopify Storefront API](https://shopify.dev/docs/api/storefront). To do that, you can use `ShopifyAPI::Clients::Graphql::Storefront` with the current session and a `storefrontAccessToken`.
+
+You can obtain Storefront API access tokens for both private apps and sales channels. Please read [our documentation](https://shopify.dev/docs/custom-storefronts/building-with-the-storefront-api/getting-started) to learn more about Storefront Access Tokens.
+
+Below is an example of how you may query the Storefront API:
+
+```ruby
+# Load the access token as per instructions above
+storefront_access_token = ''
+# your shop domain
+shop_url = 'shop.myshopify.com'
+
+# initialize the client with session and storefront access token
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token)
+
+query = <<~QUERY
+  {
+    collections(first: 2) {
+      edges {
+        node {
+          id
+          products(first: 5) {
+            edges {
+              node {
+                id
+                title
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+QUERY
+
+response = client.query(query: query)
+# do something with the returned data
+```
+
+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::Storefront.new(shop_url, storefront_access_token, api_version: "unstable")
+```
+
+Want to make calls to the Admin API? Click [here](graphql.md)

data/docs/usage/oauth.md

@@ -0,0 +1,104 @@
+# Performing OAuth
+
+Once the library is set up for your project, you'll be able to use it to start adding functionality to your app. The first thing your app will need to do is to obtain an access token to the Admin API by performing the OAuth process.
+
+To do this, you can follow the steps below.
+For more information on authenticating a Shopify app please see the [Types of Authentication](https://shopify.dev/docs/apps/auth#types-of-authentication) page.
+
+## Add a route to start OAuth
+
+The route for starting the OAuth process (in this case `/login`) will use the library's `begin_auth` method. The method will return an `auth_route` URI that will be used for redirecting the user to the Shopify Authentication screen and a session cookie to store on the user's browser. These return values will be a hash in the form of {`auth_route`: `String`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`}
+
+| Parameter      | Type                   | Required? | Default Value | Notes                                                                                                       |
+| -------------- | ---------------------- | :-------: | :-----------: | ----------------------------------------------------------------------------------------------------------- |
+| `shop`          | `String`               |    Yes    |       -       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                                            |
+| `redirect_path` | `String`               |    Yes    |       -       | The redirect path used for callback with a leading `/`. The route should be allowed under the app settings. |
+| `is_online`     | `Boolean`              |    No     |    `true`     | `true` if the session is online and `false` otherwise.                                                      |
+
+Your app should take the returned values from the `begin_auth` function and redirect the user to url defined by `auth_route` and set the cookie in the user's browser. We strongly recommend that you use secure, httpOnly cookies for this to help prevent session hijacking.
+
+An example is shown below in a Rails app but these steps could be applied in any framework:
+
+```ruby
+class ShopifyAuthController < ApplicationController
+  def login
+    shop = request.headers["Shop"]
+
+    auth_response = ShopifyAPI::Auth::Oauth.begin_auth(shop: domain, redirect_path: "/auth/callback")
+
+    cookies[auth_response[:cookie].name] = {
+      expires: auth_response[:cookie].expires,
+      secure: true,
+      http_only: true,
+      value: auth_response[:cookie].value
+    }
+
+    head 307
+    response.set_header("Location", auth_response[:auth_route])
+  end
+end
+```
+
+## Add your OAuth callback route
+
+After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route (which you provided as a parameter to `begin_auth`, above). Your app will now use the provided `validate_auth_callback` method to finalize the OAuth process. This method returns a hash containing the new session and a cookie to be set in the browser in form of {`session`: `ShopifyAPI::Auth::Session`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`}.
+
+An example is shown below in a Rails app but these steps could be applied in any framework:
+
+```ruby
+def callback
+  begin
+    auth_result = ShopifyAPI::Auth::Oauth.validate_auth_callback(
+      cookies: cookies.to_h,
+      auth_query: ShopifyAPI::Auth::Oauth::AuthQuery.new(request.parameters.symbolize_keys.except(:controller, :action))
+    )
+
+    cookies[auth_result[:cookie].name] = {
+      expires: auth_result[:cookie].expires,
+      secure: true,
+      http_only: true,
+      value: auth_result[:cookie].value
+    }
+
+    puts("OAuth complete! New access token: #{auth_result[:session].access_token}")
+
+    head 307
+    response.set_header("Location", "<some-redirect-url>")
+  rescue => e
+    puts(e.message)
+    head 500
+  end
+end
+```
+## Fetching sessions
+
+You can use the OAuth methods to create both offline and online sessions. Once the process is completed, the session will be stored as per your `Context.session_storage`, and can be retrieved with `SessionUtils` class methods.
+
+- To load current session, you can use the following method:
+
+```ruby
+ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: <auth-header>, cookies: <cookies>, is_online: <true|false>)
+```
+
+Accepted arguments:
+| Parameter   | Type                      | Notes                                                                                                                                                                     |
+| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth_header`   | `String`    | JWT token will be extracted from `auth_header` to load session for embedded apps. If JWT token is not provided this methods will try with `cookies`. Only required if trying to load, an embedded session. |
+| `cookies`   | `Hash(String, String)`    | The cookies from the HTTP request. A session cookie named `shopify_app_session` is used to load session for non-embedded apps. Can be omitted if loading and embedded session without falling back on cookies |
+| `is_online` | `Boolean`                 | Whether to load online or offline sessions. Defaults to `false` |
+
+This method will return a `ShopifyAPI::Auth::Session`  if a session exists. Either a proper token or a proper cookie must be present.
+
+- To load offline session, you can use the following method:
+
+```ruby
+ShopifyAPI::Utils::SessionUtils.load_offline_session(shop)
+```
+
+Accepted arguments:
+| Parameter           | Type      | Notes                                                                                                                                                                     |
+| ------------------- | --------- | --------------------------------------------- |
+| `shop`              | `String`  | The shop url to find the offline session for. |
+| `include_expired`   | `Boolean` | Include expired sessions or not.              |
+
+This method will return a `ShopifyAPI::Auth::Session` if a session exists and `nil` otherwise. This method **does not** perform any validation on the shop domain, so it **must not** rely on user input for the domain. This method is typically meant to be used in background tasks like webhooks, where the data is expected to have been validated when the task was enqueued.