shopify_api-graphql-request 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ac24b90edcc2ac73f86627c06801e1ef9ae67a470cd466befaacc920009e9c3
-  data.tar.gz: 8f56fd88505e60ce25cd4287b7ac781e9874f8507cf76a83080277953bec152a
+  metadata.gz: bee339fb15f11c233c7dc08e8e7333282a4e3372ce44278437bbff81898fd9a7
+  data.tar.gz: a83aaa1a7d828dc311ada7c1c4d65480d7bcef63cb3fa40f0e229978e8be25cb
 SHA512:
-  metadata.gz: 5cbb9adffc7ce34f8a46eee7698955153402ca5bd72232bf25653409d99be4c766b8cddf302ec7e42506c0db26d3e76e877c08b640750aec7306c1424c5781ea
-  data.tar.gz: 5aa3ddc3ba5dca7315e3a1a9e3af2f80389f3391cd09dae55986f8ba47d43319f70dd134808a34819105616ca4e38bc31054a2611294d58e76a15a57e1f7d39d
+  metadata.gz: 3290890d3abc1b59a82b053d038cae873b0038b478253f7e12ea8a7ee20d2c216c3ae5e86e9d80f8970cdc4b6245e516c723ba34ac60b16a12e45a90b37a1d83
+  data.tar.gz: f3e684ef553213512ff80f9252a171b32055746c1d9b4a1934cf4e470e30caf7ee594248ee5fbf42887435d25573be57d70be9d022ba1bfa4784e32d770bf34c

data/.env.template

@@ -9,6 +9,13 @@
 SHOPIFY_DOMAIN=
 SHOPIFY_TOKEN=
 
+# App credentials test test OAuth::AccessToken
+SHOPIFY_CLIENT_API_KEY=
+SHOPIFY_CLIENT_API_SECRET=
+
+# Refresh token needed to test OAuth::AccessToken#refresh
+SHOPIFY_REFRESH_TOKEN=
+
 # Will result in the creation of a metadafield on the customer. write_customers permission required
 SHOPIFY_CUSTOMER_ID=
 

data/Changes

@@ -0,0 +1,10 @@
+v0.1.0  2026-11-10
+--------------------
+Add OAuth::AccessToken to support Shopify expiring tokens
+Add :refresh option to Request to automatically refresh expiring tokens
+Add shopify_api:graphql:request:migrate_access_tokens Rake task for non-expiring token migration
+
+v0.0.2  2026-04-19
+--------------------
+Require TinyGID >= 0.1.2. This version allows one to call #parse and #to_s methods on #gid.
+Make #transform_keys private to communicate to implementors that it should not be called

data/README.md

@@ -1,15 +1,42 @@
 # ShopifyAPI::GraphQL::Request
 
+[![CI](https://github.com/ScreenStaring/shopify_api-graphql-request/actions/workflows/main.yml/badge.svg)](https://github.com/ScreenStaring/shopify_api-graphql-request/actions/workflows/main.yml)
+
 Small class to simplify the writing and handling of GraphQL queries and mutations for the Shopify Admin API.
-Comes with built-in retry, pagination, error handling, and more!
+Comes with built-in retry, token refresh, pagination, error handling, and more!
 
 ## Usage
 
-It's recommended to organize queries and mutations by subclassing `ShopifyAPI::GraphQL::Request`:
+Queries:
 
 ```rb
 require "shopify_api/graphql/request"
 
+request = ShopifyAPI::GraphQL::Request.new("a-shop", token)
+
+begin
+  product = request.execute(query, :id => "gid://shopify/Product/123").dig(:data, :product)
+  p product[:title]
+  p product[:description_html]
+rescue ShopifyAPI::GraphQL::Request::NotFoundError => e
+  p e
+end
+```
+
+And mutations:
+
+```rb
+begin
+  product = request.execute(mutation, :id => "gid://shopify/Product/123", :title => "Foo Hoo!").dig(:data, :product)
+rescue ShopifyAPI::GraphQL::Request::UserError => e
+  p e
+end
+```
+
+If your application contains a lot of query and/or mutations it's recommended to organize them by
+subclassing `ShopifyAPI::GraphQL::Request`:
+
+```rb
 class ShopifyProduct < ShopifyAPI::GraphQL::Request
   # Define your queries/mutations
   FIND =<<-GQL
@@ -149,38 +176,159 @@ class ShopifyProduct < ShopifyAPI::GraphQL::Request
 end
 ```
 
-### Making Requests Without Subclassing
+### Auto-Refreshing Expiring Access Tokens
 
-Of course you can make requests directly on an instance of `ShopifyAPI::GraphQL::Request`:
+`ShopifyAPI::GraphQL::Request` can automatically refresh Shopify's expiring offline access tokens before making a request, and automatically retry once on `401 Unauthorized` responses.
+
+To enable auto-refresh, pass the `:refresh` option:
 
 ```rb
-require "shopify_api/graphql/request"
+request = ShopifyAPI::GraphQL::Request.new(shop, token, :refresh => {
+  :client_id => SHOPIFY_CLIENT_ID,
+  :client_secret => SHOPIFY_CLIENT_SECRET,
+  :refresh_token => refresh_token,
+  :expires_at => expires_at, # Absolute Time or Integer Unix epoch timestamp
+  :refresh_expires_at => refresh_expires_at, # Absolute Time or Integer Unix epoch timestamp
+  :synchronize => ->(refresh, shopify_domain) do
+    shop = Shop.find_by!(:shopify_domain => shopify_domain)
+
+    shop.with_lock do
+      updates = refresh.call  # see Multi-Process Concurrency section
+      now = Time.now.to_i
+
+      shop.update!(
+        :access_token => tokens["access_token"],
+        :expires_at => now + tokens["expires_in"],
+        :refresh_token => tokens["refresh_token"],
+        :refresh_expires_at => now + tokens["refresh_token_expires_in"]
+      )
+    end
+  end
+})
+```
 
-request = ShopifyAPI::GraphQL::Request.new("a-shop", token)
+#### The `:synchronize` Callback
 
-begin
-  product = request.execute(query, :id => "gid://shopify/Product/123").dig(:data, :product)
-  p product[:title]
-  p product[:description_html]
-rescue ShopifyAPI::GraphQL::Request::NotFoundError => e
-  p e
+Because refreshed tokens must be persisted for future requests, `:synchronize` is required. It is passed a `refresh` proc and the shop's Shopify domain:
+
+* `refresh.call` returns a `Hash` with `:access_token`, `:expires_at`, `:refresh_token`, and `:refresh_expires_at`. Note that `:expires_at` and `:refresh_expires_at` are absolute Unix epoch timestamps (in seconds), not relative duration offsets like Shopify's `expires_in`.
+* Calling `refresh.call` without arguments refreshes using the client's **current in-memory token state**. If you're using multiple processes see [Multi-Process Concurrency](#multi-process-concurrency)
+
+#### Multi-Process Concurrency
+
+In multi-process environments multiple processes may attempt to refresh an expired token simultaneously. To prevent duplicate refresh requests and token invalidation
+pass the freshly read storage state to `refresh`:
+
+```rb
+:synchronize => ->(refresh, shop) do
+  shop = Shop.find_by!(:shopify_domain => shopify_domain)
+  shop.with_lock do
+    # Pass the latest token state.
+    # If another worker already refreshed it refresh.call returns the fresh state without hitting Shopify.
+    new_state = refresh.call(
+      :access_token => shop.access_token,
+      :expires_at => shop.expires_at,
+      :refresh_token => shop.refresh_token,
+      :refresh_expires_at => shop.refresh_expires_at
+    )
+
+    # save new_state
+  end
 end
 ```
 
-And mutations:
+### Migrating Non-Expiring Access Tokens
+
+To migrate a legacy non-expiring offline access token to an expiring offline access token, call `ShopifyAPI::GraphQL::Request::OAuth::AccessToken#migrate`:
 
 ```rb
-begin
-  product = request.execute(mutation, :id => "gid://shopify/Product/123", :title => "Foo Hoo!").dig(:data, :product)
-rescue ShopifyAPI::GraphQL::Request::UserError => e
-  p e
+client = ShopifyAPI::GraphQL::Request::OAuth::AccessToken.new(
+  SHOPIFY_CLIENT_ID,
+  SHOPIFY_CLIENT_SECRET,
+  shop
+)
+
+tokens = client.migrate(non_expiring_token)
+```
+
+`#migrate` returns Shopify's token exchange response `Hash`:
+
+```rb
+{
+  "access_token" => "shpca_...",
+  "scope" => "read_products,write_products",
+  "expires_in" => 3599,
+  "refresh_token" => "shprt_...",
+  "refresh_token_expires_in" => 7775999
+}
+```
+
+You can then calculate absolute expiration timestamps and persist the tokens for use with [Auto-Refreshing Expiring Access Tokens](#auto-refreshing-expiring-access-tokens):
+
+```rb
+now = Time.now.to_i
+
+store.update!(
+  :access_token => tokens["access_token"],
+  :expires_at => now + tokens["expires_in"],
+  :refresh_token => tokens["refresh_token"],
+  :refresh_expires_at => now + tokens["refresh_token_expires_in"]
+)
+```
+
+If the token is invalid or cannot be migrated, a `ShopifyAPI::GraphQL::Request::OAuth::AccessToken::InvalidTokenError` will be raised.
+
+#### Rake Task
+
+You can also migrate tokens using the provided rake task:
+
+```sh
+# Migrate a single shop:
+bundle exec rake shopify_api:graphql:request:migrate_access_tokens SHOPIFY_API_KEY=X SHOPIFY_API_SECRET=Y SHOP=my-shop TOKEN=shpat_...
+
+# Migrate from a CSV file (with "shop" and "token" columns). HANDLER is required, see below:
+bundle exec rake shopify_api:graphql:request:migrate_access_tokens SHOPIFY_API_KEY=X SHOPIFY_API_SECRET=Y FILE=tokens.csv HANDLER=update_token.rb
+```
+
+A single shop's tokens are always printed. `HANDLER=file.rb` is required with `FILE` (nothing is printed for CSV) and optional with `SHOP`. Use it to persist the new tokens. The file is `load`ed and must define `update_token(shop, tokens)`, which is called with the
+shop and the return value of `#migrate`:
+
+```rb
+# update_token.rb
+def update_token(shop, tokens)
+  Shop.find_by!(:domain => shop).update!(:access_token => tokens["access_token"], ...)
 end
 ```
 
+```sh
+bundle exec rake shopify_api:graphql:request:migrate_access_tokens SHOPIFY_API_KEY=X SHOPIFY_API_SECRET=Y FILE=tokens.csv HANDLER=update_token.rb
+```
+
+#### Recovering a Lost Response
+
+If a migration request fails or the response is lost, you can safely repeat the `#migrate` call with the original non-expiring token within
+7 days of the initial exchange. Shopify will return the same token pair.
+
 ### More Info
 
 For more information checkout [the API docs](https://rdoc.info/gems/shopify_api-graphql-request)
 
+## Why Use This Instead of Shopify's API Client?
+
+- Easy-to-use
+- Built-in retry
+- Built-in pagination
+- Improved exception handling
+- You can use `:snake_case` hash keys
+- Lightweight
+
+Overall, Shopify's API client is bloated trash that will give you development headaches and long-term maintenance nightmares.
+
+We used to use it, staring way back in 2015, but eventually had to pivot away from their Ruby libraries due to developer
+frustration and high maintenance cost (and don't get us started on the ShopifyApp gem!@#).
+
+For more information see: https://github.com/Shopify/shopify-api-ruby/issues/1181
+
 ## Testing
 
 `cp env.template .env` and fill-in `.env` with the missing values. This requires a Shopify store.
@@ -188,7 +336,6 @@ For more information checkout [the API docs](https://rdoc.info/gems/shopify_api-
 ## See Also
 
 - [Shopify Dev Tools](https://github.com/ScreenStaring/shopify-dev-tools/) - Command-line program to assist with the development and/or maintenance of Shopify apps and stores
-- [Shopify ID Export](https://github.com/ScreenStaring/shopify_id_export/) - Dump Shopify product and variant IDs —along with other identifiers— to a CSV or JSON file
 - [`ShopifyAPI::GraphQL::Tiny`](https://github.com/ScreenStaring/shopify_api-graphql-tiny/) - Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry
 - [`TinyGID`](https://github.com/sshaw/tiny_gid/) - Build Global ID (`gid://`) URI strings from scalar values
 
@@ -198,4 +345,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ---
 
-Made by [ScreenStaring](http://screenstaring.com)
+Made by [ScreenStaring](https://screenstaring.com)

data/lib/shopify_api/graphql/request/oauth/access_token.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+require "json"
+require "net/http"
+require "uri"
+
+require "shopify_api/graphql/request/version"
+
+module ShopifyAPI
+  module GraphQL
+    class Request
+      module OAuth
+        ##
+        # Shopify OAuth access token operations
+        #
+        class AccessToken
+          InvalidTokenError = Class.new(Error)
+          InvalidRefreshTokenError = Class.new(Error)
+
+          TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
+          OFFLINE_TOKEN_TYPE = "urn:shopify:params:oauth:token-type:offline-access-token"
+          REFRESH_TOKEN_GRANT_TYPE = "refresh_token"
+
+          TOKEN_ENDPOINT = "https://%s/admin/oauth/access_token"
+
+          USER_AGENT = "ShopifyAPI::GraphQL::Request v#{VERSION} (Ruby v#{RUBY_VERSION})"
+
+          SHOPIFY_DOMAIN = ".myshopify.com"
+
+          ##
+          # === Arguments
+          #
+          # [client_id (String)] App's client ID
+          # [client_secret (String)] App's client secret
+          # [shop (String)] Shopify domain to make requests against
+          # [options (Hash)] Client options. Optional.
+          #
+          # === Options
+          #
+          # [:open_timeout (Numeric)] Number of seconds to wait for the connection to open. Defaults to Net::HTTP's default.
+          # [:read_timeout (Numeric)] Number of seconds to wait for a response. Defaults to Net::HTTP's default.
+          # [:debug (Boolean|IO)] Output the HTTP request/response to +STDERR+ or to its value if it's an +IO+. Defaults to +false+.
+          #
+          # === Errors
+          #
+          # ArgumentError if no +client_id+, +client_secret+, or +shop+ is provided.
+          #
+          def initialize(client_id, client_secret, shop, options = nil)
+            raise ArgumentError, "client_id required" if client_id.to_s.strip.empty?
+            raise ArgumentError, "client_secret required" if client_secret.to_s.strip.empty?
+            raise ArgumentError, "shop required" if shop.to_s.strip.empty?
+
+            @client_id = client_id
+            @client_secret = client_secret
+            @domain = shopify_domain(shop)
+
+            options ||= {}
+
+            @open_timeout = options[:open_timeout]
+            @read_timeout = options[:read_timeout]
+
+            if options[:debug]
+              @debug = options[:debug].is_a?(IO) ? options[:debug] : $stderr
+            end
+
+            @endpoint = URI(sprintf(TOKEN_ENDPOINT, @domain))
+          end
+
+          ##
+          # Migrate a legacy non-expiring offline access token to an expiring offline access token
+          #
+          # === Arguments
+          #
+          # [non_expiring_token (String)] Existing non-expiring offline access token to migrate
+          #
+          # === Returns
+          #
+          # [Hash] The token response. Unmodified.
+          #
+          # === Errors
+          #
+          # ArgumentError, InvalidTokenError, Error
+          #
+          def migrate(non_expiring_token)
+            raise ArgumentError, "token required" if non_expiring_token.to_s.strip.empty?
+
+            request(
+              :client_id => @client_id,
+              :client_secret => @client_secret,
+              :grant_type => TOKEN_EXCHANGE_GRANT_TYPE,
+              :subject_token => non_expiring_token,
+              :subject_token_type => OFFLINE_TOKEN_TYPE,
+              :requested_token_type => OFFLINE_TOKEN_TYPE,
+              :expiring => 1
+            )
+          end
+
+          ##
+          # Refresh an expiring offline access token
+          #
+          # === Arguments
+          #
+          # [refresh_token (String)] Refresh token to use
+          #
+          # === Returns
+          #
+          # [Hash] The token response. Unmodified.
+          #
+          # === Errors
+          #
+          # ArgumentError, InvalidRefreshTokenError, Error
+          #
+          def refresh(refresh_token)
+            raise ArgumentError, "refresh token required" if refresh_token.to_s.strip.empty?
+
+            request(
+              :client_id => @client_id,
+              :client_secret => @client_secret,
+              :grant_type => REFRESH_TOKEN_GRANT_TYPE,
+              :refresh_token => refresh_token
+            )
+          end
+
+          private
+
+          def request(params)
+            response = post(params)
+            body = parse_body(response)
+
+            handle_error(response, body) unless response.is_a?(Net::HTTPSuccess)
+
+            body
+          end
+
+          def post(params)
+            http = Net::HTTP.new(@endpoint.host, @endpoint.port)
+            http.use_ssl = true
+            http.open_timeout = @open_timeout if @open_timeout
+            http.read_timeout = @read_timeout if @read_timeout
+            http.set_debug_output(@debug) if @debug
+
+            post = Net::HTTP::Post.new(@endpoint.path)
+            post.body = URI.encode_www_form(params)
+            post["Content-Type"] = "application/x-www-form-urlencoded"
+            post["Accept"] = "application/json"
+            post["User-Agent"] = USER_AGENT
+
+            http.start { |connection| connection.request(post) }
+          end
+
+          def parse_body(response)
+            return if response.body.nil? || response.body.empty?
+            return response.body unless response["Content-Type"].to_s.include?("json")
+
+            JSON.parse(response.body)
+          rescue JSON::ParserError => e
+            raise Error, "failed to parse JSON response: #{e.message}"
+          end
+
+          def handle_error(response, body)
+            error = body["error"] if body.is_a?(Hash)
+            message = error_message(body)
+
+            if response.code == "400" && (error == "invalid_subject_token" || error == "invalid_requested_token_type")
+              raise InvalidTokenError, "failed to migrate access token for #{@domain}: #{message}"
+            # RFC 6749 §5.2 specifies HTTP 400 for invalid_grant, but Shopify returns HTTP 401
+            # when a refresh token is inactive, expired, or already rotated. Check both to be safe.
+            elsif (response.code == "400" || response.code == "401") && error == "invalid_grant"
+              raise InvalidRefreshTokenError, "failed to refresh access token for #{@domain}: #{message}"
+            else
+              raise Error, "failed to request access token for #{@domain}: #{message} (HTTP #{response.code})"
+            end
+          end
+
+          def error_message(body)
+            return body unless body.is_a?(Hash)
+
+            body["error_description"] || body["error"] || body.to_s
+          end
+
+          def shopify_domain(host)
+            domain = host.sub(%r{\Ahttps?://}i, "")
+            domain << SHOPIFY_DOMAIN unless domain.end_with?(SHOPIFY_DOMAIN)
+            domain
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/graphql/request/oauth/access_token_migrator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "csv"
+require "pp"
+
+require "shopify_api/graphql/request/oauth/access_token"
+
+module ShopifyAPI
+  module GraphQL
+    class Request
+      module OAuth
+        ##
+        # Migrates legacy non-expiring offline access tokens to expiring ones for
+        # a single shop or for many shops listed in a CSV file.
+        #
+        # Backs the +shopify_api:graphql:request:migrate_access_tokens+ rake task.
+        #
+        class AccessTokenMigrator
+          HANDLER_METHOD = :update_token
+
+          ##
+          # === Arguments
+          #
+          # [client_id (String)] Shopify app client ID
+          # [client_secret (String)] Shopify app client secret
+          # [options (Hash)]
+          #
+          # === Options
+          #
+          # [:shop (String)] Shop to migrate.
+          # [:token (String)] Non-expiring token for +:shop+
+          # [:file (String)] CSV file with +shop+ and +token+ columns. Ignored if +:shop+ is given. Requires +:handler+.
+          # [:handler (String)] Ruby file to +load+. It must define +update_token(shop, tokens)+, which is called
+          #                     with the shop and the return value of AccessToken#migrate.
+          # [:out (IO)] Where to write results. Defaults to +$stdout+.
+          #
+          # === Errors
+          #
+          # ArgumentError
+          #
+          def initialize(client_id, client_secret, options = {})
+            @client_id = client_id
+            @client_secret = client_secret
+            @shop = nil_if_blank(options[:shop])
+            @token = nil_if_blank(options[:token])
+            @file = nil_if_blank(options[:file])
+            @handler = nil_if_blank(options[:handler])
+            @out = options[:out] || $stdout
+
+            raise ArgumentError, "client_id required" if nil_if_blank(client_id).nil?
+            raise ArgumentError, "client_secret required" if nil_if_blank(client_secret).nil?
+            raise ArgumentError, "shop or file required" unless @shop || @file
+            raise ArgumentError, "handler required when using file" if !@shop && !@handler
+          end
+
+          ##
+          # Perform the migration(s).
+          #
+          # === Returns
+          #
+          # [Array<Hash>] One +{ :shop => String, :result => Hash }+ per migrated shop
+          #
+          # === Errors
+          #
+          # ArgumentError, AccessToken::InvalidTokenError, AccessToken::Error
+          #
+          def run
+            pairs = @shop ? [single_shop_and_token] : rows
+            load_handler if @handler
+
+            pairs.map { |shop, token| migrate(shop, token) }
+          end
+
+          private
+
+          def nil_if_blank(value)
+            value unless value.to_s.strip.empty?
+          end
+
+          def load_handler
+            raise ArgumentError, "Handler not found: #{@handler}" unless File.file?(@handler)
+
+            load File.expand_path(@handler)
+            return if respond_to?(HANDLER_METHOD, true)
+
+            raise ArgumentError, "Handler must define #{HANDLER_METHOD}: #{@handler}"
+          end
+
+          def single_shop_and_token
+            raise ArgumentError, "token required" unless @token
+
+            [@shop, @token]
+          end
+
+          def rows
+            raise ArgumentError, "File not found: #{@file}" unless File.file?(@file)
+
+            table = CSV.read(@file, :headers => true, :skip_blanks => true, :converters => ->(value) { value&.strip }, :header_converters => ->(h) { h.to_s.strip.downcase })
+            unless table.headers.include?("shop") && table.headers.include?("token")
+              raise ArgumentError, "CSV must contain 'shop' and 'token' columns"
+            end
+
+            table.map { |row| [row["shop"], row["token"]] }.reject { |shop, token| shop.nil? && token.nil? }
+          end
+
+          def migrate(shop, token)
+            client = AccessToken.new(@client_id, @client_secret, shop)
+            result = client.migrate(token)
+
+            @out.puts result.pretty_inspect if @shop
+
+            call_handler(result, shop) if @handler
+
+            { :shop => shop, :result => result }
+          end
+
+          def call_handler(result, shop)
+            send(HANDLER_METHOD, shop, result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shopify_api/graphql/request/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module GraphQL
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path("../../../tasks/shopify.rake", __dir__)
+
+        # Task is also usable outside Rails, so only add the dep here
+        Rake::Task["shopify_api:graphql:request:migrate_access_tokens"].enhance([:environment])
+      end
+    end
+  end
+end

data/lib/shopify_api/graphql/request/tasks.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+load File.expand_path("../../../tasks/shopify.rake", __dir__)

data/lib/shopify_api/graphql/request/version.rb

@@ -3,7 +3,7 @@
 module ShopifyAPI
   module GraphQL
     class Request
-      VERSION = "0.0.1"
+      VERSION = "0.1.0"
     end
   end
 end

data/lib/shopify_api/graphql/request.rb

@@ -13,6 +13,12 @@ module ShopifyAPI
     #
     class Request
       Error = Class.new(StandardError)
+      RefreshNotCalledError = Class.new(Error)
+
+      # Smallest plausible Unix epoch timestamp (Sep 2001). Used to guard against callers
+      # mistakenly passing relative duration offsets (e.g., 3600 or Shopify's `expires_in`)
+      # instead of an absolute point in time.
+      MIN_EPOCH_TIMESTAMP = 1_000_000_000
 
       class UserError < Error
         attr_reader :errors
@@ -60,6 +66,21 @@ module ShopifyAPI
       # [:raise_if_not_found (Boolean)] If +true+ raise a NotFoundError if the requested record is not found. Defaults to +true+.
       # [:raise_if_user_errors (Boolean)] If +true+ raise a UserError if the mutation resulted in user errors. Defaults to +true+.
       # [:snake_case (Boolean)] Convert response `Hash` keys to +snake_case+ symbols. Defaults to +true+.
+      # [:refresh (Hash)] Auto-refresh expiring access tokens. Requires +:client_id+, +:client_secret+,
+      #   +:expires_at+, +:refresh_token+, +:refresh_expires_at+, and +:synchronize+.
+      #   +:expires_at+ and +:refresh_expires_at+ must be absolute timestamps (+Time+s or Integer Unix epoch timestamps in seconds),
+      #   not relative duration offsets (e.g. Shopify's +expires_in+).
+      #
+      #   +:synchronize+ is a Proc called with a refresh Proc and the shop. It should persist the new token
+      #   state returned by the refresh Proc:
+      #
+      #     :synchronize => ->(refresh, shop) do
+      #       store.update!(refresh.call)
+      #     end
+      #
+      #   Calling +refresh.call+ without arguments uses the client's current in-memory token state.
+      #   In multi-process environments, pass the freshly read token state from storage (e.g. +refresh.call(db_state)+)
+      #   under a lock to prevent concurrent workers from performing duplicate refreshes.
       #
       # Additional options: those accepted by {ShopifyAPI::GraphQL::Tiny}[https://rdoc.info/gems/shopify_api-graphql-tiny]
       #
@@ -70,9 +91,30 @@ module ShopifyAPI
           @options[name] = true unless @options.include?(name)
         end
 
+        @shop = shop
         @gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, @options)
 
         @gid = TinyGID.new("shopify")
+
+        refresh = @options[:refresh]
+        return unless refresh
+
+        raise ArgumentError, ":refresh must be a Hash" unless refresh.is_a?(Hash)
+
+        missing = [:client_id, :client_secret, :expires_at, :refresh_token, :refresh_expires_at, :synchronize].reject { |name| refresh.include?(name) }
+        raise ArgumentError, ":refresh requires #{missing.join(", ")}" if missing.any?
+
+        validate_timestamp(:expires_at, refresh[:expires_at])
+        validate_timestamp(:refresh_expires_at, refresh[:refresh_expires_at]) if refresh[:refresh_expires_at]
+
+        @oauth = OAuth::AccessToken.new(refresh[:client_id], refresh[:client_secret], shop, @options)
+        @synchronize = refresh[:synchronize]
+        @token_state = {
+          :access_token => token,
+          :expires_at => refresh[:expires_at],
+          :refresh_token => refresh[:refresh_token],
+          :refresh_expires_at => refresh[:refresh_expires_at]
+        }
       end
 
       ##
@@ -89,9 +131,9 @@ module ShopifyAPI
       #
       #  These override the instance's defaults for a single query or mutation.
       #
-      # [:raise_if_not_found (Boolean)]
-      # [:raise_if_user_errors (Boolean)]
-      # [:snake_case (Boolean)]
+      # [:raise_if_not_found (Boolean)] - raise a `ShopifyAPI::GraphQL::Request::NotFoundError` if query target is not found; defaults to +true+
+      # [:raise_if_user_errors (Boolean)] - raise a `ShopifyAPI::GraphQL::Request::UserError` if the response contains them; defaults to +true+
+      # [:snake_case (Boolean)] - Accept `:snake_case`-style hash keys and returned response hash keys to be snake_case; defaults to +true+
       #
       # === Returns
       #
@@ -100,6 +142,7 @@ module ShopifyAPI
       # === Errors
       #
       # * ArgumentError
+      # * ShopifyAPI::GraphQL::Request::RefreshNotCalledError - if :synchronize did not invoke refresh
       # * ShopifyAPI::GraphQL::Request::UserError - the a mutation contains user errors
       # * ShopifyAPI::GraphQL::Request::NotFoundError - if the query cannot be find the given object
       # * ShopifyAPI::GraphQL::Tiny::ConnectionError
@@ -111,8 +154,16 @@ module ShopifyAPI
         options = @options.merge(options || {})
 
         variables = camelize_keys(variables) if options[:snake_case]
+        ensure_fresh_token
+
+        begin
+          data = gql.execute(query, variables)
+        rescue ShopifyAPI::GraphQL::Tiny::HTTPError => error
+          raise unless refreshable? && error.code == "401"
 
-        data = gql.execute(query, variables)
+          refresh_after_401
+          data = gql.execute(query, variables)
+        end
 
         raise_if_not_found(data, variables) if options[:raise_if_not_found]
         raise_if_user_errors(data) if options[:raise_if_user_errors]
@@ -137,26 +188,34 @@ module ShopifyAPI
       #
       # === Errors
       #
-      #  See #execute
+      # See #execute
       #
       def paginate(query, variables = nil, options = nil)
         options = @options.merge(options || {})
 
         variables = camelize_keys(variables) if options[:snake_case]
+        ensure_fresh_token
 
-        pager = gql.paginate
-        # execute() returns a lazy enumerator so we're not loading everything now.
-        pages = pager.execute(query, variables).map do |page|
-          raise_if_not_found(page, variables) if options[:raise_if_not_found]
-          raise_if_user_errors(page) if options[:raise_if_user_errors]
+        begin
+          pager = gql.paginate
+          # execute() returns a lazy enumerator so we're not loading everything now.
+          pages = pager.execute(query, variables).map do |page|
+            raise_if_not_found(page, variables) if options[:raise_if_not_found]
+            raise_if_user_errors(page) if options[:raise_if_user_errors]
 
-          page = snake_case_keys(page) if options[:snake_case]
-          page
-        end
+            page = snake_case_keys(page) if options[:snake_case]
+            page
+          end
 
-        return pages unless block_given?
+          return pages unless block_given?
 
-        pages.each { |page| yield page }
+          pages.each { |page| yield page }
+        rescue ShopifyAPI::GraphQL::Tiny::HTTPError => error
+          raise unless refreshable? && error.code == "401"
+
+          refresh_after_401
+          retry
+        end
 
         nil
       end
@@ -189,6 +248,94 @@ module ShopifyAPI
         transform_keys(object) { |key| Strings::Case.snakecase(key).to_sym }
       end
 
+      private
+
+      def ensure_fresh_token
+        return unless refreshable?
+        return unless token_expired?(@token_state)
+
+        synchronize(method(:refresh_tokens))
+      end
+
+      def refreshable?
+        @oauth && @synchronize
+      end
+
+      def token_expired?(state)
+        expires_at = state[:expires_at]
+        expires_at && to_time(expires_at) <= Time.now
+      end
+
+      def to_time(value)
+        return value.to_time if value.respond_to?(:to_time)
+
+        validate_timestamp(:expires_at, value)
+        Time.at(value)
+      end
+
+      # Ensures timestamp values are absolute points in time (Time instances or Unix epoch timestamps)
+      # rather than relative offsets (e.g., passing `expires_in: 3600`), which would otherwise evaluate
+      # to 1970 and cause continuous refresh loops.
+      def validate_timestamp(name, value)
+        return if value.respond_to?(:to_time)
+
+        if value.is_a?(Numeric)
+          return if value >= MIN_EPOCH_TIMESTAMP
+
+          raise ArgumentError, ":#{name} must be a Time or modern Unix epoch timestamp in seconds, not a relative offset (got #{value})"
+        end
+
+        raise ArgumentError, ":#{name} must be a Time or Integer Unix epoch timestamp (got #{value.inspect})"
+      end
+
+      def refresh_tokens(state = @token_state)
+        state ||= @token_state
+        if token_expired?(state)
+          @token_state = normalize_tokens(@oauth.refresh(state[:refresh_token]))
+        else
+          @token_state = state
+        end
+      end
+
+      def refresh_stale_tokens(state = @token_state)
+        state ||= @token_state
+        if state.equal?(@token_state) || state[:access_token] == @token_state[:access_token]
+          @token_state = normalize_tokens(@oauth.refresh(state[:refresh_token]))
+        else
+          @token_state = state
+        end
+      end
+
+      def refresh_after_401
+        synchronize(method(:refresh_stale_tokens))
+      end
+
+      def synchronize(refresh)
+        invoked = false
+        callable = ->(*args, &block) do
+          invoked = true
+          refresh.call(*args, &block)
+        end
+
+        result = @synchronize.call(callable, @shop)
+        raise RefreshNotCalledError, ":synchronize did not call refresh" unless invoked
+
+        @token_state = result if result.is_a?(Hash) && result.key?(:access_token)
+        @gql = ShopifyAPI::GraphQL::Tiny.new(@shop, @token_state[:access_token], @options)
+        @token_state
+      end
+
+      def normalize_tokens(tokens)
+        now = Time.now.to_i
+
+        {
+          :access_token => tokens["access_token"],
+          :expires_at => now + tokens["expires_in"],
+          :refresh_token => tokens["refresh_token"],
+          :refresh_expires_at => tokens["refresh_token_expires_in"] ? now + tokens["refresh_token_expires_in"] : nil
+        }
+      end
+
       def transform_keys(object, &transformer)
         case object
         when Hash
@@ -204,3 +351,6 @@ module ShopifyAPI
     end
   end
 end
+
+require "shopify_api/graphql/request/oauth/access_token"
+require "shopify_api/graphql/request/railtie" if defined?(Rails::Railtie)

data/lib/tasks/shopify.rake

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "shopify_api/graphql/request"
+require "shopify_api/graphql/request/oauth/access_token_migrator"
+
+namespace :shopify_api do
+  namespace :graphql do
+    namespace :request do
+      desc "Migrate legacy non-expiring Shopify offline access tokens to expiring offline access tokens"
+      task :migrate_access_tokens do
+        client_id = ENV["SHOPIFY_API_KEY"].to_s.strip
+        client_secret = ENV["SHOPIFY_API_SECRET"].to_s.strip
+
+        abort "SHOPIFY_API_KEY required" if client_id.empty?
+        abort "SHOPIFY_API_SECRET required" if client_secret.empty?
+
+        begin
+          ShopifyAPI::GraphQL::Request::OAuth::AccessTokenMigrator.new(
+            client_id,
+            client_secret,
+            :shop => ENV["SHOP"],
+            :token => ENV["TOKEN"],
+            :file => ENV["FILE"],
+            :handler => ENV["HANDLER"]
+          ).run
+        rescue ArgumentError => e
+          abort e.message
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api-graphql-request
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Skye Shaw
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-24 00:00:00.000000000 Z
+date: 2026-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shopify_api-graphql-tiny
@@ -35,14 +36,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: strings-case
   requirement: !ruby/object:Gem::Requirement
@@ -57,6 +64,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -99,6 +120,35 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description:
 email:
 - skye.shaw@gmail.com
 executables: []
@@ -107,11 +157,18 @@ extra_rdoc_files: []
 files:
 - ".env.template"
 - ".rspec"
+- Changes
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/shopify_api/graphql/request.rb
+- lib/shopify_api/graphql/request/oauth/access_token.rb
+- lib/shopify_api/graphql/request/oauth/access_token_migrator.rb
+- lib/shopify_api/graphql/request/railtie.rb
+- lib/shopify_api/graphql/request/tasks.rb
 - lib/shopify_api/graphql/request/version.rb
+- lib/tasks/shopify.rake
+homepage:
 licenses:
 - MIT
 metadata:
@@ -119,6 +176,7 @@ metadata:
   changelog_uri: https://github.com/ScreenStaring/shopify_api-graphql-request/blob/master/Changes
   documentation_uri: https://rubydoc.info/gems/shopify_api-graphql-request
   source_code_uri: https://github.com/ScreenStaring/shopify_api-graphql-request
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -133,9 +191,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.5.16
+signing_key:
 specification_version: 4
 summary: Small class to simplify the writing and handling of GraphQL queries and mutations
-  for the Shopify Admin API. Comes with built-in retry, pagination, error handling,
-  and more!
+  for the Shopify Admin API. Comes with built-in retry, token refresh, pagination,
+  error handling, and more!
 test_files: []