NAME

WebService::Buxfer - Interact with the Buxfer webservice

SYNOPSIS

      use strict;
      use warnings;
      use WebService::Buxfer;
  
      my $bux = WebService::Buxfer->new(
          {
              userid => 'nheinrichs',                 # Required
              password => 'my password',              # Required
  
              preload_accounts => 1,                  # Default
              inject_account_name => 1,               # Default
              debug => 0,                             # Default
              url => 'https://www.buxfer.com/api',    # Default
          }
          );
  
      my $results = $bux->transactions;
      print "Transaction: ".Dumper($)."\n" for (@$results);
  
      my $newtransactions = [
          'coffee 5.45 tags:drinks,coffee',       # Raw, Buxfer SMS format
          'Pay check +6952.32 status:pending',    # Raw, Buxfer SMS format
          {                                       # As a hashref
              description => 'Thai food with friends',
              amount => -3000,
              payer => 'me',
              tags => ['sustenance, 'thai food'],
              account => 'cash',
              date => '2009-01-03',
              status => 'default',
              participants => [ [andy, 1000], elena ],
          },
          ];
  
      my @responses = $bux->add_transactions($new_transactions);
      print "Response: ".($->buxferstatus)."\n" for (@responses);

DESCRIPTION

Buxfer is an online personal finance site: <http://www.buxfer.com>

WebService::Buxfer provides access to the Buxfer webservices API.

ACCESSORS

• preload_accounts - Whether to prefetch account details on login
• inject_account_name - Whether to automatically inject an 'accountName' field into results that contain an internal Buxfer 'accountId' field.
• debug - Enable debug output
• url - The URL of the Buxfer API server. You probably don't need to change this.
• response - The WebService::Buxfer::Response object from the last call
• token - The value of the authentication token received from Buxfer

METHODS
new( \%options )
Build a new WebService::Buxfer instance.

GET methods
transactions(\%params), analysis(\%params) Retrieve transactions (25 at a time.)

Results can be restricted using the following parameters (see Buxfer API documentation for details):

• accountId OR accountName
• tagId OR tagName
• startDate AND endDate OR month: date can be specified as "10 feb 2008", or "2008-02-10". month can be specified as "feb08", "feb 08", or "feb 2008".
• budgetId OR budgetName
• contactId OR contactName
• groupId OR groupName
• page - the page of results you want to see ("transactions" only)

NOTE: On any given day the format of the 'date' field in the transactions seems to change (sometimes I get '3 Jan' and sometimes '3 Jan 08'.)

This package makes no attempt to format or inflate dates or any other information returned from the API.

analysts(\%params)
Get Analysis graph URLs and rawData.

Takes the same parameters as "transactions".

Returns a hashref of Analysis information.

accounts()
Retrieve Buxfer accounts.

In array context returns an array of hashrefs containing account details.

In scalar context returns a hashref of account details keyed on the internal Buxfer accountId.

i.e., { $accountId => { name => 'cash', ... }, ... }

impacts, tags, budgets, groups, contacts Calls the given Buxfer API. See Buxfer docs for details.

In array context returns an array of results.

In scalar context returns a reference to the array of results.

POST methods
add_transactions(\@transactions, \%params) Accepts an array of transactions in raw format or as hashrefs and submits them to Buxfer using the "add_transaction" API call.

Because the Buxfer API allows for submission of multiple transactions in a single API call, this method will combine transactions into batches based on the "max_transactions_per_submit" parameter prior to submission.

WebService::Buxfer will also wrap tags containing spaces in single quotes. HOWEVER, the quotes themselves will also end up as part of the tag.

This is the fault of Buxfer's parser: if the single quotes are omitted, the system will fail to parse/import the transaction properly.

Parameters

• max_transactions_per_submit - I was able to submit 1000 transactions in a single call, so that is the default.
• format - Currently only 'sms' is supported

In array context returns an array of responses.

In scalar context returns a reference to the responses array.

SEE ALSO

• Buxfer - <http://www.buxfer.com>
• Buxfer API Documentation - <https://www.buxfer.com/api>

TODO

Move some of the logic out of here and into WebService::Buxfer::Response.

Add a pager for flipping through transactions based on 25 results per page and numTransactions in the response.

Automatically in/deflate DateTime objects

ACKNOWLEDGEMENTS

Portions of this package borrowed/adapted from the WebService::Solr code.

Thanks to Brian Cassidy and Kirk Beers for that package.

AUTHORS

Nathaniel Heinrichs <nheinric@cpan.org>

COPYRIGHT AND LICENSE

     Copyright (c) 2009 Nathaniel Heinrichs.
     This program is free software; you can redistribute it and/or
     modify it under the same terms as Perl itself.