amee 2.0.25

data/COPYING

@@ -0,0 +1,19 @@
+Copyright (c) 2008 James Smith (james@floppy.org.uk)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,106 @@
+== AMEE-Ruby
+
+A gem to provide a Ruby interface to the AMEE carbon calculator (http://amee.cc)
+
+Licensed under the MIT license (See COPYING file for details)
+
+Author: James Smith (james@floppy.org.uk / http://www.floppy.org.uk)
+
+Homepage: http://github.com/Floppy/amee-ruby
+
+Documentation: http://docs.github.com/Floppy/amee-ruby
+
+== INSTALLATION
+
+1) Enable gems from github, if you haven't already done so (rubygems >= 1.2): 
+    > sudo gem sources -a http://gems.github.com
+
+2) Install gem
+    > sudo gem install Floppy-amee
+
+== IMPORTANT CHANGES in 2.0.25
+
+If you are using the $amee connection in your Rails apps, this is now deprecated
+ and will be removed in future releases. See the "Rails" section below for details 
+of what you should use instead.
+
+== USAGE
+
+Currently, you can read DataCategories, DataItems and DataItemValues. See 
+examples/view_data_*.rb for simple usage examples. You can also get the list
+of available Profiles, and create and delete them. See examples/list_profiles.rb
+and examples/create_profile.rb for details. You can also load ProfileCategories,
+and load, create and update ProfileItems.
+
+The gem will use the AMEE JSON API if the JSON gem is installed on the local
+system. Otherwise the XML API will be used.
+
+== SUPPORT
+                    Create    Read     Update    Delete
+DataCategories         N        Y         N         N
+DataItems              N        Y         N         N
+DataItemValues         N        Y         N         Y
+Profile List           -        Y         -         -
+Profiles               Y        -         -         Y
+ProfileCategories      -        Y         -         -
+ - drilldown           -        Y         -         -
+ProfileItems           Y        Y         Y         Y
+
+== INTERACTIVE SHELL
+
+You can use the 'ameesh' app to interactively explore the AMEE data area. Run
+'ameesh -u USERNAME -p PASSWORD -s SERVER' to try it out. Source code for this 
+tool is in bin/ameesh and lib/amee/shell.rb. Profiles are not accessible through
+this interface yet.
+
+== RAILS
+
+This gem can also be used as a Rails plugin. You can either extract it into
+vendor/plugins, or use the new-style config.gem command in environment.rb. For
+example:
+
+    config.gem "Floppy-amee", :lib => "amee", :source => "http://gems.github.com", :version => '>= 0.3.0'
+
+If you copy amee.example.yml from the gem source directory to amee.yml in your
+app's config directory, a persistent AMEE connection will be available from 
+AMEE::Rails#connection, which you can use anywhere. In your controllers, you can
+also use the global_amee_connection function to access the same global connection.
+
+    data = AMEE::Data::Category.root(global_amee_connection)
+
+If you do not use this facility, you will have to create your own connection
+objects and manage them yourself, which you can do using AMEE::Connection#new
+
+There is a helper for ActiveRecord models which should be linked to an AMEE profile.
+By adding:
+
+    has_amee_profile
+
+to your model, and by adding an amee_profile:string field to the model in the
+database, an AMEE profile will be automatically created and destroyed with your
+model. By overriding the function amee_save in your model, you can store data in
+AMEE when your model is saved.
+
+== CACHING
+
+The AMEE::Connection object implements an optional cache for GET requests. This is
+currently a versy simple implementation which caches the result of all GET requests
+until a POST, PUT, or DELETE is executed, at which point the cache is cleared. To
+enable caching, set the enable_caching parameter of AMEE::Connection.new to true.
+Caching is disabled by default.
+
+== UPGRADING TO VERSION > 2
+
+There are a few changes to the API exposed by this gem for version 2. The main
+ones are:
+
+1) AMEE::Connection#new takes a hash of options instead of an explicit parameter list.
+   Whereas before you would have used new(server, username, password, use_json, enable_cache, enable_debug)
+   you would now use new(server, username, password, :format => :json, :enable_caching => true, :enable_debug => true)
+
+2) Many get functions take a hash of options instead of explicit date and itemsPerPage parameters.
+   get(... , :start_date => {your_date}, :itemsPerPage => 20)
+
+3) total_amount_per_month functions have been replaced with total_amount. There are also
+   total_amount_unit and total_amount_per_unit functions which give the units that the total
+   amount is in.

data/amee.example.yml

@@ -0,0 +1,12 @@
+development:
+  server: stage.amee.com
+  username: your_amee_username
+  password: your_amee_password
+test:
+  server: stage.amee.com
+  username: your_amee_username
+  password: your_amee_password
+production:
+  server: live.amee.com
+  username: your_amee_username
+  password: your_amee_password

data/bin/ameesh

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+shell_lib   = File.dirname(__FILE__) + '/../lib/amee/shell'
+irb_name = RUBY_PLATFORM =~ /mswin32/ ? 'irb.bat' : 'irb'
+
+require 'optparse'
+# Command-line options - get username, password, and server
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u USERNAME", "AMEE username") do |u|
+    options[:username] = u
+  end
+  opts.on("-p PASSWORD", "AMEE password") do |p|
+    options[:password] = p
+  end
+  opts.on("-s SERVER", "AMEE server") do |s|
+    options[:server] = s
+  end
+end.parse!
+
+# Set environment variables for irb
+ENV['AMEE_SERVER'] = options[:server]
+ENV['AMEE_USERNAME'] = options[:username]
+ENV['AMEE_PASSWORD'] = options[:password]
+
+if options[:server].nil? || options[:username].nil? || options[:password].nil?
+  puts "Please provide connection details. Run 'ameesh --help' for details."
+else
+  exec "#{irb_name} -r #{shell_lib} --simple-prompt"
+end

data/examples/create_profile.rb

@@ -0,0 +1,27 @@
+dir = File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
+
+#require 'rubygems'
+require 'amee'
+require 'optparse'
+
+# Command-line options - get username, password, and server
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u", "--username USERNAME", "AMEE username") do |u|
+    options[:username] = u
+  end  
+  opts.on("-p", "--password PASSWORD", "AMEE password") do |p|
+    options[:password] = p
+  end
+  opts.on("-s", "--server SERVER", "AMEE server") do |s|
+    options[:server] = s
+  end
+end.parse!
+
+# Connect
+connection = AMEE::Connection.new(options[:server], options[:username], options[:password])
+
+# Create a new profile
+profile = AMEE::Profile::Profile.create(connection)
+puts "#{profile.uid} created"

data/examples/create_profile_item.rb

@@ -0,0 +1,33 @@
+dir = File.dirname(__FILE__) + '/../lib'
+$LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
+
+#require 'rubygems'
+require 'amee'
+require 'optparse'
+
+# Command-line options - get username, password, and server
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u", "--username USERNAME", "AMEE username") do |u|
+    options[:username] = u
+  end  
+  opts.on("-p", "--password PASSWORD", "AMEE password") do |p|
+    options[:password] = p
+  end
+  opts.on("-s", "--server SERVER", "AMEE server") do |s|
+    options[:server] = s
+  end
+end.parse!
+
+# Connect
+connection = AMEE::Connection.new(options[:server], options[:username], options[:password])
+
+# Create a new profile item
+category = AMEE::Profile::Category.get(connection, ARGV[0])
+puts "loaded category #{category.name}"
+item = AMEE::Profile::Item.create(category, ARGV[1])
+if item
+  puts "created item in #{category.name} OK"
+else
+  puts "error creating item in #{category.name}"
+end

data/examples/list_profiles.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'amee'
+require 'optparse'
+
+# Command-line options - get username, password, and server
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u", "--username USERNAME", "AMEE username") do |u|
+    options[:username] = u
+  end  
+  opts.on("-p", "--password PASSWORD", "AMEE password") do |p|
+    options[:password] = p
+  end
+  opts.on("-s", "--server SERVER", "AMEE server") do |s|
+    options[:server] = s
+  end
+end.parse!
+
+# Connect
+connection = AMEE::Connection.new(options[:server], options[:username], options[:password])
+
+# List all available profiles
+profiles = AMEE::Profile::Profile.list(connection)
+puts "#{profiles.size} #{profiles.size == 1 ? "profile" : "profiles"} available in AMEE:"
+profiles.each do |p|
+  puts p.uid
+end
+
+

data/examples/view_data_category.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'amee'
+require 'optparse'
+
+# Command-line options - get username, password, and server
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u", "--username USERNAME", "AMEE username") do |u|
+    options[:username] = u
+  end  
+  opts.on("-p", "--password PASSWORD", "AMEE password") do |p|
+    options[:password] = p
+  end
+  opts.on("-s", "--server SERVER", "AMEE server") do |s|
+    options[:server] = s
+  end
+end.parse!
+
+# Connect
+connection = AMEE::Connection.new(options[:server], options[:username], options[:password])
+
+# For each path in arg list, show details
+ARGV.each do |path|
+  cat = AMEE::Data::Category.get(connection, path)
+  puts "---------------------"
+  puts "Category: #{cat.name}"
+  puts "Path: #{cat.full_path}"
+  puts "UID: #{cat.uid}"
+  puts "Subcategories:"
+  cat.children.each do |c|
+    puts "  - #{c[:path]} (#{c[:name]})"
+  end
+  puts "Items:"
+  cat.items.each do |i|
+    puts "  - #{i[:path]} (#{i[:label]})"
+  end
+  
+end
+
+

data/examples/view_data_item.rb

@@ -0,0 +1,37 @@
+require 'rubygems'
+require 'amee'
+require 'optparse'
+
+# Command-line options - get username, password, and server
+options = {}
+OptionParser.new do |opts|
+  opts.on("-u", "--username USERNAME", "AMEE username") do |u|
+    options[:username] = u
+  end  
+  opts.on("-p", "--password PASSWORD", "AMEE password") do |p|
+    options[:password] = p
+  end
+  opts.on("-s", "--server SERVER", "AMEE server") do |s|
+    options[:server] = s
+  end
+end.parse!
+
+# Connect
+connection = AMEE::Connection.new(options[:server], options[:username], options[:password])
+
+# For each path in arg list, show details
+ARGV.each do |path|
+  cat = AMEE::Data::Item.get(connection, path)
+  puts "---------------------"
+  puts "Name: #{cat.name}"
+  puts "Path: #{cat.full_path}"
+  puts "Label: #{cat.label}"
+  puts "UID: #{cat.uid}"
+  puts "Values:"
+  cat.values.each do |v|
+    puts "  - #{v[:name]}: #{v[:value]}"
+  end
+  
+end
+
+

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/lib/amee.rb

@@ -0,0 +1,63 @@
+require 'rexml/document'
+require 'activesupport'
+
+# We don't NEED the JSON gem, but if it's available, use it.
+begin
+  require 'json'
+rescue LoadError
+  nil
+end
+
+class String
+  def is_json?
+    slice(0,1) == '{'
+  end
+  def is_v2_json?
+    is_json? && match('"apiVersion"\s?:\s?"2.0"')
+  end
+  def is_xml?
+    slice(0,5) == '<?xml'
+  end
+  def is_v2_xml?
+    is_xml? && include?('<Resources xmlns="http://schemas.amee.cc/2.0">')
+  end
+  def is_v2_atom?
+    is_xml? && (include?('<feed ') || include?('<entry ')) && include?('xmlns:amee="http://schemas.amee.cc/2.0"')
+  end
+end
+
+require 'amee/version'
+require 'amee/exceptions'
+require 'amee/connection'
+require 'amee/object'
+require 'amee/data_object'
+require 'amee/profile_object'
+require 'amee/data_category'
+require 'amee/data_item'
+require 'amee/data_item_value'
+require 'amee/profile'
+require 'amee/profile_category'
+require 'amee/profile_item'
+require 'amee/profile_item_value'
+require 'amee/drill_down'
+require 'amee/pager'
+require 'amee/item_definition'
+require 'amee/user'
+
+class Date
+  def amee1_date
+    strftime("%Y%m%d")
+  end
+  def amee1_month
+    strftime("%Y%m")
+  end
+end
+
+class Time
+  def amee1_date
+    strftime("%Y%m%d")
+  end
+  def amee1_month
+    strftime("%Y%m")
+  end
+end

data/lib/amee/connection.rb

@@ -0,0 +1,236 @@
+require 'net/http'
+
+module AMEE
+  class Connection
+
+    def initialize(server, username, password, options = {})
+      unless options.is_a?(Hash)
+        raise AMEE::ArgumentError.new("Fourth argument must be a hash of options!")
+      end
+      @server = server
+      @username = username
+      @password = password
+      @auth_token = nil
+      @format = options[:format] || (defined?(JSON) ? :json : :xml)
+      if !valid?
+       raise "You must supply connection details - server, username and password are all required!"
+      end
+      @enable_caching = options[:enable_caching]
+      if @enable_caching
+        $cache ||= {}
+      end
+      # Make connection to server
+      @http = Net::HTTP.new(@server)
+      @http.read_timeout = 5
+      @http.set_debug_output($stdout) if options[:enable_debug]
+    end
+
+    attr_reader :format
+    attr_reader :server
+    attr_reader :username
+    attr_reader :password
+    
+    def timeout
+      @http.read_timeout
+    end
+    
+    def timeout=(t)
+      @http.read_timeout = t
+    end
+
+    def version
+      authenticate if @version.nil?
+      @version
+    end
+
+    def valid?
+      @username && @password && @server
+    end
+    
+    def authenticated?
+      !@auth_token.nil?
+    end
+
+    def get(path, data = {})
+      # Allow format override
+      format = data.delete(:format) || @format
+      # Create URL parameters
+      params = []
+      data.each_pair do |key, value|
+        params << "#{CGI::escape(key.to_s)}=#{CGI::escape(value.to_s)}"
+      end
+      if params.size > 0
+        path += "?#{params.join('&')}"
+      end
+      # Send request
+      return $cache[path] if @enable_caching and $cache[path]
+      response = do_request(Net::HTTP::Get.new(path), format)
+      $cache[path] = response if @enable_caching
+      return response
+    end
+    
+    def post(path, data = {})
+      # Allow format override
+      format = data.delete(:format) || @format
+      # Clear cache
+      clear_cache
+      # Create POST request
+      post = Net::HTTP::Post.new(path)
+      body = []
+        data.each_pair do |key, value|
+        body << "#{CGI::escape(key.to_s)}=#{CGI::escape(value.to_s)}"
+      end
+      post.body = body.join '&'
+      # Send request
+      do_request(post, format)
+    end
+
+    def raw_post(path, body, options = {})
+      # Allow format override
+      format = options.delete(:format) || @format
+      # Clear cache
+      clear_cache
+      # Create POST request
+      post = Net::HTTP::Post.new(path)
+      post['Content-type'] = options[:content_type] || content_type(format)
+      post.body = body
+      # Send request
+      do_request(post, format)
+    end
+
+    def put(path, data = {})
+      # Allow format override
+      format = data.delete(:format) || @format
+      # Clear cache
+      clear_cache
+      # Create PUT request
+      put = Net::HTTP::Put.new(path)
+      body = []
+        data.each_pair do |key, value|
+        body << "#{CGI::escape(key.to_s)}=#{CGI::escape(value.to_s)}"
+      end
+      put.body = body.join '&'
+      # Send request
+      do_request(put, format)
+    end
+
+    def raw_put(path, body, options = {})
+      # Allow format override
+      format = options.delete(:format) || @format
+      # Clear cache
+      clear_cache
+      # Create PUT request
+      put = Net::HTTP::Put.new(path)
+      put['Content-type'] = options[:content_type] || content_type(format)
+      put.body = body
+      # Send request
+      do_request(put, format)
+    end
+
+    def delete(path)
+      clear_cache
+      # Create DELETE request
+      delete = Net::HTTP::Delete.new(path)
+      # Send request
+      do_request(delete)
+    end
+
+    def authenticate
+      response = nil
+      post = Net::HTTP::Post.new("/auth/signIn")
+      post.body = "username=#{@username}&password=#{@password}"
+      post['Accept'] = content_type(:xml)
+      response = @http.request(post)
+      @auth_token = response['authToken']
+      unless authenticated?
+        raise AMEE::AuthFailed.new("Authentication failed. Please check your username and password.") 
+      end
+      # Detect API version
+      if response.body.is_json?
+        @version = JSON.parse(response.body)["user"]["apiVersion"].to_f
+      elsif response.body.is_xml?
+        @version = REXML::Document.new(response.body).elements['Resources'].elements['SignInResource'].elements['User'].elements['ApiVersion'].text.to_f
+      else
+        @version = 1.0
+      end
+    end
+
+    protected
+
+    def content_type(format = @format)
+      case format
+      when :xml
+        return 'application/xml'
+      when :json
+        return 'application/json'
+      when :atom
+        return 'application/atom+xml'
+      end
+    end
+    
+    def redirect?(response)
+      response.code == '301' || response.code == '302'
+    end
+
+    def response_ok?(response)
+      case response.code
+        when '200', '201'
+          return true
+        when '403'
+          raise AMEE::PermissionDenied.new("You do not have permission to perform the requested operation. AMEE Response: #{response.body}")
+        when '401'
+          authenticate
+          return false
+        when '400'
+          if response.body.include? "would have resulted in a duplicate resource being created"
+            raise AMEE::DuplicateResource.new("The specified resource already exists. This is most often caused by creating an item that overlaps another in time. AMEE Response: #{response.body}")
+          else
+            raise AMEE::UnknownError.new("An error occurred while talking to AMEE: HTTP response code #{response.code}. AMEE Response: #{response.body}")
+          end
+        else
+          raise AMEE::UnknownError.new("An error occurred while talking to AMEE: HTTP response code #{response.code}. AMEE Response: #{response.body}")
+      end
+    end
+
+    def do_request(request, format = @format)
+      # Open HTTP connection
+      @http.start
+      # Do request
+      begin
+        response = send_request(request, format)
+      end while !response_ok?(response)
+      # Return response
+      return response
+    rescue SocketError
+      raise AMEE::ConnectionFailed.new("Connection failed. Check server name or network connection.")
+    ensure
+      # Close HTTP connection
+      @http.finish if @http.started?
+    end
+        
+    def send_request(request, format = @format)
+      # Set auth token in cookie (and header just in case someone's stripping cookies)
+      request['Cookie'] = "authToken=#{@auth_token}"
+      request['authToken'] = @auth_token
+      # Set accept header
+      request['Accept'] = content_type(format)
+      # Do the business
+      response = @http.request(request)
+      # Handle 404s
+      if response.code == '404'
+        raise AMEE::NotFound.new("URL doesn't exist on server.") 
+      end
+      # Done
+      response
+    end
+
+    public
+
+    def clear_cache
+      if @enable_caching
+        $cache = {}
+      end
+    end
+
+  end
+end