reuters 0.8.1

data/lib/reuters/builder.rb

@@ -0,0 +1,117 @@
+module Reuters
+  # This class enables the rapid and relatively painless
+  # construction of the body of Reuters API calls.
+  #
+  # It extends the Hash class, which means that it is
+  # compatible with the Savon request call and includes
+  # all the basic functionality of a Hash.
+  #
+  # @note This class is documented with worked examples
+  #  on the main README file.
+  #
+  # @see http://savonrb.com/version2/requests.html
+  class Builder < Hash
+
+    def initialize(body = {}, &block)
+      self[:attributes!] = {}
+      attributes body
+      block.call(self) if block
+    end
+
+    # Assign element attributes to a specific key inside
+    # the hash. All attributes are assigned to the
+    # 'hidden' :attributes! key.
+    #
+    # @example Adding an attribute
+    #   req = Reuters::Builder.new
+    #   req.attributes(exchange_code: { id: 123 })
+    #
+    # @param [Hash] attribs to add to the attributes! key.
+    # @param [Boolean] camelcase the keys inside the hash?
+    #
+    # @return [Hash] the resulting hash that was added.
+    def attributes(attribs, camelcase = true)
+      camelize_keys(attribs).each do |key, value|
+        hash = camelcase ? camelize_keys(value) : value
+        self[:attributes!][key] ||= {}
+        self[:attributes!][key].merge! hash
+      end
+    end
+
+    # Uses the name of the missing method and adds it
+    # as a new key inside this hash. If the method
+    # is called as an assignment, the value will be
+    # set to the element, otherwise a nested {Builder}
+    # is returned.
+    def method_missing(name, body = nil, camelcase = true, &block)
+      key = camelize name
+
+      if name.match(/\=$/)
+        assign_val(key, body)
+      else
+        assign_body(key, body, camelcase)
+      end
+
+      self[key] ||= Reuters::Builder.new(&block) if block
+      self[key] ||= Reuters::Builder.new
+
+    end
+
+    # Return all keys inside this Hash object except
+    # for the :attributes! key. This key is hidden
+    # so that it cannot be mistaken for an XML Element.
+    #
+    # @return [Array] All keys except for :attributes!
+    #   which will always exist.
+    def keys
+      super - [:attributes!]
+    end
+
+    # Attempts to find a key that exists in the hash.
+    # If the key cannot be found in its current format,
+    # the method attempts to camelcase the key and
+    # search again.
+    #
+    # @return [Boolean] True if the key exists, false otherwise.
+    def key?(key)
+      super || super(camelize(key))
+    end
+
+    private
+
+    def assign_val(key, body)
+      self[key] = body
+    end
+
+    def assign_body(key, body, camelcase = true)
+      case body
+      when Hash
+        attributes({ key => body }, camelcase)
+      when Array
+        self[key] ||= Array.new(body.count) { '' }
+        attributes(key => order_attributes(body))
+      end
+    end
+
+    def order_attributes(attribs)
+      keys = attribs.map(&:keys).flatten.uniq
+      ordered = {}
+      keys.each do |k|
+        ordered[k] = []
+        attribs.each { |a| ordered[k] << (a[k].to_s || '') }
+      end
+      ordered
+    end
+
+    def camelize(key)
+      key.to_s.camelize.gsub(/[^a-z0-9]/i, '')
+    end
+
+    def camelize_keys(hash)
+      new_hash = {}
+      hash.each { |key, val| new_hash[camelize key] = val }
+      new_hash
+    end
+
+  end
+end

data/lib/reuters/client.rb

@@ -0,0 +1,12 @@
+require 'reuters/client/base'
+require 'reuters/client/token'
+require 'reuters/client/fundamentals'
+require 'reuters/client/search'
+
+module Reuters
+  # Main client for the Reuters Gem. The Client module wraps
+  # all different types of Clients for retrieving data from the
+  # Reuter's API.
+  module Client
+  end
+end

data/lib/reuters/client/base.rb

@@ -0,0 +1,132 @@
+module Reuters
+  module Client
+    # The base class for the client is not meant to be directly
+    # initialized but instead contains common functionality
+    # shared by most classes inside the Client.
+    #
+    # This class also handles authenticating the user with the
+    # Reuter's API and handling the resulting token provided.
+    class Base
+
+      delegate :operations, to: :client
+
+      delegate :app_id, :token, :header, to: :@token
+
+      # Initialize the base client class and set a token
+      # that can be retrieved upon request.
+      def initialize
+        @wsdl = Reuters::Wsdls.const_get client_name
+        @namespace = Reuters::Namespaces.const_get client_name
+        @token = Reuters::Client::Token.new
+      end
+
+      # Retrieves a new instance of a Savon client that
+      # has been correctly configured for sending requests
+      # to the Reuter's API.
+      #
+      # @see http://savonrb.com/version2/client.html
+      #
+      # @return [Object] client to make requests through.
+      def client
+        Savon.client options
+      end
+
+      # Attempts to call an operation for this client through
+      # the determined set of operations that have been retrieved
+      # from the WSDL.
+      def method_missing(op, *args)
+        if client.operations.include?(op)
+          request op, *args
+        else
+          fail NoMethodError, op
+        end
+      end
+
+      # Send a correctly formatted request to the Reuter's
+      # API. This method makes an authenticated request to
+      # the API, assuming that a token object has been defined
+      # by the extending Class.
+      #
+      # @note This request method calls the Savon Client #call
+      #   method.
+      #
+      # @see http://savonrb.com/version2/requests.html
+      #
+      # @param [Symbol] type of request to send to Reuters API.
+      # @param [Reuters::Builder] message contents to send to the API.
+      # @param [Hash] attribs to attach to the request object.
+      # @param [Boolean] auth defaults to true if a token is required
+      #                  for this request
+      #
+      # @return [Object] The corresponding Response object.
+      def request(type, message, attribs = {}, auth = true)
+
+        content = {
+          attributes: attribs.merge('xmlns' => @namespace.endpoint),
+          message: before_request.call(message, type)
+        }
+
+        content[:soap_header] = header if auth
+
+        data = client.call(type, content).body
+
+        Reuters::Response.new after_request.call(data[data.keys.first])
+
+      end
+
+      # Yields a block that is called before a request
+      # is sent to Savon. The hash that is returned from
+      # this block is used as the message part of the
+      # Savon request.
+      #
+      # @note By default this request hook has no effect.
+      #
+      # @yield [req, type] The request object that has been
+      #  sent to the client. The operation name is passed
+      #  as the second parameter.
+      #
+      # @yieldparam req [Reuters::Builder] The request object.
+      # @yieldparam type [Symbol] The intended operation to perform.
+      def before_request(&block)
+        @before_request = block if block
+        @before_request || proc { |a| a }
+      end
+
+      # Yields a block that is called after a successful
+      # request to Reuters. The object that is returned from
+      # this is request is subsequently passed onto this Clients
+      # corresponding response class.
+      #
+      # @note By default this request hook has no effect.
+      #
+      # @yield [req] The raw response object that
+      #              has been received and parsed by Savon.
+      def after_request(&block)
+        @after_request = block if block
+        @after_request || proc { |a| a }
+      end
+
+      private
+
+      def client_name
+        self.class.name.demodulize
+      end
+
+      def common
+        Reuters::Namespaces::Common
+      end
+
+      def options
+        {
+          wsdl: @wsdl.endpoint,
+          ssl_version: :SSLv3,
+          namespace_identifier: nil,
+          ssl_verify_mode: :none,
+          log: Reuters.debug,
+          pretty_print_xml: true
+        }
+      end
+
+    end
+  end
+end

data/lib/reuters/client/fundamentals.rb

@@ -0,0 +1,20 @@
+module Reuters
+  module Client
+    # Performs a Fundamentals Reuters API request. Fundamentals
+    # can be used to retrieve snapshot information about a specific
+    # company ID and Ticker.
+    #
+    # @example Making a fundamentals request
+    #   req = Reuters::Client::Fundamentals.new
+    #   msg = Reuters::Builder.new
+    #   puts req.operations #=> [:get_snapshot_reports_1, ...]
+    #   response = req.get_snapshot_reports_1(msg, {
+    #     'companyId' => id,
+    #     'companyIdType' => type,
+    #     'countryCode' => code,
+    #     'includeMedians' => medians
+    #   })
+    class Fundamentals < Base
+    end
+  end
+end

data/lib/reuters/client/search.rb

@@ -0,0 +1,19 @@
+require 'reuters/client/search/base'
+require 'reuters/client/search/equity'
+
+module Reuters
+  module Client
+    # Search is a namespace for sub-clients, such as
+    # Equity-based searches on the Reuters API. This
+    # client cannot be initialized directly.
+    # A specific sub-client should be initialized.
+    #
+    # @note Each client behaves in the same way
+    #  as every other client.
+    #
+    # @example Initializing an Equity Search Client
+    #  cli = Reuters::Client::Search::Equity.new
+    module Search
+    end
+  end
+end

data/lib/reuters/client/search/base.rb

@@ -0,0 +1,26 @@
+module Reuters
+  module Client
+    module Search
+      # The base class for the search client is not meant to be
+      # directly initialized but instead contains common functionality
+      # shared by all Search Clients.
+      class Base < Reuters::Client::Base
+
+        def initialize
+          # Re-define namespace and wsdl to be scoped to search
+          @namespace = Reuters::Namespaces::Search.const_get client_name
+          @wsdl = Reuters::Wsdls::Search.const_get client_name
+          @token = Reuters::Client::Token.new
+        end
+
+        private
+
+        def ns_definition(*args)
+          Reuters::Namespaces::Search.define(*args)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/reuters/client/search/equity.rb

@@ -0,0 +1,64 @@
+module Reuters
+  module Client
+    module Search
+      # Performs a Equity Search Reuters API request. Equity
+      # searches are intended to vary in complexity but allow
+      # you to retrieve financial information about a
+      # company on a specific exchange.
+      #
+      # @note All Equity Search XML Requests require that the
+      #   appropriate xmlns attribute is present on elements
+      #   inside the request element. This class uses the
+      #   before_request hook to inject the appropriate attribute.
+      class Equity < Base
+
+        def initialize
+          # process equity request objects before they are sent.
+          before_request do |req|
+
+            if req.key?(:query_header)
+              req.attributes({ query_header: { 'xmlns' => data_type } }, false)
+            end
+
+            [:filter, :query].each do |section|
+              if req.key?(section)
+
+                sec = req.send(section)
+
+                sec.keys.each do |key|
+                  sec.attributes({ key => { 'xmlns' => query_spec } }, false)
+                  sec[key].keys.each do |type|
+                    sec[key].attributes({ type => { 'xmlns' => data_type } }, false)
+                  end
+                end
+
+              end
+            end
+
+            req
+          end
+
+          super
+        end
+
+        # Retrieve the correctly formatted Namespace Data Type
+        # for an Equity-based Search Reuters Request.
+        #
+        # @return [String] the fully resolved namespace endpoint.
+        def data_type
+          ns_definition(:query_spec_data_types)
+        end
+
+        # Retrieve the correctly formatted Namespace Query
+        # Specification for an Equity-based Search.
+        #
+        # @return [String] the fully resolved namespace endpoint.
+        def query_spec
+          ns_definition(:equity_quote, :query_spec, 1)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/reuters/client/token.rb

@@ -0,0 +1,101 @@
+module Reuters
+  module Client
+    # Retrieves a new Token from the Reuter's API using the
+    # credentials that have been globally configured.
+    #
+    # @example Retrieving a new token
+    #   Reuters::Credentials.configure do |c|
+    #     c.username = 'username'
+    #     c.password = 'pass'
+    #     c.app_id = 'MyAppID'
+    #   end
+    #   authentication = Reuters::Client::Token.new
+    #   authentication.token #=> "raj2ja89djf98aj3jjoadjowajdoiaj"
+    class Token < Base
+
+      # @!attribute [r] token
+      #   The token that has been retrieved from the Reuter's API.
+      #   @return [String, Nil] the token contents, or nil if not set.
+
+      # @!attribute [r] expiration
+      #   The timestamp at which the associated token will expire.
+      #   @return [Integer, Nil] the expiry time of the token,
+      #     or nil if not set.
+
+      # @!attribute [r] username
+      #   The username that will be used to authenticate with
+      #   the Reuter's api.
+      #   @return [String, Nil] the username, or nil if one has
+      #     not been configured.
+
+      # @!attribute [r] password
+      #   The password that will be used to authenticate with
+      #   the Reuter's api.
+      #   @return [String, Nil] the password, or nil if one has
+      #     not been configured.
+
+      # @!attribute [r] app_id
+      #   The application id that will be used to authenticate with
+      #   the Reuter's api.
+      #   @return [String, Nil] the application id, or nil if one has
+      #     not been configured.
+
+      delegate :token, :expiration, to: :current_response
+
+      delegate :username, :password, :app_id, to: :credentials
+
+      # Override {Base} constructor and avoid setting a token
+      # as it will crash the client.
+      def initialize
+        @wsdl = Reuters::Wsdls.const_get client_name
+        @namespace = Reuters::Namespaces.const_get client_name
+      end
+
+      # Build the authentication message that will be sent to Reuters.
+      #
+      # @return [Hash] the contents of the body of the message.
+      def message
+        Reuters::Builder.new do |body|
+          body.application_id = app_id
+          body.username = username
+          body.password = password
+          body.application_id({ xmlns: common.endpoint }, false)
+        end
+      end
+
+      # Authenticates with Reuters and automatically
+      # attempts to retieve a new token from the Reuter's API.
+      #
+      # @return [Token] an initialized instance of {Token}
+      def authenticate
+        @response = create_service_token_1(message, {}, false)
+      end
+
+      def header
+        response = current_response
+        Reuters::Builder.new do |body|
+          body.authorization.application_id = app_id
+          body.authorization.token = response.token
+          body.authorization({ 'xmlns' => common.endpoint }, false)
+        end
+      end
+
+      private
+
+      def credentials
+        Reuters::Credentials
+      end
+
+      def current_response
+        if @response && Time.parse(@response.expiration) > Time.now
+          @response
+        else
+          fail 'Token has expired.'
+        end
+      rescue
+        authenticate
+      end
+
+    end
+  end
+end