kippt 1.1.0 → 2.0.0

data/.travis.yml

@@ -2,6 +2,7 @@ language: ruby
 rvm:
   - 1.8.7
   - 1.9.3
+  - 2.0.0
   - jruby-18mode
   - jruby-19mode
   - rbx-18mode

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.0 / July 7, 2013
+
+After being long time in development this update adds support for all the
+[new Kippt APIs](http://blog.kippt.com/2013/04/10/say-hi-to-api-and-apps/).
+
+README has been updated to reflect the additions to the API. There has also
+been plenty of refactoring done under the covers.
+
 ## 1.1 / July 20, 2012
 
 Changes in response to feedback from [Matias Korhonen](https://github.com/k33l0r):

data/Gemfile

@@ -1,5 +1,7 @@
 source 'https://rubygems.org'
 
+gem "rake"
+
 platform :jruby do
   gem "jruby-openssl"
 end

data/README.md

@@ -49,19 +49,26 @@ client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
 # Methods called on `client` will use the passed credentials
 ```
 
+Or you can use the API unauthenticated:
+
+```ruby
+client = Kippt::Client.new(unauthenticated: true)
+```
+
 
 ### Account
 
-You can get the account details (username and token):
+You can get the current authenticated user:
 
 ```ruby
 client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
 account = client.account
 account.username #=> "vesan"
-account.token    #=> "2544d6bfddf5893ec8617"
+account = client.account(true) # includes the API token
+account.api_token    #=> "2544d6bfddf5893ec8617"
 ```
 
-Always use token instead of the password if possible because it's more secure.
+Always use the API token instead of the password if possible because it's more secure.
 
 
 ### Resources
@@ -168,6 +175,16 @@ clip = client.clips[clip_id]
 clip.destroy #=> true
 ```
 
+### Debugging
+
+To get more information on what is going on under the covers, set `DEBUG=true` 
+as environment variable or pass `debug: true` in the Kippt::Client options hash 
+like:
+
+```ruby
+client = Kippt::Client.new(unauthenticated: true, debug: true)
+```
+
 
 ## Contributing
 

data/TODO.md

@@ -0,0 +1,43 @@
+* [DONE] Adding support for unauthenticated requests
+* [DONE] Timestamps as time
+* Better exceptions
+
+# Clip
+
+* [DONE] Getting the feed of authenticated user
+* [DONE] Getting the user of the clip
+* [DONE] Support for including list & via data
+* [DONE] Getting the list of the clip
+* [DONE] Getting the original clip the clip was created via
+* [DONE] Getting the comments of a clip
+* [DONE] Getting the likes of a clip
+* [DONE] Getting the saves of a clip
+* [DONE] Getting and setting is favorited (How does is starred work with it?)
+* [DONE] Getting the media of the clip (experimental)
+* [DONE] Getting the type of the clip
+* [DONE] Getting the favicon url of the clip
+* [DONE] Getting the app url fo the clip
+
+# User
+
+* [DONE] Support for all the user API's (still missing following/unfollowing users)
+* [DONE] Getting the user for the authenticated user
+* [DONE] Getting the embedded user for likes
+* [DONE] Getting the counts
+
+# List
+
+* [DONE] Support for is private
+* [DONE] Getting the user
+* [DONE] Getting & setting the description
+* [DONE] Getting the collaborators of the list
+* [DONE] Getting the app url fo the clip
+* [DONE] Getting the rss url fo the clip
+* [DONE] Add support for following and unfollowing a list
+* [DONE] Handle "List not found" error
+
+# Comment
+
+* [DONE] Add support for comments
+
+

data/kippt.gemspec

@@ -15,11 +15,11 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Kippt::VERSION
 
-  gem.add_dependency "faraday", "~> 0.7.6"
-  gem.add_dependency "faraday_middleware", "~> 0.8.7"
-  gem.add_dependency "multi_json", "~> 1.3.4"
+  gem.add_dependency "faraday", "~> 0.8"
+  gem.add_dependency "faraday_middleware", "~> 0.8"
+  gem.add_dependency "multi_json", "~> 1.3"
 
-  gem.add_development_dependency "rspec", "~> 2.9.0"
-  gem.add_development_dependency "webmock", "~> 1.8.6"
-  gem.add_development_dependency "simplecov", "~> 0.6.4"
+  gem.add_development_dependency "rspec", "~> 2.9"
+  gem.add_development_dependency "webmock", "~> 1.11"
+  gem.add_development_dependency "simplecov", "~> 0.7"
 end

data/lib/kippt/client.rb

@@ -1,7 +1,7 @@
 require "kippt/connection"
-require "kippt/account"
 require "kippt/clips"
 require "kippt/lists"
+require "kippt/users"
 
 class Kippt::Client
   include Kippt::Connection
@@ -9,18 +9,42 @@ class Kippt::Client
   attr_reader :username, :token, :password
 
   def initialize(options = {})
-    @username = options.fetch(:username) { raise ArgumentError.new("username is required") }
+    self.debug = options.fetch(:debug, nil)
 
-    @password = options.fetch(:password) { nil }
-    @token    = options.fetch(:token) { nil }
+    if options[:unauthenticated]
+      # Unauthenticated
+    else
+      @username  = options.fetch(:username) { raise ArgumentError.new("username is required") }
 
-    if @password.nil? && @token.nil?
-      raise ArgumentError.new("password or token is required")
+      @password  = options.fetch(:password) { nil }
+      @token     = options.fetch(:token) { nil }
+
+      if @password.nil? && @token.nil?
+        raise ArgumentError.new("password or token is required")
+      end
     end
   end
 
-  def account
-    Kippt::Account.new(get("account").body)
+  def debug=(value)
+    @debug = value
+  end
+
+  def debug
+    if @debug.nil?
+      !!ENV["DEBUG"]
+    else
+      @debug
+    end
+  end
+  alias_method :debug?, :debug
+
+  def account(include_api_token = false)
+    if include_api_token
+      url = "account?include_data=api_token"
+    else
+      url = "account"
+    end
+    Kippt::User.new(get(url).body, self)
   end
 
   def lists
@@ -30,4 +54,18 @@ class Kippt::Client
   def clips
     Kippt::Clips.new(self)
   end
+
+  def users
+    Kippt::Users.new(self)
+  end
+
+  def collection_resource_for(resource_class, *options)
+    resource_class.new(*([self] + options))
+  end
+
+  def resource_from_url(resource_class, url)
+    raise ArgumentError.new("The parameter URL can't be blank") if url.nil? || url == ""
+
+    resource_class.new(self.get(url).body, self)
+  end
 end

data/lib/kippt/clip.rb

@@ -1,11 +1,90 @@
-require "ostruct"
 require "kippt/resource"
+require "kippt/list"
+require "kippt/comments"
+require "kippt/likes"
+require "kippt/saves"
+require "kippt/user"
 
 class Kippt::Clip
   include Kippt::Resource
 
-  attributes :url_domain, :updated, :is_starred, :title,
-             :url, :notes, :created, :list, :id, :resource_uri
+  attributes :url_domain, :is_starred, :title,
+             :url, :notes, :id, :resource_uri,
+             :type, :favicon_url, :app_url, :media,
+             :updated => Time, :created => Time,
+             :user => Kippt::User
 
-  writable_attributes :is_starred, :title, :url, :notes, :list
+  writable_attributes :is_favorite, :title, :url, :notes, :list
+
+  boolean_attributes :is_favorite
+
+  alias :is_starred :is_favorite
+  alias :is_starred= :is_favorite=
+  alias :starred? :favorite?
+
+  embedded_attributes :list => "Kippt::List", :via => "Kippt::Clip"
+
+  def collection_resource_class
+    Kippt::Clips
+  end
+
+  def list_uri
+    if attributes.list.is_a? String
+      attributes.list
+    else
+      list.resource_uri
+    end
+  end
+
+  def comments
+    Kippt::Comments.new(client, self)
+  end
+
+  def all_comments_embedded?
+    comments_count == comments_data.size
+  end
+
+  def comments_count
+    attributes.comments["count"]
+  end
+
+  def comments_data
+    attributes.comments["data"]
+  end
+
+  def likes
+    Kippt::Likes.new(client, self)
+  end
+
+  def all_likes_embedded?
+    likes_count == likes_data.size
+  end
+
+  def likes_count
+    attributes.likes["count"]
+  end
+
+  def likes_data
+    attributes.likes["data"]
+  end
+
+  def saves
+    Kippt::Saves.new(client, self)
+  end
+
+  def saves_count
+    attributes.saves["count"]
+  end
+
+  def saves_data
+    attributes.saves["data"]
+  end
+
+  def like
+    Kippt::Like.new(client, self).save
+  end
+
+  def unlike
+    Kippt::Like.new(client, self).destroy
+  end
 end

data/lib/kippt/clip_collection.rb

@@ -7,4 +7,8 @@ class Kippt::ClipCollection
   def object_class
     Kippt::Clip
   end
+
+  def collection_resource_class
+    Kippt::Clips
+  end
 end

data/lib/kippt/clips.rb

@@ -27,17 +27,21 @@ class Kippt::Clips
     "clips"
   end
 
+  def feed
+    Kippt::ClipCollection.new(client.get("clips/feed").body, client)
+  end
+
   def search(parameters)
     if parameters.is_a?(String)
       Kippt::ClipCollection.new(
-        @client.get("search/clips", {:q => parameters}).body,
-        self)
+        client.get("search/clips", {:q => parameters}).body,
+        client)
     else
       validate_search_parameters(parameters)
 
       Kippt::ClipCollection.new(
-        @client.get("search/clips", parameters).body,
-        self)
+        client.get("search/clips", parameters).body,
+        client)
     end
   end
 

data/lib/kippt/collection.rb

@@ -3,21 +3,24 @@ module Kippt::Collection
 
   attr_reader :total_count, :limit, :offset
 
-  def initialize(data, collection_resource = nil)
-    meta         = data.fetch("meta")
-    @limit       = meta.fetch("limit")
-    @offset      = meta.fetch("offset")
+  def initialize(data, client = nil)
+    meta         = data.fetch("meta") { {} }
+    @limit       = meta.fetch("limit") { nil }
+    @offset      = meta.fetch("offset") { nil }
     @next        = meta.fetch("next") { nil }
     @previous    = meta.fetch("previous") { nil }
-    @total_count = meta.fetch("total_count")
+    @total_count = meta.fetch("total_count") { nil }
 
-    @collection_resource  = collection_resource
+    @client  = client
 
     @object_data = data.fetch("objects")
   end
 
+  extend Forwardable
+  def_delegators :objects, :size, :length
+
   def objects
-    @objects ||= @object_data.map {|data| object_class.new(data, @collection_resource) }
+    @objects ||= @object_data.map {|data| object_class.new(data, client) }
   end
 
   def [](index)
@@ -35,7 +38,7 @@ module Kippt::Collection
   def next_page
     raise Kippt::APIError.new("There is no next page") if @next.nil? || @next == ""
 
-    @collection_resource.collection_from_url(@next)
+    collection_resource.collection_from_url(@next)
   end
 
   def previous_page?
@@ -46,7 +49,17 @@ module Kippt::Collection
   def previous_page
     raise Kippt::APIError.new("There is no previous page") if @previous.nil? || @previous == ""
 
-    @collection_resource.collection_from_url(@previous)
+    collection_resource.collection_from_url(@previous)
   end
   alias_method :prev_page, :previous_page
+
+  private
+
+  def collection_resource
+    @collection_resource ||= client.collection_resource_for(collection_resource_class)
+  end
+
+  def client
+    @client
+  end
 end

data/lib/kippt/collection_resource.rb

@@ -1,16 +1,29 @@
 module Kippt::CollectionResource
+  # For certain objects you can get extra data by giving option `include_data`.
+  # For example with clips you can add `include_data: "list,via"`.
   def all(options = {})
     validate_collection_options(options)
 
-    collection_class.new(@client.get(base_uri, options).body, self)
+    collection_class.new(client.get(base_uri, options).body, client)
   end
 
   def build(attributes = {})
-    object_class.new(attributes, self)
+    object_class.new(attributes, client)
   end
 
-  def [](resource_id)
-    object_class.new(@client.get("#{base_uri}/#{resource_id}").body)
+  def create(attributes = {})
+    build(attributes).save
+  end
+
+  # For certain objects you can get extra data by giving option `include_data`.
+  # For example with clips you can add `include_data: "list,via"`.
+  def [](resource_id, options = {})
+    response = client.get("#{base_uri}/#{resource_id}", options)
+    if response.success?
+      object_class.new(response.body, client)
+    else
+      raise Kippt::APIError.new("Resource could not be loaded: #{response.body["message"]}")
+    end
   end
 
   alias find []
@@ -18,14 +31,14 @@ module Kippt::CollectionResource
   def collection_from_url(url)
     raise ArgumentError.new("The parameter URL can't be blank") if url.nil? || url == ""
 
-    collection_class.new(@client.get(url).body, self)
+    collection_class.new(client.get(url).body, client)
   end
 
   def save_resource(object)
     if object.id
-      response = @client.put("#{base_uri}/#{object.id}", :data => writable_parameters_from(object))
+      response = client.put("#{base_uri}/#{object.id}", :data => writable_parameters_from(object))
     else
-      response = @client.post("#{base_uri}", :data => writable_parameters_from(object))
+      response = client.post("#{base_uri}", :data => writable_parameters_from(object))
     end
 
     save_response = {:success => response.success?}
@@ -39,7 +52,7 @@ module Kippt::CollectionResource
 
   def destroy_resource(resource)
     if resource.id
-      @client.delete("#{base_uri}/#{resource.id}").success?
+      client.delete("#{base_uri}/#{resource.id}").success?
     end
   end
 
@@ -56,4 +69,8 @@ module Kippt::CollectionResource
   def writable_parameters_from(resource)
     resource.writable_attributes_hash
   end
+
+  def client
+    @client
+  end
 end