shopify_api-graphql-request 0.0.2 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 392d3a9629abbbe7f7c768b5d2af6597f90dfc5728c4c55d2908d41730b66497
-  data.tar.gz: 790ba7b6a275ef632d0a43b86e4b141065ebd2a6bde41bc5b90bff7961018b96
+  metadata.gz: 8693e4abd154bf4592d8582f4f00c542a22440a47554529cabca27a2acca9102
+  data.tar.gz: 2baa318c0578781d9419bb7916d26eeb59a09783d4ccaddfe577d485a9a6a3da
 SHA512:
-  metadata.gz: 65b742996ac8a08a6e878424c0f293ccc3d899cd55a7a562de76eccb559d63163738faf0a3dfe1cc6f87e7cb9104cd04473c549b5f802e86f2b336973d7001d0
-  data.tar.gz: d8644370482c62f2aa95d22eaf7e59e406d7e32754b6ce48d70a0f0ad5cc0753d38ca13c7770f0dfaddbfd9ef4edb6cd1a0f78dd48d14aaa20f108f1b915b84f
+  metadata.gz: 2ea1da8888f62de6903138ae9f116578f155e044a6375ee2646f8ae416c2b4ba53c903e7adc9922fa85d02d8d5f6cb48a9244251d78d9650d3f6a85019127177
+  data.tar.gz: dec264b7bcdf723b6e0da2ed3c5d7554f645797e5f4ace298effb046b2aca1da7077b977e2b06d46c82ce840af158c605e470787ee6d1b10a98b916929fc7b05

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

@@ -1,3 +1,13 @@
+v0.1.1  2026-11-11
+--------------------
+Improve robustness of token migration task when using a spreadsheet
+
+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.

data/README.md

@@ -1,7 +1,9 @@
 # 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
 
@@ -174,6 +176,141 @@ class ShopifyProduct < ShopifyAPI::GraphQL::Request
 end
 ```
 
+### Auto-Refreshing Expiring Access Tokens
+
+`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
+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
+})
+```
+
+#### The `:synchronize` Callback
+
+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
+```
+
+### 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
+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
+```
+
+A summary of succeeded and failed shops (with the error for each failure) is printed when done. A failure for one shop does not stop the others; the task exits with status 1 if any shop failed.
+
+#### 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)

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,130 @@
+# 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 status per shop, in input order:
+          #               +{ :shop => String, :result => Hash, :error => nil }+ or
+          #               +{ :shop => String, :result => nil, :error => String }+.
+          #               Per-shop errors (+StandardError+, including those raised by the handler) are
+          #               rescued so one failure does not stop the rest.
+          #
+          # === Errors
+          #
+          # ArgumentError for invalid input (before any shop is processed)
+          #
+          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, :error => nil }
+          rescue StandardError => e
+            { :shop => shop, :result => nil, :error => "#{e.class}: #{e.message}" }
+          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.2"
+      VERSION = "0.1.1"
     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
 
       ##
@@ -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]
@@ -143,20 +194,28 @@ module ShopifyAPI
         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
@@ -191,6 +250,92 @@ module ShopifyAPI
 
       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
@@ -206,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,42 @@
+# 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
+          statuses = 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
+
+        failed, succeeded = statuses.partition { |status| status[:error] }
+
+        puts "Succeeded (#{succeeded.size}):"
+        succeeded.each { |status| puts "  #{status[:shop]}" }
+
+        puts "Failed (#{failed.size}):"
+        failed.each { |status| puts "  #{status[:shop]}: #{status[:error]}" }
+
+        exit 1 unless failed.empty?
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api-graphql-request
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.1
 platform: ruby
 authors:
 - Skye Shaw
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-19 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shopify_api-graphql-tiny
@@ -64,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
@@ -106,6 +120,34 @@ 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
@@ -120,7 +162,12 @@ files:
 - 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
@@ -148,6 +195,6 @@ 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: []