little 0.0.3 → 0.0.4

data/lib/little/attempt.rb

@@ -1,11 +1,28 @@
 module Little
+  # log and retrieve login attempts
   class Attempt
+    # adds a login attempt
+    # @param [String] user the user who attempted to login
+    # @param [String] ip the user's ip address (use request.remote_ip in rails)
+    # @param [bool] ok whether or not the login was successful
+    # @return [Hash] the number of failed attempts in the last 0.5, 1, 3 and 5 minutes
     def self.add(user, ip, ok)
       Little.post(:attempts, {:user => user, :ip => ip, :ok => ok}, [:user, :ip, :ok])
     end
+    
+    # gets the previous (2nd last) successful login attempt
+    def self.get_previous_successful(user)
+      Little.get(:attempts, {:user => user}, [:user])
+    end
+    
+    # gets the login attempts for theu ser
+    # @param [String] user the user who attempted to login
+    # @param [int] count the number of past attempts to retrieve
     def self.get(user, count = 1)
       Little.get(:attempts, {:user => user, :count => count}, [:user])
     end
+    
+    # generates a signature for getting attempts(useful when using the javascript library)
     def self.sign_get(user)
       Little.sign(:attempts, {:user => user})
     end

data/lib/little/like.rb

@@ -1,29 +1,64 @@
 module Little
+  # add, delete and retrieve likes by user or assets
   class Like
+    # adds a like for a user to an asset
+    # @param [String] user the user who likes the asset
+    # @param [String] asset the asset being liked
+    # @param [int] type the type of asset
     def self.add(user, asset, type)
       Little.post(:likes, {:user => user, :asset => asset, :type => type}, [:user])
     end
+    
+    # generates a signature for adding a like (useful when using the javascript library)
     def self.sign_add(user)
       Little.sign(:likes, {:user => user})
     end
+    
+    # removes a like for a user to an asset
+    # @param [String] user the user who no longer likes the asset
+    # @param [String] asset the asset being unliked
+    # @param [int] type the type of asset
+    def self.delete(user, asset, type)
+      Little.delete(:likes, {:user => user, :asset => asset, :type => type}, [:user, :asset, :type])
+    end
+    
+    # generates a signature for deleting a like (useful when using the javascript library)
+    # @param [String] user the user who no longr likes the asset
+    def self.sign_delete(user, asset, type)
+      Little.sign(:likes, {:user => user, :asset => asset, :type => type})
+    end
+    
+    # does the user like the asset
     def self.user_likes_asset(user, asset, type)
       Little.get(:likes, {:user => user, :asset => asset, :type => type})
     end
+    
+    # gets all the assets liked by the user
     def self.user_likes(user, page, records)
       Little.get(:likes, {:user => user, :page => page, :records => records})
     end
+    
+    # gets the number of assets the user likes
     def self.user_like_count(user)
       Little.get(:likes, {:user => user, :count => true})
     end
+    
+    # gets all the users who like an asset
     def self.asset_liked_by(asset, type, page, records)
       Little.get(:likes, {:asset => asset, :type => type, :page => page, :records => records})
     end
+    
+    # gets the number of users who like an asset
     def self.asset_like_count(asset, type)
       Little.get(:likes, {:asset => asset, :type => type, :count => true})
     end
+    
+    # gets the assets liked by type, ordered by number of likes (desc)
     def self.by_type(type, page, records)
       Little.get(:likes, {:type => type, :page => page, :records => records})
     end
+    
+    # gets the number of assets for a type
     def self.by_type_count(type)
       Little.get(:likes, {:type => type, :count => true})
     end

data/lib/little/notification.rb

@@ -1,11 +1,23 @@
 module Little
+  # retrieve and repond to notifications
   class Notification
+    # gets the notification for a user and type
+    # @param [String] user the user to get the notification for
+    # @param [int] type the type of notifiation to get
+    # @return [Hash] containing the notification id and body, nil if the type is valid or if the user has already responded
     def self.get(user, type)
       Little.get(:notifications, {:user => user, :type => type})
     end
+    
+    # responds to a particular notification
+    # @param [String] user the user responding to the notificaiton
+    # @param [String] notificaiton_id the id of the notificaiton
+    # @param [int] response the user's response
     def self.respond(user, notification_id, response)
       Little.post(:notifications, {:user => user, :notification => notification_id, :response => response}, [:user, :notification])
     end
+    
+    # generates a signature for sending a response(useful when using the javascript library)
     def self.sign_respond(user, notification_id)
       Little.sign(:notification, {:user => user, :notification => notification_id})
     end

data/lib/little/sender.rb

@@ -12,25 +12,19 @@ module Little
     end
 
     def get_request(resource, data, signature_keys)
-      response = nil
-      begin
-        http = create_http(resource, data, signature_keys)
-        response = http.get("#{BASE_URL}#{resource}?#{url_encode(data)}", HEADERS)
-      rescue => e
-        raise Little::Error.new(-1, 0)
-      end
-      handle_response(response) unless response.nil?
+      query_request(:get, resource, data, signature_keys)
+    end
+    
+    def delete_request(resource, data, signature_keys)
+      query_request(:delete, resource, data, signature_keys)
     end
     
     def post_request(resource, data, signature_keys)
-      response = nil
-      begin
-        http = create_http(resource, data, signature_keys)
-        response = http.post(BASE_URL + resource.to_s, url_encode(data), HEADERS)
-      rescue => e
-        raise Little::Error.new(-2, e)
-      end
-      handle_response(response) unless response.nil?
+      form_request(:post, resource, data, signature_keys)
+    end
+    
+    def put_request(resource, data, signature_keys)
+      form_request(:put, resource, data, signature_keys)
     end
     
     private
@@ -42,14 +36,39 @@ module Little
       complete_data(resource, data, signature_keys)
       http
     end
+    
     def complete_data(resource, data, signature_keys)
       data[:key] = @configuration.api_key
       return if signature_keys.nil?
       data[:sig] = Little.sign(resource, data.select{|k,v| signature_keys.include?(k)})
     end
+    
     def url_encode(data)
       URI.encode_www_form(data)
     end
+    
+    def query_request(method, resource, data, signature_keys)
+      response = nil
+      begin
+        http = create_http(resource, data, signature_keys)
+        response = http.send(method, "#{BASE_URL}#{resource}?#{url_encode(data)}", HEADERS)
+      rescue => e
+        raise Little::Error.new(-1, e)
+      end
+      handle_response(response) unless response.nil?
+    end
+    
+    def form_request(method, resource, data, signature_keys)
+      response = nil
+      begin
+        http = create_http(resource, data, signature_keys)
+        response = http.send(method, BASE_URL + resource.to_s, url_encode(data), HEADERS)
+      rescue => e
+        raise Little::Error.new(-2, e)
+      end
+      handle_response(response) unless response.nil?
+    end
+    
     def handle_response(response)
       body = response.body
       if body.length < 2

data/lib/little/tag.rb

@@ -1,51 +1,88 @@
 module Little
+  # add, delete and retrieve tags by user or assets
   class Tag
+    # adds a tag for a user to an asset
+    # @param [String] user the user who likes the asset
+    # @param [String] asset the asset being liked
+    # @param [int] type the type of asset
+    # @param [bool] share whether to share this tag or not
+    # @param [String] arbitrary data to save with the tag
     def self.add(user, asset, type, share, data = nil)
       d = {:user => user, :asset => asset, :share => share, :type => type}
       d[:data] = data if data
       Little.post(:tags, d, [:user])
     end
+    
+    # generates a signature for adding a tag (useful when using the javascript library)
     def self.sign_add(user)
       Little.sign(:tags, {:user => user})
     end
+    
+    # removes a tag for a user to an asset
+    # @param [String] id the tag's id
+    def self.delete(id)
+      Little.delete(:tags, {:id => id}, [:id])
+    end
+    
+    # generates a signature for deleting a tag (useful when using the javascript library)
+    def self.sign_delete(id)
+      Little.sign(:tags, {:id => id})
+    end
+    
+    # gets a tag by id
+    # @param [String] id the tag's id
+    # @param [bool] shared_only only get the tag if it's shared
     def self.get_by_id(id, shared_only = true)
       Little.get(:tags, {:id => id}, shared_only ? nil : [:id])
     end
-    def self.user_tags(user, page, records, shared_only = true, asset = nil, type = 0)
+    
+    # generates a signature for getting a tag by id (useful when using the javascript library)
+    def self.sign_get_by_id(id)
+      Little.sign(:tags, {:id => id})
+    end
+    
+    # gets all the tags for a user
+    def self.user_tags(user, page, records, shared_only = true)
       data = {:user => user, :page => page, :records => records}
-      if asset
-        data[:asset] = asset 
-        data[:type] = type
-      end
-      Little.get(:tags, data, keys_to_sign_with(!asset.nil?, shared_only))
+      Little.get(:tags, data, shared_only ? nil : [:user])
+    end
+    
+    # gets all the assets liked for a user for a specific asset
+    def self.user_tags_for_asset(user, asset, type, page, records, shared_only = true)
+      data = {:user => user, :asset => asset, :type => type, :page => page, :records => records}
+      Little.get(:tags, data, shared_only ? nil : [:user, :asset, :type])
     end
-    def self.user_tag_count(user, shared_only = true, asset = nil, type = 0)
+    
+    # gets the number of tags for a user
+    def self.user_tag_count(user, shared_only = true)
       data = {:user => user, :count => true}
-      if asset
-        data[:asset] = asset 
-        data[:type] = type
-      end
-      Little.get(:tags, data, keys_to_sign_with(!asset.nil?, shared_only))
+      Little.get(:tags, data, shared_only ? nil : [:user])
+    end
+    
+    # gets all the of tags for a user for a specific asset
+    def self.user_tag_for_asset_count(user, asset, type, shared_only = true)
+      data = {:user => user, :asset => asset, :type => type, :count => true}
+      Little.get(:tags, data, shared_only ? nil : [:user, :asset, :type])
     end
-    def self.sign_user_tags(user, asset = nil, type = nil)
-      asset.nil? ? Little.sign(:tags, {:user => user}) : Little.sign(:tags, {:user => user, :asset => asset, :type => type})
+    
+    # generates a signature for getting a tags for a user (useful when using the javascript library)
+    def self.sign_user_tags(user)
+      Little.sign(:tags, {:user => user})
     end
+    
+    # generates a signature for getting a for a user for a specific asset (useful when using the javascript library)
+    def self.sign_user_tags_for_asset(user, asset, type)
+      Little.sign(:tags, {:user => user, :asset => asset, :type => type})
+    end
+    
+    # gets all the shared tags for a specific asset
     def self.asset_tags(asset, type, page, records)
       Little.get(:tags, {:asset => asset, :type => type, :page => page, :records => records})
     end
+    
+    # gets the number of shared tags for a specific asset
     def self.asset_tag_count(asset, type)
       Little.get(:tags, {:asset => asset, :type => type, :count => true})
     end
-    
-    private
-    def self.keys_to_sign_with(has_asset, shared_only)
-      return nil if shared_only
-      keys = [:user]
-      if has_asset
-        keys << :asset
-        keys << :type
-      end
-      keys
-    end
   end
 end

data/lib/little/version.rb

@@ -1,3 +1,3 @@
 module Little
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/lib/little.rb

@@ -7,32 +7,51 @@ require 'little/attempt'
 require 'little/notification'
 require 'little/sender'
 
-module Little
+module Little #:nodoc
   class << self
     attr_accessor :sender
     attr_writer :configuration
     
-    def configuration
-      @configuration ||= Configuration.new
-    end
-    
+    # Sets the configuration options. Best used by passing a block, for example:
+    #
+    #   Little.configure do |config|
+    #     config.api_key = 'KEY'
+    #     config.api_secret = 'SECRET'
+    #   end
     def configure
       yield(configuration)
       self.sender = Sender.new(configuration)
     end
     
+    # Can be used to generate a signature. Best to use specific signature methods such as Little::Like.sign_add(user)
+    def sign(resource, params)
+      params[:key] = configuration.api_key
+      raw = params.sort{|a, b| a[0] <=> b[0]}.join('|') + '|' + configuration.api_secret + '|' + resource.to_s
+      Digest::SHA1.hexdigest(raw)
+    end
+    
+    # Gets the current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    
+    # Issues a POST request to the little.io service
     def post(resource, data, signature_keys)
       sender.post_request(resource, data, signature_keys)
     end
+    # Issues a DELETE request to the little.io service
+    # @param [String, Symbol] resource name of the resource (:tags, :likes, ...)
+    # @param [Hash] data data to send to the service
+    # @param [Array] signature_keys keys of the data used for signing (optional)
+    def delete(resource, data, signature_keys)
+      sender.delete_request(resource, data, signature_keys)
+    end
+    # Issues a GET request to the little.io service
+    # @param [String, Symbol] resource name of the resource (:tags, :likes, ...)
+    # @param [Hash] data data to send to the service
+    # @param [Array] signature_keys keys of the data used for signing (optional)
     def get(resource, data, signature_keys = nil)
       sender.get_request(resource, data, signature_keys)
     end
-    
-    def sign(resource, params)
-      params[:key] = configuration.api_key
-      raw = params.sort{|a, b| a[0] <=> b[0]}.join('|') + '|' + configuration.api_secret + '|' + resource.to_s
-      Digest::SHA1.hexdigest(raw)
-    end
-
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: little
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-29 00:00:00.000000000 Z
+date: 2011-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
-  requirement: &70285946445680 !ruby/object:Gem::Requirement
+  requirement: &70251397271620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 2.2.6
   type: :runtime
   prerelease: false
-  version_requirements: *70285946445680
+  version_requirements: *70251397271620
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70285946444780 !ruby/object:Gem::Requirement
+  requirement: &70251397269580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70285946444780
+  version_requirements: *70251397269580
 description: 
 email:
 - help@little.io