oanda_api 0.8.1 → 0.8.3

data/lib/oanda_api/errors.rb

@@ -0,0 +1,4 @@
+module OandaAPI
+  # Errors raised by the client.
+  class RequestError < RuntimeError; end
+end

data/lib/oanda_api/resource/account.rb

@@ -0,0 +1,37 @@
+module OandaAPI
+  # Namespace for all resources.
+  module Resource
+    # Account value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/accounts/ Accounts}.
+    class Account < ResourceBase
+      attr_accessor :account_currency,
+                    :account_id,
+                    :account_name,
+                    :balance,
+                    :margin_available,
+                    :margin_rate,
+                    :margin_used,
+                    :open_orders,
+                    :open_trades,
+                    :password,
+                    :realized_pl,
+                    :unrealized_pl,
+                    :username
+
+      alias_method :id,  :account_id
+      alias_method :id=, :account_id=
+
+      alias_method :currency,  :account_currency
+      alias_method :currency=, :account_currency=
+
+      alias_method :name,  :account_name
+      alias_method :name=, :account_name=
+
+      def initialize(attributes = {})
+        @open_orders = []
+        @open_trades = []
+        super
+      end
+    end
+  end
+end

data/lib/oanda_api/resource/candle.rb

@@ -0,0 +1,29 @@
+module OandaAPI
+  module Resource
+    # Candle value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/rates/#retrieveInstrumentHistory Candles}.
+    class Candle < ResourceBase
+      attr_accessor :close_ask,
+                    :close_bid,
+                    :close_mid,
+                    :complete,
+                    :high_ask,
+                    :high_bid,
+                    :high_mid,
+                    :low_ask,
+                    :low_bid,
+                    :low_mid,
+                    :open_ask,
+                    :open_bid,
+                    :open_mid,
+                    :time,
+                    :volume
+
+      alias_method :complete?, :complete
+
+      def time=(v)
+        @time = Time.parse v.to_s
+      end
+    end
+  end
+end

data/lib/oanda_api/resource/instrument.rb

@@ -0,0 +1,21 @@
+module OandaAPI
+  module Resource
+    # Instrument value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/rates/#getInstrumentList Instruments}.
+    class Instrument < ResourceBase
+      attr_accessor :display_name,
+                    :halted,
+                    :instrument,
+                    :margin_rate,
+                    :max_trade_units,
+                    :max_trailing_stop,
+                    :min_trailing_stop,
+                    :pip,
+                    :precision
+
+      alias_method :halted?, :halted
+      alias_method :name, :instrument
+      alias_method :name=, :instrument=
+    end
+  end
+end

data/lib/oanda_api/resource/order.rb

@@ -0,0 +1,74 @@
+module OandaAPI
+  module Resource
+    # Order value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/orders/ Orders}.
+    class Order < ResourceBase
+      attr_accessor :expiry,
+                    :id,
+                    :instrument,
+                    :lower_bound,
+                    :order_opened,
+                    :price,
+                    :side,
+                    :stop_loss,
+                    :take_profit,
+                    :time,
+                    :trades_closed,
+                    :trade_opened,
+                    :trade_reduced,
+                    :trailing_stop,
+                    :type,
+                    :units,
+                    :upper_bound
+
+      def initialize(attributes = {})
+        attribs = attributes.dup
+        self.order_opened  = attribs.delete(order_opened)  || {}
+        self.trade_opened  = attribs.delete(trade_opened)  || {}
+        self.trade_reduced = attribs.delete(trade_reduced) || {}
+        self.trades_closed = attribs.delete(trades_closed) || []
+        super attribs
+      end
+
+      def expiry=(v)
+        @expiry = Time.parse v.to_s
+      end
+
+      def time=(v)
+        @time = Time.parse v.to_s
+      end
+
+      def order_opened=(v)
+        @order_opened = OrderOpened.new v
+      end
+
+      def trade_opened=(v)
+        @trade_opened = TradeOpened.new v
+      end
+
+      def trade_reduced=(v)
+        @trade_reduced = TradeReduced.new v
+      end
+
+      # See the Oanda Developer Guide for {http://developer.oanda.com/rest-live/orders/ Order} details.
+      class OrderOpened < ResourceBase
+        attr_accessor :expiry, :id, :lower_bound, :side, :stop_loss,
+                      :take_profit, :trailing_stop, :units, :upper_bound
+
+        def expiry=(v)
+          @expiry = Time.parse v.to_s
+        end
+      end
+
+      # See the Oanda Developer Guide for {http://developer.oanda.com/rest-live/orders/ Order} details.
+      class TradeOpened < ResourceBase
+        attr_accessor :id, :side, :stop_loss, :take_profit, :trailing_stop, :units
+      end
+
+      # See the Oanda Developer Guide for {http://developer.oanda.com/rest-live/orders/ Order} details.
+      class TradeReduced < ResourceBase
+        attr_accessor :id, :interest, :pl, :units
+      end
+    end
+  end
+end

data/lib/oanda_api/resource/position.rb

@@ -0,0 +1,18 @@
+module OandaAPI
+  module Resource
+    # Position value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/positions/ Positions}.
+    class Position < ResourceBase
+      attr_accessor :avg_price,
+                    :ids,
+                    :instrument,
+                    :side,
+                    :total_units
+
+      alias_method :price,  :avg_price
+      alias_method :price=, :avg_price=
+      alias_method :units,  :total_units
+      alias_method :units=, :total_units=
+    end
+  end
+end

data/lib/oanda_api/resource/price.rb

@@ -0,0 +1,16 @@
+module OandaAPI
+  module Resource
+    # Price value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/rates/#getCurrentPrices Prices}.
+    class Price < ResourceBase
+      attr_accessor :ask,
+                    :bid,
+                    :instrument,
+                    :time
+
+      def time=(v)
+        @time = Time.parse v.to_s
+      end
+    end
+  end
+end

data/lib/oanda_api/resource/trade.rb

@@ -0,0 +1,23 @@
+module OandaAPI
+  module Resource
+    # Trade value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/trades/ Trades}.
+    class Trade < ResourceBase
+      attr_accessor :id,
+                    :instrument,
+                    :price,
+                    :profit,
+                    :side,
+                    :stop_loss,
+                    :take_profit,
+                    :time,
+                    :trailing_amount,
+                    :trailing_stop,
+                    :units
+
+      def time=(v)
+        @time = Time.parse v.to_s
+      end
+    end
+  end
+end

data/lib/oanda_api/resource/transaction.rb

@@ -0,0 +1,67 @@
+module OandaAPI
+  module Resource
+    # Transaction value object.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/transaction-history/ Transactions}.
+    class Transaction < ResourceBase
+      attr_accessor :account_balance,
+                    :account_id,
+                    :amount,
+                    :expiry,
+                    :id,
+                    :instrument,
+                    :interest,
+                    :lower_bound,
+                    :margin_rate,
+                    :order_id,
+                    :pl,
+                    :price,
+                    :rate,
+                    :reason,
+                    :side,
+                    :stop_loss_price,
+                    :stop_loss_price,
+                    :take_profit_price,
+                    :time,
+                    :trade_id,
+                    :trade_opened,
+                    :trade_reduced,
+                    :trailing_stop_loss_distance,
+                    :type,
+                    :units,
+                    :upper_bound
+
+      def initialize(attributes = {})
+        attribs = attributes.dup
+        self.trade_opened  = attribs.delete(:trade_opened)  || {}
+        self.trade_reduced = attribs.delete(:trade_reduced) || {}
+        super attribs
+      end
+
+      def expiry=(v)
+        @expiry = Time.parse v.to_s
+      end
+
+      def time=(v)
+        @time = Time.parse v.to_s
+      end
+
+      def trade_opened=(v)
+        @trade_opened = TradeOpened.new v
+      end
+
+      def trade_reduced=(v)
+        @trade_reduced = TradeReduced.new v
+      end
+
+      # See http://developer.oanda.com/rest-live/transaction-history/ for attribute details.
+      class TradeOpened < ResourceBase
+        attr_accessor :id, :units
+      end
+
+      # See http://developer.oanda.com/rest-live/transaction-history/ for attribute details.
+      class TradeReduced < ResourceBase
+        attr_accessor :id, :interest, :pl, :units
+      end
+    end
+  end
+end

data/lib/oanda_api/resource_base.rb

@@ -0,0 +1,35 @@
+module OandaAPI
+  # Base class for all Resources.
+  #
+  # @!attribute [rw] location
+  #   @return [String] the +location+ header if one is returned in an API
+  #     response.
+  #   @example Using the +location+ attribute
+  #      client = OandaAPI::Client::TokenClient.new :practice, token
+  #      all_transactions = client.account(123).alltransactions.get
+  #      all_transactions.location # => https://fxtrade.oanda.com/transactionhistory/d3aed6823c.json.zip
+  class ResourceBase
+    attr_accessor :location
+
+    # @param [Hash] attributes collection of resource attributes. See the
+    #   {http://developer.oanda.com/rest-live/development-guide/ Oanda Developer Guide}
+    #   for documentation about resource attributes.
+    def initialize(attributes = {})
+      initialize_attributes Utils.rubyize_keys(attributes.dup)
+      @location = attributes.location if attributes.respond_to? :location
+    end
+
+    private
+
+    # @private
+    # Initializes attributes.
+    #
+    # @param [Hash] attributes collection of resource attributes.
+    # @return [void]
+    def initialize_attributes(attributes)
+      attributes.each do |key, value|
+        send("#{key}=", value) if respond_to? key
+      end
+    end
+  end
+end

data/lib/oanda_api/resource_collection.rb

@@ -0,0 +1,77 @@
+module OandaAPI
+  # A collection of a specific resource. Returned by API requests that return
+  # collections. See the {http://developer.oanda.com/rest-live/development-guide/ Oanda Development Guide}
+  # for documentation about resource attributes expected for specific requests.
+  #
+  # @example  Getting candle information
+  #   client  = OandaAPI::Client::TokenClient.new :practice, token
+  #   candles = client.candles( instrument: "EUR_USD",
+  #                            granularity: "M1",
+  #                                  count: 1,
+  #                          candle_format: "midpoint" ).get
+  #
+  #   candles              # => OandaAPI::ResourceCollection
+  #   candles.granularity  # => "M1"
+  #   candles.instrument   # => "EUR_USD"
+  #   candles.first        # => OandaAPI::Resource::Candle
+  #
+  # @!attribute [r] location
+  #   @return [String] see {ResourceBase#location}
+  class ResourceCollection
+    include Enumerable
+
+    attr_reader :location
+
+    # @param [Hash] attributes collection of resource attributes
+    #
+    # @param [OandaAPI::Client::ResourceDescriptor] resource_descriptor metadata
+    #   about the resource collection and its elements.
+    def initialize(attributes, resource_descriptor)
+      attributes = {} if attributes.nil? || attributes.respond_to?(:empty) && attributes.empty?
+      fail ArgumentError, "Expecting a Hash" unless attributes.respond_to? :each_pair
+      @attributes = Utils.rubyize_keys attributes
+      @collection = @attributes.delete(resource_descriptor.collection_name) || []
+      @collection.map! { |resource| resource_descriptor.resource_klass.new resource }
+      @location   = attributes.location if attributes.respond_to? :location
+    end
+
+    # @yield [OandaAPI::ResourceBase]
+    # @return [Enumerator]
+    def each
+      if block_given?
+        @collection.each { |el| yield el }
+      else
+        @collection.each
+      end
+    end
+
+    # @private
+    # Responds to collection-scoped accessor methods that are specific to the
+    # type of resource collection. For example, a +Candle+ collection includes
+    # the collection-scoped methods +granularity+ and +instrument+.
+    def method_missing(sym, *args)
+      case
+      when @attributes.keys.include?(sym) 
+        @attributes[sym]
+      when
+        @collection.respond_to?(sym)
+          @collection.send sym
+      else
+        super
+      end
+    end
+
+    # Returns +true+ for concrete, delegated and dynamic methods.
+    # @return [Boolean]
+    def respond_to?(sym)
+      case
+      when @attributes.keys.include?(sym)
+        true
+      when @collection.respond_to?(sym)
+        true
+      else
+        super
+      end
+    end
+  end
+end

data/lib/oanda_api/utils/utils.rb

@@ -0,0 +1,101 @@
+module OandaAPI
+  # A few general purpose useful methods.
+  # Intentionally not implemented as monkey patches.
+  # Some wheel-reinventing to avoid adding extra dependencies.
+  module Utils
+    # Puts camelHumps where you expect them.
+    # @param [String] s
+    # @return [String]
+    def self.camelize(s)
+      s.to_s.gsub(/(?:_)([a-z\d]*)/i) { "#{$1.capitalize}" }.sub(/^(.)/) { $1.downcase }
+    end
+
+    # Naively plops an "s" at the end of a string.
+    # If the string is "" or nil, returns "".
+    # @param [String] s
+    # @return [String]
+    def self.pluralize(s)
+      return "" if s.to_s == ""
+      s.to_s =~ /s$/ ? s.to_s : "#{s}s"
+    end
+
+    # Returns a string with its trailing "s" vaporized.
+    # @param [String] s
+    # @return [String]
+    def self.singularize(s)
+      s.to_s.chomp("s")
+    end
+
+    # Returns a deep copy of a hash with its keys downcased, underscored
+    # and symbolized into ruby sweetness.
+    # @param [Hash] hash
+    # @return [Hash]
+    def self.rubyize_keys(hash)
+      transform_hash_keys(hash) { |key| underscore(key).to_sym }
+    end
+
+    # Returns a deep copy of a hash with its keys camelized,
+    # underscored and symbolized.
+    # @param [Hash] hash
+    # @return [Hash]
+    def self.stringify_keys(hash)
+      transform_hash_keys(hash) { |key| camelize key }
+    end
+
+    # Yields all keys of a hash, and safely applies whatever transform
+    # the block provides. Supports nested hashes.
+    #
+    # @param [Object] value can be a +Hash+, an +Array+ or scalar object type.
+    #
+    # @param [Block] block transforms the yielded key.
+    #
+    # @yield [Object] key the key to be prettied up.
+    #
+    # @return [Hash] a deep copy of the hash with it's keys transformed
+    #   according to the design of the block.
+    def self.transform_hash_keys(value, &block)
+      case
+      when value.is_a?(Array)
+        value.map { |v| transform_hash_keys(v, &block) }
+      when value.is_a?(Hash)
+        Hash[value.map { |k, v| [yield(k), transform_hash_keys(v, &block)] }]
+      else
+        value
+      end
+    end
+
+    # Yields all key/value pairs of a hash, and safely applies whatever
+    # transform the block provides to the values.
+    # Supports nested hashes and arrays.
+    #
+    # @param [Object] value can be a +Hash+, an +Array+ or scalar object type.
+    #
+    # @param [Object] key
+    #
+    # @param [Block] block transforms the yielded value.
+    #
+    # @return [Hash] a deep copy of the hash with it's values transformed
+    #   according to the design of the block.
+    def self.transform_hash_values(value, key = nil, &block)
+      case
+      when value.is_a?(Array)
+        value.map { |v| transform_hash_values(v, key, &block) }
+      when value.is_a?(Hash)
+        Hash[value.map { |k, v| [k, transform_hash_values(v, k, &block)] }]
+      else
+        yield key, value
+      end
+    end
+
+    # Converts a string from camelCase to snake_case.
+    # @param [String] s
+    # @return [String]
+    def self.underscore(s)
+      s.to_s
+       .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+       .tr("-", "_")
+       .downcase
+    end
+  end
+end