[Bps-public-commit] storage-box branch, master, updated. 4b34b90ddaa72bf4ff027fea7bea6bcbe586ab97

[Dave Goehrig]

The branch, master has been updated
       via  4b34b90ddaa72bf4ff027fea7bea6bcbe586ab97 (commit)
      from  5a13191bffcd1b572f374d97cac8070b78f8cd37 (commit)

Summary of changes:
 lib/Storage/Box.pm | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 114 insertions(+), 4 deletions(-)

- Log -----------------------------------------------------------------
commit 4b34b90ddaa72bf4ff027fea7bea6bcbe586ab97
Author: Dave Goehrig <dave at bestpractical.com>
Date:   Thu Sep 1 13:50:07 2016 -0400

    added top level documentation

diff --git a/lib/Storage/Box.pm b/lib/Storage/Box.pm
index ae30b21..4db248c 100644
--- a/lib/Storage/Box.pm
+++ b/lib/Storage/Box.pm
@@ -36,7 +36,10 @@ Storage::Box - a module for managing storage at Box.com
 
 =head1 DESCRIPTION
 
-Storage::Box is 
+Storage::Box is module for interfacing with Box.com's REST API.
+It provides a JWT authenticated cleint for a server side application.
+
+
 
 =head1 METHODS
 
@@ -53,6 +56,27 @@ has enterprise_auth => '';
 has user_auth => '';
 has user => '';
 
+=pod
+
+B<authenticate_enterprise($self)>
+
+    Attempts to authenticate an enterprise access token,
+    and requires the following parameters be set:
+
+        * key_id
+        * enterprise_id
+        * private_key
+        * password
+        * client_id
+        * client_secret
+
+    If successful the 'enterprise_auth' parameter will be
+    set to a Storage::Box::Auth object with a suitable
+    token.  These tokens are generally good for 1 hour, and
+    will attempt to reprovision automatically when expired.
+
+=cut
+
 sub authenticate_enterprise {
     my $self = shift;    
     $self->enterprise_auth('') if ($self->enterprise_auth and 
@@ -71,6 +95,29 @@ sub authenticate_enterprise {
     $self;
 }
 
+=pod
+
+B<authenticate_user($self)>
+
+    Attempts to authenticate a user access token.
+    Requires the following parameters be populated:
+
+        * key_id
+        * user_id
+        * private_key
+        * password
+        * client_id
+        * client_secret
+
+    A user_id can be obtained by using the enterprise_auth
+    to create a new app user via create_user.  This
+    user_id can then be used to inteface with files and
+    folders.  The user auth token usually lasts for
+    about 1 hour, and will try to auto reprovision when
+    expired.
+
+=cut
+
 sub authenticate_user {
     my $self = shift;    
     $self->user_auth('') if ($self->user_auth and 
@@ -90,9 +137,12 @@ sub authenticate_user {
 }
 
 =pod
+
 B<create_user($self,$name)>
 
-    Creates a new Box.com App user with the given username
+    Creates a new Box.com App user with the given username.
+    If successful it will set the user object's id to the
+    user's user_id.
 
 =cut
 
@@ -107,9 +157,12 @@ sub create_user {
 }
 
 =pod
+
 B<read_user($self,$user_id)>
 
-    Reads a user object for the given user_id
+    Reads a user object for the given user_id,
+    returns a hash with the user's data.
+    On failure it will return an empty hash.
 
 =cut
 
@@ -124,10 +177,11 @@ sub read_user {
 }
 
 =pod
+
 B<update_user($self,$user_id,%options)>
 
     Updates a user object specified by user_id with the given hash 
-    of key => values. Returns the updated user object.
+    of key => values. Returns the updated user hash.
 
 =cut
 
@@ -142,9 +196,11 @@ sub update_user {
 }
 
 =pod
+
 B<delete_user($self,$user_id)>
 
     Deletes the user associated with $user_id.  Returns true on success.
+
 =cut
 
 sub delete_user {
@@ -158,8 +214,14 @@ sub delete_user {
 }
 
 =pod
+
 B<create_file($self,$filename)>
 
+    Uploads the file specified by filename,
+    and returns the file object.  If the 
+    file is successfully uploaded the id 
+    of the file object willl be set.
+
 =cut
 
 sub create_file {
@@ -173,6 +235,15 @@ sub create_file {
     $file;
 }
 
+=pod
+
+B<download_file($self,$file_id)>
+
+    Returns the contents of the file specified by file_id,
+    or an empty string if it fails.
+
+=cut
+
 sub download_file {
     my ($self,$file_id) = @_;
     $self->authenticate_user;
@@ -183,6 +254,15 @@ sub download_file {
     $file->download;
 }
 
+=pod
+
+B<delete_file($self,$file_id)>
+
+    Deletes the file corresponding to the given file_id.
+    Returns true if successful, false otherwise.
+
+=cut
+
 sub delete_file {
     my ($self,$file_id) = @_;
     $self->authenticate_user;
@@ -193,6 +273,19 @@ sub delete_file {
     $file->delete;
 }
 
+=pod
+
+B<create_folder($self,$name)>
+
+    Creates a folder with the given name and returns
+    the folder id.  The parent of this folder is '0'
+    by default.  Setting the 'parent' property on the
+    folder object allows you to specify a different
+    parent object.  This function returns the folder_id
+    for the newly created folder.
+
+=cut
+
 sub create_folder {
     my ($self,$name) = @_;
     $self->authenticate_user;
@@ -202,6 +295,14 @@ sub create_folder {
     );
     $folder->create;
 }
+=pod
+
+B<list_folder($self,$folder_id)>
+    
+    Returns an array of hashes representing the files and folders
+    contained by the folder with the given folder_id.
+
+=cut
 
 sub list_folder {
     my ($self,$folder_id) = @_;
@@ -213,6 +314,15 @@ sub list_folder {
     $folder->items;
 }
 
+=pod
+
+B<delete_folder($self,$folder_id)>
+
+    Deletes the folder corresponding to the given folder_id.
+    Returns true if successful, and false otherwise.
+
+=cut
+
 sub delete_folder {
     my ($self,$folder_id) = @_;
     $self->authenticate_user;

-----------------------------------------------------------------------