pinboard 0.0.51 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 34dae5a7d0157a62075e08ae484d3b97959ed666
-  data.tar.gz: 4f2c559e7af3f1f43e37270872c18e202f0776ca
+  metadata.gz: 87cc2921a9f8b072ac29ce9be0629ebc368cca61
+  data.tar.gz: 9bb8e0dc7769f13d49227efe154d5678178083de
 SHA512:
-  metadata.gz: 65a44277439c422d52ff695b557c4e781c7b5225459ab321e64735445b52c3ff4e41198e323a786b69b82b8a8c0f03f80bedad6209739ee4b44014c99475b66d
-  data.tar.gz: 3498b877afc4bef15ba34728aa2b302f7ceeb7f521b2c8e6dd7a1f35fffe3c7729123ff457a2866103677f9ab3b7796f5c8f73b927e26f16d3a9e4fa984ab9e5
+  metadata.gz: 1d2ff69a5c1f26f2721cb53f26bd67d4672112b205c7000dde9de8e400df1bae1245e747822cc703f3efcfa26c151fdbc94f33b5ce1847a99eeb8eec91cf8651
+  data.tar.gz: e129eaa534e5cf5f6c4ad85f0888c1f38941914bd9564ceda05fdb1d987a757ff60ce514b8b91d220caf9c5ec5c3fff48386b45f619a2938745d187c4f683689

data/.travis.yml

@@ -1,6 +1,4 @@
 rvm:
-  - 1.8.7
-  - 1.9.2
+  - 1.9.3
   - jruby
-  - ree
   - ruby-head

data/lib/pinboard.rb

@@ -1,6 +1,8 @@
 require 'pinboard/util'
 require 'pinboard/client'
 require 'pinboard/post'
+require 'pinboard/tag'
+require 'pinboard/note'
 
 module Pinboard
   class << self

data/lib/pinboard/client.rb

@@ -1,31 +1,56 @@
 require 'httparty'
+require 'time'
 
 module Pinboard
+  # Raised when API returns failure
   Error = Class.new(StandardError)
 
   class Client
     include HTTParty
     base_uri 'api.pinboard.in:443/v1'
 
+    # Construct a new instance of the client
+    #
+    # @param [Hash] options Options for the connection
+    # @option options [String] :token The Pinboard API token (prefered over username & password)
+    # @option options [String] :username Pinboard username
+    # @option options [String] :password Pinboard password
     def initialize(options={})
-      @auth = { :username => options[:username],
-                :password => options[:password] }
+      @auth       = nil
+      @auth_token = nil
+
+      if (token=options.delete(:token))
+        @auth_token = token
+      else
+        @auth = {
+          username: options[:username],
+          password: options[:password]
+        }
+      end
     end
 
+    # Returns all bookmarks in the user's account.
+    #
+    # @return [Array<Post>] the list of bookmarks.
     def posts(params={})
-      options = {}
-      options[:basic_auth] = @auth
-      options[:query] = params
+      options = create_params(params)
       posts = self.class.get('/posts/all', options)['posts']['post']
       posts = [] if posts.nil?
       posts = [posts] if posts.class != Array
       posts.map { |p| Post.new(Util.symbolize_keys(p)) }
     end
 
+    # Add a bookmark
+    #
+    # @param [Hash] params Arguments for this call
+    # @option params [String] :url the URL of the item (required)
+    # @option params [String] :description Title of the item
+    # @option params [String] :extended Description of the item
+    # @option params [Array] :tags List of up to 100 tags
+    # @option params [Boolean] :replace Replace any existing bookmark with this URL (default: true)
+    # @option params [Boolean] :shared Make bookmark public (default: true)
+    # @option params [Boolean] :toread Marks the bookmark as unread (default: false)
     def add(params={})
-      options = {}
-      options[:basic_auth] = @auth
-
       # Pinboard expects multiple tags=foo,bar separated by comma instead of tag=foo&tag=bar
       params[:tags] = Array(params[:tags]).join(',') if params[:tags]
 
@@ -34,19 +59,139 @@ module Pinboard
           params[boolean] = params[boolean] ? 'yes' : 'no' if params.has_key?(boolean)
       end
 
-      options[:query] = params
+      options = create_params(params)
       result_code = self.class.post('/posts/add', options).parsed_response["result"]["code"]
 
       raise Error.new(result_code) if result_code != "done"
     end
 
-    def delete(params={})
-      options = {}
-      options[:basic_auth] = @auth
-      options[:query] = params
+    # Returns the most recent time a bookmark was added, updated or deleted.
+    #
+    # Use this before calling {#posts} to see if the data has changed
+    # since the last fetch.
+    #
+    # @return [Time] the time a bookmark was modified
+    def update
+      options = create_params({})
+      time = self.class.get('/posts/update', options)["update"]["time"]
+
+      Time.parse time
+    end
+
+    # Returns a list of the user's most recent posts, filtered by tag.
+    #
+    # @param <Hash> params the options to filter current posts
+    # @option params [String] :tag filter by up to three tags
+    # @option params [String] :count Number of results to return.
+    #                                Default is 15, max is 100
+    #
+    # @return [Array<Post>] the list of recent posts.
+    def recent(params={})
+      options = create_params(params)
+      posts = self.class.get('/posts/recent', options)['posts']['post']
+      posts = [] if posts.nil?
+      posts = [*posts]
+      posts.map { |p| Post.new(Util.symbolize_keys(p)) }
+    end
+
+    # Returns a list of dates with the number of posts at each date.
+    #
+    # @param [String] tag Filter by up to three tags
+    #
+    # @return [Hash<String,Fixnum>] List of dates with number of posts
+    #                               at each date
+    def dates(tag=nil)
+      params = {}
+      params[:tag] = tag if tag
+
+      options = create_params(params)
+      dates = self.class.get('/posts/dates', options)['dates']['date']
+      dates = [] if dates.nil?
+      dates = [*dates]
+      dates.each_with_object({}) { |value, hash|
+        hash[value["date"]] = value["count"].to_i
+      }
+    end
+
+
+    # Delete a bookmark
+    #
+    # @param [String] url The url to delete
+    def delete(url)
+      params = { url: url }
+      options = create_params(params)
       result_code = self.class.get('/posts/delete', options).parsed_response["result"]["code"]
 
       raise Error.new(result_code) if result_code != "done"
     end
+
+    # Returns a full list of the user's tags along with the number of
+    # times they were used.
+    #
+    # @return [Array<Tag>] List of all tags
+    def tags_get(params={})
+      options = create_params(params)
+      tags = self.class.get('/tags/get', options)['tags']['tag']
+      tags = [] if tags.nil?
+      tags = [*tags]
+      tags.map { |p| Tag.new(Util.symbolize_keys(p)) }
+    end
+
+    # Rename an tag or fold it into an existing tag
+    #
+    # @param [String] old_tag Tag to rename (not case sensitive)
+    # @param [String] new_tag New tag (if empty nothing will happen)
+    #
+    # @raise [Error] if result code is not "done"
+    def tags_rename(old_tag, new_tag=nil, params={})
+      params[:old] = old_tag
+      params[:new] = new_tag if new_tag
+
+      options = create_params(params)
+      result_code = self.class.get('/tags/rename', options).parsed_response["result"]
+
+      raise Error.new(result_code) if result_code != "done"
+    end
+
+    # Delete an existing tag
+    #
+    # @param [String] tag Tag to delete
+    # @return [nil]
+    def tags_delete(tag)
+      params = { tag: tag }
+
+      options = create_params(params)
+      self.class.get('/tags/delete', options)
+      nil
+    end
+
+    # Returns a list of the user's notes
+    #
+    # @return [Array<Note>] list of notes
+    def notes_list
+      options = create_params(params)
+      notes = self.class.get('/notes/list', options)['notes']['note']
+      notes = [] if notes.nil?
+      notes = [*notes]
+      notes.map { |p| Note.new(Util.symbolize_keys(p)) }
+    end
+
+    private
+    # Construct params hash for HTTP request
+    #
+    # @param [Hash] params Query arguments to include in request
+    # @return [Hash] Options hash for request
+    def create_params params
+      options = {}
+      options[:query] = params
+
+      if @auth_token
+        options[:query].merge!(auth_token: @auth_token)
+      else
+        options[:basic_auth] = @auth
+      end
+
+      options
+    end
   end
 end

data/lib/pinboard/note.rb

@@ -0,0 +1,22 @@
+module Pinboard
+  class Note < Struct.new(:id, :title, :created_at, :updated_at, :length)
+    def initialize(attributes={})
+      self.id         = attributes[:id]
+      self.title      = attributes[:title]
+      self.created_at = Util.parse_time(attributes[:created_at])
+      self.updated_at = Util.parse_time(attributes[:updated_at])
+      self.length     = attributes[:length].to_i
+      self.text       = attributes[:text]
+    end
+
+    def to_json(*args)
+      {
+        id:          id,
+        title:       title,
+        created_at:  created_at,
+        updated_at:  updated_at,
+        length:      length
+      }.to_json(*args)
+    end
+  end
+end

data/lib/pinboard/post.rb

@@ -15,5 +15,18 @@ module Pinboard
         send("#{attribute}=", value) if respond_to?("#{attribute}=")
       end
     end
+
+    def to_json(*args)
+      {
+        href:         href,
+        description:  description,
+        extended:     extended,
+        tag:          tag,
+        time:         time,
+        replace:      replace,
+        shared:       shared,
+        toread:       toread
+      }.to_json(*args)
+    end
   end
 end

data/lib/pinboard/tag.rb

@@ -0,0 +1,8 @@
+module Pinboard
+  class Tag < Struct.new(:tag, :count)
+    def initialize(attributes={})
+      self.tag = attributes.delete(:tag)
+      self.count  = attributes.delete(:count).to_i
+    end
+  end
+end

data/pinboard.gemspec

@@ -10,13 +10,13 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rb-fsevent'
   s.add_development_dependency 'terminal-notifier-guard'
 
-  s.add_runtime_dependency 'httparty', '= 0.7.8'
+  s.add_runtime_dependency 'httparty', '= 0.11.0'
   s.name = 'pinboard'
-  s.version = '0.0.51'
-  s.date = '2013-03-28'
+  s.version = '0.1.0'
+  s.date = '2013-04-28'
   s.summary = "Ruby wrapper for the Pinboard API"
   s.description = "Ruby wrapper for the Pinboard API"
-  s.authors = ["Ryan Waker"]
+  s.authors = ["Ry Waker", "Jan-Erik Rediger"]
   s.email = 'ry@rywalker.com'
   s.require_paths = ['lib']
   s.files = `git ls-files`.split("\n")

data/spec/fixtures/dates.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<dates user="user" tag="">
+    <date count="1" date="2013-04-19" />
+    <date count="2" date="2013-04-18" />
+    <date count="3" date="2013-04-17" />
+</dates>

data/spec/fixtures/dates_filtered.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<dates user="user" tag="tag">
+    <date count="1" date="2013-04-19" />
+    <date count="2" date="2013-04-18" />
+    <date count="3" date="2013-04-17" />
+</dates>

data/spec/fixtures/post_update.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<update>
+    <time>2013-04-20 13:58:56 +0200</time>
+</update>
+

data/spec/pinboard/client_spec.rb

@@ -70,7 +70,7 @@ describe Pinboard::Client do
       end
 
       it "succeeds without raising an error" do
-        expect{client.delete(:url => "http://bar.com/")}.to_not raise_error
+        expect{client.delete("http://bar.com/")}.to_not raise_error
       end
     end
 
@@ -82,7 +82,7 @@ describe Pinboard::Client do
       end
 
       it "throws an error" do
-        expect{client.delete(:url => "http://baz.com/")}.to raise_error(Pinboard::Error, 'item not found')
+        expect{client.delete("http://baz.com/")}.to raise_error(Pinboard::Error, 'item not found')
       end
     end
   end
@@ -235,4 +235,93 @@ describe Pinboard::Client do
       end
     end
   end
+
+  describe "#update" do
+    let(:client) { Pinboard::Client.new(auth_params) }
+
+    before do
+      stub_get("posts/update?").
+        to_return(:body => fixture("post_update.xml"),
+                  :headers => { 'content-type' => 'text/xml' })
+    end
+
+    it "returns the time of last update" do
+      expected = Time.parse "2013-04-20 13:58:56 +0200"
+
+      client.update.should == expected
+    end
+  end
+
+  describe "#recent" do
+    let(:client) { Pinboard::Client.new(auth_params) }
+
+    before do
+      stub_get("posts/recent?").
+        to_return(:body => fixture("multiple_posts.xml"),
+                  :headers => { 'content-type' => 'text/xml' })
+    end
+
+    it "returns recent items" do
+      expected = [
+          Pinboard::Post.new(
+            :href => "http://foo.com/",
+            :description => "Foo!",
+            :extended => "long description Foo",
+            :tag => 'foo bar',
+            :toread => 'yes',
+            :time => Time.parse("2011-07-26T17:52:04Z")),
+            Pinboard::Post.new(
+              :href => "http://bar.com/",
+              :description => "Bar!",
+              :extended => "long description Bar",
+              :tag => 'foo bar',
+              :toread => 'yes',
+              :time => Time.parse("2011-07-26T17:52:04Z")),
+      ]
+
+      client.recent.should == expected
+    end
+  end
+
+  describe "#dates" do
+    let(:client) { Pinboard::Client.new(auth_params) }
+
+    context "unfiltered" do
+      before do
+        stub_get("posts/dates?").
+          to_return(:body => fixture("dates.xml"),
+                    :headers => { 'content-type' => 'text/xml' })
+      end
+
+      it "returns a list of dates with the number of posts at each date" do
+
+        expected = {
+          "2013-04-19" => 1,
+          "2013-04-18" => 2,
+          "2013-04-17" => 3
+        }
+
+        client.dates.should == expected
+      end
+    end
+
+    context "filtered by tag" do
+      before do
+        stub_get("posts/dates?tag=tag").
+          to_return(:body => fixture("dates_filtered.xml"),
+                    :headers => { 'content-type' => 'text/xml' })
+      end
+
+      it "returns a list of dates with the number of posts at each date" do
+
+        expected = {
+          "2013-04-19" => 1,
+          "2013-04-18" => 2,
+          "2013-04-17" => 3
+        }
+
+        client.dates("tag").should == expected
+      end
+    end
+  end
 end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: pinboard
 version: !ruby/object:Gem::Version
-  version: 0.0.51
+  version: 0.1.0
 platform: ruby
 authors:
-- Ryan Waker
+- Ry Waker
+- Jan-Erik Rediger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-28 00:00:00.000000000 Z
+date: 2013-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -156,14 +157,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.7.8
+        version: 0.11.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.7.8
+        version: 0.11.0
 description: Ruby wrapper for the Pinboard API
 email: ry@rywalker.com
 executables: []
@@ -181,16 +182,21 @@ files:
 - Rakefile
 - lib/pinboard.rb
 - lib/pinboard/client.rb
+- lib/pinboard/note.rb
 - lib/pinboard/post.rb
+- lib/pinboard/tag.rb
 - lib/pinboard/util.rb
 - pinboard.gemspec
 - spec/fixtures/created.xml
+- spec/fixtures/dates.xml
+- spec/fixtures/dates_filtered.xml
 - spec/fixtures/deleted.xml
 - spec/fixtures/missing_description.xml
 - spec/fixtures/missing_url.xml
 - spec/fixtures/multiple_posts.xml
 - spec/fixtures/no_posts.xml
 - spec/fixtures/not_found.xml
+- spec/fixtures/post_update.xml
 - spec/fixtures/single_post.xml
 - spec/helper.rb
 - spec/pinboard/client_spec.rb
@@ -215,18 +221,21 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Ruby wrapper for the Pinboard API
 test_files:
 - spec/fixtures/created.xml
+- spec/fixtures/dates.xml
+- spec/fixtures/dates_filtered.xml
 - spec/fixtures/deleted.xml
 - spec/fixtures/missing_description.xml
 - spec/fixtures/missing_url.xml
 - spec/fixtures/multiple_posts.xml
 - spec/fixtures/no_posts.xml
 - spec/fixtures/not_found.xml
+- spec/fixtures/post_update.xml
 - spec/fixtures/single_post.xml
 - spec/helper.rb
 - spec/pinboard/client_spec.rb