evrythng 0.0.5 → 0.1.0

data/README.md

@@ -9,6 +9,5 @@ This is a Ruby wrapper for the Evrythng API. Do not consider it as stable, that'
 ## Usage
 
     Evrythng.configure do |config|
-      config.username = 'username' # your Evrythng username
-      config.password = 'passw0rd' # your Evrythng password
+      config.token = 't0ken' # your Evrythng authentication token
     end

data/evrythng.gemspec

@@ -8,26 +8,22 @@ Gem::Specification.new do |s|
   s.version      = Evrythng::VERSION.dup
   s.authors      = ["beawesomeinstead"]
   s.email        = "graf.otodrakula@gmail.com"
-  s.homepage     = "http://github.com/bai/evrythng-ruby"
-  s.summary      = "A Ruby wrapper for Evrythng API"
-  s.description  = "A Ruby wrapper for Evrythng API. Just proof of concept, do not consider this as a solid library."
+  s.homepage     = "http://github.com/bai/evrythng"
+  s.summary      = "Evrythng API wrapper"
+  s.description  = "A Ruby wrapper for Evrythng API."
 
   s.files        = `git ls-files`.split("\n")
   s.platform     = Gem::Platform::RUBY
   s.require_path = 'lib'
 
-  s.add_development_dependency 'maruku', '~> 0.6'
-  s.add_development_dependency 'nokogiri', '~> 1.4'
-  s.add_development_dependency 'rake', '~> 0.9'
-  s.add_development_dependency 'rspec', '~> 2.6'
-  s.add_development_dependency 'simplecov', '~> 0.4'
-  s.add_development_dependency 'webmock', '~> 1.7'
-  s.add_development_dependency 'yard', '~> 0.7'
-  s.add_development_dependency 'ZenTest', '~> 4.5'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'webmock'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'json'
 
-  s.add_runtime_dependency 'hashie', '~> 1.1.0'
-  s.add_runtime_dependency 'faraday', '~> 0.7.4'
-  s.add_runtime_dependency 'faraday_middleware', '~> 0.7.0'
-  s.add_runtime_dependency 'multi_json', '~> 1.0.0'
-  s.add_runtime_dependency 'simple_oauth', '~> 0.1.5'
+  s.add_dependency 'activesupport', ['>= 2.3.9', '< 4']
+  s.add_dependency 'faraday', '~> 0.8.0.rc2'
+  s.add_dependency 'multi_json', '~> 1.0.0'
 end

data/lib/evrythng/authenticatable.rb

@@ -0,0 +1,21 @@
+module Evrythng
+  module Authenticatable
+
+    # Credentials hash
+    #
+    # @return [Hash]
+    def credentials
+      {
+        :token => token
+      }
+    end
+
+    # Check whether credentials are present
+    #
+    # @return [Boolean]
+    def credentials?
+      credentials.values.all?
+    end
+
+  end
+end

data/lib/evrythng/client/collections.rb

@@ -4,34 +4,26 @@ module Evrythng
     module Collections
       # Returns a list of collections
       #
-      # @format :json, :xml
-      # @authenticated true
-      # @rate_limited true
       # @param options [Hash] A customizable set of options.
-      # @return [Hashie::Mash] The requested list of collections.
-      # @see http://dev.evrythng.net/doc/get/collections
+      # @return [Array] The requested list of collections.
+      # @see http://dev.evrythng.com/collections
       # @example Return the list of collections
       #   Evrythng.collections
       def collections(options={})
-        response = get('collections', options)
-        format.to_s.downcase == 'xml' ? response['collections'] : response
+        get('collections', options)
       end
 
       # Creates a collection
       #
-      # @format :json, :xml
-      # @authenticated true
-      # @rate_limited false
       # @param name [String] The name of collection.
       # @param description [String] The description of collection.
       # @param options [Hash] A customizable set of options.
-      # @return [Hashie::Mash] The created collection.
-      # @see http://dev.evrythng.net/doc/post/collections
+      # @return [Hash] The created collection.
+      # @see http://dev.evrythng.com/collections
       # @example Create the authenticating user's collection
       #   Evrythng.collection_create("This is a new collection!", "Here comes the description.")
       def collection_create(name, description=nil, options={})
-        response = post('collections', options.merge(:collection => { :name => name, :description => description }))
-        format.to_s.downcase == 'xml' ? response['collection'] : response
+        post('collections', options.merge(:name => name, :description => description))
       end
     end
   end

data/lib/evrythng/client/properties.rb

@@ -0,0 +1,45 @@
+module Evrythng
+  class Client
+    # Defines methods related to properties
+    module Properties
+      # Returns a list of properties for a given thng
+      #
+      # @param thng_id [String] The id of the thng to get properties for.
+      # @param options [Hash] A customizable set of options.
+      # @return [Array] The requested list of properties.
+      # @see http://dev.evrythng.com/properties
+      # @example Return the list of properties for thng 4f2133f39f5c550c2000016a
+      #   Evrythng.properties('4f2133f39f5c550c2000016a')
+      def properties(thng_id, options={})
+        get("thngs/#{thng_id}/properties", options)
+      end
+
+      # Returns a single property, specified by key
+      #
+      # @param thng_id [String] The id of the thng to get property for.
+      # @param key [String] The key of a property to fetch.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash] The requested property.
+      # @see http://dev.evrythng.com/properties
+      # @example Return the property with key 'Volume' for the thng with id 4f2133f39f5c550c2000016a
+      #   Evrythng.property('4f2133f39f5c550c2000016a', 'Volume')
+      def property(thng_id, key, options={})
+        get("thngs/#{thng_id}/properties/#{key}", options)
+      end
+
+      # Creates a property
+      #
+      # @param thng_id [String] The id of the thng to create property for.
+      # @param key [String] The key of property.
+      # @param value [String] The value of property.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash] The created property.
+      # @see http://dev.evrythng.com/properties
+      # @example Create a property for a thng with id 4f2133f39f5c550c2000016a
+      #   Evrythng.property_create('4f2133f39f5c550c2000016a', 'Volume', '30')
+      def property_create(thng_id, key, value, options={})
+        post("thngs/#{thng_id}/properties", options.merge(:key => key, :value => value))
+      end
+    end
+  end
+end

data/lib/evrythng/client/search.rb

@@ -0,0 +1,22 @@
+module Evrythng
+  class Client
+    # Defines methods related to Search
+    module Search
+
+      # Returns thngs that match a specified query.
+      #
+      # @see https://dev.evrythng.com/search
+      # @param q [String] A search term.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] :geocode Returns thngs located within a given radius of the given latitude/longitude. The parameter value is specified by "latitude,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers).
+      # @option options [Integer] :page The page number (starting at 1) to return.
+      # @option options [Integer] :per_page The number of thngs to return per page, up to a max of 100.
+      # @return [Array] Return thngs that match a specified query
+      # @example Returns thngs that contain 'bike' in their name or description
+      #   Evrythng.search('bike')
+      def search(q, options={})
+        get('search', options.merge(:q => q))
+      end
+    end
+  end
+end

data/lib/evrythng/client/thngs.rb

@@ -4,34 +4,38 @@ module Evrythng
     module Thngs
       # Returns a list of thngs
       #
-      # @format :json, :xml
-      # @authenticated true
-      # @rate_limited true
       # @param options [Hash] A customizable set of options.
-      # @return [Hashie::Mash] The requested list of thngs.
-      # @see http://developer.evrythng.net/thngs
+      # @return [Array] The requested list of thngs.
+      # @see http://dev.evrythng.com/thngs
       # @example Return the list of thngs
       #   Evrythng.thngs
       def thngs(options={})
-        response = get('thngs', options)
-        format.to_s.downcase == 'xml' ? response['thngs'] : response
+        get('thngs', options)
+      end
+
+      # Returns a single thng, specified by id
+      #
+      # @param id [String] The id of the desired thng.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash] The requested thng.
+      # @see http://dev.evrythng.com/thngs
+      # @example Return the thng with the id 4f2133f39f5c550c2000016a
+      #   Evrythng.thng('4f2133f39f5c550c2000016a')
+      def thng(id, options={})
+        get("thngs/#{id}", options)
       end
 
       # Creates a thng
       #
-      # @format :json, :xml
-      # @authenticated true
-      # @rate_limited false
-      # @param identifier [String] The identifier of thng.
+      # @param name [String] The name of thng.
       # @param description [String] The description of thng.
       # @param options [Hash] A customizable set of options.
-      # @return [Hashie::Mash] The created thng.
-      # @see http://developer.evrythng.net/thngs
+      # @return [Hash] The created thng.
+      # @see http://dev.evrythng.com/thngs
       # @example Create the authenticating user's thng
       #   Evrythng.thng_create("my.test.thng", "Here comes the description.")
-      def thng_create(identifier, description=nil, options={})
-        response = post('thngs', options.merge(:thng => { :identifier => identifier, :description => description }))
-        format.to_s.downcase == 'xml' ? response['thng'] : response
+      def thng_create(name, description=nil, options={})
+        post('thngs', options.merge(:name => name, :description => description))
       end
     end
   end

data/lib/evrythng/client.rb

@@ -1,13 +1,38 @@
+require 'evrythng/authenticatable'
+require 'evrythng/config'
+require 'evrythng/connection'
+require 'evrythng/request'
+
 module Evrythng
   # Wrapper for the Evrythng REST API
-  class Client < API
-    # Require client method modules after initializing the Client class in
-    # order to avoid a superclass mismatch error, allowing those modules to be
-    # Client-namespaced.
-    require 'evrythng/client/thngs'
-    require 'evrythng/client/collections'
+  class Client
+    include Evrythng::Authenticatable
+    include Evrythng::Connection
+    include Evrythng::Request
 
+    require 'evrythng/client/thngs'
     include Evrythng::Client::Thngs
+
+    require 'evrythng/client/collections'
     include Evrythng::Client::Collections
+
+    require 'evrythng/client/properties'
+    include Evrythng::Client::Properties
+
+    require 'evrythng/client/search'
+    include Evrythng::Client::Search
+
+    attr_accessor *Config::VALID_OPTIONS_KEYS
+
+    # Initializes a new API object
+    #
+    # @param attrs [Hash]
+    # @return [Evrythng::Client]
+    def initialize(attrs={})
+      attrs = Evrythng.options.merge(attrs)
+      Config::VALID_OPTIONS_KEYS.each do |key|
+        instance_variable_set("@#{key}".to_sym, attrs[key])
+      end
+    end
   end
 end

data/lib/evrythng/config.rb

@@ -0,0 +1,69 @@
+require 'evrythng/version'
+
+module Evrythng
+  # Defines constants and methods related to configuration
+  module Config
+    # An array of valid keys in the options hash when configuring a {Evrythng::API}
+    VALID_OPTIONS_KEYS = [
+      :adapter,
+      :connection_options,
+      :token,
+      :endpoint,
+      :gateway,
+      :proxy,
+      :user_agent]
+
+    # The adapter that will be used to connect if none is set
+    DEFAULT_ADAPTER = :net_http
+
+    # The Faraday connection options if none is set
+    DEFAULT_CONNECTION_OPTIONS = {}
+
+    # By default, don't set a token
+    DEFAULT_TOKEN = nil
+
+    # The endpoint that will be used to connect if none is set
+    DEFAULT_ENDPOINT = 'http://evrythng.com'
+
+    # By default, don't use a proxy server
+    DEFAULT_PROXY = nil
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_USER_AGENT = "Evrythng Ruby Gem #{Evrythng::VERSION}"
+
+    # By default, don't use a gateway server
+    DEFAULT_GATEWAY = nil
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+    end
+
+    # Create a hash of options and their values
+    def options
+      options = {}
+      VALID_OPTIONS_KEYS.each { |k| options[k] = send(k) }
+      options
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.adapter            = DEFAULT_ADAPTER
+      self.connection_options = DEFAULT_CONNECTION_OPTIONS
+      self.token              = DEFAULT_TOKEN
+      self.endpoint           = DEFAULT_ENDPOINT
+      self.proxy              = DEFAULT_PROXY
+      self.user_agent         = DEFAULT_USER_AGENT
+      self.gateway            = DEFAULT_GATEWAY
+      self
+    end
+  end
+end

data/lib/evrythng/connection.rb

@@ -1,38 +1,37 @@
-require 'faraday_middleware'
-require 'faraday/request/multipart_with_file'
-require 'faraday/request/gateway'
-require 'faraday/request/evrythng_oauth'
-require 'faraday/request/basic_authentication'
-require 'faraday/response/raise_http_4xx'
-require 'faraday/response/raise_http_5xx'
+require 'faraday'
+require 'evrythng/core_ext/hash'
+require 'evrythng/request/gateway'
+require 'evrythng/request/token_authentication'
+require 'evrythng/response/parse_json'
+require 'evrythng/response/raise_client_error'
+require 'evrythng/response/raise_server_error'
 
 module Evrythng
-  # @private
   module Connection
     private
 
-    def connection(format=format)
-      options = {
+    # Returns a Faraday::Connection object
+    #
+    # @param options [Hash] A hash of options
+    # @return [Faraday::Connection]
+    def connection(options={})
+      default_options = {
         :headers => {
-          :accept => "application/#{format}",
-          :user_agent => user_agent
+          :accept => 'application/vnd.evrythng-v2+json',
+          :user_agent => user_agent,
         },
         :proxy => proxy,
         :ssl => {:verify => false},
-        :url => api_endpoint,
+        :url => options.fetch(:endpoint, endpoint),
       }
-
-      Faraday.new(options) do |builder|
-        builder.use Faraday::Request::MultipartWithFile
-        # builder.use Faraday::Request::EvrythngOAuth, authentication if authenticated?
-        builder.use Faraday::Request::BasicAuthentication, username, password
+      Faraday.new(default_options.deep_merge(connection_options)) do |builder|
         builder.use Faraday::Request::Multipart
         builder.use Faraday::Request::UrlEncoded
-        builder.use Faraday::Request::Gateway, gateway if gateway
-        builder.use Faraday::Response::RaiseHttp4xx
-        builder.use Faraday::Response::Mashify
-        builder.use Faraday::Response::ParseJson
-        builder.use Faraday::Response::RaiseHttp5xx
+        builder.use Evrythng::Request::Gateway, gateway if gateway
+        builder.use Evrythng::Request::TokenAuthentication, token
+        builder.use Evrythng::Response::RaiseClientError
+        builder.use Evrythng::Response::ParseJson unless options[:raw]
+        builder.use Evrythng::Response::RaiseServerError
         builder.adapter(adapter)
       end
     end

data/lib/evrythng/core_ext/hash.rb

@@ -0,0 +1,19 @@
+class Hash
+
+  # Merges self with another hash, recursively
+  #
+  # @param hash [Hash] The hash to merge
+  # @return [Hash]
+  def deep_merge(hash)
+    target = self.dup
+    hash.keys.each do |key|
+      if hash[key].is_a?(Hash) && self[key].is_a?(Hash)
+        target[key] = target[key].deep_merge(hash[key])
+        next
+      end
+      target[key] = hash[key]
+    end
+    target
+  end
+
+end

data/lib/evrythng/error/bad_gateway.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/server_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 502
+  class Error::BadGateway < Evrythng::Error::ServerError
+  end
+end

data/lib/evrythng/error/bad_request.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/client_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 400
+  class Error::BadRequest < Evrythng::Error::ClientError
+  end
+end

data/lib/evrythng/error/client_error.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error'
+
+module Evrythng
+  # Raised when Evrythng returns a 4xx HTTP status code
+  class Error::ClientError < Evrythng::Error
+  end
+end

data/lib/evrythng/error/enhance_your_calm.rb

@@ -0,0 +1,11 @@
+require 'evrythng/error/client_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 420
+  class Error::EnhanceYourCalm < Evrythng::Error::ClientError
+    # The number of seconds your application should wait before requesting date from the Search API again
+    def retry_after
+      @http_headers.values_at('retry-after', 'Retry-After').detect{|value| value }.to_i
+    end
+  end
+end

data/lib/evrythng/error/forbidden.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/client_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 403
+  class Error::Forbidden < Evrythng::Error::ClientError
+  end
+end

data/lib/evrythng/error/internal_server_error.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/server_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 500
+  class Error::InternalServerError < Evrythng::Error::ServerError
+  end
+end

data/lib/evrythng/error/not_acceptable.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/client_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 406
+  class Error::NotAcceptable < Evrythng::Error::ClientError
+  end
+end

data/lib/evrythng/error/not_found.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/client_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 404
+  class Error::NotFound < Evrythng::Error::ClientError
+  end
+end

data/lib/evrythng/error/server_error.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error'
+
+module Evrythng
+  # Raised when Evrythng returns a 5xx HTTP status code
+  class Error::ServerError < Evrythng::Error
+  end
+end

data/lib/evrythng/error/service_unavailable.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/server_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 503
+  class Error::ServiceUnavailable < Evrythng::Error::ServerError
+  end
+end

data/lib/evrythng/error/unauthorized.rb

@@ -0,0 +1,7 @@
+require 'evrythng/error/client_error'
+
+module Evrythng
+  # Raised when Evrythng returns the HTTP status code 401
+  class Error::Unauthorized < Evrythng::Error::ClientError
+  end
+end

data/lib/evrythng/error.rb

@@ -3,57 +3,34 @@ module Evrythng
   class Error < StandardError
     attr_reader :http_headers
 
+    # Initializes a new Error object
+    #
+    # @param message [String]
+    # @param http_headers [Hash]
+    # @return [Evrythng::Error]
     def initialize(message, http_headers)
       @http_headers = Hash[http_headers]
-      super message
+      super(message)
     end
 
+    # @return [Time]
     def ratelimit_reset
       Time.at(@http_headers.values_at('x-ratelimit-reset', 'X-RateLimit-Reset').detect{|value| value}.to_i)
     end
 
+    # @return [Integer]
     def ratelimit_limit
       @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect{|value| value}.to_i
     end
 
+    # @return [Integer]
     def ratelimit_remaining
       @http_headers.values_at('x-ratelimit-remaining', 'X-RateLimit-Remaining').detect{|value| value}.to_i
     end
 
+    # @return [Integer]
     def retry_after
       [(ratelimit_reset - Time.now).ceil, 0].max
     end
   end
-
-  # Raised when Evrythng returns the HTTP status code 400
-  class BadRequest < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 401
-  class Unauthorized < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 403
-  class Forbidden < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 404
-  class NotFound < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 406
-  class NotAcceptable < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 420
-  class EnhanceYourCalm < Error
-    # The number of seconds your application should wait before requesting date from the Search API again
-    def retry_after
-      @http_headers.values_at('retry-after', 'Retry-After').detect {|value| value }.to_i
-    end
-  end
-
-  # Raised when Evrythng returns the HTTP status code 500
-  class InternalServerError < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 502
-  class BadGateway < Error; end
-
-  # Raised when Evrythng returns the HTTP status code 503
-  class ServiceUnavailable < Error; end
 end

data/lib/evrythng/request/gateway.rb

@@ -0,0 +1,20 @@
+require 'faraday'
+
+module Evrythng
+  module Request
+    class Gateway < Faraday::Middleware
+
+      def call(env)
+        url = env[:url].dup
+        url.host = @gateway
+        env[:url] = url
+        @app.call(env)
+      end
+
+      def initialize(app, gateway)
+        @app, @gateway = app, gateway
+      end
+
+    end
+  end
+end

data/lib/evrythng/request/token_authentication.rb

@@ -0,0 +1,22 @@
+require 'faraday'
+
+module Evrythng
+  module Request
+    class TokenAuthentication < Faraday::Middleware
+
+      def initialize(app, token, options={})
+        super(app)
+
+        @header_value = token
+      end
+
+      def call(env)
+        unless env[:request_headers]['X-Evrythng-Token']
+          env[:request_headers]['X-Evrythng-Token'] = @header_value
+        end
+        @app.call(env)
+      end
+
+    end
+  end
+end