cloudapp_api 0.1.1 → 0.2.0

data/README.md

@@ -18,73 +18,97 @@ Authentication is necessary for most actions, the only exceptions being when cre
 
     CloudApp.authenticate "email@address.com", "password"
 
-## Item examples
+## Drops
 
-* Documentation - {CloudApp::Item}
+* Documentation - {CloudApp::Drop}
 
 ---
 
-### Usage via the Item class
-    # Find a single item by it's slug
-    item = CloudApp::Item.find "2wr4"
-  
-    # Get a list of all items
-    items = CloudApp::Item.all
-  
+### Usage via the Drop class
+
+    # Find a single drop by it's slug
+    @drop = CloudApp::Drop.find "2wr4"
+    
+    # Get a list of all drops
+    @drops = CloudApp::Drop.all
+    
     # Create a new bookmark
-    item = CloudApp::Item.create :bookmark, :name => "CloudApp", :redirect_url => "http://getcloudapp.com"
-  
+    @drop = CloudApp::Drop.create :bookmark, :name => "CloudApp", :redirect_url => "http://getcloudapp.com"
+    
+    # Create multiple bookmarks
+    bookmarks = [
+      { :name => "Authur Dent", :redirect_url => "http://en.wikipedia.org/wiki/Arthur_Dent" },
+      { :name => "Zaphod Beeblebrox", :redirect_url => "http://en.wikipedia.org/wiki/Zaphod_Beeblebrox" }
+    ]
+    @drops = CloudApp::Drop.create :bookmarks, bookmarks
+    
     # Upload a file
-    item = CloudApp::Item.create :upload, :file => "/path/to/image.png"
-  
+    @drop = CloudApp::Drop.create :upload, :file => "/path/to/image.png"
+    @drop = CloudApp::Drop.create :upload, :file => "/path/to/image.png", :private => true
+    
     # Rename a file
-    CloudApp::Item.update "http://my.cl.ly/items/1912565", :name => "Big Screenshot"
-  
-    # Set an items privacy
-    CloudApp::Item.update "http://my.cl.ly/items/1912565", :private => true
-  
-    # Delete an item
-    CloudApp::Item.delete "http://my.cl.ly/items/1912565"
-
-### Usage via an Item instance
+    CloudApp::Drop.update "http://my.cl.ly/items/1912565", :name => "Big Screenshot"
+    
+    # Set a drop's privacy
+    CloudApp::Drop.update "http://my.cl.ly/items/1912565", :private => true
+    
+    # Delete a drop
+    CloudApp::Drop.delete "http://my.cl.ly/items/1912565"
+ 
+    # Recover a deleted drop
+    CloudApp::Drop.recover "http://my.cl.ly/items/1912565"
+
+### Usage via the class instance
+
     # Rename a file
-    @item.update :name => "Big Screenshot"
-  
-    # Set an items privacy
-    @item.update :private => true
-  
-    # Delete an item
-    @tem.delete
+    @drop.update :name => "Big Screenshot"
+    
+    # Set the drop's privacy
+    @drop.update :private => true
+    
+    # Delete a drop
+    @drop.delete
+ 
+    # Recover a deleted drop
+    @drop.recover
 
-## Usage via a Client instance
+## Drops via a Client instance
 
 * Documentation - {CloudApp::Client}
 
 ---
 
-    # Create a Client instance
-    @client = CloudApp::Client.new
+    # Find a single drop by it's slug
+    drop = @client.drop "2wr4"
     
-    # Find a single item by it's slug
-    item = @client.item "2wr4"
-    
-    # Get a list of all items
-    items = @client.all
+    # Get a list of all drops
+    drops = @client.all
     
     # Create a new bookmark
-    item = @client.bookmark "http://getcloudapp.com", "CloudApp"
+    drop = @client.bookmark "http://getcloudapp.com", "CloudApp"
+    
+    # Create multiple new bookmarks
+    bookmarks = [
+      { :name => "Authur Dent", :redirect_url => "http://en.wikipedia.org/wiki/Arthur_Dent" },
+      { :name => "Zaphod Beeblebrox", :redirect_url => "http://en.wikipedia.org/wiki/Zaphod_Beeblebrox" }
+    ]
+    drops = @client.bookmark bookmarks
     
     # Upload a file
-    item = @client.upload "/path/to/image.png"
+    drop = @client.upload "/path/to/image.png"
+    drop = @client.upload "/path/to/image.png", :private => true
     
     # Rename a file
     @client.rename "2wr4", "Big Screenshot"
     
-    # Set an items privacy
+    # Set a drop's privacy
     @client.privacy "2wr4", true
     
-    # Delete an item
+    # Delete an drop
     @client.delete "2wr4"
+    
+    # Recover a deleted drop
+    @client.recover "2wr4"
 
 ## Account examples
 
@@ -95,12 +119,12 @@ Authentication is necessary for most actions, the only exceptions being when cre
     # Create a CloudApp account
     @account = CloudApp::Account.create :email => "arthur@dent.com", :password => "towel"
     
-    # Forgot password
-    CloudApp::Account.reset :email => "arthur@dent.com"
-    
-    # View details of authenticated account
+    # View account details
     @account = CloudApp::Account.find
     
+    # Forgot password
+    CloudApp::Account.reset :email => "arthur@dent.com"
+     
     # Change default security
     @account.update :private_items => false
     
@@ -113,6 +137,22 @@ Authentication is necessary for most actions, the only exceptions being when cre
     # Set custom domain
     @account.update :domain => "dent.com", :domain_home_page => "http://hhgproject.org"
     
+    # View account stats
+    @account.stats
+
+## Gift cards
+
+* Documentation - {CloudApp::GiftCard}
+
+---
+
+    # View gift card details
+    @gift = CloudApp::GiftCard.find "ABC123"
+    
+    # Apply the gift card
+    CloudApp::GiftCard.redeem "ABC123"
+      # or
+    @gift.redeem
 
 ## Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/cloudapp_api.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{cloudapp_api}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Aaron Russell"]
-  s.date = %q{2011-01-30}
+  s.date = %q{2011-05-01}
   s.description = %q{A simple Ruby wrapper for the CloudApp API. Uses HTTParty with a simple ActiveResource-like interface.}
   s.email = %q{aaron@gc4.co.uk}
   s.extra_rdoc_files = [
@@ -28,41 +28,51 @@ Gem::Specification.new do |s|
     "lib/cloudapp/account.rb",
     "lib/cloudapp/base.rb",
     "lib/cloudapp/client.rb",
+    "lib/cloudapp/core_ext.rb",
+    "lib/cloudapp/drop.rb",
+    "lib/cloudapp/gift_card.rb",
     "lib/cloudapp/httparty.rb",
-    "lib/cloudapp/item.rb",
     "lib/cloudapp/multipart.rb",
     "lib/cloudapp_api.rb",
     "spec/cloudapp_account_spec.rb",
     "spec/cloudapp_api_spec.rb",
     "spec/cloudapp_client_spec.rb",
+    "spec/cloudapp_drop_spec.rb",
+    "spec/cloudapp_gift_card_spec.rb",
     "spec/cloudapp_item_spec.rb",
     "spec/fakeweb_helper.rb",
     "spec/spec_helper.rb",
     "spec/stubs/account/create",
     "spec/stubs/account/show",
+    "spec/stubs/account/stats",
     "spec/stubs/account/update",
-    "spec/stubs/item/create",
-    "spec/stubs/item/delete",
-    "spec/stubs/item/index",
-    "spec/stubs/item/new",
-    "spec/stubs/item/show",
-    "spec/stubs/item/update"
+    "spec/stubs/drop/create",
+    "spec/stubs/drop/delete",
+    "spec/stubs/drop/index",
+    "spec/stubs/drop/new",
+    "spec/stubs/drop/new-private",
+    "spec/stubs/drop/show",
+    "spec/stubs/drop/show-private",
+    "spec/stubs/drop/update",
+    "spec/stubs/gift_card/redeem",
+    "spec/stubs/gift_card/show"
   ]
   s.homepage = %q{http://github.com/aaronrussell/cloud_app}
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
+  s.rubygems_version = %q{1.7.2}
   s.summary = %q{A simple Ruby wrapper for the CloudApp API. Uses HTTParty with a simple ActiveResource-like interface.}
   s.test_files = [
     "spec/cloudapp_account_spec.rb",
     "spec/cloudapp_api_spec.rb",
     "spec/cloudapp_client_spec.rb",
+    "spec/cloudapp_drop_spec.rb",
+    "spec/cloudapp_gift_card_spec.rb",
     "spec/cloudapp_item_spec.rb",
     "spec/fakeweb_helper.rb",
     "spec/spec_helper.rb"
   ]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then

data/lib/cloudapp/account.rb

@@ -1,6 +1,6 @@
 module CloudApp
   
-  # An ActiveResource-like interface through which to interract with the CloudApp API.
+  # An ActiveResource-like interface through which to interract with CloudApp accounts.
   #
   # @example Create a CloudApp account
   #   CloudApp::Account.create :email => "arthur@dent.com", :password => "towel"
@@ -26,6 +26,9 @@ module CloudApp
   #   
   #   # Forgot password
   #   CloudApp::Account.reset :email => "arthur@dent.com"
+  #   
+  #   # View account stats
+  #   CloudApp::Account.stats
   #
   # @example Usage via the class instance
   #   # Change default security
@@ -42,11 +45,16 @@ module CloudApp
   #   
   #   # Forgot password
   #   @account.reset
+  #   
+  #   # View account stats
+  #   @account.stats
   #
   class Account < Base
     
     # Get the basic details of the authenticated account.
+    #
     # Requires authentication.
+    #
     # @return [CloudApp::Account]
     def self.find
       res = get "/account", :digest_auth => @@auth
@@ -54,9 +62,11 @@ module CloudApp
     end
     
     # Create a CloudApp account.
-    # @example Provide a user details param
-    #   { :email => "arthur@dent.com", :password => "towel" }
-    # @param [Hash] of user credentials
+    #
+    # @param [Hash] opts options parameters
+    # @option opts [String] :email Account email address
+    # @option opts [String] :password Account password
+    # @option opts [Boolean] :accept_tos Accept CloudApp terms of service
     # @return [CloudApp::Account]
     def self.create(opts = {})
       res = post "/register", :body => {:user => opts}
@@ -64,18 +74,20 @@ module CloudApp
     end
     
     # Modify the authenticated accounts details. Can change the default security of newly
-    # created items, the accounts email address, password, and custom domain details.
-    # @example Options for changing default security of new items
-    #   { :private_items => false }
-    # @example Options for changing email address
-    #   { :email => "ford@prefect.com", :current_password => "towel" }
-    # @example Options for modifying password
-    #   { :password => "happy frood", :current_password => "towel" }
-    # @example Options for changing custom domain
-    #   { :domain => "dent.com", :domain_home_page => "http://hhgproject.org" }
-    # Note that to custom domains requires and account with a Pro subscription.
-    # Requires authentication.
-    # @param [Hash] account parameters
+    # created drops, the accounts email address, password, and custom domain details.
+    #
+    # Note that when changing email address or password, the current password is required.
+    # Also note that to change custom domains requires an account with a Pro subscription.
+    #
+    # Requires authentication
+    #
+    # @param [Hash] opts options parameters
+    # @option opts [Boolean] :private_items Change default security of new drops
+    # @option opts [String] :email Change email address
+    # @option opts [String] :password Change password
+    # @option opts [String] :current_password Current account password
+    # @option opts [String] :domain Set custom domain
+    # @option opts [String] :domain_home_page URL to redirect visitors to custom domain's root
     # @return [CloudApp::Account]
     def self.update(opts = {})
       res = put "/account", {:body => {:user => opts}, :digest_auth => @@auth}
@@ -83,20 +95,32 @@ module CloudApp
     end
     
     # Dispatch an email containing a link to reset the account's password.
-    # @example Requires the account email address in a hash
-    #   { :email => "arthur@dent.com" }
-    # @param [Hash] account credentials
+    #
+    # @param [Hash] opts options parameters
+    # @option opts [String] :email Account email address
     # @return [Boolean]
     def self.reset(opts = {})
       res = post "/reset", :body => {:user => opts}
       res.ok? ? true : res
     end
+    
+    # Get the total number of drops created and total views for all drops.
+    #
+    # Requires authentication.
+    # 
+    # @return [Hash]
+    def self.stats
+      res = get "/account/stats", :digest_auth => @@auth
+      res.ok? ? res.symbolize_keys! : res
+    end
         
     attr_reader :id, :email, :domain, :domain_home_page, :private_items,
                 :subscribed, :alpha, :created_at, :updated_at, :activated_at
     
     # Create a new CloudApp::Account object.
+    #
     # Only used internally
+    #
     # @param [Hash] attributes
     # @param [CloudApp::Account]
     def initialize(attributes = {})
@@ -104,29 +128,39 @@ module CloudApp
     end
     
     # Modify the authenticated accounts details. Can change the default security of newly
-    # created items, the accounts email address, password, and custom domain details.
-    # @example Options for changing default security of new items
-    #   { :private_items => false }
-    # @example Options for changing email address
-    #   { :email => "ford@prefect.com", :current_password => "towel" }
-    # @example Options for modifying password
-    #   { :password => "happy frood", :current_password => "towel" }
-    # @example Options for changing custom domain
-    #   { :domain => "dent.com", :domain_home_page => "http://hhgproject.org" }
-    # Note that to custom domains requires and account with a Pro subscription.
-    # Requires authentication.
-    # @param [Hash] account parameters
+    # created drops, the accounts email address, password, and custom domain details.
+    #
+    # Note that when changing email address or password, the current password is required.
+    # Also note that to change custom domains requires an account with a Pro subscription.
+    #
+    # @param [Hash] opts options parameters
+    # @option opts [Boolean] :private_items Change default security of new drops
+    # @option opts [String] :email Change email address
+    # @option opts [String] :password Change password
+    # @option opts [String] :current_password Current account password
+    # @option opts [String] :domain Set custom domain
+    # @option opts [String] :domain_home_page URL to redirect visitors to custom domain's root
     # @return [CloudApp::Account]
     def update(opts = {})
       self.class.update opts
     end
     
     # Dispatch an email containing a link to reset the account's password.
+    #
+    # @param [Hash] opts options parameters
+    # @option opts [String] :email Account email address
     # @return [Boolean]
     def reset
       self.class.reset :email => self.email
     end
     
+    # Get the total number of drops created and total views for all drops.
+    # 
+    # @return [Hash]
+    def stats
+      self.class.stats
+    end
+    
   end
   
 end

data/lib/cloudapp/base.rb

@@ -19,11 +19,11 @@ module CloudApp
     
     # Sets the authentication credentials in a class variable.
     #
-    # @param [String] username cl.ly username
+    # @param [String] email cl.ly email
     # @param [String] password cl.ly password
     # @return [Hash] authentication credentials
-    def self.authenticate(username, password)
-      @@auth = {:username => username, :password => password}
+    def self.authenticate(email, password)
+      @@auth = {:username => email, :password => password}
     end
     
     private

data/lib/cloudapp/client.rb

@@ -6,27 +6,38 @@ module CloudApp
   #   @client = CloudApp::Client.new
   #   @client.authenticate "username", "password"
   #
-  # @example Creating editing and deleting cl.ly items
-  #   # Find a single item by it's slug
-  #   item = @client.item "2wr4"
+  # @example Creating editing and deleting drops
+  #   # Find a single drop by it's slug
+  #   drop = @client.drop "2wr4"
   #   
-  #   # Get a list of all items
-  #   items = @client.all
+  #   # Get a list of all drops
+  #   drops = @client.all
   #   
   #   # Create a new bookmark
-  #   item = @client.bookmark "http://getcloudapp.com", "CloudApp"
+  #   drop = @client.bookmark "http://getcloudapp.com", "CloudApp"
+  #   
+  #   # Create multiple new bookmarks
+  #   bookmarks = [
+  #     { :name => "Authur Dent", :redirect_url => "http://en.wikipedia.org/wiki/Arthur_Dent" },
+  #     { :name => "Zaphod Beeblebrox", :redirect_url => "http://en.wikipedia.org/wiki/Zaphod_Beeblebrox" }
+  #   ]
+  #   drops = @client.bookmark bookmarks
   #   
   #   # Upload a file
-  #   item = @client.upload "/path/to/image.png"
+  #   drop = @client.upload "/path/to/image.png"
+  #   drop = @client.upload "/path/to/image.png", :private => true
   #   
   #   # Rename a file
   #   @client.rename "2wr4", "Big Screenshot"
   #   
-  #   # Set an items privacy
+  #   # Set a drop's privacy
   #   @client.privacy "2wr4", true
   #   
-  #   # Delete an item
+  #   # Delete an drop
   #   @client.delete "2wr4"
+  #   
+  #   # Recover a deleted drop
+  #   @client.recover "2wr4"
   #
   class Client
     
@@ -55,15 +66,17 @@ module CloudApp
     
     # Get metadata about a cl.ly URL like name, type, or view count.
     #
-    # Finds the item by it's slug id, for example "2wr4".
+    # Finds the drop by it's slug id, for example "2wr4".
     #
     # @param [String] id cl.ly slug id
-    # @return [CloudApp::Item]
-    def item(id)
-      Item.find(id)
+    # @return [CloudApp::Drop]
+    def drop(id)
+      Drop.find(id)
     end
     
-    # Page through your items.
+    alias_method :item, :drop
+    
+    # Page through your drops.
     #
     # Requires authentication.
     #
@@ -71,72 +84,97 @@ module CloudApp
     # @option opts [Integer] :page (1) Page number starting at 1
     # @option opts [Integer] :per_page (5) Number of items per page
     # @option opts [String] :type ('image') Filter items by type (image, bookmark, text, archive, audio, video, or unknown)
-    # @option opts [Boolean] :deleted (true) Show trashed items
-    # @return [Array[CloudApp::Item]]
-    def items(opts = {})
-      Item.all(opts)
+    # @option opts [Boolean] :deleted (true) Show trashed drops
+    # @return [Array[CloudApp::Drop]]
+    def drops(opts = {})
+      Drop.all(opts)
     end
     
-    # Create a new cl.ly item by bookmarking a link.
+    alias_method :items, :drops
+    
+    # Create one or more new bookmark drops.
     #
     # Requires authentication.
     #
-    # @param [String] url url to bookmark
-    # @param [String] name name of bookmark
-    # @return [CloudApp::Item]
-    def bookmark(url, name = "")
-      Item.create(:bookmark, {:name => name, :redirect_url => url})
+    # @overload bookmark(url, name = "")
+    #   @param [String] url url to bookmark
+    #   @param [String] name name of bookmark
+    # @overload bookmark(opts)
+    #   @param [Array] opts array of bookmark option parameters (containing +:name+ and +:redirect_url+)
+    # @return [CloudApp::Drop]
+    def bookmark(*args)
+      if args[0].is_a? Array
+        Drop.create(:bookmarks, args)
+      else
+        name, url = args[0], (args[1] || "")
+        Drop.create(:bookmark, {:name => name, :redirect_url => url})
+      end
     end
     
-    # Create a new cl.ly item by uploading a file.
+    # Create a new drop by uploading a file.
     #
     # Requires authentication.
     #
     # @param [String] file local path to file
-    # @return [CloudApp::Item]
-    def upload(file)
-      Item.create(:upload, :file => file)
+    # @param [optional, Hash] opts options paramaters
+    # @option opts [Boolean] :private override the account default privacy setting
+    # @return [CloudApp::Drop]
+    def upload(file, opts = {})
+      Drop.create(:upload, opts.merge(:file => file))
     end
     
-    # Change the name of an item.
+    # Change the name of the drop.
     #
-    # Finds the item by it's slug id, for example "2wr4".
+    # Finds the drop by it's slug id, for example "2wr4".
     #
     # Requires authentication.
     #
-    # @param [String] id cl.ly item id
-    # @param [String] name new item name
-    # @return [CloudApp::Item]
+    # @param [String] id drop id
+    # @param [String] name new drop name
+    # @return [CloudApp::Drop]
     def rename(id, name = "")
-      item = Item.find(id)
-      item.class == Item ? item.update(:name => name) : item
+      drop = Drop.find(id)
+      drop.class == Drop ? drop.update(:name => name) : drop
     end
     
-    # Modify an item with a private URL to have a public URL or vice versa.
+    # Modify a drop with a private URL to have a public URL or vice versa.
     #
-    # Finds the item by it's slug id, for example "2wr4".
+    # Finds the drop by it's slug id, for example "2wr4".
     #
     # Requires authentication.
     #
-    # @param [String] id cl.ly item id
+    # @param [String] id drop id
     # @param [Boolean] privacy privacy setting
-    # @return [CloudApp::Item]
+    # @return [CloudApp::Drop]
     def privacy(id, privacy = false)
-      item = Item.find(id)
-      item.class == Item ? item.update(:private => privacy) : item
+      drop = Drop.find(id)
+      drop.class == Drop ? drop.update(:private => privacy) : drop
     end
     
-    # Send an item to the trash.
+    # Send the drop to the trash.
     #
-    # Finds the item by it's slug id, for example "2wr4".
+    # Finds the drop by it's slug id, for example "2wr4".
     #
     # Requires authentication.
     #
-    # @param [String] id cl.ly item id
-    # @return [CloudApp::Item]
+    # @param [String] id drop id
+    # @return [CloudApp::Drop]
     def delete(id)
-      item = Item.find(id)
-      item.class == Item ? item.delete : item
+      drop = Drop.find(id)
+      drop.class == Drop ? drop.delete : drop
+    end
+    
+    # Recover a deleted drop from the trash.
+    #
+    # Finds the drop by it's slug id, for example "2wr4".
+    #
+    # Requires authentication.
+    #
+    # @param [String] id drop id
+    # @return [CloudApp::Drop]
+    def recover(id)
+      drop = Drop.find(id)
+      drop.class == Drop ? drop.recover : drop
     end
         
   end

data/lib/cloudapp/core_ext.rb

@@ -0,0 +1,16 @@
+class Hash #:nodoc:
+  
+  # Return a new hash with all keys converted to symbols.
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end
+
+  # Destructively convert all keys to symbols.
+  def symbolize_keys!
+    self.replace(self.symbolize_keys)
+  end
+  
+end