File Coverage

blib/lib/Net/Backpack.pm

Criterion	Covered	Total	%
statement	24	396	6.0
branch	0	124	0.0
condition	1	36	2.7
subroutine	8	49	16.3
pod	40	40	100.0
total	73	645	11.3

=head1 NAME

Net::Backpack - Perl extension for interfacing with Backpack.

=head1 SYNOPSIS

    use strict; use warnings;
    use Net::Backpack;

    my $bp = Net::Backpack(
        user  => $your_backpack_username,
        token => $your_backpack_api_token,
        ssl   => $use_ssl
    );

    # Fill out a Perl data structure with information about your Backspace pages.
    my $std_pages = $bp->list_all_pages;

    # Alternatively get the same information in XML format
    my $xml_pages = $bp->list_all_pages(xml => 1);

    # Create a new page
    my $page = $bp->create_page(
        title       => 'A test page',
        description => 'Created with the Backpack API'
    );

    # Get the id of the new page
    my $page_id = $page->{page}{id};

    # Get details of the new page (in XML format)
    my $page_xml = $bp->show_page(id => $page->{page}{id});

    # Rename the page
    $bp->update_title(
        id    => $page_id,
        title => 'A new title'
    );

    # Change the body
    $bp->update_description(
        id          => $page_id,
        description => 'Something new'
    );

    # Remove the page
    $bp->destroy_page(id => $page_id);

=head1 DESCRIPTION

Net::Backpack provides a thin Perl wrapper around the L.
Currently it only implements the parts of the API that manipulate Backpack pages.
Future releases will increase the coverage.

=head2 Getting Started

In order to use the Backpack API, you'll need to have a Backpack API token.And in
order to get one of those, you'll need a Backpack account.But then again, the API
will be pretty  useless to you if you don't have a Backpack account to manipulate
with it.

You can get a Backpack account from L.

=head2 Backback API

The Backpack API is  based on XML over HTTP. You send an XML message over HTTP to
the Backpack server  and the server sends a response to you which is also in XML.
The format of the various XML requests and responses are defined L.

This module removes the need to deal with any XML.You create an object to talk to
the Backpack server and  call  methods on that object to manipulate your Backpage
pages. The values  returned  from Backpack are  converted to Perl data structures
before being handed back to you (although it is also possible to get back the raw
XML).

=head1 IMPORTANT NOTE

C  uses  L  to  parse  the data that is returned from
Backpack.From version 1.10 of C has changed.By default we now pass
the parameter C 1> to L. This will change the Perl
data structure returned by most calls.

To get the old behaviour back, you can pass the parameter C 0>
to the C function.

=cut

package Net::Backpack;

use 5.006;
use strict;
use warnings;

use Carp;
use LWP::UserAgent;
use HTTP::Request;
use XML::Simple;

our $VERSION = '1.15';

my %data = (
	    'list_all_pages' =>
	    {
	     url => '/ws/pages/all',
	     req => '
  [S:token]
'
	    },
	    'create_page' =>
	    {
	     url => '/ws/pages/new',
	     req => '
  [S:token]

    [P:title]
    [P:description]

'
	    },
	    'show_page' =>
	    {
	     url => '/ws/page/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'destroy_page' =>
	    {
	     url => '/ws/page/[P:id]/destroy',
	     req => '
  [S:token]
'
	    },
	    'update_title' =>
	    {
	     url => '/ws/page/[P:id]/update_title',
	     req => '
  [S:token]
  [P:title]
'
	    },
	    update_body =>
	    {
	     url => '/ws/page/[P:id]/update_body',
	     req => '
  [S:token]
  [P:description]
'
	    },
	    'duplicate_page' =>
	    {
	     url => '/ws/page/[P:id]/duplicate',
	     req => '
  [S:token]
'
	    },
	    'link_page' =>
	    {
	     url => '/ws/page/[P:to_page]/link',
	     req => '
  [S:token]
  [P:link_page]
'
	    },
	    'unlink_page' =>
	    {
	     url => '/ws/page/[P:from_page]/link',
	     req => '
  [S:token]
  [P:link_page]
'
	    },
	    'share_people' =>
	    {
	     url => '/ws/page/[P:id]/share',
	     req => '
  [S:token]

    [P:people]

'
	    },
	    'make_page_public' =>
	    {
	     url => '/ws/page/[P:id]/share',
	     req => '
  [S:token]

    [P:public]

'
	    },
	    'unshare_friend_page' =>
	    {
	     url => '/ws/page/[P:id]/unshare_friend_page',
	     req => '
  [S:token]
'
	    },
	    'email_page' =>
	    {
	     url => '/ws/page/[P:id]/email',
	     req => '
  [S:token]
'
	    },
	    'list_all_items' =>
	    {
	     url => '/ws/page/[P:page_id]/items/list',
	     req => '
  [S:token]
'
	    },
	    'create_item' =>
	    {
	     url => '/ws/page/[P:page_id]/items/add',
	     req => '
  [S:token]

    [P:item]

'
	    },
	    'update_item' =>
	    {
	     url => '/ws/page/[P:page_id]/items/update/[P:id]',
	     req => '
  [S:token]

    [P:item]

'
	    },
	    'toggle_item' =>
	    {
	     url => '/ws/page/[P:page_id]/items/toggle/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'destroy_item' =>
	    {
	     url => '/ws/page/[P:page_id]/items/destroy/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'move_item' =>
	    {
	     url => '/ws/page/[P:page_id]/items/move/[P:id]',
	     req => '
  [S:token]
  [P:direction]
'
	    },
	    'list_all_notes' =>
	    {
	     url => '/ws/page/[P:page_id]/notes/list',
	     req => '
  [S:token]
'
	    },
	    'create_note' =>
	    {
	     url => '/ws/page/[P:page_id]/notes/create',
	     req => '
  [S:token]

    [P:title]
    [P:body]

'
	    },
	    'update_note' =>
	    {
	     url => '/ws/page/[P:page_id]/notes/update/[P:id]',
	     req => '
  [S:token]

    [P:title]
    [P:body]

'
	    },
	    'destroy_note' =>
	    {
	     url => '/ws/page/[P:page_id]/notes/destroy/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'get_tag_pages' =>
	    {
	     url => '/ws/tags/[P:page_id]',
	     req => '
  [S:token]
'
	    },
	    'set_page_tags' =>
	    {
	     url => '/ws/page/[P:page_id]/tags/tag',
	     req => '
  [S:token]
  [P:tags]
'
	    },
	    'upcoming_reminders' =>
	    {
	     url => '/ws/reminders',
	     req => '
  [S:token]
'
	    },
	    'create_reminder' =>
	    {
	     url => '/ws/reminders/create',
	     req => '
  [S:token]

    [P:content]
	[P:remind_at]

'
	    },
	    'update_reminder' =>
	    {
	     url => '/ws/reminders/update/[P:id]',
	     req => '
  [S:token]

    [P:content]
	[P:remind_at]

'
	    },
	    'destroy_reminder' =>
	    {
	     url => '/ws/reminders/destroy/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'list_all_emails' =>
	    {
	     url => '/ws/page/[P:page_id]/emails/list',
	     req => '
  [S:token]
'
	    },
	    'show_email' =>
	    {
	     url => '/ws/page/[P:page_id]/emails/show/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'destroy_email' =>
	    {
	     url => '/ws/page/[P:page_id]/emails/destroy/[P:id]',
	     req => '
  [S:token]
'
	    },
	    'export' =>
	    {
	     url => '/ws/account/export',
	     req => '
  [S:token]
'
	    },
	    'list_all_lists' =>
	    {
	     url => '/ws/page/[P:page_id]/lists/list',
	     req => '
  [S:token]
'
	    },
	    'list_this_list' =>
	    {
	     url => '/ws/page/[P:page_id]/items/list?list_id=[P:list_id]',
	     req => '
  [S:token]
'
	    },
	    'create_list' =>
	    {
	     url => '/ws/page/[P:page_id]/lists/add',
	     req => '
  [S:token]
    [P:title]
'
	    },
	    'update_list' =>
	    {
	     url => '/ws/page/[P:page_id]/lists/update/[P:list_id]',
	     req =>	'
  [S:token]

    [P:title]

'
	    },
	    'destroy_list' =>
	    {
	     url => '/ws/page/[P:page_id]/lists/destroy/[P:list_id]',
	     req => '
  [S:token]
'
	    },
	    'create_list_item' =>
	    {
	     url => '/ws/page/[P:page_id]/items/add?list_id=[P:list_id]',
	     req =>	'
  [S:token]

    [P:item]

'
	    },
	   );

=head1 METHODS

=head2 new(%params)

Creates a new Net::Backpack object. All communication with the Backpack server is
made through this object.

Takes two mandatory arguments,your Backpack API token and your Backpack username.
Returns the new C object.

There is  also  an optional parameter, forcearray. This controls the value of the
C parameter that is used by C. The default value is 1.

If the C parameter is provided, then communication will take place over SSL.
This is required for Plus and Premium accounts.

    my $bp = Net::Backpack->new(
        token      => $token,
        user       => $user,
        forcearray => 0,
        ssl        => 0
    );

=cut

sub new {
    my $class  = shift;
    my %params = @_;

    my $self;
    $self->{token} = $params{token}
    || croak "No Backpack API token passed Net::Backpack::new\n";
    $self->{user}  = $params{user}
    || croak "No Backpack API user passed Net::Backpack::new\n";

    $self->{protocol}   = $params{ssl} ? 'https' : 'http';
    $self->{forcearray} = $params{forcearray} || 1;

    $self->{ua} = LWP::UserAgent->new;
    $self->{ua}->env_proxy;
    $self->{ua}->default_header('X-POST-DATA-FORMAT' => 'xml');

    $self->{base_url} = "$self->{protocol}://$self->{user}.backpackit.com";

    return bless $self, $class;
}

=head2 list_all_pages(%params)

Get a list of all of your Backpack pages.Returns a Perl data structure unless the
C parameter is true, in which case it returns the raw XML as returned by the
Backpack server.

    my $bp = Net::Backpack->new(
        token      => $token,
        user       => $user,
        forcearray => 0,
        ssl        => 0
    );

    $pages = $bp->list_all_pages(xml => 1);

=cut

sub list_all_pages {
    my $self   = shift;
    my %params = @_;

    my $req_data = $data{list_all_pages};
    my $url = $self->{base_url} . $req_data->{url};

    my $req = HTTP::Request->new('POST', $url);
    $req->content($self->_expand($req_data->{req}, %params));

    return $self->_call(%params, req => $req);
}

=head2 create_page(%param)

Create a new Backpack page with the given title and (optional) description.Returns
a Perl data structure unless the C parameter is true,in which case it returns
the raw XML as returned by the Backpack server.


    my $bp = Net::Backpack->new(
        token      => $token,
        user       => $user,
        forcearray => 0,
        ssl        => 0
    );

    my $page = $bp->create_page(
        title       => $title,
        description => $desc,
        xml         => 1
    );

=cut

sub create_page {
    my $self = shift;
    my %params = @_;

    croak 'No title for new page' unless $params{title};
    $params{description} ||= '';

    my $req_data = $data{create_page};
    my $url   = $self->{base_url} . $req_data->{url};

    my $req   = HTTP::Request->new(POST => $url);
    $req->content($self->_expand($req_data->{req}, %params));

    return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->show_page(id => $id, [xml => 1]);

Get details of the Backpack page with the given id. Returns a Perl data
structure unless the C parameter is true, in which case it returns the
raw XML as returned by the Backpack server.

=cut

sub show_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};

  my $req_data = $data{show_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->destroy_page(id => $id, [xml => 1]);

Delete the Backpack page with the given id. Returns a Perl data structure
unless the C parameter is true, in which case it returns the raw XML
as returned by the Backpack server.

=cut

sub destroy_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};

  my $req_data = $data{destroy_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->update_title(id => $id, title => $title, [xml => 1]);

Update the title of the given Backpack page. Returns a Perl data structure
unless the C parameter is true, in which case it returns the raw XML
as returned by the Backpack server.

=cut

sub update_title {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};
  croak 'No title' unless $params{title};

  my $req_data = $data{update_title};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->update_body(id => $id, description => $desc, [xml => 1]);

Update the description of the given Backpack page. Returns a Perl data
structure unless the C parameter is true, in which case it returns the
raw XML as returned by the Backpack server.

=cut

sub update_body {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};
  croak 'No description' unless defined $params{description};

  my $req_data = $data{update_body};
  my $url   = $self->{base_url} .$self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $page = $bp->duplicate_page(id => $id, [xml => 1]);

Create a duplicate of the given Backpack page. Returns a Perl data
structure unless the C parameter is true, in which case it returns the
raw XML as returned by the Backpack server.

=cut

sub duplicate_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};

  my $req_data = $data{duplicate_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->link_page(link_page => $id1, to_page => $id2, [xml => 1]);

Link one Backpack page to another. Returns a Perl data structure unless the
C parameter is true, in which case it returns the raw XML as returned
by the Backpack server.

=cut

sub link_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{link_page} and $params{to_page};

  my $req_data = $data{link_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->unlink_page(link_page => $id1, from_page => $id2,
                              [xml => 1]);

Unlink one Backpack page from another. Returns a Perl data structure unless
the C parameter is true, in which case it returns the raw XML as returned
by the Backpack server.

=cut

sub unlink_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{link_page} and $params{from_page};

  my $req_data = $data{unlink_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->share_page(id => $id, people => \@people,
                             [ xml => 1 ]);

Share a given Backpack page with a list of other people. The parameter
'people' is a list of email addresses of the people you wish to share the
page with.

=cut

sub share_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};
  croak 'No people' unless scalar @{$params{people}};

  $params{people} = join "\n", @{$params{people}};
  my $req_data = $data{share_people};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->make_page_public(id => $id, public => $public,
                                   [ xml => 1 ]);

Make a given Backpage page public or private. The parameter 'public' is
a boolean flag indicating whether the page should be made public or
private

=cut

sub make_page_public {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};
  croak 'No public flag' unless exists $params{public};

  $params{public} = !!$params{public};
  my $req_data = $data{make_page_public};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $rc = $bp->unshare_friend_page(id => $id, [ xml => 1 ]);

Unshare yourself from a friend's page.

=cut

sub unshare_friend_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};

  my $req_data = $data{unshare_friend_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}


=head2 $rc = $bp->email_page(id => $id, [ xml => 1 ]);

Email a page to yourself.

=cut

sub email_page {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{id};

  my $req_data = $data{email_page};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $items = $bp->list_all_items(page_id => $page_id, [xml => 1]);

Get a list of all of your Backpack checklist items. Returns a Perl data structure
unless the C parameter is true, in which case it returns the raw
XML as returned by the Backpack server.

=cut

sub list_all_items {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{page_id};

  my $req_data = $data{list_all_items};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $item = $bp->create_item(page_id => $page_id, item => $item, [xml => 1]);

Create a Backpack checklist item given a page id and some item content.
Returns a Perl data structure unless the C parameter is true, in which case
it returns the raw XML as returned by the Backpack server.

=cut

sub create_item {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No item content' unless $params{item};

  my $req_data = $data{create_item};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $item = $bp->update_item(page_id => $page_id, item => $item, [xml => 1]
                                id => $item_id);

Updates a Backpack checklist item given a page id, item id, and new content.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub update_item {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No item id' unless $params{id};
  croak 'No item content' unless $params{item};

  my $req_data = $data{update_item};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->toggle_item(page_id => $page_id, id => $item_id,
                                    [xml => 1]);

Toggles a Backpack checklist item given a page id and an item id.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub toggle_item {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No item id' unless $params{id};

  my $req_data = $data{toggle_item};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->destroy_item(page_id => $page_id, id => $item_id,
                                     [xml => 1]);

Destroys a Backpack checklist item given a page id and an item id.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub destroy_item {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No item id' unless $params{id};

  my $req_data = $data{destroy_item};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->move_item(page_id => $page_id, id => $item_id,
                                  direction => $direction, [xml => 1]);

Modifies the location in the list of a Backpack checklist item. Requires a
page id, a direction and an item id. Valid values for direction are
"move_lower", "move_higher", "move_to_top", and "move_to_bottom". Returns a
Perl data structure unless the C parameter is true, in which case it
returns the raw XML as returned by the Backpack server.

=cut

sub move_item {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No item id' unless $params{id};
  unless (exists $params{direction} &&
          $params{direction} =~ /move_(lower|higher|to_top|to_bottom)/) {
    croak 'No direction specified';
  }

  my $req_data = $data{move_item};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  #print "url : $url\n";
  #sleep 2;
  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $notes = $bp->list_all_notes(page_id => $page_id, [xml => 1]);

Get a list of all of your Backpack notes. Returns a Perl data structure
unless the C parameter is true, in which case it returns the raw
XML as returned by the Backpack server.

=cut

sub list_all_notes {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{page_id};

  my $req_data = $data{list_all_notes};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $note = $bp->create_note(page_id => $page_id, title => $title,
                                body => $body, [xml => 1]);

Create a Backpack note given a page id and some content. Title is required,
body is optional. Returns a Perl data structure unless the C parameter
is true, in which case it returns the raw XML as returned by the Backpack
server.

=cut

sub create_note {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No note title' unless $params{title};

  $params{body} ||= "";

  my $req_data = $data{create_note};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  print "url: $url\n";

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $note = $bp->update_note(page_id => $page_id, id => $note_id, [xml => 1]
                                title => $title, body => $body);

Updates a Backpack note given a page id, note id, and new content.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub update_note {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No note id' unless $params{id};

  $params{title} ||= "";
  $params{body} ||= "";

  my $req_data = $data{update_note};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->destroy_note(page_id => $page_id, id => $note_id,
                                     [xml => 1]);

Destroys a Backpack note given a page id and an note id.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub destroy_note {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No note id' unless $params{id};

  my $req_data = $data{destroy_note};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $pages = $bp->get_tag_pages(page_id => $id, [ xml => 1 ]);

Retrieve all the pages associated with a particular tag id. Returns a Perl
data structure unless the C parameter is true, in which case it returns
the raw XML as returned by the Backpack server.

=cut

sub get_tag_pages {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};

  my $req_data = $data{get_tag_pages};
  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->set_page_tags(page_id => $id, tags => \@tags,
                                         [ xml => 1 ]);

Set the tags for a given Backpack page. This method overwrites all tags for
the page. An empty set of tags serves to remove all the tags for the page.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

This is currently returning true, and though it seems to create and submit a
valid request, the tags are not being updated.

=cut

sub set_page_tags {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};

  $params{tags} = join "\n", map { '"'.$_.'"' } @{$params{tags}};
  my $req_data = $data{set_page_tags};

  my $url   = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  # print $url.$self->_expand($req_data->{req}, %params);

  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $reminders = $bp->upcoming_reminders([ xml => 1 ]);

Gets the upcoming Backpack reminders for an account, in the time zone
specified per the account's settings.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub upcoming_reminders {
  my $self = shift;
  my %params = @_;

  my $req_data = $data{upcoming_reminders};

  my $url   = $self->{base_url} . $self->_expand($req_data->{url});
  my $req   = HTTP::Request->new(POST => $url);

  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $reminder = $bp->create_reminder(content => $reminder, [xml => 1],
                                        [remind_at => $remind_at]);

Create a Backpack reminder given some reminder content. The content
takes fuzzy date/times like "+30 Do foo and bar" to set the reminder for 30
minutes from now. Optionally, specify a date in a relatively parseable date
format and use the remind_at parameter instead.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub create_reminder {
  my $self = shift;
  my %params = @_;

  croak 'No reminder content' unless $params{content};

  $params{remind_at} ||= "";

  my $req_data = $data{create_reminder};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $reminder = $bp->update_reminder(id => $reminder_id,
                                        [content => $reminder], [xml => 1],
                                        [remind_at => $remind_at);

Update a Backpack reminder given a reminder id. The content takes fuzzy
date/times like "+30 Do foo and bar" to set the reminder for 30 minutes
from now. Optionally, specify a date in a relatively parseable date format
and use the remind_at parameter instead.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub update_reminder {
  my $self = shift;
  my %params = @_;

  croak 'No reminder id' unless $params{id};
  unless (exists $params{content} && exists $params{remind_at}) {
    my $reminders = $self->upcoming_reminders();
    $params{content} ||=
      $reminders->{reminders}{reminder}{$params{id}}{content};
    $params{remind_at} ||=
      $reminders->{reminders}{reminder}{$params{id}}{remind_at};
  }

  my $req_data = $data{update_reminder};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->destroy_reminder( id => $reminder_id,  [xml => 1]);

Destroys a Backpack reminder given a reminder id.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub destroy_reminder {
  my $self = shift;
  my %params = @_;

  croak 'No reminder id' unless $params{id};

  my $req_data = $data{destroy_reminder};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $emails = $bp->list_all_emails(page_id => $page_id, [xml => 1]);

Get a list of all of your Backpack email items for a page. Returns a Perl
data structure unless the C parameter is true, in which case it returns
the raw XML as returned by the Backpack server.

=cut

sub list_all_emails {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{page_id};

  my $req_data = $data{list_all_emails};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $email = $bp->show_email(page_id => $page_id, id => $reminder_id,
                                [xml => 1]);

Returns a Backpack email item given a page id and an email id.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub show_email {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No email id' unless $params{id};

  my $req_data = $data{show_email};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $response = $bp->destroy_email(page_id => $page_id, id => $reminder_id,
                                      [xml => 1]);

Destroys a Backpack email item for a page given a page id and an email id.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub destroy_email {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No email id' unless $params{id};

  my $req_data = $data{destroy_email};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $exported_bp = $bp->export([xml => 1]);

Exports an account's entire Backpack. Returns a Perl data structure
unless the C parameter is true, in which case it returns the raw
XML as returned by the Backpack server.

=cut

sub export {
  my $self = shift;
  my %params = @_;

  my $req_data = $data{export};
  my $url = $self->{base_url} . $req_data->{url};

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $lists = $bp->list_all_lists(page_id => $page_id, [xml => 1]);

Get a list of *all* of your Backpack checklists for a specific page.
Returns a Perl data structure unless the C parameter is true,
in which case it returns the raw XML as returned by the Backpack server.

=cut

sub list_all_lists {
  my $self = shift;
  my %params = @_;

  croak 'No id' unless $params{page_id};

  my $req_data = $data{list_all_lists};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $list = $bp->list_this_list(page_id => $page_id, list_id => $list_id, [xml => 1]);

Get details of a specific list with the given list_id on a specific Backpack
page with the given page_id. Returns a Perl data structure unless the C
parameter is true, in which case it returns the raw XML as returned by the
Backpack server.

=cut

sub list_this_list {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No list id' unless $params{list_id};

  my $req_data = $data{list_this_list};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $list = $bp->create_list(page_id => $page_id, title => $title, [xml => 1]);

Create a new Backpack checklist given a page id and a list title.
Returns a Perl data structure unless the C parameter is true, in which
case it returns the raw XML as returned by the Backpack server.

=cut

sub create_list {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No list title' unless $params{title};

  my $req_data = $data{create_list};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $list = $bp->update_list(page_id => $page_id, list_id => $list_id, title => $title, [xml => 1]);

Update the title of a specific list with the given list_id on a specific
Backpack page with the given page_id. Returns a Perl data structure unless
the C parameter is true, in which case it returns the raw XML as
returned by the Backpack server.

=cut

sub update_list {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No list id' unless $params{list_id};
  croak 'No title' unless $params{title};

  my $req_data = $data{update_list};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $list = $bp->destroy_list(page_id => $page_id, list_id => $list_id, [xml => 1]);

Destroy a specific list with the given list_id on a specific Backpack page
with the given page_id. Returns a Perl data structure unless the C
parameter is true, in which case it returns the raw XML as returned by the
Backpack server.

=cut

sub destroy_list {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No list id' unless $params{list_id};

  my $req_data = $data{destroy_list};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}

=head2 $list = $bp->create_list_item(page_id => $page_id, list_id => $list_id, item = $item, [xml => 1]);

Create an item on a specific list with the given list_id on a specific
Backpack page with the given page_id. This differs from the usual
"create_item" function in that you can specify which list on a page you want
to add the item to. Returns a Perl data structure unless the C parameter
is true, in which case it returns the raw XML as returned by the Backpack
server.

=cut

sub create_list_item {
  my $self = shift;
  my %params = @_;

  croak 'No page id' unless $params{page_id};
  croak 'No list id' unless $params{list_id};
  croak 'No item content' unless $params{item};

  my $req_data = $data{create_list_item};
  my $url      = $self->{base_url} . $self->_expand($req_data->{url}, %params);

  my $req = HTTP::Request->new('POST', $url);
  $req->content($self->_expand($req_data->{req}, %params));

  return $self->_call(%params, req => $req);
}


sub _call {
  my $self = shift;
  my %params = @_;

  my $resp = $self->{ua}->request($params{req});
  my $xml = $resp->content;

  if ($params{xml}) {
    return $xml;
  } else {
    my $data = XMLin($xml, ForceArray => $self->{forcearray});
    return $data;
  }
}

sub _expand {
  my $self = shift;
  my $string = shift;
  my %params = @_;

  $string =~ s/\[S:(\w+)]/$self->{$1}/g;
  $string =~ s/\[P:(\w+)]/$params{$1}/g;

  return $string;
}

=head1 AUTHOR

Dave Cross Edave@[e-mail]

Please feel free to email me to tell me how you are using the module.

Lots of stuff implemented by neshura when I was being too tardy!

Currently maintained by Mohammad S Anwar, C<<  >>

=head1 REPOSITORY

L

=head1 BUGS

Please report bugs by email to [e-mail].

=head1 LICENSE AND COPYRIGHT

Copyright (c) 2005, Dave Cross.  All Rights Reserved.

This script is  free software; you can redistribute it and/or modify it under the
same terms as Perl itself.

=head1 SEE ALSO

L, L

=cut

1;
__END__