box-api 0.2.0 → 0.2.1

data/lib/box/api.rb

@@ -331,5 +331,35 @@ module Box
     def file_embed(id, options = Hash.new)
       query_rest('s_create_file_embed', { :action => :create_file_embed, :file_id => id }.merge(options))
     end
+
+    # Share an item publically, making it accessible via a share link.
+    #
+    # @param [String] target The type of item.
+    # @param [String] target_id The id of the item to share.
+    # @param [Hash] options Extra options related to notifications. Please
+    #        read the developer documentation for more details.
+    def share_public(target, target_id, options = Hash.new)
+      query_rest('share_ok', { :action => :public_share, :target => target, :target_id => target_id }.merge(options))
+    end
+
+    # Share an item privately, making it accessible only via email.
+    #
+    # @param [String] target The type of item.
+    # @param [String] target_id The id of the item to share.
+    # @param [Array] emails The email addresses of the individuals to share with.
+    # @param [Hash] options Extra options related to notifications. Please
+    #        read the developer documentation for more details.
+    #
+    def share_private(target, target_id, emails, options = Hash.new)
+      query_rest('private_share_ok', { :action => :private_share, :target => target, :target_id => target_id, :emails => emails }.merge(options))
+    end
+
+    # Stop sharing an item publically.
+    #
+    # @param [String] target The type of item.
+    # @param [String] target_id The id of the item to unshare.
+    def unshare_public(target, target_id)
+      query_rest('unshare_ok', :action => :public_unshare, :target => target, :target_id => target_id)
+    end
   end
 end

data/lib/box/api/exceptions.rb

@@ -29,6 +29,9 @@ module Box
     class AccountExceeded < Exception; end
     class SizeExceeded < Exception; end
 
+    # Sharing specific responses
+    class NotShared < Exception; end
+
     # Given a status, returning a cooresponding Exception class.
     #
     # @param [String] status The failing status to look for.
@@ -52,6 +55,8 @@ module Box
       when "get_auth_token_error", "e_register"
         Generic
       # Folder/File specific responses
+      when "wrong_node"
+        InvalidItem
       when "e_folder_id"
         InvalidFolder
       when "no_parent"
@@ -74,6 +79,13 @@ module Box
       # Comment specific responses
       when "get_comments_error", "add_comment_error", "delete_comment_error"
         Generic
+      # Sharing specific responses
+      when "file_not_shared"
+        NotShared
+      when "wrong input params"
+        InvalidInput
+      when "share_error", "unshare_error", "private_share_error"
+        Generic
       else
         Unknown
       end

data/lib/box/file.rb

@@ -67,8 +67,14 @@ module Box
     #        when generating the embed code.
     # @return [String] HTML code to use to embed the file.
     #
+    # @note This function will share the file if it is not already shared.
     def embed_code(options = Hash.new)
-      @api.file_embed(id, options)['file_embed_html']
+      begin
+        @api.file_embed(id, options)['file_embed_html']
+      rescue Api::NotShared
+        share_public
+        retry
+      end
     end
 
     protected

data/lib/box/item.rb

@@ -169,12 +169,40 @@ module Box
       @data.key?(sym.to_s) or super
     end
 
-    # Consider the item cached. This prevents an additional api
-    # when we know the item is fully fetched.
+    # Consider the item cached. This prevents an additional api when we
+    # know the item is fully fetched.
     def force_cached_info
       @cached_info = true
     end
 
+    # Generates a share link for this item.
+    #
+    # @param [Hash] options Special options related to notification. See
+    #         the developer wiki for details instructions.
+    # @return The public name of the item. In order to access this item
+    #         on the web, prefix this value with 'http://www.box.net/shared/'.
+    #
+    # TODO: Document the options.
+    def share_public(options = Hash.new)
+      @api.share_public(type, id, options)['public_name']
+    end
+
+    # Shares this item privately with the given email addresses.
+    #
+    # @param [Array] emails The Box users to share this item with.
+    # @param [Hash] options Special options related to notification. See
+    #         the developer wiki for details instructions.
+    def share_private(emails, options = Hash.new)
+      @api.share_private(type, id, emails, options)
+
+      true
+    end
+
+    # Unshares this item.
+    def unshare
+      @api.unshare(type, id)
+    end
+
     protected
 
     # Fetches this item's info from the api.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: box-api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-08 00:00:00.000000000 Z
+date: 2011-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httmultiparty
-  requirement: &2156752360 !ruby/object:Gem::Requirement
+  requirement: &2153669280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,10 @@ dependencies:
         version: 0.3.6
   type: :runtime
   prerelease: false
-  version_requirements: *2156752360
+  version_requirements: *2153669280
 - !ruby/object:Gem::Dependency
   name: launchy
-  requirement: &2156751520 !ruby/object:Gem::Requirement
+  requirement: &2153668860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156751520
+  version_requirements: *2153668860
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2156750700 !ruby/object:Gem::Requirement
+  requirement: &2153668360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156750700
+  version_requirements: *2153668360
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2156739960 !ruby/object:Gem::Requirement
+  requirement: &2153667820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,7 +55,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156739960
+  version_requirements: *2153667820
 description: Box-api is a collection of classes that implement functions defined in
   the Box public API. See http://developer.box.net for more information.
 email:
@@ -87,6 +87,7 @@ files:
 - doc/Box/Api/NoAccess.html
 - doc/Box/Api/NoParent.html
 - doc/Box/Api/NotAuthorized.html
+- doc/Box/Api/NotShared.html
 - doc/Box/Api/Restricted.html
 - doc/Box/Api/SizeExceeded.html
 - doc/Box/Api/Unknown.html
@@ -144,7 +145,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -77914252247933561
+      hash: 2152248300867732637
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -153,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -77914252247933561
+      hash: 2152248300867732637
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10