shopify_api-graphql-tiny 0.0.2 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b83386464ba310b5225b0eaa43f9f2de9c942de2c1a1bd877e65b7aef41c4469
-  data.tar.gz: d6d6bc0d2a4dc61a0c430b712eadcf52dbd5355c4ed91a3a4c2b44e40933305f
+  metadata.gz: 125818846e86b77345ee59d8e6d03c4600b2aaa56f18e33ec1ae23ecfa90938e
+  data.tar.gz: 4b4443e43ff6d37fdbbad202222b6f5b3dff11f8f0a377260898dab06d2209ec
 SHA512:
-  metadata.gz: 8b15b5bd7a5ce57beb926673041c803f822194ec1c32190a8b80099d4eda987c870084d08ab70d73f956a18b60a12130fb3b3d77846aa56d94346e254864aff6
-  data.tar.gz: 12235d40cea2cc700c6b74376521c4eec56369f7700232f3773d7ec08d5dd3254cb0e71ad5c2a1087591dcad6547d316841b28fcce0698d68bc097d40765ca62
+  metadata.gz: 5418a19e0a24b56d7e587c9a1bde22bf4d1c830639393fa30b371216dc6e8f9824cf1b31f477e6834ae17ec92c0594803a8b0593920a1b7db22655e5fc8439dd
+  data.tar.gz: b2ae36edf66dcb67395950e39231cbba3d13f0873b381a78b1cd8404f3e40fd3c7dbc157030c6665cc029ea6800611455cfb19da8fc5dfcd7fc08c3d45304631

data/.env.template

@@ -6,4 +6,9 @@
 #
 SHOPIFY_DOMAIN=
 SHOPIFY_TOKEN=
+
+# Will result in the creation of a private metadafield
 SHOPIFY_CUSTOMER_ID=
+
+# Must have more than 1 variant
+SHOPIFY_PRODUCT_ID=

data/.github/workflows/ci.yml

@@ -11,10 +11,11 @@ jobs:
       SHOPIFY_DOMAIN: "${{ secrets.SHOPIFY_DOMAIN }}"
       SHOPIFY_TOKEN: "${{ secrets.SHOPIFY_TOKEN }}"
       SHOPIFY_CUSTOMER_ID: "${{ secrets.SHOPIFY_CUSTOMER_ID }}"
+      SHOPIFY_PRODUCT_ID: "${{ secrets.SHOPIFY_PRODUCT_ID }}"
 
     strategy:
       matrix:
-        ruby: ["3.1", "3.0", "2.7.2", "2.6.6", "2.5.8", "2.4.10"]
+        ruby: ["3.2", "3.1", "3.0", "2.7.2", "2.6.6", "2.5.8", "2.4.10"]
 
     steps:
       - uses: actions/checkout@v2

data/Changes

@@ -1,3 +1,12 @@
+2023-02-12  v0.1.1
+--------------------
+* Add pagination support
+
+2022-06-16  v0.1.0
+--------------------
+* Make RateLimitError a subclass of GraphQLError
+* Set HTTP user-agent header
+
 2022-06-08  v0.0.2
 --------------------
 * Add GraphQLError#response to return the parsed GQL response body

data/README.md

@@ -1,8 +1,8 @@
 # ShopifyAPI::GraphQL::Tiny
 
-Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in retry.
+Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry.
 
-![CI](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions/workflows/ci.yml/badge.svg)
+[![CI](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions/workflows/ci.yml/badge.svg)](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions)
 
 ## Usage
 
@@ -10,6 +10,8 @@ Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in retry.
 require "shopify_api/graphql/tiny"
 
 gql = ShopifyAPI::GraphQL::Tiny.new("my-shop", token)
+
+# Automatically retried
 result = gql.execute(<<-GQL, :id => "gid://shopify/Customer/1283599123")
   query findCustomer($id: ID!) {
     customer(id: $id) {
@@ -33,6 +35,8 @@ p customer["tags"]
 p customer.dig("metafields", "edges", 0, "node")["value"]
 
 updates = { :id => customer["id"], :tags => customer["tags"] + %w[foo bar] }
+
+# Automatically retried as well
 result = gql.execute(<<-GQL, :input => updates)
   mutation customerUpdate($input: CustomerInput!) {
     customerUpdate(input: $input) {
@@ -50,7 +54,129 @@ GQL
 p result.dig("data", "customerUpdate", "userErrors")
 ```
 
-See [the docs](https://rdoc.info/gems/shopify_api-graphql-tiny) for complete documentation.
+### Pagination
+
+In addition to built-in request retry `ShopifyAPI::GraphQL::Tiny` also builds in support for pagination.
+
+Using pagination requires you to include [the Shopify `PageInfo` object](https://shopify.dev/api/admin-graphql/2022-10/objects/PageInfo)
+in your queries and wrap them in a function that accepts a page/cursor argument.
+
+The pager's `#execute` is like the non-paginated `#execute` method and accepts additional, non-pagination query arguments:
+
+```rb
+pager.execute(query, :foo => 123)
+```
+
+And it accepts a block which will be passed each page returned by the query:
+
+```rb
+pager.execute(query, :foo => 123) do |page|
+  # do something with each page
+end
+```
+
+#### `after` Pagination
+
+To use `after` pagination, i.e., to paginate forward, your query must:
+
+- Make the page/cursor argument optional
+- Include `PageInfo`'s `hasNextPage` and `endCursor` fields
+
+For example:
+
+```rb
+FIND_ORDERS = <<-GQL
+  query findOrders($after: String) {
+    orders(first: 10 after: $after) {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      edges {
+        node {
+          id
+          email
+        }
+      }
+    }
+  }
+GQL
+
+pager = gql.paginate  # This is the same as gql.paginate(:after)
+pager.execute(FIND_ORDERS) do |page|
+  orders = page.dig("data", "orders", "edges")
+  orders.each do |order|
+    # ...
+  end
+end
+```
+
+By default it is assumed your GraphQL query uses a variable named `$after`. You can specify a different name using the `:variable`
+option:
+
+```rb
+pager = gql.paginate(:after, :variable => "yourVariable")
+```
+
+#### `before` Pagination
+
+To use `before` pagination, i.e. to paginate backward, your query must:
+
+- Make the page/cursor argument **required**
+- Include the `PageInfo`'s `hasPreviousPage` and `startCursor` fields
+- Specify the `:before` argument to `#paginate`
+
+For example:
+
+```rb
+FIND_ORDERS = <<-GQL
+  query findOrders($before: String) {
+    orders(last: 10 before: $before) {
+      pageInfo {
+        hasPreviousPage
+        startCursor
+      }
+      edges {
+        node {
+          id
+          email
+        }
+      }
+    }
+  }
+GQL
+
+pager = gql.paginate(:before)
+pager.execute(FIND_ORDERS) do |page|
+  # ...
+end
+```
+
+By default it is assumed your GraphQL query uses a variable named `$before`. You can specify a different name using the `:variable`
+option:
+
+```rb
+pager = gql.paginate(:before, :variable => "yourVariable")
+```
+
+#### Response Pagination Data
+
+By default `ShopifyAPI::GraphQL::Tiny` will use the first `pageInfo` block with a next or previous page it finds
+in the GraphQL response. If necessary you can specify an explicit location for the `pageInfo` block:
+
+```rb
+pager = gql.paginate(:after => %w[some path to it])
+pager.execute(query) { |page| }
+
+pager = gql.paginate(:after => ->(data) { data.dig("some", "path", "to", "it") })
+pager.execute(query) { |page| }
+```
+
+The `"data"` and `"pageInfo"` keys are automatically added if not provided.
+
+### Automatically Retrying Failed Requests
+
+See [the docs](https://rubydoc.info/gems/shopify_api-graphql-tiny) for more information.
 
 ## Testing
 
@@ -59,6 +185,7 @@ See [the docs](https://rdoc.info/gems/shopify_api-graphql-tiny) for complete doc
 ## 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
 - [ShopifyAPIRetry](https://github.com/ScreenStaring/shopify_api_retry) - Retry a ShopifyAPI request if rate-limited or other errors occur (REST and GraphQL APIs)
 
 ## License

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

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module ShopifyAPI
   module GraphQL
     class Tiny
-      VERSION = "0.0.2"
+      VERSION = "0.1.1"
     end
   end
 end

data/lib/shopify_api/graphql/tiny.rb

@@ -24,6 +24,7 @@ module ShopifyAPI
         end
       end
 
+      RateLimitError = Class.new(GraphQLError)
 
       class HTTPError < Error
         attr_reader :code
@@ -34,14 +35,7 @@ module ShopifyAPI
         end
       end
 
-      class RateLimitError < Error
-        attr_reader :response
-
-        def initialize(message, response)
-          super(message)
-          @response = response
-        end
-      end
+      USER_AGENT = "ShopifyAPI::GraphQL::Tiny v#{VERSION} (Ruby v#{RUBY_VERSION})"
 
       SHOPIFY_DOMAIN = ".myshopify.com"
 
@@ -49,6 +43,8 @@ module ShopifyAPI
       QUERY_COST_HEADER = "X-GraphQL-Cost-Include-Fields"
 
       DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
+
+      # Retry rules to be used for all instances if no rules are specified via the +:retry+ option when creating an instance
       DEFAULT_RETRY_OPTIONS = {
         ConnectionError => { :wait => 3, :tries => 20 },
         GraphQLError => { :wait => 3, :tries => 20 },
@@ -71,7 +67,7 @@ module ShopifyAPI
       #
       # [:retry (Boolean|Hash)] +Hash+ can be retry config options. For the format see {ShopifyAPIRetry}[https://github.com/ScreenStaring/shopify_api_retry/#usage]. Defaults to +true+
       # [:version (String)] Shopify API version to use. Defaults to the latest version.
-      # [:debug (Boolean)] Output the HTTP request/response to +STDERR+. Defaults to +false+.
+      # [:debug (Boolean|IO)] Output the HTTP request/response to +STDERR+ or to its value if it's an +IO+. Defaults to +false+.
       #
       # === Errors
       #
@@ -102,21 +98,71 @@ module ShopifyAPI
       #
       # === Errors
       #
-      # ConnectionError, HTTPError, RateLimitError, GraphQLError
+      # ArgumentError, ConnectionError, HTTPError, RateLimitError, GraphQLError
       #
-      # * An HTTPError is raised of the response does not have 200 status code
-      # * A RateLimitError is raised if rate-limited and retries are disabled or if still rate-limited after the configured number of retry attempts
-      # * A GraphQLError is raised if the response contains an +errors+ property that is not a rate-limit error
+      # * An ShopifyAPI::GraphQL::Tiny::HTTPError is raised of the response does not have 200 status code
+      # * A ShopifyAPI::GraphQL::Tiny::RateLimitError is raised if rate-limited and retries are disabled or if still
+      #   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
       #
       # === Returns
       #
       # [Hash] The GraphQL response. Unmodified.
 
       def execute(q, variables = nil)
+        raise ArgumentError, "query required" if q.nil? || q.to_s.strip.empty?
+
         config = retry? ? @options[:retry] || DEFAULT_RETRY_OPTIONS : {}
         ShopifyAPIRetry::GraphQL.retry(config) { post(q, variables) }
       end
 
+      ##
+      # Create a pager to execute a paginated query:
+      #
+      #  pager = gql.paginate  # This is the same as gql.paginate(:after)
+      #  pager.execute(query, :id => id) do |page|
+      #    page.dig("data", "product", "title")
+      #  end
+      #
+      # The block is called for each page.
+      #
+      # Using pagination requires you to include the
+      # {PageInfo}[https://shopify.dev/api/admin-graphql/2022-10/objects/PageInfo]
+      # object in your queries and wrap them in a function that accepts a page/cursor argument.
+      # See the README for more information.
+      #
+      # === Arguments
+      #
+      # [direction (Symbol)] The direction to paginate, either +:after+ or +:before+. Optional, defaults to +:after:+
+      # [options (Hash)] Pagination options. Optional.
+      #
+      # === Options
+      #
+      # [:after (Array|Proc)] The location of {PageInfo}[https://shopify.dev/api/admin-graphql/2022-10/objects/PageInfo]
+      #                       block.
+      #
+      #                       An +Array+ will be passed directly to <code>Hash#dig</code>. A +TypeError+ resulting
+      #                       from the +#dig+ call will be raised as an +ArgumentError+.
+      #
+      #                       The <code>"data"</code> and <code>"pageInfo"</code> keys are automatically added if not provided.
+      #
+      #                       A +Proc+ must accept the GraphQL response +Hash+ as its argument and must return the
+      #                       +pageInfo+ block to use for pagination.
+      #
+      # [:before (Array|Proc)] See the +:after+ option
+      # [:variable (String)] Name of the GraphQL variable to use as the "page" argument.
+      #                      Defaults to <code>"before"</code> or <code>"after"</code>, depending on the pagination
+      #                      direction.
+      #
+      # === Errors
+      #
+      # ArgumentError
+
+      def paginate(*options)
+        Pager.new(self, options)
+      end
+
       private
 
       def retry?
@@ -138,12 +184,18 @@ module ShopifyAPI
 
           post = Net::HTTP::Post.new(@endpoint.path)
           post.body = params.to_json
+          post["User-Agent"] = USER_AGENT
 
           @headers.each { |k,v| post[k] = v }
 
           request = Net::HTTP.new(@endpoint.host, @endpoint.port)
           request.use_ssl = true
-          request.set_debug_output($stderr) if @options[:debug]
+
+          if @options[:debug]
+            request.set_debug_output(
+              @options[:debug].is_a?(IO) ? @options[:debug] : $stderr
+            )
+          end
 
           response = request.start { |http| http.request(post) }
         rescue => e
@@ -166,6 +218,147 @@ module ShopifyAPI
         raise GraphQLError.new(prefix + errors, json)
       end
     end
+
+    class Pager  # :nodoc:
+      NEXT_PAGE_KEYS = {
+        :before => %w[hasPreviousPage startCursor].freeze,
+        :after  => %w[hasNextPage endCursor].freeze
+      }.freeze
+
+      def initialize(gql, *options)
+        @gql = gql
+        @options = normalize_options(options)
+      end
+
+      def execute(q, variables = nil)
+        unless pagination_variable_exists?(q)
+          raise ArgumentError, "query does not contain the pagination variable '#{@options[:variable]}'"
+        end
+
+        variables ||= {}
+        pagination_finder = @options[@options[:direction]]
+
+        loop do
+          page = @gql.execute(q, variables)
+
+          yield page
+
+          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 = next_page_variables
+        end
+      end
+
+      private
+
+      def normalize_options(options)
+        normalized = {}
+
+        options.flatten!
+        options.each do |option|
+          case option
+          when Hash
+            normalized.merge!(normalize_hash_option(option))
+          when *NEXT_PAGE_KEYS.keys
+            normalized[:direction] = option
+          else
+            raise ArgumentError, "invalid pagination option #{option}"
+          end
+        end
+
+        normalized[:direction] ||= :after
+        normalized[normalized[:direction]] ||= method(:default_pagination_finder)
+
+        normalized[:variable] ||= normalized[:direction].to_s
+        normalized[:variable] = normalized[:variable].sub(%r{\A\$}, "")
+
+        normalized
+      end
+
+      def normalize_hash_option(option)
+        normalized = option.dup
+
+        NEXT_PAGE_KEYS.each do |key, _|
+          next unless option.include?(key)
+
+          normalized[:direction] = key
+
+          case option[key]
+          when Proc
+            normalized[key] = ->(data) { extract_cursor(option[key][data]) }
+          when Array
+            path = pagination_path(option[key])
+            normalized[key] = ->(data) do
+              begin
+                extract_cursor(data.dig(*path))
+              rescue TypeError => e
+                # Use original path in error as not to confuse
+                raise ArgumentError, "invalid pagination path #{option[key]}: #{e}"
+              end
+            end
+          else
+            raise ArgumentError, "invalid pagination locator #{option[key]}"
+          end
+        end
+
+        normalized
+      end
+
+      def pagination_path(user_path)
+        path = user_path.dup
+
+        # No need for this, we check for this key ourselves
+        path.pop if path[-1] == "pageInfo"
+
+        # Must always include this (sigh)
+        path.unshift("data") if path[0] != "data"
+
+        path
+      end
+
+      def pagination_variable_exists?(query)
+        name = Regexp.quote(@options[:variable])
+        query.match?(%r{\$#{name}\s*:})
+      end
+
+      def extract_cursor(data)
+        return unless data.is_a?(Hash)
+
+        has_next, next_cursor = NEXT_PAGE_KEYS[@options[:direction]]
+
+        pi = data["pageInfo"]
+        return unless pi && pi[has_next]
+
+        pi[next_cursor]
+      end
+
+      def default_pagination_finder(data)
+        cursor = nil
+
+        case data
+        when Hash
+          cursor = extract_cursor(data)
+          return cursor if cursor
+
+          data.values.each do |v|
+            cursor = default_pagination_finder(v)
+            break if cursor
+          end
+        when Array
+          data.each do |v|
+            cursor = default_pagination_finder(v)
+            break if cursor
+          end
+        end
+
+        cursor
+      end
+    end
   end
 
   GQL = GraphQL

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 Admin API GraphQL client with built-in retry.}
+  spec.summary       = %q{Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in pagination and retry}
   spec.homepage      = "https://github.com/ScreenStaring/shopify_api-graphql-tiny"
   spec.license       = "MIT"
 
@@ -21,6 +21,12 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+  spec.metadata = {
+    "bug_tracker_uri"   => "https://github.com/ScreenStaring/shopify_api-graphql-tiny/issues",
+    "changelog_uri"     => "https://github.com/ScreenStaring/shopify_api-graphql-tiny/blob/master/Changes",
+    "documentation_uri" => "https://rubydoc.info/gems/shopify_api-graphql-tiny",
+    "source_code_uri"   => "https://github.com/ScreenStaring/shopify_api-graphql-tiny",
+  }
 
   spec.add_dependency "shopify_api_retry", "~> 0.2"
   spec.add_development_dependency "webmock", "~> 3.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api-graphql-tiny
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.1
 platform: ruby
 authors:
 - Skye Shaw
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-08 00:00:00.000000000 Z
+date: 2023-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shopify_api_retry
@@ -104,7 +104,11 @@ files:
 homepage: https://github.com/ScreenStaring/shopify_api-graphql-tiny
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/ScreenStaring/shopify_api-graphql-tiny/issues
+  changelog_uri: https://github.com/ScreenStaring/shopify_api-graphql-tiny/blob/master/Changes
+  documentation_uri: https://rubydoc.info/gems/shopify_api-graphql-tiny
+  source_code_uri: https://github.com/ScreenStaring/shopify_api-graphql-tiny
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -123,6 +127,6 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
-summary: Lightweight, no-nonsense, Shopify Admin API GraphQL client with built-in
-  retry.
+summary: Lightweight, no-nonsense, Shopify GraphQL Admin API client with built-in
+  pagination and retry
 test_files: []