cloudapp_api 0.0.3 → 0.1.0

data/lib/cloudapp/account.rb

@@ -0,0 +1,132 @@
+module CloudApp
+  
+  # An ActiveResource-like interface through which to interract with the CloudApp API.
+  #
+  # @example Create a CloudApp account
+  #   CloudApp::Account.create :email => "arthur@dent.com", :password => "towel"
+  #
+  # @example Most other account actions require authentication first
+  #   CloudApp.authenticate "username", "password"
+  #
+  # @example Usage via the Account class
+  #   # View account details
+  #   @account = CloudApp::Account.find
+  #   
+  #   # Change default security
+  #   CloudApp::Account.update :private_items => false
+  #   
+  #   # Change email
+  #   CloudApp::Account.update :email => "ford@prefect.com", :current_password => "towel"
+  #   
+  #   # Change password
+  #   CloudApp::Account.update :password => "happy frood", :current_password => "towel"
+  #   
+  #   # Set custom domain
+  #   CloudApp::Account.update :domain => "dent.com", :domain_home_page => "http://hhgproject.org"
+  #   
+  #   # Forgot password
+  #   CloudApp::Account.reset :email => "arthur@dent.com"
+  #
+  # @example Usage via the class instance
+  #   # Change default security
+  #   @account.update :private_items => false
+  #   
+  #   # Change email
+  #   @account.update :email => "ford@prefect.com", :current_password => "towel"
+  #   
+  #   # Change password
+  #   @account.update :password => "happy frood", :current_password => "towel"
+  #   
+  #   # Set custom domain
+  #   @account.update :domain => "dent.com", :domain_home_page => "http://hhgproject.org"
+  #   
+  #   # Forgot password
+  #   @account.reset
+  #
+  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
+      res.ok? ? Account.new(res) : res
+    end
+    
+    # Create a CloudApp account.
+    # @example Provide a user details param
+    #   { :email => "arthur@dent.com", :password => "towel" }
+    # @param [Hash] of user credentials
+    # @return [CloudApp::Account]
+    def self.create(opts = {})
+      res = post "/register", :body => {:user => opts}
+      res.ok? ? Account.new(res) : res
+    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
+    # @return [CloudApp::Account]
+    def self.update(opts = {})
+      res = put "/account", {:body => {:user => opts}, :digest_auth => @@auth}
+      res.ok? ? Account.new(res) : res
+    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
+    # @return [Boolean]
+    def self.reset(opts = {})
+      res = post "/reset", :body => {:user => opts}
+      res.ok? ? true : 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 = {})
+      load(attributes)
+    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
+    # @return [CloudApp::Account]
+    def update(opts = {})
+      self.class.update opts
+    end
+    
+    # Dispatch an email containing a link to reset the account's password.
+    # @return [Boolean]
+    def reset
+      self.class.reset :email => self.email
+    end
+    
+  end
+  
+end

data/lib/cloudapp/base.rb

@@ -2,12 +2,14 @@ require "httparty"
 
 module CloudApp
   
+  # Globally set request headers
   HEADERS = {
-    "User-Agent" => "Ruby.CloudApp.API",
-    "Accept" => "application/json",
-    "Content-Type" => "application/json"
+    "User-Agent"    => "Ruby.CloudApp.API",
+    "Accept"        => "application/json",
+    "Content-Type"  => "application/json"
   }
-      
+  
+  # Base class for setting HTTParty configurations globally
   class Base
     
     include HTTParty
@@ -15,55 +17,24 @@ module CloudApp
     headers HEADERS
     format :json
     
+    # Sets the authentication credentials in a class variable.
+    # @param [String] cl.ly username
+    # @param [String] cl.ly password
+    # @return [Hash] authentication credentials
     def self.authenticate(username, password)
       @@auth = {:username => username, :password => password}
     end
     
-    def self.find(id)
-      res = get "http://cl.ly/#{id}"
-      res.ok? ? Item.new(res) : res
-    end
-    
-    def self.all(opts = nil)
-      opts = opts.nil? ? "" : "?#{opts.to_params}"
-      res = get "/items#{opts}", :digest_auth => @@auth
-      res.ok? ? res.collect{|i| Item.new(i)} : res
-    end
-    
-    def self.create(kind, opts = {})
-      case kind
-      when :bookmark
-        res = post "/items", {:query => {:item => opts}, :digest_auth => @@auth}
-      when :upload
-        res = get "/items/new", :digest_auth => @@auth
-        return res unless res.ok?
-        res = post res['url'], Multipart.new(res['params'].merge!(:file => File.new(opts[:file]))).payload.merge!(:digest_auth => @@auth)
-      else
-        return false
-      end
-      res.ok? ? Item.new(res) : res
-    end
-    
-    def initialize(attributes = {})
-      load(attributes)
-    end
-    
-    def delete
-      res = self.class.delete self.href, :digest_auth => @@auth
-      res.ok? ? true : res
-    end
-    
     private
     
+    # Sets the attributes for object.
+    # @param [Hash] attributes
     def load(attributes = {})
       attributes.each do |key, val|
         self.instance_variable_set("@#{key}", val)
-        self.class.send(:define_method, key, proc{self.instance_variable_get("@#{key}")})
       end
     end
-        
+    
   end  
   
-  class Item < Base ; end
-
 end

data/lib/cloudapp/client.rb

@@ -1,33 +1,119 @@
 module CloudApp
   
+  # A client interface through which to interract with the CloudApp API.
+  # 
+  # @example Creating a client instance and set authentication credentials
+  #   @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"
+  #   
+  #   # Get a list of all items
+  #   items = @client.all
+  #   
+  #   # Create a new bookmark
+  #   item = @client.bookmark "http://getcloudapp.com", "CloudApp"
+  #   
+  #   # Upload a file
+  #   item = @client.upload "/path/to/image.png"
+  #   
+  #   # Rename a file
+  #   @client.rename "2wr4", "Big Screenshot"
+  #   
+  #   # Set an items privacy
+  #   @client.privacy "2wr4", true
+  #   
+  #   # Delete an item
+  #   @client.delete "2wr4"
+  #
   class Client
     
+    # Creates a new CloudApp::Client instance.
+    # @example Optionally provide an authentication hash
+    #   { :username => "testuser@test.com", :password => "password" }
+    # @param [Hash] authentication credentials.
+    # @return [CloudApp::Client]
     def initialize(opts = {})
       if opts[:username] && opts[:password]
         Base.authenticate(opts[:username], opts[:password])
       end
     end
     
+    # Sets the authentication credentials in a class variable.
+    # @param [String] cl.ly username
+    # @param [String] cl.ly password
+    # @return [Hash] authentication credentials
     def authenticate(username, password)
       Base.authenticate(username, password)
     end
     
+    # Get metadata about a cl.ly URL like name, type, or view count.
+    # Finds the item by it's slug id, for example "2wr4".
+    # @param [String] cl.ly slug id
+    # @return [CloudApp::Item]
     def item(id)
       Item.find(id)
     end
     
+    # Page through your items.
+    # @example Optionally pass a hash of parameters.
+    #   :page => 1        # Page number starting at 1
+    #   :per_page => 5    # Number of items per page
+    #   :type => image    # Filter items by type (image, bookmark, text, archive, audio, video, or unknown)
+    #   :deleted => true  # Show trashed items
+    # Requires authentication.
+    # @param [Hash] options parameters
+    # @return [Array] of CloudApp::Item items
     def items(opts = {})
       Item.all(opts)
     end
-  
+    
+    # Create a new cl.ly item by bookmarking a link.
+    # Requires authentication.
+    # @param [String] url to bookmark
+    # @param [String] name of bookmark
+    # @return [CloudApp::Item]
     def bookmark(url, name = "")
       Item.create(:bookmark, {:name => name, :redirect_url => url})
     end
     
+    # Create a new cl.ly item by uploading a file.
+    # Requires authentication.
+    # @param [String] local path to file
+    # @return [CloudApp::Item]
     def upload(file)
       Item.create(:upload, :file => file)
     end
-  
+    
+    # Change the name of an item.
+    # Finds the item by it's slug id, for example "2wr4".
+    # Requires authentication.
+    # @param [String] cl.ly item id
+    # @param [String] new item name
+    # @return [CloudApp::Item]
+    def rename(id, name = "")
+      item = Item.find(id)
+      item.class == Item ? item.update(:name => name) : item
+    end
+    
+    # Modify an item with a private URL to have a public URL or vice versa.
+    # Finds the item by it's slug id, for example "2wr4".
+    # Requires authentication.
+    # @param [String] cl.ly item id
+    # @param [Boolean] privacy setting
+    # @return [CloudApp::Item]
+    def privacy(id, privacy = false)
+      item = Item.find(id)
+      item.class == Item ? item.update(:private => privacy) : item
+    end
+    
+    # Send an item to the trash.
+    # Finds the item by it's slug id, for example "2wr4".
+    # Requires authentication.
+    # @param [String] cl.ly item id
+    # @return [CloudApp::Item]
     def delete(id)
       item = Item.find(id)
       item.class == Item ? item.delete : item

data/lib/cloudapp/httparty.rb

@@ -1,18 +1,21 @@
-if HTTParty::VERSION <= "0.5.2"
-  ["httparty", "net_digest_auth"].each do |inc|
-    require File.join(File.dirname(__FILE__), "monkey_patch", inc)
-  end
-end
+require "json"
 
-module HTTParty
-  class Response < HTTParty::BasicObject
+module HTTParty #:nodoc:
+  
+  class Response < HTTParty::BasicObject #:nodoc:
     def ok?
-      self.code == 200
+      [200, 201, 202].include?(self.code)
     end
   end
   
-  class Request
+  class Request #:nodoc:
+    
     private
+    
+    def body
+      options[:body].is_a?(Hash) ? options[:body].to_json : options[:body]
+    end
+    
     def setup_raw_request
       # This is a cloudapp hack to ensure the correct headers are set on redirect from S3
       if @redirect
@@ -26,5 +29,7 @@ module HTTParty
       @raw_request.basic_auth(username, password) if options[:basic_auth]
       setup_digest_auth if options[:digest_auth]
     end
+    
   end
+  
 end

data/lib/cloudapp/item.rb

@@ -0,0 +1,147 @@
+module CloudApp
+  
+  # An ActiveResource-like interface through which to interract with the CloudApp API.
+  #
+  # @example Gets started by Authenticating
+  #   CloudApp.authenticate "username", "password"
+  #
+  # @example 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
+  #   
+  #   # Create a new bookmark
+  #   item = CloudApp::Item.create :bookmark, :name => "CloudApp", :redirect_url => "http://getcloudapp.com"
+  #   
+  #   # Upload a file
+  #   item = CloudApp::Item.create :upload, :file => "/path/to/image.png"
+  #   
+  #   # 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"
+  #
+  # @example 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
+  #
+  class Item < Base
+    
+    # Get metadata about a cl.ly URL like name, type, or view count.
+    # Finds the item by it's slug id, for example "2wr4".
+    # @param [String] cl.ly slug id
+    # @return [CloudApp::Item]
+    def self.find(id)
+      res = get "http://cl.ly/#{id}"
+      res.ok? ? Item.new(res) : res
+    end
+    
+    # Page through your items. Optionally pass a hash of parameters.
+    # @example Optionally pass a hash of parameters.
+    #   :page => 1        # Page number starting at 1
+    #   :per_page => 5    # Number of items per page
+    #   :type => image    # Filter items by type (image, bookmark, text, archive, audio, video, or unknown)
+    #   :deleted => true  # Show trashed items
+    # Requires authentication.
+    # @param [Hash] options parameters
+    # @return [Array] of CloudApp::Item items
+    def self.all(opts = {})
+      res = get "/items?#{opts.to_params}", :digest_auth => @@auth
+      res.ok? ? res.collect{|i| Item.new(i)} : res
+    end
+    
+    # Create a new cl.ly item. Can be one of two types:
+    #   :bookmark         # Bookmark link
+    #   :upload           # Upload file
+    # Depending on the type of item, a parameter hash is required.
+    # @example Options for a bookmark
+    #   { :name => "CloudApp", :redirect_url => "http://getcloudapp.com" }
+    # @example Options for a file upload
+    #   { :file => "/path/to/image.png" }
+    # Requires authentication.
+    # @param [Symbol] type of cl.ly item
+    # @param [Hash] item parameters
+    # @return [CloudApp::Item]
+    def self.create(kind, opts = {})
+      case kind
+      when :bookmark
+        res = post "/items", {:body => {:item => opts}, :digest_auth => @@auth}
+      when :upload
+        res = get "/items/new", :digest_auth => @@auth
+        return res unless res.ok?
+        res = post res['url'], Multipart.new(res['params'].merge!(:file => File.new(opts[:file]))).payload.merge!(:digest_auth => @@auth)
+      else
+        # TODO raise an error
+        return false
+      end
+      res.ok? ? Item.new(res) : res
+    end
+    
+    # Modify a cl.ly item. Can currently modify it's name or security setting by passing parameters.
+    # @example Options for renaming
+    #   { :name => "CloudApp" }
+    # @example Options for modifying privacy
+    #   { :privacy => true }
+    # Requires authentication.
+    # @param [String] href of cl.ly item
+    # @param [Hash] item parameters
+    # @return [CloudApp::Item]
+    def self.update(href, opts = {})
+      res = put href, {:body => {:item => opts}, :digest_auth => @@auth}
+      res.ok? ? Item.new(res) : res
+    end
+    
+    # Send an item to the trash.
+    # Requires authentication.
+    # @param [String] href of cl.ly item
+    # @return [CloudApp::Item]
+    def self.delete(href)
+      res = Base.delete href, :digest_auth => @@auth
+      res.ok? ? Item.new(res) : res
+    end
+    
+    attr_reader :href, :name, :private, :url, :content_url, :item_type, :view_counter,
+                :icon, :remote_url, :redirect_url, :created_at, :updated_at, :deleted_at
+    
+    # Create a new CloudApp::Item object.
+    # Only used internally
+    # @param [Hash] attributes
+    # @param [CloudApp::Item]
+    def initialize(attributes = {})
+      load(attributes)
+    end
+    
+    # Modify the cl.ly item. Can currently modify it's name or security setting by passing parameters.
+    # @example Options for renaming
+    #   { :name => "CloudApp" }
+    # @example Options for modifying privacy
+    #   { :privacy => true }
+    # Requires authentication.
+    # @param [Hash] item parameters
+    # @return [CloudApp::Item]
+    def update(opts = {})
+      self.class.update self.href, opts
+    end
+    
+    # Send the item to the trash.
+    # Requires authentication.
+    # @return [CloudApp::Item]
+    def delete
+      self.class.delete self.href
+    end
+        
+  end
+  
+end