shopify_api 1.0.4 → 12.3.0

data/Gemfile.lock

@@ -0,0 +1,159 @@
+PATH
+  remote: .
+  specs:
+    shopify_api (12.3.0)
+      activesupport
+      concurrent-ruby
+      hash_diff
+      httparty
+      jwt
+      oj
+      openssl
+      securerandom
+      sorbet-runtime
+      zeitwerk (~> 2.5, < 2.6.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.10)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.5.0)
+    fakefs (1.4.1)
+    hash_diff (1.1.1)
+    hashdiff (1.0.1)
+    httparty (0.20.0)
+      mime-types (~> 3.0)
+      multi_xml (>= 0.5.2)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.2)
+    jwt (2.5.0)
+    language_server-protocol (3.17.0.1)
+    method_source (1.0.0)
+    mime-types (3.4.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2022.0105)
+    minitest (5.15.0)
+    mocha (1.13.0)
+    multi_xml (0.6.0)
+    netrc (0.11.0)
+    oj (3.13.23)
+    openssl (3.0.1)
+    parallel (1.22.1)
+    parser (3.1.2.1)
+      ast (~> 2.4.1)
+    prettier_print (0.1.0)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    public_suffix (4.0.6)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rbi (0.0.15)
+      ast
+      parser (>= 2.6.4.0)
+      sorbet-runtime (>= 0.5.9204)
+      unparser
+    regexp_parser (2.5.0)
+    rexml (3.2.5)
+    rubocop (1.36.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.20.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.21.0)
+      parser (>= 3.1.1.0)
+    rubocop-shopify (2.10.1)
+      rubocop (~> 1.35)
+    rubocop-sorbet (0.6.11)
+      rubocop (>= 0.90.0)
+    ruby-lsp (0.3.2)
+      language_server-protocol (~> 3.17.0)
+      sorbet-runtime
+      syntax_tree (>= 3.4)
+    ruby-progressbar (1.11.0)
+    securerandom (0.2.1)
+    sorbet (0.5.10438)
+      sorbet-static (= 0.5.10438)
+    sorbet-runtime (0.5.10438)
+    sorbet-static (0.5.10438-universal-darwin-21)
+    sorbet-static (0.5.10438-x86_64-linux)
+    sorbet-static-and-runtime (0.5.10438)
+      sorbet (= 0.5.10438)
+      sorbet-runtime (= 0.5.10438)
+    spoom (1.1.11)
+      sorbet (>= 0.5.9204)
+      sorbet-runtime (>= 0.5.9204)
+      thor (>= 0.19.2)
+    syntax_tree (3.6.1)
+      prettier_print
+    tapioca (0.10.2)
+      bundler (>= 1.17.3)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      pry (>= 0.12.2)
+      rbi (~> 0.0.0, >= 0.0.14)
+      sorbet-static-and-runtime (>= 0.5.9204)
+      spoom (~> 1.1.0, >= 1.1.11)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.2.1)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.3.0)
+    unparser (0.6.5)
+      diff-lcs (~> 1.3)
+      parser (>= 3.1.0)
+    webmock (3.14.0)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    yard-sorbet (0.7.0)
+      sorbet-runtime (>= 0.5)
+      yard (>= 0.9)
+    zeitwerk (2.6.4)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  fakefs
+  minitest
+  mocha
+  pry-byebug
+  rake
+  rubocop
+  rubocop-shopify
+  rubocop-sorbet
+  ruby-lsp
+  shopify_api!
+  sorbet
+  tapioca
+  webmock
+
+BUNDLED WITH
+   2.3.4

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 "JadedPixel inc."
+Copyright (c) 2022 Shopify Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# Shopify API Library for Ruby
+
+<!-- ![Build Status]() -->
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+![Build Status](https://github.com/Shopify/shopify-api-ruby/workflows/CI/badge.svg?branch=main)
+
+This library provides support for Ruby [Shopify apps](https://apps.shopify.com/) to access the [Shopify Admin API](https://shopify.dev/api/admin), by making it easier to perform the following actions:
+
+- Creating [online](https://shopify.dev/apps/auth/oauth/access-modes#online-access) or [offline](https://shopify.dev/apps/auth/oauth/access-modes#offline-access) access tokens for the Admin API via OAuth
+- Making requests to the [REST API](https://shopify.dev/api/admin-rest)
+- Making requests to the [GraphQL API](https://shopify.dev/api/admin-graphql)
+- Registering/processing webhooks
+
+In addition to the Admin API, this library also allows querying the [Storefront API](https://shopify.dev/docs/storefront-api).
+
+You can use this library in any application that has a Ruby backend, since it doesn't rely on any specific framework — you can include it alongside your preferred stack and use the features that you need to build your app.
+
+**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).
+
+## Requirements
+
+To follow these usage guides, you will need to:
+
+- have a working knowledge of ruby and a web framework such as Rails or Sinatra
+- have a Shopify Partner account and development store
+- have an app already set up in your test store or partner account
+- add the URL and the appropriate redirect for your OAuth callback route to your app settings
+
+## Installation
+
+Add the following to your Gemfile:
+
+```sh
+gem "shopify_api"
+```
+
+or use [bundler](https://bundler.io):
+
+```sh
+bundle add 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: "<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/apps/tools/app-bridge).
+
+### Performing OAuth
+
+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](docs/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](docs/usage/webhooks.md) for instructions on registering and handling webhooks.
+
+### Start Making Authenticated Shopify 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).
+
+## Breaking Change Notices
+
+### 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.
+
+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/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/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
+
+See [BREAKING_CHANGES_FOR_OLDER_VERSIONS](BREAKING_CHANGES_FOR_OLDER_VERSIONS.md)
+
+## Developing this gem
+
+After cloning the repository, you can install the dependencies with bundler:
+
+```bash
+bundle install
+```
+
+To run the automated tests:
+
+```bash
+bundle exec rake test
+```
+
+We use [rubocop](https://rubocop.org) to lint/format the code. You can run it with the following command:
+
+```bash
+bundle exec rubocop
+```

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,57 +1,23 @@
-require 'rubygems'
-require 'rake'
+# typed: false
+# frozen_string_literal: true
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "shopify_api"
-    gem.summary = "ShopifyAPI is a lightweight gem for accessing the Shopify admin REST web services"
-    gem.description = File.read(File.dirname(__FILE__) + "/README.rdoc")
-    gem.email = "developers@jadedpixel.com"
-    gem.homepage = "http://github.com/Shopify/shopify_api"
-    gem.authors = ["Tobias Lütke", "Cody Fauser", "Dennis Theisen"]
-    gem.rubyforge_project = "shopify-api"
-    gem.add_dependency('activeresource', '>= 2.2.2')
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.verbose = true
-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
+namespace :test do
+  Rake::TestTask.new(:library) do |t|
+    t.test_files = FileList["test/**/*_test.rb"].exclude("test/rest/**/*.rb")
   end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
 
+  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
 
-task :default => :test
-
-require 'rake/rdoctask'
-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
+end
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "shopify_api #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-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)