view release on metacpan or  search on metacpan

lib/Business/Monzo.pm  view on Meta::CPAN

methods.

Please note this library is very much a work in progress, as is the Monzo API.
Also note the Monzo were previously called Mondo, so if you see any references
to Mondo they are either typos or historical references that have not yet been
updated to reflect the changes.

All objects within the Business::Monzo namespace are immutable. Calls to methods
will, for the most part, return new instances of objects.

=head1 SYNOPSIS

    my $monzo = Business::Monzo->new(
        token   => $token, # REQUIRED
        api_url => $url,   # optional
    );

    # transaction related information
    my @transactions = $monzo->transactions( account_id => $account_id );

    my $Transaction  = $monzo->transaction( id => 1 );

    $Transaction->annotate(
        foo => 'bar',
        baz => 'boz,
    );

    my $annotations = $Transaction->annotations;

    # account related information
    my @accounts = $monzo->accounts;

    foreach my $Account ( @accounts ) {

        my @transactions = $Account->transactions;

        $Account->add_feed_item(
            params => {
                title     => 'My Feed Item',
                image_url => 'http://...',
            }
        );

        # balance information
        my $Balance = $Account->balance;

        # webhooks
        my @webhooks = $Account->webhooks;

        my $Webhook = $Account->register_webhook(
            callback_url => 'http://www.foo.com',
        );

        $Webhook->delete
    }

    # pots
    my @pots = $monzo->pots();

    # attachments
    my $Attachment = $monzo->upload_attachment(
        file_name => 'foo.png',
        file_type => 'image/png',
    );

    $Attachment->register(
        external_id => 'my_id'
    );

    $Attachment->deregister;

=head1 ERROR HANDLING

Any problems or errors will result in a Business::Monzo::Exception
object being thrown, so you should wrap any calls to the library in the
appropriate error catching code (ideally a module from CPAN):

    try {
        ...
    }
    catch ( Business::Monzo::Exception $e ) {
        # error specific to Business::Monzo
        ...
        say $e->message;  # error message
        say $e->code;     # HTTP status code
        say $e->response; # HTTP status message

        # ->request may not always be present
        say $e->request->{path}    if $e->request;
        say $e->request->{params}  if $e->request;
        say $e->request->{headers} if $e->request;
        say $e->request->{content} if $e->request;
    }
    catch ( $e ) {
        # some other failure?
        ...
    }

You can view some useful debugging information by setting the MONZO_DEBUG
env varible, this will show the calls to the Monzo endpoints as well as a
stack trace in the event of exceptions:

    $ENV{MONZO_DEBUG} = 1;

=cut

use strict;
use warnings;

use Moo;
with 'Business::Monzo::Version';

$Business::Monzo::VERSION = '0.13';

use Carp qw/ confess /;

use Business::Monzo::Client;
use Business::Monzo::Account;
use Business::Monzo::Pot;
use Business::Monzo::Attachment;

lib/Business/Monzo.pm  view on Meta::CPAN

        message => "balance requires params: account_id",
    });

    return Business::Monzo::Account->new(
        client => $self->client,
        id     => $params{account_id},
    )->balance( %params );
}

=head2 transaction

    my $Transaction = $monzo->transaction(
        id     => $id,
        expand => 'merchant'
    );

Get a transaction. Will return a L<Business::Monzo::Transaction> object

=cut

sub transaction {
    my ( $self,%params ) = @_;

    if ( my $expand = delete( $params{expand} ) ) {
        $params{'expand[]'} = $expand;
    }

    return $self->client->_get_transaction( \%params );
}

=head2 accounts

    $monzo->accounts;                                   # all accounts
    $monzo->accounts( account_type => "uk_prepaid" );   # prepaid accounts
    $monzo->accounts( account_type => "uk_retail" );    # current accounts

Get a list of accounts. Will return a list of L<Business::Monzo::Account>
objects

=cut

sub accounts {
    my ( $self,%params ) = @_;
    return $self->client->_get_accounts( \%params );
}

=head2 pots

    $monzo->pots;

Get a list of pots. Will return a list of L<Business::Monzo::Pot>
objects

=cut

sub pots {
    my ( $self ) = @_;
    return $self->client->_get_pots;
}

sub upload_attachment {
    my ( $self,%params ) = @_;

    return Business::Monzo::Attachment->new(
        client => $self->client,
    )->upload( %params );
}

=head1 PAGINATION

As per the Monzo docs: L<https://monzo.com/docs/#pagination> - you can pass
through arguments to the methods (e.g. C<transactions>) to limit the return
data or set date ranges, etc:

    # last three months transactions, but only show 5
    my $since = DateTime->now->subtract( months => 3 )->iso8601 . "Z";
    my $limit = 5;

    foreach my $transaction (
        $monzo->transactions(
            account_id => $account_id,
            limit      => $limit,
            since      => $since,
        )
    {
        ...
    }

The supported pagination keys are C<limit>, C<since>, and C<before> - where
C<since> can be an RFC 3339-encoded timestamp or an object id, and C<before>
can be an RFC 3339-encoded timestamp. C<limit> should always be an integer.

=head1 EXAMPLES

See the t/002_end_to_end.t test included with this distribution. you can run
this test against the Monzo emulator by running end_to_end_emulated.sh (this
is advised, don't run it against a live endpoint).

You can also see the scripts in the bin/ directory included in this dist for
more examples.

=head1 SEE ALSO

L<Business::Monzo::Account>

L<Business::Monzo::Attachment>

L<Business::Monzo::Balance>

L<Business::Monzo::Transaction>

L<Business::Monzo::Webhook>

=head1 AUTHOR

Lee Johnson - C<leejo@cpan.org>

With contributions from:

    Chris Merry
    Aaron Moses
    Dave Cross

=head1 LICENSE

This library is free software; you can redistribute it and/or modify it under