Merge branch 'main' into dependabot/github_actions/ruby/setup-ruby-1.265.0

Author: lizkenyon

.github/workflows/build.yml

@@ -11,10 +11,9 @@ jobs:
     strategy:
       matrix:
         version:
-          - 3.0
-          - 3.1
           - 3.2
           - 3.3
+          - 3.4
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: Set up Ruby ${{ matrix.version }}

BREAKING_CHANGES_FOR_V15.md

@@ -1,5 +1,99 @@
 # Breaking change notice for version 15.0.0
 
+## Removal of positional `storefront_access_token` parameter from Storefront GraphQL Client
+
+The `ShopifyAPI::Clients::Graphql::Storefront` class no longer accepts the public Storefront access token as a positional parameter. You must now use the named parameters `private_token:` or `public_token:` instead.
+
+This parameter was deprecated in [PR #1302](https://github.com/Shopify/shopify-api-ruby/pull/1302) (v14.1.0).
+
+### Previous implementation (deprecated in v14.1.0)
+
+```ruby
+# Old way: passing token as positional parameter
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token)
+
+# With API version
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, storefront_access_token, api_version: "2024-01")
+```
+
+### New implementation (required in v15.0.0)
+
+```ruby
+# Use private token (recommended)
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, private_token: storefront_private_access_token)
+
+# Or use public token
+client = ShopifyAPI::Clients::Graphql::Storefront.new(shop_url, public_token: storefront_public_access_token)
+
+# With API version
+client = ShopifyAPI::Clients::Graphql::Storefront.new(
+  shop_url,
+  private_token: storefront_private_access_token,
+  api_version: "2024-01"
+)
+```
+
+For more information on private vs public Storefront access tokens, see [Shopify's authentication documentation](https://shopify.dev/docs/api/usage/authentication#getting-started-with-private-access).
+## Removal of `LATEST_SUPPORTED_ADMIN_VERSION` and `RELEASE_CANDIDATE_ADMIN_VERSION` constants
+
+The `LATEST_SUPPORTED_ADMIN_VERSION` and `RELEASE_CANDIDATE_ADMIN_VERSION` constants have been removed to prevent semantic versioning (semver) breaking changes. Previously, these constants would automatically update every quarter when new API versions were released, causing unintended breaking changes for apps.
+
+### Migration Guide
+
+**If you were using these constants directly:**
+
+```ruby
+# Before (v14 and earlier)
+api_version = ShopifyAPI::LATEST_SUPPORTED_ADMIN_VERSION
+# or
+api_version = ShopifyAPI::RELEASE_CANDIDATE_ADMIN_VERSION
+
+# After (v15+)
+api_version = "2025-07" # Explicitly specify the version you want to use
+```
+
+**In your Context.setup:**
+
+The `api_version` parameter has always been required in `Context.setup`, so most apps should not be affected. However, you must now explicitly specify which API version you want to use:
+
+```ruby
+# Before (v14 and earlier)
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host: "<https://application-host-name.com>",
+  scope: "read_orders,read_products,etc",
+  is_embedded: true,
+  api_version: ShopifyAPI::LATEST_SUPPORTED_ADMIN_VERSION, # This constant no longer exists
+  is_private: false,
+)
+
+# After (v15+)
+ShopifyAPI::Context.setup(
+  api_key: "<api-key>",
+  api_secret_key: "<api-secret-key>",
+  host: "<https://application-host-name.com>",
+  scope: "read_orders,read_products,etc",
+  is_embedded: true,
+  api_version: "2025-07", # Explicitly specify the version
+  is_private: false,
+)
+```
+
+**Finding the right API version:**
+
+You can see all supported API versions by referencing:
+```ruby
+ShopifyAPI::SUPPORTED_ADMIN_VERSIONS
+# => ["unstable", "2025-10", "2025-07", "2025-04", ...]
+```
+
+**Why this change?**
+ By requiring explicit version specification, apps can:
+- Control when they upgrade to new API versions
+- Test thoroughly before upgrading
+- Avoid unexpected breaking changes from automatic version updates
+
 ## Removal of `ShopifyAPI::Webhooks::Handler`
 
 The `ShopifyAPI::Webhooks::Handler` class has been removed in favor of `ShopifyAPI::Webhooks::WebhookHandler`. The `ShopifyAPI::Webhooks::WebhookHandler` class is now the recommended way to handle webhooks.
@@ -8,7 +102,8 @@ Make a module or class that includes or extends `ShopifyAPI::Webhooks::WebhookHa
 
 In v14, adding new fields to the callback would become a breaking change. To make this code more flexible, handlers will now receive an object that can be typed and extended.
 
-`data` will have the following keys
+`data` will have the following keys:
+
 - `topic`, `String` - The topic of the webhook
 - `shop`, `String` - The shop domain of the webhook
 - `body`, `T::Hash[String, T.untyped]`- The body of the webhook
@@ -21,8 +116,8 @@ module WebhookHandler
   extend ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle_webhook(data:)
-      puts "Received webhook! topic: #{data.topic} shop: #{data.shop} body: #{data.body} webhook_id: #{data.webhook_id} api_version: #{data.api_version"
+    def handle(data:)
+      puts "Received webhook! topic: #{data.topic} shop: #{data.shop} body: #{data.body} webhook_id: #{data.webhook_id} api_version: #{data.api_version}"
     end
   end
 end

BREAKING_CHANGES_FOR_V16.md

@@ -0,0 +1,76 @@
+# Breaking change notice for version 16.0.0
+
+## Minimum Ruby Version Requirement
+
+The minimum required Ruby version has been updated from 3.0 to 3.2.
+
+### Why this change?
+
+Ruby 3.0  and 3.1 have reached End of Life (EOL).
+
+### Migration Guide
+
+If you're currently using Ruby 3.0 or 3.1, you'll need to upgrade to Ruby 3.2 or higher before upgrading to shopify-api-ruby v16.0.0.
+
+**Note:** Ruby 3.2+ includes performance improvements and new features. Most applications should not require code changes beyond updating the Ruby version itself.
+## Removal of `Session#serialize` and `Session.deserialize` methods
+
+The `Session#serialize` and `Session.deserialize` methods have been removed due to a security vulnerability. The `deserialize` method used `Oj.load` without safe mode, which allows instantiation of arbitrary Ruby objects.
+
+These methods were originally created for session persistence when the library handled session storage. After session storage was deprecated in v12.3.0, applications became responsible for their own session persistence, making these methods unnecessary for their original purpose.
+
+### Why this change?
+
+**No impact on most applications:** The `shopify_app gem` stores individual session attributes in database columns and reconstructs sessions using `Session.new()`, which is the recommended pattern.
+
+## Migration Guide
+
+If your application was using `Session#serialize` and `Session.deserialize` for session persistence, you'll need to refactor to store individual session attributes and reconstruct sessions using `Session.new()`.
+
+### Previous implementation (removed in v16.0.0)
+
+```ruby
+# Storing a session
+session = ShopifyAPI::Auth::Session.new(
+  shop: "example.myshopify.com",
+  access_token: "shpat_xxxxx",
+  scope: "read_products,write_orders"
+)
+
+serialized_data = session.serialize
+# Store serialized_data in Redis, database, etc.
+redis.set("session:#{session.id}", serialized_data)
+
+# Retrieving a session
+serialized_data = redis.get("session:#{session_id}")
+session = ShopifyAPI::Auth::Session.deserialize(serialized_data)
+```
+
+### New implementation (required in v16.0.0)
+
+Store individual session attributes and reconstruct using `Session.new()`:
+
+## Reference: shopify_app gem implementation
+
+The [shopify_app gem](https://github.com/Shopify/shopify_app) provides a reference implementation of session storage that follows these best practices:
+
+**Shop Session Storage** ([source](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage.rb)):
+```ruby
+# Stores attributes in database columns
+def store(auth_session)
+  shop = find_or_initialize_by(shopify_domain: auth_session.shop)
+  shop.shopify_token = auth_session.access_token
+  shop.save!
+end
+
+# Reconstructs using Session.new()
+def retrieve(id)
+  shop = find_by(id: id)
+  return unless shop
+
+  ShopifyAPI::Auth::Session.new(
+    shop: shop.shopify_domain,
+    access_token: shop.shopify_token
+  )
+end
+```

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 ## Unreleased
+- ⚠️ [Breaking] Minimum required Ruby version is now 3.2. Ruby 3.0 and 3.1 are no longer supported.
+- ⚠️ [Breaking] Removed `Session#serialize` and `Session.deserialize` methods due to security concerns (RCE vulnerability via `Oj.load`). These methods were not used internally by the library. If your application relies on session serialization, use `Session.new()` to reconstruct sessions from stored attributes instead.
+
+- Add support for expiring offline access tokens with refresh tokens. See [OAuth documentation](docs/usage/oauth.md#expiring-offline-access-tokens) for details.
+- Add `ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token` method to migrate existing non-expiring offline tokens to expiring tokens. See [migration documentation](docs/usage/oauth.md#migrating-non-expiring-tokens-to-expiring-tokens) for details.
+
+### 15.0.0
+
+- ⚠️ [Breaking] Removed deprecated `ShopifyAPI::Webhooks::Handler` interface. Apps must migrate to `ShopifyAPI::Webhooks::WebhookHandler` which provides `webhook_id` and `api_version` in addition to `topic`, `shop`, and `body`. See [BREAKING_CHANGES_FOR_V15.md](BREAKING_CHANGES_FOR_V15.md) for migration guide.
+- Add support for 2025-10 API version
+  - Updated `LATEST_SUPPORTED_ADMIN_VERSION` to `2025-10`
+- [#1411](https://github.com/Shopify/shopify-api-ruby/pull/1411) Remove `LATEST_SUPPORTED_ADMIN_VERSION` and `RELEASE_CANDIDATE_ADMIN_VERSION` constants to prevent semver violations. Developers must now explicitly specify API versions. See the [migration guide](BREAKING_CHANGES_FOR_V15.md#removal-of-latest_supported_admin_version-and-release_candidate_admin_version-constants) for details.
 
 - [#1405](https://github.com/Shopify/shopify-api-ruby/pull/1405) Fix webhook registration for topics containing dots (e.g., `customer.tags_added`, `customer.tags_removed`)
 

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shopify_api (14.11.1)
+    shopify_api (15.0.0)
       activesupport
       concurrent-ruby
       hash_diff

docs/getting_started.md

@@ -28,7 +28,8 @@ ShopifyAPI::Context.setup(
   scope: "read_orders,read_products,etc",
   is_embedded: true, # Set to true if you are building an embedded app
   is_private: false, # Set to true if you are building a private app
-  api_version: "2021-01" # The version of the API you would like to use
+  api_version: "2021-01", # The version of the API you would like to use
+  expiring_offline_access_tokens: true # Set to true to enable expiring offline access tokens with refresh tokens
 )
 ```
 

docs/usage/oauth.md

@@ -13,6 +13,9 @@ For more information on authenticating a Shopify app please see the [Types of Au
   - [Token Exchange](#token-exchange)
   - [Authorization Code Grant](#authorization-code-grant)
   - [Client Credentials Grant](#client-credentials-grant)
+- [Expiring Offline Access Tokens](#expiring-offline-access-tokens)
+  - [Refreshing Access Tokens](#refreshing-access-tokens)
+  - [Migrating Non-Expiring Tokens to Expiring Tokens](#migrating-non-expiring-tokens-to-expiring-tokens)
 - [Using OAuth Session to make authenticated API calls](#using-oauth-session-to-make-authenticated-api-calls)
 
 ## Session Persistence
@@ -305,6 +308,132 @@ end
 
 ```
 
+## Expiring Offline Access Tokens
+
+
+To start requesting expiring offline access tokens, set the `expiring_offline_access_tokens` parameter to `true` when setting up the Shopify context:
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: <SHOPIFY_API_KEY>,
+  api_secret_key: <SHOPIFY_API_SECRET>,
+  api_version: <SHOPIFY_API_VERSION>,
+  scope: <SHOPIFY_API_SCOPES>,
+  expiring_offline_access_tokens: true, # Enable expiring offline access tokens
+  ...
+)
+```
+
+When enabled:
+- **Authorization Code Grant**: The OAuth flow will request expiring offline access tokens by sending `expiring: 1` parameter
+- **Token Exchange**: When requesting offline access tokens via token exchange, the flow will request expiring tokens
+
+The resulting `Session` object will contain:
+- `access_token`: The access token that will eventually expire
+- `expires`: The expiration time for the access token
+- `refresh_token`: A token that can be used to refresh the access token
+- `refresh_token_expires`: The expiration time for the refresh token
+
+### Refreshing Access Tokens
+
+When your access token expires, you can use the refresh token to obtain a new access token using the `ShopifyAPI::Auth::RefreshToken.refresh_access_token` method.
+
+#### Input
+| Parameter      | Type     | Required? | Notes                                                                                           |
+| -------------- | -------- | :-------: | ----------------------------------------------------------------------------------------------- |
+| `shop`         | `String` | Yes       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                               |
+| `refresh_token`| `String` | Yes       | The refresh token from the session.                                                             |
+
+#### Output
+This method returns a new `ShopifyAPI::Auth::Session` object with a fresh access token and a new refresh token. Your app should store this new session to replace the expired one.
+
+#### Example
+```ruby
+def refresh_session(shop, refresh_token)
+  begin
+    # Refresh the access token using the refresh token
+    new_session = ShopifyAPI::Auth::RefreshToken.refresh_access_token(
+      shop: shop,
+      refresh_token: refresh_token
+    )
+
+    # Store the new session, replacing the old one
+    MyApp::SessionRepository.store_shop_session(new_session)
+  rescue ShopifyAPI::Errors::HttpResponseError => e
+    puts("Failed to refresh access token: #{e.message}")
+    raise e
+  end
+end
+```
+#### Checking Token Expiration
+The `Session` object provides helper methods to check if tokens have expired:
+
+```ruby
+session = MyApp::SessionRepository.retrieve_shop_session_by_shopify_domain(shop)
+
+# Check if the access token has expired
+if session.expired?
+  # Access token has expired, refresh it
+  new_session = ShopifyAPI::Auth::RefreshToken.refresh_access_token(
+    shop: session.shop,
+    refresh_token: session.refresh_token
+  )
+  MyApp::SessionRepository.store_shop_session(new_session)
+end
+
+# Check if the refresh token has expired
+if session.refresh_token_expired?
+  # Refresh token has expired, need to re-authenticate with OAuth
+end
+```
+
+### Migrating Non-Expiring Tokens to Expiring Tokens
+
+If you have existing non-expiring offline access tokens and want to migrate them to expiring tokens, you can use the `ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token` method. This performs a token exchange that converts your non-expiring offline token into an expiring one with a refresh token.
+
+> [!WARNING]
+> This is a **one-time, irreversible migration** per shop. Once you migrate a shop's token to an expiring token, you cannot convert it back to a non-expiring token. The shop would need to reinstall your app with `expiring_offline_access_tokens: false` in your Context configuration to obtain a new non-expiring token.
+
+#### Input
+| Parameter      | Type     | Required? | Notes                                                                                           |
+| -------------- | -------- | :-------: | ----------------------------------------------------------------------------------------------- |
+| `shop`         | `String` | Yes       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                               |
+| `non_expiring_offline_token` | `String` | Yes | The non-expiring offline access token to migrate. |
+
+#### Output
+This method returns a new `ShopifyAPI::Auth::Session` object with an expiring access token and refresh token. Your app should store this new session to replace the non-expiring one.
+
+#### Example
+```ruby
+def migrate_shop_to_expiring_offline_token(shop)
+  # Retrieve the existing non-expiring session
+  old_session = MyApp::SessionRepository.retrieve_shop_session_by_shopify_domain(shop)
+
+  # Migrate to expiring token
+  new_session = ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+    shop: shop,
+    non_expiring_offline_token: old_session.access_token
+  )
+
+  # Store the new expiring session, replacing the old one
+  MyApp::SessionRepository.store_shop_session(new_session)
+end
+```
+
+#### Migration Strategy
+When migrating your app to use expiring tokens, follow this order:
+
+1. **Update your database schema** to add `expires_at` (timestamp), `refresh_token` (string) and `refresh_token_expires` (timestamp) columns to your session storage
+2. **Implement refresh logic** in your app to handle token expiration using `ShopifyAPI::Auth::RefreshToken.refresh_access_token`
+3. **Enable expiring tokens in your Context setup** so new installations will request and receive expiring tokens:
+   ```ruby
+   ShopifyAPI::Context.setup(
+     expiring_offline_access_tokens: true,
+     # ... other config
+   )
+   ```
+4. **Migrate existing non-expiring tokens** for shops that have already installed your app using the migration method above
+
 ## Using OAuth Session to make authenticated API calls
 Once your OAuth flow is complete, and you have persisted your `Session` object, you may use that `Session` object to make authenticated API calls.