pinboard_api 0.1.0 → 0.7.0

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+.rbx/
 .bundle
 .config
 .yardoc

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+#   - rbx-19mode
+# env:
+#   - RBXOPT=-X19

data/Gemfile

@@ -1,4 +1,8 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in pinboard_api.gemspec
 gemspec
+
+platforms :jruby do
+  gem "jruby-openssl"
+end

data/README.md

@@ -1,4 +1,4 @@
-# PinboardApi
+# PinboardApi [![Build Status](https://secure.travis-ci.org/phlipper/pinboard_api.png?branch=master)](http://travis-ci.org/phlipper/pinboard_api) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/phlipper/pinboard_api)
 
 ## Description
 
@@ -9,8 +9,13 @@ This client aims to cover all of the Pinboard [API v1](https://pinboard.in/api/)
 
 ## Requirements
 
-* This library requires Ruby 1.9.2 or newer.
 * You must have a paid Pinboard account to use the API. It is a great service and you can [signup here](https://pinboard.in/signup/) if you don't already have an account.
+* Currently tested on the following Ruby versions:
+  * 1.9.2
+  * 1.9.3
+  * JRuby (1.9 mode)
+
+_Note:_ Specs are currently passing on Rubinius with `RBXOPT=-X19` on my local machine but there is a failing spec on [Travis CI](http://travis-ci.org/#!/phlipper/pinboard_api). I will update the `README` with official support for Rubinus once everything runs smoothly on Travis.
 
 
 ## Installation
@@ -34,6 +39,22 @@ $ gem install pinboard_api
 ```
 
 
+## Getting Started
+
+You will need to set your username and password for the Pinboard service.
+
+```ruby
+PinboardApi.username = "phlipper"
+PinboardApi.password = "[REDACTED]"
+```
+
+You may also set the SSL options which will be passed through to [Faraday](https://github.com/technoweenie/faraday#readme):
+
+```ruby
+PinboardApi.ssl_options = { ca_file: "/opt/local/share/curl/curl-ca-bundle.crt" }
+```
+
+
 ## Usage
 
 The `PinboardApi` namespace implements the 3 primary object types: `Post`, `Tag`, and `User`.
@@ -50,24 +71,63 @@ PinboardApi::Post.update
 ```
 
 * ~~[posts/add](https://pinboard.in/api#posts_add) - add a new bookmark~~
-* ~~[posts/delete](https://pinboard.in/api#posts_delete) - delete an existing bookmark~~
+* [posts/delete](https://pinboard.in/api#posts_delete) - delete an existing bookmark
+
+```ruby
+post = PinboardApi::Post.find(url: "https://pinboard.in/u:phlipper").first
+post.destroy
+# => #<PinboardApi::Post:0x007ffcb5166cf0 @description="Pinboard - antisocial bookmarking", @extended="", @hash="bc857ba651d134be0c9a5267e943c3ce", @url="https://pinboard.in/u:phlipper", @meta=nil, @tags="test", @time="2012-07-11T09:16:14Z">
+
+PinboardApi::Post.destroy("https://pinboard.in/u:phlipper")
+# => #<PinboardApi::Post:0x007f98d6946d78 @description="Pinboard - antisocial bookmarking", @extended="", @hash="bc857ba651d134be0c9a5267e943c3ce", @url="https://pinboard.in/u:phlipper", @meta=nil, @tags="test", @time="2012-07-11T09:17:36Z">
+```
+
 * [posts/get](https://pinboard.in/api#posts_get) - get bookmark for a single date, or fetch specific items by URL
 
 ```ruby
 PinboardApi::Post.find(tag: "test")
-# => [#<PinboardApi::Post:0x007fdce4547388 @description="Test.com – Certification Program Management – Create Online Tests with This Authoring, Management, Training and E-Learning Software", @extended="", @hash="dbb720d788ffaeb0afb7572104072f4a", @href="http://test.com/", @tags="test junk", @time="2012-07-07T04:18:28Z">, ...]
+# => [#<PinboardApi::Post:0x007fdce4547388 @description="Test.com – Certification Program Management – Create Online Tests with This Authoring, Management, Training and E-Learning Software", @extended="", @hash="dbb720d788ffaeb0afb7572104072f4a", @url="http://test.com/", @tags="test junk", @time="2012-07-07T04:18:28Z">, ...]
 
 PinboardApi::Post.find(hash: "dbb720d788ffaeb0afb7572104072f4a", meta: "yes")
-# => [#<PinboardApi::Post:0x007fac2b9d6690 @description="Test.com – Certification Program Management – Create Online Tests with This Authoring, Management, Training and E-Learning Software", @extended="", @hash="dbb720d788ffaeb0afb7572104072f4a", @href="http://test.com/", @meta="73b192512e3e4829806f5eee0a6b456d", @tags="test junk", @time="2012-07-07T04:18:28Z">, ...]
-
 PinboardApi::Post.find(dt: Date.parse("2012-07-07"))
-# => [#<PinboardApi::Post:0x007fac2ba0fdf0 @description="Test.com – Certification Program Management – Create Online Tests with This Authoring, Management, Training and E-Learning Software", @extended="", @hash="dbb720d788ffaeb0afb7572104072f4a", @href="http://test.com/", @meta=nil, @tags="test junk", @time="2012-07-07T04:18:28Z">, ...]
 ```
 
-* ~~[posts/dates](https://pinboard.in/api#posts_dates) - list dates on which bookmarks were posted~~
-* ~~[posts/recent](https://pinboard.in/api#posts_recent) - fetch recent bookmarks~~
-* ~~[posts/all](https://pinboard.in/api#posts_all) - fetch all bookmarks by date, tag, or range~~
-* ~~[posts/suggest](https://pinboard.in/api#posts_suggest) - fetch popular and recommended tags for a url~~
+* [posts/dates](https://pinboard.in/api#posts_dates) - list dates on which bookmarks were posted
+
+```ruby
+PinboardApi::Post.dates
+# => [{"count"=>1, "date"=>#<Date: 2012-07-10 ((2456119j,0s,0n),+0s,2299161j)>}, {"count"=>3, "date"=>#<Date: 2012-07-08 ((2456117j,0s,0n),+0s,2299161j)>}, ...]
+
+PinboardApi::Post.dates(tag: "ruby")
+```
+
+* [posts/recent](https://pinboard.in/api#posts_recent) - fetch recent bookmarks
+
+```ruby
+PinboardApi::Post.recent
+# => [#<PinboardApi::Post:0x007ffe150e1fd0 @description="Techniques to Secure Your Website with Ruby on Rails..."> ...]
+
+PinboardApi::Post.recent(count: 3)
+PinboardApi::Post.recent(tag: "ruby")
+PinboardApi::Post.recent(count: 25, tag: ["ruby", "programming"])
+```
+
+* [posts/all](https://pinboard.in/api#posts_all) - fetch all bookmarks by date, tag, or range
+
+```ruby
+PinboardApi::Post.all
+# => [#<PinboardApi::Post:0x007ffe150e1fd0 @description="Techniques to Secure Your Website with Ruby on Rails..."> ...]
+
+PinboardApi::Post.all(tag: %w[ruby programming], meta: true, results: 30)
+PinboardApi::Post.all(start: 50, fromdt: 2.weeks.ago, todt: 1.week.ago)
+```
+
+* [posts/suggest](https://pinboard.in/api#posts_suggest) - fetch popular and recommended tags for a url
+
+```ruby
+PinboardApi::Post.suggest("http://blog.com")
+# => {"popular"=>["hosting", "blogs", "blog", "free"], "recommended"=>["blog", "blogging", "blogs", "free"]}
+```
 
 
 ### Tag
@@ -86,13 +146,11 @@ PinboardApi::Tag.find("leadership")
 
 ```ruby
 tag = PinboardApi::Tag.find("foo")
+tag.destroy
 # => #<PinboardApi::Tag:0x007fdce45f56e0 @name="foo", @count=1>
 
-tag.delete
-# => #<PinboardApi::Tag:0x007fdce45f56e0 @name="foo", @count=1>
-
-tag = PinboardApi::Tag.find("foo")
-# => nil
+PinboardApi::Tag.destroy("foo")
+# => #<PinboardApi::Tag:0x007fdce45f20f8 @name="foo", @count=1>
 ```
 
 * [tags/rename](https://pinboard.in/api#tags_rename) - rename a tag
@@ -116,6 +174,13 @@ PinboardApi::User.secret
 ```
 
 
+## TODO
+
+* Implement Post.add/create
+* Implement support for the new `[auth_token](http://pinboard.in/api/#authentication)`
+* Cleanup/refactor internal exception handling
+
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,2 +1,12 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :default => :spec
+
+Rake::TestTask.new(:spec) do |t|
+  t.libs << "lib"
+  t.libs << "spec"
+  t.pattern = "spec/**/*_spec.rb"
+  t.verbose = false
+end

data/lib/core_ext/array.rb

@@ -0,0 +1,11 @@
+class Array
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary || [object]
+    else
+      [object]
+    end
+  end
+end

data/lib/core_ext/hash.rb

@@ -0,0 +1,8 @@
+class Hash
+  def stringify_keys!
+    keys.each do |key|
+      self[key.to_s] = delete(key)
+    end
+    self
+  end
+end

data/lib/pinboard_api.rb

@@ -1,6 +1,9 @@
 require "faraday"
 require "faraday_middleware"
 
+require "core_ext/array"
+require "core_ext/hash"
+
 require "pinboard_api/post"
 require "pinboard_api/tag"
 require "pinboard_api/user"
@@ -10,30 +13,33 @@ module PinboardApi
 
   class << self
     attr_accessor :username, :password, :adapter, :ssl_options
+  end
 
-    def adapter
-      @adapter ||= :net_http
-    end
+  def self.adapter
+    @adapter ||= :net_http
+  end
 
-    def ssl_options
-      @ssl_options ||= {}
-    end
+  def self.ssl_options
+    @ssl_options ||= {}
+  end
 
-    def api_version
-      "v1"
-    end
+  def self.api_version
+    "v1"
+  end
 
-    def api_url
-      "https://#{username}:#{password}@api.pinboard.in"
-    end
+  def self.api_url
+    "https://#{username}:#{password}@api.pinboard.in"
+  end
 
-    def connection
-      Faraday.new(url: api_url, ssl: ssl_options) do |builder|
-        builder.response :logger if ENV["PINBOARD_LOGGER"]
-        builder.response :xml, content_type: /\bxml$/
-        builder.adapter adapter
-      end
+  def self.connection
+    Faraday.new(url: api_url, ssl: ssl_options) do |builder|
+      builder.response :logger if ENV["PINBOARD_LOGGER"]
+      builder.response :xml, content_type: /\bxml$/
+      builder.adapter adapter
     end
   end
 
+  def self.request(path, options = {}, &blk)
+    PinboardApi.connection.get(path, options, &blk)
+  end
 end

data/lib/pinboard_api/post.rb

@@ -1,55 +1,137 @@
 module PinboardApi
   class Post
 
-    attr_reader :description, :extended, :hash, :href, :meta
+    attr_reader :description, :extended, :hash, :meta, :url
 
     def initialize(attributes = {})
+      attributes.stringify_keys!
+
       @description = attributes["description"]
       @extended    = attributes["extended"]
       @hash        = attributes["hash"]
-      @href        = attributes["href"]
       @meta        = attributes["meta"]
+      @url         = attributes["url"] || attributes["href"]
       @tags        = attributes["tags"] || attributes["tag"]
       @time        = attributes["time"] || Time.now
     end
 
     def time
-      if @time.is_a?(Time)
-        @time
-      elsif @time.is_a?(Date)
-        @time.to_time
-      else
-        Time.parse(@time)
-      end
+      @time.is_a?(String) ? Time.parse(@time) : @time.to_time
     end
 
     def tags
       @tags.is_a?(String) ? @tags.split(/\s+/) : @tags
     end
 
+    def destroy
+      path = "/#{PinboardApi.api_version}/posts/delete"
+      body = PinboardApi.request(path, url: @url).body["result"]
+
+      if body && body.fetch("code", "") == "done"
+        self
+      else
+        raise RuntimeError, "unknown response"
+      end
+    end
+
+    def self.destroy(url)
+      if post = find(url: url).first
+        post.destroy
+      else
+        raise RuntimeError, "unknown response"
+      end
+    end
+
+    def self.all(options = {})
+      path = "/#{PinboardApi.api_version}/posts/all"
+
+      tag    = tag_param_string(options[:tag])
+      fromdt = dt_param_string(options[:fromdt])
+      todt   = dt_param_string(options[:todt])
+
+      response = PinboardApi.request(path) do |req|
+        req.params["tag"]     = tag if tag
+        req.params["start"]   = options[:start] if options[:start]
+        req.params["results"] = options[:results] if options[:results]
+        req.params["fromdt"]  = fromdt if fromdt
+        req.params["todt"]    = todt if todt
+        req.params["meta"]    = 1 if options[:meta]
+      end
+
+      extract_posts(response.body["posts"])
+    end
 
     def self.find(options = {})
       path = "/#{PinboardApi.api_version}/posts/get"
-      response = PinboardApi.connection.get(path) do |req|
+      response = PinboardApi.request(path) do |req|
         options.each_pair { |k,v| req.params[k.to_s] = v }
       end
+      extract_posts(response.body["posts"])
+    end
+
+    def self.last_update
+      path = "/#{PinboardApi.api_version}/posts/update"
+      body = PinboardApi.request(path).body
+      Time.parse(body["update"]["time"])
+    end
 
-      posts = response.body["posts"]
-      if posts.keys.include?("post")
-        posts.inject([]) do |collection, tuple|
-          key, attrs = tuple
-          Array(collection) << new(attrs) if key == "post"
+    def self.suggest(url)
+      path = "/#{PinboardApi.api_version}/posts/suggest"
+      response = PinboardApi.request(path, url: url)
+      response.body["suggested"]
+    end
+
+    def self.recent(options = {})
+      path = "/#{PinboardApi.api_version}/posts/recent"
+      tag = tag_param_string(options[:tag])
+      count = options[:count]
+
+      response = PinboardApi.request(path) do |req|
+        req.params["tag"] = tag if tag
+        req.params["count"] = count if count
+      end
+
+      extract_posts(response.body["posts"])
+    end
+
+    def self.dates(options = {})
+      path = "/#{PinboardApi.api_version}/posts/dates"
+      tag = tag_param_string(options[:tag])
+
+      response = PinboardApi.request(path) do |req|
+        req.params["tag"] = tag if tag
+      end
+
+      dates = response.body["dates"]["date"]
+      dates.map do |date|
+        { "count" => date["count"].to_i, "date" =>  Date.parse(date["date"]) }
+      end
+    end
+
+
+    def self.extract_posts(payload)
+      unless payload.respond_to?(:keys) && payload.keys.include?("post")
+        return Array.new
+      end
+
+      # response.body["posts"] - "429 Too Many Requests.  Wait 60 seconds before fetching posts/all again."
+
+      payload.inject([]) do |collection, (key, attrs)|
+        if key == "post"
+          Array.wrap(attrs).each do |post|
+            Array.wrap(collection) << new(post)
+          end
         end
-      else
-        Array.new
+        collection
       end
     end
 
-    def self.update
-      path = "/#{PinboardApi.api_version}/posts/update"
-      body = PinboardApi.connection.get(path).body
-      Time.parse(body["update"]["time"])
+    def self.dt_param_string(time)
+      time.nil? ? nil : time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
     end
 
+    def self.tag_param_string(tags)
+      tags.nil? ? nil : Array.wrap(tags).join(",")
+    end
   end
 end

data/lib/pinboard_api/tag.rb

@@ -9,25 +9,22 @@ module PinboardApi
 
     def rename(new_name)
       path = "/#{PinboardApi.api_version}/tags/rename"
-      response = PinboardApi.connection.get(path) do |req|
-        req.params["old"] = self.name
+      response = PinboardApi.request(path) do |req|
+        req.params["old"] = @name
         req.params["new"] = new_name.to_s
       end
       body = response.body
 
       if body["result"] == "done"
-        Tag.new("name" => new_name, "count" => self.count)
+        Tag.new("name" => new_name, "count" => @count)
       else
         raise body["result"].to_s
       end
     end
 
-    def delete
+    def destroy
       path = "/#{PinboardApi.api_version}/tags/delete"
-      response = PinboardApi.connection.get(path) do |req|
-        req.params["tag"] = self.name
-      end
-      body = response.body
+      body = PinboardApi.request(path, tag: @name).body
 
       if body["result"] == "done"
         self
@@ -38,13 +35,18 @@ module PinboardApi
 
     def self.all
       path = "/#{PinboardApi.api_version}/tags/get"
-      body = PinboardApi.connection.get(path).body
+      body = PinboardApi.request(path).body
       body["tags"]["tag"].map { |tag| new(tag) }
+    rescue
+      raise RuntimeError, "unknown response"
     end
 
     def self.find(name)
       all.detect { |t| t.name == name }
     end
 
+    def self.destroy(tag)
+      find(tag).destroy
+    end
   end
 end