shopify_api 9.0.4 → 12.4.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,44 +1,23 @@
-require 'rake'
-require "bundler/gem_tasks"
+# typed: false
+# frozen_string_literal: true
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.warning = false
-end
+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
+  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 '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 = ""
+    t.pattern = pattern
   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

@@ -0,0 +1,59 @@
+# Security Policy
+
+## Supported versions
+
+### New features
+
+New features will only be added to the main branch and will not be made available in point releases.
+
+### Bug fixes
+
+Only the latest release series will receive bug fixes. When enough bugs are fixed and its deemed worthy to release a new gem, this is the branch it happens from.
+
+### Security issues
+
+Only the latest release series will receive patches and new versions in case of a security issue.
+
+### Severe security issues
+
+For severe security issues we will provide new versions as above, and also the last major release series will receive patches and new versions. The classification of the security issue is judged by the core team.
+
+### Unsupported Release Series
+
+When a release series is no longer supported, it's your own responsibility to deal with bugs and security issues. If you are not comfortable maintaining your own versions, you should upgrade to a supported version.
+
+## Reporting a bug
+
+All security bugs in shopify repositories should be reported to [our hackerone program](https://hackerone.com/shopify)
+Shopify's whitehat program is our way to reward security researchers for finding serious security vulnerabilities in the In Scope properties listed at the bottom of this page, including our core application (all functionality associated with a Shopify store, particularly your-store.myshopify.com/admin) and certain ancillary applications.
+
+## Disclosure Policy
+
+We look forward to working with all security researchers and strive to be respectful, always assume the best and treat others as peers. We expect the same in return from all participants. To achieve this, our team strives to:
+
+- Reply to all reports within one business day and triage within two business days (if applicable)
+- Be as transparent as possible, answering all inquires about our report decisions and adding hackers to duplicate HackerOne reports
+- Award bounties within a week of resolution (excluding extenuating circumstances)
+- Only close reports as N/A when the issue reported is included in Known Issues, Ineligible Vulnerabilities Types or lacks evidence of a vulnerability
+
+**The following rules must be followed in order for any rewards to be paid:**
+
+- You may only test against shops you have created which include your HackerOne YOURHANDLE @ wearehackerone.com registered email address.
+- You must not attempt to gain access to, or interact with, any shops other than those created by you.
+- The use of commercial scanners is prohibited (e.g., Nessus).
+- Rules for reporting must be followed.
+- Do not disclose any issues publicly before they have been resolved.
+- Shopify reserves the right to modify the rules for this program or deem any submissions invalid at any time. Shopify may cancel the whitehat program without notice at any time.
+- Contacting Shopify Support over chat, email or phone about your HackerOne report is not allowed. We may disqualify you from receiving a reward, or from participating in the program altogether.
+- You are not an employee of Shopify; employees should report bugs to the internal bug bounty program.
+- You hereby represent, warrant and covenant that any content you submit to Shopify is an original work of authorship and that you are legally entitled to grant the rights and privileges conveyed by these terms. You further represent, warrant and covenant that the consent of no other person or entity is or will be necessary for Shopify to use the submitted content.
+- By submitting content to Shopify, you irrevocably waive all moral rights which you may have in the content.
+- All content submitted by you to Shopify under this program is licensed under the MIT License.
+- You must report any discovered vulnerability to Shopify as soon as you have validated the vulnerability.
+- Failure to follow any of the foregoing rules will disqualify you from participating in this program.
+
+** Please see our [Hackerone Profile](https://hackerone.com/shopify) for full details
+
+## Receiving Security Updates
+
+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

@@ -0,0 +1,32 @@
+name: shopify-api
+
+type: ruby
+
+up:
+  - 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,53 @@
+# 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",
+  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
+)
+```
+
+### 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/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/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,115 @@
+# 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
+```
+
+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,42 @@
+# Make a Storefront API call
+
+The library also allows you to send GraphQL requests to the [Shopify Storefront API](https://shopify.dev/docs/storefront-api). 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/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
+```
+
+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/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.