Add docs and changelog

zzooeeyy · zzooeeyy · commit b3871b4364bb · 2025-11-17T16:51:57.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,13 @@ 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
+  - `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 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)
diff --git a/docs/Upgrading.md b/docs/Upgrading.md
@@ -47,6 +47,53 @@ If you do run into issues, we recommend looking at our [debugging tips.](https:/
 #### (v23.0.0) Drops support for Ruby 3.0
 The minimum ruby version is now 3.1
 
+#### (v23.0.0) - ShopSessionStorageWithScopes and UserSessionStorageWithScopes are deprecated
+
+`ShopSessionStorageWithScopes` and `UserSessionStorageWithScopes` are now deprecated in favor of `ShopSessionStorage` and `UserSessionStorage`, which handle all session attributes automatically (including `access_scopes`, `expires_at`, `refresh_token`, and `refresh_token_expires_at` for shops).
+
+**Migration:**
+
+1. Update your Shop model to use `ShopSessionStorage`:
+```ruby
+# Before
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorageWithScopes
+end
+
+# After
+class Shop < ActiveRecord::Base
+  include ShopifyApp::ShopSessionStorage
+end
+```
+
+2. Update your User model to use `UserSessionStorage`:
+```ruby
+# Before
+class User < ActiveRecord::Base
+  include ShopifyApp::UserSessionStorageWithScopes
+end
+
+# After
+class User < ActiveRecord::Base
+  include ShopifyApp::UserSessionStorage
+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.
+
+**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.
+
 #### (v23.0.0) - Deprecated methods in CallbackController
 The following methods from `ShopifyApp::CallbackController` have been deprecated in `v23.0.0`
 - `perform_after_authenticate_job`
diff --git a/docs/shopify_app/sessions.md b/docs/shopify_app/sessions.md
@@ -129,11 +129,11 @@ These methods are already implemented as a part of the `User` and `Shop` models
 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)
+  - [ShopSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage_with_scopes.rb) (Deprecated in 23.0.0)
   - [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)
+  - [UserSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage_with_scopes.rb) (Deprecated in 23.0.0)
   - [UserSessionStorage](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage.rb)
 
 ### Loading Sessions
@@ -206,6 +206,60 @@ user.with_shopify_session do
 end
 ```
 
+##### Automatic Access Token Refresh
+
+`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.
+
+**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
+
+**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.
@@ -300,39 +354,42 @@ class MyController < ApplicationController
 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:
+## 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. 
 
-### `ShopifyApp::ShopSessionStorageWithScopes`
-```ruby
-class Shop < ActiveRecord::Base
-  include ShopifyApp::ShopSessionStorageWithScopes
+### 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.
 
-  def access_scopes=(scopes)
-    # Store access scopes
-  end
-  def access_scopes
-    # Find access scopes
-  end
-end
-```
+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
+
+**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`:
 
-### `ShopifyApp::UserSessionStorageWithScopes`
 ```ruby
-class User < ActiveRecord::Base
-  include ShopifyApp::UserSessionStorageWithScopes
+# config/initializers/shopify_app.rb
+ShopifyApp.configure do |config|
+  # ... other configuration
 
-  def access_scopes=(scopes)
-    # Store access scopes
-  end
-  def access_scopes
-    # Find access scopes
-  end
+  # Enable checking session expiry dates
+  config.check_session_expiry_date = true
 end
+
+# For ShopifyAPI Context - enable expiring offline tokens
+ShopifyAPI::Context.setup(
+  # ... other configuration
+  offline_access_token_expires: true, # Opt-in to expiring offline tokens
+)
 ```
 
-## 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.
+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.
+
+**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.
+
+**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.
+
+**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.
 
 ## Migrating from shop-based to user-based token strategy
 
