green-button-data 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 943fa4496c7abd93c91c099eecc7f8da6f7b1183
-  data.tar.gz: 686f00fc33360e511ec3db4a79f901397dcf39d1
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MGE1ZDYxMWY2OWQ5ZjdiZTk1OWM2ZmEzZTdhMzg5OGVhMzRkZDk5Mw==
+  data.tar.gz: !binary |-
+    M2I1ZjllMGUzOWEzMjk5MDgwODY0YjFiYTQxY2Y4M2Y2NTA0ZWNhZQ==
 SHA512:
-  metadata.gz: c7f6738ec44e9a2a3d2fcff1abfb89e87f814782675fc4d734a8bc9fc99c8177aec1b7f906931a07b5e44bf73dc483b68a9973d4850417ce0863a8d3a7e85465
-  data.tar.gz: e1113a4af39451f38be1eeacfc7841772302d141159b10bc4f91cc00129971e4b81b10243c022f0d1f66303b0e80b8afa1843e1810ec7000208660d71c829f80
+  metadata.gz: !binary |-
+    YmVkYzZjMzFmNDYwMzY4NTE5MzM0ZGU3MTkzODI4ZjdjMDUwMGUzYjRiZjQ0
+    ZjcwYzY3ZjYzOTJlNzE2YTYwYmY1OTVjMWQ2NTdmODQ1MTA1ZDg0MDhjM2Ni
+    MjhjNTJiYzhlYzVmYTY4ZTFlZWM4YmUxZWE2ODA4ZTU5MjJmMjQ=
+  data.tar.gz: !binary |-
+    YmM1OTAzZjE4OTIzMzg4ZDQ5YWIxMWViY2ZjOGQ1M2RkMDc3ODY5ZTRlNDg0
+    OWU5YzQwNzUwMjQ0OWEwNzZlMjJmMzJmY2RhNDNkODllNTI3Y2NjZDE1NTQ1
+    NmZiMWJjMWI1YmE4YTc1MzNkZTgwNjUyNTJlYmVmOWJjNzZjZTc=

data/README.md

@@ -1,15 +1,15 @@
 # Green Button Data
 
-[![CI Results](https://img.shields.io/circleci/project/VerdigrisTech/green-button-data.svg)](https://circleci.com/gh/VerdigrisTech/green-button-data)
 [![Gem Version](https://img.shields.io/gem/v/green-button-data.svg)](https://rubygems.org/gems/green-button-data)
+[![CI Results](https://img.shields.io/circleci/project/VerdigrisTech/green-button-data.svg)](https://circleci.com/gh/VerdigrisTech/green-button-data)
 [![Dependencies](https://img.shields.io/gemnasium/VerdigrisTech/green-button-data.svg)](https://gemnasium.com/VerdigrisTech/green-button-data)
-[![Code Coverage](https://img.shields.io/codecov/c/github/VerdigrisTech/green-button-data.svg)](https://codecov.io/github/VerdigrisTech/green-button-data)
 [![Code Climate](https://img.shields.io/codeclimate/github/VerdigrisTech/green-button-data.svg)](https://codeclimate.com/github/VerdigrisTech/green-button-data)
+[![Code Coverage](https://img.shields.io/codecov/c/github/VerdigrisTech/green-button-data.svg)](https://codecov.io/github/VerdigrisTech/green-button-data)
 
-Green Button Data is a Ruby gem that can quickly parse the Green Button data
-standard. It uses an event-driven <abbr title="Simple API for XML">SAX</abbr>
-parser which does not build the entire <abbr title="Document Object Model">DOM</abbr>
-in memory.
+Green Button Data is a Ruby gem that can consume Green Button APIs and parse
+the Green Button data XML schema very quickly. It uses an event-driven
+<abbr title="Simple API for XML">SAX</abbr> parser which parses XML data without
+building an entire <abbr title="Document Object Model">DOM</abbr> in memory.
 
 ## Getting Started
 
@@ -25,7 +25,100 @@ Then run Bundler:
 $ bundle
 ```
 
-## Usage
+Unless you have a project that auto loads all gems in the Gemfile (e.g. a Rails
+project), you will need to require it:
+
+```ruby
+require 'green-button-data'
+```
+
+This will expose the GreenButtonData module namespace.
+
+## Integrating GreenButtonData Into Your Application
+
+GreenButtonData gem provides a familiar interface to consuming API endpoints.
+Method names are similar to Rails' ActiveRecord models and can be easily
+integrated into existing applications.
+
+### Configuration
+
+You can add configuration options like the following:
+
+```ruby
+GreenButtonData.configure do |config|
+  config.base_url = "https://api.example.com/DataCustodian/espi/1_1/resource/"
+  config.application_information_path = "ApplicationInformation/"
+  config.authorization_path = "Authorization/"
+  config.subscription_path = "Subscription/"
+  config.usage_point_path = "UsagePoint/"
+end
+```
+
+Note that each path _must_ end with a trailing slash.
+
+#### Rails Integration
+
+If you are developing a Rails app, create a file at
+`config/initializers/green_button_data.rb` from your Rails project root and
+add the configuration there.
+
+## Green Button Data API Client
+
+Green Button Data specification states that all API endpoints be secured with
+OAuth2 which means most fetch operations will require auth tokens.
+
+Some endpoints are secured further by utilizing client SSL certificates (e.g.
+Pacific Gas & Electric). You may pass in `ssl` options in addition to
+the `token` option in this case.
+
+> **DISCLAIMER:** Green Button Data is **_NOT_** responsible for managing OAuth
+tokens to make authenticated requests. There are other gems that provide mature,
+production proven OAuth 2 functionalities such as [OmniAuth](https://github.com/intridea/omniauth).
+
+### List all entries
+
+By default, the `.all` method attempts to use the URL path set by configuration:
+
+```ruby
+require 'green-button-data'
+
+# Ideally obtained from OmniAuth gem
+access_token = "12345678-1024-2048-abcdef001234"
+
+# Return all usage points; URL is specified in GreenButtonData.configuration.usage_point_url
+usage_points = UsagePoint.all token: access_token
+```
+
+You may override the global configuration by specifying the URL in the method:
+
+```ruby
+usage_points = UsagePoint.all "https://someotherapi.org/espi/Authorization",
+                              token: access_token
+```
+
+### Find an entry by ID
+
+If you have URL defined in configuration, the `.find` method appends the ID to
+the URL:
+
+```ruby
+GreenButtonData.configure do |config|
+  config.base_url = "https://services.greenbuttondata.org/"
+  config.usage_point_path = "DataCustodian/espi/1_1/resource/UsagePoint/"
+end
+
+# GET request to https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/UsagePoint/2
+usage_point = GreenButtonData::UsagePoint.find 2, token: access_token
+```
+
+As with `.all` method, URL can be overridden per request in `.find`:
+
+```ruby
+usage_point = GreenButtonData::UsagePoint.find "https://someotherapi.org/espi/UsagePoint/1",
+                                               token: access_token
+```
+
+## Parsing
 
 Almost all of the functionality for parsing data is wrapped in the
 `GreenButtonData::Feed` class.
@@ -61,6 +154,21 @@ end
 4. Push the branch: `git push origin my-awesome-feature`
 5. Submit a pull request
 
+## Versioning
+
+Green Button Data gem follows [Semantic Versioning 2.0](http://semver.org/). As
+such, you can specify a pessimistic version constraint on this gem with two
+digits of precision and be guaranteed latest features and bug fixes without
+backwards breaking changes:
+
+```ruby
+gem 'green-button-data', '~> 0.1'
+```
+
+Exception to this rule as per the SemVer specification is major version zero for
+initial development. This gem's API should NOT be considered stable until 1.0
+release.
+
 ## License
 
 This software is distributed AS IS WITHOUT WARRANTY under [Simplified BSD](https://raw.githubusercontent.com/VerdigrisTech/green-button-data/master/LICENSE.txt)
@@ -70,4 +178,4 @@ Verdigris Technologies Inc. assumes NO RESPONSIBILITY OR LIABILITY
 UNDER ANY CIRCUMSTANCES for usage of this software. See the [LICENSE.txt](https://raw.githubusercontent.com/VerdigrisTech/green-button-data/master/LICENSE.txt)
 file for detailed legal information.
 
-Copyright © 2015, Verdigris Technologies Inc. All rights reserved.
+Copyright © 2015, [Verdigris Technologies Inc](http://verdigris.co). All rights reserved.

data/green-button-data.gemspec

@@ -10,7 +10,10 @@ Gem::Specification.new do |s|
   s.licenses    = ['BSD-2-Clause']
 
   s.summary     = 'Parser for Green Button data format'
-  s.description = 'A library to parse large Green Button feed quickly'
+  s.description = 'Green Button Data is a Ruby gem that can consume Green ' +
+                  'Button APIs and parse the Green Button data XML schema ' +
+                  'very quickly. It uses an event-driven SAX parser which ' +
+                  'parses XML data without building an entire DOM in memory.'
 
   s.files         = `git ls-files`.split("\n")
   s.require_paths = ['lib']
@@ -20,7 +23,9 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'nokogiri', '~> 1.6'
   s.add_dependency 'sax-machine', '~> 1.3'
+  s.add_dependency 'faraday', '~> 0.9'
 
   s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'webmock', '~> 1.21'
   s.add_development_dependency 'guard', '~>2.13'
 end

data/lib/green-button-data.rb

@@ -1,11 +1,36 @@
 require 'sax-machine'
+require 'faraday'
 
 require 'green-button-data/core_ext'
+require 'green-button-data/configuration'
+require 'green-button-data/utilities'
 require 'green-button-data/dst'
 require 'green-button-data/enumerations'
-require 'green-button-data/utilities'
 require 'green-button-data/parser'
 require 'green-button-data/feed'
+require 'green-button-data/relations'
+require 'green-button-data/model_collection'
+require 'green-button-data/fetchable'
+require 'green-button-data/entry'
+require 'green-button-data/application_information'
+require 'green-button-data/authorization'
+require 'green-button-data/interval_block'
+require 'green-button-data/local_time_parameters'
+require 'green-button-data/meter_reading'
+require 'green-button-data/reading_type'
+require 'green-button-data/usage_point'
+require 'green-button-data/usage_summary'
 
 module GreenButtonData
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield configuration
+  end
 end

data/lib/green-button-data/application_information.rb

@@ -0,0 +1,112 @@
+module GreenButtonData
+  class ApplicationInformation < Entry
+    include Enumerations
+    include Utilities
+
+    attr_accessor :authorization_server_authorization_endpoint,
+                  :authorization_server_registration_endpoint,
+                  :authorization_server_token_endpoint,
+                  :authorization_server_uri,
+                  :contacts,
+                  :client_id,
+                  :client_name,
+                  :client_secret,
+                  :data_custodian_bulk_request_uri,
+                  :data_custodian_id,
+                  :data_custodian_resource_endpoint,
+                  :data_custodian_scope_selection_screen_uri,
+                  :grant_types,
+                  :redirect_uri,
+                  :registration_access_token,
+                  :registration_client_uri,
+                  :response_types,
+                  :scopes,
+                  :software_id,
+                  :software_version,
+                  :third_party_application_description,
+                  :third_party_notify_uri,
+                  :third_party_phone,
+                  :third_party_scope_selection_screen_uri,
+                  :third_party_user_portal_screen_uri,
+                  :token_endpoint_auth_method
+
+    def client_id_issued_at(kwargs = {})
+      epoch_to_time @client_id_issued_at, kwargs
+    end
+
+    def client_secret_expires_at(kwargs = {})
+      if @client_secret_expires_at == 0
+        # Maximum Fixnum = 4611686018427387903
+        max_fixnum = 2 ** (@client_secret_expires_at.size * 8 - 2) - 1
+
+        # Roughly 146 billion years into the future; Sun would be long dead by
+        # this time; so for all intents and purposes, never expires
+        time = Time.at(max_fixnum)
+
+        if kwargs[:local] == true
+          return time.localtime
+        else
+          return time.utc
+        end
+      else
+        epoch_to_time(@client_secret_expires_at, kwargs)
+      end
+    end
+
+    def data_custodian_application_status
+      get_enum_symbol DATA_CUSTODIAN_APPLICATION_STATUS,
+                      @data_custodian_application_status
+    end
+
+    def third_party_application_type
+      get_enum_symbol THIRD_PARTY_APPLICATION_TYPE,
+                      @third_party_application_type
+    end
+
+    def third_party_application_use
+      get_enum_symbol THIRD_PARTY_APPLICATION_USE, @third_party_application_use
+    end
+
+    def to_h
+      {
+        authorization_server_authorization_endpoint:
+          authorization_server_authorization_endpoint,
+        authorization_server_registration_endpoint:
+          authorization_server_registration_endpoint,
+        authorization_server_token_endpoint:
+          authorization_server_token_endpoint,
+        authorization_server_uri: authorization_server_uri,
+        contacts: contacts,
+        client_id: client_id,
+        client_id_issued_at: client_id_issued_at,
+        client_name: client_name,
+        client_secret: client_secret,
+        client_secret_expires_at: client_secret_expires_at,
+        data_custodian_application_status: data_custodian_application_status,
+        data_custodian_bulk_request_uri: data_custodian_bulk_request_uri,
+        data_custodian_id: data_custodian_id,
+        data_custodian_resource_endpoint: data_custodian_resource_endpoint,
+        data_custodian_scope_selection_screen_uri:
+          data_custodian_scope_selection_screen_uri,
+        grant_types: grant_types,
+        redirect_uri: redirect_uri,
+        registration_access_token: registration_access_token,
+        registration_client_uri: registration_client_uri,
+        response_types: response_types,
+        scopes: scopes,
+        software_id: software_id,
+        software_version: software_version,
+        third_party_application_description:
+          third_party_application_description,
+        third_party_application_type: third_party_application_type,
+        third_party_application_use: third_party_application_use,
+        third_party_notify_uri: third_party_notify_uri,
+        third_party_phone: third_party_phone,
+        third_party_scope_selection_screen_uri:
+          third_party_scope_selection_screen_uri,
+        third_party_user_portal_screen_uri: third_party_user_portal_screen_uri,
+        token_endpoint_auth_method: token_endpoint_auth_method
+      }
+    end
+  end
+end

data/lib/green-button-data/authorization.rb

@@ -0,0 +1,35 @@
+module GreenButtonData
+  class Authorization < Entry
+    include Enumerations
+    include Utilities
+
+    attr_reader :id
+
+    attr_accessor :authorized_period,
+                  :published_period,
+                  :expires_at,
+                  :status,
+                  :resource_uri,
+                  :authorization_uri
+
+    def active?
+      @status > 0
+    end
+
+    def expires_at
+      if @expires_at.is_a? Numeric
+        epoch_to_time @expires_at
+      elsif @expires_at.is_a? String
+        parse_datetime(@expires_at).to_time
+      elsif @expires_at.respond_to? :to_time
+        @expires_at.to_time
+      else
+        raise "Invalid expires_at type"
+      end
+    end
+
+    def status
+      get_enum_symbol AUTHORIZATION_STATUS, @status
+    end
+  end
+end

data/lib/green-button-data/configuration.rb

@@ -0,0 +1,133 @@
+require 'uri'
+
+module GreenButtonData
+  class Configuration
+    attr_accessor :base_url,
+                  :application_information_path,
+                  :authorization_path,
+                  :interval_block_path,
+                  :local_time_parameters_path,
+                  :meter_reading_path,
+                  :reading_type_path,
+                  :subscription_path,
+                  :usage_point_path,
+                  :usage_summary_path
+
+    def application_information_url
+      return URI.join(@base_url, @application_information_path).to_s
+    end
+
+    def application_information_url=(url)
+      uri = URI.parse url
+      @base_url = "#{uri.scheme}://#{uri.host}"
+      @application_information_path = uri.path
+    end
+
+    def authorization_url
+      return URI.join(@base_url, @authorization_path).to_s
+    end
+
+    def authorization_url=(url)
+      uri = URI.parse url
+      @base_url = "#{uri.scheme}://#{uri.host}"
+      @authorization_path = uri.path
+    end
+
+    def interval_block_url(kwargs = {})
+      subscription_id = kwargs[:subscription_id]
+      usage_point_id = kwargs[:usage_point_id]
+      meter_reading_id = kwargs[:meter_reading_id]
+      interval_block_id = kwargs[:interval_block_id]
+
+      uri = if subscription_id && usage_point_id && meter_reading_id
+        meter_reading_uri = meter_reading_url(
+          subscription_id: subscription_id,
+          usage_point_id: usage_point_id,
+          meter_reading_id: meter_reading_id
+        )
+
+        URI.join meter_reading_uri, @interval_block_path
+      else
+        URI.join @base_url, @interval_block_path
+      end
+
+      uri = URI.join uri, "#{interval_block_id}/" if interval_block_id
+
+      return uri.to_s
+    end
+
+    def local_time_parameters_url
+      return URI.join @base_url, @local_time_parameters_path
+    end
+
+    def meter_reading_url(kwargs = {})
+      subscription_id = kwargs[:subscription_id]
+      usage_point_id = kwargs[:usage_point_id]
+      meter_reading_id = kwargs[:meter_reading_id]
+
+      uri = if subscription_id && usage_point_id
+        usage_point_uri = usage_point_url(
+          subscription_id: subscription_id,
+          usage_point_id: usage_point_id
+        )
+
+        URI.join usage_point_uri, @meter_reading_path
+      else
+        URI.join @base_url, @meter_reading_path
+      end
+
+      uri = URI.join uri, "#{meter_reading_id}/" if meter_reading_id
+
+      return uri.to_s
+    end
+
+    def reading_type_url(id = nil)
+      uri = URI.join @base_url, @reading_type_path
+      uri = URI.join uri, "#{id}/" if id
+
+      return uri.to_s
+    end
+
+    def subscription_url(id)
+      uri = URI.join @base_url, @subscription_path
+      uri = URI.join uri, "#{id}/" if id
+      return uri.to_s
+    end
+
+    def usage_point_url(kwargs = {})
+      subscription_id = kwargs[:subscription_id]
+      usage_point_id = kwargs[:usage_point_id]
+
+      uri = if subscription_id
+        subscription_uri = subscription_url subscription_id
+
+        URI.join subscription_uri, @usage_point_path
+      else
+        URI.join @base_url, @usage_point_path
+      end
+
+      uri = URI.join uri, "#{usage_point_id}/" if usage_point_id
+
+      return uri.to_s
+    end
+
+    def usage_summary_url(kwargs = {})
+      subscription_id = kwargs[:subscription_id]
+      usage_point_id = kwargs[:usage_point_id]
+
+      if subscription_id && usage_point_id
+        usage_point_uri = usage_point_url subscription_id: subscription_id,
+                                          usage_point_id: usage_point_id
+
+        return URI.join(usage_point_uri, @usage_summary_path).to_s
+      elsif subscription_id
+        raise ArgumentError.new "Missing required argument: usage_point_id"
+      elsif usage_point_id
+        raise ArgumentError.new "Missing required argument: subscription_id"
+      else
+        raise ArgumentError.new "Missing required arguments: subscription_id," +
+                                " usage_point_id"
+      end
+    end
+  end
+end