shopify_app 21.6.0 → 22.5.0

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.
 
@@ -31,18 +64,26 @@ Implements Rails' [protect_from_forgery](https://api.rubyonrails.org/classes/Act
 #### EmbeddedApp
 If your ShopifyApp configuration has the `embedded_app` config set to true, [P3P header](https://www.w3.org/P3P/) and [content security policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) are handled for you.
 
-#### 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.
+By default, the `EmbeddedApp` concern also sets the layout file to be `app/views/layouts/embedded_app.html.erb`.
 
-## 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.
+Sometimes one wants to run an embedded app in non-embedded mode. For example:
 
-## RequireKnownShop
-Designed to handle unauthenticated requests for *embedded apps*. If you are non-embedded app, we recommend using `Authenticated` concern instead of this one.
+- When the remote environment is a CI;
+- When the remote environment is a preview/PR app;
+- When the developer wants to run the app in a non-embedded mode for testing.
 
-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.
+To use the same application layout for every application controller, a developer can now overwrite the `#use_embedded_app_layout?` method.
 
-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`.
+```ruby
+class ApplicationController
+  # Ensures every controller is using the standard app/views/layouts/application.html.erb layout.
+  #
+  # @return [true, false]
+  def use_embedded_app_layout?
+    false
+  end
+end
+```
 
-## 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`
+#### 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.

data/docs/shopify_app/generators.md

@@ -68,13 +68,13 @@ Specify whether the app is an embedded app. Apps are embedded by default.
 
 #### `$ rails generate shopify_app:shop_model`
 
-This generator creates a `Shop` model and a migration to store shop installation records. See [*Shop-based token strategy*](/docs/shopify_app/session-repository.md#shop-based-token-storage) to learn more.
+This generator creates a `Shop` model and a migration to store shop installation records. See [*Shop-based token strategy*](/docs/shopify_app/sessions.md#shop-offline-token-storage) to learn more.
 
 ---
 
 #### `$ rails generate shopify_app:user_model`
 
-This generator creates a `User` model and a migration to store user records. See [*User-based token strategy*](/docs/shopify_app/session-repository.md#user-based-token-storage) to learn more.
+This generator creates a `User` model and a migration to store user records. See [*User-based token strategy*](/docs/shopify_app/sessions.md#user-online-token-storage) to learn more.
 
 ---
 

data/docs/shopify_app/sessions.md

@@ -0,0 +1,358 @@
+# 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)
+      - [Table of contents](#table-of-contents)
+  - [Sessions](#sessions-1)
+      - [Types of access tokens (sessions)](#types-of-access-tokens-sessions)
+      - [Access token storage (session)](#access-token-storage-session)
+        - [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)
+        - [⚠️  Custom Session Storage Requirements](#️--custom-session-storage-requirements)
+        - [Available `ActiveSupport::Concerns` that contains implementation of the above methods](#available-activesupportconcerns-that-contains-implementation-of-the-above-methods)
+    - [Loading Sessions](#loading-sessions)
+      - [Getting Sessions with Controller Concerns](#getting-sessions-with-controller-concerns)
+        - [**Shop Sessions - `EnsureInstalled`**](#shop-sessions---ensureinstalled)
+        - [User Sessions - `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)
+      - [Re-fetching an access token when API returns Unauthorized](#re-fetching-an-access-token-when-api-returns-unauthorized)
+  - [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 access tokens (sessions)
+- **Shop** ([offline access](https://shopify.dev/docs/apps/auth/access-token-types/offline))
+  - 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/access-token-types/online))
+  - 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
+
+#### Access token storage (session)
+##### 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 access 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.
+
+⚠️ If you started from the [Ruby App Template](https://github.com/Shopify/shopify-app-template-ruby), you don't need to run the generator as it's already included in the template. You can skip this step.
+
+```sh
+rails generate shopify_app:user_model
+```
+
+2. Configure `config/initializers/shopify_app.rb` to enable user access token persistance:
+
+```ruby
+config.user_session_repository = 'User'
+```
+
+The current Shopify user will be stored in the rails session at `session[:shopify_user]`
+
+You should also enable the [check for session expiry](#expiry-date) so that a new access token can be fetched before being used for an API operation.
+
+##### 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 |
+| `self.destroy_by_shopify_domain(shopify_domain)`  | `shopify_domain` (String)                  | -                         |
+
+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`  |
+| `self.destroy_by_shopify_user_id(user_id)`  | `user_id` (String)                  | -                            |
+
+
+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 and that it is not expired (when `check_session_expiry_date` is enabled). 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
+```
+
+#### Re-fetching an access token when API returns Unauthorized
+
+When using `ShopifyApp::EnsureHasSession` and the `new_embedded_auth_strategy` configuration, any **unhandled** Unauthorized `ShopifyAPI::Errors::HttpResponseError` will cause the app to perform token exchange to fetch a new access token from Shopify and the action to be executed again. This will update and store the new access token to the current session instance.
+
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_shopify_session)
+
+    # If this call raises an Unauthorized error from Shopify, EnsureHasSession
+    # will execute the action again after performing token exchange.
+    # It will store and use the newly retrieved access token for this and any subsequent calls.
+    client.query(options)
+  end
+end
+```
+
+If the error is being rescued in the action, it's still possible to make use of `with_token_refetch` provided by `EnsureHasSession` so that a new access token is fetched and the code is executed again with it. This will also update the session parameter with the new attributes.
+This block should be used to wrap the code that makes API queries, so your business logic won't be retried.
+
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    # Your app's business logic
+    with_token_refetch(current_shopify_session, shopify_id_token) do
+      # Unauthorized errors raised within this block will initiate token exchange.
+      # `with_token_refetch` will store the new access token and use it
+      # to execute this block again.
+      # Any subsequent calls using the same session instance will have the new token.
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_shopify_session)
+      client.query(options)
+    end
+    # Your app's business logic continues
+  rescue => error
+    # app's specific error handling
+  end
+end
+```
+
+It's also possible to use `with_token_refetch` on classes other than the controller by including the `ShopifyApp::AdminAPI::WithTokenRefetch` module and passing in the session along with the current request's `shopify_id_token`, which is provided by `ShopifyApp::EnsureHasSession`. This will also update the session parameter with the new attributes.
+
+```ruby
+# my_controller.rb
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    # shopify_id_token is a method provided by EnsureHasSession
+    MyClass.new.do_things(current_shopify_session, shopify_id_token)
+  end
+end
+
+# my_class.rb
+class MyClass
+  include ShopifyApp::AdminAPI::WithTokenRefetch
+
+  def do_things(session, shopify_id_token)
+    with_token_refetch(session, shopify_id_token) do
+      # Unauthorized errors raised within this block will initiate token exchange.
+      # `with_token_refetch` will store the new access token and use it
+      # to execute this block again.
+      # Any subsequent calls using the same session instance will have the new token.
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+      client.query(options)
+    end
+  rescue => error
+    # app's specific error handling
+  end
+end
+```
+
+If the retried block raises an `Unauthorized` error again, `with_token_refetch` will delete the current `session` from the database and raise the error again.
+
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_shopify_session)
+    with_token_refetch(current_shopify_session, shopify_id_token) do
+      # When this call raises Unauthorized a second time during retry,
+      # the `session` will be deleted from the database and the error raised
+      client.query(options)
+    end
+  rescue => error
+    # The Unauthorized error will reach this rescue
+  end
+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
+```
+
+## Expiry date
+When the configuration flag `check_session_expiry_date` is set to true, the user session expiry date will be checked to trigger a re-auth and get a fresh user token when it is expired. This requires the `ShopifyAPI::Auth::Session` `expires` attribute to be stored. When the `User` model includes the `UserSessionStorageWithScopes` concern, a DB migration can be generated with `rails generate shopify_app:user_model --skip` to add the `expires_at` attribute to the model.
+
+## Migrating from shop-based to user-based token strategy
+
+1. Run the `user_model` generator as [mentioned above](#user-online-token-storage).
+  - The generator will ask whether you want to migrate the User model to include `access_scopes` and `expires_at` columns. `expires_at` field is useful for detecting when the user session has expired and trigger a re-auth before an operation. It can reduce
+   API failures for invalid access tokens. Configure the [expiry date check](#expiry-date) to complete this feature.
+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 ["Access Token Storage" instructions](#access-token-storage-session) to specify the storage repository for shop and user sessions.
+     - [Customizing session storage](#customizing-session-storage-with-shopifyappsessionrepository)

data/docs/shopify_app/webhooks.md

@@ -2,23 +2,38 @@
 
 #### Table of contents
 
-[Manage webhooks using `ShopifyApp::WebhooksManager`](#manage-webhooks-using-shopifyappwebhooksmanager)
-[Mandatory GDPR Webhooks](#mandatory-gdpr-webhooks)
+[App-specific webhooks in shopify.app.toml (recommended)](#subscribing-to-webhooks-in-the-app-configuration-file)
+[Manage shop-specific webhooks using `ShopifyApp::WebhooksManager`](#manage-webhooks-using-shopifyappwebhooksmanager)
+[Mandatory Privacy Webhooks](#mandatory-privacy-webhooks)
 
-## Manage webhooks using `ShopifyApp::WebhooksManager`
+## App-specific webhooks in shopify.app.toml (recommended)
+You can specify app-specific webhooks to subscribe to in the `shopify.app.toml` file. These subscriptions are easier to manage because they are kept up to date by Shopify. In many cases they will be sufficient. Please read [app-specific vs shop-specific subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-vs-shop-specific-subscriptions) to understand when you might need shop-specific webhooks.
 
-See [`ShopifyApp::WebhooksManager`](/lib/shopify_app/managers/webhooks_manager.rb)
-ShopifyApp can manage your app's webhooks for you if you set which webhooks you require in the initializer:
+### Consuming app-specific webhooks events
+To consume app-specific webhooks events from the `shopify.app.toml` file, you can scaffold the necessary files by running the following generator.
+
+```bash
+rails g shopify_app:add_declarative_webhook --topic carts/update --path webhooks/carts_update
+```
+
+This will add a new controller, job, and route to your application. The controller will verify the webhook and queue the job to process the webhook. The job will be responsible for processing the webhook data.
+
+## Manage shop-specific webhooks using `ShopifyApp::WebhooksManager`
+
+See [`ShopifyApp::WebhooksManager`](/lib/shopify_app/managers/webhooks_manager.rb).
+ShopifyApp can manage your app's shop-specific webhooks for you if you set which webhooks you require in the initializer:
 
 ```ruby
 ShopifyApp.configure do |config|
   config.webhooks = [
-    {topic: 'carts/update', path: 'webhooks/carts_update'}
+    {topic: 'carts/update', path: 'api/webhooks/carts_update'}
   ]
 end
 ```
 
-When the [OAuth callback](/docs/shopify_app/authentication.md#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.
+This method should only be used if you have a good reason not to use app-specific webhooks (such as requiring different topics for different shops).
+
+When the [OAuth callback](/docs/shopify_app/authentication.md#oauth-callback) or token exchange 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](/app/controllers/shopify_app/webhooks_controller.rb) 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).
 
@@ -35,7 +50,35 @@ If you are only interested in particular fields, you can optionally filter the d
 ```ruby
 ShopifyApp.configure do |config|
   config.webhooks = [
-    {topic: 'products/update', path: 'webhooks/products_update', fields: ['title', 'vendor']}
+    {topic: 'products/update', path: 'api/webhooks/products_update', fields: ['title', 'vendor']}
+  ]
+end
+```
+
+If you need to read metafields, you can pass in the `metafield_namespaces` parameter in `config/webhooks`. Note if you are also using the `fields` parameter you will need to add `metafields` into that as well. Shopify documentation on metafields in webhooks can be found [here](https://shopify.dev/docs/api/admin-rest/2023-10/resources/webhook#resource-object).
+
+```ruby
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {
+      topic: 'orders/create',
+      path: 'api/webhooks/orders_create',
+      metafield_namespaces: ['app-namespace'],
+    },
+  ]
+end
+```
+
+If you need to filter by webhook fields, you can register a webhook with a `filter` parameter. The documentation for Webhook filters can be found [here](https://shopify.dev/docs/apps/build/webhooks/customize/filters).
+
+```ruby
+ShopifyApp.configure do |config|
+  config.webhooks = [
+    {
+      topic: 'products/update',
+      path: 'api/webhooks/products_update',
+      filter: "variants.price:>=10.00",
+    },
   ]
 end
 ```
@@ -72,9 +115,9 @@ rails g shopify_app:add_webhook --topic carts/update --path webhooks/carts_updat
 
 Where `--topic` is the topic and `--path` is the path the webhook should be sent to.
 
-## Mandatory GDPR Webhooks
+## Mandatory Privacy Webhooks
 
-We have three mandatory GDPR webhooks
+We have three mandatory privacy webhooks
 
 1. `customers/data_request`
 2. `customer/redact`
@@ -82,4 +125,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/karma.conf.js

@@ -16,9 +16,6 @@ module.exports = function(config) {
     exclude: [
       // Exclude JS files that create 'DOMContentLoaded' event listeners
       'app/assets/javascripts/**/redirect.js',
-      'app/assets/javascripts/**/storage_access_redirect.js',
-      'app/assets/javascripts/**/top_level_interaction.js',
-      'app/assets/javascripts/**/partition_cookies.js',
     ],
     mochaReporter: {
       output: 'autowatch',
@@ -26,7 +23,12 @@ module.exports = function(config) {
     preprocessors: {
       'test/javascripts/**/*test.js': ['webpack'],
     },
-    webpack: {},
+    webpack: {
+      mode: 'none',
+      output: {
+        hashFunction: 'rsa-sha512',
+      },
+    },
     reporters: karmaReporters,
     port: 9876,
     colors: true,