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, <quelcom@gmail.com>
=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