shopify_api-graphql-tiny 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c46728d688b8edf620e1d9e5d9f78b32dcb4dde40854996e2a42b66f642596b
-  data.tar.gz: 5640ff9490907231cb4d2a9bae7d8f4f96460265bfcd6d77572d4f90e2b758d7
+  metadata.gz: be69f222bb991d00b37c44d8aea2ad9caee713527ce23c60121a401d8d2a8b39
+  data.tar.gz: 5a35aaada946e0f0ef1dc50ea7962da2252a7f70a111a911f660b1c8eab3a79a
 SHA512:
-  metadata.gz: 5e1f350a6269fbb377f29c2342add0ae82b103aa940047995e5f377896e7c0ca0ca555b3eb4f9083bfea8edf8e3f310ae2caf99e7de5ac1b1451b6b12d45158e
-  data.tar.gz: 9c5fad042bcb6cb2b638178bfe7a0dc5920ca585b1e317c310b25be9ec6c79476c2cf6342bde98ad0c3a467b4864edf37a7cdf9153f4b2ddbe58b49def372b4a
+  metadata.gz: be94db6e155cc11d0136a229e6ee728ac808c655896f5489a657fc4ba82b7d5ab8403989bc356cfaaa617766077220e8234c60ff6d9aa9a651d484490cb161c3
+  data.tar.gz: 166c19ddde4a76d8d216bffac16d3844c9add39f9884eb70adac3477ce5b222e19cba820c1bae1204f58424239be38a1ec063d8e75a977f337f0d5df5afc6452

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,7 @@
+2023-02-12  v0.1.1
+--------------------
+* Add pagination support
+
 2022-06-16  v0.1.0
 --------------------
 * Make RateLimitError a subclass of GraphQLError

data/README.md

@@ -1,15 +1,37 @@
 # 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)](https://github.com/ScreenStaring/shopify_api-graphql-tiny/actions)
 
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "shopify_api-graphql-tiny"
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+Or install it yourself as:
+
+```sh
+gem install shopify_api-graphql-tiny
+```
+
 ## Usage
 
 ```rb
 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 +55,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 +74,131 @@ 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
+gql = ShopifyAPI::GraphQL::Tiny.new("my-shop", token)
+pager = gql.paginate
+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 +207,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.1.0"
+      VERSION = "0.2.0"
     end
   end
 end

data/lib/shopify_api/graphql/tiny.rb

@@ -43,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 },
@@ -84,6 +86,10 @@ module ShopifyAPI
         @headers[QUERY_COST_HEADER] = "true" if retry?
 
         @endpoint = URI(sprintf(ENDPOINT, @domain, !@options[:version].to_s.strip.empty? ? "/#{@options[:version]}" : ""))
+
+        if @options[:retry].is_a?(Hash)
+          warn "DEPRECATION WARNING from #{self.class}: specifying retry options as a Hash via the :retry option is deprecated and will be removed in v1.0"
+        end
       end
 
       #
@@ -96,21 +102,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?
@@ -166,6 +222,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,13 @@
 --- !ruby/object:Gem::Specification
 name: shopify_api-graphql-tiny
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Skye Shaw
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-16 00:00:00.000000000 Z
+date: 2026-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shopify_api_retry
@@ -80,7 +79,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: 
 email:
 - skye.shaw@gmail.com
 executables: []
@@ -104,8 +102,11 @@ files:
 homepage: https://github.com/ScreenStaring/shopify_api-graphql-tiny
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+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
 rdoc_options: []
 require_paths:
 - lib
@@ -120,10 +121,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.6.2
 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: []