shopify_app 12.0.0 → 17.2.0

data/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to the Shopify App gem
+
+The following is a set of guidelines for contributing to the Shopify App gem. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request.
+
+#### Table of contents
+
+[I just have a question!](#i-just-have-a-question)
+
+[How can I contribute?](#how-can-i-contribute)
+  * [Reporting bugs](#reporting-bugs)
+  * [Suggesting or requesting improvements](#suggesting-or-requesting-improvements)
+  * [Pull requests](#pull-requests)
+
+## I just have a question!
+
+> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below.
+
+Shopify has an official message board with dedicated forums to discuss all things apps, APIs, SDKs and more.
+
+#### Shopify Community forum links
+
+* [Shopify Community](https://community.shopify.com)
+* [Shopify Apps](https://community.shopify.com/c/Shopify-Apps/bd-p/shopify-apps)
+* [Shopify APIs & SDKs](https://community.shopify.com/c/Shopify-APIs-SDKs/bd-p/shopify-apis-and-technology)
+
+If you prefer to chat instead, join the [Shopify Partners Slack Community group](https://www.shopify.com/partners/community#conversation). This Slack group hosts an active community of thousands of app developers.
+
+By participating in the Community forum or Slack group, you agree to adhere to the forum [Code of Conduct](https://community.shopify.com/c/Announcements/Code-of-Conduct/m-p/491969#M23) outlined.
+
+## How can I contribute?
+
+### Reporting bugs
+
+This section guides you through submitting a bug report for the Shopify App gem. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
+
+#### Before submitting a bug report
+
+* **Check the [troubleshooting guide](/docs/Troubleshooting.md).** You may be able to troubleshoot the issue you're facing.
+* **Check the [Shopify Community links](#shopify-community-forum-links) to search for your issue.** This problem may have been reported before and solved on the Shopify forum.
+* **Perform a cursory search for similar issues.** You may find that the same problem (or a similar one) has been filed already as an issue.
+
+#### How do I submit a good bug report?
+
+Bugs are tracked as GitHub issues. Create an issue and provide the following information by filling in the [bug-report template](/.github/ISSUE_TEMPLATE/bug-report.md).
+
+Explain the problem and include additional details to help maintainers reproduce the problem:
+
+* **Use a clear and descriptive title** for the issue to identify the problem.
+* **Describe the exact steps which reproduce the problem** in as many details as possible.
+* **Provide specific examples to demonstrate the steps.** Include links to files, or copy/pasteable snippets. If you're providing snippets in the issue, use Markdown code blocks.
+* **Describe the behavior you observed** after following the steps and point out what exactly is the problem with that behavior.
+* **Explain which behavior you expected to see** instead and why.
+* **Include screenshots and animated GIFs** where possible.
+* **Redact any private information** from your logs and issue description. This includes things like API keys, API secrets, and any access tokens.
+
+### Suggesting or requesting improvements
+
+If you have a suggestion for the Shopify App gem or a feature request, provide the appropriate information by filling out the [feature-request template](/.github/ISSUE_TEMPLATE/feature-request.md).
+
+### Pull requests
+
+The process described here has several goals:
+
+* Maintain the Shopify App gem's quality
+* Fix problems that are important to app developers
+* Enable a sustainable system for the Shopify App gem's maintainers to review contributions
+
+Please follow these steps to have your contribution considered by the maintainers:
+
+* Follow all instructions in the [pull request template](/.github/PULL_REQUEST_TEMPLATE.md)
+* After you submit your pull request, verify that all status checks are passing
+  * <details>
+      <summary>What if the status checks are failing?</summary>
+
+      While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
+    </details>

data/Gemfile

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in shopify_app.gemspec
 gemspec
 
 gem 'rails-controller-testing', group: :test
+
+group :rubocop do
+  gem 'rubocop-shopify', require: false
+end

data/Gemfile.lock

@@ -0,0 +1,257 @@
+PATH
+  remote: .
+  specs:
+    shopify_app (17.2.0)
+      browser_sniffer (~> 1.2.2)
+      jwt (~> 2.2.1)
+      omniauth-shopify-oauth2 (~> 2.2.2)
+      rails (> 5.2.1, < 6.2)
+      redirect_safely (~> 1.0)
+      shopify_api (~> 9.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.1.3.1)
+      actionpack (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.1.3.1)
+      actionpack (= 6.1.3.1)
+      activejob (= 6.1.3.1)
+      activerecord (= 6.1.3.1)
+      activestorage (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      mail (>= 2.7.1)
+    actionmailer (6.1.3.1)
+      actionpack (= 6.1.3.1)
+      actionview (= 6.1.3.1)
+      activejob (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.1.3.1)
+      actionview (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      rack (~> 2.0, >= 2.0.9)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.1.3.1)
+      actionpack (= 6.1.3.1)
+      activerecord (= 6.1.3.1)
+      activestorage (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      nokogiri (>= 1.8.5)
+    actionview (6.1.3.1)
+      activesupport (= 6.1.3.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.1.3.1)
+      activesupport (= 6.1.3.1)
+      globalid (>= 0.3.6)
+    activemodel (6.1.3.1)
+      activesupport (= 6.1.3.1)
+    activemodel-serializers-xml (1.0.2)
+      activemodel (> 5.x)
+      activesupport (> 5.x)
+      builder (~> 3.1)
+    activerecord (6.1.3.1)
+      activemodel (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+    activeresource (5.1.1)
+      activemodel (>= 5.0, < 7)
+      activemodel-serializers-xml (~> 1.0)
+      activesupport (>= 5.0, < 7)
+    activestorage (6.1.3.1)
+      actionpack (= 6.1.3.1)
+      activejob (= 6.1.3.1)
+      activerecord (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      marcel (~> 1.0.0)
+      mini_mime (~> 1.0.2)
+    activesupport (6.1.3.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.1)
+    binding_of_caller (0.8.0)
+      debug_inspector (>= 0.0.1)
+    browser_sniffer (1.2.2)
+    builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.8)
+    crack (0.4.4)
+    crass (1.0.6)
+    debug_inspector (0.0.3)
+    erubi (1.10.0)
+    faraday (1.3.0)
+      faraday-net_http (~> 1.0)
+      multipart-post (>= 1.2, < 3)
+      ruby2_keywords
+    faraday-net_http (1.0.1)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    graphql (1.12.6)
+    graphql-client (0.16.0)
+      activesupport (>= 3.0)
+      graphql (~> 1.8)
+    hashdiff (1.0.1)
+    hashie (4.1.0)
+    i18n (1.8.9)
+      concurrent-ruby (~> 1.0)
+    jwt (2.2.2)
+    loofah (2.9.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.0)
+    method_source (0.9.2)
+    mini_mime (1.0.3)
+    mini_portile2 (2.5.0)
+    minitest (5.14.4)
+    mocha (1.11.2)
+    multi_json (1.15.0)
+    multi_xml (0.6.0)
+    multipart-post (2.1.1)
+    nio4r (2.5.7)
+    nokogiri (1.11.2)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    oauth2 (1.4.7)
+      faraday (>= 0.8, < 2.0)
+      jwt (>= 1.0, < 3.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    omniauth (1.9.1)
+      hashie (>= 3.4.6)
+      rack (>= 1.6.2, < 3)
+    omniauth-oauth2 (1.5.0)
+      oauth2 (~> 1.1)
+      omniauth (~> 1.2)
+    omniauth-shopify-oauth2 (2.2.3)
+      activesupport
+      omniauth-oauth2 (~> 1.5.0)
+    parallel (1.20.1)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-nav (0.3.0)
+      pry (>= 0.9.10, < 0.13.0)
+    pry-stack_explorer (0.4.9.3)
+      binding_of_caller (>= 0.7)
+      pry (>= 0.9.11)
+    public_suffix (4.0.6)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.1.3.1)
+      actioncable (= 6.1.3.1)
+      actionmailbox (= 6.1.3.1)
+      actionmailer (= 6.1.3.1)
+      actionpack (= 6.1.3.1)
+      actiontext (= 6.1.3.1)
+      actionview (= 6.1.3.1)
+      activejob (= 6.1.3.1)
+      activemodel (= 6.1.3.1)
+      activerecord (= 6.1.3.1)
+      activestorage (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      bundler (>= 1.15.0)
+      railties (= 6.1.3.1)
+      sprockets-rails (>= 2.0.0)
+    rails-controller-testing (1.0.5)
+      actionpack (>= 5.0.1.rc1)
+      actionview (>= 5.0.1.rc1)
+      activesupport (>= 5.0.1.rc1)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.1.3.1)
+      actionpack (= 6.1.3.1)
+      activesupport (= 6.1.3.1)
+      method_source
+      rake (>= 0.8.7)
+      thor (~> 1.0)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    rb-readline (0.5.5)
+    redirect_safely (1.0.0)
+      activemodel
+    regexp_parser (2.0.0)
+    rexml (3.2.4)
+    rubocop (1.5.2)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.3.0)
+      parser (>= 2.7.1.5)
+    rubocop-shopify (1.0.7)
+      rubocop (~> 1.4)
+    ruby-progressbar (1.10.1)
+    ruby2_keywords (0.0.4)
+    shopify_api (9.4.1)
+      activeresource (>= 4.1.0, < 6.0.0)
+      graphql-client
+      rack
+    sprockets (4.0.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.2)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.4.2)
+    thor (1.1.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (1.7.0)
+    webmock (3.9.1)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    websocket-driver (0.7.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  minitest
+  mocha
+  pry
+  pry-nav
+  pry-stack_explorer
+  rails-controller-testing
+  rake
+  rb-readline
+  rubocop-shopify
+  shopify_app!
+  sqlite3 (~> 1.4)
+  webmock
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -1,545 +1,130 @@
-Shopify App
-===========
-[![Version][gem]][gem_url] [![Build Status](https://travis-ci.org/Shopify/shopify_app.png)](https://travis-ci.org/Shopify/shopify_app)
+# Shopify App
+
+[![Version][gem]][gem_url] [![Build Status](https://github.com/Shopify/shopify_app/workflows/CI/badge.svg)](https://github.com/Shopify/shopify_app/actions?query=workflow%3ACI) ![Supported Rails version][supported_rails_version]
 
 [gem]: https://img.shields.io/gem/v/shopify_app.svg
 [gem_url]: https://rubygems.org/gems/shopify_app
+[supported_rails_version]: https://img.shields.io/badge/rails-%3C6.2.0-orange
 
+This gem builds Rails applications that can be embedded in the Shopify Admin.
 
-Shopify Application Rails engine and generator
-
-#### NOTE : Versions 8.0.0 through 8.2.3 contained a CSRF vulnerability that was addressed in version 8.2.4. Please update to version 8.2.4 if you're using an old version.
+[Introduction](#introduction) | 
+[Requirements](#requirements) | 
+[Usage](#usage) | 
+[Documentation](#documentation) | 
+[Contributing](/CONTRIBUTING.md) |
+[License](/LICENSE)
 
-Table of Contents
------------------
-- [Introduction](#introduction)
-- [Become a Shopify App Developer](#become-a-shopify-app-developer)
-- [Installation](#installation)
-- [Generators](#generators)
-- [Mounting the Engine](#mounting-the-engine)
-- [Authentication](#authentication)
-- [WebhooksManager](#webhooksmanager)
-- [ScripttagsManager](#scripttagsmanager)
-- [RotateShopifyTokenJob](#rotateshopifytokenjob)
-- [App Tunneling](#app-tunneling)
-- [AppProxyVerification](#appproxyverification)
-- [Troubleshooting](#troubleshooting)
-- [Testing an embedded app outside the Shopify admin](#testing-an-embedded-app-outside-the-shopify-admin)
-- [Questions or problems?](#questions-or-problems-)
-- [Rails 6 Compatibility](#rails-6-compatibility)
-- [Upgrading from 8.6 to 9.0.0](#upgrading-from-86-to-900)
+## Introduction
 
-Introduction
------------
-Get started with the [Shopify Admin API](https://help.shopify.com/en/api/getting-started) faster; This gem includes a Rails Engine and generators for writing Rails applications using the Shopify API. The Engine provides a SessionsController and all the required code for authenticating with a shop via Oauth (other authentication methods are not supported).
+This gem includes a Rails engine, generators, modules, and mixins that help create Rails applications that work with Shopify APIs. The [Shopify App Rails engine](/docs/shopify_app/engine.md) provides all the code required to implement OAuth with Shopify. The [default Shopify App generator](/docs/shopify_app/generators.md#-environment-rails-generate-shopify_app) builds an app that can be embedded in the Shopify Admin and secures it with [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens).
 
-*Note: It's recommended to use this on a new Rails project, so that the generator won't overwrite/delete your files.*
+<!-- This section is linked to in `templates/shopify_app.rb.tt`. Be careful renaming this heading. -->
+## Requirements
 
-Learn how to create and deploy a new Shopify App to Heroku with our [quickstart guide](https://github.com/Shopify/shopify_app/blob/master/docs/Quickstart.md), or dive in in less than 5 minutes with this quickstart video:
+> **Rails compatibility** 
+> * Rails 6.1 or above is not yet supported due to the new `cookies_same_site_protection` setting. 
+> * Use Shopify App `<= v7.2.8` if you need to work with Rails 4.
 
-[https://www.youtube.com/watch?v=yGxeoAHlQOg](https://www.youtube.com/watch?v=yGxeoAHlQOg)
+To become a Shopify app developer, you will need a [Shopify Partners](https://www.shopify.com/partners) account. Explore the [Shopify dev docs](https://shopify.dev/concepts/shopify-introduction) to learn more about [building Shopify apps](https://shopify.dev/concepts/apps).
 
-Become a Shopify App Developer
---------------------------------
-To become a Shopify App Developer you'll need a [Shopify Partner account.](http://shopify.com/partners) If you don't have a Shopify Partner account, head to http://shopify.com/partners to create one before you start.
+This gem requires that you have the following credentials:
 
-Once you have a Partner account, [create a new application in the Partner Dashboard](https://help.shopify.com/en/api/tools/partner-dashboard/your-apps) to get an API key and other API credentials. 
+- **Shopify API key:** The API key app credential specified in your [Shopify Partners dashboard](https://partners.shopify.com/organizations). 
+- **Shopify API secret:** The API secret key app credential specified in your [Shopify Partners dashboard](https://partners.shopify.com/organizations). 
 
-To create an application for development set your new app's `App URL` to the URL provided by [your tunnel](#app-tunneling), ensuring that you use `https://`. If you are not planning to embed your app inside the Shopify admin or receive webhooks, set your redirect URL to `http://localhost:3000/` and the `Whitelisted redirection URL(s)` to contain `<App URL>/auth/shopify/callback`. 
+## Usage
 
-Installation
-------------
-To get started add `shopify_app` to your Gemfile and run `bundle install`:
+1. To get started, create a new Rails app:
 
 ``` sh
-# Create a new rails app
 $ rails new my_shopify_app
-$ cd my_shopify_app
-
-# Add the gem shopify_app to your Gemfile
-$ echo "gem 'shopify_app'" >> Gemfile
-$ bundle install
-```
-
-Now we are ready to run any of the [generators](#generators) included with `shopify_app`. The following section explains the generators and what you can do with them.
-
-
-#### Rails Compatibility
-
-The lastest version of shopify_app is compatible with Rails `>= 5`. Use version `<= v7.2.8` if you need to work with Rails 4.
-
-
-Generators
-----------
-
-### Default Generator
-
-The default generator will run the `install`, `shop`, and `home_controller` generators. This is the recommended way to start a new app from scratch:
-
-```sh
-$ rails generate shopify_app
-```
-
-After running the generator, you will need to run `rails db:migrate` to add new tables to your database. You can start your app with `bundle exec rails server` and install your app by visiting `http://localhost` in your web browser. 
-
-### API Keys
-
-The default and install generators have been updated to source Shopify API key and secret from an Environment (`.env`) variables file, which you will need to create with the following format:
-
-```
-SHOPIFY_API_KEY=your api key
-SHOPIFY_API_SECRET=your api secret
 ```
 
-These values can be found on the "App Setup" page in the [Shopify Partners Dashboard][dashboard]. If you are checking your code into a code repository, ensure your `.gitignore` prevents your `.env` file from being checked into any publicly accessible code. 
-
-### Install Generator
+2. Add the Shopify App gem to `my_shopify_app`'s Gemfile.
 
 ```sh
-$ rails generate shopify_app:install
-
-# or optionally with arguments:
-
-$ rails generate shopify_app:install
+$ bundle add shopify_app
 ```
 
-Other options include:
-* `application_name` - the name of your app, it can be supplied with or without double-quotes if a whitespace is present. (e.g. `--application_name Example App` or `--application_name "Example App"`)
-* `scope` - the Oauth access scope required for your app, eg **read_products, write_orders**. *Multiple options* need to be delimited by a comma-space, and can be supplied with or without double-quotes
-(e.g. `--scope read_products, write_orders, write_products` or `--scope "read_products, write_orders, write_products"`)
-For more information, refer the [docs](http://docs.shopify.com/api/tutorials/oauth).
-* `embedded` - the default is to generate an [embedded app](http://docs.shopify.com/embedded-app-sdk), if you want a legacy non-embedded app then set this to false, `--embedded false`
-
-You can update any of these settings later on easily, the arguments are simply for convenience.
-
-The generator adds ShopifyApp and the required initializers to the host Rails application.
-
-After running the `install` generator, you can start your app with `bundle exec rails server` and install your app by visiting localhost.
+3. Create a `.env` file in the root of `my_shopify_app` to specify your Shopify API credentials:
 
-
-### Home Controller Generator
-
-```sh
-$ rails generate shopify_app:home_controller
 ```
-
-This generator creates an example home controller and view which fetches and displays products using the Shopify API
-
-
-### App Proxy Controller Generator
-
-```sh
-$ rails generate shopify_app:app_proxy_controller
+SHOPIFY_API_KEY=<Your Shopify API key>
+SHOPIFY_API_SECRET=<Your Shopify API secret>
 ```
 
-This optional generator, not included with the default generator, creates the app proxy controller to handle proxy requests to the app from your shop storefront, modifies 'config/routes.rb' with a namespace route, and an example view which displays current shop information using the LiquidAPI
+> In a development environment, you can use a gem like `dotenv-rails` to manage environment variables. 
 
-### Marketing Extension Generator
+4. Run the default Shopify App generator to create an app that can be embedded in the Shopify Admin:
 
 ```sh
-$ rails generate shopify_app:add_marketing_activity_extension
-```
-
-This will create a controller with the endpoints required to build a [marketing activities extension](https://help.shopify.com/en/api/embedded-apps/app-extensions/shopify-admin/marketing-activities). The extension will be generated with a base url at `/marketing_activities`, which should also be configured in partners.
-
-### Controllers, Routes and Views
-
-The last group of generators are for your convenience if you want to start overriding code included as part of the Rails engine. For example by default the engine provides a simple SessionController, if you run the `rails generate shopify_app:controllers` generator then this code gets copied out into your app so you can start adding to it. Routes and views follow the exact same pattern.
-
-Mounting the Engine
--------------------
-
-Mounting the Engine will provide the basic routes to authenticating a shop with your application. By default it will provide:
-
-| Verb   | Route                         | Action                       |
-|--------|-------------------------------|------------------------------|
-|GET     |'/login'                       |Login                         |
-|POST    |'/login'                       |Login                         |
-|GET     |'/auth/shopify/callback'       |Authenticate Callback         |
-|GET     |'/logout'                      |Logout                        |
-|POST    |'/webhooks/:type'              |Webhook Callback              |
-
-### Nested Routes
-
-The engine may also be mounted at a nested route, for example:
-
-```ruby
-mount ShopifyApp::Engine, at: '/nested'
-```
-
-This will create the Shopify engine routes under the specified subpath. You'll also need to make some updates to your `shopify_app.rb` and `omniauth.rb` initializers. First update the shopify_app initializer to include a custom `root_url` e.g.:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.root_url = '/nested'
-end
-```
-
-then update the omniauth initializer to include a custom `callback_path` e.g.:
-
-```ruby
-provider :shopify,
-  ShopifyApp.configuration.api_key,
-  ShopifyApp.configuration.secret,
-  scope: ShopifyApp.configuration.scope,
-  callback_path: '/nested/auth/shopify/callback'
-```
-
-You may also need to change your `config/routes.rb` to render a view for `/nested`, since this is what will be rendered in the Shopify Admin of any shops that have installed your app.  The engine itself doesn't have a view for this, so you'll need something like this:
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  root :to => 'something_else#index'
-  get "/nested", to: "home#index"
-  mount ShopifyApp::Engine, at: '/nested'
-end
-```
-
-Finally, note that if you do this, to add your app to a store, you must navigate to `/nested` in order to render the `Enter your shop domain to log in or install this app.` UI.
-
-### Custom login URL
-
-While you can customize the login view by creating a `/app/views/shopify_app/sessions/new.html.erb` file, you may also want to customize the URL entirely. You can modify your `shopify_app.rb` initializer to provide a custom `login_url` e.g.:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.login_url = 'https://my.domain.com/nested/login'
-end
-```
-
-Authentication
---------------
-
-### ShopifyApp::SessionRepository
-
-`ShopifyApp::SessionRepository` allows you as a developer to define how your sessions are stored and retrieved for shops. The `SessionRepository` is configured in the `config/initializers/shopify_app.rb` file and can be set to any object that implements `self.store(auth_session, *args)` which stores the session and returns a unique identifier and `self.retrieve(id)` which returns a `ShopifyAPI::Session` for the passed id. These methods are already implemented as part of the `ShopifyApp::SessionStorage` concern, but can be overridden for custom implementation.
-
-If you only run the install generator then by default you will have an in memory store but it **won't work** on multi-server environments including Heroku. For multi-server environments, implement one of the following token-storage strategies.
-
-#### Shop-based token storage
-Storing tokens on the store model means that any user login associated to the store will have equal access levels to whatever the original user granted the app.
-```sh
-$ rails generate shopify_app:shop_model
-```
-This will generate a shop model which will be the storage for the tokens necessary for authentication.
-
-#### User-based token storage
-A more granular control over level of access per user on an app might be necessary, to which the shop-based token strategy is not sufficient. Shopify supports a user-based token storage strategy where a unique token to each user can be managed.
-```sh
-$ rails generate shopify_app:user_model
-```
-This will generate a user model which will be the storage for the tokens necessary for authentication.
-
-The current Shopify user will be stored in the rails session at `session[:shopify_user]`
-
-In this mode, The `self.store(auth_session, *args)` will be invoked with a Shopify User object hash, which is then used to store the token as part of a user record, rather than a store record.
-
-This will change the type of token that Shopify returns and it will only be valid for a short time. Read more about `Online access` [here](https://help.shopify.com/api/getting-started/authentication/oauth). Note that this means you won't be able to use this token to respond to Webhooks.
-
-#### Migrating from shop-based to user-based token strategy
-After running the generator, ensure that configuration settings are successfully changed:
-
-```ruby
-# In the `omniauth.rb` initializer:
-provider :shopify,
-  ShopifyApp.configuration.api_key,
-  ShopifyApp.configuration.secret,
-  scope: ShopifyApp.configuration.scope,
-  per_user_permissions: true
-
-# In the `shopify_app.rb` initializer:
-config.session_repository = 'User'
-config.per_user_tokens = true
-```
-
-### Authenticated
-
-The engine provides a `ShopifyApp::Authenticated` concern which should be included in any controller that is intended to be behind Shopify OAuth. It adds `before_action`s to ensure that the user is authenticated and will redirect to the Shopify login page if not. It is best practice to include this concern in a base controller inheriting from your `ApplicationController`, from which all controllers that require Shopify authentication inherit.
-
-For backwards compatibility, the engine still provides a controller called `ShopifyApp::AuthenticatedController` which includes the `ShopifyApp::Authenticated` concern. Note that it inherits directly from `ActionController::Base`, so you will not be able to share functionality between it and your application's `ApplicationController`.
-
-### AfterAuthenticate Job
-
-If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing (note that we already provide support for automatically creating Webhooks and Scripttags). To configure the after authenticate job update your initializer as follows:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.after_authenticate_job = { job: "Shopify::AfterAuthenticateJob" }
-end
-```
-
-The job can be configured as either a class or a class name string.
-
-If you need the job to run synchronously add the `inline` flag:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.after_authenticate_job = { job: Shopify::AfterAuthenticateJob, inline: true }
-end
-```
-
-We've also provided a generator which creates a skeleton job and updates the initializer for you:
-
-```
-bin/rails g shopify_app:add_after_authenticate_job
-```
-
-If you want to perform that action only once, e.g. send a welcome email to the user when they install the app, you should make sure that this action is idempotent, meaning that it won't have an impact if run multiple times.
-
-
-WebhooksManager
----------------
-
-ShopifyApp can manage your app's webhooks for you if you set which webhooks you require in the initializer:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.webhooks = [
-    {topic: 'carts/update', address: 'https://example-app.com/webhooks/carts_update'}
-  ]
-end
-```
-
-When the oauth callback is completed successfully ShopifyApp will queue a background job which will ensure all the specified webhooks exist for that shop. Because this runs on every oauth callback it means your app will always have the webhooks it needs even if the user uninstalls and re-installs the app.
-
-ShopifyApp also provides a WebhooksController that receives webhooks and queues a job based on the received topic. For example if you register the webhook from above then all you need to do is create a job called `CartsUpdateJob`. The job will be queued with 2 params: `shop_domain` and `webhook` (which is the webhook body).
-
-If you would like to namespace your jobs you may set `webhook_jobs_namespace` in the config. For example if your app handles webhooks from other ecommerce applications as well, and you want Shopify cart update webhooks to be processed by a job living in `jobs/shopify/webhooks/carts_update_job.rb` rather than `jobs/carts_update_job.rb`):
-
-```ruby
-ShopifyApp.configure do |config|
-  config.webhook_jobs_namespace = 'shopify/webhooks'
-end
-```
-
-If you are only interested in particular fields, you can optionally filter the data sent by Shopify by specifying the `fields` parameter in `config/webhooks`. Note that you will still receive a webhook request from Shopify every time the resource is updated, but only the specified fields will be sent.
-
-```ruby
-ShopifyApp.configure do |config|
-  config.webhooks = [
-    {topic: 'products/update', address: 'https://example-app.com/webhooks/products_update', fields: ['title', 'vendor']}
-  ]
-end
-```
-
-If you'd rather implement your own controller then you'll want to use the WebhookVerification module to verify your webhooks, example:
-
-```ruby
-class CustomWebhooksController < ApplicationController
-  include ShopifyApp::WebhookVerification
-
-  def carts_update
-    params.permit!
-    SomeJob.perform_later(shop_domain: shop_domain, webhook: webhook_params.to_h)
-    head :no_content
-  end
-
-  private
-
-  def webhook_params
-    params.except(:controller, :action, :type)
-  end
-end
-```
-
-The module skips the `verify_authenticity_token` before_action and adds an action to verify that the webhook came from Shopify. You can now add a post route to your application pointing to the controller and action to accept the webhook data from Shopify.
-
-The WebhooksManager uses ActiveJob, if ActiveJob is not configured then by default Rails will run the jobs inline. However it is highly recommended to configure a proper background processing queue like sidekiq or resque in production.
-
-ShopifyApp can create webhooks for you using the `add_webhook` generator. This will add the new webhook to your config and create the required job class for you.
-
-```
-rails g shopify_app:add_webhook -t carts/update -a https://example.com/webhooks/carts_update
-```
-
-where `-t` is the topic and `-a` is the address the webhook should be sent to.
-
-ScripttagsManager
------------------
-
-As with webhooks, ShopifyApp can manage your app's scripttags for you by setting which scripttags you require in the initializer:
-
-```ruby
-ShopifyApp.configure do |config|
-  config.scripttags = [
-    {event:'onload', src: 'https://my-shopifyapp.herokuapp.com/fancy.js'},
-    {event:'onload', src: ->(domain) { dynamic_tag_url(domain) } }
-  ]
-end
-```
-
-You also need to have write_script_tags permission in the config scope in order to add script tags automatically:
-
-```ruby
- config.scope = '... , write_script_tags'
-```
-
-Scripttags are created in the same way as the Webhooks, with a background job which will create the required scripttags.
-
-If `src` responds to `call` its return value will be used as the scripttag's source. It will be called on scripttag creation and deletion.
-
-RotateShopifyTokenJob
----------------------
-
-If your Shopify secret key is leaked, you can use the RotateShopifyTokenJob to perform [API Credential Rotation](https://help.shopify.com/en/api/getting-started/authentication/oauth/api-credential-rotation).
-
-Before running the job, you'll need to generate a new secret key from your Shopify Partner dashboard, and update the `/config/initializers/shopify_app.rb` to hold your new and old secret keys:
-
-```ruby
-config.secret = Rails.application.secrets.shopify_secret
-config.old_secret = Rails.application.secrets.old_shopify_secret
+$ rails generate shopify_app
 ```
 
-We've provided a generator which creates the job and an example rake task:
+5. Run a migration to create the necessary tables in your database:
 
 ```sh
-bin/rails g shopify_app:rotate_shopify_token_job
+$ rails db:migrate
 ```
 
-The generated rake task will be found at `lib/tasks/shopify/rotate_shopify_token.rake` and is provided strictly for example purposes. It might not work with your application out of the box without some configuration.
-
-⚠️ Note: if you are updating `shopify_app` from a version prior to 8.4.2 (and do not wish to run the default/install generator again), you will need to add [the following line](https://github.com/Shopify/shopify_app/blob/4f7e6cca2a472d8f7af44b938bd0fcafe4d8e88a/lib/generators/shopify_app/install/templates/shopify_provider.rb#L18) to `config/intializers/omniauth.rb`:
-
-```ruby
-strategy.options[:old_client_secret] = ShopifyApp.configuration.old_secret
-```
-
-App Tunneling
--------------
-
-Your local app needs to be accessible from the public Internet in order to install it on a Shopify store, to use the [App Proxy Controller](#app-proxy-controller-generator) or receive Webhooks. 
-
-Use a tunneling service like [ngrok](https://ngrok.com/), [Forward](https://forwardhq.com/), [Beeceptor](https://beeceptor.com/), [Mockbin](http://mockbin.org/), or [Hookbin](https://hookbin.com/) to make your development environment accessible to the internet.
-
-For example with [ngrok](https://ngrok.com/), run this command to set up a tunnel proxy to Rails' default port:
+6. Run the app:
 
 ```sh
-ngrok http 3000
+$ rails server
 ```
 
-AppProxyVerification
---------------------
+See [*Quickstart*](/docs/Quickstart.md) to learn how to install your app on a shop.
 
-The engine provides a mixin for verifying incoming HTTP requests sent via an App Proxy. Any controller that `include`s `ShopifyApp::AppProxyVerification` will verify that each request has a valid `signature` query parameter that is calculated using the other query parameters and the app's shared secret.
+This app implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) with Shopify to authenticate requests made to Shopify APIs. By default, this app is configured to use [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens) to authenticate merchants when embedded in the Shopify Admin.
 
-### Recommended Usage
+See [*Generators*](/docs/shopify_app/generators.md) for a complete list of generators available to Shopify App.
 
-The App Proxy Controller Generator automatically adds the mixin to the generated app_proxy_controller.rb
-Additional controllers for resources within the App_Proxy namespace, will need to include the mixin like so:
+## Documentation
 
-```ruby
-# app/controllers/app_proxy/reviews_controller.rb
-class ReviewsController < ApplicationController
-  include ShopifyApp::AppProxyVerification
-  # ...
-end
-```
-
-Create your app proxy url in the [Shopify Partners' Dashboard][dashboard], making sure to point it to `https://your_app_website.com/app_proxy`.
-![Creating an App Proxy](/images/app-proxy-screenshot.png)
-
-App Bridge
----
+You can find documentation on gem usage, concepts, mixins, installation, and more in [`/docs`](/docs).
 
-A basic example of using [App Bridge][app-bridge] is included in the install generator. An app instance is automatically initialized in [shopify_app.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/shopify_app.js) and [flash_messages.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/flash_messages.js) converts Rails [flash messages](https://api.rubyonrails.org/classes/ActionDispatch/Flash.html) to App Bridge Toast actions automatically. By default, this library is included via [unpkg in the embedded_app layout](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/embedded_app.html.erb#L27). For more advanced uses it is recommended to [install App Bridge via npm or yarn](https://help.shopify.com/en/api/embedded-apps/app-bridge/getting-started#set-up-shopify-app-bridge-in-your-app).
+* Start with the [*Generators*](/docs/shopify_app/generators.md) document to learn more about the generators this gem offers.
+* Check out the [*Changelog*](/CHANGELOG.md) for notes on the latest gem releases.
+* See [*Troubleshooting*](/docs/Troubleshooting.md) for tips on common issues.
+* If you are looking to upgrade your Shopify App version to a new major release, see [*Upgrading*](/docs/Upgrading.md) for important notes on breaking changes.
 
-Troubleshooting
----------------
+### Overview
 
-see [TROUBLESHOOTING.md](https://github.com/Shopify/shopify_app/blob/master/docs/Troubleshooting.md)
+[Quickstart](/docs/Quickstart.md)
 
-Testing an embedded app outside the Shopify admin
--------------------------------------------------
+[Troubleshooting](/docs/Troubleshooting.md)
 
-By default, loading your embedded app will redirect to the Shopify admin, with the app view loaded in an `iframe`. If you need to load your app outside of the Shopify admin (e.g., for performance testing), you can change `forceRedirect: true` to `false` in `ShopifyApp.init` block in the `embedded_app` view. To keep the redirect on in production but off in your `development` and `test` environments, you can use:
-
-```javascript
-forceRedirect: <%= Rails.env.development? || Rails.env.test? ? 'false' : 'true' %>
-```
+[Upgrading](/docs/Upgrading.md)
 
-Questions or problems?
-----------------------
+[Shopify App](/docs/shopify_app)
+  * [Authentication](/docs/shopify_app/authentication.md)
+  * [Engine](/docs/shopify_app/engine.md)
+  * [Generators](/docs/shopify_app/generators.md)
+  * [ScriptTags](/docs/shopify_app/script-tags.md)
+  * [Session repository](/docs/shopify_app/session-repository.md)
+  * [Handling changes in access scopes](/docs/shopify_app/handling-access-scopes-changes.md)
+  * [Testing](/docs/shopify_app/testing.md)
+  * [Webhooks](/docs/shopify_app/webhooks.md)
 
-- [Ask questions!](https://ecommerce.shopify.com/c/shopify-apis-and-technology)
-- [Read the docs!](https://help.shopify.com/api/guides)
+### Engine
 
-Upgrading to 11.7.0
----------------------------
+Mounting the Shopify App Rails Engine provides the following routes. These routes are configured to help install your application on shops and implement OAuth.
 
-### Session storage method signature breaking change
-If you override `def self.store(auth_session)` method in your session storage model (e.g. Shop), the method signature has changed to `def self.store(auth_session, *args)` in order to support user-based token storage. Please update your method signature to include the second argument.
+| Verb   | Route                    | Action             |
+|   ---: | :---                     | :---               |
+| `GET`  | `/login`                 | Login              |
+| `POST` | `/login`                 | Login              |
+| `GET`  | `/auth/shopify/callback` | OAuth redirect URI |
+| `GET`  | `/logout`                | Logout             |
+| `POST` | `/webhooks/:type`        | Webhook callback   |
 
-Rails 6 Compatibility
----------------------
+These routes are configurable. See the more detailed [*Engine*](/docs/shopify_app/engine.md) documentation to learn how you can customize the login URL or mount the Shopify App Rails engine at nested routes.
 
-### Disable Webpacker
-If you are using sprockets in rails 6 or want to generate a shopify_app without webpacker run the install task by running
-
-```
-SHOPIFY_APP_DISABLE_WEBPACKER=1 rails generate shopify_app
-```
-
-and then in your ShopifyApp configuration block, add
-
-```
-ShopifyApp.configure do |config|
-  config.disable_webpacker = true
-end
-```
-
-Upgrading from 8.6 to 9.0.0
----------------------------
-
-### Configuration change
-
-Add an api version configuration in `config/initializers/shopify_app.rb`
-Set this to the version you want to run against by default. See [Shopify API docs](https://help.shopify.com/en/api/versioning) for versions available.
-```ruby
-config.api_version = '2019-04'
-```
-
-### Session storage change
-
-You will need to add an `api_version` method to you session storage object.  The default implementation for this is.
-```ruby
-def api_version
-  ShopifyApp.configuration.api_version
-end
-```
-
-### Generated file change
-
-`embedded_app.html.erb` the usage of `shop_session.url` needs to be changed to `shop_session.domain`
-```erb
-<script type="text/javascript">
-  ShopifyApp.init({
-    apiKey: "<%= ShopifyApp.configuration.api_key %>",
-
-    shopOrigin: "<%= "https://#{ @shop_session.url }" if @shop_session %>",
-
-    debug: false,
-    forceRedirect: true
-  });
-</script>
-```
-is changed to
-```erb
-<script type="text/javascript">
-  ShopifyApp.init({
-    apiKey: "<%= ShopifyApp.configuration.api_key %>",
-
-    shopOrigin: "<%= "https://#{ @shop_session.domain }" if @shop_session %>",
-
-    debug: false,
-    forceRedirect: true
-  });
-</script>
-```
+To learn more about how this gem authenticates with Shopify, see [*Authentication*](/docs/shopify_app/authentication.md).
 
-### ShopifyAPI changes
+### API Versioning
 
-You will need to also follow the ShopifyAPI [upgrade guide](https://github.com/Shopify/shopify_api/blob/master/README.md#-breaking-change-notice-for-version-700-) to ensure your app is ready to work with api versioning.
+[Shopify's API is versioned](https://shopify.dev/concepts/about-apis/versioning). With Shopify App `v1.11.0`, the included Shopify API gem allows developers to specify and update the Shopify API version they want their app or service to use. The Shopify API gem also surfaces warnings to Rails apps about [deprecated endpoints, GraphQL fields and more](https://shopify.dev/concepts/about-apis/versioning#deprecation-practices).
 
-[dashboard]:https://partners.shopify.com
-[app-bridge]:https://help.shopify.com/en/api/embedded-apps/app-bridge
+See the [Shopify API gem README](https://github.com/Shopify/shopify_api/) for more information.