buxfer 0.1 → 0.2

data/CHANGELOG

@@ -1 +1,3 @@
+v0.2 Added a proper class structure and documentation.
+
 v0.1 First version of Buxfer API.

data/Manifest

@@ -1,6 +1,14 @@
 CHANGELOG
 LICENSE
 Manifest
-README
+README.rdoc
 Rakefile
+buxfer.gemspec
 lib/buxfer.rb
+lib/buxfer/account.rb
+lib/buxfer/base.rb
+lib/buxfer/report.rb
+lib/buxfer/tag.rb
+spec/lib/base_spec.rb
+spec/spec.opts
+spec/spec_helper.rb

data/README.rdoc

@@ -0,0 +1,43 @@
+Buxfer is a library for accessing the buxfer API (http://www.buxfer.com).
+
+== Requirements:
+
+* HTTParty 0.5.0
+* ActiveSupport 2.3.4
+
+== Install:
+
+* sudo gem install buxfer
+
+== Usage:
+
+  require 'buxfer'
+
+  Buxfer.auth('username', 'password')
+  accounts = Buxfer.accounts.all => [Buxfer::Account(name => 'Savings')]
+  accounts.first.transactions    => [amount => 30.0, description => 'Petrol']
+
+== License
+
+Copyright (c) 2009 Jeremy Wells
+
+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/buxfer.gemspec

@@ -2,17 +2,17 @@
 
 Gem::Specification.new do |s|
   s.name = %q{buxfer}
-  s.version = "0.1"
+  s.version = "0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jeremy Wells"]
-  s.date = %q{2009-12-28}
+  s.date = %q{2009-12-29}
   s.description = %q{A library providing access to buxfer (www.buxfer.com) API based on HTTParty.}
   s.email = %q{}
-  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README", "lib/buxfer.rb"]
-  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README", "Rakefile", "lib/buxfer.rb", "buxfer.gemspec"]
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.rdoc", "lib/buxfer.rb", "lib/buxfer/account.rb", "lib/buxfer/base.rb", "lib/buxfer/report.rb", "lib/buxfer/tag.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.rdoc", "Rakefile", "buxfer.gemspec", "lib/buxfer.rb", "lib/buxfer/account.rb", "lib/buxfer/base.rb", "lib/buxfer/report.rb", "lib/buxfer/tag.rb", "spec/lib/base_spec.rb", "spec/spec.opts", "spec/spec_helper.rb"]
   s.homepage = %q{}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Buxfer", "--main", "README"]
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Buxfer", "--main", "README.rdoc"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{buxfer}
   s.rubygems_version = %q{1.3.5}

data/lib/buxfer.rb

@@ -1,76 +1,17 @@
 require 'httparty'
 require 'active_support'
+require 'ostruct'
 
-class Buxfer
-  include HTTParty
-  base_uri 'https://www.buxfer.com/api'
-  format :xml
-
-  def initialize(username, password)
-    @username = username
-    @password = password
-  end
-
-  def add_transaction(amount, description, account = nil, status = nil, tags = [])
-    amount = (amount < 0 ? amount.to_s : '+' + amount.to_s)
-    tags = tags.join(',')
-    attrs = {}
-    text = [description, amount]
-
-    {:acct => account, :status => status, :tags => tags}.each do |k, v|
-      text << '%s:%s' % [k, v] unless v.blank?
-    end
-
-    self.class.post('/add_transaction.xml', auth_query({:text => text, :format => 'sms'}, :body))
-  end
-
-  def upload_statement(accountId, statement, dateFormat = 'DD/MM/YYYY')
-    unless statement.is_a?(String)
-      if statement.respond_to?(:read)
-        statement = statement.read
-      else chec
-        statement = statement.to_s
-      end
-    end
-
-    options = {:accountId => accountId, :statement => statement, :dateFormat => dateFormat}
-
-    self.class.post('/upload_statement.xml', auth_query(options, :body))
+module Buxfer
+  class Response < OpenStruct
+    undef_method :id
+    undef_method :type
   end
+end
 
-  def transactions(options = {})
-    self.class.get('/transactions.xml', auth_query(options))['response']['transactions']['transaction']
-  end
-  
-  def reports(options = {})
-    self.class.get('/reports.xml', auth_query(options))
-  end
+$: << File.dirname(__FILE__)
 
-  def accounts
-    self.class.get('/accounts.xml', auth_query)['response']['accounts']['account']
-  end
-
-  def loans
-    self.class.get('/loans.xml', auth_query)
-  end
-
-  def tags
-    self.class.get('/tags.xml', auth_query)['response']['tags']['tag']
-  end
-
-  private
-
-  def auth
-    @auth ||= begin
-      self.class.get('/login.xml', :query => {:userid => @username, :password => @password})
-    end
-  end
-
-  def token
-    auth['response']['token']
-  end
-
-  def auth_query(options = {}, container = :query)
-    {container => options.merge(:token => token)}
-  end
-end
+require 'buxfer/base'
+require 'buxfer/account'
+require 'buxfer/tag'
+require 'buxfer/report'

data/lib/buxfer/account.rb

@@ -0,0 +1,49 @@
+module Buxfer
+  class Account < OpenStruct
+    # Returns an array of accounts. See Buxfer::Base#accounts
+    #
+    # Example:
+    #   Buxfer::Account.all
+    #
+    def self.all
+      Buxfer.accounts
+    end
+
+    # Return an array of the last 25 transactions for this account.
+    # See Buxfer::Base#transactions for valid options.
+    def transactions(options = {})
+      Buxfer.transactions(options.merge(:account => self))
+    end
+
+    # Add a transaction to Buxfer. The amount and description must be
+    # specified.
+    #
+    # An array of tag names can be specified.
+    #
+    # Examples:
+    #
+    #   account.add_transaction(1000, 'Salary')
+    #
+    # See: http://www.buxfer.com/help.php?topic=API#add_transaction
+    def add_transaction(amount, description, status = nil, tags = [])
+      Buxfer.add_transaction(amount, description, self.name, status, tags)
+    end
+
+    # Upload a file containing a transaction statement to Buxfer account.
+    #
+    # The statement can be a String or an IO object.
+    #
+    # An optional date format can be passed indicating if the dates used in the statement
+    # are in the format 'DD/MM/YYYY' (default) or 'MM/DD/YYYY'
+    #
+    # Example:
+    #
+    #   account = Buxfer.accounts.first
+    #   account.upload_statement(open('/path/to/file')) => true
+    #
+    # http://www.buxfer.com/help.php?topic=API#upload_statement
+    def upload_statement(statement, date_format = 'DD/MM/YYYY')
+      Buxfer.upload_statement(self.id, statement, date_format)
+    end
+  end
+end

data/lib/buxfer/base.rb

@@ -0,0 +1,214 @@
+# The Buxfer API methods can be called on the Buxfer module after calling
+# the #auth method. See Buxfer::Base for more information on each API call.
+module Buxfer
+  # Specify the authentication details for connecting to Buxfer
+  def self.auth(username, password)
+    @username = username
+    @password = password
+    @connection = nil
+  end
+
+  def self.method_missing(method, *args) #:nodoc:
+    if connection.respond_to?(method)
+      connection.send(method, *args)
+    else
+      super
+    end
+  end
+
+  private
+
+  # The username that will be used
+  def self.username
+    @username
+  end
+
+  # The password that will be used
+  def self.password
+    @password
+  end
+
+  def self.connection #:nodoc:
+    @connection ||= Buxfer::Base.new(username, password)
+  end
+
+  public
+
+  # The Buxfer::Base class provides the API methods. It can be instansiated directly
+  # or a default instance is used with the Buxfer module.
+  #
+  # Default usage:
+  #
+  #   Buxfer.auth('username', 'password')
+  #   Buxfer.accounts
+  #
+  # Instance usage:
+  #
+  #  client = Buxfer::Base.new('username', 'password')
+  #  client.accounts
+  #
+  class Base
+    include HTTParty
+    base_uri 'https://www.buxfer.com/api'
+    format :xml
+
+    # Create a new Buxfer::Base object with a username and password.
+    def initialize(username, password)
+      @username = username
+      @password = password
+    end
+
+    # Add a transaction to Buxfer. The amount and description must be
+    # specified.
+    #
+    # An account name or Buxfer::Account object can be specified
+    # if the transaction is to be associated with a particular account.
+    #
+    # An array of tag names can be specified.
+    #
+    # Examples:
+    #
+    #   Buxfer.add_transaction(-10.0, 'Internet bill', 'Current account', nil, %w(bill payment))
+    #   Buxfer.add_transaction(1000, 'Salary', 'Current account', 'pending', %w(salary))
+    #
+    # See: http://www.buxfer.com/help.php?topic=API#add_transaction
+    def add_transaction(amount, description, account = nil, status = nil, tags = [])
+      amount = (amount < 0 ? amount.to_s : '+' + amount.to_s)
+      tags = tags.join(',')
+      attrs = {}
+      text = [description, amount]
+      account.respond_to?(:name) ? account.name : account.to_s
+
+      {:acct => account, :status => status, :tags => tags}.each do |k, v|
+        text << '%s:%s' % [k, v] unless v.blank?
+      end
+
+      self.class.post('/add_transaction.xml', auth_query({:text => text, :format => 'sms'}, :body))
+    end
+
+    # Upload a file containing a transaction statement to Buxfer account. The account
+    # specified can be a Buxfer::Account (see #accounts) or an account id string.
+    #
+    # The statement can be a String or an IO object.
+    #
+    # An optional date format can be passed indicating if the dates used in the statement
+    # are in the format 'DD/MM/YYYY' (default) or 'MM/DD/YYYY'
+    #
+    # Example:
+    #
+    #   account = Buxfer.accounts.first
+    #   Buxfer.upload_statement(account, open('/path/to/file')) => true
+    #
+    # http://www.buxfer.com/help.php?topic=API#upload_statement
+    def upload_statement(account, statement, date_format = 'DD/MM/YYYY')
+      account_id = account.is_a?(Buxfer::Account) ? account.id : account
+      
+      unless statement.is_a?(String)
+        if statement.respond_to?(:read)
+          statement = statement.read
+        else
+          statement = statement.to_s
+        end
+      end
+
+      options = {:accountId => account_id, :statement => statement, :dateFormat => date_format}
+
+      self.class.post('/upload_statement.xml', auth_query(options, :body))
+    end
+
+    # Return an array of the last 25 transactions.
+    #
+    # Valid options:
+    #
+    # * <tt>:account</tt> - A Buxfer::Account or account name
+    # * <tt>:tag</tt> - A Buxfer::Tag object or tag name
+    # * <tt>:startDate</tt> - Date in format '10 feb 2008' or '2008-02-10'
+    # * <tt>:endDate</tt> - Date in format '10 feb 2008' or '2008-02-10'
+    # * <tt>:month</tt> - Month name and year in short format 'feb 08'
+    #
+    # http://www.buxfer.com/help.php?topic=API#transactions
+    def transactions(options = {})
+      options.symbolize_keys!
+
+      if account = options.delete(:account)
+        options[:accountName] = account.is_a?(Buxfer::Account) ? account.name : account
+      end
+
+      if tag = options.delete(:tag)
+        options[:tagName] = tag.is_a?(Buxfer::Tag) ? tag.name : tag
+      end
+
+      get_collection('transactions', options)
+    end
+
+    # Return a Buxfer::Report object.
+    #
+    # http://www.buxfer.com/help.php?topic=API#reports
+    def reports(options = {})
+      Buxfer::Report.new(get('/reports.xml', auth_query(options))['response'])
+    end
+
+    # Returns an array of Buxfer::Account objects
+    #
+    # http://www.buxfer.com/help.php?topic=API#accounts
+    def accounts
+      get_collection 'accounts', :class => Buxfer::Account
+    end
+
+    # Returns an array of Buxfer::Tag objects
+    #
+    # http://www.buxfer.com/help.php?topic=API#tags
+    def tags
+      get_collection 'tags', :class => Buxfer::Tag
+    end
+
+    # http://www.buxfer.com/help.php?topic=API#loans
+    def loans;     get_collection('loans');     end
+    # http://www.buxfer.com/help.php?topic=API#budgets
+    def budgets;   get_collection('budgets');   end
+    # http://www.buxfer.com/help.php?topic=API#reminders
+    def reminders; get_collection('reminders'); end
+    # http://www.buxfer.com/help.php?topic=API#groups
+    def groups;    get_collection('groups');    end
+    # http://www.buxfer.com/help.php?topic=API#contacts
+    def contacts;  get_collection('contacts');  end
+
+    private
+
+    def get(*args)
+      self.class.get(*args)
+    end
+
+    def get_collection(plural, options = {})
+      options.symbolize_keys!
+      path = options.delete(:path) || '/%s.xml' % plural
+      singular = options.delete(:singular) || plural.singularize
+      klass = options.delete(:class) || Buxfer::Response
+
+      response = get(path, auth_query(options))['response']
+      load_collection(response[plural][singular], klass)
+    end
+
+    def load_collection(collection, klass = Buxfer::Response)
+      if collection.respond_to?(:map)
+        collection.map{|item| klass.new(item) }
+      else
+        [klass.new(collection)]
+      end
+    end
+
+    def auth
+      @auth ||= begin
+        self.class.get('/login.xml', :query => {:userid => @username, :password => @password})
+      end
+    end
+
+    def token
+      auth['response']['token']
+    end
+
+    def auth_query(options = {}, container = :query)
+      {container => options.merge(:token => token)}
+    end
+  end
+end

data/lib/buxfer/report.rb

@@ -0,0 +1,30 @@
+module Buxfer
+  class Report
+    def initialize(data)
+      @data = data['analysis']
+      @tags = [@data['rawData']['item']].flatten.map do |item|
+        Buxfer::Tag.new(:name => item['tag'], :amount => item['amount'].to_f)
+      end
+    end
+
+    def image_url
+      @data['imageURL']
+    end
+
+    def [](value)
+      tags.detect{|tag| tag.name == value }
+    end
+
+    def tags
+      @tags
+    end
+
+    def tag_names
+      tags.map(&:name)
+    end
+
+    def to_s
+      tags.collect{|t| [t.name, t.amount].join(': ') }.join("\n")
+    end
+  end
+end

data/lib/buxfer/tag.rb

@@ -0,0 +1,13 @@
+module Buxfer
+  class Tag < OpenStruct
+    # Return an array of the last 25 transactions for this tag.
+    # See Buxfer::Base#transactions for valid options.
+    def transactions(options = {})
+      Buxfer.transactions(options.merge(:tag => self))
+    end
+
+    def report(options = {})
+      Buxfer.reports(options.merge(:tagName => self.name))
+    end
+  end
+end

data/spec/lib/base_spec.rb

@@ -0,0 +1,61 @@
+require 'spec/spec_helper'
+
+describe Buxfer do
+  describe '::auth' do
+    it 'should reset the connection'
+  end
+
+  describe '::connection' do
+    it 'should create a new connection'
+  end
+end
+
+describe Buxfer::Base do
+  before do
+    @base = Buxfer::Base.new('username', 'password')
+    @base.stub!(:token).and_return('token')
+    @base.class.stub!(:get)
+  end
+
+  describe '#tags' do
+    it 'should return a collection of Buxfer::Tag objects'
+  end
+
+  describe '#accounts' do
+    it 'should return a collection of Buxfer::Account objects'
+  end
+
+  %w(loans budgets reminders groups contacts).each do |type|
+    describe "##{type}" do
+      before do
+        @response = {
+            'response' => {
+                type => {
+                    type.singularize => [
+                        {'id' => 1},
+                        {'id' => 2}
+                    ]
+                }
+            }
+        }
+        @base.class.stub!(:get).and_return(@response)
+      end
+
+      it "should call get on the path /#{type}.xml" do
+        @base.class.should_receive(:get).with("/#{type}.xml", anything).and_return(@response)
+        @base.send(type)
+      end
+
+      it "should pass the auth token with the get request" do
+        @base.class.should_receive(:get).with(anything, :query => {:token => 'token'}).and_return(@response)
+        @base.send(type)
+      end
+
+      it "should load the collection from response[#{type}][#{type.singularize}]" do
+        @base.send(type).first.should be_a(Buxfer::Response)
+        @base.send(type).first.id.should == 1
+        @base.send(type).last.id.should == 2
+      end
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,3 @@
+--color
+--reverse
+--debugger

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'rubygems'
+load 'lib/buxfer.rb'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: buxfer
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Jeremy Wells
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-28 00:00:00 +13:00
+date: 2009-12-29 00:00:00 +13:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,16 +47,27 @@ extensions: []
 extra_rdoc_files: 
 - CHANGELOG
 - LICENSE
-- README
+- README.rdoc
 - lib/buxfer.rb
+- lib/buxfer/account.rb
+- lib/buxfer/base.rb
+- lib/buxfer/report.rb
+- lib/buxfer/tag.rb
 files: 
 - CHANGELOG
 - LICENSE
 - Manifest
-- README
+- README.rdoc
 - Rakefile
-- lib/buxfer.rb
 - buxfer.gemspec
+- lib/buxfer.rb
+- lib/buxfer/account.rb
+- lib/buxfer/base.rb
+- lib/buxfer/report.rb
+- lib/buxfer/tag.rb
+- spec/lib/base_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
 has_rdoc: true
 homepage: ""
 licenses: []
@@ -68,7 +79,7 @@ rdoc_options:
 - --title
 - Buxfer
 - --main
-- README
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement