vault_client 0.0.3 → 0.1.0

data/lib/presenters/unit_group_presenter.rb

@@ -1,4 +1,4 @@
-module VaultClient
+module VC
   class UnitGroupPresenter < BasePresenter
 
     attr_reader :unit_group
@@ -12,45 +12,33 @@ module VaultClient
     end
 
     def unit_presenters
-      if defined?(@unit_presenters)
-        @unit_presenters
-      else
-        @unit_presenters = @unit_group.units.map {|u| UnitPresenter.new(u)}
-      end
-    end
-
-    def template
-      if @unit_group.dyno_type?
-        "line_item_types/dyno"
-      elsif @unit_group.add_on_type?
-        "line_item_types/add_on"
-      elsif @unit_group.additional_type?
-        "line_item_types/additional"
-      end
-    end
-
-    def detail_template
-      if @unit_group.run_type?
-        "unit_group_types/flat"
-      elsif @unit_group.dyno_type?
-        "unit_group_types/metered"
-      else
-        "unit_group_types/brief"
-      end
+      @unit_presenters ||= @unit_group.units.map {|u| UnitPresenter.new(u)}
     end
 
     def daily_report_url
-      #TODO remove stub
+      #TODO remove chart stub
       #payments_uri("/billable_units/daily")
       "/billable_units/daily"
     end
 
     def compacted_reports
-      #TODO remove stub
+      #TODO remove chart stub
       #BillableUnitReporter.compacted(@unit_group.units)
       []
     end
 
+    def total
+      money(@unit_group.total)
+    end
+
+    def qty
+      trunc_hours(@unit_group.qty)
+    end
+
+    def rate
+      @unit_group.rate
+    end
+
     def name
       @unit_group.name
     end
@@ -59,20 +47,17 @@ module VaultClient
       @unit_group.description
     end
 
-    def qty
-      trunc_hours(@unit_group.qty)
+    def product_name
+      @unit_group.product_name
     end
 
-    def rate
+    def product_group
+      @unit_group.product_group
     end
 
     def unit_of_measure
-    end
-
-    def total
-      money(@unit_group.total)
+      @unit_group.rate_period
     end
 
   end
 end
-

data/lib/presenters/unit_presenter.rb

@@ -1,4 +1,4 @@
-module VaultClient
+module VC
   class UnitPresenter < BasePresenter
 
     def initialize(unit)
@@ -6,7 +6,7 @@ module VaultClient
     end
 
     def total
-      money(@unit.rate * @unit.qty)
+      money(@unit.total)
     end
 
     def rate
@@ -26,7 +26,7 @@ module VaultClient
     end
 
     def description
-      @unit.subresource
+      @unit.product_name
     end
 
   end

data/lib/services/line_item_builder.rb

@@ -1,4 +1,4 @@
-module VaultClient
+module VC
   module LineItemBuilder
     extend self
 

data/lib/vault_client.rb

@@ -1,88 +1,32 @@
-require 'rest-client'
 require 'yajl'
-require 'vault_helper'
-require 'resource_ownership_client'
-require 'billable_events_client'
-require 'usage_reports_client'
-
-module VaultClient
-
-  AuthenticationError  = Class.new(Exception)
-  AuthorizationError   = Class.new(Exception)
-  ServiceDownError     = Class.new(Exception)
-  UnexpectedError      = Class.new(Exception)
-  SymanticError        = Class.new(Exception)
-
-  attr_accessor :url
+require 'rest-client'
+require 'helpers/http_helpers'
 
+module VC
   extend self
-
-  def resource_ownerships(action, args={})
-    if ENV["VAULT_CLIENT_UNSAFE"] == "true"
-      make_unsafe_request! {ResourceOwnershipClient.make_request(action, args)}
-    else
-      make_http_request {ResourceOwnershipClient.make_request(action, args)}
-    end
-  end
-
-  def billable_events(action, args={})
-    if ENV["VAULT_CLIENT_UNSAFE"] == "true"
-      make_unsafe_request! {BillableEventsClient.make_request(action, args)}
-    else
-      make_http_request {BillableEventsClient.make_request(action, args)}
-    end
-  end
-
-  def make_unsafe_request!
-    begin
-      resp = yield
-      JSON.parse(resp.body)
-    rescue RestClient => e
-      return e.inspect
-    end
-  end
-
-  def make_http_request(&block)
-    block.call() do |resp, req, res|
-      response_body = JSON.parse(resp.body)
-      case resp.code
-      when 200, 201
-        response_body
-      when 400, 401,
-        raise(AuthenticationError, response_body)
-      when 403
-        raise(AuthorizationError, response_body)
-      when 404
-        raise(NotFound, response_body)
-      when 422
-        raise(SymanticError, response_body)
-      when 500
-        raise(UnexpectedError)
-      when 503
-        raise(ServiceDownError)
-      end
-    end
-  end
-
-  def url
-    @url || ENV["VAULT_URL"]
-  end
-
+  extend HttpHelpers
+
+  VCException         = Class.new(Exception)
+  AuthenticationError = Class.new(VCException)
+  AuthorizationError  = Class.new(VCException)
+  ServiceDownError    = Class.new(VCException)
+  UnexpectedError     = Class.new(VCException)
+  SymanticError       = Class.new(VCException)
 end
 
-$:.unshift("lib")
 
-require 'models/usage_report'
+require 'models/account'
 require 'models/billable_unit'
+require 'models/report'
 require 'models/unit_group'
 require 'models/line_item'
+require 'models/b_event'
+require 'models/res_own'
 
 require 'services/line_item_builder'
-require 'services/report_builder'
-
-require 'dto/usage_report'
 
 require 'presenters/base_presenter'
-require 'presenters/report_presenter'
-require 'presenters/line_item_presenter'
 require 'presenters/unit_group_presenter'
+require 'presenters/unit_presenter'
+require 'presenters/line_item_presenter'
+require 'presenters/report_presenter'

data/readme.md

@@ -3,17 +3,15 @@
 ## Purpose
 
 This gem wraps the APIs defined [here](https://github.com/heroku/shushu/tree/master/doc).
+The vault_client also provides a set of objects that help with the presentation
+of an invoice.
 
-## Usage
-
-### Setup
+## Setup
 
 ```bash
 $ gem install vault_client
 ```
 
-### Configure
-
 ```bash
 # Optional. When set, vault_client will ignore bad responses from The Vault's API.
 # Default: false
@@ -27,42 +25,208 @@ $VAULT_URL=https://vault-stg.heroku.com
 **Ruby configuration will take precedence over environment variables.**
 
 ```ruby
-VaultClient.url = "https://core:secret@vault-stg.heroku.com"
+VC.url = "https://core:secret@vault-stg.heroku.com"
 ```
 
-### Resource Ownership
+## Usage
+
+### PaymentMethods
+
+This API deals primarily with credit cards. PaymentMethods can be created
+indipendintly of Accounts. You will need a payment_method to generate an
+invoice.
+
+```ruby
+  #TODO Build API
+```
+
+### Accounts
+
+This API deals with accounts which is a primitive for grouping resources. You
+will need an account to generate a usage report.
+
+```ruby
+  VC::Account.create
+  #=> {:id => "001"}
+```
+
+### AccountOwnerships
+
+Use this API when you want to setup associations between Vault accounts and
+Vault payment_methods.
+
+For complete details on the semantics of this API, read the [AccountOwnerships
+API docs.](https://github.com/heroku/shushu/blob/master/doc/account_ownership_api.md)
+
+```ruby
+  # To associate an account with a payment_method
+  VC::AcctOwn.act(
+    :account_id        => vault_account_id,
+    :payment_method_id => payment_method_id,
+    :entity_id         => entity_id,
+    :time              => time
+  )
+  #=> {"payment_method_id"=>"123", "account_id"=>"1", "entity_id"=>"entity123"}
+
+  # Now we need to change the payment_method on an account
+  VC::AcctOwn.xfr(
+    :prev_payment_method_id => prev_payment_method_id,
+    :payment_method_id      => new_payment_method_id,
+    :account_id             => account_id,
+    :prev_entity_id         => prev_entity_id,
+    :entity_id              => entity_id,
+    :time                   => time
+  )
+  #=> {"payment_method_id"=>"456", "account_id"=>"1", "entity_id"=>"event124"}
+```
+
+### ResourceOwnerships
+
+Use this API when dealing with resources and Vault accounts. For instance:
+Heroku apps and Teams.
+
+For complete details on the semantics of this API, read the [ResourceOwnerships
+API docs.](https://github.com/heroku/shushu/blob/master/doc/resource_ownership_api.md)
 
 ```ruby
   # When a new app is created, activate a new resource_ownership record.
-  VaultClient.resource_ownerships(:activate, hid, vault_account_id, time, event_id)
-  #=> {"hid"=>"123", "account_id"=>"1", "event_id"=>"event123"}
+  VC::ResOwn.act(
+    :hid              => hid,
+    :entity_id         => entity_id,
+    :account_id       => vault_account_id,
+    :time             => time
+  )
+  #=> {"hid"=>"123", "account_id"=>"1", "entity_id"=>"event123"}
 
 
   # When an app is transfered to another vault account, transfer the resource_ownership record.
-  VaultClient.resource_ownerships(:transfer, hid, prev_vault_account_id, new_vault_account_id, time, prev_event_id, event_id)
-  #=> {"hid"=>"123", "account_id"=>"1", "event_id"=>"event123"}
+  VC::ResOwn.xfr(
+    :hid                   => hid,
+    :prev_entity_id         => prev_entity_id,
+    :prev_vault_account_id => prev_vault_account_id,
+    :entity_id              => entity_id,
+    :account_id            => new_vault_account_id,
+    :time                  => time
+  )
+  #=> {"hid"=>"123", "account_id"=>"1", "entity_id"=>"event123"}
 
   # When an app is destroyed, deactivate the resource_ownership record.
-  VaultClient.resource_ownerships(:deactivate, hid, new_vault_account_id, time, event_id)
-  #=> {"hid"=>"123", "account_id"=>"1", "event_id"=>"event123"}
+  VC::ResOwn.deact(
+    :hid        => hid,
+    :entity_id   => entity_id,
+    :account_id => vault_account_id,
+    :time       => time
+  )
+  #=> {"hid"=>"123", "account_id"=>"1", "entity_id"=>"event123"}
 ```
 
-## Hacking
+### BillableEvents
 
-### Supporting a vault endpoint
+Use this API when you want to start billing for a resource. You can start
+emitting events prior to setting up relationships between accounts and
+payment_methods. (Although, usage reports and invoices will not be available
+until account_ownerships and resource_ownerships have been established.)
 
-Define a method in the VaultClient module that looks like the name of the http
-resource. Have this method dispatch the call to another modle that implements
-the detail of the api. The aforementioned API client module should only return
-the data that is needed by rest-client to submit the request.
+For complete details on the semantics of this API, read the [BillableEvents
+API docs.](https://github.com/heroku/shushu/blob/master/doc/events_api.md)
 
-### Running the tests
+```ruby
+  # Open an event when you would like to start billing.
+  VC::BEvent.open(
+    :entity_id    => entity_id,
+    :hid          => hid,
+    :time         => time,
+    :rate_code    => rate_code,
+    :product_name => product_name,
+    :qty          => qty
+  )
+
+  # Don't forget to close it.
+  VC::BEvent.close(
+    :entity_id => entity_id,
+    :time      => time
+  )
+```
 
-We only test that our API client modules return the http parameters and the body
-for the http request. We trust that when rest-client is used correctly it will
-work.
+### UsageReports
 
-```bash
-$ bundle
-$ bundle turn test/
+```ruby
+  report = VC::UsageReport.new(account_id, from, to)
+  report.billable_units
+```
+
+
+### Invoices
+
+```ruby
+  invoice = VC::UsageReport.new(account_id, from, to)
+  invoice.billable_units
 ```
+
+
+### Report Generation
+
+Invoices and UsageReports can be used for report generation. Basically, the
+report generation code expects a collection of BillableUnits. BillableUnits are
+returned from both the Invoice API and the UsageReport API. However, the details
+of the billable_units may be different with respect to the type of the report.
+
+#### Presenters
+
+Clients of this library will want to generate some sort of view for the reports, the
+presenter objects were created to aid with that effort. You should only need to
+use the presenters while building views. Each view wraps a simple model object.
+All of the models and presenters are derived from the billable_unit which is
+retreived from the remote API.
+
+Report --> LineItem --> UnitGroup --> Billable Unit
+
+
+#### ReportPresenter
+
+The report presenter is how you will kick off the process of generating a
+report. You hand it a report object, either a UsageReport or and Invoice, and
+using the reports billable_units, it will build the line_items and a set of
+line_item_presenters for the line_items.
+
+#### LineItemBuilder
+
+The ReportPresenter will create a set of line_items based upon the
+billable_units in the report. The default is to group things by HID. Thus there
+will be a line_item for each distinct HID in the set of billable_units. The
+builder will also give a collection of unit_groups to the line_item. By default,
+the unit_groups will be partitioned by the product_group. (i.e. dyno, addon)
+
+You can customize the LineItemBuilder by creating a new class that responds to
+build and passing it to the ReportPresenter.
+
+```ruby
+  ReportPresenter.new(report, CustomLineItemBuilder)
+```
+
+#### LineItemPresenter
+
+The LineItemPresenter is responsible for handling the total and names of the
+line_items. It also manages the set of unit_groups. Since the default
+LineItemBuilder partitioned unit_groups based upon product_group, you can ask
+the LineItemPresenter for infomation about subsets of unit_groups. For instance:
+
+```ruby
+  line_item_presenter.unit_group_presenters("dyno")
+  line_item_presenter.unit_group_total("dyno")
+  line_item_presenter.unit_group_qty("dyno")
+```
+
+
+#### UnitGroupPresenter
+
+UnitGroups are collections of billable_units that are partitioned by
+product_name. So if there exists a set of billable_units that all have
+product_group = "dyno" and product_name= "worker", then this presenter
+will give you information about that group.
+
+
+#### UnitPresenter
+
+Finally, the UnitPresenter wraps a billable_unit and exposes methods to show
+totals, quantities and other meta-data.