shopify_api-graphql-tiny 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e48648295daa6495ff73f0415253f062439c876620351d00b90da3ec98ba700
-  data.tar.gz: 6789cbc730bc6f98f8ac89d63f1a9b57b043a990c685250f3992e8e4756f8a26
+  metadata.gz: 28d098f2ad608cf375916eb9efdf9c3278b514fc632058a835c1566989a4538b
+  data.tar.gz: 0a1b2d891a11116279b0169d2d093589148538f3c8abecaa35a5bd0d3bb2363a
 SHA512:
-  metadata.gz: e22a8f947de401a3e8ca218486d5ac9e6c396b091d848d189b3564790b4f1b2dcca3e3b32f651698cee5030908ec1aa3926df31c013153b407cb0b466a8624ba
-  data.tar.gz: 313dc8dcb7058042be6b39240f5177123bd4498d8ddae770801324875e187b5b625246f49b34e1b62ca2b87c0d94d51156a5ecf43b8829e0fcc7ab5378d5c735
+  metadata.gz: c0a66340735b1fc42126eda00b52598cbb4f1668da9e2680d99eab359e840865a6082568e53a71550f7e2edf936c7b78e1b15998391b6485d09958c7ae9cbfd2
+  data.tar.gz: b1ad6ca96b39d5c5a1e06c4d4a6b5e893a3236034b10426bbd9822f25e11bd9f03deddbc0125577abf3f126c5b2d78c4176f8913aa03f68f38362529e9ac0e2b

data/.env.template

@@ -7,7 +7,8 @@
 
 # Must be full domain as it's used in test assertions
 SHOPIFY_DOMAIN=
-SHOPIFY_TOKEN=
+SHOPIFY_ADMIN_TOKEN=
+SHOPIFY_STOREFRONT_TOKEN=
 
 # Will result in the creation of a metadafield on the customer. write_customers permission required
 SHOPIFY_CUSTOMER_ID=

data/Changes

@@ -1,3 +1,11 @@
+2026-06-25  v1.1.0
+--------------------
+* Add support for requests against the storefront API
+
+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

@@ -1,6 +1,6 @@
 # ShopifyAPI::GraphQL::Tiny
 
-Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry
+Lightweight, no-nonsense, Shopify Admin & Storefront GraphQL API client with built-in pagination and retry
 
 [![CI](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions/workflows/ci.yml/badge.svg)](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions)
 
@@ -74,6 +74,24 @@ GQL
 p result.dig("data", "customerUpdate", "userErrors")
 ```
 
+### Storefront API
+
+By default requests are made against the Admin API.
+To make requests against the Storefront API use the `:storefront => true` option:
+
+```rb
+gql = ShopifyAPI::GraphQL::Tiny.new("my-shop", token, :storefront => true)
+result = gql.execute(<<-GQL, :id => your_gid)
+  query($id: ID!) {
+    product(id: $id) {
+      selectedOrFirstAvailableVariant {
+        id
+      }
+    }
+  }
+GQL
+```
+
 ### Automatically Retrying Failed Requests
 
 There are 2 types of retries: 1) request is rate-limited by Shopify 2) request fails due to an exception or non-200 HTTP response.
@@ -266,6 +284,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,8 +327,8 @@ 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
 
 ## License
@@ -288,4 +337,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/tiny/version.rb

@@ -3,7 +3,7 @@
 module ShopifyAPI
   module GraphQL
     class Tiny
-      VERSION = "1.0.1"
+      VERSION = "1.1.0"
     end
   end
 end

data/lib/shopify_api/graphql/tiny.rb

@@ -8,7 +8,7 @@ require "shopify_api/graphql/tiny/version"
 module ShopifyAPI
   module GraphQL
     ##
-    # Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry
+    # Lightweight, no-nonsense, Shopify GraphQL Admin/Storefront API client with built-in pagination and retry
     #
     class Tiny
       Error = Class.new(StandardError)
@@ -29,6 +29,7 @@ module ShopifyAPI
       end
 
       RateLimitError = Class.new(GraphQLError)
+      WarningError = Class.new(GraphQLError)
 
       class HTTPError < Error
         attr_reader :code
@@ -44,6 +45,8 @@ module ShopifyAPI
       SHOPIFY_DOMAIN = ".myshopify.com"
 
       ACCESS_TOKEN_HEADER = "X-Shopify-Access-Token"
+      STOREFRONT_ACCESS_TOKEN_HEADER = "X-Shopify-Storefront-Access-Token"
+      STOREFRONT_BUYER_IP_HEADER = "X-Shopify-Storefront-Buyer-IP"
       QUERY_COST_HEADER = "X-GraphQL-Cost-Include-Fields"
 
       DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
@@ -63,7 +66,7 @@ module ShopifyAPI
         *NetHttpTimeoutErrors.all
       ]
 
-      ENDPOINT = "https://%s/admin/api%s/graphql.json"       # Note that we omit the "/" after API for the case where there's no version.
+      ENDPOINT = "https://%s%s/api%s/graphql.json"       # We omit the "/" after API for the case where there's no version
 
       ##
       #
@@ -72,18 +75,21 @@ module ShopifyAPI
       # === Arguments
       #
       # [shop (String)] Shopify domain to make requests against
-      # [token (String)] Shopify Admin API GraphQL token
+      # [token (String)] Shopify Admin API or Storefront Access Token, depending on options
       # [options (Hash)] Client options. Optional.
       #
       # === Options
       #
       # [:retry (Boolean|Array)] If +false+ disable retries or an +Array+ of errors to retry. Can be HTTP status codes, GraphQL errors, or exception classes.
       # [:version (String)] Shopify API version to use. Defaults to the latest version.
+      # [:storefront (Boolean)] If +true+ use the Storefront API instead of Admin API. Defaults to +false+.
+      # [:ip (String)] Optional buyer IP address for Storefront API (sets X-Shopify-Storefront-Buyer-IP header). Only used when :storefront is +true+.
       # [:max_attempts (Integer)] Maximum number of retry attempts across all errors. Defaults to +10+
       # [:base_delay (Float)] Exponential backoff base delay. Defaults to +0.5+
       # [: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
       #
@@ -97,11 +103,22 @@ module ShopifyAPI
         @domain = shopify_domain(shop)
         @options = options || {}
 
+        @raise_on_warnings = @options[:raise_on_warnings]
+        @storefront = !!@options[:storefront]
+
         @headers = DEFAULT_HEADERS.dup
-        @headers[ACCESS_TOKEN_HEADER] = token
+
+        if @storefront
+          @headers[STOREFRONT_ACCESS_TOKEN_HEADER] = token
+          @headers[STOREFRONT_BUYER_IP_HEADER] = @options[:ip] if @options[:ip]
+        else
+          @headers[ACCESS_TOKEN_HEADER] = token
+        end
+
         @headers[QUERY_COST_HEADER] = "true" unless @options[:retry] == false
 
-        @endpoint = URI(sprintf(ENDPOINT, @domain, !@options[:version].to_s.strip.empty? ? "/#{@options[:version]}" : ""))
+        admin_path = @storefront ? "" : "/admin"
+        @endpoint = URI(sprintf(ENDPOINT, @domain, admin_path, !@options[:version].to_s.strip.empty? ? "/#{@options[:version]}" : ""))
         @backoff_options = DEFAULT_BACKOFF_OPTIONS.merge(@options.slice(*DEFAULT_BACKOFF_OPTIONS.keys))
 
         if @options[:debug]
@@ -137,6 +154,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 +177,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 +208,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 +240,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 +350,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

data/shopify_api-graphql-tiny.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Skye Shaw"]
   spec.email         = ["skye.shaw@gmail.com"]
 
-  spec.summary       = %q{Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry}
+  spec.summary       = %q{Lightweight, no-nonsense, Shopify Admin & Storefront GraphQL API client with built-in pagination and retry}
   spec.homepage      = "https://github.com/ScreenStaring/shopify_api-graphql-tiny"
   spec.license       = "MIT"
 

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.1.0
 platform: ruby
 authors:
 - Skye Shaw
 bindir: exe
 cert_chain: []
-date: 2026-01-24 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net_http_timeout_errors
@@ -123,6 +123,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in
-  pagination and retry
+summary: Lightweight, no-nonsense, Shopify Admin & Storefront GraphQL API client with
+  built-in pagination and retry
 test_files: []