shopify-client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 996fd4c7f7e89ddeff22da53168828c5d8bd1a87ad3d965a512c10aee7c99850
+  data.tar.gz: 0c2829baff3a2518d6a4ab44544a975a7f72dcb8614d75b703e0da46f3238b25
+SHA512:
+  metadata.gz: 93aa4de201357efbf4a51f5924bf1f547d85ee822f5fe35f34b2a1e7cc23645849026bb309de43f48644a94ff6772f63b967e98dad5ca1670d305c1877f411c2
+  data.tar.gz: 2930f0d23bb145629ab392015142b213d4470d81c69675890ad9594983f8acf6fcac91ce1fabb68acb7207d779f9282faa6d261b9ee3249d021dad58dda101e9

data/README.md

@@ -0,0 +1,342 @@
+shopify-client
+==============
+
+1. [Installation](#installation)
+2. [Setup](#setup)
+    * [Configuration](#configuration)
+3. [Calling the API](#calling-the-api)
+    * [Make API requests](#make-api-requests)
+    * [Make bulk API requests](#make-bulk-api-requests)
+    * [Make cached API requests](#make-cached-api-requests)
+    * [Pagination](#pagination)
+4. [OAuth](#oauth)
+5. [Cookieless authentication](#cookieless-authentication)
+    * [Rack middleware](#rack-middleware)
+    * [Manual check](#manual-check)
+6. [Webhooks](#webhooks)
+    * [Configure webhooks](#configure-webhooks)
+    * [Create and delete webhooks](#create-and-delete-webhooks)
+7. [Verification](#verification)
+    * [Verify callbacks](#verify-callbacks)
+    * [Verify webhooks](#verify-webhooks)
+8. [Mixins](#mixins)
+    * [Read a resource](#read-a-resource)
+    * [Create a resource](#create-a-resource)
+    * [Update a resource](#update-a-resource)
+    * [Delete a resource](#delete-a-resource)
+
+
+Installation
+------------
+
+Add the gem to your 'Gemfile':
+
+    gem 'shopify-client'
+
+
+Setup
+-----
+
+### Configuration
+
+    ShopifyClient.configure do |config|
+      config.api_key = '...'
+      config.api_version = '...' # e.g. '2021-04'
+      config.cache_ttl = 3600
+      config.redirect_uri = '...' # for OAuth
+      config.logger = Logger.new(STDOUT) # defaults to a null logger
+      config.scope = '...'
+      config.shared_secret = '...'
+      config.webhook_uri = '...'
+    end
+
+All settings are optional and in some private apps, you may not require any
+configuration at all.
+
+
+Calling the API
+---------------
+
+### Make API requests
+
+    client = ShopifyClient::Client.new(myshopify_domain, access_token)
+
+    client.get('orders', since_id: since_id).data['orders']
+    client.post('orders', order: new_order)
+    client.graphql(%(
+      {
+        orders(first: 10) {
+          edges {
+            node {
+              id
+              tags
+            }
+          }
+        }
+      }
+    )).data['data']['orders']
+
+Request logging is disabled by default. To enable it:
+
+    ShopifyClient.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 bulk API requests
+
+The gem wraps Shopify's bulk query API by writing the result to a temporary file
+and yielding an enumerator which itself streams each line of the result to limit
+memory usage.
+
+    client.grahql_bulk(%(
+      {
+        products {
+          edges {
+            node {
+              id
+              handle
+            }
+          }
+        }
+      }
+    )) do |lines|
+      db.transaction do
+        lines.each do |product|
+          db[:products].insert(
+            id: product['id'],
+            handle: product['handle'],
+          )
+        end
+      end
+    end
+
+Bulk requests are limited to one per shop at any one time. Creating a new bulk
+request via the gem will cancel any request in progress for the shop.
+
+
+### Make cached API requests
+
+Make a cached GET request:
+
+    client.get_cached('orders', params: {since_id: since_id})
+
+Note that unlike `#get`, `#get_cached` returns the `Response#data` hash rather
+than a `Response` object.
+
+Making the same call with the same shop/client, will result in the data being
+returned straight from the cache on subsequent calls, until the configured TTL
+expires (the default TTL is 1 hour). If you're using Redis, it will be used as
+the cache store; otherwise, the cache will be stored in a thread local variable.
+
+You can also manually build and clear a cached request. For example, you might
+need to clear the cache without waiting for the TTL if you receive an update
+webhook indicating that the cached data is obsolete:
+
+    get_shop = ShopifyClient::CachedRequest.new('shop')
+
+    # Request shop data (from API).
+    get_shop.(client)
+    # Request shop data (from cache).
+    get_shop.(client)
+
+Clear the cache data to force fetch from API on next access:
+
+    get_shop.clear(myshopify_domain)
+
+Set the cache data (e.g. from shop/update webhook body):
+
+    get_shop.set(myshopify_domain, new_shop)
+
+
+### Pagination
+
+When you make a GET request, you can request the next or the previous page
+directly from the response object.
+
+    page_1 = client.get('orders')
+    page_2 = page_1.next_page
+    page_1 = page_2.previous_page
+
+When no page is available, `nil` will be returned.
+
+
+OAuth
+-----
+
+Redirect unauthorised users through the Shopify OAuth flow:
+
+    authorise = ShopifyClient::Authorise.new
+
+    redirect_to authorise.authorisation_code_url(myshopify_domain)
+
+Once the user returns to the app, exchange the authorisation code for an access
+token:
+
+    access_token = authorise.(client, authorisation_code)
+
+
+Cookieless authentication
+-------------------------
+
+Embedded apps using App Bridge are required to use the cookieless authentication
+system which uses JWT session tokens rather than cookies to authenticate users
+signed into the Shopify admin.
+
+
+### Rack middleware
+
+In config.ru, or wherever you set up your middleware stack:
+
+    use ShopifyClient::Cookieless::Middleware
+
+You can also control when session tokens are checked with a predicate (such as
+only for certain paths):
+
+    use ShopifyClient::Cookieless::Middleware, is_authenticated: ->(env) do
+      # ...
+    end
+
+
+### Manual check
+
+You can also check the Authorization header manually, if you require more
+control than the middleware provides:
+
+    begin
+      ShopifyClient::Cookieless::CheckHeader.new.(env)
+    rescue ShopifyClient::Error => e
+      # ...
+    end
+
+
+Webhooks
+--------
+
+### Configure webhooks
+
+Configure each webhook the app will create (if any), and register handlers:
+
+    ShopifyClient.webhooks.register('orders/create', OrdersCreateWebhook.new, fields: %w[id tags])
+
+You can register as many handlers as you need for a topic, and the gem will
+merge required fields across all handlers when creating the webhooks.
+
+To call/delegate a webhook to its handler for processing, you will likely want
+to create a worker around something like this:
+
+    webhook = ShopifyClient::Webhook.new(myshopify_domain, topic, data)
+
+    ShopifyClient.webhooks.delegate(webhook)
+
+
+### Create and delete webhooks
+
+Create/delete all configured webhooks (see above):
+
+    ShopifyClient::CreateAllWebhooks.new.(client)
+    ShopifyClient::DeleteAllWebhooks.new.(client)
+
+Create/delete webhooks manually:
+
+    webhook = {topic: 'orders/create', fields: %w[id tags]}
+
+    ShopifyClient::CreateWebhook.new.(client, webhook)
+    ShopifyClient::DeleteWebhook.new.(client, webhook_id)
+
+
+Verification
+------------
+
+### Verify requests
+
+Verify callback requests with the request params:
+
+    begin
+      ShopifyClient::VerifyRequest.new.(params)
+    rescue ShopifyClient::Error => e
+      # ...
+    end
+
+
+### Verify webhooks
+
+Verify webhook requests with the request data and the HMAC header:
+
+    begin
+      ShopifyClient::VerifyWebhook.new.(data, hmac)
+    rescue ShopifyClient::Error => e
+      # ...
+    end
+
+
+Mixins
+------
+
+A set of mixins is provided for easily creating repository classes for API
+resources. Each mixin represents an operation or a set of operations, e.g.
+reading and writing data to/from the API.
+
+
+### Read a resource
+
+    class OrderRepository
+      include ShopifyClient::Resource::Read
+
+      resource :orders
+
+      default_params fields: 'id,tags', limit: 250
+    end
+
+    order_repo = OrderRepository.new
+
+Find a single result:
+
+    order_repo.find_by_id(client, id)
+
+Iterate over results (automatic pagination):
+
+    order_repo.all.each do |order|
+      # ...
+    end
+
+
+### Create a resource
+
+    class OrderRepository
+      include ShopifyClient::Resource::Create
+
+      resource :orders
+    end
+
+    order_repo = OrderRepository.new
+
+    order_repo.create(client, new_order)
+
+
+### Update a resource
+
+    class OrderRepository
+      include ShopifyClient::Resource::Update
+
+      resource :orders
+    end
+
+    order_repo = OrderRepository.new
+
+    order_repo.update(client, id, order)
+
+
+### Delete a resource
+
+    class OrderRepository
+      include ShopifyClient::Resource::Delete
+
+      resource :orders
+    end
+
+    order_repo = OrderRepository.new
+
+    order_repo.delete(client, id)

data/lib/shopify-client.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'dry-configurable'
+require 'logger'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.new
+loader.push_dir(__dir__)
+loader.tag = File.basename(__FILE__, '.rb')
+loader.inflector.inflect(
+  'shopify-client' => 'ShopifyClient',
+  'version' => 'VERSION',
+)
+loader.setup
+
+module ShopifyClient
+  extend Dry::Configurable
+
+  setting :api_key
+  setting :api_version, '2021-04'
+  setting :cache_ttl, 3600
+  setting :logger, Logger.new(File::NULL).freeze
+  setting :oauth_redirect_uri
+  setting :oauth_scope
+  setting :shared_secret
+  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
+
+    # @return [WebhookList]
+    #
+    # @example Register webhook handlers
+    #   ShopifyClient.webhooks.register('orders/create', OrdersCreateWebhook.new, fields: %w[id tags])
+    #
+    # @example Call handlers for a topic
+    #   webhook = Webhook.new(myshopify_domain, topic, data)
+    #
+    #   ShopifyClient.webhooks.delegate(webhook)
+    def webhooks
+      @webhooks ||= WebhookList.new
+    end
+  end
+end

data/lib/shopify-client/authorise.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ShopifyClient
+  class Authorise
+    Error = Class.new(Error)
+
+    # @param myshopify_domain [String]
+    def authorisation_code_url(myshopify_domain)
+      format('https://%s/admin/oauth/authorize?client_id=%s&scope=%s&redirect_uri=%s',
+        myshopify_domain,
+        ShopifyClient.config.api_key,
+        ShopifyClient.config.scope,
+        ShopifyClient.config.redirect_uri,
+      ]
+    end
+
+    # Exchange an authorisation code for a new Shopify access token.
+    #
+    # @param client [Client]
+    # @param authorisation_code [String]
+    #
+    # @return [String] the access token
+    #
+    # @raise [Error] if the response is invalid
+    def call(client, authorisation_code)
+      data = client.post('/admin/oauth/access_token', {
+        client_id: ShopifyClient.config.api_key,
+        client_secret: ShopifyClient.config.shared_secret,
+        code: authorisation_code,
+      }).data
+
+      raise Error if data['access_token'].nil?
+      raise Error if data['scope'] != ShopifyClient.config.scope
+
+      data['access_token']
+    end
+  end
+end

data/lib/shopify-client/bulk_request.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'tempfile'
+require 'timeout'
+
+module ShopifyClient
+  class BulkRequest
+    OperationError = Class.new(Error)
+
+    CanceledOperationError = Class.new(OperationError)
+    ExpiredOperationError = Class.new(OperationError)
+    FailedOperationError = Class.new(OperationError)
+    ObsoleteOperationError = Class.new(OperationError)
+
+    TimeoutError = Class.new(Error)
+
+    class Operation
+      # @param client [Client]
+      # @param id [String]
+      def initialize(client, id)
+        @client = client
+        @id = id
+      end
+
+      # Wait for the operation to complete, then download the JSONL result
+      # data which is yielded as an {Enumerator} to the block. The data is
+      # streamed and parsed line by line to limit memory usage.
+      #
+      # @param delay [Integer] delay between polling requests in seconds
+      #
+      # @yield [Enumerator<Hash>] yields each parsed line of JSONL
+      #
+      # @raise CanceledOperationError
+      # @raise ExpiredOperationError
+      # @raise FailedOperationError
+      # @raise ObsoleteOperationError
+      def call(delay: 1, &block)
+        url = loop do
+          status, url = poll
+
+          case status
+          when 'CANCELED'
+            raise CanceledOperationError
+          when 'EXPIRED'
+            raise ExpiredOperationError
+          when 'FAILED'
+            raise FailedOperationError
+          when 'COMPLETED'
+            break url
+          else
+            sleep(delay)
+          end
+        end
+
+        return if url.nil?
+
+        file = Tempfile.new(mode: 0600)
+
+        begin
+          Faraday.get(url) do |request|
+            request.options.on_data = ->(chunk, _) do
+              file.write(chunk)
+            end
+          end
+          file.rewind
+          block.(Enumerator.new do |y|
+            file.each_line { |line| y << JSON.parse(line) }
+          end)
+        ensure
+          file.close
+          file.unlink
+        end
+      end
+
+      # Cancel the bulk operation.
+      #
+      # @raise ObsoleteOperationError
+      # @raise TimeoutError
+      def cancel
+        begin
+          @client.graphql(<<~QUERY)
+            mutation {
+              bulkOperationCancel(id: "#{@id}") {
+                userErrors {
+                  field
+                  message
+                }
+              }
+            }
+          QUERY
+        rescue Response::GraphQLClientError => e
+          return if e.response.user_errors.message?([
+            /cannot be canceled when it is completed/,
+          ])
+
+          raise e
+        end
+
+        poll_until(['CANCELED', 'COMPLETED'])
+      end
+
+      # Poll until operation status is met.
+      #
+      # @param statuses [Array<String>] to terminate polling on
+      # @param timeout [Integer] in seconds
+      #
+      # @raise ObsoleteOperationError
+      # @raise TimeoutError
+      def poll_until(statuses, timeout: 60)
+        Timeout.timeout(timeout) do
+          loop do
+            status, _ = poll
+
+            break if statuses.any? { |expected_status| status == expected_status }
+          end
+        end
+      rescue Timeout::Error
+        raise TimeoutError, 'exceeded %s seconds polling for status %s' % [
+          timeout,
+          statuses.join(', '),
+        ]
+      end
+
+      # @return [Array(String, String | nil)] the operation status and the
+      #   download URL, or nil if the result data is empty
+      private def poll
+        op = @client.graphql(<<~QUERY).data['data']['currentBulkOperation']
+          {
+            currentBulkOperation {
+              id
+              status
+              url
+            }
+          }
+        QUERY
+
+        raise ObsoleteOperationError if op['id'] != @id
+
+        [
+          op['status'],
+          op['url'],
+        ]
+      end
+    end
+
+    # Create and start a new bulk operation via the GraphQL API. Any currently
+    # running bulk operations are cancelled.
+    #
+    # @param client [Client]
+    # @param query [String] the GraphQL query
+    #
+    # @return [Operation]
+    #
+    # @example
+    #   bulk_request.(client, <<~QUERY).() do |products|
+    #     {
+    #       products {
+    #         edges {
+    #           node {
+    #             id
+    #             handle
+    #           }
+    #         }
+    #       }
+    #     }
+    #   QUERY
+    #     db.transaction do
+    #       products.each do |product|
+    #         db[:products].insert(
+    #           id: product['id'],
+    #           handle: product['handle'],
+    #         )
+    #       end
+    #     end
+    #   end
+    def call(client, query)
+      ShopifyClient.assert_api_version!('2019-10')
+
+      op = client.graphql(<<~QUERY)['data']['currentBulkOperation']
+        {
+          currentBulkOperation {
+            id
+            status
+            url
+          }
+        }
+      QUERY
+
+      case op&.fetch('status')
+      when 'CANCELING'
+        Operation.new(client, op['id']).poll_until(['CANCELED'])
+      when 'CREATED', 'RUNNING'
+        Operation.new(client, op['id']).cancel
+      end
+
+      id = client.graphql(<<~QUERY).data['data']['bulkOperationRunQuery']['bulkOperation']['id']
+        mutation {
+          bulkOperationRunQuery(
+            query: """
+              #{query}
+            """
+          ) {
+            bulkOperation {
+              id
+            }
+            userErrors {
+              field
+              message
+            }
+          }
+        }
+      QUERY
+
+      Operation.new(client, id)
+    end
+  end
+end