Add DB migration template to generator

Author: zzooeeyy

CHANGELOG.md

@@ -3,13 +3,12 @@ Unreleased
 - ⚠️ [Breaking] Removes `ShopifyApp::JWTMiddleware` and `ShopifyApp::JWT` See [Upgrading](/docs/Upgrading.md) for more migration. [1960](https://github.com/Shopify/shopify_app/pull/1960)
 - ⚠️ [Breaking] Removed deprecated `CallbackController` methods. `perform_after_authenticate_job`, `install_webhooks`, and `perform_post_authenticate_jobs` have been removed. [#1961](https://github.com/Shopify/shopify_app/pull/1961)
 - ⚠️ [Breaking] Bumps minimum supported Ruby version to 3.1 [#1959](https://github.com/Shopify/shopify_app/pull/1959)
-- Adds automatic offline access token refresh support for `ShopSessionStorage`. When using `with_shopify_session`, expired offline access tokens will automatically be refreshed using refresh tokens. [#XXXX](https://github.com/Shopify/shopify_app/pull/XXXX)
-  - Adds `refresh_token_if_expired!` public method to `ShopSessionStorage` for manual token refresh
-  - Adds `RefreshTokenExpiredError` exception raised when refresh token itself is expired
+- Adds support for expiring offline access tokens with automatic refresh for `ShopSessionStorage`. Apps can now opt-in to expiring offline tokens via `ShopifyAPI::Context.setup(offline_access_token_expires: true)`, and `ShopSessionStorage` will automatically refresh expired tokens when using `with_shopify_session`. **See [migration guide](/docs/shopify_app/sessions.md#migrating-to-expiring-offline-access-tokens) for setup instructions.** [#2027](https://github.com/Shopify/shopify_app/pull/2027)
   - `ShopSessionStorage` now automatically stores `access_scopes`, `expires_at`, `refresh_token`, and `refresh_token_expires_at` from auth sessions
   - `UserSessionStorage` now automatically stores `access_scopes` and `expires_at` from auth sessions (refresh tokens not applicable for online/user tokens)
-  - See [Sessions documentation](/docs/shopify_app/sessions.md#automatic-access-token-refresh) for migration guide
-- Deprecates `ShopSessionStorageWithScopes` and `UserSessionStorageWithScopes` in favor of `ShopSessionStorage` and `UserSessionStorage`, which now handle session attributes automatically. Will be removed in v23.0.0. [#XXXX](https://github.com/Shopify/shopify_app/pull/XXXX)
+  - Adds `refresh_token_if_expired!` public method to `ShopSessionStorage` for manual token refresh
+  - Adds `RefreshTokenExpiredError` exception raised when refresh token itself is expired
+  - Mark deprecation for `ShopSessionStorageWithScopes` and `UserSessionStorageWithScopes` in favor of `ShopSessionStorage` and `UserSessionStorage`.
 - Adds a `script_tag_manager` that will automatically create script tags when the app is installed. [1948](https://github.com/Shopify/shopify_app/pull/1948)
 - Handle invalid token when adding redirection headers [#1945](https://github.com/Shopify/shopify_app/pull/1945)
 - Handle invalid record error for concurrent token exchange calls [#1966](https://github.com/Shopify/shopify_app/pull/1966)

README.md

@@ -189,7 +189,6 @@ You can find documentation on gem usage, concepts, mixins, installation, and mor
   * [Controller Concerns](/docs/shopify_app/controller-concerns.md)
   * [Generators](/docs/shopify_app/generators.md)
   * [Sessions](/docs/shopify_app/sessions.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)
   * [Content Security Policy](/docs/shopify_app/content-security-policy.md)
@@ -243,8 +242,7 @@ ShopifyApp.configure do |config|
   config.embedded_app = true
   config.new_embedded_auth_strategy = true
 
-  # If your app is configured to use online sessions, you can enable session expiry date check so a new access token
-  # is fetched automatically when the session expires.
+  # You can enable session expiry date check so a new access token is fetched automatically when the session expires.
   # See expiry date check docs: https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md#expiry-date
   config.check_session_expiry_date = true
   ...

docs/Upgrading.md

@@ -79,18 +79,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-3. **Optional but recommended:** Add columns to enable automatic token refresh for shops:
-```ruby
-class AddTokenRefreshFieldsToShops < ActiveRecord::Migration[7.0]
-  def change
-    add_column :shops, :expires_at, :datetime
-    add_column :shops, :refresh_token, :string
-    add_column :shops, :refresh_token_expires_at, :datetime
-  end
-end
-```
-
-With these columns, `ShopSessionStorage#with_shopify_session` will automatically refresh expired offline access tokens. See the [Sessions documentation](/docs/shopify_app/sessions.md#automatic-access-token-refresh) for more details.
+3. **Optional:** You can now opt-in to using expiring offline access tokens with automatic refresh. See the [Sessions documentation](/docs/shopify_app/sessions.md#offline-access-tokens) for setup instructions.
 
 **Note:** If you had custom `access_scopes=` or `access_scopes` methods in your models, these are no longer needed. The base concerns now handle these attributes automatically.
 

docs/shopify_app/sessions.md

@@ -23,6 +23,7 @@ Sessions are used to make contextual API calls for either a shop (offline sessio
   - [Access scopes](#access-scopes)
     - [`ShopifyApp::ShopSessionStorageWithScopes`](#shopifyappshopsessionstoragewithscopes)
     - [`ShopifyApp::UserSessionStorageWithScopes`](#shopifyappusersessionstoragewithscopes)
+  - [Migrating to Expiring Offline Access Tokens](#migrating-to-expiring-offline-access-tokens)
   - [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)
 
@@ -206,60 +207,18 @@ user.with_shopify_session do
 end
 ```
 
-##### Automatic Access Token Refresh
+**Automatic Token Refresh for Shop Sessions:**
 
-`ShopSessionStorage` includes automatic token refresh for expired offline access tokens. When using `with_shopify_session` on a Shop model, the gem will automatically refresh the access token if it has expired, using the refresh token stored in the database.
+When using `Shop` models with [expiring offline access tokens](#migrating-to-expiring-offline-access-tokens) configured, `with_shopify_session` will automatically refresh expired tokens before executing the block. This ensures your API calls always use valid credentials without manual intervention.
 
-**Requirements:**
-- Shop model must include `ShopSessionStorage` concern
-- Database must have the following columns:
-  - `expires_at` (datetime) - when the access token expires
-  - `refresh_token` (string) - the refresh token
-  - `refresh_token_expires_at` (datetime) - when the refresh token expires
+To disable automatic refresh, pass `auto_refresh: false`:
 
-**Migration Example:**
 ```ruby
-class AddTokenRefreshFieldsToShops < ActiveRecord::Migration[7.0]
-  def change
-    add_column :shops, :expires_at, :datetime
-    add_column :shops, :refresh_token, :string
-    add_column :shops, :refresh_token_expires_at, :datetime
-  end
-end
-```
-
-**Usage:**
-```ruby
-shop = Shop.find_by(shopify_domain: "example.myshopify.com")
-
-# Automatic refresh (default behavior)
-shop.with_shopify_session do
-  # If the token is expired, it will be automatically refreshed before making API calls
-  ShopifyAPI::Product.all
-end
-
-# Disable automatic refresh if needed
 shop.with_shopify_session(auto_refresh: false) do
   # Token will NOT be refreshed even if expired
-  ShopifyAPI::Product.all
-end
-
-# Manual refresh
-begin
-  shop.refresh_token_if_expired!
-rescue ShopifyApp::RefreshTokenExpiredError
-  # Handle case where refresh token itself has expired
-  # App needs to go through OAuth flow again
 end
 ```
 
-**Error Handling:**
-- `ShopifyApp::RefreshTokenExpiredError` is raised when the refresh token itself is expired
-- When this happens, the shop must go through the OAuth flow again to get new tokens
-- The refresh process uses database row-level locking to prevent race conditions from concurrent requests
-
-**Note:** Refresh tokens are only available for offline (shop) access tokens. Online (user) access tokens do not support refresh and must be re-authorized through OAuth when expired.
-
 #### 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.
@@ -355,41 +314,109 @@ end
 ```
 
 ## Expiry date
-When the configuration flag `check_session_expiry_date` is set to true, the 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 configuration flag `check_session_expiry_date` is set to true, the session expiry date will be checked to trigger a re-auth and get a fresh token when it is expired.
+This requires the `ShopifyAPI::Auth::Session` `expires` attribute to be stored.
 
-### Online access tokens
-When the `User` model includes the `UserSessionStorage` concern, a DB migration can be generated with `rails generate shopify_app:user_model --skip` to add the `expires_at` attribute to the model.
+**Online access tokens (User sessions):**
+- When the `User` model includes the `UserSessionStorage` concern, a DB migration can be generated with `rails generate shopify_app:user_model --skip` to add the `expires_at` attribute to the model
+- Online access tokens cannot be refreshed, so when the token is expired, the user must go through the OAuth flow again to get a new token
 
-Online access tokens can not be refreshed, so when the token is expired, the user must go through the OAuth flow again to get a new token.
+**Offline access tokens (Shop sessions):**
+- Offline access tokens can optionally be configured to expire and support automatic refresh. See [Migrating to Expiring Offline Access Tokens](#migrating-to-expiring-offline-access-tokens) for detailed setup instructions
 
-### Offline access tokens
+## Migrating to Expiring Offline Access Tokens
 
-**Optional Configuration:** By default, offline access tokens do not expire. However, you can opt-in to expiring offline access tokens for enhanced security by configuring it through `ShopifyAPI::Context`:
+You can opt-in to expiring offline access tokens for enhanced security. When enabled, Shopify will issue offline access tokens with an expiration date and a refresh token. `ShopSessionStorage` will then automatically refresh expired tokens when using `with_shopify_session`.
+
+**1. Database Migration:**
+
+Run the shop model generator (use `--skip` to avoid regenerating the Shop model if it already exists):
+
+```bash
+rails generate shopify_app:shop_model --skip
+```
+
+The generator will prompt you to create a migration that adds the `expires_at`, `refresh_token`, and `refresh_token_expires_at` columns. Alternatively, you can create the migration manually:
+
+```ruby
+class AddShopAccessTokenExpiryColumns < ActiveRecord::Migration[7.0]
+  def change
+    add_column :shops, :expires_at, :datetime
+    add_column :shops, :refresh_token, :string
+    add_column :shops, :refresh_token_expires_at, :datetime
+  end
+end
+```
+
+**2. Update Model Concern:**
+
+If your Shop model is using the deprecated `ShopSessionStorageWithScopes` concern, update it to use `ShopSessionStorage`:
+
+```ruby
+# app/models/shop.rb
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorage  # Change from ShopSessionStorageWithScopes
+end
+```
+
+`ShopSessionStorage` now automatically handles `access_scopes`, `expires_at`, `refresh_token`, and `refresh_token_expires_at` - no additional concerns needed.
+
+**3. Configuration:**
 
 ```ruby
 # config/initializers/shopify_app.rb
 ShopifyApp.configure do |config|
   # ... other configuration
 
-  # Enable checking session expiry dates
+  # Enable automatic reauthentication when session is expired
   config.check_session_expiry_date = true
 end
 
-# For ShopifyAPI Context - enable expiring offline tokens
+# For ShopifyAPI Context - enable requesting expiring offline tokens
 ShopifyAPI::Context.setup(
   # ... other configuration
-  offline_access_token_expires: true, # Opt-in to expiring offline tokens
+  offline_access_token_expires: true, # Opt-in to start requesting expiring offline tokens
 )
 ```
 
-When expiring offline tokens are enabled, Shopify will issue offline access tokens with an expiration date and a refresh token. Your app can then automatically refresh these tokens when they expire.
+**4. Refreshing Expired Tokens:**
+
+With the configuration enabled, expired tokens are automatically handled differently based on the flow:
+
+**For user-facing requests (OAuth/Token Exchange flow):**
+When `check_session_expiry_date` is enabled, expired sessions trigger automatic re-authentication through the OAuth flow. This happens transparently when using controller concerns like `EnsureHasSession`.
+
+**For background jobs and non-user interactions:**
+Tokens are automatically refreshed when using `with_shopify_session` from `ShopSessionStorage`:
 
-**Database Setup:** When the `Shop` model includes the `ShopSessionStorage` concern, a DB migration can be generated with `rails generate shopify_app:shop_model --skip` to add the `expires_at`, `refresh_token`, and `refresh_token_expires_at` attributes to the model.
+```ruby
+shop = Shop.find_by(shopify_domain: "example.myshopify.com")
 
-**Automatic Refresh:** Offline access tokens can be automatically refreshed using the stored refresh token when expired. See [Automatic Access Token Refresh](#automatic-access-token-refresh) for more details.
+# Automatic refresh (default behavior)
+shop.with_shopify_session do
+  # If the token is expired, it will be automatically refreshed before making API calls
+end
+
+# Disable automatic refresh if needed
+shop.with_shopify_session(auto_refresh: false) do
+  # Token will NOT be refreshed even if expired
+end
+
+# Manual refresh
+begin
+  shop.refresh_token_if_expired!
+rescue ShopifyApp::RefreshTokenExpiredError
+  # Handle case where refresh token itself has expired
+  # App needs to go through OAuth flow again
+end
+```
+
+**Error Handling:**
+- `ShopifyApp::RefreshTokenExpiredError` is raised when the refresh token itself is expired
+- When this happens, the user must interact with the app to go through the OAuth flow again to get new tokens
+- The refresh process uses database row-level locking to prevent race conditions from concurrent requests
 
-**Note:** If you choose not to enable expiring offline tokens, the `expires_at`, `refresh_token`, and `refresh_token_expires_at` columns will remain `NULL` and no automatic refresh will occur.
+**Note:** If you choose not to enable expiring offline tokens, the `expires_at`, `refresh_token`, and `refresh_token_expires_at` columns will remain `NULL` and no automatic refresh will occur. Refresh tokens are only available for offline (shop) access tokens. Online (user) access tokens do not support refresh and must be re-authorized through OAuth when expired.
 
 ## Migrating from shop-based to user-based token strategy
 

lib/generators/shopify_app/shop_model/shop_model_generator.rb

@@ -40,6 +40,24 @@ def create_shop_with_access_scopes_migration
         end
       end
 
+      def create_shop_with_token_refresh_migration
+        token_refresh_prompt = <<~PROMPT
+          To support expiring offline access token with refresh, your Shop model needs to store \
+          token expiration dates and refresh tokens.
+
+          The following migration will add `expires_at`, `refresh_token`, and \
+          `refresh_token_expires_at` columns to the Shop model. \
+          Do you want to include this migration? [y/n]
+        PROMPT
+
+        if new_shopify_cli_app? || Rails.env.test? || yes?(token_refresh_prompt)
+          migration_template(
+            "db/migrate/add_shop_access_token_expiry_columns.erb",
+            "db/migrate/add_shop_access_token_expiry_columns.rb",
+          )
+        end
+      end
+
       def update_shopify_app_initializer
         gsub_file("config/initializers/shopify_app.rb", "ShopifyApp::InMemoryShopSessionStore", "Shop")
       end

lib/generators/shopify_app/shop_model/templates/db/migrate/add_shop_access_token_expiry_columns.erb

@@ -0,0 +1,7 @@
+class AddShopAccessTokenExpiryColumns < ActiveRecord::Migration[<%= rails_migration_version %>]
+  def change
+    add_column :shops, :expires_at, :datetime
+    add_column :shops, :refresh_token, :string
+    add_column :shops, :refresh_token_expires_at, :datetime
+  end
+end

lib/generators/shopify_app/shop_model/templates/shop.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Shop < ActiveRecord::Base
-  include ShopifyApp::ShopSessionStorageWithScopes
+  include ShopifyApp::ShopSessionStorage
 
   def api_version
     ShopifyApp.configuration.api_version

lib/generators/shopify_app/user_model/templates/user.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class User < ActiveRecord::Base
-  include ShopifyApp::UserSessionStorageWithScopes
+  include ShopifyApp::UserSessionStorage
 
   def api_version
     ShopifyApp.configuration.api_version

lib/shopify_app/session/shop_session_storage_with_scopes.rb

@@ -8,8 +8,8 @@ module ShopSessionStorageWithScopes
     included do
       ShopifyApp::Logger.deprecated(
         "ShopSessionStorageWithScopes is deprecated and will be removed in v23.0.0. " \
-        "Use ShopSessionStorage instead, which now handles access_scopes, expires_at, " \
-        "refresh_token, and refresh_token_expires_at automatically.",
+          "Use ShopSessionStorage instead, which now handles access_scopes, expires_at, " \
+          "refresh_token, and refresh_token_expires_at automatically.",
         "23.0.0",
       )
       validates :shopify_domain, presence: true, uniqueness: { case_sensitive: false }

lib/shopify_app/session/user_session_storage_with_scopes.rb

@@ -8,7 +8,7 @@ module UserSessionStorageWithScopes
     included do
       ShopifyApp::Logger.deprecated(
         "UserSessionStorageWithScopes is deprecated and will be removed in v23.0.0. " \
-        "Use UserSessionStorage instead, which now handles access_scopes and expires_at automatically.",
+          "Use UserSessionStorage instead, which now handles access_scopes and expires_at automatically.",
         "23.0.0",
       )