File Coverage

blib/lib/Net/ZooTool.pm

Criterion	Covered	Total	%
statement	1	3	33.3
branch			n/a
condition			n/a
subroutine	1	1	100.0
pod			n/a
total	2	4	50.0

package Net::ZooTool;
# ABSTRACT: a Moose interface to the Zootool API
use Moose;
with 'Net::ZooTool::Utils';

use Carp;

use Net::ZooTool::Auth;
use Net::ZooTool::User;
use Net::ZooTool::Item;

use namespace::autoclean;

our $VERSION = '0.003';

has auth => (
    isa => 'Net::ZooTool::Auth',
    is  => 'ro',
);

around BUILDARGS => sub {
    my $orig  = shift;
    my $class = shift;

    # Transform normal params to hashref
    if ( !ref $_[0] ) {
        if ( scalar @_ == 1 ) {
            return $class->$orig( apikey => $_[0] );
        }
        elsif ( scalar @_ == 3 ) {
            return $class->$orig( apikey => $_[0], user => $_[1], password => $_[2] );
        }
        else {
            croak "Unaccepted params";
        }
    }

    # Hashref checkings
    if ( ref $_[0] and !$_[0]->{apikey} ) {
        croak "You have to provide at least the apikey as either parameter or hashref";
    }

    # You need to provide username and password
    if ( defined $_[0]->{user} and !defined $_[0]->{password} ) {
        croak "If you provide user you also need to provide password";
    }

    if ( defined $_[0]->{password} and !defined $_[0]->{user} ) {
        croak "If you provide password you also need to provide username";
    }

    # If you have reached here everything is good

    return $class->$orig(@_);
};

sub BUILD {
    my $self = shift;
    my $args = shift;

    $self->{auth} = Net::ZooTool::Auth->new(
        {
            apikey   => $args->{apikey},
            user     => $args->{user},
            password => $args->{password},
        }
    );
}

sub user {
    my $self = shift;
    return Net::ZooTool::User->new({ auth => $self->auth });
}

sub item {
    my $self = shift;
    return Net::ZooTool::Item->new({ auth => $self->auth });
}

sub add {
    my ( $self, $args ) = @_;

    $args->{apikey} = $self->auth->apikey;

    my $data = _fetch('/add/' . _hash_to_query_string($args), $self->auth);
    return $data;
}

no Moose;
__PACKAGE__->meta->make_immutable;

1;

__END__

=pod

=head1 NAME

Net::ZooTool - Moose interface to the Zootool API: http://zootool.com

=head1 SYNOPSIS

    my $zoo = Net::ZooTool->new({ apikey   => $config{apikey} });

    my $weekly_popular = $zoo->item->popular({ type => "week" });

    # Info about a specific item
    print Dumper($zoo->item->info({ uid => "6a80z" }));

    # Examples with authenticated calls
    my $auth_zoo = Net::ZooTool->new(
        {
            apikey   => $config{apikey},
            user     => $config{user},
            password => $config{password},
        }
    );

    my $data = $auth_zoo->user->validate({ username => $config{user}, login => 'true' });
    print Dumper($data);

    # In some methods authentication is optional.
    # Public items only
    my $public_items = $auth_zoo->user->items({ username => $config{user} });
    # Include also your private items
    my $all_items = $auth_zoo->user->items({ username => $config{user}, login => 'true' });

=head1 DESCRIPTION

Net::ZooTool is a wrapper to the Zootool bookmarking service. It attempts to follow the api defined in http://zootool.com/api/docs/general as much as possible. Please refer to their API Documentation site for more information.

=head1 PACKAGE METHODS

=over 1

=item new(\%ARGS)

Create a new Net::ZooTool object.

Parameters:

=over 3

=item *

B<apikey>

I<string>. Your Zootool apikey (required)

=item *

B<user>

I<string>. Your Zootool username (optional)

=item *

B<password>

I<string>. Your Zootool password (optional)

=back

=back

=head1 OBJECT METHODS

=over 6

=item $zoo->user()

Net::ZooTool::User object

=item $zoo->item()

Net::ZooTool::Item object

=item $zoo->add(\%ARGS)

Adds a new item to your zoo (authentication is required).

Parameters:

=over 8

=item *

B<apikey>

I<string>. Your Zootool api key (required)

=item *

B<url>

I<string>. Url to add (required)

=item *

B<title>

I<string>. Item title (required)

=item *

B<tags>

I<string>. Comma separated if you want to include more than one (optional)

=item *

B<description>

I<string>. Entry description (optional)

=item *

B<referer>

I<string>. Entry referer, must be a valid url (optional)

=item *

B<public>

I<string>. Whether or not the item is public ('y' or 'n')

=item *

B<login>

I<boolean>. Add method requires authenticated call (required)

=back

=item $zoo->user->items(\%ARGS)

Get the latest items from all users or specify a username to get all items from a specific user. Authenticate to get all private items of a user as well. Use authentication if you want to get private items as well).

Parameters:

=over 6

=item *

B<apikey>

I<string>. Your Zootool api key (required)

=item *

B<username>

I<string>. Zootool username (required)

=item *

B<login>

I<string>. must be true if you want to make an authenticated call via digest (optional).

=item *

B<tag>

I<string>. Tag search (optional)

=item *

B<offset>

I<int>. Search offset (optional)

=item *

B<limit>

I<int>. Search limit (optional)

=item *

B<login>

I<boolean>. Set to true to get private items as well.

=back

=item $zoo->user->info(\%ARGS)

Get info about a certain user. Authentication is optional (if you want to get the email address from the user, you need to sign in).

Parameters:

=over 3

=item *

B<apikey>

I<string>. Your Zootool api key (required)

=item *

B<username>

I<string>. Zootool username (required)

=item *

B<login>

I<boolean>. Set to true to get email address

=back

=item $zoo->user->validate(\%ARGS)

Validate the user credentials. Useful for logins.

Parameters:

=over 2

=item *

B<apikey>

I<string>. Your Zootool api key (required)

=item *

B<username>

I<string>. Your zootool username (required)

=back

=back

=head1 SEE ALSO

http://zootool.com/

http://zootool.com/api/docs

=head1 AUTHOR

Josep Roca, <[e-mail]>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2011 by Josep Roca

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.

=cut