pinboard_api 0.7.0 → 1.0.0

data/.travis.yml

@@ -4,5 +4,6 @@ rvm:
   - 1.9.3
   - jruby-19mode # JRuby in 1.9 mode
 #   - rbx-19mode
-# env:
+env:
+  - PINBOARD_USERNAME=phlipper
 #   - RBXOPT=-X19

data/README.md

@@ -41,13 +41,19 @@ $ gem install pinboard_api
 
 ## Getting Started
 
-You will need to set your username and password for the Pinboard service.
+You will need to set your username and password for the Pinboard service:
 
 ```ruby
 PinboardApi.username = "phlipper"
 PinboardApi.password = "[REDACTED]"
 ```
 
+Alternately, you may use the new [`auth_token`](http://pinboard.in/api/#authentication) method:
+
+```ruby
+PinboardApi.auth_token = "[REDACTED]"
+```
+
 You may also set the SSL options which will be passed through to [Faraday](https://github.com/technoweenie/faraday#readme):
 
 ```ruby
@@ -66,11 +72,27 @@ The `PinboardApi` namespace implements the 3 primary object types: `Post`, `Tag`
 * [posts/update](https://pinboard.in/api#update) - Check to see when a user last posted an item.
 
 ```ruby
-PinboardApi::Post.update
+PinboardApi::Post.last_update
 # => 2012-07-07 04:18:28 UTC
 ```
 
-* ~~[posts/add](https://pinboard.in/api#posts_add) - add a new bookmark~~
+* [posts/add](https://pinboard.in/api#posts_add) - add a new bookmark
+
+```ruby
+attributes = { url: "http://phlippers.net/pinboard_api", description: "A Ruby client for the Pinboard.in API", tags: %[ruby awesomesauce] }
+
+post = PinboardApi::Post.new(attributes)
+post.save
+# => #<PinboardApi::Post:0x007fb42d905a68 @description="A Ruby client for the Pinboard.in API", @extended=nil, @hash=nil, @meta=nil, @url="http://phlippers.net/pinboard_api", @tags="ruby awesomesauce", @time=2012-07-13 23:03:34 -0700>
+
+post = PinboardApi::Post.new
+post.url = attributes[:url]
+post.description = attributes[:description]
+post.save
+
+PinboardApi::Post.create(attributes)
+```
+
 * [posts/delete](https://pinboard.in/api#posts_delete) - delete an existing bookmark
 
 ```ruby
@@ -176,9 +198,7 @@ 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
+* Implement support for rate limiting
 
 
 ## Contributing

data/lib/core_ext/blank.rb

@@ -0,0 +1,26 @@
+class NilClass
+  def blank?
+    true
+  end
+end
+
+class FalseClass
+  def blank?
+    true
+  end
+end
+
+class Object
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+end
+
+class String
+  # 0x3000: fullwidth whitespace
+  NON_WHITESPACE_REGEXP = /[^\s#{[0x3000].pack("U")}]/
+
+  def blank?
+    self !~ NON_WHITESPACE_REGEXP
+  end
+end

data/lib/pinboard_api.rb

@@ -2,8 +2,12 @@ require "faraday"
 require "faraday_middleware"
 
 require "core_ext/array"
+require "core_ext/blank"
 require "core_ext/hash"
 
+require "pinboard_api/exceptions"
+require "pinboard_api/request_utils"
+
 require "pinboard_api/post"
 require "pinboard_api/tag"
 require "pinboard_api/user"
@@ -12,7 +16,7 @@ require "pinboard_api/version"
 module PinboardApi
 
   class << self
-    attr_accessor :username, :password, :adapter, :ssl_options
+    attr_accessor :username, :password, :auth_token, :adapter, :ssl_options
   end
 
   def self.adapter
@@ -28,18 +32,20 @@ module PinboardApi
   end
 
   def self.api_url
-    "https://#{username}:#{password}@api.pinboard.in"
+    "https://api.pinboard.in"
   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.basic_auth username, password if auth_token.blank?
       builder.adapter adapter
     end
   end
 
   def self.request(path, options = {}, &blk)
+    options.merge!(auth_token: auth_token) unless auth_token.blank?
     PinboardApi.connection.get(path, options, &blk)
   end
 end

data/lib/pinboard_api/exceptions.rb

@@ -0,0 +1,5 @@
+module PinboardApi
+  class PinboardApiError < StandardError; end
+  class InvalidPostError < PinboardApiError; end
+  class InvalidResponseError < PinboardApiError; end
+end

data/lib/pinboard_api/post.rb

@@ -1,5 +1,6 @@
 module PinboardApi
   class Post
+    include PinboardApi::RequestUtils
 
     attr_reader :description, :extended, :hash, :meta, :url
 
@@ -23,41 +24,71 @@ module PinboardApi
       @tags.is_a?(String) ? @tags.split(/\s+/) : @tags
     end
 
+    def save(options = {})
+      validate!
+      path = "/#{PinboardApi.api_version}/posts/add"
+      params = {
+        url:         @url,
+        description: @description,
+        extended:    @extended,
+        tags:        Post.tag_param_string(tags),
+        dt:          options[:dt],
+        replace:     yes_no(options[:replace]),
+        shared:      yes_no(options[:shared]),
+        toread:      yes_no(options[:toread])
+      }
+
+      result = PinboardApi.request(path, params).body["result"]
+      parse_result_code(result)
+    end
+
     def destroy
       path = "/#{PinboardApi.api_version}/posts/delete"
-      body = PinboardApi.request(path, url: @url).body["result"]
+      result = PinboardApi.request(path, url: @url).body["result"]
+      parse_result_code(result)
+    end
 
-      if body && body.fetch("code", "") == "done"
-        self
-      else
-        raise RuntimeError, "unknown response"
+    def validate!
+      if @url.blank?
+        raise InvalidPostError, "url cannot be blank"
+      end
+      if @description.blank?
+        raise InvalidPostError, "description cannot be blank"
+      end
+    end
+
+    def parse_result_code(result)
+      unless result && code = result.fetch("code", false)
+        raise InvalidResponseError, "unknown response"
       end
+
+      code == "done" ? self : raise(InvalidResponseError, code.to_s)
+    end
+
+    def self.create(attributes)
+      new(attributes).save
     end
 
     def self.destroy(url)
       if post = find(url: url).first
         post.destroy
       else
-        raise RuntimeError, "unknown response"
+        raise InvalidResponseError, "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
-
+      params = {
+        tag:     tag_param_string(options[:tag]),
+        start:   options[:start],
+        results: options[:results],
+        fromdt:  dt_param_string(options[:fromdt]),
+        todt:    dt_param_string(options[:todt]),
+        meta:    (options[:meta] ? 1 : 0)
+      }
+
+      response = PinboardApi.request(path, params)
       extract_posts(response.body["posts"])
     end
 
@@ -83,24 +114,15 @@ module PinboardApi
 
     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
-
+      params = { tag: tag_param_string(options[:tag]), count: options[:count] }
+      response = PinboardApi.request(path, params)
       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
+      response = PinboardApi.request(path, tag: tag)
 
       dates = response.body["dates"]["date"]
       dates.map do |date|
@@ -125,13 +147,5 @@ module PinboardApi
         collection
       end
     end
-
-    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/request_utils.rb

@@ -0,0 +1,22 @@
+module PinboardApi
+  module RequestUtils
+    def self.included(receiver)
+      receiver.extend ClassMethods
+    end
+
+    def yes_no(value)
+      return nil if value.nil?
+      value ? "yes" : "no"
+    end
+
+    module ClassMethods
+      def tag_param_string(tags)
+        tags.nil? ? nil : Array.wrap(tags).join(",")
+      end
+
+      def dt_param_string(time)
+        time.nil? ? nil : time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      end
+    end
+  end
+end

data/lib/pinboard_api/tag.rb

@@ -3,6 +3,8 @@ module PinboardApi
     attr_reader :name, :count
 
     def initialize(attributes = {})
+      attributes.stringify_keys!
+
       @name  = attributes["name"] || attributes["tag"]
       @count = attributes["count"].to_i
     end
@@ -13,23 +15,23 @@ module PinboardApi
         req.params["old"] = @name
         req.params["new"] = new_name.to_s
       end
-      body = response.body
+      result = response.body["result"]
 
-      if body["result"] == "done"
-        Tag.new("name" => new_name, "count" => @count)
+      if result == "done"
+        Tag.new(name: new_name, count: @count)
       else
-        raise body["result"].to_s
+        raise InvalidResponseError, result.to_s
       end
     end
 
     def destroy
       path = "/#{PinboardApi.api_version}/tags/delete"
-      body = PinboardApi.request(path, tag: @name).body
+      result = PinboardApi.request(path, tag: @name).body["result"]
 
-      if body["result"] == "done"
+      if result == "done"
         self
       else
-        raise body["result"].to_s
+        raise InvalidResponseError, result.to_s
       end
     end
 
@@ -38,7 +40,7 @@ module PinboardApi
       body = PinboardApi.request(path).body
       body["tags"]["tag"].map { |tag| new(tag) }
     rescue
-      raise RuntimeError, "unknown response"
+      raise InvalidResponseError, "unknown response"
     end
 
     def self.find(name)

data/lib/pinboard_api/version.rb

@@ -1,3 +1,3 @@
 module PinboardApi
-  VERSION = "0.7.0"
+  VERSION = "1.0.0"
 end

data/spec/core_ext/blank_spec.rb

@@ -0,0 +1,19 @@
+require "spec_helper"
+
+describe NilClass do
+  it { nil.must_be :blank? }
+end
+
+describe FalseClass do
+  it { false.must_be :blank? }
+end
+
+describe Object do
+  it { [].must_be :blank? }
+  it { ["foo"].wont_be :blank? }
+end
+
+describe String do
+  it { "".must_be :blank? }
+  it { "foo".wont_be :blank? }
+end

data/spec/exceptions_spec.rb

@@ -0,0 +1,7 @@
+require "spec_helper"
+
+describe PinboardApi do
+  it { PinboardApi::PinboardApiError.new.must_be_kind_of StandardError }
+  it { PinboardApi::InvalidPostError.new.must_be_kind_of PinboardApi::PinboardApiError }
+  it { PinboardApi::InvalidResponseError.new.must_be_kind_of PinboardApi::PinboardApiError }
+end

data/spec/pinboard_api_spec.rb

@@ -4,18 +4,22 @@ describe PinboardApi do
   before do
     @username = PinboardApi.username
     @password = PinboardApi.password
+    @auth_token = PinboardApi.auth_token
 
     PinboardApi.username = nil
     PinboardApi.password = nil
+    PinboardApi.auth_token = nil
   end
 
   after do
     PinboardApi.username = @username
     PinboardApi.password = @password
+    PinboardApi.auth_token = @auth_token
   end
 
   it { PinboardApi.must_respond_to :username }
   it { PinboardApi.must_respond_to :password }
+  it { PinboardApi.must_respond_to :auth_token }
 
   it { PinboardApi.must_respond_to :api_version }
   it { PinboardApi.api_version.must_equal "v1" }
@@ -27,7 +31,7 @@ describe PinboardApi do
   it { PinboardApi.ssl_options.must_be_kind_of Hash }
 
   it { PinboardApi.must_respond_to :api_url }
-  it { PinboardApi.api_url.must_equal "https://:@api.pinboard.in" }
+  it { PinboardApi.api_url.must_equal "https://api.pinboard.in" }
 
   it { PinboardApi.must_respond_to :connection }
   it { PinboardApi.connection.must_be_kind_of Faraday::Connection }
@@ -36,23 +40,22 @@ describe PinboardApi do
     before do
       @username = PinboardApi.username
       @password = PinboardApi.password
+      @auth_token = PinboardApi.auth_token
 
       PinboardApi.username = "username"
       PinboardApi.password = "password"
+      PinboardApi.auth_token = "auth_token"
     end
 
     after do
       PinboardApi.username = @username
       PinboardApi.password = @password
+      PinboardApi.auth_token = @auth_token
     end
 
     it { PinboardApi.username.must_equal "username" }
     it { PinboardApi.password.must_equal "password" }
-
-    it "adds credentials to the api_url" do
-      url = "https://username:password@api.pinboard.in"
-      PinboardApi.api_url.must_equal url
-    end
+    it { PinboardApi.auth_token.must_equal "auth_token" }
   end
 
   describe "ssl_options" do