/ 
WebService-Buxfer-0.01
River stage zero No dependents
/ WebService::Buxfer

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 $new_transactions = [
    '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: ".($_->buxfer_status)."\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

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.