lucid-shopify 0.34.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 217e5561d29c394e5975a12714a48d9dd4d5a4e93b7e69d421ec2636870ac7db
+  data.tar.gz: fc995f74c559fd840abf1a865b1dc387b836dcfa75ac4c1024c70671f27fbe2f
+SHA512:
+  metadata.gz: fbd32aef35360dcfd9da86a985d1cbbfb459c0443ea968dd8ca08645560bf4257d3839fe457b0a298080e901c1bab10dfecf5a2e1c2ccce931cc7b7bc27db76d
+  data.tar.gz: a5019bb0890375bb869195ffda3c8e2d41b0ba80339dfd47ac16fe4637f6f3319804698dfd6d035b8e2d68ac9281a6de977129d4c8c63b37c40a77cfb546ea61

data/README.md

@@ -0,0 +1,156 @@
+lucid-shopify
+=============
+
+Installation
+------------
+
+Add the gem to your ‘Gemfile’:
+
+    gem 'lucid-shopify'
+
+
+Usage
+-----
+
+### Configure the default API client
+
+    Lucid::Shopify.configure(
+      api_key: '...',
+      api_version: '...', # e.g. '2019-07'
+      billing_callback_uri: '...',
+      callback_uri: '...', # (for OAuth; unused by this gem)
+      logger: Logger.new(STDOUT),
+      scope: '...',
+      shared_secret: '...',
+      webhook_uri: '...',
+    )
+
+Alternatively load the configuration from a Ruby file. The Ruby
+file is evaluated and should return a hash.
+
+    Lucid::Shopify.configure_from_file('config/shopify.rb') # the default path
+
+When loading from a file, any environment variables matching the
+upcased key with the prefix ‘SHOPIFY_’ will override values in the
+file. For example ‘SHOPIFY_SHARED_SECRET=...’.
+
+All keys are optional and in some private apps, you may not require
+any configuration at all.
+
+Additionally, each API request requires authorisation:
+
+    credentials = Lucid::Shopify::Credentials.new(
+      '...', # myshopify_domain
+      '...', # access_token
+    )
+
+If the access token is omitted, the request will be unauthorised.
+This is only useful during the OAuth2 process.
+
+
+### Configure webhooks
+
+Configure each webhook the app will create (if any):
+
+    webhooks = Lucid::Shopify::Container['webhook_list']
+
+    webhooks.register('orders/create', fields: 'id,tags'}
+
+
+### Register webhook handlers
+
+For each webhook, register one or more handlers:
+
+    handlers = Lucid::Shopify::Container['webhook_handler_list']
+
+    handlers.register('orders/create', OrdersCreateWebhook.new)
+
+See the inline method documentation for more detail.
+
+To call/delegate a webhook to its handler for processing, you will likely want
+to create a worker around something like this:
+
+    webhook = Lucid::Shopify::Webhook.new(myshopify_domain, topic, data)
+
+    handlers.delegate(webhook)
+
+
+### Create and delete webhooks
+
+Create/delete all configured webhooks (see above):
+
+    Lucid::Shopify::CreateAllWebhooks.new.(credentials)
+    Lucid::Shopify::DeleteAllWebhooks.new.(credentials)
+
+Create/delete webhooks manually:
+
+    webhook = {topic: 'orders/create', fields: %w(id tags)}
+
+    Lucid::Shopify::CreateWebhook.new.(credentials, webhook)
+    Lucid::Shopify::DeleteWebhook.new.(credentials, webhook_id)
+
+
+### Verification
+
+Verify callback requests with the request params:
+
+    begin
+      Lucid::Shopify::VerifyCallback.new.(params)
+    rescue Lucid::Shopify::Error => e
+      # ...
+    end
+
+Verify webhook requests with the request data and the HMAC header:
+
+    begin
+      Lucid::Shopify::VerifyWebhook.new.(data, hmac)
+    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.configure(
+      logger: Logger.new(STDOUT),
+    )
+
+
+### Make throttled API requests
+
+    client.throttled.get(credentials, 'orders')
+    client.throttled.post_json(credentials, 'orders', new_order)
+
+Note that throttling currently uses a naive implementation that is
+only maintained across a single thread.

data/lib/lucid/shopify/activate_charge.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class ActivateCharge
+      # @param client [#post_json]
+      def initialize(client: Container[:client])
+        @client = client
+      end
+
+      # Activate a recurring application charge.
+      #
+      # @param credentials [Credentials]
+      # @param charge [#to_h] an accepted charge received from Shopify via callback
+      #
+      # @return [Hash] the active charge
+      def call(credentials, charge)
+        data = @client.post_json(credentials, "recurring_application_charges/#{charge.to_h['id']}/activate", charge.to_h)
+
+        data['recurring_application_charge']
+      end
+    end
+  end
+end

data/lib/lucid/shopify/authorise.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class Authorise
+      Error = Class.new(Error)
+
+      # @param client [#post_json]
+      def initialize(client: Container[:client])
+        @client = client
+      end
+
+      # Exchange an authorisation code for a new Shopify access token.
+      #
+      # @param myshopify_domain [String]
+      # @param authorisation_code [String]
+      #
+      # @return [String] the access token
+      #
+      # @raise [Error] if the response is invalid
+      def call(myshopify_domain, authorisation_code)
+        credentials = Credentials.new(myshopify_domain)
+
+        data = @client.post_json(credentials, 'oauth/access_token', post_data(authorisation_code))
+
+        raise Error if data['access_token'].nil?
+        raise Error if data['scope'] != Shopify.config.scope
+
+        data['access_token']
+      end
+
+      # @param authorisation_code [String]
+      #
+      # @return [Hash]
+      private def post_data(authorisation_code)
+        {
+          client_id: Shopify.config.api_key,
+          client_secret: Shopify.config.shared_secret,
+          code: authorisation_code,
+        }
+      end
+    end
+  end
+end

data/lib/lucid/shopify/client.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+%w[delete get post put].each { |m| require "lucid/shopify/#{m}_request" }
+
+module Lucid
+  module Shopify
+    class Client
+      # @param send_request [#call]
+      # @param send_throttled_request [#call]
+      def initialize(send_request: Container[:send_request],
+                     send_throttled_request: Container[:send_throttled_request],
+                     throttling: false)
+        @send_request = send_request
+        @send_throttled_request = send_throttled_request
+        @throttling = throttling
+
+        @params = {
+          send_request: @send_request,
+          send_throttled_request: @send_throttled_request
+        }
+      end
+
+      # @return [#call]
+      private def send_request
+        throttled? ? @send_throttled_request : @send_request
+      end
+
+      # @return [Boolean]
+      def throttled?
+        @throttling
+      end
+
+      # Returns a new instance with throttling enabled, or self.
+      #
+      # @return [Client, self]
+      def throttled
+        return self if throttled?
+
+        self.class.new(**@params, throttling: true)
+      end
+
+      # Returns a new instance with throttling disabled, or self.
+      #
+      # @return [Client, self]
+      def unthrottled
+        return self unless throttled?
+
+        self.class.new(**@params, throttling: false)
+      end
+
+      # @see DeleteRequest#initialize
+      def delete(*args)
+        send_request.(DeleteRequest.new(*args))
+      end
+
+      # @see GetRequest#initialize
+      def get(*args)
+        send_request.(GetRequest.new(*args))
+      end
+
+      # @see PostRequest#initialize
+      def post_json(*args)
+        send_request.(PostRequest.new(*args))
+      end
+
+      # @see PutRequest#initialize
+      def put_json(*args)
+        send_request.(PutRequest.new(*args))
+      end
+    end
+  end
+end

data/lib/lucid/shopify/config.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+require 'lucid/shopify'
+require 'lucid/utils'
+
+module Lucid
+  module Shopify
+    class << self
+      # @param options [Hash]
+      #
+      # @return [Config]
+      def configure(options = {})
+        @config = Config.new(
+          **@config.to_h.compact,
+          **options,
+        )
+      end
+
+      # @param path [String]
+      #
+      # @return [Config]
+      def configure_from_file(path = 'config/shopify.rb')
+        options = Utils::ConfigFromFile.new.(path, env_prefix: 'shopify')
+
+        configure(options)
+      end
+
+      # @return [Config]
+      def config
+        @config ||= configure
+      end
+    end
+
+    class Config < Dry::Struct
+      attribute :api_version, Types::String.default('2019-07')
+      attribute :logger, Types::Logger.default(Logger.new(File::NULL).freeze)
+
+      # The following attributes may be unnecessary in some private apps.
+      attribute? :api_key, Types::String
+      attribute? :billing_callback_uri, Types::String
+      attribute? :callback_uri, Types::String
+      attribute? :scope, Types::String
+      attribute? :shared_secret, Types::String
+      attribute? :webhook_uri, Types::String
+    end
+
+    self.configure
+  end
+end

data/lib/lucid/shopify/container.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'dry/container'
+require 'http'
+
+require 'lucid/shopify'
+require 'lucid/shopify/config'
+
+module Lucid
+  module Shopify
+    Container = Dry::Container.new
+
+    # Services only (dependencies); no value objects, entities.
+    Container.register(:activate_charge) { ActivateCharge.new }
+    Container.register(:authorise) { Authorise.new }
+    Container.register(:client) { Client.new }
+    Container.register(:create_all_webhooks) { CreateAllWebhooks.new }
+    Container.register(:create_charge) { CreateCharge.new }
+    Container.register(:create_webhook) { CreateWebhook.new }
+    Container.register(:delete_all_webhooks) { DeleteAllWebhooks.new }
+    Container.register(:delete_webhook) { DeleteWebhook.new }
+    Container.register(:http) { ::HTTP::Client.new }
+    Container.register(:send_request) { SendRequest.new }
+    Container.register(:send_throttled_request) do
+      if defined?(Redis)
+        SendRequest.new(strategy: RedisThrottledStrategy.new)
+      else
+        SendRequest.new(strategy: ThrottledStrategy.new)
+      end
+    end
+    Container.register(:verify_callback) { VerifyCallback.new }
+    Container.register(:verify_webhook) { VerifyWebhook.new }
+    Container.register(:webhook_handler_list) { Shopify.handlers }
+    Container.register(:webhook_list) { Shopify.webhooks }
+  end
+end

data/lib/lucid/shopify/create_all_webhooks.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class CreateAllWebhooks
+      # @param create_webhook [#call]
+      def initialize(create_webhook: Container[:create_webhook])
+        @create_webhook = create_webhook
+      end
+
+      # Create all webhooks for the shop. Shopify ignores any webhooks which
+      # already exist remotely.
+      #
+      # @param credentials [Credentials]
+      # @param webhooks [WebhookList]
+      #
+      # @return [Array<Hash>] response data
+      def call(credentials, webhooks: Container[:webhook_list])
+        webhooks.map do |webhook|
+          Thread.new { @create_webhook.(credentials, webhook) }
+        end.map(&:value)
+      end
+    end
+  end
+end

data/lib/lucid/shopify/create_charge.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class CreateCharge
+      # @param client [#post_json]
+      def initialize(client: Container[:client])
+        @client = client
+      end
+
+      # Create a new recurring application charge.
+      #
+      # @param credentials [Credentials]
+      # @param charge [Hash]
+      #
+      # @return [Hash] the pending charge
+      def call(credentials, charge)
+        data = @client.post_json(credentials, 'recurring_application_charges', post_data(charge))
+
+        data['recurring_application_charge']
+      end
+
+      # @param charge [Hash]
+      #
+      # @return [Hash]
+      private def post_data(charge)
+        {
+          'recurring_application_charge' => {
+            'return_url' => Shopify.config.billing_callback_uri
+          }.merge(charge.transform_keys(&:to_s)),
+        }
+      end
+    end
+  end
+end

data/lib/lucid/shopify/create_webhook.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class CreateWebhook
+      # @param client [#post_json]
+      def initialize(client: Container[:client])
+        @client = client
+      end
+
+      # @param credentials [Credentials]
+      # @param webhook [Hash]
+      #
+      # @return [Hash] response data
+      def call(credentials, webhook)
+        data = {**webhook, address: Shopify.config.webhook_uri}
+
+        @client.post_json(credentials, 'webhooks', webhook: data)
+      end
+    end
+  end
+end

data/lib/lucid/shopify/credentials.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class Credentials
+      extend Dry::Initializer
+
+      # @return [String]
+      param :myshopify_domain
+      # @return [String, nil] if {nil}, request will be unauthorised
+      param :access_token, optional: true
+    end
+  end
+end

data/lib/lucid/shopify/delete_all_webhooks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class DeleteAllWebhooks
+      # @param client [#get]
+      # @param delete_webhook [#call]
+      def initialize(client: Container[:client],
+                     delete_webhook: Container[:delete_webhook])
+        @client = client
+        @delete_webhook = delete_webhook
+      end
+
+      # Delete any existing webhooks.
+      #
+      # @param credentials [Credentials]
+      #
+      # @return [Array<Hash>] response data
+      def call(credentials)
+        webhooks = @client.get(credentials, 'webhooks')['webhooks']
+
+        webhooks.map do |webhook|
+          Thread.new { @delete_webhook.(credentials, webhook['id']) }
+        end.map(&:value)
+      end
+    end
+  end
+end

data/lib/lucid/shopify/delete_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class DeleteRequest < Request
+      # @private
+      #
+      # @param credentials [Credentials]
+      # @param path [String] the endpoint relative to the base URL
+      def initialize(credentials, path)
+        super(credentials, :delete, path)
+      end
+    end
+  end
+end

data/lib/lucid/shopify/delete_webhook.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify/container'
+
+module Lucid
+  module Shopify
+    class DeleteWebhook
+      # @param client [#delete]
+      def initialize(client: Container[:client])
+        @client = client
+      end
+
+      # @param credentials [Credentials]
+      # @param id [Integer]
+      #
+      # @return [Hash] response data
+      def call(credentials, id)
+        @client.delete(credentials, "webhooks/#{id}")
+      end
+    end
+  end
+end

data/lib/lucid/shopify/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Lucid
+  module Shopify
+    # Subclass this class for all gem exceptions, so that callers may rescue
+    # any subclass with:
+    #
+    #     rescue Lucid::Shopify::Error => e
+    Error = Class.new(StandardError)
+  end
+end

data/lib/lucid/shopify/get_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class GetRequest < Request
+      # @private
+      #
+      # @param credentials [Credentials]
+      # @param path [String] the endpoint relative to the base URL
+      # @param params [Hash] the query params
+      def initialize(credentials, path, params = {})
+        super(credentials, :get, path, params: params)
+      end
+    end
+  end
+end

data/lib/lucid/shopify/post_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class PostRequest < Request
+      # @private
+      #
+      # @param credentials [Credentials]
+      # @param path [String] the endpoint relative to the base URL
+      # @param json [Hash] the JSON request body
+      def initialize(credentials, path, json)
+        super(credentials, :post, path, json: json)
+      end
+    end
+  end
+end

data/lib/lucid/shopify/put_request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'lucid/shopify'
+
+module Lucid
+  module Shopify
+    class PutRequest < Request
+      # @private
+      #
+      # @param credentials [Credentials]
+      # @param path [String] the endpoint relative to the base URL
+      # @param json [Hash] the JSON request body
+      def initialize(credentials, path, json)
+        super(credentials, :put, path, json: json)
+      end
+    end
+  end
+end