box-api 0.1.6

data/lib/box/api.rb

@@ -0,0 +1,140 @@
+require 'box/api/exceptions'
+
+require 'httmultiparty'
+
+module Box
+  class Api
+    include HTTMultiParty # a slight modification to HTTParty, adding multi-part upload support
+
+    def initialize(key, url = 'https://box.net', upload_url = 'https://upload.box.net', version = '1.0')
+      @default_params = { :api_key => key } # add the api_key to every query
+
+      @base_url = "#{ url }/api/#{ version }" # set the base of the request url
+      @upload_url = "#{ upload_url }/api/#{ version }" # uploads use a different url than everything else
+    end
+
+    def query_rest(expected, options = {})
+      query_raw('get', "#{ @base_url }/rest", expected, options)['response']
+    end
+
+    def query_download(query, args, options = {})
+      url = [ "#{ @base_url }/#{ query }", @auth_token, args ].flatten.compact.join('/') # /download/<auth_token>/<arg1>/<arg2>/<etc>
+      query_raw('get', url, nil, options) # note, expected is nil because the return will be raw data
+    end
+
+    def query_upload(query, args, expected, options = {})
+      url = [ "#{ @upload_url }/#{ query }", @auth_token, args ].flatten.compact.join('/') # /upload/<auth_token>/<arg1>/<arg2>/<etc>
+      query_raw('post', url, expected, options)['response']
+    end
+
+    def query_raw(method, url, expected, options = {})
+      response = case method
+      when 'get'
+        self.class.get(url, :query => @default_params.merge(options))
+      when 'post'
+        self.class.post(url, :query => @default_params.merge(options), :format => :xml) # known bug with api that only occurs with uploads, will be fixed soon
+      end
+
+      handle_response(response, expected)
+    end
+
+    def handle_response(response, expected = nil)
+      if expected
+        begin
+          status = response['response']['status']
+        rescue
+          raise UnknownResponse, "Unknown response: #{ response }"
+        end
+
+        unless status == expected # expected is the normal, successful status for this request
+          exception = self.class.get_exception(status)
+          raise exception, status
+        end
+      end
+
+      raise ErrorStatus, response.code unless response.success? # when the http return code is not normal
+      response
+    end
+
+    def get_ticket
+      query_rest('get_ticket_ok', :action => :get_ticket)
+    end
+
+    def get_auth_token(ticket)
+      query_rest('get_auth_token_ok', :action => :get_auth_token, :ticket => ticket)
+    end
+
+    # save the auth token and add it to every request
+    def set_auth_token(auth_token)
+      @auth_token = auth_token
+      @default_params[:auth_token] = auth_token
+    end
+
+    def logout
+      query_rest('logout_ok', :action => :logout)
+    end
+
+    def register_new_user(login, password)
+      query_rest('successful_register', :action => :register_new_user, :login => login, :password => password)
+    end
+
+    def verify_registration_email(login)
+      query_rest('email_ok', :action => :verify_registration_email, :login => login)
+    end
+
+    def get_account_info
+      query_rest('get_account_info_ok', :action => :get_account_info)
+    end
+
+    # TODO: Use zip compression to save space
+    def get_account_tree(folder_id = 0, *args)
+      query_rest('listing_ok', :action => :get_account_tree, :folder_id => folder_id, :params => [ 'nozip' ] + args)
+    end
+
+    def create_folder(parent_id, name, share = 0)
+      query_rest('create_ok', :action => :create_folder, :parent_id => parent_id, :name => name, :share => share)
+    end
+
+    def move(target, target_id, destination_id)
+      query_rest('s_move_node', :action => :move, :target => target, :target_id => target_id, :destination_id => destination_id)
+    end
+
+    def copy(target, target_id, destination_id)
+      query_rest('s_copy_node', :action => :copy, :target => target, :target_id => target_id, :destination_id => destination_id)
+    end
+
+    def rename(target, target_id, new_name)
+      query_rest('s_rename_node', :action => :rename, :target => target, :target_id => target_id, :new_name => new_name)
+    end
+
+    def delete(target, target_id)
+      query_rest('s_delete_node', :action => :delete, :target => target, :target_id => target_id)
+    end
+
+    def get_file_info(file_id)
+      query_rest('s_get_file_info', :action => :get_file_info, :file_id => file_id)
+    end
+
+    def set_description(target, target_id, description)
+      query_rest('s_set_description', :action => :set_description, :target => target, :target_id => target_id, :description => description)
+    end
+
+    def download(path, file_id, version = nil)
+      ::File.open(path, 'w') do |file|
+        file << query_download('download', [ file_id, version ]) # write the response directly to file
+      end
+    end
+
+    def upload(path, folder_id, new_copy = false)
+      query_upload('upload', folder_id, 'upload_ok', :file => ::File.new(path), :new_copy => new_copy)
+    end
+
+    def overwrite(path, file_id, name = nil)
+      query_upload('overwrite', file_id, 'upload_ok', :file => ::File.new(path), :file_name => name)
+    end
+
+    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
+  end
+end

data/lib/box/api/exceptions.rb

@@ -0,0 +1,75 @@
+module Box
+  class Api
+    class Exception < StandardError; end
+
+    # HTTP exceptions
+    class UnknownResponse < Exception; end
+    class ErrorStatus < Exception; end
+
+    # Common responses
+    class Restricted < Exception; end
+    class InvalidInput < Exception; end
+    class NotAuthorized < Exception; end
+    class Generic < Exception; end
+    class Unknown < Exception; end
+
+    # Registration specific responses
+    class EmailInvalid < Exception; end
+    class EmailTaken < Exception; end
+
+    # Folder/File specific responses
+    class InvalidFolder < Exception; end
+    class InvalidName < Exception; end
+    class NoAccess < Exception; end
+    class NoParent < Exception; end
+    class NameTaken < Exception; end
+
+    # Upload/Download specific responses
+    class UploadFailed < Exception; end
+    class AccountExceeded < Exception; end
+    class SizeExceeded < Exception; end
+
+    def self.get_exception(status)
+      case status
+      # Common responses
+      when "application_restricted"
+        Restricted
+      when "wrong_input", "Wrong input params"
+        InvalidInput
+      when "not_logged_in", "wrong auth token"
+        NotAuthorized
+      when "e_no_access", "e_access_denied", "access_denied"
+        NoAccess
+      # Registration specific responses
+      when "email_invalid"
+        EmailInvalid
+      when "email_already_registered"
+        EmailTaken
+      when "get_auth_token_error", "e_register"
+        Generic
+      # Folder/File specific responses
+      when "e_folder_id"
+        InvalidFolder
+      when "no_parent"
+        NoParent
+      when "invalid_folder_name", "e_no_folder_name", "folder_name_too_big", "upload_invalid_file_name"
+        InvalidName
+      when "e_input_params"
+        InvalidInput
+      when "e_filename_in_use", "s_folder_exists"
+        NameTaken
+      when "e_move_node", "e_copy_node", "e_rename_node", "e_set_description"
+        Generic
+      # Upload/Download specific responses
+      when "upload_some_files_failed"
+        UploadFailed
+      when "not_enough_free_space"
+        AccountExceeded
+      when "filesize_limit_exceeded"
+        SizeExceeded
+      else
+        Unknown
+      end
+    end
+  end
+end

data/lib/box/file.rb

@@ -0,0 +1,37 @@
+require 'box/item'
+
+module Box
+  class File < Item
+    def self.type; 'file'; end
+
+    # download the file to the specified path
+    def download(path)
+      @api.download(path, id)
+    end
+
+    # overwrite this file, using the file at the specified path
+    def upload_overwrite(path)
+      info = @api.overwrite(path, id)['files']['file']
+
+      clear_info
+      update_info(info)
+
+      self
+    end
+
+    # upload a new copy of this file, the name being 'file (#).ext' for the #th copy
+    def upload_copy(path)
+      info = @api.new_copy(path, id)['files']['file']
+      parent.delete_info('files')
+
+      self.class.new(api, parent, info)
+    end
+
+    protected
+
+    # get the file info
+    def get_info
+      @api.get_file_info(id)['info']
+    end
+  end
+end

data/lib/box/folder.rb

@@ -0,0 +1,140 @@
+require 'box/item'
+require 'box/file'
+
+module Box
+  class Folder < Item
+    attr_accessor :cached_tree
+
+    def self.type; 'folder'; end
+
+    def info(refresh = false)
+      return self if @cached_info and not refresh
+
+      create_sub_items(nil, Box::Folder)
+      create_sub_items(nil, Box::File)
+
+      super
+    end
+
+    # use the cached tree or update it if requested
+    def tree(refresh = false)
+      return self if @cached_tree and not refresh
+
+      @cached_info = true # count the info as cached as well
+      @cached_tree = true
+
+      update_info(get_tree)
+      force_cached_tree
+
+      self
+    end
+
+    # create a new folder using this folder as the parent
+    def create(name, share = 0)
+      info = @api.create_folder(id, name, share)['folder']
+
+      delete_info('folders')
+
+      Box::Folder.new(api, self, info)
+    end
+
+    # upload a new file using this folder as the parent
+    def upload(path)
+      info = @api.upload(path, id)['files']['file']
+
+      delete_info('files')
+
+      Box::File.new(api, self, info)
+    end
+
+    # search for items using criteria
+    def find(criteria)
+      recursive = criteria.delete(:recursive)
+      recursive = true if recursive == nil # default to true
+
+      tree if recursive # get the full tree
+
+      find!(criteria, recursive)
+    end
+
+    protected
+
+    # get the folder info
+    def get_info
+      @api.get_account_tree(id, 'onelevel')['tree']['folder']
+    end
+
+    # get the folder info and all nested items
+    def get_tree
+      @api.get_account_tree(id)['tree']['folder']
+    end
+
+    def clear_info
+      @cached_tree = false
+      super
+    end
+
+    # overload Item#update_info to create the subobjects like Files and Folders
+    def update_info(info)
+      if folders = info.delete('folders')
+        create_sub_items(folders, Box::Folder)
+      end
+
+      if files = info.delete('files')
+        create_sub_items(files, Box::File)
+      end
+
+      super
+    end
+
+    # create the sub items, so they are objects rather than hashes
+    def create_sub_items(items, item_class)
+      @data[item_class.types] ||= Array.new
+
+      return unless items
+
+      temp = items[item_class.type]
+      temp = [ temp ] if temp.class == Hash # lone folders need to be packaged into an array
+
+      temp.collect do |item_info|
+        item_class.new(api, self, item_info).tap do |item|
+          @data[item_class.types] << item
+        end
+      end
+    end
+
+    def force_cached_tree
+      create_sub_items(nil, Box::Folder)
+      create_sub_items(nil, Box::File)
+
+      files.each do |file|
+        file.cached_info = true
+      end
+
+      folders.each do |folder|
+        folder.cached_info = true
+        folder.cached_tree = true
+
+        folder.force_cached_tree
+      end
+    end
+
+    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
+        end
+
+        item if match # use the item if it is a match
+      end
+
+      if recursive
+        folders.each do |folder| # recursive step
+          matches += folder.find!(criteria, recursive) # search each folder
+        end
+      end
+
+      matches.compact # return the results without nils
+    end
+  end
+end

data/lib/box/item.rb

@@ -0,0 +1,127 @@
+module Box
+  class Item
+    attr_accessor :data, :api, :parent
+    attr_accessor :cached_info
+
+    def initialize(api, parent, info)
+      @api = api
+      @parent = parent
+      @data = Hash.new
+
+      update_info(info) # merges with the info hash, and renames some fields
+    end
+
+    def self.type; raise "Overwrite this method"; end
+    def self.types; type + 's'; end
+
+    # should be a better way of doing this
+    def type; self.class.type; end
+    def types; self.class.types; end
+
+    def id; @data['id']; end # overwrite Object#id, which is not what we want
+
+    # use cached info or update it if requested
+    def info(refresh = false)
+      return self if @cached_info and not refresh
+
+      @cached_info = true
+      update_info(get_info)
+
+      self
+    end
+    # move the item to the destination folder
+    def move(destination)
+      @api.move(type, id, destination.id)
+
+      parent.delete_info(self.types)
+      destination.delete_info(self.types)
+
+      @parent = destination
+
+      self
+    end
+
+    # copy the file (folder not supported in the api) to the destination folder
+    def copy(destination)
+      @api.copy(type, id, destination.id)
+
+      destination.delete_info(self.types)
+
+      self.class.new(api, destination, @data)
+    end
+
+    # rename the item
+    def rename(new_name)
+      @api.rename(type, id, new_name)
+
+      update_info('name' => new_name)
+
+      self
+    end
+
+    # delete the item
+    def delete
+      @api.delete(type, id)
+
+      parent.delete_info(self.types)
+      @parent = nil
+
+      self
+    end
+
+    def description(message)
+      @api.set_description(type, id, message)
+
+      self
+    end
+
+    # get the path, starting with /
+    def path
+      "#{ parent.path + '/' if parent }#{ name }"
+    end
+
+    # use method_missing as to provide an easy way to access the item's properties
+    def method_missing(sym, *args, &block)
+      str = sym.to_s
+
+      # return the value if it already exists
+      return @data[str] if @data.key?(str)
+
+      # value didn't exist, so update the info
+      self.info
+
+      # try again
+      return @data[str] if @data.key?(str)
+
+      # we didn't find a value, so it must be invalid
+      super
+    end
+
+    protected
+
+    # sub-classes are meant to implement this
+    def get_info(*args); Hash.new; end
+
+    def update_info(info)
+      ninfo = Hash.new
+
+      # the api is stupid and some fields are named 'file_id' or 'id' inconsistently, so trim the type off
+      info.each do |name, value|
+        if name.to_s =~ /^#{ type }_(.+)$/; ninfo[$1] = value
+        else; ninfo[name.to_s] = value; end
+      end
+
+      @data.merge!(ninfo) # merge in the updated info
+    end
+
+    def delete_info(field)
+      @cached_info = false
+      @data.delete(field)
+    end
+
+    def clear_info
+      @cached_info = false
+      @data.clear
+    end
+  end
+end