genability 0.2.0 → 0.3.0

data/Gemfile

@@ -1,19 +1,20 @@
 source "http://rubygems.org"
 
-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"
+gem "faraday", "~> 0.7"
+gem "faraday_middleware", "~> 0.7"
+gem "hashie", "~> 1.2"
+gem "multi_json", "~> 1.0"
+gem "chronic", "~> 0.6"
 
-group :development do
-  gem "rspec", "~> 2.7"
-  gem "yard", "~> 0.7.0"
-  gem "bundler", "~> 1.0.7"
+group :development, :test do
+  gem "rspec", "~> 2.8"
+  gem "yard", "~> 0.7"
+  gem "redcarpet"
+  gem "bundler", "~> 1.0"
   gem "jeweler", "~> 1.6.4"
-  gem "simplecov", "~> 0.4"
+  gem "simplecov", "~> 0.5"
   gem "vcr", "~> 1.11.3"
-  gem "webmock", "~> 1.7.4"
-  gem 'ruby-debug19', :require => 'ruby-debug'
+  gem "webmock", "~> 1.7"
+  gem "pry"
 end
 

data/README.md

@@ -12,7 +12,6 @@ Documentation
 
 Usage Examples
 --------------
-    require "rubygems"
     require "genability"
 
     # Configure during client initialization
@@ -70,6 +69,39 @@ Usage Examples
     # Get information about a zipcode
     Genability.zipcode('48322')
 
+    # Add an account
+    Genability.add_account(:account_name => 'New Account')
+
+    # Show account
+    Genability.account("account_id")
+
+    # Get a list of accounts
+    Genability.accounts
+
+    # Delete account
+    Genability.delete_account("account_id")
+
+    # Add a usage profile
+    Genability.add_usage_profile(:account_id => "account_id")
+
+    # Show a usage profile
+    Genability.usage_profile("usage_profile_id")
+
+    # List usage profile
+    Genability.usage_profiles
+
+    # Add a reading(s) to a usage profile
+    Genability.add_readings("usage_profile_id", :readings =>
+      [
+        {
+          :from => "2011-08-01T22:30:00.000-0700",
+          :to => "2011-08-01T22:45:00.000-0700",
+          :quantity_unit => "kWh",
+          :quantity_value => 220
+        }
+      ]
+    )
+
     # Calculate the cost of electricity for a given rate plan
     #
     # First, get the caculation metadata necessary to run the calculation
@@ -77,9 +109,9 @@ Usage Examples
                  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"
+                 :additional_values => {                      # Metadata Options
+                   "connectionType" => "Primary Connection",
+                   "cityLimits" => "Inside"
                  }
                )
 
@@ -88,12 +120,14 @@ Usage Examples
                512,                                           # Master Tariff ID
                "Monday, September 1st, 2011",                 # From DateTime
                "Monday, September 10th, 2011",                # To DateTime
-               metadata                                       # Metadata from previous call
+               metadata,                                      # Metadata from previous call
+               {}                                             # Additional options
              )
     result.total_cost # => 10.837
 
 
-    # Please see the documentation for available options and the tests for additional examples
+
+Please see the [documentation](http://rubydoc.info/gems/genability/frames) for available options and the tests for additional examples
 
 
 Contributing to Genability

data/VERSION

@@ -1,2 +1,2 @@
-0.2.0
+0.3.0
 

data/genability.gemspec

@@ -4,14 +4,14 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{genability}
-  s.version = "0.2.0"
+  s.name = "genability"
+  s.version = "0.3.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-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.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Matthew Solt"]
+  s.date = "2011-11-27"
+  s.description = "Ruby client for the Genability power pricing and related APIs - learn more at https://developer.genability.com"
+  s.email = "mattsolt@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE.md",
     "README.md"
@@ -80,11 +80,11 @@ Gem::Specification.new do |s|
     "spec/genability_spec.rb",
     "spec/spec_helper.rb"
   ]
-  s.homepage = %q{http://github.com/activefx/genability}
-  s.licenses = [%q{MIT}]
-  s.require_paths = [%q{lib}]
-  s.rubygems_version = %q{1.8.5}
-  s.summary = %q{Ruby client for the Genability API}
+  s.homepage = "http://github.com/activefx/genability"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.11"
+  s.summary = "Ruby client for the Genability API"
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

data/lib/faraday/request/url_encoding_fix.rb

@@ -1,6 +1,6 @@
 require 'faraday'
 require 'addressable/uri'
-
+require 'pry'
 # @private
 module Faraday
   # @private

data/lib/genability.rb

@@ -1,8 +1,10 @@
-require 'genability/api'
-require 'genability/client'
+require 'mashie_extensions'
 require 'genability/configuration'
+require 'genability/connection'
+require 'genability/request'
+require 'genability/api'
 require 'genability/error'
-require 'mashie_extensions'
+require 'genability/client'
 
 module Genability
   extend Configuration

data/lib/genability/api.rb

@@ -1,6 +1,3 @@
-require 'genability/configuration'
-require 'genability/connection'
-require 'genability/request'
 #require File.expand_path('../oauth', __FILE__)
 
 module Genability

data/lib/genability/client.rb

@@ -2,6 +2,7 @@ module Genability
   # Wrapper for the Genability REST API
   class Client < API
     require 'genability/client/helpers'
+    require 'genability/client/account'
     require 'genability/client/calculate'
     require 'genability/client/echo'
     require 'genability/client/load_serving_entity'
@@ -11,10 +12,12 @@ module Genability
     require 'genability/client/tariff'
     require 'genability/client/territory'
     require 'genability/client/time_of_use'
+    require 'genability/client/usage_profile'
     require 'genability/client/zip_code'
 
     include Genability::Client::Helpers
 
+    include Genability::Client::Account
     include Genability::Client::Calculate
     include Genability::Client::Echo
     include Genability::Client::LoadServingEntity
@@ -24,6 +27,7 @@ module Genability
     include Genability::Client::Tariff
     include Genability::Client::Territory
     include Genability::Client::TimeOfUse
+    include Genability::Client::UsageProfile
     include Genability::Client::ZipCode
   end
 end

data/lib/genability/client/calculate.rb

@@ -19,10 +19,19 @@ module Genability
       #   @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.)
+      #   @option options [Integer] :territory_id The territory ID of where the usage consumption
+      #     occurred. (Required for most CA tariffs.)
+      #   @option options [Hash] :additional_values Any additional applicability values that
+      #     are required to calculate this tariff are passed in on the request url. Keep in
+      #     mind that this is only for the GET method where you are getting the required inputs.
+      #     When you POST to run the calculation, you will pass these applicability values as
+      #     part of the Tariff Input array. To find out how to get the list of applicability
+      #     properties required for a tariff,
+      #     {https://developer.genability.com/documentation/api-reference/public/tariff#getTariff read more here}.
       #   @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")
+      #     Genability.calculate_metadata(512, "2011-06-16T19:00:00.0-0400", "2011-08-01T00:00:00.0-0400",
+      #       { :additional_values => { "connectionType" => "Primary Connection", "cityLimits" => "Inside" })
       # @format :json
       # @authenticated true
       # @rate_limited true
@@ -33,9 +42,31 @@ module Genability
 
       # Calculate the cost of electricity for a given rate/pricing plan.
       # @overload calculate(tariff_id, from_date_time, to_date_time, tariff_inputs, options = {})
+      #   To run a new calculation, you will POST a payload containing the calculation criteria and
+      #   inputs, and a Calculated Cost will be returned. The table below documents the various
+      #   properties of the payload, and immediately after the table is an example of the payload itself.
+      #   @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.)
+      #   @option options [String] :detail_level Toggles the level of details for the calculation
+      #     result. (Optional) Possible values are:
+      #     ALL - return all details for this calculation (default)
+      #     TOTAL - return only the overall total, without any details
+      #     CHARGE_TYPE - group the details by charge types, such as FIXED, CONSUMPTION, QUANTITY
+      #     RATE - group the details by rates. This is most similar to how a utility bill is constructed.
+      #   @option options [Array] :tariff_inputs The array of TariffInput values to use when running
+      #     the calculation.
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
       # @see https://developer.genability.com/documentation/api-reference/pricing/calculate
       def calculate(tariff_id, from, to, tariff_inputs, options = {})
-        post( "beta/calculate/#{tariff_id}",
+        post( "beta/calculate/#{tariff_id}?appId=#{application_id}&appKey=#{application_key}",
               calculate_params(from, to, tariff_inputs, options)
             ).results.first
       end
@@ -51,8 +82,6 @@ module Genability
           "tariffInputs" => tariff_input_params(tariff_inputs)
         }.
         delete_if{ |k,v| v.nil? }.
-        merge({ "appId" => application_id,
-                "appKey" => application_key }).
         to_json
       end
 
@@ -66,29 +95,28 @@ module Genability
               a << convert_tariff_input_params(ti)
             end
           else
-            raise Genability::InvalidTariffInput
+            raise Genability::InvalidInput
           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]
-        }
+        raise Genability::InvalidInput unless tariff_input.is_a?(Hash)
+        tariff_input
       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? }
+          "territoryId" => options[:territory_id]
+        }.delete_if{ |k,v| v.nil? }.
+          merge( additional_values(options[:additional_values]) )
+      end
+
+      def additional_values(av)
+        av.is_a?(Hash) ? av : {}
       end
 
     end

data/lib/genability/client/echo.rb

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

data/lib/genability/client/helpers.rb

@@ -7,18 +7,63 @@ module Genability
     # @private
     module Helpers
 
-      private
+      protected
 
-      def pagination_params(options)
+      # @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)
+      def pagination_params(options = {})
         {
           'pageStart' => options['pageStart'] || options[:page_start] || options[:page],
-          'pageCount' => options['pageCount'] || options[:page_count] || options[:per_page],
+          'pageCount' => options['pageCount'] || options[:page_count] || options[:per_page]
+        }.delete_if{ |k,v| v.nil? }
+      end
+
+      # @option options [String] :search The string of text to search on. This
+      #   can also be a regular expression, in which case you should set the
+      #   'isRegex' flag to true. (Optional)
+      # @option options [String] :search_on Comma separated list of fields to
+      #   query on. When searchOn is specified, the text provided in the search
+      #   string field will be searched within these fields. The list of fields
+      #   to search on depend on the entity being searched for. Read the documentation
+      #   for the entity for more details on the fields that can be searched, and
+      #   the default fields to be searched if searchOn is not specified. (Optional)
+      # @option options [Boolean] :starts_with When true, the search will only
+      #   return results that begin with the specified search string. Otherwise,
+      #   any match of the search string will be returned as a result. Default is
+      #   false. (Optional)
+      # @option options [Boolean] :ends_with When true, the search will only return
+      #   results that end with the specified search string. Otherwise, any match of
+      #   the search string will be returned as a result. Default is false. (Optional)
+      # @option options [Boolean] :is_regex When true, the provided search string
+      #   will be regarded as a regular expression and the search will return results
+      #   matching the regular expression. Default is false. (Optional)
+      # @option options [String] :sort_on Comma separated list of fields to sort on.
+      #   This can also be input via Array Inputs (see above). (Optional)
+      # @option options [String] :sort_order Comma separated list of ordering.
+      #   Possible values are 'ASC' and 'DESC'. Default is 'ASC'. If your sortOn
+      #   contains multiple fields and you would like to order fields individually,
+      #   you can pass in a comma separated list here (or use Array Inputs, see above).
+      #   For example, if your sortOn contained 5 fields, and your sortOrder contained
+      #   'ASC, DESC, DESC', these would be applied to the first three items in the sortOn
+      #   field. The remaining two would default to ASC. (Optional)
+      def search_params(options = {})
+        {
+          'search'      => options[:search],
+          'searchOn'    => multi_option_handler(options[:search_on]),
+          'startsWith'  => convert_to_boolean(options[:starts_with]),
+          'endsWith'    => convert_to_boolean(options[:ends_with]),
+          'isRegex'     => convert_to_boolean(options[:is_regex]),
+          'sortOn'      => options[:sort_on],
+          'sortOrder'   => options[:sort_order]
         }.delete_if{ |k,v| v.nil? }
       end
 
       def convert_to_boolean(value = nil)
         return nil if value.nil? || value.empty?
-        "true"
+        value == "false" ? nil : "true"
       end
 
       def multi_option_handler(value = nil)

data/lib/genability/client/load_serving_entity.rb

@@ -17,11 +17,43 @@ 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 [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)
+      # @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)
+      # @option options [String] :search The string of text to search on. This
+      #   can also be a regular expression, in which case you should set the
+      #   'isRegex' flag to true. (Optional)
+      # @option options [String] :search_on Comma separated list of fields to
+      #   query on. When searchOn is specified, the text provided in the search
+      #   string field will be searched within these fields. The list of fields
+      #   to search on depend on the entity being searched for. Read the documentation
+      #   for the entity for more details on the fields that can be searched, and
+      #   the default fields to be searched if searchOn is not specified. (Optional)
+      # @option options [Boolean] :starts_with When true, the search will only
+      #   return results that begin with the specified search string. Otherwise,
+      #   any match of the search string will be returned as a result. Default is
+      #   false. (Optional)
+      # @option options [Boolean] :ends_with When true, the search will only return
+      #   results that end with the specified search string. Otherwise, any match of
+      #   the search string will be returned as a result. Default is false. (Optional)
+      # @option options [Boolean] :is_regex When true, the provided search string
+      #   will be regarded as a regular expression and the search will return results
+      #   matching the regular expression. Default is false. (Optional)
+      # @option options [String] :sort_on Comma separated list of fields to sort on.
+      #   This can also be input via Array Inputs (see above). (Optional)
+      # @option options [String] :sort_order Comma separated list of ordering.
+      #   Possible values are 'ASC' and 'DESC'. Default is 'ASC'. If your sortOn
+      #   contains multiple fields and you would like to order fields individually,
+      #   you can pass in a comma separated list here (or use Array Inputs, see above).
+      #   For example, if your sortOn contained 5 fields, and your sortOrder contained
+      #   'ASC, DESC, DESC', these would be applied to the first three items in the sortOn
+      #   field. The remaining two would default to ASC. (Optional)
+      # @option options [String] :account_id The unique ID of the Account for which
+      #   you want to find LSEs. When passed in, the search will look for a territoryId
+      #   on the Account and use that to find all LSEs that provide service within that
+      #   territory. (Optional)
       # @return [Array] List of load serving entities.
       # @see https://developer.genability.com/documentation/api-reference/public/lse
       # @example Return the first 25 load serving entities
@@ -31,11 +63,13 @@ module Genability
       # @example Return only 10 load serving entities
       #   Genability.load_serving_entities(:per_page => 10)
       # @example Search for load serving entities starting with the letters 'Ka'
-      #   Genability.load_serving_entities(:starts_with => 'Ka')
+      #   Genability.load_serving_entities(:search => 'Ka', :starts_with => 'true')
       # @example Search for load serving entities ending with the word 'Inc'
-      #   Genability.load_serving_entities(:ends_with => 'Inc')
+      #   Genability.load_serving_entities(:search => 'Inc', :ends_with => 'true')
       # @example Search for load serving entities with the word 'Energy'
-      #   Genability.load_serving_entities(:search_string => 'Energy')
+      #   Genability.load_serving_entities(:search => 'Energy')
+      # @example Search for load serving entities with a regular expression
+      #   Genability.load_serving_entities(:search => /\w{5,}/)
       def load_serving_entities(options={})
         get("public/lses", lses_params(options)).results
       end
@@ -62,14 +96,10 @@ module Genability
 
       def lses_params(options)
         {
-          '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]
+          'accountId' => options[:account_id]
+        }.delete_if{ |k,v| v.nil? }.
+          merge( pagination_params(options) ).
+          merge( search_params(options) )
       end
 
     end