=head1 NAME

WebService::FileCloud - filecloud.io WebService API

=head1 SYNOPSIS

  use WebService::FileCloud;

  $websvc = WebService::FileCloud->new( akey => 'apikey',
                                        username => 'username',
                                        password => 'password' );

  $result = $websvc->fetch_apikey();

  # you should check for HTTP request / usage errors first
  if ( !$result ) {

    die( $websvc->error() );
  }

  # check for filecloud.io errors in response
  if ( $result->{'status'} eq 'error' ) {

    die( $result->{'message'} );
  }

  $akey = $result->{'akey'};

=head1 DESCRIPTION

B<WebService::FileCloud> is a module to communicate with the L<http://filecloud.io> API.
Documentation for their API is available at L<https://code.google.com/p/filecloud/>.

=head1 CONSTRUCTOR

=over 4

=item new ( OPTIONS )

Creates a new B<WebService::FileCloud> object with the arguments given.  All arguments
are optional, but may be required depending upon the API methods executed.

=over 4

=item akey =E<gt> APIKEY

The API key provided to your account by filecloud.io.  This can be determined via the
B<fetch_apikey()> method if you provided your B<username> and B<password> of the
account.  Many methods require this argument to be specified.

=item username =E<gt> USERNAME

The username for your account.  The only method that requires this is
B<fetch_apikey()>.  Must also be provided with B<password>.

=item password =E<gt> PASSWORD

The password for your account.  The only method that requires this is
B<fetch_apikey()>.  Must also be provided with B<username>.

=back

=back

=head1 METHODS

All methods will return a false value if they were called incorrectly (missing
required parameters), or if there was an HTTP or other internal error issuing the
request.  Use the B<error()> method to get an error message as to why it failed.
Otherwise, they should return a JSON-decoded hashref as is directly from
filecloud.io (which may also contain an error).

=over 4

=item fetch_apikey

Returns the API key associated to the account.  Both the B<username> and
B<password> options must be given in the constructor.

=item fetch_account_details

Returns the details of the account.  The B<akey> option must be given in the
constructor to execute this method.

=item ping

Determines if the filecloud.io API is operational.  No arguments are necessary
in the constructor to execute this method.

=item fetch_upload_url

Returns a URL to use when uploading a file.  No arguments are necessary in the
constructor to execute this method.

=item check_file ( OPTIONS )

Determines if a file is available and returns basic information.  No arguments
are necessary in the constructor to execute this method, but the B<ukey> option
must be provided to this method.

=over 4

=item ukey =E<gt> FILEKEY

The unique key of the file.  This argument is required.

=back

=item fetch_file_details ( OPTIONS )

Returns the full details for a particular file.  The B<akey> option must be
given in the constructor, and the B<ukey> option described below must be
provided to this method.

=over 4

=item ukey =E<gt> FILEKEY

The unique key of the file.  This argument is required.

=back

=item fetch_download_url ( OPTIONS )

Returns the URL to use in order to download the specified file.  The B<akey>
option must be given in the constructor, and the B<ukey> option described
below must be provided to this method.

=over 4

=item ukey =E<gt> FILEKEY

The unique key of the file.  This argument is required.

=back

=item upload_file ( OPTIONS )

Uploads a file to the URL specified.  The upload url can be determined via
the B<fetch_upload_url()> method.  The B<akey> option must be given in the
constructor, and the B<filename> and B<url> options described below must be
provided to this method.

=over 4

=item filename =E<gt> PATH

The location of the file to upload.  This argument is required.

=item url =E<gt> URL

The URL to upload the file to.  This argument is required.

=back

=item fetch_tag_details ( OPTIONS )

Returns the details of the tag specified.  The B<akey> option must be
given in the constructor, and the B<tkey> option described below must be
provided to this method.

=over 4

=item tkey =E<gt> TAGKEY

The unique key of the tag.  This argument is required.

=back

=item error

Returns an error string for the last error encountered.  This only
contains internal errors related to HTTP requests and not errors from
the filecloud.io API itself.

=back

=head1 SEE ALSO

L<LWP::UserAgent>,
L<JSON>

L<http://filecloud.io> and L<https://code.google.com/p/filecloud/>

=head1 AUTHOR

Mitch McCracken E<lt>mrmccrac@gmail.comE<gt>

=cut
