helio-ruby 0.1.0

data/lib/helio-ruby.rb

@@ -0,0 +1,185 @@
+# Helio Ruby bindings
+# API spec at https://helio.zurb.com
+require "cgi"
+require "faraday"
+require "json"
+require "logger"
+require "openssl"
+require "rbconfig"
+require "securerandom"
+require "set"
+require "socket"
+require "uri"
+
+# Version
+require "helio/version"
+
+# API operations
+require "helio/api_operations/create"
+require "helio/api_operations/delete"
+require "helio/api_operations/list"
+require "helio/api_operations/nested_resource"
+require "helio/api_operations/request"
+require "helio/api_operations/save"
+
+# API resource support classes
+require "helio/errors"
+require "helio/util"
+require "helio/helio_client"
+require "helio/helio_object"
+require "helio/helio_response"
+require "helio/list_object"
+require "helio/api_resource"
+require "helio/singleton_api_resource"
+
+# Named API resources
+require "helio/customer_list"
+require "helio/participant"
+
+module Helio
+  DEFAULT_CA_BUNDLE_PATH = File.dirname(__FILE__) + "/data/ca-certificates.crt"
+
+  @app_info = nil
+
+  @api_base = "http://api.helio.test/public"
+
+  @log_level = nil
+  @logger = nil
+
+  @max_network_retries = 0
+  @max_network_retry_delay = 2
+  @initial_network_retry_delay = 0.5
+
+  @ca_bundle_path = DEFAULT_CA_BUNDLE_PATH
+  @ca_store = nil
+  @verify_ssl_certs = true
+
+  @open_timeout = 30
+  @read_timeout = 80
+
+  class << self
+    attr_accessor :api_id, :api_token, :api_base, :verify_ssl_certs, :api_version, :client_id,
+                  :open_timeout, :read_timeout
+
+    attr_reader :max_network_retry_delay, :initial_network_retry_delay
+  end
+
+  # Gets the application for a plugin that's identified some. See
+  # #set_app_info.
+  def self.app_info
+    @app_info
+  end
+
+  def self.app_info=(info)
+    @app_info = info
+  end
+
+  # The location of a file containing a bundle of CA certificates. By default
+  # the library will use an included bundle that can successfully validate
+  # Helio certificates.
+  def self.ca_bundle_path
+    @ca_bundle_path
+  end
+
+  def self.ca_bundle_path=(path)
+    @ca_bundle_path = path
+
+    # empty this field so a new store is initialized
+    @ca_store = nil
+  end
+
+  # A certificate store initialized from the the bundle in #ca_bundle_path and
+  # which is used to validate TLS on every request.
+  #
+  # This was added to the give the gem "pseudo thread safety" in that it seems
+  # when initiating many parallel requests marshaling the certificate store is
+  # the most likely point of failure (see issue #382). Any program attempting
+  # to leverage this pseudo safety should make a call to this method (i.e.
+  # `Helio.ca_store`) in their initialization code because it marshals lazily
+  # and is itself not thread safe.
+  def self.ca_store
+    @ca_store ||= begin
+      store = OpenSSL::X509::Store.new
+      store.add_file(ca_bundle_path)
+      store
+    end
+  end
+
+  # map to the same values as the standard library's logger
+  LEVEL_DEBUG = Logger::DEBUG
+  LEVEL_ERROR = Logger::ERROR
+  LEVEL_INFO = Logger::INFO
+
+  # When set prompts the library to log some extra information to $stdout and
+  # $stderr about what it's doing. For example, it'll produce information about
+  # requests, responses, and errors that are received. Valid log levels are
+  # `debug` and `info`, with `debug` being a little more verbose in places.
+  #
+  # Use of this configuration is only useful when `.logger` is _not_ set. When
+  # it is, the decision what levels to print is entirely deferred to the logger.
+  def self.log_level
+    @log_level
+  end
+
+  def self.log_level=(val)
+    # Backwards compatibility for values that we briefly allowed
+    if val == "debug"
+      val = LEVEL_DEBUG
+    elsif val == "info"
+      val = LEVEL_INFO
+    end
+
+    if !val.nil? && ![LEVEL_DEBUG, LEVEL_ERROR, LEVEL_INFO].include?(val)
+      raise ArgumentError, "log_level should only be set to `nil`, `debug` or `info`"
+    end
+    @log_level = val
+  end
+
+  # Sets a logger to which logging output will be sent. The logger should
+  # support the same interface as the `Logger` class that's part of Ruby's
+  # standard library (hint, anything in `Rails.logger` will likely be
+  # suitable).
+  #
+  # If `.logger` is set, the value of `.log_level` is ignored. The decision on
+  # what levels to print is entirely deferred to the logger.
+  def self.logger
+    @logger
+  end
+
+  def self.logger=(val)
+    @logger = val
+  end
+
+  def self.max_network_retries
+    @max_network_retries
+  end
+
+  def self.max_network_retries=(val)
+    @max_network_retries = val.to_i
+  end
+
+  # Sets some basic information about the running application that's sent along
+  # with API requests. Useful for plugin authors to identify their plugin when
+  # communicating with Helio.
+  #
+  # Takes a name and optional version and plugin URL.
+  def self.set_app_info(name, version: nil, url: nil)
+    @app_info = {
+      name: name,
+      url: url,
+      version: version,
+    }
+  end
+
+  # DEPRECATED. Use `Util#encode_parameters` instead.
+  def self.uri_encode(params)
+    Util.encode_parameters(params)
+  end
+  private_class_method :uri_encode
+  class << self
+    extend Gem::Deprecate
+    deprecate :uri_encode, "Helio::Util#encode_parameters", 2016, 1
+  end
+end
+
+Helio.log_level = ENV["HELIO_LOG"] unless ENV["HELIO_LOG"].nil?

data/lib/helio/api_operations/create.rb

@@ -0,0 +1,10 @@
+module Helio
+  module APIOperations
+    module Create
+      def create(params = {}, opts = {})
+        resp, opts = request(:post, resource_url, params, opts)
+        Util.convert_to_helio_object(resp.data, opts)
+      end
+    end
+  end
+end

data/lib/helio/api_operations/delete.rb

@@ -0,0 +1,11 @@
+module Helio
+  module APIOperations
+    module Delete
+      def delete(params = {}, opts = {})
+        opts = Util.normalize_opts(opts)
+        resp, opts = request(:delete, resource_url, params, opts)
+        initialize_from(resp.data, opts)
+      end
+    end
+  end
+end

data/lib/helio/api_operations/list.rb

@@ -0,0 +1,28 @@
+module Helio
+  module APIOperations
+    module List
+      def list(filters = {}, opts = {})
+        opts = Util.normalize_opts(opts)
+
+        resp, opts = request(:get, resource_url, filters, opts)
+        obj = ListObject.construct_from(resp.data, opts)
+
+        # set filters so that we can fetch the same limit, expansions, and
+        # predicates when accessing the next and previous pages
+        #
+        # just for general cleanliness, remove any paging options
+        obj.filters = filters.dup
+        obj.filters.delete(:ending_before)
+        obj.filters.delete(:starting_after)
+
+        obj
+      end
+
+      # The original version of #list was given the somewhat unfortunate name of
+      # #all, and this alias allows us to maintain backward compatibility (the
+      # choice was somewhat misleading in the way that it only returned a single
+      # page rather than all objects).
+      alias all list
+    end
+  end
+end

data/lib/helio/api_operations/nested_resource.rb

@@ -0,0 +1,61 @@
+module Helio
+  module APIOperations
+    # Adds methods to help manipulate a subresource from its parent resource so
+    # that it's possible to do so from a static context (i.e. without a
+    # pre-existing collection of subresources on the parent).
+    #
+    # For examle, a transfer gains the static methods for reversals so that the
+    # methods `.create_reversal`, `.retrieve_reversal`, `.update_reversal`,
+    # etc. all become available.
+    module NestedResource
+      def nested_resource_class_methods(resource, path: nil, operations: nil)
+        path ||= "#{resource}s"
+        raise ArgumentError, "operations array required" if operations.nil?
+
+        resource_url_method = :"#{resource}s_url"
+        define_singleton_method(resource_url_method) do |id, nested_id = nil|
+          url = "#{resource_url}/#{CGI.escape(id)}/#{CGI.escape(path)}"
+          url += "/#{CGI.escape(nested_id)}" unless nested_id.nil?
+          url
+        end
+
+        operations.each do |operation|
+          case operation
+          when :create
+            define_singleton_method(:"create_#{resource}") do |id, params = {}, opts = {}|
+              url = send(resource_url_method, id)
+              resp, opts = request(:post, url, params, opts)
+              Util.convert_to_helio_object(resp.data, opts)
+            end
+          when :retrieve
+            define_singleton_method(:"retrieve_#{resource}") do |id, nested_id, opts = {}|
+              url = send(resource_url_method, id, nested_id)
+              resp, opts = request(:get, url, {}, opts)
+              Util.convert_to_helio_object(resp.data, opts)
+            end
+          when :update
+            define_singleton_method(:"update_#{resource}") do |id, nested_id, params = {}, opts = {}|
+              url = send(resource_url_method, id, nested_id)
+              resp, opts = request(:post, url, params, opts)
+              Util.convert_to_helio_object(resp.data, opts)
+            end
+          when :delete
+            define_singleton_method(:"delete_#{resource}") do |id, nested_id, params = {}, opts = {}|
+              url = send(resource_url_method, id, nested_id)
+              resp, opts = request(:delete, url, params, opts)
+              Util.convert_to_helio_object(resp.data, opts)
+            end
+          when :list
+            define_singleton_method(:"list_#{resource}s") do |id, params = {}, opts = {}|
+              url = send(resource_url_method, id)
+              resp, opts = request(:get, url, params, opts)
+              Util.convert_to_helio_object(resp.data, opts)
+            end
+          else
+            raise ArgumentError, "Unknown operation: #{operation.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/helio/api_operations/request.rb

@@ -0,0 +1,55 @@
+module Helio
+  module APIOperations
+    module Request
+      module ClassMethods
+        def request(method, url, params = {}, opts = {})
+          warn_on_opts_in_params(params)
+
+          opts = Util.normalize_opts(opts)
+          opts[:client] ||= HelioClient.active_client
+
+          headers = opts.clone
+          api_token = headers.delete(:api_token)
+          api_base = headers.delete(:api_base)
+          client = headers.delete(:client)
+          # Assume all remaining opts must be headers
+
+          resp, opts[:api_token] = client.execute_request(
+            method, url,
+            api_base: api_base, api_token: api_token,
+            headers: headers, params: params
+          )
+
+          # Hash#select returns an array before 1.9
+          opts_to_persist = {}
+          opts.each do |k, v|
+            opts_to_persist[k] = v if Util::OPTS_PERSISTABLE.include?(k)
+          end
+
+          [resp, opts_to_persist]
+        end
+
+        private
+
+        def warn_on_opts_in_params(params)
+          Util::OPTS_USER_SPECIFIED.each do |opt|
+            if params.key?(opt)
+              $stderr.puts("WARNING: #{opt} should be in opts instead of params.")
+            end
+          end
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      protected
+
+      def request(method, url, params = {}, opts = {})
+        opts = @opts.merge(Util.normalize_opts(opts))
+        self.class.request(method, url, params, opts)
+      end
+    end
+  end
+end

data/lib/helio/api_operations/save.rb

@@ -0,0 +1,85 @@
+module Helio
+  module APIOperations
+    module Save
+      module ClassMethods
+        # Updates an API resource
+        #
+        # Updates the identified resource with the passed in parameters.
+        #
+        # ==== Attributes
+        #
+        # * +id+ - ID of the resource to update.
+        # * +params+ - A hash of parameters to pass to the API
+        # * +opts+ - A Hash of additional options (separate from the params /
+        #   object values) to be added to the request. E.g. to allow for an
+        #   idempotency_key to be passed in the request headers, or for the
+        #   api_token to be overwritten. See {APIOperations::Request.request}.
+        def update(id, params = {}, opts = {})
+          params.each_key do |k|
+            if protected_fields.include?(k)
+              raise ArgumentError, "Cannot update protected field: #{k}"
+            end
+          end
+
+          resp, opts = request(:post, "#{resource_url}/#{id}", params, opts)
+          Util.convert_to_helio_object(resp.data, opts)
+        end
+      end
+
+      # Creates or updates an API resource.
+      #
+      # If the resource doesn't yet have an assigned ID and the resource is one
+      # that can be created, then the method attempts to create the resource.
+      # The resource is updated otherwise.
+      #
+      # ==== Attributes
+      #
+      # * +params+ - Overrides any parameters in the resource's serialized data
+      #   and includes them in the create or update. If +:req_url:+ is included
+      #   in the list, it overrides the update URL used for the create or
+      #   update.
+      # * +opts+ - A Hash of additional options (separate from the params /
+      #   object values) to be added to the request. E.g. to allow for an
+      #   idempotency_key to be passed in the request headers, or for the
+      #   api_token to be overwritten. See {APIOperations::Request.request}.
+      def save(params = {}, opts = {})
+        # We started unintentionally (sort of) allowing attributes sent to
+        # +save+ to override values used during the update. So as not to break
+        # the API, this makes that official here.
+        update_attributes(params)
+
+        # Now remove any parameters that look like object attributes.
+        params = params.reject { |k, _| respond_to?(k) }
+
+        values = serialize_params(self).merge(params)
+
+        # note that id gets removed here our call to #url above has already
+        # generated a uri for this object with an identifier baked in
+        values.delete(:id)
+
+        resp, opts = request(:post, save_url, values, opts)
+        initialize_from(resp.data, opts)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      private
+
+      def save_url
+        # This switch essentially allows us "upsert"-like functionality. If the
+        # API resource doesn't have an ID set (suggesting that it's new) and
+        # its class responds to .create (which comes from
+        # Helio::APIOperations::Create), then use the URL to create a new
+        # resource. Otherwise, generate a URL based on the object's identifier
+        # for a normal update.
+        if self[:id].nil? && self.class.respond_to?(:create)
+          self.class.resource_url
+        else
+          resource_url
+        end
+      end
+    end
+  end
+end

data/lib/helio/api_resource.rb

@@ -0,0 +1,67 @@
+module Helio
+  class APIResource < HelioObject
+    include Helio::APIOperations::Request
+
+    # A flag that can be set a behavior that will cause this resource to be
+    # encoded and sent up along with an update of its parent resource. This is
+    # usually not desirable because resources are updated individually on their
+    # own endpoints, but there are certain cases, replacing a customer's source
+    # for example, where this is allowed.
+    attr_accessor :save_with_parent
+
+    def self.class_name
+      name.split("::")[-1]
+    end
+
+    def self.resource_url
+      if self == APIResource
+        raise NotImplementedError, "APIResource is an abstract class.  You should perform actions on its subclasses (Charge, Customer, etc.)"
+      end
+      resource_path = class_name.gsub(/([^\^])([A-Z])/,'\1_\2').downcase
+      "/#{CGI.escape(resource_path)}s"
+    end
+
+    # A metaprogramming call that specifies that a field of a resource can be
+    # its own type of API resource (say a nested card under an account for
+    # example), and if that resource is set, it should be transmitted to the
+    # API on a create or update. Doing so is not the default behavior because
+    # API resources should normally be persisted on their own RESTful
+    # endpoints.
+    def self.save_nested_resource(name)
+      define_method(:"#{name}=") do |value|
+        super(value)
+
+        # The parent setter will perform certain useful operations like
+        # converting to an APIResource if appropriate. Refresh our argument
+        # value to whatever it mutated to.
+        value = send(name)
+
+        # Note that the value may be subresource, but could also be a scalar
+        # (like a tokenized card's ID for example), so we check the type before
+        # setting #save_with_parent here.
+        value.save_with_parent = true if value.is_a?(APIResource)
+
+        value
+      end
+    end
+
+    def resource_url
+      unless (id = self["id"])
+        raise InvalidRequestError.new("Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}", "id")
+      end
+      "#{self.class.resource_url}/#{CGI.escape(id)}"
+    end
+
+    def refresh
+      resp, opts = request(:get, resource_url, @retrieve_params)
+      initialize_from(resp.data, opts)
+    end
+
+    def self.retrieve(id, opts = {})
+      opts = Util.normalize_opts(opts)
+      instance = new(id, opts)
+      instance.refresh
+      instance
+    end
+  end
+end