thumbtack 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 223435e3e89fab503c5c9e5e42cb6debb6f29a5d
-  data.tar.gz: 769a2c552c39a0e87d35ef21c12afb475ab5029b
+  metadata.gz: dfceebca8bd2653fbb6a32085aa3449e3a872c1d
+  data.tar.gz: f3be0d3c15e9f9ca487bba144f9192fe300941b2
 SHA512:
-  metadata.gz: 86c48c48a0008be9f3cea5d1143c42a7ea87915fd7a92459affc82823d26e355828942974ac9c7af81819998f6d6695c2dd26bb31eb225ef133f34802704c98e
-  data.tar.gz: 1a5f9d3a0d61918bcd5d4e546deb18dfe2808a281f96eec5e4ee6bfd41f15d3a739b925c55e609f3a338eea2ee7e94aed53fabfb55c34b77cd8a61c26787fb3b
+  metadata.gz: 57742f4274a670de859c45b9e4373176205d01ba219a1d8b0eccc3443ef61a8f171881c37917a8bb7a174fc531171c89163df9e7b65172f52c5bc2eef703c6e8
+  data.tar.gz: 392b5f79e1ecd490bf8fa7c336f48c150ba47b19c7f8c010c6be8eea4c8327d3239c3279fd5d4b95ce1fec6b1f3552a56e80581992740895c35e7a1e7d7dba8f

data/lib/thumbtack.rb

@@ -25,7 +25,6 @@ require 'json'
 require 'net/http'
 require 'uri'
 
-require 'thumbtack/types'
 require 'thumbtack/types/range_validation'
 require 'thumbtack/types/length_validation'
 require 'thumbtack/types/boolean'
@@ -45,8 +44,10 @@ require 'thumbtack/posts'
 require 'thumbtack/tags'
 require 'thumbtack/user'
 require 'thumbtack/hash_to_digest'
+require 'thumbtack/symbolize_keys'
 require 'thumbtack/note'
 require 'thumbtack/note_summary'
 require 'thumbtack/notes'
+require 'thumbtack/adapters/basic_adapter'
 require 'thumbtack/client'
 require 'thumbtack/version'

data/lib/thumbtack/adapters/basic_adapter.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+
+module Thumbtack
+  module Adapters
+    # A basic adapter using Ruby's builtin HTTP and JSON parsing libraries
+    class BasicAdapter
+      # The status code for rate limited responses from the Pinboard API
+      TOO_MANY_REQUESTS_CODE = '429'.freeze
+
+      # The response format requested from the Pinboard API
+      RESPONSE_FORMAT = 'json'.freeze
+
+      # The base Pinboard API URL.
+      BASE_URL = 'https://api.pinboard.in/v1'.freeze
+
+      # Initialize a BasicAdapter
+      #
+      # @example
+      #   adapter = BasicAdapter.new(username, token)
+      #
+      # @param [String] username
+      #   the user to authenticate with
+      # @param [String] token
+      #   the API token for the user, found on the Pinboard settings page
+      #
+      # @api public
+      def initialize(username, token)
+        @username = username
+        @token = token
+      end
+
+      # Retrieve JSON from the Pinboard API
+      #
+      # @param [String] path
+      #   the path to fetch from, relative to the base Pinboard API URL
+      #
+      # @param [Hash] params
+      #   query parameters to append to the URL
+      #
+      # @return [Hash] the response parsed from the JSON
+      #
+      # @raise [RateLimitError] if the response is rate-limited
+      #
+      # @api private
+      def get(path, params = EMPTY_HASH)
+        uri = URI("#{BASE_URL}#{path}")
+        uri.query = extend_parameters(params)
+        JSON.parse(http_response(uri).body)
+      end
+
+      private
+
+      # Retrieve HTTP response from a URI
+      #
+      # @param [URI] uri
+      #   the uri to fetch from
+      # @return [Net::HTTPResponse]
+      #   the response
+      #
+      # @api private
+      # @raise [RateLimitError] if the response is rate-limited
+      def http_response(uri)
+        Net::HTTP.get_response(uri).tap do |response|
+          fail RateLimitError if response.code == TOO_MANY_REQUESTS_CODE
+        end
+      end
+
+      # Extend parameters with authentication and format parameters
+      #
+      # @param [Hash{#to_s => #to_s}] parameters
+      #   the parameters to extend
+      # @return [Hash{#to_s => #to_s}]
+      #   the extended parameters
+      #
+      # @api private
+      def extend_parameters(parameters)
+        base_params = { auth_token: "#{@username}:#{@token}",
+                        format: RESPONSE_FORMAT }
+        URI.encode_www_form(parameters.merge(base_params))
+      end
+    end
+  end
+end

data/lib/thumbtack/client.rb

@@ -3,12 +3,6 @@
 module Thumbtack
   # Wraps each interaction with the Pinboard API
   class Client
-    # 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
-
     # Username used by the client to make authenticated requests
     #
     # @example
@@ -29,6 +23,16 @@ module Thumbtack
     # @api public
     attr_reader :token
 
+    # Token used by the client to make authenticated requests
+    #
+    # @example
+    #   client.adapter  # => #<Thumbtack::Adapters::BasicAdapter...
+    #
+    # @return [Adapter]
+    #
+    # @api public
+    attr_reader :adapter
+
     # Initialize a Client
     #
     # @example
@@ -38,10 +42,18 @@ module Thumbtack
     #   the user to authenticate with
     # @param [String] token
     #   the API token for the user account, found on the Pinboard settings page
+    # @param [Hash] options
+    #   options for the construction of the client
+    # @option options [BasicAdapter] :adapter
+    #   an adapter to use for communicating with the Pinboard API
     #
     # @api public
-    def initialize(username, token)
-      @username, @token = username, token
+    def initialize(username, token, options = EMPTY_HASH)
+      @username = username
+      @token = token
+      @adapter = options.fetch(:adapter) do
+        Adapters::BasicAdapter.new(@username, @token)
+      end
     end
 
     # Retrieve JSON from the Pinboard API
@@ -58,14 +70,7 @@ module Thumbtack
     #
     # @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 RateLimitError if response.code == TOO_MANY_REQUESTS_CODE
-      JSON.parse(response.body)
+      @adapter.get(path, params)
     end
 
     # Perform an action request against the Pinboard API
@@ -83,9 +88,11 @@ module Thumbtack
     #
     # @api private
     # @see https://pinboard.in/api/#errors
-    def action(path, params = EMPTY_HASH)
-      response = get(path, params)
-      fail ResultError, response['result'] unless response['result'] == 'done'
+    def action(path, params)
+      response = @adapter.get(path, params)
+      unless response['result_code'] == 'done'
+        fail ResultError, response['result_code']
+      end
       self
     end
 

data/lib/thumbtack/hash_to_digest.rb

@@ -1,22 +1,27 @@
+# encoding: utf-8
+
 module Thumbtack
   # Handles renaming the hash attribute to digest from response hashes.
   #
   # @api private
   class HashToDigest
+    HASH = 'hash'.freeze
+    DIGEST = 'digest'.freeze
+
     # Rename any attribute called hash to digest
     #
     # @example
-    #   HashToDigest.rename('hash' => '1234')  # => { :digest => '1234' }
+    #   HashToDigest.rename('hash' => '1234')  # => { 'digest' => '1234' }
     #
-    # @param [Hash{String => Object}]
-    #   reponse hash
+    # @param [Hash{String => Object}] hash
+    #   the response hash
     #
-    # @return [Hash{Symbol => Object}]
-    #   a hash with any key named hash renamed to digest
+    # @return [Hash{String => Object}]
+    #   a hash with any key 'hash' renamed to 'digest'
     def self.rename(hash)
       attrs = hash.dup
-      digest = attrs.delete('hash')
-      Hash[attrs.map { |k, v| [k.to_sym, v] }].merge(digest: digest)
+      digest = attrs.delete(HASH)
+      attrs.merge(DIGEST => digest)
     end
   end
 end

data/lib/thumbtack/note.rb

@@ -102,7 +102,7 @@ module Thumbtack
     # @api private
     # @see Client#get
     def self.from_hash(hash)
-      new(HashToDigest.rename(hash))
+      new(SymbolizeKeys.symbolize(HashToDigest.rename(hash)))
     end
 
     # Initialize a Note

data/lib/thumbtack/note_summary.rb

@@ -92,7 +92,7 @@ module Thumbtack
     # @api private
     # @see Client#get
     def self.from_hash(hash)
-      new(HashToDigest.rename(hash))
+      new(SymbolizeKeys.symbolize(HashToDigest.rename(hash)))
     end
 
     # Initialize a NoteSummary

data/lib/thumbtack/post.rb

@@ -128,7 +128,7 @@ module Thumbtack
     # @api private
     # @see Client#get
     def self.from_hash(hash)
-      new(HashToDigest.rename(hash))
+      new(SymbolizeKeys.symbolize(HashToDigest.rename(hash)))
     end
 
     # Initialize a Post

data/lib/thumbtack/posts.rb

@@ -226,11 +226,7 @@ module Thumbtack
     def dates(options = EMPTY_HASH)
       parameters = Specification.new(tag: Types::Tags).parameters(options)
       response = @client.get('/posts/dates', parameters)
-      Hash[
-        response.fetch('dates', EMPTY_HASH).map do |date, count|
-          [Types::Date.from_parameter(date), count.to_i]
-        end
-      ]
+      dates_with_counts_from(response)
     end
 
     private
@@ -245,5 +241,17 @@ module Thumbtack
         Post.from_hash(post_hash)
       end
     end
+
+    # Create Hash of dates to counts from dates response
+    #
+    # @return [Hash{Date => Integer}]
+    #
+    # @api private
+    def dates_with_counts_from(response)
+      entries = response.fetch('dates', EMPTY_HASH).map do |date, count|
+        [Types::Date.from_parameter(date), count.to_i]
+      end
+      Hash[entries]
+    end
   end
 end

data/lib/thumbtack/suggestion.rb

@@ -56,10 +56,24 @@ module Thumbtack
     # @api private
     # @see Client#get
     def self.from_array(array)
-      popular = array.find { |hash| hash.key?(POPULAR_KEY) }
-      recommended = array.find { |hash| hash.key?(RECOMMENDED_KEY) }
-      new(popular: popular.fetch(POPULAR_KEY, EMPTY_ARRAY),
-          recommended: recommended.fetch(RECOMMENDED_KEY, EMPTY_ARRAY))
+      new(popular: entries_for(POPULAR_KEY, array),
+          recommended: entries_for(RECOMMENDED_KEY, array))
     end
+
+    # Extracts the entries for a given key in an array of hashes
+    #
+    # @param [String] key
+    #   A key from which to extract the entries
+    #
+    # @param [Array<Hash{String => Array<String>}>] array
+    #   An array of strings associated with the key
+    #
+    # @return [Array[String]]
+    #
+    # @api private
+    def self.entries_for(key, array)
+      array.find { |hash| hash.key?(key) }.fetch(key, EMPTY_ARRAY)
+    end
+    private_class_method :entries_for
   end
 end

data/lib/thumbtack/symbolize_keys.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Handles converting string keys to symbols in a response hash
+  #
+  # @api private
+  class SymbolizeKeys
+    # Convert any keys to symbols
+    #
+    # @example
+    #   SymbolizeKeys.symbolize('digest' => '1234')  # => { :digest => '1234' }
+    #
+    # @param [Hash{#to_sym => Object}] hash
+    #   the response hash
+    #
+    # @return [Hash{Symbol => Object}]
+    #   a hash with symbol keys
+    def self.symbolize(hash)
+      Hash[hash.map { |key, value| [key.to_sym, value] }]
+    end
+  end
+end

data/lib/thumbtack/types/boolean.rb

@@ -12,7 +12,7 @@ module Thumbtack
       # @param [Boolean] value
       #   the value to validate
       #
-      # @return [undefined]
+      # @return [self]
       #
       # @raise [Types::ValidationError]
       #   if the value is not true or false

data/lib/thumbtack/types/date.rb

@@ -17,7 +17,7 @@ module Thumbtack
       # @param [Date] value
       #   the date to validate
       #
-      # @return [undefined]
+      # @return [self]
       #
       # @raise [Types::ValidationError]
       #   if the date is not between 0001-01-01 and 2100-01-01

data/lib/thumbtack/types/date_time.rb

@@ -19,7 +19,7 @@ module Thumbtack
       # @param [DateTime] value
       #   The time to validate
       #
-      # @return [undefined]
+      # @return [self]
       #
       # @raise [Types::ValidationError]
       #   if the time is not between 0001-01-01 00:00:00 and 2100-01-01 00:00:00

data/lib/thumbtack/types/identity.rb

@@ -8,7 +8,7 @@ module Thumbtack
     class Identity
       # Any value passed is valid
       #
-      # @return [undefined]
+      # @return [self]
       def self.validate(*)
         self
       end

data/lib/thumbtack/types/integer.rb

@@ -16,7 +16,7 @@ module Thumbtack
       # @param [Integer] value
       #   the integer to validate
       #
-      # @return [undefined]
+      # @return [self]
       #
       # @raise [Types::ValidationError]
       #   if the value is not between 0 and 2^32

data/lib/thumbtack/types/length_validation.rb

@@ -1,26 +1,28 @@
+# encoding: utf-8
+
 module Thumbtack
   module Types
-    # Handles validation of values within a certain range
-    # Pinboard
+    # Handles validation of the length of values
     #
     # @api private
     class LengthValidation
       # Validate a value
       #
-      # @param [Object] length
+      # @param [Object] maximum_length
       #   the maximum length
       # @param [Object] value
       #   the value to validate
       #
-      # @return [undefined]
+      # @return [self]
       #
       # @raise [Types::ValidationError]
-      #   if the value is not between 0001-01-01 and 2100-01-01
-      def self.validate(value, length)
-        unless value.length <= length
+      #   if the value is not less or equal to the maximum length
+      def self.validate(value, maximum_length)
+        unless value.length <= maximum_length
           fail ValidationError,
-               "#{value} cannot be greater than #{length} characters"
+               "#{value} cannot be greater than #{maximum_length} characters"
         end
+        self
       end
     end
   end

data/lib/thumbtack/types/md5.rb

@@ -16,18 +16,31 @@ module Thumbtack
       # @param [String] value
       #   the MD5 to validate
       #
-      # @return [undefined]
+      # @return [self]
       #
       # @raise [Types::ValidationError]
       #   if the value is not a 32 character hexadecimal MD5 hash
       def self.validate(value)
-        unless value.length == 32 &&
-            value.each_char.all? { |char| CHARACTERS.include?(char) }
+        unless valid_md5?(value)
           fail ValidationError,
                "#{value} must be a 32 character hexadecimal MD5 hash"
         end
         self
       end
+
+      # If true, the value is a valid MD5 string
+      #
+      # @param [String] value
+      #   the MD5 to validate
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def self.valid_md5?(value)
+        value.length == LENGTH &&
+          value.each_char.all? { |char| CHARACTERS.include?(char) }
+      end
+      private_class_method :valid_md5?
     end
   end
 end