genability 0.1.0 → 0.2.0

data/.document

@@ -1,5 +1,5 @@
 lib/**/*.rb
 bin/*
-- 
+-
 features/**/*.feature
-LICENSE.txt
+

data/Gemfile

@@ -1,18 +1,19 @@
 source "http://rubygems.org"
 
-gem "faraday", "~> 0.6"
-gem "faraday_middleware", "~> 0.6"
-gem "hashie", "~> 1.0.0"
-gem "multi_json", "~> 1.0.0"
-gem "chronic", "~> 0.4.0"
+gem "faraday", "~> 0.7.4"
+gem "faraday_middleware", "~> 0.7.0"
+gem "hashie", "~> 1.2.0"
+gem "multi_json", "~> 1.0.3"
+gem "chronic", "~> 0.6.4"
 
 group :development do
-  gem "rspec", "~> 2.6.0"
+  gem "rspec", "~> 2.7"
   gem "yard", "~> 0.7.0"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.6.2"
+  gem "bundler", "~> 1.0.7"
+  gem "jeweler", "~> 1.6.4"
   gem "simplecov", "~> 0.4"
-  gem "vcr", "~> 1.10.0"
-  gem "webmock", "~> 1.6.0"
+  gem "vcr", "~> 1.11.3"
+  gem "webmock", "~> 1.7.4"
+  gem 'ruby-debug19', :require => 'ruby-debug'
 end
 

data/HISTORY.md

@@ -5,3 +5,11 @@ HISTORY
 ----------------------
 * Initial Release
 
+0.2.0 - October 26, 2011
+----------------------
+* Added Calculate API calls
+* Added Echo and Property API helper calls
+* Update Faraday and Faraday Middleware to 0.7 versions
+* Added .to\_friendly\_hash method to Hashie::Mash to convert results to Ruby / Rails friendly attributes
+* Continued improving test coverage
+

data/README.md

@@ -19,10 +19,22 @@ Usage Examples
     client = Genability::Client.new(:application_id = 'ValidAppId', :application_key => 'ValidAppKey')
 
     # Or use the block configuration method
+    # Useful for using in a Rails initializer
     # register an app at https://developer.genability.com
     Genability.configure do |config|
-      config.application_id = 'ValidAppId'
-      config.application_key = 'ValidAppKey'
+      config.application_id   = 'ValidAppId'
+      config.application_key  = 'ValidAppKey'
+    end
+
+    # Advanced Configuration Options
+    Genability.configure do |config|
+      config.application_id   = 'ValidAppId'
+      config.application_key  = 'ValidAppKey'
+      config.adapter          = :typhoeus
+      config.endpoint         = "http://api.genability.com/rest/"
+      config.format           = :json
+      config.user_agent       = "Genability API Ruby Gem"
+      config.proxy            = "http://127.0.0.1"
     end
 
     # Get a list of load serving entities
@@ -53,11 +65,34 @@ Usage Examples
     Genability.time_of_uses(2756, 1)
 
     # Get the intervals for the particular time of use group of a given load serving entity
-    Genability.time_of_use_intervals(2756, 1)
+    Genability.time_of_use_intervals(734, 1)
 
     # Get information about a zipcode
     Genability.zipcode('48322')
 
+    # Calculate the cost of electricity for a given rate plan
+    #
+    # First, get the caculation metadata necessary to run the calculation
+    metadata = Genability.calculate_metadata(
+                 512,                                         # Master Tariff ID
+                 "Monday, September 1st, 2011",               # From DateTime
+                 "Monday, September 10th, 2011",              # To DateTime
+                 {                                            # Metadata Options
+                   :connection_type => "Primary Connection",
+                   :city_limits => "Inside"
+                 }
+               )
+
+    # Then, run the calculation with the metadata you just received
+    result = Genability.calculate(
+               512,                                           # Master Tariff ID
+               "Monday, September 1st, 2011",                 # From DateTime
+               "Monday, September 10th, 2011",                # To DateTime
+               metadata                                       # Metadata from previous call
+             )
+    result.total_cost # => 10.837
+
+
     # Please see the documentation for available options and the tests for additional examples
 
 

data/Rakefile

@@ -40,3 +40,4 @@ task :default => :spec
 
 require 'yard'
 YARD::Rake::YardocTask.new
+

data/VERSION

@@ -1 +1,2 @@
-0.1.0
+0.2.0
+

data/genability.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{genability}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Matthew Solt}]
-  s.date = %q{2011-07-01}
+  s.date = %q{2011-10-26}
   s.description = %q{Ruby client for the Genability power pricing and related APIs - learn more at https://developer.genability.com}
   s.email = %q{mattsolt@gmail.com}
   s.extra_rdoc_files = [
@@ -33,9 +33,12 @@ Gem::Specification.new do |s|
     "lib/genability.rb",
     "lib/genability/api.rb",
     "lib/genability/client.rb",
+    "lib/genability/client/calculate.rb",
+    "lib/genability/client/echo.rb",
     "lib/genability/client/helpers.rb",
     "lib/genability/client/load_serving_entity.rb",
     "lib/genability/client/price.rb",
+    "lib/genability/client/property.rb",
     "lib/genability/client/season.rb",
     "lib/genability/client/tariff.rb",
     "lib/genability/client/territory.rb",
@@ -46,9 +49,13 @@ Gem::Specification.new do |s|
     "lib/genability/error.rb",
     "lib/genability/request.rb",
     "lib/mashie_extensions.rb",
+    "spec/cassettes/calculate.yml",
+    "spec/cassettes/echo.yml",
     "spec/cassettes/load_serving_entities.yml",
     "spec/cassettes/load_serving_entity.yml",
     "spec/cassettes/prices.yml",
+    "spec/cassettes/properties.yml",
+    "spec/cassettes/property.yml",
     "spec/cassettes/seasons.yml",
     "spec/cassettes/tariff.yml",
     "spec/cassettes/tariffs.yml",
@@ -57,8 +64,12 @@ Gem::Specification.new do |s|
     "spec/cassettes/time_of_use.yml",
     "spec/cassettes/time_of_uses.yml",
     "spec/cassettes/zipcode.yml",
+    "spec/client/calculate_spec.rb",
+    "spec/client/echo_spec.rb",
+    "spec/client/helpers_spec.rb",
     "spec/client/load_serving_entity_spec.rb",
     "spec/client/price_spec.rb",
+    "spec/client/property_spec.rb",
     "spec/client/season_spec.rb",
     "spec/client/tariff_spec.rb",
     "spec/client/territory_spec.rb",
@@ -79,45 +90,48 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<faraday>, ["~> 0.6"])
-      s.add_runtime_dependency(%q<faraday_middleware>, ["~> 0.6"])
-      s.add_runtime_dependency(%q<hashie>, ["~> 1.0.0"])
-      s.add_runtime_dependency(%q<multi_json>, ["~> 1.0.0"])
-      s.add_runtime_dependency(%q<chronic>, ["~> 0.4.0"])
-      s.add_development_dependency(%q<rspec>, ["~> 2.6.0"])
+      s.add_runtime_dependency(%q<faraday>, ["~> 0.7.4"])
+      s.add_runtime_dependency(%q<faraday_middleware>, ["~> 0.7.0"])
+      s.add_runtime_dependency(%q<hashie>, ["~> 1.2.0"])
+      s.add_runtime_dependency(%q<multi_json>, ["~> 1.0.3"])
+      s.add_runtime_dependency(%q<chronic>, ["~> 0.6.4"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.7"])
       s.add_development_dependency(%q<yard>, ["~> 0.7.0"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.6.2"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.7"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
       s.add_development_dependency(%q<simplecov>, ["~> 0.4"])
-      s.add_development_dependency(%q<vcr>, ["~> 1.10.0"])
-      s.add_development_dependency(%q<webmock>, ["~> 1.6.0"])
+      s.add_development_dependency(%q<vcr>, ["~> 1.11.3"])
+      s.add_development_dependency(%q<webmock>, ["~> 1.7.4"])
+      s.add_development_dependency(%q<ruby-debug19>, [">= 0"])
     else
-      s.add_dependency(%q<faraday>, ["~> 0.6"])
-      s.add_dependency(%q<faraday_middleware>, ["~> 0.6"])
-      s.add_dependency(%q<hashie>, ["~> 1.0.0"])
-      s.add_dependency(%q<multi_json>, ["~> 1.0.0"])
-      s.add_dependency(%q<chronic>, ["~> 0.4.0"])
-      s.add_dependency(%q<rspec>, ["~> 2.6.0"])
+      s.add_dependency(%q<faraday>, ["~> 0.7.4"])
+      s.add_dependency(%q<faraday_middleware>, ["~> 0.7.0"])
+      s.add_dependency(%q<hashie>, ["~> 1.2.0"])
+      s.add_dependency(%q<multi_json>, ["~> 1.0.3"])
+      s.add_dependency(%q<chronic>, ["~> 0.6.4"])
+      s.add_dependency(%q<rspec>, ["~> 2.7"])
       s.add_dependency(%q<yard>, ["~> 0.7.0"])
-      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.6.2"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.7"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
       s.add_dependency(%q<simplecov>, ["~> 0.4"])
-      s.add_dependency(%q<vcr>, ["~> 1.10.0"])
-      s.add_dependency(%q<webmock>, ["~> 1.6.0"])
+      s.add_dependency(%q<vcr>, ["~> 1.11.3"])
+      s.add_dependency(%q<webmock>, ["~> 1.7.4"])
+      s.add_dependency(%q<ruby-debug19>, [">= 0"])
     end
   else
-    s.add_dependency(%q<faraday>, ["~> 0.6"])
-    s.add_dependency(%q<faraday_middleware>, ["~> 0.6"])
-    s.add_dependency(%q<hashie>, ["~> 1.0.0"])
-    s.add_dependency(%q<multi_json>, ["~> 1.0.0"])
-    s.add_dependency(%q<chronic>, ["~> 0.4.0"])
-    s.add_dependency(%q<rspec>, ["~> 2.6.0"])
+    s.add_dependency(%q<faraday>, ["~> 0.7.4"])
+    s.add_dependency(%q<faraday_middleware>, ["~> 0.7.0"])
+    s.add_dependency(%q<hashie>, ["~> 1.2.0"])
+    s.add_dependency(%q<multi_json>, ["~> 1.0.3"])
+    s.add_dependency(%q<chronic>, ["~> 0.6.4"])
+    s.add_dependency(%q<rspec>, ["~> 2.7"])
     s.add_dependency(%q<yard>, ["~> 0.7.0"])
-    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.6.2"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.7"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
     s.add_dependency(%q<simplecov>, ["~> 0.4"])
-    s.add_dependency(%q<vcr>, ["~> 1.10.0"])
-    s.add_dependency(%q<webmock>, ["~> 1.6.0"])
+    s.add_dependency(%q<vcr>, ["~> 1.11.3"])
+    s.add_dependency(%q<webmock>, ["~> 1.7.4"])
+    s.add_dependency(%q<ruby-debug19>, [">= 0"])
   end
 end
 

data/lib/faraday/request/url_encoding_fix.rb

@@ -13,7 +13,6 @@ module Faraday
       @app.call(env)
     end
 
-
   end
 end
 

data/lib/genability/client.rb

@@ -2,8 +2,11 @@ module Genability
   # Wrapper for the Genability REST API
   class Client < API
     require 'genability/client/helpers'
+    require 'genability/client/calculate'
+    require 'genability/client/echo'
     require 'genability/client/load_serving_entity'
     require 'genability/client/price'
+    require 'genability/client/property'
     require 'genability/client/season'
     require 'genability/client/tariff'
     require 'genability/client/territory'
@@ -12,8 +15,11 @@ module Genability
 
     include Genability::Client::Helpers
 
+    include Genability::Client::Calculate
+    include Genability::Client::Echo
     include Genability::Client::LoadServingEntity
     include Genability::Client::Price
+    include Genability::Client::Property
     include Genability::Client::Season
     include Genability::Client::Tariff
     include Genability::Client::Territory

data/lib/genability/client/calculate.rb

@@ -0,0 +1,97 @@
+module Genability
+  class Client
+    # The Calculate service basically calculates the cost of electricity for a
+    # given rate/pricing plan. This can be used to calculate a bill, "what-if"
+    # different rates, levels of usage, energy efficiency measures or any other
+    # electrical activity. It gives a total cost for a period of time. (Note
+    # that if you want a price/rate for a specific point in time, then look at
+    # the Price service.)
+    module Calculate
+
+      # @overload calculate_metadata(tariff_id, from_date_time, to_date_time, options = {})
+      #   Calling the URL as a HTTP GET will return the "inputs" required to accurately
+      #   calculate the cost for a given period. It essentially gives you the meta-data
+      #   for what to pass into the calculate method, and as such provides a template
+      #   for the payload of the HTTP POST.
+      #   @param tariff_id [Integer] Unique Genability ID (primary key) for a tariff.
+      #   @param from_date_time [DateTime, String] Starting date and time for this Calculate request.
+      #     In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.
+      #   @param to_date_time [DateTime, String] End date and time for this Calculate request.
+      #     In ISO 8601 format. Will attempt to use the Chronic gem to parse if a string is used.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :territory_id The territory ID of where the usage consumption occurred. (Required for most CA tariffs.)
+      #   @return [Array] Array of TariffInput for consumption.
+      #   @example Return the inputs required to accurately calculate the cost for a given period
+      #     Genability.calculate_metadata(512, "2011-06-16T19:00:00.0-0400", "2011-08-01T00:00:00.0-0400")
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @see https://developer.genability.com/documentation/api-reference/pricing/calculate
+      def calculate_metadata(tariff_id, from, to, options = {})
+        get("beta/calculate/#{tariff_id}", calculate_meta_params(from, to, options)).results
+      end
+
+      # Calculate the cost of electricity for a given rate/pricing plan.
+      # @overload calculate(tariff_id, from_date_time, to_date_time, tariff_inputs, options = {})
+      # @see https://developer.genability.com/documentation/api-reference/pricing/calculate
+      def calculate(tariff_id, from, to, tariff_inputs, options = {})
+        post( "beta/calculate/#{tariff_id}",
+              calculate_params(from, to, tariff_inputs, options)
+            ).results.first
+      end
+
+      private
+
+      def calculate_params(from, to, tariff_inputs, options)
+        {
+          "fromDateTime" => format_to_iso8601(from),
+          "toDateTime" => format_to_iso8601(to),
+          "territoryId" => options[:territory_id],
+          "detailLevel" => options[:detail_level],
+          "tariffInputs" => tariff_input_params(tariff_inputs)
+        }.
+        delete_if{ |k,v| v.nil? }.
+        merge({ "appId" => application_id,
+                "appKey" => application_key }).
+        to_json
+      end
+
+      def tariff_input_params(tariff_inputs)
+        [].tap do |a|
+          case tariff_inputs
+          when Hash
+            a << convert_tariff_input_params(tariff_inputs)
+          when Array
+            tariff_inputs.each do |ti|
+              a << convert_tariff_input_params(ti)
+            end
+          else
+            raise Genability::InvalidTariffInput
+          end
+        end
+      end
+
+      def convert_tariff_input_params(tariff_input)
+        return tariff_input.to_hash if tariff_input.is_a? Hashie::Mash
+        {
+          "keyName" => tariff_input[:key_name],
+          "fromDateTime" => tariff_input[:from],
+          "toDateTime" => tariff_input[:to],
+          "unit" => tariff_input[:unit]
+        }
+      end
+
+      def calculate_meta_params(from, to, options)
+        {
+          "fromDateTime" => format_to_iso8601(from),
+          "toDateTime" => format_to_iso8601(to),
+          "territoryId" => options[:territory_id],
+          "connectionType" => options[:connection_type],
+          "cityLimits" => options[:city_limits]
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/echo.rb

@@ -0,0 +1,21 @@
+module Genability
+  class Client
+
+    module Echo
+
+      def credentials_valid?
+        get("echo").status == "success"
+      end
+
+      #  def validate_date(date)
+      #    get("echo/validatedate", {"dateToValidate" => date}).results.first
+      #  end
+
+      def raise_error(error_code)
+        get("echo/errors/#{error_code}")
+      end
+
+    end
+  end
+end
+

data/lib/genability/client/helpers.rb

@@ -1,3 +1,4 @@
+require 'json'
 require 'time'
 require 'chronic'
 
@@ -20,7 +21,7 @@ module Genability
         "true"
       end
 
-      def multi_option_handler(value)
+      def multi_option_handler(value = nil)
         return nil if value.nil?
         if value.is_a?(Array)
           value.collect{|x| x.upcase}.join(',')

data/lib/genability/client/load_serving_entity.rb

@@ -17,9 +17,9 @@ module Genability
       # @authenticated true
       # @rate_limited true
       # @param options [Hash] A customizable set of options.
+      # @option options [String] :search_string Phrase for searching the names of Load Serving Entities (Optional)
       # @option options [String] :starts_with  Indicates the search phrase should match the start of the name. (Optional)
       # @option options [String] :ends_with Indicates the search phrase should match the end of the name. (Optional)
-      # @option options [String] :contains Indicates the search phrase should be somewhere in the middle of the name. (Optional)
       # @option options [Integer] :page The page number to begin the result set from. If not specified, this will begin with the first result set. (Optional)
       # @option options [Integer] :per_page The number of results to return. If not specified, this will return 25 results. (Optional)
       # @return [Array] List of load serving entities.
@@ -30,16 +30,14 @@ module Genability
       #   Genability.load_serving_entities(:page => 2)
       # @example Return only 10 load serving entities
       #   Genability.load_serving_entities(:per_page => 10)
-      # @example Search for load serving entities with the name 'Infinite'
-      #   Genability.load_serving_entities(:search => 'Infinite')
       # @example Search for load serving entities starting with the letters 'Ka'
       #   Genability.load_serving_entities(:starts_with => 'Ka')
       # @example Search for load serving entities ending with the word 'Inc'
       #   Genability.load_serving_entities(:ends_with => 'Inc')
-      # @example Search for load serving entities with the word 'Energy' somewhere in the name
-      #   Genability.load_serving_entities(:contains => 'Energy')
+      # @example Search for load serving entities with the word 'Energy'
+      #   Genability.load_serving_entities(:search_string => 'Energy')
       def load_serving_entities(options={})
-        get("lses", lses_params(options)).results
+        get("public/lses", lses_params(options)).results
       end
 
       alias :lses :load_serving_entities
@@ -55,7 +53,7 @@ module Genability
       # @example Return the details for Georgia Power Co
       #   Genability.load_serving_entity(2756)
       def load_serving_entity(load_serving_entity_id)
-        get("lses/#{load_serving_entity_id}").results.first
+        get("public/lses/#{load_serving_entity_id}").results.first
       end
 
       alias :lse :load_serving_entity
@@ -64,13 +62,16 @@ module Genability
 
       def lses_params(options)
         {
-          'wildCardText' => options[:contains] || options[:starts_with] || options[:ends_with],
-          'startsWithWildCard' => convert_to_boolean(options[:starts_with]),
-          'endsWithWildCard' => convert_to_boolean(options[:ends_with]),
-          'containsWildCard' => convert_to_boolean(options[:contains])
+          'searchString' => search_string(options),
+          'startsWith' => convert_to_boolean(options[:starts_with]),
+          'endsWith' => convert_to_boolean(options[:ends_with])
         }.delete_if{ |k,v| v.nil? }.merge( pagination_params(options) )
       end
 
+      def search_string(options)
+        options[:search_string] || options[:contains] || options[:starts_with] || options[:ends_with]
+      end
+
     end
   end
 end