flattr 0.2.2 → 0.2.3

data/README.md

@@ -1,6 +1,8 @@
-# Flattr API wrapper gem
+# Flattr API wrapper
 
-This gem is a wrapper around the Flattr API. With the gem you can search things, add new thing and much more.
+This gem is a wrapper around the Flattr API. With the gem you can search things, add new thing and much more. If you want information about updates follow [@simongate](http://twitter.com/simongate) on twitter.
+
+[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=smgt&url=https://github.com/simon/flattr&title=Flattr API gem&language=en_GB&tags=github&category=software)
 
 ## Build status
 
@@ -22,6 +24,15 @@ Installation is easy, just install the gem with.
 
 To talk with all of Flattr API resources you need to [register a application](http://flattr.com/apps). This will give you a *client id* and a *client secret* whom you can exchange for a *access token*. The *access token* is then used to access the resources in the Flattr API that needs authentication. You can find more information about the API in [Flattr developer documents](http://developers.flattr.net/v2).
 
+### Resources
+
+You can find documentation about available resources in the code.
+
+* [things](https://github.com/simon/flattr/blob/master/lib/flattr/client/things.rb)
+* [users](https://github.com/simon/flattr/blob/master/lib/flattr/client/users.rb)
+* [categories](https://github.com/simon/flattr/blob/master/lib/flattr/client/categories.rb)
+* [languages](https://github.com/simon/flattr/blob/master/lib/flattr/client/languages.rb)
+
 ### Access public resources
 
 There are several public available resources in the Flattr API where you don't need to authenticate to access.

data/lib/flattr/client.rb

@@ -3,6 +3,7 @@ require 'flattr/connection'
 require 'flattr/request'
 require 'flattr/user'
 require 'flattr/thing'
+require 'flattr/search'
 require 'flattr/language'
 require 'flattr/category'
 require 'flattr/version'

data/lib/flattr/client/categories.rb

@@ -4,12 +4,32 @@ module Flattr
   class Client
     module Categories
 
+      # Public: Get a list of available categories
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.categories
+      #   # => [Flattr::Category]
+      #
+      # Returns a Array with Flattr::Category inside
       def categories
         @categories ||= get('/rest/v2/categories').map do |category|
           Flattr::Category.new(category)
         end
       end
 
+      # Public: Get a category by id
+      #
+      # id - id of the catgory
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.category("software")
+      #   # => Flattr::Category
+      #
+      # Returns a Flattr::Category on success and nil on failure
       def category(id)
         categories.select do |category|
           category.id == id

data/lib/flattr/client/languages.rb

@@ -4,6 +4,15 @@ module Flattr
   class Client
     module Languages
 
+      # Public: Returns available languages on flattr
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.languages
+      #   # => [Flattr::Language]
+      #
+      # Returns a Array with Flattr::Language inside
       def languages
         get("/rest/v2/languages").map do |language|
           Flattr::Language.new(language)

data/lib/flattr/client/things.rb

@@ -4,36 +4,147 @@ module Flattr
   class Client
     module Things
 
+      # Public: Fetch a thing
+      #
+      # id - id of the thing you would like to fetch
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.thing(450287)
+      #   #=> Flattr::Thing
+      #
+      # Returns the thing
+      # Raises error on failure
       def thing(id)
         thing = get("/rest/v2/things/#{id}")
         Flattr::Thing.new(thing)
       end
 
+      # Public: Create a thing
+      #
+      # url - URL you want to submit
+      # opts - A Hash containing the thing attribtues (default: {})
+      #        :title - title of the thing (optional).
+      #        :description - description of the thing (optional).
+      #        :category - category of the thing (optional).
+      #        :language - language of the thing (optional).
+      #        :tags - tags of the thing (optional).
+      #        :hidden - boolean toggling if thing should be hidden or not (optional).
+      #
+      # Returns new thing
+      # Raises error on failure
       def thing_new(url, opts = {})
         response = post("/rest/v2/things", opts.merge(:url => url))
         thing = get("/rest/v2/things/#{response[:id]}") 
         Flattr::Thing.new(thing)
       end
 
+      # Public: Update a thing
+      #
+      # id - id of the thing to update
+      # opts - a Hash containing the attributes to update (default: {})
+      #        :title - title of the thing (optional).
+      #        :description - description of the thing (optional).
+      #        :category - category of the thing (optional).
+      #        :language - language of the thing (optional).
+      #        :tags - tags of the thing (optional).
+      #        :hidden - boolean toggling if thing should be hidden or not (optional).
+      #
+      # Returns updated thing
+      # Raises Error on failure
       def thing_update(id, opts = {})
         patch("/rest/v2/things/#{id}", opts)
         thing = get("/rest/v2/things/#{id}")
         Flattr::Thing.new(thing)
       end
 
+      # Public: Delete a thing
+      #
+      # id - id of the thing you want to delete
+      #
+      # Example
+      #
+      #   f = Flattr.new
+      #   f.thing_delete(1)
+      #   # => true
+      #
+      # Returns true if successful
+      # Raises Error on failure
       def thing_delete(id)
         thing = delete("/rest/v2/things/#{id}")
-        true
+        if thing.nil? || thing == ""
+          return true
+        else
+          return false
+        end
       end
 
-      def search(query = {})
-        result = get("/rest/v2/things/search")
-        result
+      # Public: Flattr a thing
+      #
+      # id - id of the thing you want to flattr
+      #
+      # Example
+      #
+      #   f = Flattr.new
+      #   f.thing_flattr(1)
+      #   # => true
+      #
+      # Returns true
+      def thing_flattr(id)
+        post("/rest/v2/things/#{id}/flattr")
       end
 
-      def lookup(url)
-        thing = get("/rest/v2/things/lookup/?q=#{url}")
-        Flattr::Thing.new(thing)
+      # Public: Search things
+      #
+      # params - The Hash options used to configure search (default: {})
+      #          :query - A free text search query (optional).
+      #          :language - Filter by language (optional).
+      #          :category - Filter by category (optional).
+      #          :user - Search only a users things (optional).
+      #          :tags - Filter by tags (optional).
+      #          :page - Show page (optional).
+      #          :count - How many items per page (optional).
+      #
+      # Examples
+      #
+      #   # Return a search result containgin 'smgt'
+      #   f = Flattr.new
+      #   f.things_search(:query => "smgt")
+      #
+      #   # Return a search result containing 'ruby' from user 'smgt'
+      #   f = Flattr.new
+      #   f.things_search(:query => "ruby", :user => 'smgt')
+      #
+      # Returns Flattr::Search
+      def thing_search(params = {})
+        result = get("/rest/v2/things/search", params)
+        Flattr::Search.new(result)
+      end
+
+      # Public: Check if a URL is registred as a thing
+      #
+      # url - URL to lookup
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.things_lookup("http://flattr.com")
+      #   # => nil
+      #
+      #   f = Flattr.new
+      #   f.things_lookup("http://github.com/simon/flattr")
+      #   # => Flattr::Thing
+      #
+      # Returns Flattr::Thing on success and nil on failure
+      def thing_lookup(url)
+        lookup = get("/rest/v2/things/lookup", {:url => url})
+        if lookup["location"]
+          thing = get(lookup['location'])
+          Flattr::Thing.new(thing)
+        else
+          nil
+        end
       end
 
     end

data/lib/flattr/client/users.rb

@@ -4,12 +4,62 @@ module Flattr
   class Client
     module Users
 
+      # Public: Get a user or the one currently authenticated
+      #
+      # username - username of the user you want to get (optional)
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.user("smgt")
+      #   # => #<Flattr::User...
+      #
+      # Returns a Flattr::User if successful
+      # Raises a ERROR on failure
       def user(username=nil)
         user = username || self.current_user.username
         user = get("/rest/v2/users/#{user}")
         Flattr::User.new(user)
       end
 
+      # Public: Get a users things
+      #
+      # username - username of the user you want to get (optional)
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.user_things("smgt")
+      #   # => [#<Flattr::Thing...
+      #
+      # Returns a Array with Flattr::User's inside if successful
+      # Raises a ERROR on failure
+      def user_things(username=nil, args={})
+        user = username || self.current_user.username
+        get("/rest/v2/users/#{user}/things", args).map do |thing|
+          Flattr::Thing.new(thing)
+        end
+      end
+
+      # Public: Get a users flattrs
+      #
+      # username - username of the user you want to get (optional)
+      #
+      # Examples
+      #
+      #   f = Flattr.new
+      #   f.user_flattrs("smgt")
+      #   # => [{"type" => "flattr"....
+      #
+      # Returns a Array with flattrs if successful
+      # Raises a ERROR on failure
+      def user_flattrs(username=nil, args={})
+        user = username || self.current_user.username
+        get("/rest/v2/users/#{user}/flattrs").map do |flattr|
+          flattr
+        end
+      end
+
     end
   end
 end

data/lib/flattr/search.rb

@@ -0,0 +1,20 @@
+require 'flattr/base'
+
+module Flattr
+  class Search < Flattr::Base
+
+    lazy_attr_reader :total_items, :items, :page, :things
+
+    def initialize(attrs={})
+      if attrs["items"] > 0
+        items = []
+        attrs["things"].each do |item|
+          items << Flattr::Thing.new(item)
+        end
+        attrs["things"] = items
+      end
+      super attrs
+    end
+
+   end
+end

data/lib/flattr/version.rb

@@ -13,7 +13,7 @@ module Flattr
 
   # @return [Integer]
   def self.patch
-    2
+    3
   end
 
   # @return [String, NilClass]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flattr
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-11 00:00:00.000000000Z
+date: 2012-01-16 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
-  requirement: &70325557419160 !ruby/object:Gem::Requirement
+  requirement: &70335945795100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70325557419160
+  version_requirements: *70335945795100
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &70325557417700 !ruby/object:Gem::Requirement
+  requirement: &70335945794620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70325557417700
+  version_requirements: *70335945794620
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70325557416920 !ruby/object:Gem::Requirement
+  requirement: &70335945794040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70325557416920
+  version_requirements: *70335945794040
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70325557406820 !ruby/object:Gem::Requirement
+  requirement: &70335945793560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70325557406820
+  version_requirements: *70335945793560
 - !ruby/object:Gem::Dependency
   name: rdiscount
-  requirement: &70325557406000 !ruby/object:Gem::Requirement
+  requirement: &70335945793020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70325557406000
+  version_requirements: *70335945793020
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70325557405480 !ruby/object:Gem::Requirement
+  requirement: &70335945792400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +77,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70325557405480
+  version_requirements: *70335945792400
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70325557405020 !ruby/object:Gem::Requirement
+  requirement: &70335945791660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -88,10 +88,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70325557405020
+  version_requirements: *70335945791660
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &70325557404500 !ruby/object:Gem::Requirement
+  requirement: &70335945790720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -99,7 +99,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70325557404500
+  version_requirements: *70335945790720
 description: 
 email:
 - simon@smgt.me
@@ -142,6 +142,7 @@ files:
 - lib/flattr/request.rb
 - lib/flattr/request/oauth2.rb
 - lib/flattr/response/parse_json.rb
+- lib/flattr/search.rb
 - lib/flattr/thing.rb
 - lib/flattr/user.rb
 - lib/flattr/version.rb
@@ -174,3 +175,4 @@ summary: Flattr API wrapper
 test_files:
 - spec/flattr_spec.rb
 - spec/helper.rb
+has_rdoc: