shopify_api-graphql-tiny 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c827a0b468aeb34cfb05760a7a1a25e641c61f21f6d2d15c4ed8a05b29bd383b
-  data.tar.gz: 23b357593431fb8beda6a29689b6b90e4101fde3cac2eaaad38c7a2cb48f1437
+  metadata.gz: 18495ff517670050b05536c1ef5fda702e689a4ffab229eba78fd2aba055dce5
+  data.tar.gz: c374cf2ae48b8ed7de70b5ec8501841593535ad21ef2d5591deb17c7dc96fdef
 SHA512:
-  metadata.gz: 7fe6d5f27b0936703ce4f7f45875406ab11069d41f8e83e9d57a873ce5dd63d1093e88219cd8b5b69eed2bdd3b39bb233292360aa8bb4534f5a799690cceab5f
-  data.tar.gz: d7231b2be188d9bedbfa92f6de69a0ee4c082b8801633db73c570c7cef6c6a349afc81e942e2f36b685edf26a02d9e74817595d7b4988298f42092182a49a718
+  metadata.gz: 3388c846e2190e5996f780bf847d28f66c9336e0a96d53a8b6eed051fe8e38ffb18f3b32cc0abb15dfb15373d9f254eb6c8afbd2fbc050b3c19aea9c690db4de
+  data.tar.gz: e29a9dd41cd963bd96e8025ee31c5c4ec5b6b2726164655707c214fa73062f4e30e72545ea2df0c1b2ce54c90816c564776f509e4b9e3a51ef672290d35d2aec

data/Changes

@@ -1,3 +1,11 @@
+2026-06-23  v1.0.2
+--------------------
+* Add :raise_on_warnings option to raise a WarningError when a response contains warnings
+
+2026-01-24  v1.0.1
+--------------------
+* Add support for calling #paginate without a block
+
 2026-01-20  v1.0.0
 --------------------
 * Add support for exponential backoff and remove ShopifyAPIRetry

data/README.md

@@ -97,7 +97,7 @@ These can be overridden globally (by assigning to the constant) or per instance:
 gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, :max_attempts => 20, :max_delay => 90)
 ```
 
-`ShopifyAPI::GraphQL::Tiny::DEFAULT_RETRY_ERRORS` determines what is retried. It contains and HTTP statuses codes, Shopify GraphQL errors codes, and exceptions.
+`ShopifyAPI::GraphQL::Tiny::DEFAULT_RETRY_ERRORS` determines what is retried. It contains HTTP status codes, Shopify GraphQL errors codes, and exception classes.
 By default it contains:
 
 * `"5XX"` - Any HTTP 5XX status
@@ -160,6 +160,13 @@ pager.execute(query, :foo => 123) do |page|
 end
 ```
 
+If a block is not given an `Enumerator::Lazy` instance is returned that will fetch the next page upon each iteration:
+
+```rb
+results = pager.execute(query, :foo => 123)
+results.each { |page| ... }
+```
+
 #### `after` Pagination
 
 To use `after` pagination, i.e., to paginate forward, your query must:
@@ -259,6 +266,37 @@ pager.execute(query) { |page| }
 
 The `"data"` and `"pageInfo"` keys are automatically added if not provided.
 
+### Raising on Warnings
+
+A successful GraphQL response can still contain warnings (for example an invalid search field reported under
+`extensions.search`). By default these are ignored. Set `:raise_on_warnings` to `true` to raise a `WarningError`
+(a subclass of `GraphQLError`) whenever the response contains warnings:
+
+```rb
+gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, :raise_on_warnings => true)
+
+begin
+  gql.execute(query)
+rescue ShopifyAPI::GraphQL::Tiny::WarningError => e
+  warn e.message    # The warnings, formatted
+  e.response        # The full GraphQL response Hash
+end
+```
+
+## Why Use This Instead of Shopify's API Client?
+
+- Easy-to-use
+- Built-in retry
+- Built-in pagination
+- 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.
@@ -271,6 +309,7 @@ bundle exec rake rate_limit SHOPIFY_DOMAIN=your-domain SHOPIFY_TOKEN=your-token
 
 ## See Also
 
+- [`ShopifyAPI::GraphQL::Request`](https://github.com/ScreenStaring/shopify_api-graphql-request) - A higher-level wrapper around this class with improved exception handling and `:snake_case` hash key conversion
 - [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
 - [`TinyGID`](https://github.com/sshaw/tiny_gid/) - Build Global ID (gid://) URI strings from scalar values

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

@@ -3,7 +3,7 @@
 module ShopifyAPI
   module GraphQL
     class Tiny
-      VERSION = "1.0.0"
+      VERSION = "1.0.2"
     end
   end
 end

data/lib/shopify_api/graphql/tiny.rb

@@ -29,6 +29,7 @@ module ShopifyAPI
       end
 
       RateLimitError = Class.new(GraphQLError)
+      WarningError = Class.new(GraphQLError)
 
       class HTTPError < Error
         attr_reader :code
@@ -84,6 +85,7 @@ module ShopifyAPI
       # [:jitter (Boolean)] Exponential backoff jitter (random delay added to backoff). Defaults to +true+
       # [:multiplier (Float)] Exponential backoff multiplier. Defaults to +2.0+
       # [:debug (Boolean|IO)] Output the HTTP request/response to +STDERR+ or to its value if it's an +IO+. Defaults to +false+.
+      # [:raise_on_warnings (Boolean)] If +true+ raise a WarningError when the GraphQL response contains warnings. Defaults to +false+.
       #
       # === Errors
       #
@@ -96,6 +98,7 @@ module ShopifyAPI
 
         @domain = shopify_domain(shop)
         @options = options || {}
+        @raise_on_warnings = @options[:raise_on_warnings]
 
         @headers = DEFAULT_HEADERS.dup
         @headers[ACCESS_TOKEN_HEADER] = token
@@ -137,6 +140,8 @@ module ShopifyAPI
       #   rate-limited after the configured number of retry attempts
       # * A ShopifyAPI::GraphQL::Tiny::GraphQLError is raised if the response contains an +errors+ property that is
       #   not a rate-limit error
+      # * A ShopifyAPI::GraphQL::Tiny::WarningError is raised if the +:raise_on_warnings+ option is +true+ and the
+      #   response contains warnings
       #
       # === Returns
       #
@@ -158,7 +163,8 @@ module ShopifyAPI
       #    page.dig("data", "product", "title")
       #  end
       #
-      # The block is called for each page.
+      # The block is called for each page. If a block is not provided returns an instance of Enumerator::Lazy that will fetch the next
+      # page on each iteration.
       #
       # Using pagination requires you to include the
       # {PageInfo}[https://shopify.dev/api/admin-graphql/2022-10/objects/PageInfo]
@@ -188,9 +194,13 @@ module ShopifyAPI
       #                      Defaults to <code>"before"</code> or <code>"after"</code>, depending on the pagination
       #                      direction.
       #
+      # === Returns
+      #
+      # +nil+ or `Enumerator::Lazy` if no block was provided
+      #
       # === Errors
       #
-      # ArgumentError
+      # See #execute
 
       def paginate(*options)
         Pager.new(self, options)
@@ -216,12 +226,20 @@ module ShopifyAPI
         end
 
         json = parse_json(response.body)
-        return json unless json.include?("errors")
 
-        return make_request(query, variables) if handle_graphql_error(json)
+        if json.include?("errors")
+          return make_request(query, variables) if handle_graphql_error(json)
+
+          message = error_message(json["errors"])
+          raise GraphQLError.new("failed to execute query for #@domain: #{message}", json)
+        end
+
+        if @raise_on_warnings
+          warnings = find_warnings(json)
+          raise WarningError.new("query for #@domain returned warnings: #{warning_message(warnings)}", json) unless warnings.empty?
+        end
 
-        message = error_message(json["errors"])
-        raise GraphQLError.new("failed to execute query for #@domain: #{message}", json)
+        json
       end
 
       def post(query, variables = nil)
@@ -318,6 +336,34 @@ module ShopifyAPI
         end.join(", ")
       end
 
+      def find_warnings(data, prop = nil)
+        case data
+        when Hash
+          data.flat_map do |key, value|
+            if key == "warnings" && value.is_a?(Array)
+              value.map { |w| [prop, w] }
+            else
+              find_warnings(value, key)
+            end
+          end
+        when Array
+          data.flat_map { |value| find_warnings(value, prop) }
+        else
+          []
+        end
+      end
+
+      def warning_message(warnings)
+        warnings.map do |prop, warning|
+          next warning.to_s unless warning.is_a?(Hash)
+
+          field = Array(warning["field"]).join(".")
+          parts = [prop]
+          parts << field unless field.empty?
+          "#{parts.join(" ")}: #{warning["message"]}"
+        end.join("\n")
+      end
+
       def request_attempts_remain?
         @request_attempts < @backoff_options[:max_attempts]
       end
@@ -348,19 +394,22 @@ module ShopifyAPI
         variables ||= {}
         pagination_finder = @options[@options[:direction]]
 
-        loop do
-          page = @gql.execute(q, variables)
-
-          yield page
+        enumerator = Enumerator.new do |y|
+          loop do
+            page = @gql.execute(q, variables)
+            y << page
 
-          cursor = pagination_finder[page]
-          break unless cursor
+            cursor = pagination_finder[page]
+            break unless cursor
 
-          next_page_variables = variables.dup
-          next_page_variables[@options[:variable]] = cursor
-          #break unless next_page_variables != variables
+            variables[@options[:variable]] = cursor
+          end
+        end
 
-          variables = next_page_variables
+        if block_given?
+          enumerator.each { |page| yield page }
+        else
+          enumerator.lazy
         end
       end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api-graphql-tiny
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Skye Shaw
 bindir: exe
 cert_chain: []
-date: 2026-01-20 00:00:00.000000000 Z
+date: 2026-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net_http_timeout_errors