shopify_api-graphql-request 0.0.1

checksums.yaml

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

data/.env.template

@@ -0,0 +1,16 @@
+# To run tests:
+#
+#   1. Copy this file to .env
+#   2. Fill-in the below variables with valid values.
+#      These values will be used by the tests. Data will be written to SHOPIFY_DOMAIN
+#
+
+# Must be full domain as it's used in test assertions
+SHOPIFY_DOMAIN=
+SHOPIFY_TOKEN=
+
+# Will result in the creation of a metadafield on the customer. write_customers permission required
+SHOPIFY_CUSTOMER_ID=
+
+# Must have more than 1 variant values
+SHOPIFY_PRODUCT_ID=

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ScreenStaring
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# ShopifyAPI::GraphQL::Request
+
+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!
+
+## Usage
+
+It's recommended to organize queries and mutations by subclassing `ShopifyAPI::GraphQL::Request`:
+
+```rb
+require "shopify_api/graphql/request"
+
+class ShopifyProduct < ShopifyAPI::GraphQL::Request
+  # Define your queries/mutations
+  FIND =<<-GQL
+    query($id: ID!) {
+      product(id: $id) {
+        id
+        title
+        descriptionHtml
+      }
+    }
+  GQL
+
+  UPDATE =<<-GQL
+    mutation($product: ProductUpdateInput!) {
+      productUpdate(product: $product) {
+        product {
+          id
+          title
+          descriptionHtml
+        }
+        userErrors {
+          field
+          message
+        }
+      }
+    }
+  GQL
+
+  LIST <<-GQL
+    query($after: String) {
+      products(first: 25 after: $after) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        edges {
+          node {
+            id
+            title
+            descriptionHtml
+          }
+        }
+      }
+    }
+  GQL
+
+  def find(id)
+    execute(FIND, :id => gid::Product(id)).dig(:data, :product)
+  end
+
+  def update(id, changes)
+    execute(UPDATE, :product => changes.merge(:id => gid::Product(id))).dig(:data, :product_update, :product)
+  end
+
+  def list
+    paginate(LIST) { |page| yield page.dig(:data, :products, :edges) }
+  end
+end
+```
+
+Then use it:
+
+```rb
+shopify = ShopifyProduct.new("a-shop", token)
+
+begin
+  product = shopify.find(123)
+  p product[:id]
+  p product[:description_html]
+rescue ShopifyAPI::GraphQL::Request::NotFoundError => e
+  warn "Product not found: #{e}"
+end
+
+begin
+  product = shopify.update(123, :description_html => "Something amaaaazing!")
+  p product[:id]
+  p product[:description_html]
+rescue ShopifyAPI::GraphQL::Request::UserError => e
+  warn "User errors:"
+  e.errors { |err| warn err["field"] }
+end
+
+begin
+  shopify.list(123) do |node|
+    product = node[:node]
+    p product[:id]
+    p product[:description_html]
+  end
+rescue ShopifyAPI::GraphQL::Request::NotFoundError => e
+  warn "Request failed: #{e}"
+end
+```
+
+Subclasses have access to the following methods:
+
+- `#execute` - Execute a query or mutation with the provided arguments
+- `#paginate` - Execute a query with pagination; without a block a lazy enumerator (`Enumerator::Lazy`) is returned
+- `#gid` - Used for Global ID manipulation (an instance of [`TinyGID`](https://github.com/sshaw/tiny_gid/))
+- `#gql` - The underlying GraphQL client (an instance of [`ShopifyAPI::GraphQL::Tiny`](https://github.com/ScreenStaring/shopify_api-graphql-tiny/))
+
+`#execute` and `#paginate` also:
+
+- Automatically retry failed or rate-limited requests
+- Accept `snake_case` `Symbol` keys
+- Return a `Hash` with `snake_case` `Symbol` keys
+- Raise a `UserError` when a mutation's response contains `userErrors`
+- Raise a `NotFoundError` when a query's result cannot be found
+
+Both of these are small wrappers around the equivalent methods on `ShopifyAPI::GraphQL::Tiny`.
+For more information see [its documentation on retries](https://github.com/ScreenStaring/shopify_api-graphql-tiny#automatically-retrying-failed-requests).
+
+With the exception of retry, most defaults can be disabled per instance or per execution:
+
+```rb
+class ShopifyProduct < ShopifyAPI::GraphQL::Request
+  def initialize(shop, token)
+    super(shop, token, :raise_if_not_found => false, :raise_if_user_errors => false, :snake_case => false)
+  end
+
+  def find(gid)
+    execute(QUERY, :raise_if_not_found => true)
+  end
+end
+```
+
+Disabling retry must be done per instance.
+
+### Setting the GraphQL API Version
+
+Pass the desired version to `Request`'s constructor:
+
+```rb
+class ShopifyProduct < ShopifyAPI::GraphQL::Request
+  def initialize(shop, token)
+    super(shop, token, :version => "2026-01")
+  end
+end
+```
+
+### Making Requests Without Subclassing
+
+Of course you can make requests directly on an instance of `ShopifyAPI::GraphQL::Request`:
+
+```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
+```
+
+### More Info
+
+For more information checkout [the API docs](https://rdoc.info/gems/shopify_api-graphql-request)
+
+## Testing
+
+`cp env.template .env` and fill-in `.env` with the missing values. This requires a Shopify store.
+
+## 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
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+Made by [ScreenStaring](http://screenstaring.com)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ShopifyAPI
+  module GraphQL
+    class Request
+      VERSION = "0.0.1"
+    end
+  end
+end

data/lib/shopify_api/graphql/request.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "strings/case"
+require "tiny_gid"
+
+require "shopify_api/graphql/tiny"
+
+module ShopifyAPI
+  module GraphQL
+    #
+    # 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!
+    #
+    class Request
+      Error = Class.new(StandardError)
+
+      class UserError < Error
+        attr_reader :errors
+
+        def initialize(errors)
+          super error_message(errors)
+          @errors = errors
+        end
+
+        private
+
+        def error_message(errors)
+          errors.map do |error|
+            if error["field"]
+              sprintf("%s: %s", error["field"].join("."), error["message"])
+            else
+              error["message"]
+            end
+          end.join("\n")
+        end
+      end
+
+      class NotFoundError < Error
+        def initialize(queries, variables)
+          if queries.size > 1
+            super "No records found for queries #{queries.join(", ")} with #{variables}"
+          else
+            super "No record found for #{queries[0]} with #{variables}"
+          end
+        end
+      end
+
+      ##
+      #
+      # Create a new GraphQL client to connect to +shop+
+      #
+      # === Arguments
+      #
+      # [shop (String)] Shopify domain to make requests against
+      # [token (String)] Shopify API token
+      # [options (Hash)] Client options. Optional.
+      #
+      # === Options
+      #
+      # [: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+.
+      #
+      # Additional options: those accepted by {ShopifyAPI::GraphQL::Tiny}[https://rdoc.info/gems/shopify_api-graphql-tiny]
+      #
+      def initialize(shop, token, options = nil)
+        @options = (options || {}).dup
+
+        [:snake_case, :raise_if_not_found, :raise_if_user_errors].each do |name|
+          @options[name] = true unless @options.include?(name)
+        end
+
+        @gql = ShopifyAPI::GraphQL::Tiny.new(shop, token, @options)
+
+        @gid = TinyGID.new("shopify")
+      end
+
+      ##
+      #
+      # Executes a query or mutation
+      #
+      # === Arguments
+      #
+      # [query (String)] Query or mutation to execute
+      # [token (String)] Optional variables accepted by +query+
+      # [options (Hash)] Optional
+      #
+      # === Options
+      #
+      #  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)]
+      #
+      # === Returns
+      #
+      # The GraphQL response +Hash+
+      #
+      # === Errors
+      #
+      # * ArgumentError
+      # * 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
+      # * ShopifyAPI::GraphQL::Tiny::HTTPError
+      # * ShopifyAPI::GraphQL::Tiny::RateLimitError - if the retry attempts have been exceeded
+      # * ShopifyAPI::GraphQL::Tiny::GraphQLError
+      #
+      def execute(query, variables = nil, options = nil)
+        options = @options.merge(options || {})
+
+        variables = camelize_keys(variables) if options[:snake_case]
+
+        data = gql.execute(query, variables)
+
+        raise_if_not_found(data, variables) if options[:raise_if_not_found]
+        raise_if_user_errors(data) if options[:raise_if_user_errors]
+
+        data = snake_case_keys(data) if options[:snake_case]
+
+        data
+      end
+
+      ##
+      #
+      # Executes a query using pagination.
+      #
+      # Using pagination requires you to include the
+      # {PageInfo}[https://shopify.dev/api/admin-graphql/2026-01/objects/PageInfo] in your query.
+      #
+      # === Arguments
+      #
+      # Same as #execute but also accepts a block that will be called with each page.
+      # If a block not given returns an instance of Enumerator::Lazy that will fetch the next
+      # page on each iteration
+      #
+      # === Errors
+      #
+      #  See #execute
+      #
+      def paginate(query, variables = nil, options = nil)
+        options = @options.merge(options || {})
+
+        variables = camelize_keys(variables) if options[:snake_case]
+
+        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
+
+        return pages unless block_given?
+
+        pages.each { |page| yield page }
+
+        nil
+      end
+
+      protected
+
+      attr_reader :gql, :gid
+
+      def raise_if_not_found(data, variables)
+        not_found = data["data"].select { |key, value| value.nil? }
+        return unless not_found.any?
+
+        raise NotFoundError.new(not_found.keys, variables)
+      end
+
+      def raise_if_user_errors(data)
+        # FIXME: this does not account for multiple queries
+        # Structure is { "data" => QUERY => { "userErrors" => [] } }
+        data = data["data"].values[0]
+        return unless data && data["userErrors"] && data["userErrors"].any?
+
+        raise UserError, data["userErrors"]
+      end
+
+      def camelize_keys(object)
+        transform_keys(object) { |key| Strings::Case.camelcase(key.to_s) }
+      end
+
+      def snake_case_keys(object)
+        transform_keys(object) { |key| Strings::Case.snakecase(key).to_sym }
+      end
+
+      def transform_keys(object, &transformer)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            result[transformer[key]] = transform_keys(value, &transformer)
+          end
+        when Array
+          object.map { |value| transform_keys(value, &transformer) }
+        else
+          object
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: shopify_api-graphql-request
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Skye Shaw
+bindir: exe
+cert_chain: []
+date: 2026-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: shopify_api-graphql-tiny
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: tiny_gid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: strings-case
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+email:
+- skye.shaw@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.template"
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/shopify_api/graphql/request.rb
+- lib/shopify_api/graphql/request/version.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/ScreenStaring/shopify_api-graphql-request/issues
+  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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+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!
+test_files: []