box-api 0.1.9 → 0.2.0

data/doc/top-level-namespace.html

@@ -6,7 +6,7 @@
 <title>
   Top Level Namespace
   
-    &mdash; Documentation by YARD 0.7.2
+    &mdash; Documentation by YARD 0.7.3
   
 </title>
 
@@ -94,9 +94,9 @@
 </div>
     
     <div id="footer">
-  Generated on Mon Aug  8 13:05:22 2011 by 
+  Generated on Tue Nov  8 15:32:24 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.7.2 (ruby-1.9.2).
+  0.7.3 (ruby-1.9.3).
 </div>
 
   </body>

data/examples/files.rb

@@ -1,5 +1,6 @@
-# log in using the login example, so we don't have to duplicate code
 $: << File.dirname(__FILE__) # for 1.9
+
+# log in using the login example, so we don't have to duplicate code
 require 'login'
 
 # get the root of the folder structure
@@ -16,18 +17,15 @@ index = gets
 
 begin
   # grab the folder they selected
-  # to_i or [] will throw an exception if the index is invalid or out of range respectively
   folder = root.folders[index.to_i]
 rescue
-  # they picked an invalid folder!
+  # they picked a folder that broke our script!
   puts "You picked an invalid folder, please try again."
   exit
 end
 
-# the folder they picked was valid
 puts "Excellent choice, here are the contents of that folder"
 
-# show the selected folder
 puts "FOLDER: #{ folder.name } (#{ folder.id })"
 
 # loop through and show each of the sub files and folders

data/examples/login.rb

@@ -1,12 +1,11 @@
-# add the lib directory to our require path (you do not need this if you install the box-api gem)
+# add the lib directory to our require path (you do not need this if you use the box-api gem)
 $: << File.dirname(__FILE__) + "/../lib"
 
 # we use bundler to keep all of our gems up to date, but it is optional
 require 'rubygems'
 require 'bundler/setup'
 
-# we're only using account specific features in this example, so we don't need to require the entire gem
-require 'box/account'
+require 'box-api'
 
 # launchy is a simple gem that opens a browser, but is completely optional
 require 'launchy'
@@ -19,18 +18,17 @@ app_data = YAML.load_file(app_data_file)
 # you need to get your own API key at http://www.box.net/developers/services
 account = Box::Account.new(app_data['api_key'])
 
-# the user has to authorize your app on the box website, at which point you'll get an auth token
-# this auth token works between sessions, so read it from disk if the user has authed before
+# read any auth tokens if they are saved, so we don't have to re-authenticate on Box
 auth_token = app_data['auth_token']
 
-# now we have enough information to log into the box api, so we try to authorize using the auth token
-account.authorize(auth_token) do |auth_url|
+# try to authorize using the auth token, or request a new one if not
+account.authorize(:auth_token => auth_token) do |auth_url|
   # this block is called if the auth_token is invalid or missing
 
-  # we use launchy to open a new browser, but you can do it however you want
+  # we use launchy to open a new browser to the given url
   Launchy.open(auth_url)
 
-  # make sure you pause until the user has authorized, or just tell them to restart the program
+  # wait until the user authenticates on box before continuing
   puts "Please press the enter key once you have authorized this application to use your account"
   gets
 end
@@ -41,17 +39,15 @@ unless account.authorized?
   exit
 end
 
-# this auth token will let us instantly authorize next time this app is run, so we want to save it
-# keep in mind that an auth token only works with the same api key, and will expire if the user logs out
+# we managed to log in successfully!
+puts "Logged in as #{ account.login }"
+
+# this is so the other example can access the account variable
+@account = account
+
+# this auth token will let us instantly authorize next time this app is run, so we save it
 app_data['auth_token'] = account.auth_token
 
-# we write the auth_token to file so it can be accessed on next run
 File.open(app_data_file, 'w') do |file|
   YAML.dump(app_data, file)
 end
-
-# we managed to log in successfully!
-puts "Logged in as #{ account.info['login'] }"
-
-# this is so the other example can access the account variable (bad practice)
-@account = account

data/lib/box/account.rb

@@ -42,7 +42,7 @@ module Box
       true
     end
 
-    # Authorize the account using the given auth token, or request
+    # Authorize the account using the given auth token/ticket, or request
     # permission from the user to let this application use their account.
     #
     # An auth token can be reused from previous authorizations provided the
@@ -51,8 +51,18 @@ module Box
     # normally and requires the user to log in and provide access for their
     # account.
     #
-    # @param [Optional, String] auth_token Uses an existing token or requests
-    #        a new one if nil.
+    # A ticket can be used for applications that do not block on the user,
+    # such as a website, where specifying a redirection url is not possible.
+    #
+    # In order to maintain backwards compatibility, a ticket can only be
+    # specified in the hash syntax, while an auth token can be used in
+    # either the hash or string syntax.
+    #
+    # @param [Optional, String, Hash{:ticket,:auth_token => String}] details
+    #        Uses an existing auth token or ticket. If nil, a new ticket
+    #        will be generated and used. If a String, it is assumed to be
+    #        an auth_token (depreciated). If a Hash, then any values of
+    #        the :ticket and :auth_token keys will be used to authenticate.
     # @yield [authorize_url] This block called when the user has not yet
     #        granted this application permission to use their account. You
     #        must have the user navigate to the passed url and authorize
@@ -68,15 +78,24 @@ module Box
     #
     # @example Authorize an account using an existing auth token.
     #   auth_token = "saved auth token" # load from file ideally
-    #   account.authorize(auth_token)
+    #   account.authorize(:auth_token => auth_token)
     #
     # @example Combining the above two for the best functionality.
     #   auth_token = "saved auth token" # load from file if possible
-    #   account.authorize(auth_token) do |auth_url|
+    #   account.authorize(:auth_token => auth_token) do |auth_url|
     #     # auth token was invalid or nil, have the user visit auth_url
     #   end
     #
-    def authorize(auth_token = nil)
+    def authorize(details = nil)
+      # for backwards compatibility
+      if details.is_a?(Hash)
+        auth_token = details[:auth_token]
+        ticket = details[:ticket]
+      else
+        auth_token = details
+        ticket = nil
+      end
+
       # use a saved auth token if it is given
       if auth_token
         return true if authorize_token(auth_token)
@@ -84,12 +103,12 @@ module Box
 
       # the auth token either failed or was not provided
       # we must try to authorize a ticket, and call the block if that fails
-      if not authorize_ticket and block_given?
+      if not authorize_ticket(ticket) and block_given?
         # the supplied block should instruct the user to visit this url
-        yield authorize_url
+        yield authorize_url(ticket)
 
         # try authorizing once more
-        authorize_ticket
+        authorize_ticket(ticket)
       end
 
       # return our authorized status
@@ -152,17 +171,36 @@ module Box
       @info != nil
     end
 
-    protected
-
-    # @return [Api] The api currently in use.
-    attr_reader :api
-
     # Get the cached ticket or request a new one from the Box api.
     # @return [String] The authorization ticket.
     def ticket
       @ticket ||= @api.get_ticket['ticket']
     end
 
+    # Provides an easy way to access this account's info.
+    #
+    # @example
+    #   account.login # returns @info['login']
+    def method_missing(sym, *args, &block)
+      super unless authorized?
+
+      # TODO: Use symbols instead of strings
+      str = sym.to_s
+
+      return @info[str] if @info.key?(str)
+
+      super
+    end
+
+    def respond_to?(sym)
+      @info.key?(sym.to_s) or super
+    end
+
+    protected
+
+    # @return [Api] The api currently in use.
+    attr_reader :api
+
     # The url the user needs to visit in order to grant this application
     # permission to use their account. This requires a ticket, which
     # is either pulled from the cache or requested.
@@ -171,7 +209,8 @@ module Box
     #         If no ticket is provided, one will be requested and cached.
     # @return [String] the url used for authorizing this account.
     #
-    def authorize_url(ticket = self.ticket)
+    def authorize_url(ticket = nil)
+      ticket = self.ticket unless ticket
       "#{ api.base_url }/auth/#{ ticket }"
     end
 
@@ -183,7 +222,9 @@ module Box
     #         If no ticket is provided, one will be requested and cached.
     # @return [String, nil] The auth token if successful otherwise, nil.
     #
-    def authorize_ticket(ticket = self.ticket)
+    def authorize_ticket(ticket = nil)
+      ticket = self.ticket unless ticket
+
       begin
         response = @api.get_auth_token(ticket)
 

data/lib/box/api.rb

@@ -129,7 +129,7 @@ module Box
         end
       end
 
-      raise ErrorStatus, response.code unless response.success? # when the http return code is not normal
+      raise ErrorStatus, "HTTP code #{ response.code }" unless response.success? # when the http return code is not normal
       response
     end
 
@@ -298,5 +298,38 @@ module Box
     def new_copy(path, file_id, name = nil)
       query_upload('new_copy', file_id, 'upload_ok', :file => ::File.new(path), :new_file_name => name)
     end
+
+    # Gets the comments posted on the given item.
+    #
+    # @param ["file"] target The type of item.
+    # @param [String] target_id The id of the item to get.
+    def get_comments(target, target_id)
+      query_rest('get_comments_ok', :action => :get_comments, :target => target, :target_id => target_id)
+    end
+
+    # Adds a new comment to the given item.
+    #
+    # @param ["file"] target The type of item.
+    # @param [String] target_id The id of the item to add to.
+    # @param [String] message The message to use.
+    def add_comment(target, target_id, message)
+      query_rest('add_comment_ok', :action => :add_comment, :target => target, :target_id => target_id, :message => message)
+    end
+
+    # Deletes a given comment.
+    #
+    # @param [String] comment_id The id of the comment to delete.
+    def delete_comment(comment_id)
+      query_rest('delete_comment_ok', :action => :delete_comment, :target_id => comment_id)
+    end
+
+    # Request the HTML embed code for a file.
+    #
+    # @param [String] id The id of the file to use.
+    # @param [Hash] options The properties for the generated preview code.
+    #        See File#embed_code for a more detailed list of options.
+    def file_embed(id, options = Hash.new)
+      query_rest('s_create_file_embed', { :action => :create_file_embed, :file_id => id }.merge(options))
+    end
   end
 end

data/lib/box/api/exceptions.rb

@@ -71,6 +71,9 @@ module Box
         AccountExceeded
       when "filesize_limit_exceeded"
         SizeExceeded
+      # Comment specific responses
+      when "get_comments_error", "add_comment_error", "delete_comment_error"
+        Generic
       else
         Unknown
       end

data/lib/box/comment.rb

@@ -0,0 +1,50 @@
+module Box
+  class Comment
+    def self.create(api, comments)
+      if comments
+        comments = [ comments ] if comments.class == Hash
+
+        comments.collect do |comment|
+          sub_comments = comment.delete('reply_comments')
+
+          comment['id'] = comment.delete('comment_id')
+          comment['comments'] = self.create(api, sub_comments['item']) if sub_comments
+
+          Comment.new(api, comment)
+        end
+      else
+        Array.new
+      end
+    end
+
+    # Create a new comment object for a file.
+    #
+    # @param [Api] api The {Api} instance used to generate requests.
+    # @param [Hash] data The hash of initial info for this item, like 'id' and 'message'.
+    def initialize(api, data)
+      @api = api
+      @data = data
+    end
+
+    def id; @data['id']; end
+
+    def method_missing(sym, *args, &block)
+      # TODO: Use symbols instead of strings for keys.
+      sym = sym.to_s
+
+      return @data[sym] if @data.key?(sym)
+
+      super
+    end
+
+    def respond_to?(sym)
+      @data.key?(sym.to_s) or super
+    end
+
+    def delete
+      @api.delete_comment(id)
+
+      true
+    end
+  end
+end

data/lib/box/file.rb

@@ -40,6 +40,37 @@ module Box
       self.class.new(api, parent, info)
     end
 
+    # Get the comments left on this file.
+    #
+    # @return [Array] An array of {Comment}s.
+    def get_comments
+      comments = @api.get_comments(type, id)['comments']
+
+      comments = Comment.create(@api, comments['comment']) if comments
+
+      @data['comments'] = comments || Array.new
+    end
+
+    # Add a comment to the file.
+    #
+    # @return [Comment] The created comment.
+    def add_comment(message)
+      response = @api.add_comment(type, id, message)
+
+      Comment.create(@api, response['comment']).first
+    end
+
+    # Request the HTML embed code for this file.
+    #
+    # @param [Optional, Hash{:allow_download,:allow_print,:allow_share,
+    #        :width,:height,:color => String}] options Options to use
+    #        when generating the embed code.
+    # @return [String] HTML code to use to embed the file.
+    #
+    def embed_code(options = Hash.new)
+      @api.file_embed(id, options)['file_embed_html']
+    end
+
     protected
 
     # (see Item#get_info)

data/lib/box/folder.rb

@@ -122,6 +122,62 @@ module Box
       end
     end
 
+    # Get the item at the given path.
+    #
+    # @param [String] The path to search for. This follows the typical unix
+    #                 path syntax, in that the root folder is '/'. Supports
+    #                 the dot sytax, where '.' is the current folder and
+    #                 '..' is the parent folder.
+    #
+    # @return [Item]  The item that exists at this path, or nil.
+    #
+    # @example Find a folder based on its absolute path.
+    #   folder.at('/box/is/awesome')
+    #
+    # @example Find a file based on a relative path.
+    #   folder.at('awesome/file.pdf')
+    #
+    # @example Find a folder using the parent.
+    #   folder.at('../other/folder')
+    def at(target_path)
+      # start with this folder
+      current = self
+
+      if target_path.start_with?('/')
+        # absolute path, find the root folder
+        current = current.parent while current.parent != nil
+      end
+
+      # split each part of the target path
+      target_path.split('/').each do |target_name|
+        # update current based on the target name
+        current = case target_name
+        when "", "."
+          # no-op
+          current
+        when ".."
+          # use the parent folder
+          parent
+        else
+          # must be a file/folder name, so make sure this is a folder
+          return nil unless current and current.type == 'folder'
+
+          # search for an item with that name
+          current.find(:name => target_name, :recursive => false).first
+        end
+      end
+
+      if current
+        # ends with a slash, so it has to be a folder
+        if target_path.end_with?('/') and current.type != 'folder'
+          # get the folder with the same name (if it exists)
+          current = parent.find(:type => 'folder', :name => name, :recursive => false).first
+        end
+      end
+
+      current
+    end
+
     protected
 
     attr_accessor :cached_tree
@@ -180,7 +236,7 @@ module Box
     def find!(criteria, recursive)
       matches = (files + folders).collect do |item| # search over our files and folders
         match = criteria.all? do |key, value| # make sure all criteria pass
-          item.send(key) == value.to_s rescue false
+          value === item.send(key) rescue false
         end
 
         item if match # use the item if it is a match