oanda_api 0.8.3 → 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2c7acc3d30cf5e19c55528d74251a43ad5e6387c
+  data.tar.gz: 6bb298acd99fb97dd08d82d86455e910694e56cc
+SHA512:
+  metadata.gz: f44a232f8c05ee18ec10b8a0e98cba28d865e8533ba2b0efdf7eca8e87936a5e9fadbc2ee49c56a5916f81b7d7063d8dbf9b9371c87d920a7d7f36992bac8f8b
+  data.tar.gz: 63c786402973185453b85fee525936234ac690a49b5119922dfbebb6fc4613512f36cdbe5cfc0bc5d883e2fafec20cf29bd8ea3f19d20fffe6b11e0305d25b7b

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+## 0.90
+
+ * Add support for live [Streaming](http://developer.oanda.com/rest-live/streaming/).
+ * Add #to_json serialization to resource classes.
+ * fixed Yardoc formatting.
+
+###What's New?
+OandaAPI now supports Oanda's streaming API for consuming realtime ticks and account transactions. See the example in the README and have a look at the specs for `OandaAPI::Streaming::Client`. 
+ 

data/Gemfile

@@ -4,6 +4,9 @@ gemspec
 
 group :development do
   gem "pry"
+  gem 'pry-stack_explorer'
+  gem 'pry-byebug'
+
   gem "guard"
   gem "guard-rspec"
   gem "fuubar"
@@ -11,3 +14,5 @@ group :development do
   gem "github-markup"
   gem "rubocop", require: false
 end
+
+gem 'simplecov', :require => false, :group => :test

data/README.md

@@ -12,7 +12,7 @@ client = OandaAPI::Client::TokenClient.new(:practice, "practice_account_token")
 account = client.account(12345).get 
 ```
 
-returns an OandaAPI::Resource::Account, with method accessors for all of the [Account](http://developer.oanda.com/rest-live/accounts/) attributes defined by the Oanda API.
+returns an `OandaAPI::Resource::Account`, with method accessors for all of the [Account](http://developer.oanda.com/rest-live/accounts/) attributes defined by the Oanda API.
 
 
 ## Features
@@ -34,7 +34,7 @@ Some Examples
 ```ruby
 require 'oanda_api'
 
-client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+client = OandaAPI::Client::TokenClient.new(:practice, ENV.fetch("OANDA_PRACTICE_TOKEN"))
 
 prices = client.prices(instruments: %w(EUR_USD USD_JPY)).get
 
@@ -50,7 +50,7 @@ end
 ```ruby
 require 'oanda_api'
 
-client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+client = OandaAPI::Client::TokenClient.new(:practice, ENV.fetch("OANDA_PRACTICE_TOKEN"))
 
 candles = client.candles( instrument: "EUR_USD",
                          granularity: "M1",
@@ -78,7 +78,7 @@ end
 ```ruby
 require 'oanda_api'
 
-client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+client = OandaAPI::Client::TokenClient.new(:practice, ENV.fetch("OANDA_PRACTICE_TOKEN"))
 
 order = client.account(12345)
               .order(instrument: "USD_JPY", 
@@ -96,7 +96,7 @@ order.trade_opened.id  # => 175491416
 ```ruby
 require 'oanda_api'
 
-client = OandaAPI::Client::TokenClient.new(:practice, ENV["practice_account_token"])
+client = OandaAPI::Client::TokenClient.new(:practice, ENV.fetch("OANDA_PRACTICE_TOKEN"))
 
 account = client.account(12345)             # => OandaAPI::NamespaceProxy
 position = account.position("USD_JPY").get  # => OandaAPI::Resource::Position
@@ -118,6 +118,24 @@ transaction.time        # => 2014-12-19 03:29:48 UTC
 transaction.type        # => "MARKET_ORDER_CREATE"
 ```
 
+##Streaming
+OandaAPI also supports the [Oanda realtime streaming API](http://developer.oanda.com/rest-live/streaming/).
+
+For example to stream live prices,
+
+```ruby
+client = OandaAPI::Streaming::Client.new(:practice, ENV.fetch("OANDA_PRACTICE_TOKEN")) 
+prices = client.prices(account_id: 1234, instruments: %w[AUD_CAD AUD_CHF])
+prices.stream do |price|
+  # Note: The code in this block should handle the price
+  #       as efficently as possible, otherwise the connection could timeout.
+  #       For example, you could publish the tick on a queue to be handled
+  #       by some other thread or process.
+  price  # => OandaAPI::Resource::Price
+end 
+```
+
+
 Documentation
 -------------
 
@@ -125,15 +143,15 @@ Please see the [Oanda Developer Wiki](http://developer.oanda.com/rest-live/intro
 for detailed documentation and API usage notes.
 
 
-| Ruby                       |  Oanda REST API      | 
+| Ruby                       |  Oanda REST API      |
 |:---------------------------|:---------------------|
-| client.accounts.get        | GET /v1/accounts     | 
+| client.accounts.get        | GET /v1/accounts     |
 | client.account(123).get    | GET /v1/accounts/123 |
 | client.account.create      | POST /v1/accounts    |
 | client.instruments.get     | GET /v1/instruments  |
 | client.prices(instruments: ["EUR_USD","USD_JPY"]).get | GET /v1/prices/?instruments=EUR_USD%2CUSD_JPY |
-| client.account(123).orders.get | GET /v1/accounts/123/orders
-| client.account(123).order(123).get | GET /v1/accounts/123/orders/123
+| client.account(123).orders.get | GET /v1/accounts/123/orders |
+| client.account(123).order(123).get | GET /v1/accounts/123/orders/123 |
 | client.account(123).order( *options* ).create | POST /v1/accounts/123/orders |
 | client.account(123).order(id:123, *options* ).update | PATCH /v1/accounts/123/orders/123 |
 | client.account(123).order(123).close | DELETE /v1/accounts/123/orders/123 |
@@ -216,3 +234,5 @@ License
 
 Copyright (c) 2014 Dean Missikowski. Distributed under the MIT License. See
 [LICENSE](LICENSE) for further details.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/oanda_api.rb

@@ -10,12 +10,15 @@ require_relative 'oanda_api/client/namespace_proxy'
 require_relative 'oanda_api/client/resource_descriptor'
 require_relative 'oanda_api/client/token_client'
 require_relative 'oanda_api/client/username_client'
+require_relative 'oanda_api/streaming/client'
+require_relative 'oanda_api/streaming/request'
 require_relative 'oanda_api/errors'
 require_relative 'oanda_api/resource_base'
 require_relative 'oanda_api/resource_collection'
 require_relative 'oanda_api/resource/account'
 require_relative 'oanda_api/resource/instrument'
 require_relative 'oanda_api/resource/candle'
+require_relative 'oanda_api/resource/heartbeat'
 require_relative 'oanda_api/resource/order'
 require_relative 'oanda_api/resource/position'
 require_relative 'oanda_api/resource/price'

data/lib/oanda_api/client/client.rb

@@ -8,7 +8,7 @@ module OandaAPI
   # Provides everything needed for accessing the API.
   #
   # - Uses persistant http connections.
-  # - Uses +OpenSSL::SSL::VERIFY_PEER+ to always validate SSL certificates.
+  # - Uses `OpenSSL::SSL::VERIFY_PEER` to always validate SSL certificates.
   # - Uses compression if enabled (see {Configuration#use_compression}).
   # - Uses request rate limiting if enabled (see {Configuration#use_request_throttling}).
   module Client
@@ -92,7 +92,7 @@ module OandaAPI
     # Maps An API _action_ to a corresponding http verb.
     #
     # @param [Symbol] method an API action. Supported actions are:
-    #  +:create+, +:close+, +:delete+, +:get+, +:update+.
+    #  `:create`, `:close`, `:delete`, `:get`, `:update`.
     #
     # @return [Symbol] an http verb.
     def self.map_method_to_http_verb(method)
@@ -167,7 +167,7 @@ module OandaAPI
 
     # @private
     # Enables method-chaining.
-    # @return [Namespace]
+    # @return [NamespaceProxy]
     def method_missing(sym, *args)
       NamespaceProxy.new self, sym, args.first
     end

data/lib/oanda_api/client/namespace_proxy.rb

@@ -24,12 +24,13 @@ module OandaAPI
       #   ordered list of segments, joined, creates a path to a resource URI.
       #
       # @param [Hash] conditions an optional list of parameters that typically
-      #   specifies conditions and filters for a resource request. A a _"key"_
+      #   specifies conditions and filters for a resource request. A _"key"_
       #   or _"id"_ is a condition that identifies a particular resource. If a
       #   key condition is included, it is extracted and added as a namespace
       #   segment. See {#extract_key_and_conditions}.
       def initialize(client, namespace_segment, conditions)
-        fail ArgumentError, "expecting an OandaAPI::Client instance" unless client && client.is_a?(OandaAPI::Client)
+        fail ArgumentError, "expecting an OandaAPI::Client instance" unless
+          client && client.is_a?(OandaAPI::Client) || client.is_a?(OandaAPI::Streaming::Client)
         fail ArgumentError, "expecting a namespace value" if namespace_segment.to_s.empty?
 
         @client = client
@@ -38,7 +39,7 @@ module OandaAPI
         extract_key_and_conditions conditions
       end
 
-      # Returns a deep clone of +self+.
+      # Returns a deep clone of `self`.
       # @return [NamespaceProxy]
       def clone
         ns = self.dup
@@ -86,20 +87,24 @@ module OandaAPI
       end
 
       # Executes an API request and returns a resource object, or returns a
-      # clone of +self+ for method chaining.
+      # clone of `self` for method chaining.
+      #
+      # @yield [OandaAPI::ResourceBase] if the method is `:stream`.
+      #
+      # @return [void] if the method is `:stream`.
       #
       # @return [OandaAPI::Client::NamespaceProxy] if the method is used
       #   for chaining.
       #
       # @return [OandaAPI::ResourceBase] if the method is one of the supported
-      #   _terminating_ methods (+:create+, +:close+, +:delete+, +:get+, +:update+).
+      #   _terminating_ methods (`:create`, `:close`, `:delete`, `:get`, `:update`).
       #
-      # @return [OandaAPI::ResourceCollection] if the method is +:get+ and the
+      # @return [OandaAPI::ResourceCollection] if the method is `:get` and the
       #   API returns a collection of resources.
-      def method_missing(sym, *args)
+      def method_missing(sym, *args, &block)
         # Check for terminating method
-        if [:create, :close, :delete, :get, :update].include?(sym)
-          @client.execute_request sym, namespace, conditions
+        if [:create, :close, :delete, :get, :update, :stream].include?(sym)
+          @client.execute_request sym, namespace, conditions, &block
         else
           ns = self.clone
           ns.namespace_segments << Utils.pluralize(sym)

data/lib/oanda_api/client/token_client.rb

@@ -8,8 +8,7 @@ module OandaAPI
     # {http://developer.oanda.com/rest-live/authentication/ obtaining a personal access token from Oanda}.
     #
     # @example Example usage
-    #   token  = ENV["oanda_practice_account_token"]
-    #   client = OandaAPI::Client::TokenClient.new :practice, token
+    #   client = OandaAPI::Client::TokenClient.new :practice, ENV.fetch("OANDA_PRACTICE_TOKEN")
     #
     #   # Get information for an account.
     #   # See http://developer.oanda.com/rest-live/accounts/
@@ -25,7 +24,7 @@ module OandaAPI
     #   @return [String] Oanda personal access token.
     #
     # @!attribute [rw] domain
-    #   @return [Symbol] identifies the Oanda subdomain (+:practice+ or +:live+)
+    #   @return [Symbol] identifies the Oanda subdomain (`:practice` or `:live`)
     #     accessed by the client.
     #
     # @!attribute [rw] default_params

data/lib/oanda_api/client/username_client.rb

@@ -15,7 +15,7 @@ module OandaAPI
     #
     #
     # @!attribute [r] domain
-    #   @return [Symbol] identifies the Oanda subdomain (+:sandbox+) which the
+    #   @return [Symbol] identifies the Oanda subdomain (`:sandbox`) which the
     #     client accesses.
     #
     # @!attribute [r] username

data/lib/oanda_api/configuration.rb

@@ -11,7 +11,7 @@ module OandaAPI
     USE_COMPRESSION         = false
     USE_REQUEST_THROTTLING  = false
 
-    # The format in which dates will be returned by the API (+:rfc3339+ or +:unix+).
+    # The format in which dates will be returned by the API (`:rfc3339` or `:unix`).
     # See the Oanda Development Guide for more details about {http://developer.oanda.com/rest-live/development-guide/#date_Time_Format DateTime formats}.
     # @return [Symbol]
     def datetime_format
@@ -27,7 +27,7 @@ module OandaAPI
     end
 
     # The maximum number of requests per second allowed to be made through the
-    # API. Only enforced if {#use_request_throttling?} is +true+.
+    # API. Only enforced if {#use_request_throttling?} is `true`.
     #
     # @return [Numeric]
     def max_requests_per_second
@@ -44,7 +44,7 @@ module OandaAPI
     end
 
     # The minimum amount of time in seconds that must elapse between consecutive requests to the API.
-    # Determined by {#max_requests_per_second}. Only enforced if {#use_request_throttling?} is +true+.
+    # Determined by {#max_requests_per_second}. Only enforced if {#use_request_throttling?} is `true`.
     # @return [Float]
     def min_request_interval
       @min_request_interval ||= (1.0 / max_requests_per_second)

data/lib/oanda_api/errors.rb

@@ -1,4 +1,7 @@
 module OandaAPI
-  # Errors raised by the client.
+  # Request errors raised by the client.
   class RequestError < RuntimeError; end
+
+  # Raised when the streaming API server disconnects the client
+  class StreamingDisconnect < RuntimeError; end
 end

data/lib/oanda_api/resource/heartbeat.rb

@@ -0,0 +1,13 @@
+module OandaAPI
+  module Resource
+    # Heartbeat returned by the Streaming API.
+    # See the Oanda Developer Guide for information about {http://developer.oanda.com/rest-live/streaming/ Heartbeats}.
+    class Heartbeat < ResourceBase
+      attr_accessor :time
+
+      def time=(v)
+        @time = Time.parse v.to_s
+      end
+    end
+  end
+end

data/lib/oanda_api/resource_base.rb

@@ -1,10 +1,11 @@
 module OandaAPI
+  require 'json'
   # Base class for all Resources.
   #
   # @!attribute [rw] location
-  #   @return [String] the +location+ header if one is returned in an API
+  #   @return [String] the `location` header if one is returned in an API
   #     response.
-  #   @example Using the +location+ attribute
+  #   @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
@@ -15,10 +16,16 @@ module OandaAPI
     #   {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)
+      initialize_attributes Utils.rubyize_keys(attributes)
       @location = attributes.location if attributes.respond_to? :location
     end
 
+    # Serializes an instance as JSON
+    # @return [String] a stringified JSON representation of an instance
+    def to_json
+      JSON.generate @_attributes.merge(custom_attributes)
+    end
+
     private
 
     # @private
@@ -27,9 +34,16 @@ module OandaAPI
     # @param [Hash] attributes collection of resource attributes.
     # @return [void]
     def initialize_attributes(attributes)
+      @_attributes = attributes
       attributes.each do |key, value|
         send("#{key}=", value) if respond_to? key
       end
     end
+
+    # Provides additional attributes used in serialization.
+    # @return [Hash] returns a hash of customized attributes for serialization
+    def custom_attributes
+      {}.tap { |hash| hash[:location] = location if location }
+    end
   end
 end

data/lib/oanda_api/resource_collection.rb

@@ -32,7 +32,7 @@ module OandaAPI
       @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
+      @location = attributes.location if attributes.respond_to? :location
     end
 
     # @yield [OandaAPI::ResourceBase]
@@ -47,21 +47,20 @@ module OandaAPI
 
     # @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+.
+    # 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) 
+      when @attributes.keys.include?(sym)
         @attributes[sym]
-      when
-        @collection.respond_to?(sym)
-          @collection.send sym
+      when @collection.respond_to?(sym)
+        @collection.send sym
       else
         super
       end
     end
 
-    # Returns +true+ for concrete, delegated and dynamic methods.
+    # Returns `true` for concrete, delegated and dynamic methods.
     # @return [Boolean]
     def respond_to?(sym)
       case

data/lib/oanda_api/streaming/client.rb

@@ -0,0 +1,153 @@
+module OandaAPI
+  module Streaming
+    # Resource URI templates
+    BASE_URI = {
+      live:     "https://stream-fxtrade.oanda.com/[API_VERSION]",
+      practice: "https://stream-fxpractice.oanda.com/[API_VERSION]"
+    }
+
+    # @example Example Usage
+    #   client = OandaAPI::Streaming::Client.new :practice, ENV.fetch("ONADA_PRACTICE_TOKEN")
+    #
+    #   # IMPORTANT
+    #   # This code will block indefinitely because streaming executes as an infinite loop.
+    #   prices = client.prices(account_id: 1234, instruments: %w[AUD_CAD AUD_CHF])
+    #   prices.stream do |price|
+    #
+    #     # The code in this block should handle the price as efficently
+    #     # as possible, otherwise the connection could timeout.
+    #     # For example, you could publish the tick on a queue to be handled
+    #     # by some other thread or process.
+    #     price  # => OandaAPI::Resource::Price
+    #   end
+    #
+    #   client.events.stream do |transaction|
+    #     transaction # => OandaAPI::Resource::Transaction
+    #   end
+    #
+    #   # -- Stopping the stream --
+    #   # You may add a second argument to the block to yield the client itself.
+    #   # You can use the client's `#stop!` method to terminate streaming.
+    #   @prices = []
+    #   prices = client.prices(account_id: 1234, instruments: %w[AUD_CAD AUD_CHF])
+    #   prices.stream do |price, client|
+    #     @prices << price
+    #     client.stop! if @prices.size == 10
+    #   end
+    #
+    # @!attribute [r] auth_token
+    #   @return [String] Oanda personal access token.
+    #
+    # @!attribute [r] streaming_request
+    #   @return [OandaAPI::Streaming::Request]
+    #
+    # @!attribute [rw] domain
+    #   @return [Symbol] identifies the Oanda subdomain (`:practice` or `:live`)
+    #     accessed by the client.
+    #
+    # @!attribute [rw] headers
+    #   @return [Hash] parameters that are included with every API request
+    #     as HTTP headers.
+    class Client
+      attr_reader :auth_token, :streaming_request
+      attr_accessor :domain, :headers
+
+      # @param [Symbol] domain see {#domain}
+      # @param [String] auth_token see {#auth_token}
+      def initialize(domain, auth_token)
+        super()
+        @auth_token = auth_token
+        self.domain = domain
+        @headers = auth
+        @streaming_request = nil
+      end
+
+      # Returns an absolute URI for a resource request.
+      #
+      # @param [String] path the path portion of the URI.
+      #
+      # @return [String] a URI.
+      def api_uri(path)
+        uri = "#{BASE_URI[domain]}#{path}"
+        uri.sub "[API_VERSION]", OandaAPI.configuration.rest_api_version
+      end
+
+      # Parameters used for authentication.
+      # @return [Hash]
+      def auth
+        { "Authorization" => "Bearer #{auth_token}" }
+      end
+
+      # @private
+      # Sets the domain the client can access.
+      # @return [void]
+      def domain=(value)
+        fail ArgumentError, "Invalid domain" unless OandaAPI::DOMAINS.include? value
+        @domain = value
+      end
+
+      # Determines whether emitted resources should include heartbeats.
+      # @param [boolean] value
+      def emit_heartbeats=(value)
+        @emit_heartbeats = value
+        streaming_request.emit_heartbeats = value if streaming_request
+      end
+
+      # Returns `true` if emitted resources include heartbeats. Defaults to false.
+      # @return [boolean]
+      def emit_heartbeats?
+        !!@emit_heartbeats
+      end
+
+      # Signals the streaming request to disconnect and terminates streaming.
+      # @return [void]
+      def stop!
+        streaming_request.stop! if running?
+      end
+
+      # Returns `true` if the client is currently streaming.
+      # @return [boolean]
+      def running?
+        !!(streaming_request && streaming_request.running?)
+      end
+
+      # @private
+      # Executes a streaming http request.
+      #
+      # @param [Symbol] _method Ignored.
+      #
+      # @param [String] path the path of an Oanda resource request.
+      #
+      # @param [Hash] conditions optional parameters that are converted into query parameters.
+      #
+      # @yield [OandaAPI:ResourceBase, OandaAPI::Streaming::Client]  See {OandaAPI::Streaming::Request.stream}
+      #
+      # @return [void]
+      #
+      # @raise [OandaAPI::RequestError] if the API return code is not 2xx.
+      # @raise [OandaAPI::StreamingDisconnect] if the API disconnects.
+      def execute_request(_method, path, conditions = {}, &block)
+        Http::Exceptions.wrap_and_check do
+          @streaming_request = OandaAPI::Streaming::Request.new client: self,
+                                                                uri: api_uri(path),
+                                                                query: Utils.stringify_keys(conditions),
+                                                                headers: OandaAPI.configuration.headers.merge(headers)
+          @streaming_request.stream(&block)
+          return nil
+        end
+
+        rescue Http::Exceptions::HttpException => e
+          raise OandaAPI::RequestError, e.message
+      end
+
+      private
+
+      # @private
+      # Enables method-chaining.
+      # @return [OandaAPI::Client::NamespaceProxy]
+      def method_missing(sym, *args)
+        OandaAPI::Client::NamespaceProxy.new self, sym, args.first
+      end
+    end
+  end
+end