=head1 NAME

Finance::Bank::easybank - check your easybank accounts from Perl

=head1 SYNOPSIS

  # look for this script in the examples directory of the
  # tar ball (balance.pl).
  use Finance::Bank::easybank;
  
  use strict;
  use warnings;
  
  my $agent = Finance::Bank::easybank->new(
          user          => 'xxx',
          pass          => 'xxx',
          return_floats => 1,
  
          accounts      => [ qw/
                  200XXXXXXXX
                  / ],

          entries       => [ qw/
                  200XXXXXXXX
                  / ],
  );
  
  my @accounts = $agent->check_balance;
  my $entries  = $agent->get_entries;
  
  foreach my $account (@accounts) {
          printf("%11s: %25s\n", $_->[0], $account->{$_->[1]})
                  for(( [ qw/ Kontonummer account / ],
                        [ qw/ BLZ bc / ],
                        [ qw/ Bezeichnung name / ],
                        [ qw/ Datum date / ],
                        [ qw/ Waehrung currency / ]
                  ));
          printf("%11s: %25.2f\n", $_->[0], $account->{$_->[1]})
                  for(( [ qw/ Saldo balance / ],
                        [ qw/ Dispo final / ]
                  ));

          print "\nBuchungzeilen:\n\n";

          if(exists($entries->{$account->{account}})) {
                  foreach my $row (@{$entries->{$account->{account}}}) {
                        $row->{text} =~ s/(.{43}).*/$1.../;

                        printf("%2d %6s %46s %6s %3s %9.2f\n", 
                                (map { $row->{$_} } qw/nr date text value currency/), 
                                $row->{amount}
                        );      
                  }
          }

          print "\n";
  }
 

=head1 DESCRIPTION

This module provides a basic interface to the online banking system of
the easybank at C<http://www.easybank.at>.

Please note, that you will need either C<Crypt::SSLeay> or C<IO::Socket::SSL>
installed for working HTTPS support of C<LWP>.

=head1 METHODS

=over

=item check_balance

Queries all via attribute C<accounts> defined accounts and extracts
various informations about the account status.

If called in list context, returns an array of hashes containing all
fetched information:

 $VAR = [
          {
            'bc'        => bank code
            'account'   => account number
            'name'      => name of the account
            'date'      => date shown on the summary page
                           (format: DD.MM.YYYY/hh:mm)
            'currency'  => currency
            'balance'   => account balance
            'final'     => final account balance
          }
        ];

Otherwise, returns a hashref:

  $VAR1 = {
          'account' => {
              'bc'        => bank code
              'account'   => account number
              'name'      => name of the account
              'date'      => date shown on the summary page
                             (format: DD.MM.YYYY/hh:mm)
              'currency'  => currency
              'balance'   => account balance
              'final'     => final account balance
            }
          };

=item get_entries

Queries and parses the first page of the entry-history for all
accounts defined via the C<entries> attribute. 

Returns a hashref containing all fetched information:

  $VAR1 = {
          'account' => {
              'date'     => date of the transaction
                            (format: DD.MM.)
              'text'     => posting text
              'value'    => value date
                            (format: DD.MM.)
              'currency' => currency
              'amount'   => transfer amount
            }
          };

=back

=head1 ATTRIBUTES

All attributes are implemented by C<Class::MethodMaker>, so please take a
look at its man page for further information about the created accessor
methods.

=over

=item user

User to connect with (Verfuegernummer).

=item pass

Password to connect with (Pin).

=item accounts

Optional list of accounts to query by C<check_balance>. This list should
contain only account numbers formated in exactly the same way as they are
listed in the online banking system.

=item entries

Optional list of accounts to query by C<get_entries>. This list should
contain only account numbers formated in exactly the same way as they are
listed in the online banking system.

=item return_floats

Boolean value defining wether the module returns the balance as signed
float or just as it gets it from the online banking system (default:
false).

=back

=head1 EXAMPLES

In the C<examples> directory of the distribution are two example scripts
which show the usage of this module. Both scripts can be used out of
the box and should represent a good starting point for a solution which
fits your particular needs (I use a copy of C<balance-gpg.pl> on a daily
basis).

=over

=item balance.pl

The very same script as seen in the C<SYNOPSIS>. Shows the basic usage,
defines all authentication settings directly in the script.

The main problem with this approach is of course the fact, that the
sensible authentication data is stored in clear text in the script
itself. Not a good thing at all if you're using it in an multiuser
environment or on a mobile computer.

But do not fear - help in form of GPG is on the way (see C<balance-gpg.pl>).

=item balance-gpg.pl

This script does the same thing as C<balance.pl> but gets all the
configuration settings from an C<GPG> encrypted file which is decrypted
on the fly at startup, C<GPG> will interactive ask for your passphrase.

To use this example script you need to set up C<GPG> and install
C<GnuPG::Interface>, C<IO::File>, C<IO::Handle> and C<YAML> on your
machine.

The encrypted file should have the following structure (in case of C<YAML>):

  user:          XXX
  pass:          XXX
  return_floats: 1
  accounts:
    - 200XXXXXXX1
    - 200XXXXXXX2
  entries:
    - 200XXXXXXX1
    - 200XXXXXXX2

The layout may differ, depending on the module you are using for
serialization.

=back

=head1 WARNING

This is code for B<online banking>, and that means B<your money>, and that
means B<BE CAREFUL>. You are encouraged, nay, expected, to audit the source 
of this module yourself to reassure yourself that I am not doing anything 
untoward with your banking data. This software is useful to me, but is 
provided under B<NO GUARANTEE>, explicit or implied.

=head1 CAVEATS

I didn't had the chance of testing this module against an account mapped
to only one bank account.

It would be very nice if someone with only one bank account could test
this module and drop me note about the results.

Also take note that this module can break easily if easybank changes the
layout of the online banking system.

=head1 THANKS

Simon Cozens <simon@cpan.org> for C<Finance::Bank::LloydsTSB> from which I've
borrowed the warning message.

Chris Ball <chris@cpan.org> for his article about screen-scraping with
C<WWW::Mechanize> at C<http://www.perl.com/pub/a/2003/01/22/mechanize.html>.

=head1 AUTHOR

Florian Helmberger <fh@laudatio.com>

=head1 VERSION

$Id: easybank.pod,v 1.2 2003/08/14 21:31:56 florian Exp $

=head1 COPYRIGHT AND LICENCE

You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl README file.

Copyright (C) 2003 Florian Helmberger

=head1 SEE ALSO

L<WWW::Mechanize>, L<HTML::TokeParser>, L<Class::MethodMaker>.

=cut
