thumbtack 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b204797fab0cc2277a9a96a0fb7f117351e77682
-  data.tar.gz: e58eb6b1b2e6e82b4c8d90cbef2cda993756884b
+  metadata.gz: af013ae7caf72e5d517bd5ce42ef097a804fca78
+  data.tar.gz: 35a058f9bc768ab4fadf48882993d3393dd5c627
 SHA512:
-  metadata.gz: edcf405a5c45dd0dd17786f292a650a44ba543de43a4318afd363b1acb592abe9b9893f037b32624a9410bc2f654eac5345708529db054919c3e1629bc41d380
-  data.tar.gz: 625d10851ca09eb39916d42c34edbcebd6db93bb1e8f1d318a9048cab8283c1d2effc35377da3c4c829723e28b7f8e463b54bd5a8bff48fc4ec97bf76b3bda37
+  metadata.gz: 73795d3553e3e56dd4cbd6d83cb9e9e47f90750c46963f703811d7a53a6e8019ab8aebf3693f8fe675219e6a8a05adb6779bbd3e2a7af917434a8af740407c85
+  data.tar.gz: a33adcc946c096f2e8dccfc3a34a166eec774a4006b396fd2a02a0107750424c7f7b495f3cb0be4c9437fcb7b34c53a78d7d6218d5d79a81e7e03661e6e52c8f

data/lib/thumbtack.rb

@@ -2,6 +2,11 @@
 
 # A simple Pinboard API wrapper
 module Thumbtack
+  # An empty Hash to use for default options
+  EMPTY_HASH = {}.freeze
+
+  # An empty Hash to use for `#fetch` fallbacks
+  EMPTY_ARRAY = [].freeze
 end
 
 require 'date'
@@ -22,6 +27,7 @@ require 'thumbtack/types/title'
 require 'thumbtack/types/url'
 require 'thumbtack/specification'
 require 'thumbtack/post'
+require 'thumbtack/suggestion'
 require 'thumbtack/posts'
 require 'thumbtack/tags'
 require 'thumbtack/user'

data/lib/thumbtack/client.rb

@@ -1,68 +1,114 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Public: Wraps each interaction with the Pinboard API.
+  # Wraps each interaction with the Pinboard API
   class Client
-    # Public: String of base Pinboard API URL.
+    # Raised when the API rate limit has been reached
+    class RateLimitError < StandardError; end
+
+    # The status code for rate limited responses from the Pinboard API
+    TOO_MANY_REQUESTS_CODE = '429'.freeze
+
+    # The base Pinboard API URL.
     BASE_URL = 'https://api.pinboard.in/v1'.freeze
 
-    # Public: Returns the String username being used by the client.
+    # Username used by the client to make authenticated requests
+    #
+    # @return [String]
+    #
+    # @api public
     attr_reader :username
 
-    # Public: Returns the String API token being used by the client.
+    # Token used by the client to make authenticated requests
+    #
+    # @return [String]
+    #
+    # @api public
     attr_reader :token
 
-    # Public: Creates a new client.
+    # Initialize a Client
+    #
+    # @example
+    #   client = Client.new(username, token)
+    #
+    # @param [String] username
+    #   the user to authenticate with
+    # @param [String] token
+    #   the API token for the user account, found on the Pinboard settings page
     #
-    # username - A String naming the user account to authenticate with.
-    # token - A String of the API token for the user account. Can be found on
-    #         the user's settings page.
+    # @api public
     def initialize(username, token)
       @username, @token = username, token
     end
 
-    # Internal: Request JSON from the Pinboard API.
+    # Retrieve JSON from the Pinboard API
     #
-    # path - A String of the path to fetch from. The is relative from the root
-    #        Pinboard API URL.
-    # params - A Hash of query parameters to append to the URL for the fetch
-    #          (default: {}).
+    # @param [String] path
+    #   the path to fetch from, relative to from the base Pinboard API URL
     #
-    # Examples
+    # @param [Hash] params
+    #   query parameters to append to the URL
     #
-    #   get('/posts/update')
-    #   # => {'update_time' => '2014-06-24T15:39:46Z'}
+    # @return [Hash] the response parsed from the JSON
     #
-    #   get('/posts/suggest', url: 'http://theinternate.com/')
-    #   # => [{'popular' => []}, {'recommended' => []}]
+    # @raise [RateLimitError] if the response is rate-limited
     #
-    # Returns a parsed JSON response from Pinboard's API.
-    def get(path, params = {})
+    # @api private
+    def get(path, params = EMPTY_HASH)
       uri = URI("#{BASE_URL}#{path}")
 
       base_params = { auth_token: "#{@username}:#{@token}", format: 'json' }
       uri.query = URI.encode_www_form(params.merge(base_params))
 
       response = Net::HTTP.get_response(uri)
+      fail Client::RateLimitError if response.code == TOO_MANY_REQUESTS_CODE
       JSON.parse(response.body)
     end
 
-    # Public: Access posts-related API calls.
+    # Access posts-related API calls
+    #
+    # @example
+    #   posts = client.posts
+    #
+    # @return [Posts]
+    #
+    # @api public
     def posts
       Posts.new(self)
     end
 
-    # Public: Access tags-related API calls.
+    # Access tags-related API calls
+    #
+    # @example
+    #   tags = client.tags
+    #
+    # @return [Tags]
+    #
+    # @api public
     def tags
       Tags.new(self)
     end
 
-    # Public: Access user-related API calls.
+    # Access user-related API calls
+    #
+    # @example
+    #   user = client.user
+    #
+    # @return [User]
+    #
+    # @api public
     def user
       User.new(self)
     end
 
-    # Public: Access notes-related API calls.
+    # Access notes-related API calls
+    #
+    # @example
+    #   notes = client.notes
+    #
+    # @return [Notes]
+    #
+    # @api public
     def notes
       Notes.new(self)
     end

data/lib/thumbtack/note.rb

@@ -1,9 +1,13 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Public: Represents a note.
+  # Represents a note
+  #
+  # @api public
   class Note
-    # Private: The attributes for a Note.
+    # The attributes for a Note
+    #
+    # @api private
     ATTRIBUTES = [
       :id,
       :title,
@@ -14,21 +18,77 @@ module Thumbtack
       :length
     ].freeze
 
-    attr_reader(*ATTRIBUTES)
+    # The identifier for the note
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :id
+
+    # The title of the note
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :title
+
+    # The time at which the note was created
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :created_at
+
+    # The time at which the note was last updated
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :updated_at
+
+    # 20 character hexadecimal SHA1 hash of the note text
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :digest
+
+    # The text of the note
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :text
+
+    # The length of the note text
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :length
 
-    # Internal: Creates a new Note from a Hash, usually a Client#get response.
+    # Creates a new Note from a Hash
     #
-    # hash - A Hash of attributes of the note.
+    # @param [Hash{#to_sym => Object}] hash
+    #   Note attributes
+    #
+    # @return [Note]
+    #
+    # @api private
+    # @see Client#get
     def self.from_hash(hash)
       attrs = hash.dup
       digest = attrs.delete('hash')
       new(Hash[attrs.map { |k, v| [k.to_sym, v] }].merge(digest: digest))
     end
 
-    # Internal: Initialize a Note.
+    # Initialize a Note
+    #
+    # @param [Hash] attrs
+    #   Note attributes
     #
-    # attrs - A Hash of attributes of the Note.
-    def initialize(attrs = {})
+    # @api private
+    def initialize(attrs = EMPTY_HASH)
       ATTRIBUTES.each do |attribute|
         instance_variable_set "@#{attribute}", attrs.fetch(attribute)
       end

data/lib/thumbtack/note_summary.rb

@@ -1,32 +1,87 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Public: Represents a note summary as returned from Notes#list.
+  # Represents a note summary as returned from Notes#list.
+  #
+  # @api public
+  # @see Notes#list
   class NoteSummary
-    # Private: The attributes for a NoteSummary.
+    # The attributes for a NoteSummary
+    #
+    # @api private
     ATTRIBUTES = [
       :id,
       :title,
-      :hash,
+      :digest,
       :created_at,
       :updated_at,
       :length
     ].freeze
 
-    attr_reader(*ATTRIBUTES)
+    # The identifier for the note
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :id
+
+    # The title of the note
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :title
 
-    # Internal: Creates a new NoteSummary from a Hash, usually a Client#get
-    # response.
+    # The time at which the note was created
     #
-    # hash - A Hash of attributes of the note.
+    # @return [String]
+    #
+    # @api public
+    attr_reader :created_at
+
+    # The time at which the note was last updated
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :updated_at
+
+    # 20 character hexadecimal SHA1 hash of the note text
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :digest
+
+    # The length of the note text
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :length
+
+    # Creates a new NoteSummary from a Hash
+    #
+    # @param [Hash{#to_sym => Object}] hash
+    #   NoteSummary attributes
+    #
+    # @return [NoteSummary]
+    #
+    # @api private
+    # @see Client#get
     def self.from_hash(hash)
-      new(Hash[hash.map { |key, value| [key.to_sym, value] }])
+      attrs = hash.dup
+      digest = attrs.delete('hash')
+      new(Hash[attrs.map { |k, v| [k.to_sym, v] }].merge(digest: digest))
     end
 
-    # Internal: Initialize a NoteSummary.
+    # Initialize a NoteSummary
+    #
+    # @param [Hash] attrs
+    #   NoteSummary attributes
     #
-    # attrs - A Hash of attributes of the NoteSummary.
-    def initialize(attrs = {})
+    # @api private
+    def initialize(attrs = EMPTY_HASH)
       ATTRIBUTES.each do |attribute|
         instance_variable_set "@#{attribute}", attrs.fetch(attribute)
       end

data/lib/thumbtack/notes.rb

@@ -1,24 +1,48 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Internal: Wraps API calls related to notes.
+  # Wraps API calls related to notes
   class Notes
-    # Internal: Creates a new Notes.
+    # Initialize a Notes
     #
-    # client - a Thumbtack::Client to communicate with the Pinboard API.
+    # @param [Client] client
+    #   client to communicate with the Pinboard API
+    #
+    # @api private
     def initialize(client)
       @client = client
     end
 
-    # Public: Returns a list of summaries of the user's notes.
+    # List of summaries of the user's notes
+    #
+    # @example
+    #   summaries = notes.list
+    #
+    # @return [Array<NoteSummary>]
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#notes_list
     def list
       response = @client.get('/notes/list')
-      response.fetch('notes', []).map do |note_hash|
+      response.fetch('notes', EMPTY_ARRAY).map do |note_hash|
         NoteSummary.from_hash(note_hash)
       end
     end
 
-    # Public: Return an individual note.
+    # Fetch a note
+    #
+    # @example
+    #   note = notes.get(id)
+    #
+    # @param [#to_s] id
+    #   the id of the note to fetch
+    #
+    # @return [Note]
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#notes_id
     def get(id)
       Note.from_hash @client.get("/notes/#{id}")
     end

data/lib/thumbtack/post.rb

@@ -1,9 +1,13 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Public: Represents a bookmark.
+  # Represents a bookmark
+  #
+  # @api public
   class Post
-    # Private: The attributes for a Post.
+    # The attributes for a Post
+    #
+    # @api private
     ATTRIBUTES = [
       :href,
       :description,
@@ -16,19 +20,89 @@ module Thumbtack
       :tags
     ].freeze
 
-    attr_reader(*ATTRIBUTES)
+    # The url of the post
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :href
+
+    # The title of the post
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :description
+
+    # The description of the post
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :extended
+
+    # 32 character hexadecimal MD5 hash tag 'version' of the post
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :meta
+
+    # 32 character hexadecimal MD5 hash of the post URL
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :hash
+
+    # The time at which the post was created
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :time
+
+    # If true, this post is public
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    attr_reader :shared
 
-    # Internal: Creates a new post from a Hash, usually a Client#get response.
+    # If true, this post is marked unread
     #
-    # hash - A Hash of attributes of the Post.
+    # @return [Boolean]
+    #
+    # @api public
+    attr_reader :toread
+
+    # The tags for this post, space-seperated
+    #
+    # @return [String]
+    #
+    # @api public
+    attr_reader :tags
+
+    # Creates a new Post from a Hash
+    #
+    # @param [Hash{#to_sym => Object}] hash
+    #   Post attributes
+    #
+    # @return [Post]
+    #
+    # @api private
+    # @see Client#get
     def self.from_hash(hash)
       new(Hash[hash.map { |key, value| [key.to_sym, value] }])
     end
 
-    # Internal: Initialize a Post.
+    # Initialize a Post
+    #
+    # @param [Hash] attrs
+    #   Post attributes
     #
-    # attrs - A Hash of attributes of the Post.
-    def initialize(attrs = {})
+    # @api private
+    def initialize(attrs = EMPTY_HASH)
       ATTRIBUTES.each do |attribute|
         instance_variable_set "@#{attribute}", attrs.fetch(attribute)
       end