shopify_app 21.5.0 → 21.7.0

data/docs/shopify_app/authentication.md

@@ -1,37 +1,75 @@
 # Authentication
 
-The Shopify App gem implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) to get [access tokens](https://shopify.dev/concepts/about-apis/authentication#api-access-modes). These are used to authenticate requests made by the app to the Shopify API. 
+The Shopify App gem implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) to get [session tokens](https://shopify.dev/concepts/about-apis/authentication#api-access-modes). These are used to authenticate requests made by the app to the Shopify API.
 
 By default, the gem generates an embedded app frontend that uses [Shopify App Bridge](https://shopify.dev/tools/app-bridge) to fetch [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens). Session tokens are used by the embedded app to make authenticated requests to the app backend. 
 
-See [*Authenticate an embedded app using session tokens*](https://shopify.dev/tutorials/authenticate-your-app-using-session-tokens) to learn more. 
+See [*Getting started with session token authentication*](https://shopify.dev/docs/apps/auth/oauth/session-tokens/getting-started) to learn more. 
 
 > ⚠️ Be sure you understand the differences between the types of authentication schemes before reading this guide.
 
 #### Table of contents
 
-[OAuth callback](#oauth-callback)
+* [OAuth callback](#oauth-callback)
+  * [Customizing callback controller](#customizing-callback-controller)
+* [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+* [Rotate API credentials](#rotate-api-credentials)
+* [Making authenticated API requests after authorization](#making-authenticated-api-requests-after-authorization)
 
-[Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+## OAuth callback
 
-[Rotate API credentials](#rotate-api-credentials)
+>️ **Note:** In Shopify App version 8.4.0, we have extracted the callback logic in its own controller. If you are upgrading from a version older than 8.4.0 the callback action and related helper methods were defined in `ShopifyApp::SessionsController` ==> you will have to extend `ShopifyApp::CallbackController` instead and port your logic to the new controller.
 
-[Available authentication mixins](#available-authentication-mixins)
-  * [`ShopifyApp::Authenticated`](#shopifyappauthenticated)
-  * [`ShopifyApp::EnsureAuthenticatedLinks`](#shopifyappensureauthenticatedlinks)
+Upon completing the OAuth flow, Shopify calls the app at `ShopifyApp.configuration.login_callback_url`.
 
-## OAuth callback
+The default callback controller [`ShopifyApp::CallbackController`](../../app/controllers/shopify_app/callback_controller.rb) provides the following behaviour:
 
->️ **Note:** In Shopify App version 8.4.0, we have extracted the callback logic in its own controller. If you are upgrading from a version older than 8.4.0 the callback action and related helper methods were defined in `ShopifyApp::SessionsController` ==> you will have to extend `ShopifyApp::CallbackController` instead and port your logic to the new controller.
+1. Logging into the shop and resetting the session
+2. Storing the session to the `SessionRepository`
+3. [Installing Webhooks](/docs/shopify_app/webhooks.md)
+4. [Setting Scripttags](/docs/shopify_app/script-tags.md)
+5. [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+6. Redirecting to the return address
 
-Upon completing the OAuth flow, Shopify calls the app at the `callback_path`. If the app needs to do some extra work, it can define and configure the route to a custom callback controller, inheriting from `ShopifyApp::CallbackController` and hook into or override any of the defined helper methods. The default callback controller already provides the following behaviour:
-* Logging into the shop and resetting the session
-* [Installing Webhooks](/docs/shopify_app/webhooks.md)
-* [Setting Scripttags](/docs/shopify_app/script-tags.md)
-* [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
-* Redirecting to the return address
 
-## Run jobs after the OAuth flow
+#### Customizing callback controller
+If the app needs to do some extra work, it can define and configure the route to a custom callback controller.
+Inheriting from `ShopifyApp::CallbackController` and hook into or override any of the defined helper methods.
+
+Example:
+
+1. Create the new custom callback controller
+```ruby
+# web/app/controllers/my_custom_callback_controller.rb
+
+class MyCustomCallbackController < ShopifyApp::CallbackController
+  private
+
+  def install_webhooks(session)
+    # My custom override/definition to install webhooks
+  end
+end
+```
+
+2. Override callback routing to this controller
+
+```ruby
+# web/config/routes.rb
+
+Rails.application.routes.draw do
+  root to: "home#index"
+
+  # Overriding the callback controller to the new custom one.
+  # This must be added before mounting the ShopifyApp::Engine
+  get ShopifyApp.configuration.login_callback_url, to: 'my_custom_callback#callback'
+
+  mount ShopifyApp::Engine, at: "/api"
+
+  # other routes
+end
+```
+
+### Run jobs after the OAuth flow
 
 See [`ShopifyApp::AfterAuthenticateJob`](/lib/generators/shopify_app/add_after_authenticate_job/templates/after_authenticate_job.rb).
 
@@ -49,7 +87,7 @@ 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 }
+  config.after_authenticate_job = { job: "Shopify::AfterAuthenticateJob", inline: true }
 end
 ```
 
@@ -63,7 +101,7 @@ If you want to perform that action only once, e.g. send a welcome email to the u
 
 ## Rotate API credentials
 
-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).
+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:
 
@@ -86,43 +124,10 @@ strategy.options[:old_client_secret] = ShopifyApp.configuration.old_secret
 
 > **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/initializers/omniauth.rb`:
 
-## Available authentication mixins
-
-### `ShopifyApp::Authenticated`
-
-The engine provides a [`ShopifyApp::Authenticated`](/app/controllers/concerns/shopify_app/authenticated.rb) 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.
-
-*Example:*
-
-```rb
-class AuthenticatedController < ApplicationController
-  include ShopifyApp::Authenticated
-end
-
-class ApiController < AuthenticatedController
-  # Actions in this controller are protected
-end
-```
-
-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`.
-
-#### Embedded apps and `ShopifyApp::Authenticated`
-
-Embedded Shopify Admin apps can only use the `ShopifyApp::Authenticated` controller concern *if* the requests originate from App Bridge's `authenticatedFetch` method. Those who include this concern in the `HomeController` or some other embedded controller will see what looks like an OAuth redirect loop as the `ShopifyApp::Authenticated` concern will be fighting with the App Bridge. For more details on how to handle embedded sessions, refer to [the session token documentation](https://shopify.dev/apps/auth/oauth/session-tokens).
-
-### `ShopifyApp::EnsureAuthenticatedLinks`
+## Making authenticated API requests after authorization
+After the app is installed onto a shop and has been granted all necessary permission, a new session record will be added to `SessionRepository#shop_storage`, or `SessionRepository#user_storage` if online sessions are enabled.
 
-The [`ShopifyApp::EnsureAuthenticatedLinks`](/app/controllers/concerns/shopify_app/ensure_authenticated_links.rb) concern helps authenticate users that access protected pages of your app directly.
-
-Include this concern in your app's `AuthenticatedController` if your app uses session tokens with [Turbolinks](https://github.com/turbolinks/turbolinks). It adds a `before_action` filter that detects whether a session token is present or not. If a session token is not found, the user is redirected to your app's splash page path (`root_path`) along with `return_to` and `shop` parameters.
-
-*Example:*
-
-```rb
-class AuthenticatedController < ApplicationController
-  include ShopifyApp::EnsureAuthenticatedLinks
-  include ShopifyApp::Authenticated
-end
-```
+When your app needs to make API requests to Shopify, `ShopifyApp`'s `ActiveSupport` controller concerns can help you retrieve the active session token from the repository to make the authenticate API call.
 
-See [Authenticate server-side rendered embedded apps using Rails and Turbolinks](https://shopify.dev/tutorials/authenticate-server-side-rendered-embedded-apps-using-rails-and-turbolinks) for more information.
+- ⚠️ See [Sessions](./sessions.md) page to understand how sessions work.
+- ⚠️ See [Controller Concerns](./controller-concerns.md) page to understand when to use which concern.

data/docs/shopify_app/controller-concerns.md

@@ -1,12 +1,45 @@
 # Controller Concerns
 
-The following controller concerns are designed to be public and can be included in your controllers. Concerns defined in `lib/shopify_app/controller_concerns` are designed to be private and are not meant to be included directly into your controllers.
+The following controller concerns are designed to be public and can be included in your controllers.
 
-## Authenticated
+If you are looking to make requests within the context of a logged in **User**, you will include `EnsureHasSession` into your controller to ensure users have a valid session to make requests.
+
+
+```ruby
+class YourController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+end
+```
+
+If you don't require a user to be present but make requests scoped by a **Shop**, you can include `EnsureInstalled` in your controller to ensure your app has been installed by the Shop and they have a shop session.
+
+```ruby
+class YourController < ApplicationController
+  include ShopifyApp::EnsureInstalled
+end
+```
+
+## EnsureHasSession - Online User Sessions
 Designed for controllers that are designed to handle authenticated actions by ensuring there is a valid session for the request.
 
 In addition to session management, this concern will also handle localization, CSRF protection, embedded app settings, and billing enforcement.
 
+## EnsureInstalled - Offline Shop Sessions
+Designed to handle request scoped by a shop for *embedded apps*. If you are non-embedded app, we recommend using `EnsureHasSession` concern instead of this one.
+
+Rather than using the JWT to determine the requested shop of the request, the `shop` name param is taken from the query string that Shopify Admin provides.
+
+If the shop session cannot be found for the provided `shop` in the query string, the request will be redirected to login or the `embedded_redirect_url`.
+
+## EnsureAuthenticatedLinks
+Designed to be more of a lightweight session concern specifically for XHR requests. Where `EnsureHasSession` does far more than just session management, this concern will redirect to the splash page of the app if no active session was found.
+
+## ShopAccessScopesVerification
+If scopes for the session don't match configuration of scopes defined in `config/initializers/shopify_app.rb` the user will be redirected to login or the `embedded_redirect_url`.
+
+# Private Concerns used with EnsureHasSession
+These concerns shouldn't be included directly, but we provide some documentation as to their functionality that are included with `EnsureHasSession`. Concerns defined in `lib/shopify_app/controller_concerns` are designed to be private and are not meant to be included directly into your controllers.
+
 #### LoginProtection - Session Management
 This concern will setup and teardown the session around the action. If the session cannot be setup for the requested shop the request will be redirected to login.
 
@@ -33,16 +66,3 @@ If your ShopifyApp configuration has the `embedded_app` config set to true, [P3P
 
 #### EnsureBilling
 If billing is enabled for the app, the active payment for the session is queried and enforced if needed. If billing is required the user will be redirected to a page requesting payment.
-
-## EnsureAuthenticatedLinks
-Designed to be more of a lightweight session concern specifically for XHR requests. Where `Authenticated` does far more than just session management, this concern will redirect to the splash page of the app if no active session was found.
-
-## RequireKnownShop
-Designed to handle unauthenticated requests for *embedded apps*. If you are non-embedded app, we recommend using `Authenticated` concern instead of this one.
-
-Rather than using the JWT to determine the requested shop of the request, the `shop` name param is taken from the query string that Shopify Admin provides.
-
-If the shop session cannot be found for the provided `shop` in the query string, the request will be redirected to login or the `embedded_redirect_url`.
-
-## ShopAccessScopesVerification
-If scopes for the session don't match configuration of scopes defined in `config/initializers/shopify_app.rb` the user will be redirected to login or the `embedded_redirect_url`

data/docs/shopify_app/sessions.md

@@ -0,0 +1,250 @@
+# Sessions
+
+Sessions are used to make contextual API calls for either a shop (offline session) or a user (online session). This gem has ownership of session persistence.
+
+#### Table of contents
+
+- [Sessions](#sessions-1)
+  - [Types of session tokens](#types-of-session-tokens) - Shop (offline) v.s. User (online)
+  - [Session token storage](#session-token-storage)
+      - [Shop (offline) token storage](#shop-offline-token-storage)
+      - [User (online) token storage](#user-online-token-storage)
+      - [In-Memory Session Storage for Testing](#in-memory-session-storage-for-testing)
+      - [Customizing Session Storage with `ShopifyApp::SessionRepository`](#customizing-session-storage-with-shopifyappsessionrepository)
+  - [Loading Sessions](#loading-sessions)
+      - [Getting Sessions with Controller Concerns](#getting-sessions-with-controller-concerns)
+        - [Shop session - "EnsureInstalled" ](#shop-sessions---ensureinstalled)
+        - [User session - "EnsureHasSession" ](#user-sessions---ensurehassession)
+      - [Getting Sessions from a Shop or User model record - "with_shopify_session"](#getting-sessions-from-a-shop-or-user-model-record---with_shopify_session)
+- [Access scopes](#access-scopes)
+  - [`ShopifyApp::ShopSessionStorageWithScopes`](#shopifyappshopsessionstoragewithscopes)
+  - [``ShopifyApp::UserSessionStorageWithScopes``](#shopifyappusersessionstoragewithscopes)
+- [Migrating from shop-based to user-based token strategy](#migrating-from-shop-based-to-user-based-token-strategy)
+- [Migrating from ShopifyApi::Auth::SessionStorage to ShopifyApp::SessionStorage](#migrating-from-shopifyapiauthsessionstorage-to-shopifyappsessionstorage)
+
+## Sessions
+#### Types of session tokens
+- **Shop** ([offline access](https://shopify.dev/docs/apps/auth/oauth/access-modes#offline-access))
+  - Access token is linked to the store
+  - Meant for long-term access to a store, where no user interaction is involved
+  - Ideal for background jobs or maintenance work
+- **User** ([online access](https://shopify.dev/docs/apps/auth/oauth/access-modes#online-access))
+  - Access token is linked to an individual user on a store
+  - Meant to be used when a user is interacting with your app through the web
+
+⚠️  [Read more about Online vs. Offline access here](https://shopify.dev/apps/auth/oauth/access-modes).
+
+#### Session token storage
+##### Shop (offline) token storage
+⚠️ All apps must have a shop session storage, if you started from the [Ruby App Template](https://github.com/Shopify/shopify-app-template-ruby), it's already configured to have a Shop model by default.
+
+If you don't already have a repository to store the access tokens:
+
+1. Run the following generator to create a shop model to store the access tokens
+
+```sh
+rails generate shopify_app:shop_model
+```
+
+2. Configure `config/initializers/shopify_app.rb` to enable shop session token persistance:
+
+```ruby
+config.shop_session_repository = 'Shop'
+```
+
+##### User (online) token storage
+If your app has user interactions and would like to control permission based on individual users, you need to configure a User token storage to persist unique tokens for each user.
+
+[Shop (offline) tokens must still be maintained](#shop-offline-token-storage).
+
+1. Run the following generator to create a user model to store the individual based access tokens
+```sh
+rails generate shopify_app:user_model
+```
+
+2. Configure `config/initializers/shopify_app.rb` to enable user session token persistance:
+
+```ruby
+config.user_session_repository = 'User'
+```
+
+The current Shopify user will be stored in the rails session at `session[:shopify_user]`
+
+##### In-memory Session Storage for testing
+The `ShopifyApp` gem includes methods for in-memory storage for both shop and user sessions. In-memory storage is intended to be used in a testing environment, please use a persistent storage for your application.
+- [InMemoryShopSessionStore](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/in_memory_shop_session_store.rb)
+- [InMemoryUserSessionStore](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/in_memory_user_session_store.rb)
+
+You can configure the `ShopifyApp` configuration to use the in-memory storage method during manual testing:
+```ruby
+# config/initializers/shopify_app.rb
+
+config.shop_session_repository = ShopifyApp::InMemoryShopSessionStore
+config.user_session_repository = ShopifyApp::InMemoryUserSessionStore
+```
+
+##### Customizing Session Storage with `ShopifyApp::SessionRepository`
+
+In the rare event that you would like to break Rails convention for storing/retrieving records, the `ShopifyApp::SessionRepository` allows you to define how your sessions are stored and retrieved for shops. The specific repository for `shop` & `user` is configured in the `config/initializers/shopify_app.rb` file and can be set to any object.
+
+```ruby
+# config/initializers/shopify_app.rb
+
+config.shop_session_repository = MyCustomShopSessionRepository
+config.user_session_repository = MyCustomUserSessionRepository
+```
+
+##### ⚠️  Custom Session Storage Requirements
+
+The custom **Shop** repository must implement the following methods:
+
+| Method                                            | Parameters                                 | Return Type               |
+|---------------------------------------------------|--------------------------------------------|---------------------------|
+| `self.store(auth_session)`                        | `auth_session` (ShopifyAPI::Auth::Session) | -                         |
+| `self.retrieve(id)`                               | `id` (String)                              | ShopifyAPI::Auth::Session |
+| `self.retrieve_by_shopify_domain(shopify_domain)` | `shopify_domain` (String)                  | ShopifyAPI::Auth::Session |
+
+The custom **User** repository must implement the following methods:
+| Method                                      | Parameters                          | Return Type                  |
+|---------------------------------------------|-------------------------------------|------------------------------|
+| `self.store(auth_session, user)`            | <li>`auth_session` (ShopifyAPI::Auth::Session)<br><li>`user` (ShopifyAPI::Auth::AssociatedUser) | - |
+| `self.retrieve(id)`                         | `id` (String)                       | `ShopifyAPI::Auth::Session`  |
+| `self.retrieve_by_shopify_user_id(user_id)` | `user_id` (String)                  | `ShopifyAPI::Auth::Session`  |
+
+
+These methods are already implemented as a part of the `User` and `Shop` models generated from this gem's generator.
+- `Shop` model includes the [ShopSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage_with_scopes.rb) concern.
+- `User` model includes the [UserSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage_with_scopes.rb) concern.
+
+##### Available `ActiveSupport::Concerns` that contains implementation of the above methods
+Simply include these concerns if you want to use the implementation, and overwrite methods for custom implementation
+
+- `Shop` storage
+  - [ShopSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage_with_scopes.rb)
+  - [ShopSessionStorage](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage.rb)
+
+- `User` storage
+  - [UserSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage_with_scopes.rb)
+  - [UserSessionStorage](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage.rb)
+
+### Loading Sessions
+By using the appropriate controller concern, sessions are loaded for you.
+
+#### Getting Sessions with Controller Concerns
+
+⚠️  **Note: These controller concerns cannot both be included in the same controller.**
+##### **Shop Sessions - `EnsureInstalled`**
+- [EnsureInstalled](https://github.com/Shopify/shopify_app/blob/main/app/controllers/concerns/shopify_app/ensure_installed.rb) controller concern will load a shop session with the `installed_shop_session` helper. If a shop session is not found, meaning the app wasn't installed for this shop, the request will be redirected to be installed.
+- This controller concern should NOT be used if you don't need your app to make calls on behalf of a user.
+- Example
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureInstalled
+
+  def method
+    current_session = installed_shop_session # `installed_shop_session` is a helper from `EnsureInstalled`
+
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_session)
+    client.query(
+    #...
+    )
+  end
+end
+```
+
+##### User Sessions - `EnsureHasSession`
+- [EnsureHasSession](https://github.com/Shopify/shopify_app/blob/main/app/controllers/concerns/shopify_app/ensure_has_session.rb) controller concern will load a user session via `current_shopify_session`. As part of loading this session, this concern will also ensure that the user session has the appropriate scopes needed for the application. If the user isn't found or has fewer permitted scopes than are required, they will be prompted to authorize the application.
+- This controller concern should be used if you don't need your app to make calls on behalf of a user. With that in mind, there are a few other embedded concerns that are mixed in to ensure that embedding, CSRF, localization, and billing allow the action for the user.
+- Example
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def method
+    current_session = current_shopify_session # `current_shopify_session` is a helper from `EnsureHasSession`
+
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_session)
+    client.query(
+    #...
+    )
+  end
+end
+```
+
+#### Getting sessions from a Shop or User model record - 'with_shopify_session'
+The [ShopifyApp::SessionStorage#with_shopify_session](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/session_storage.rb#L12)
+helper allows you to make API calls within the context of a user or shop, by using that record's access token.
+
+This mixin is already included in ActiveSupport [concerns](#available-activesupportconcerns-that-contains-implementation-of-the-above-methods) from this gem.
+If you're using a custom implementation of session storage, you can include the [ShopifyApp::SessionStorage](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/session_storage.rb) concern.
+
+All calls made within the block passed into this helper will be made in that context:
+
+```ruby
+# To use shop context for "my_shopify_domain.myshopify.com"
+shopify_domain = "my_shopify_domain.myshopify.com"
+shop = Shop.find_by(shopify_domain: shopify_domain)
+shop.with_shopify_session do
+  ShopifyAPI::Product.find(id: product_id)
+  # This will call the Shopify API with my_shopify_domain's access token
+end
+
+# To use user context for user ID "my_user_id"
+user = User.find_by(shopify_user_id: "my_user_id")
+user.with_shopify_session do
+  ShopifyAPI::Product.find(id: product_id)
+  # This will call the Shopify API with my_user_id's access token
+end
+```
+
+## Access scopes
+If you want to customize how access scopes are stored for shops and users, you can implement the `access_scopes` getters and setters in the models that include `ShopifyApp::ShopSessionStorageWithScopes` and `ShopifyApp::UserSessionStorageWithScopes` as shown:
+
+### `ShopifyApp::ShopSessionStorageWithScopes`
+```ruby
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorageWithScopes
+
+  def access_scopes=(scopes)
+    # Store access scopes
+  end
+  def access_scopes
+    # Find access scopes
+  end
+end
+```
+
+### `ShopifyApp::UserSessionStorageWithScopes`
+```ruby
+class User < ActiveRecord::Base
+  include ShopifyApp::UserSessionStorageWithScopes
+
+  def access_scopes=(scopes)
+    # Store access scopes
+  end
+  def access_scopes
+    # Find access scopes
+  end
+end
+```
+
+## Migrating from shop-based to user-based token strategy
+
+1. Run the `user_model` generator as [mentioned above](#user-online-token-storage).
+2. Ensure that both your `Shop` model and `User` model includes the [necessary concerns](#available-activesupportconcerns-that-contains-implementation-of-the-above-methods)
+3. Update the configuration file to use the new session storage.
+
+```ruby
+# config/initializers/shopify_app.rb
+
+config.shop_session_repository = {YOUR_SHOP_MODEL_CLASS}
+config.user_session_repository = {YOUR_USER_MODEL_CLASS}
+```
+
+## Migrating from `ShopifyApi::Auth::SessionStorage` to `ShopifyApp::SessionStorage`
+- Support for using `ShopifyApi::Auth::SessionStorage` was removed from ShopifyApi [version 13.0.0](https://github.com/Shopify/shopify-api-ruby/blob/main/CHANGELOG.md#1300)
+- Sessions storage are now handled with [ShopifyApp::SessionRepository](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/session_repository.rb)
+- To migrate and specify your shop or user session storage method:
+  1. Remove `session_storage` configuration from `config/initializers/shopify_app.rb`
+  2. Follow ["Session Token Storage" instructions](#session-token-storage) to specify the storage repository for shop and user sessions.
+     - [Customizing session storage](#customizing-session-storage-with-shopifyappsessionrepository)

data/docs/shopify_app/webhooks.md

@@ -82,4 +82,38 @@ We have three mandatory GDPR webhooks
 
 The `generate shopify_app` command generated three job templates corresponding to all three of these webhooks.
 To pass our approval process you will need to set these webhooks in your partner dashboard.
-You can read more about that [here](https://shopify.dev/apps/webhooks/configuration/mandatory-webhooks).
+You can read more about that [here](https://shopify.dev/apps/webhooks/configuration/mandatory-webhooks).
+
+## EventBridge and PubSub Webhooks
+
+You can also register webhooks for delivery to Amazon EventBridge or Google Cloud Pub/Sub. In this case the `path` argument to needs to be of a specific form.
+
+For EventBridge, the `path` must be the ARN of the partner event source.
+
+```rb
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {
+      delivery_method: :event_bridge,
+      topic: 'carts/update',
+      path: 'arn:aws:events....'
+    }
+  ]
+end
+```
+
+For Pub/Sub, the `path` must be of the form `pubsub://[PROJECT-ID]:[PUB-SUB-TOPIC-ID]`. For example, if you created a topic with id `red` in the project `blue`, then the value of path would be `pubsub://blue:red`.
+
+```rb
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {
+      delivery_method: :pub_sub,
+      topic: 'carts/update',
+      path: 'pubsub://project-id:pub-sub-topic-id'
+    }
+  ]
+end
+```
+
+When registering for an EventBridge or PubSub Webhook you'll need to implement a handler that will fetch webhooks from the queue and process them yourself.

data/lib/generators/shopify_app/install/templates/shopify_app.rb.tt

@@ -12,7 +12,7 @@ ShopifyApp.configure do |config|
   config.webhooks = [
     { topic: "app/uninstalled", address: "webhooks/app_uninstalled"},
     { topic: "customers/data_request", address: "webhooks/customers_data_request" },
-    { topic: "customer/redact", address: "webhooks/customers_redact"},
+    { topic: "customers/redact", address: "webhooks/customers_redact"},
     { topic: "shop/redact", address: "webhooks/shop_redact"}
   ]
 
@@ -30,6 +30,8 @@ ShopifyApp.configure do |config|
   #   amount: 5,
   #   interval: ShopifyApp::BillingConfiguration::INTERVAL_EVERY_30_DAYS,
   #   currency_code: "USD", # Only supports USD for now
+  #   trial_days: 0
+  #   test: ENV.fetch('SHOPIFY_TEST_CHARGES', !Rails.env.production?)
   # )
 
   if defined? Rails::Server

data/lib/shopify_app/configuration.rb

@@ -129,12 +129,16 @@ module ShopifyApp
     attr_reader :amount
     attr_reader :currency_code
     attr_reader :interval
+    attr_reader :trial_days
+    attr_reader :test
 
-    def initialize(charge_name:, amount:, interval:, currency_code: "USD")
+    def initialize(charge_name:, amount:, interval:, currency_code: "USD", trial_days: 0, test: !Rails.env.production?)
       @charge_name = charge_name
       @amount = amount
       @currency_code = currency_code
       @interval = interval
+      @trial_days = trial_days
+      @test = test
     end
   end
 

data/lib/shopify_app/controller_concerns/ensure_billing.rb

@@ -136,7 +136,8 @@ module ShopifyApp
             },
           },
           returnUrl: return_url,
-          test: !Rails.env.production?,
+          trialDays: ShopifyApp.configuration.billing.trial_days,
+          test: ShopifyApp.configuration.billing.test,
         },
       )
 
@@ -154,7 +155,7 @@ module ShopifyApp
             currencyCode: ShopifyApp.configuration.billing.currency_code,
           },
           returnUrl: return_url,
-          test: !Rails.env.production?,
+          test: ShopifyApp.configuration.billing.test,
         },
       )
 
@@ -208,12 +209,14 @@ module ShopifyApp
         $name: String!
         $lineItems: [AppSubscriptionLineItemInput!]!
         $returnUrl: URL!
+        $trialDays: Int
         $test: Boolean
       ) {
         appSubscriptionCreate(
           name: $name
           lineItems: $lineItems
           returnUrl: $returnUrl
+          trialDays: $trialDays
           test: $test
         ) {
           confirmationUrl

data/lib/shopify_app/controller_concerns/localization.rb

@@ -5,20 +5,23 @@ module ShopifyApp
     extend ActiveSupport::Concern
 
     included do
-      before_action :set_locale
+      around_action :set_locale
     end
 
     private
 
-    def set_locale
-      if params[:locale]
-        session[:locale] = params[:locale]
-      else
-        session[:locale] ||= I18n.default_locale
+    def set_locale(&action)
+      locale = params[:locale] || I18n.default_locale
+
+      # Fallback to the 2 letter language code if the requested locale unavailable
+      unless I18n.available_locales.include?(locale.to_sym)
+        locale = locale.split("-").first
       end
-      I18n.locale = session[:locale]
+
+      session[:locale] = locale
+      I18n.with_locale(session[:locale], &action)
     rescue I18n::InvalidLocale
-      I18n.locale = I18n.default_locale
+      I18n.with_locale(I18n.default_locale, &action)
     end
   end
 end

data/lib/shopify_app/managers/webhooks_manager.rb

@@ -43,12 +43,13 @@ module ShopifyApp
         ShopifyApp::Logger.debug("Adding registrations to webhooks")
         ShopifyApp.configuration.webhooks.each do |attributes|
           webhook_path = path(attributes)
+          delivery_method = attributes[:delivery_method] || :http
 
           ShopifyAPI::Webhooks::Registry.add_registration(
             topic: attributes[:topic],
-            delivery_method: attributes[:delivery_method] || :http,
+            delivery_method: delivery_method,
             path: webhook_path,
-            handler: webhook_job_klass(webhook_path),
+            handler: delivery_method == :http ? webhook_job_klass(webhook_path) : nil,
             fields: attributes[:fields],
           )
         end

data/lib/shopify_app/session/in_memory_user_session_store.rb

@@ -5,7 +5,7 @@ module ShopifyApp
     class << self
       def store(session, user)
         id = super
-        repo[user.shopify_user_id] = session
+        repo[user.id.to_s] = session
         id
       end