shopify_api-graphql-tiny 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e48648295daa6495ff73f0415253f062439c876620351d00b90da3ec98ba700
-  data.tar.gz: 6789cbc730bc6f98f8ac89d63f1a9b57b043a990c685250f3992e8e4756f8a26
+  metadata.gz: 18495ff517670050b05536c1ef5fda702e689a4ffab229eba78fd2aba055dce5
+  data.tar.gz: c374cf2ae48b8ed7de70b5ec8501841593535ad21ef2d5591deb17c7dc96fdef
 SHA512:
-  metadata.gz: e22a8f947de401a3e8ca218486d5ac9e6c396b091d848d189b3564790b4f1b2dcca3e3b32f651698cee5030908ec1aa3926df31c013153b407cb0b466a8624ba
-  data.tar.gz: 313dc8dcb7058042be6b39240f5177123bd4498d8ddae770801324875e187b5b625246f49b34e1b62ca2b87c0d94d51156a5ecf43b8829e0fcc7ab5378d5c735
+  metadata.gz: 3388c846e2190e5996f780bf847d28f66c9336e0a96d53a8b6eed051fe8e38ffb18f3b32cc0abb15dfb15373d9f254eb6c8afbd2fbc050b3c19aea9c690db4de
+  data.tar.gz: e29a9dd41cd963bd96e8025ee31c5c4ec5b6b2726164655707c214fa73062f4e30e72545ea2df0c1b2ce54c90816c564776f509e4b9e3a51ef672290d35d2aec

data/Changes

@@ -1,3 +1,7 @@
+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

data/README.md

@@ -266,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.
@@ -278,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.1"
+      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

metadata

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