lucid-shopify 0.40.0 → 0.50.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98281c9fea5c19507b29e96c9ac8d5ccaf1c1f94b902cd3f736c28514913228a
-  data.tar.gz: 5e7c2d62db39d4ca105666fccc329b255d3e20e4de7730d2d75f8dd031d3cd77
+  metadata.gz: 3bb84f7626f55c571effa2ee48a98c1c688da8eea47b4de4c5afae7c14a3497a
+  data.tar.gz: 79082a133ae357a08c07f18dfbaef1250e0edb3d59c513dd1479407214cf241a
 SHA512:
-  metadata.gz: 9461458119fca0aafc7fe4ebe00366a544ca63aba55588beec3d86d749f26ae9b2e7f31da3460511ea471b4f0fdbfb04c05a35ff0906fbb4809d7b5c00cc84a7
-  data.tar.gz: 6912e93c75a6c708b7da8e31b778fe266ce26e823473c3a6a5859b73e716feb73b307bab2b7dd0ddfe90ab88fde65bb7e219349705656ef9b7cda715db4719c6
+  metadata.gz: 60e51efc5e0718d4372a7d0544ffac51387536da2a89f31d8a6baba15b3e0bb04e83be03c37664f1e7cf8b75430ca8db9fa87b480729bcada2650ed9d1a22454
+  data.tar.gz: 6e30ffd8a298e1359831900b4476a512ecbb3fc2c9a57f5ff7173c80d0f360dda9f688489e177616a87a12cf70942e233a3f592eaccb69aa5a559d701d2ecd94

data/README.md

@@ -1,6 +1,25 @@
 lucid-shopify
 =============
 
+1. [Installation](#installation)
+2. [Setup](#setup)
+    * [Configure the API client](#configure-the-api-client)
+3. [Calling the API](#calling-the-api)
+    * [Make API requests](#make-api-requests)
+    * [Make unthrottled API requests](#make-unthrottled-api-requests)
+    * [Make bulk API requests](#make-bulk-api-requests)
+    * [Pagination](#pagination)
+4. [Authorisation](#authorisation)
+5. [Billing](#billing)
+6. [Webhooks](#webhooks)
+    * [Configure webhooks](#configure-webhooks)
+    * [Register webhook handlers](#register-webhook-handlers)
+    * [Create and delete webhooks](#create-and-delete-webhooks)
+7. [Verification](#verification)
+    * [Verify callbacks](#verify-callbacks)
+    * [Verify webhooks](#verify-webhooks)
+
+
 Installation
 ------------
 
@@ -9,10 +28,10 @@ Add the gem to your ‘Gemfile’:
     gem 'lucid-shopify'
 
 
-Usage
+Setup
 -----
 
-### Configure the default API client
+### Configure the API client
 
     Lucid::Shopify.configure do |config|
       config.api_key = '...'
@@ -25,8 +44,8 @@ Usage
       config.webhook_uri = '...'
     end
 
-All settings are optional and in some private apps, you may not
-require any configuration at all.
+All settings are optional and in some private apps, you may not require any
+configuration at all.
 
 Additionally, each API request requires authorisation:
 
@@ -35,10 +54,111 @@ Additionally, each API request requires authorisation:
       '...', # access_token
     )
 
-If the access token is omitted, the request will be unauthorised.
-This is only useful during the OAuth2 process.
+If the access token is omitted, the request will be unauthorised.  This is only
+useful during the OAuth2 process.
+
+
+Calling the API
+---------------
+
+### Make API requests
+
+    client = Lucid::Shopify::Client.new
+
+    client.get(credentials, 'orders', since_id: since_id)['orders']
+    client.post_json(credentials, 'orders', new_order)
+    client.post_graphql(credentials, <<~QUERY)['data']['orders']
+      {
+        orders {
+          edges {
+            node {
+              id
+              tags
+            }
+          }
+        }
+      }
+    QUERY
+
+Request logging is disabled by default. To enable it:
+
+    Lucid::Shopify.config.logger = Logger.new(STDOUT)
+
+Request throttling is enabled by default. If you're using Redis, throttling will
+automatically make use of it; otherwise, throttling will only be maintained
+across a single thread.
+
+
+### Make unthrottled API requests
+
+    client.unthrottled.get(credentials, 'orders')
+    client.unthrottled.post_json(credentials, 'orders', new_order)
+
+
+### Make bulk API requests
+
+Since API version 2019-10, Shopify has offered an API for bulk requests (using
+the GraphQL API). The gem wraps this API, by writing the result to a temporary
+file and yielding each line of the result to limit memory usage.
+
+    client.bulk(credentials, <<~QUERY) do |product|
+      {
+        products {
+          edges {
+            node {
+              id
+              title
+            }
+          }
+        }
+      }
+    QUERY
+      puts product['id']
+      puts product['title']
+    end
+
+
+### Pagination
+
+Since API version 2019-07, Shopify has encouraged a new method for pagination
+based on the Link header. When you make a GET request, you can request the next
+or the previous page directly from the response object.
+
+    page_1 = client.get(credentials, 'orders')
+    page_2 = page_1.next
+    page_1 = page_2.previous
+
+When no page is available, `nil` will be returned.
+
+
+Authorisation
+-------------
+
+    authorise = Lucid::Shopify::Authorise.new
+
+    access_token = authorise.(credentials, authorisation_code)
+
+
+Billing
+-------
+
+Create a new charge:
+
+    create_charge = Lucid::Shopify::CreateCharge.new
+
+    charge = create_charge.(credentials, charge) # see Lucid::Shopify::Charge
+
+Redirect the user to `charge['confirmation_url']`. When the user returns (see
+`config.billing_callback_uri`), activate the accepted charge:
+
+    activate_charge = Lucid::Shopify::ActivateCharge.new
+
+    activate_charge.(credentials, accepted_charge)
 
 
+Webhooks
+--------
+
 ### Configure webhooks
 
 Configure each webhook the app will create (if any):
@@ -81,7 +201,10 @@ Create/delete webhooks manually:
     Lucid::Shopify::DeleteWebhook.new.(credentials, webhook_id)
 
 
-### Verification
+Verification
+------------
+
+### Verify callbacks
 
 Verify callback requests with the request params:
 
@@ -91,6 +214,9 @@ Verify callback requests with the request params:
       # ...
     end
 
+
+### Verify webhooks
+
 Verify webhook requests with the request data and the HMAC header:
 
     begin
@@ -98,63 +224,3 @@ Verify webhook requests with the request data and the HMAC header:
     rescue Lucid::Shopify::Error => e
       # ...
     end
-
-
-### Authorisation
-
-    authorise = Lucid::Shopify::Authorise.new
-
-    access_token = authorise.(credentials, authorisation_code)
-
-
-### Billing
-
-Create a new charge:
-
-    create_charge = Lucid::Shopify::CreateCharge.new
-
-    charge = create_charge.(credentials, charge) # see Lucid::Shopify::Charge
-
-Redirect the user to `charge['confirmation_url']`. When the user
-returns (see `config.billing_callback_uri`), activate the accepted
-charge:
-
-    activate_charge = Lucid::Shopify::ActivateCharge.new
-
-    activate_charge.(credentials, accepted_charge)
-
-
-### Make API requests
-
-    client = Lucid::Shopify::Client.new
-
-    client.get(credentials, 'orders', since_id: since_id)['orders']
-    client.post_json(credentials, 'orders', new_order)
-
-Request logging is disabled by default. To enable it:
-
-    Lucid::Shopify.config.logger = Logger.new(STDOUT)
-
-Request throttling is enabled by default. If you're using Redis, throttling
-will automatically make use of it; otherwise, throttling will only be
-maintained across a single thread.
-
-
-### Make unthrottled API requests
-
-    client.unthrottled.get(credentials, 'orders')
-    client.unthrottled.post_json(credentials, 'orders', new_order)
-
-
-### Pagination
-
-Since API version 2019-07, Shopify has encouraged a new method for
-pagination based on the Link header. When you make a GET request,
-you can request the next or the previous page directly from the
-response object.
-
-    page_1 = client.get(credentials, 'orders')
-    page_2 = page_1.next
-    page_1 = page_2.previous
-
-When no page is available, `nil` will be returned.

data/lib/lucid/shopify.rb

@@ -25,6 +25,7 @@ module Lucid
     autoload :GetRequest, 'lucid/shopify/get_request'
     autoload :ParseLinkHeader, 'lucid/shopify/parse_link_header'
     autoload :PostRequest, 'lucid/shopify/post_request'
+    autoload :PostGraphQLRequest, 'lucid/shopify/post_graphql_request'
     autoload :PutRequest, 'lucid/shopify/put_request'
     autoload :RedisThrottledStrategy, 'lucid/shopify/redis_throttled_strategy'
     autoload :Request, 'lucid/shopify/request'
@@ -52,6 +53,13 @@ module Lucid
     setting :webhook_uri
 
     class << self
+      # @param version [String]
+      #
+      # @raise [RuntimeError]
+      def assert_api_version!(version)
+        raise "requires API version >= #{version}" if config.api_version < version
+      end
+
       # Webhooks created for each shop.
       #
       # @return [WebhookList]

data/lib/lucid/shopify/bulk_request.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class BulkRequest
+      OperationError = Class.new(Error)
+
+      CanceledOperationError = Class.new(OperationError)
+      ExpiredOperationError = Class.new(OperationError)
+      FailedOperationError = Class.new(OperationError)
+      ObsoleteOperationError = Class.new(OperationError)
+
+      # @param http [HTTP::Client]
+      def initialize(http: Container[:http])
+        @http = http
+      end
+
+      # @param client [Client]
+      # @param credentials [Credentials]
+      # @param query [String]
+      #
+      # @yield [String] each parsed line of JSONL (streamed to limit memory usage)
+      #
+      # @example
+      #   bulk_request.(client, credentials, <<~QUERY)
+      #     {
+      #       products {
+      #         edges {
+      #           node {
+      #             id
+      #             handle
+      #             publishedAt
+      #           }
+      #         }
+      #       }
+      #     }
+      #   QUERY
+      def call(client, credentials, query, &block)
+        Shopify.assert_api_version!('2019-10')
+
+        id = client.post_graphql(credentials, <<~QUERY)['data']['bulkOperationRunQuery']['bulkOperation']['id']
+          mutation {
+            bulkOperationRunQuery(
+              query: """
+                #{query}
+              """
+            ) {
+              bulkOperation {
+                id
+              }
+              userErrors {
+                field
+                message
+              }
+            }
+          }
+        QUERY
+
+        url = poll(client, credentials, id)
+
+        # TODO: Verify signature?
+
+        begin
+          file = Tempfile.new(mode: 0600)
+          body = @http.get(url).body
+          until (chunk = body.readpartial).nil?
+            file.write(chunk)
+          end
+          file.rewind
+          file.each_line do |line|
+            block.call(JSON.parse(line))
+          end
+        ensure
+          file.close
+          file.unlink
+        end
+      end
+
+      # @param client [Client]
+      # @param credentials [Credentials]
+      # @param id [Integer] of the bulk operation
+      #
+      # @return [String] the download URL
+      private def poll(client, credentials, id)
+        op = client.post_graphql(credentials, <<~QUERY)['data']['currentBulkOperation']
+          {
+            currentBulkOperation {
+              id
+              status
+              url
+            }
+          }
+        QUERY
+
+        raise ObsoleteOperationError if op['id'] != id
+
+        case op['status']
+        when 'CANCELED'
+          raise CanceledOperationError
+        when 'EXPIRED'
+          raise ExpiredOperationError
+        when 'FAILED'
+          raise FailedOperationError
+        when 'COMPLETED'
+          op['url']
+        else
+          poll(client, credentials, id)
+        end
+      end
+    end
+  end
+end

data/lib/lucid/shopify/client.rb

@@ -2,22 +2,26 @@
 
 require 'lucid/shopify/container'
 
-%w[delete get post put].each { |m| require "lucid/shopify/#{m}_request" }
+%w[delete get post post_graphql put].each { |m| require "lucid/shopify/#{m}_request" }
 
 module Lucid
   module Shopify
     class Client
+      # @param bulk_request [#call]
       # @param send_request [#call]
       # @param send_throttled_request [#call]
       # @param throttling [Boolean]
-      def initialize(send_request: Container[:send_request],
+      def initialize(bulk_request: Container[:bulk_request],
+                     send_request: Container[:send_request],
                      send_throttled_request: Container[:send_throttled_request],
                      throttling: true)
+        @bulk_request = bulk_request
         @send_request = send_request
         @send_throttled_request = send_throttled_request
         @throttling = throttling
 
         @params = {
+          bulk_request: @bulk_request,
           send_request: @send_request,
           send_throttled_request: @send_throttled_request
         }
@@ -58,6 +62,11 @@ module Lucid
         AuthenticatedClient.new(self, credentials)
       end
 
+      # @see BulkRequest#call
+      def bulk(*args, &block)
+        @bulk_request.(self, *args, &block)
+      end
+
       # @see DeleteRequest#initialize
       def delete(*args)
         send_request.(DeleteRequest.new(*args))
@@ -68,6 +77,11 @@ module Lucid
         send_request.(GetRequest.new(*args))
       end
 
+      # @see PostGraphQLRequest#initialize
+      def post_graphql(*args)
+        send_request.(PostGraphQLRequest.new(*args))
+      end
+
       # @see PostRequest#initialize
       def post_json(*args)
         send_request.(PostRequest.new(*args))

data/lib/lucid/shopify/container.rb

@@ -12,6 +12,7 @@ module Lucid
     # Services only (dependencies); no value objects, entities.
     Container.register(:activate_charge) { ActivateCharge.new }
     Container.register(:authorise) { Authorise.new }
+    Container.register(:bulk_request) { BulkRequest.new }
     Container.register(:client) { Client.new }
     Container.register(:create_all_webhooks) { CreateAllWebhooks.new }
     Container.register(:create_charge) { CreateCharge.new }

data/lib/lucid/shopify/post_graphql_request.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class PostGraphQLRequest < Request
+      # @private
+      #
+      # @param credentials [Credentials]
+      # @param query [String] the GraphQL query
+      # @param variables [Hash] the GraphQL variables (if any)
+      #
+      # @see https://graphql.org/graphql-js/graphql-clients
+      # @see https://graphql.org/graphql-js/mutations-and-input-types
+      def initialize(credentials, query, variables: {})
+        super(credentials, :post, 'graphql', json: {
+          query: query,
+          variables: variables,
+        })
+      end
+    end
+  end
+end

data/lib/lucid/shopify/response.rb

@@ -111,6 +111,11 @@ module Lucid
           raise ServerError.new(request, self)
         end
 
+        # GraphQL always has status 200.
+        if request.is_a?(PostGraphQLRequest) && errors?
+          raise ClientError.new(request, self)
+        end
+
         self
       end
 
@@ -126,18 +131,50 @@ module Lucid
 
       # @return [Boolean]
       def errors?
+        return user_errors? if user_errors?
+
         data_hash.has_key?('errors') # should be only on 422
       end
 
+      # GraphQL user errors.
+      #
+      # @return [Boolean]
+      private def user_errors?
+        errors = data_hash.dig('data', 'userErrors')
+
+        !errors.nil? && !errors.empty?
+      end
+
       # A string rather than an object is returned by Shopify in the case of,
       # e.g., 'Not found'. In this case, we return it under the 'resource' key.
       #
       # @return [Hash]
       def errors
         errors = data_hash['errors']
-        return {} if errors.nil?
-        return {'resource' => errors} if errors.is_a?(String)
-        errors
+        errors = case
+        when errors.nil?
+          {}
+        when errors.is_a?(String)
+          {'resource' => errors}
+        else
+          errors
+        end
+
+        errors.merge(user_errors)
+      end
+
+      # GraphQL user errors.
+      #
+      # @return [Hash]
+      private def user_errors
+        errors = data_hash.dig('data', 'userErrors')
+        return {} if errors.nil? || errors.empty?
+        errors.map do |error|
+          [
+            error['field'],
+            error['message'],
+          ]
+        end.to_h
       end
 
       # @return [Array<String>]

data/lib/lucid/shopify/version.rb

@@ -2,6 +2,6 @@
 
 module Lucid
   module Shopify
-    VERSION = '0.40.0'
+    VERSION = '0.50.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lucid-shopify
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.50.0
 platform: ruby
 authors:
 - Kelsey Judson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-12 00:00:00.000000000 Z
+date: 2020-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv
@@ -147,6 +147,7 @@ files:
 - lib/lucid/shopify.rb
 - lib/lucid/shopify/activate_charge.rb
 - lib/lucid/shopify/authorise.rb
+- lib/lucid/shopify/bulk_request.rb
 - lib/lucid/shopify/client.rb
 - lib/lucid/shopify/container.rb
 - lib/lucid/shopify/create_all_webhooks.rb
@@ -159,6 +160,7 @@ files:
 - lib/lucid/shopify/error.rb
 - lib/lucid/shopify/get_request.rb
 - lib/lucid/shopify/parse_link_header.rb
+- lib/lucid/shopify/post_graphql_request.rb
 - lib/lucid/shopify/post_request.rb
 - lib/lucid/shopify/put_request.rb
 - lib/lucid/shopify/redis_throttled_strategy.rb