thumbtack 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3d86b3db897475f83812368d11f5179d8b098af6
+  data.tar.gz: d92ba1381ba92772a4b7610b70c3d53a839f0f1d
+SHA512:
+  metadata.gz: d9ad33c40ef19811c378c9bbc6f09e54151ecb5a8c657ad05f48916f0a1b4e87ce152a1508c51a6ae290257287c5a7d0cbd463fe68dae6296a0502e5cddc2ef8
+  data.tar.gz: 32bd3769072670a57804a306fc46f78db993dbc6e91bd395a7433491c74381a13176f900429faab5f82b45f2b5e3a862e8e286c7636894631e9c949e4c3026e1

data/lib/thumbtack/client.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Public: Wraps each interaction with the Pinboard API.
+  class Client
+    # Public: String of base Pinboard API URL.
+    BASE_URL = 'https://api.pinboard.in/v1'.freeze
+
+    # Public: Returns the String username being used by the client.
+    attr_reader :username
+
+    # Public: Returns the String API token being used by the client.
+    attr_reader :token
+
+    # Public: Creates a new client.
+    #
+    # 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.
+    def initialize(username, token)
+      @username, @token = username, token
+    end
+
+    # Internal: Request 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: {}).
+    #
+    # Examples
+    #
+    #   get('/posts/update')
+    #   # => {'update_time' => '2014-06-24T15:39:46Z'}
+    #
+    #   get('/posts/suggest', url: 'http://theinternate.com/')
+    #   # => [{'popular' => []}, {'recommended' => []}]
+    #
+    # Returns a parsed JSON response from Pinboard's API.
+    def get(path, params = {})
+      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)
+      JSON.parse(response.body)
+    end
+
+    # Public: Access posts-related API calls.
+    def posts
+      Posts.new(self)
+    end
+
+    # Public: Access tags-related API calls.
+    def tags
+      Tags.new(self)
+    end
+
+    # Public: Access user-related API calls.
+    def user
+      User.new(self)
+    end
+
+    # Public: Access notes-related API calls.
+    def notes
+      Notes.new(self)
+    end
+  end
+end

data/lib/thumbtack/note.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Public: Represents a note.
+  class Note
+    # Private: The attributes for a Note.
+    ATTRIBUTES = [
+      :id,
+      :title,
+      :hash,
+      :created_at,
+      :updated_at,
+      :text,
+      :length
+    ].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    # Internal: Creates a new Note from a Hash, usually a Client#get response.
+    #
+    # hash - A Hash of attributes of the note.
+    def self.from_hash(hash)
+      new(Hash[hash.map { |key, value| [key.to_sym, value] }])
+    end
+
+    # Internal: Initialize a Note.
+    #
+    # attrs - A Hash of attributes of the Note.
+    def initialize(attrs = {})
+      ATTRIBUTES.each do |attribute|
+        instance_variable_set "@#{attribute}", attrs.fetch(attribute)
+      end
+    end
+  end
+end

data/lib/thumbtack/note_summary.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Public: Represents a note summary as returned from Notes#list.
+  class NoteSummary
+    # Private: The attributes for a NoteSummary.
+    ATTRIBUTES = [
+      :id,
+      :title,
+      :hash,
+      :created_at,
+      :updated_at,
+      :length
+    ].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    # Internal: Creates a new NoteSummary from a Hash, usually a Client#get
+    # response.
+    #
+    # hash - A Hash of attributes of the note.
+    def self.from_hash(hash)
+      new(Hash[hash.map { |key, value| [key.to_sym, value] }])
+    end
+
+    # Internal: Initialize a NoteSummary.
+    #
+    # attrs - A Hash of attributes of the NoteSummary.
+    def initialize(attrs = {})
+      ATTRIBUTES.each do |attribute|
+        instance_variable_set "@#{attribute}", attrs.fetch(attribute)
+      end
+    end
+  end
+end

data/lib/thumbtack/notes.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Internal: Wraps API calls related to notes.
+  class Notes
+    # Internal: Creates a new Notes.
+    #
+    # client - a Thumbtack::Client to communicate with the Pinboard API.
+    def initialize(client)
+      @client = client
+    end
+
+    # Public: Returns a list of summaries of the user's notes.
+    def list
+      response = @client.get('/notes/list')
+      response.fetch('notes', []).map do |note_hash|
+        NoteSummary.from_hash(note_hash)
+      end
+    end
+
+    # Public: Return an individual note.
+    def get(id)
+      Note.from_hash @client.get("/notes/#{id}")
+    end
+  end
+end

data/lib/thumbtack/post.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Public: Represents a bookmark.
+  class Post
+    # Private: The attributes for a Post.
+    ATTRIBUTES = [
+      :href,
+      :description,
+      :extended,
+      :meta,
+      :hash,
+      :time,
+      :shared,
+      :toread,
+      :tags
+    ].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    # Internal: Creates a new post from a Hash, usually a Client#get response.
+    #
+    # hash - A Hash of attributes of the Post.
+    def self.from_hash(hash)
+      new(Hash[hash.map { |key, value| [key.to_sym, value] }])
+    end
+
+    # Internal: Initialize a Post.
+    #
+    # attrs - A Hash of attributes of the Post.
+    def initialize(attrs = {})
+      ATTRIBUTES.each do |attribute|
+        instance_variable_set "@#{attribute}", attrs.fetch(attribute)
+      end
+    end
+  end
+end

data/lib/thumbtack/posts.rb

@@ -0,0 +1,186 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Internal: Wraps API calls related to posts.
+  class Posts
+    # Internal: Initialize a Posts.
+    #
+    # client - A Thumbtack::Client to communicate with the Pinboard API.
+    def initialize(client)
+      @client = client
+    end
+
+    # Public: The most recent time a bookmark was added, updated, or deleted.
+    #
+    # Examples
+    #
+    #   update
+    #   # => '2014-06-26T19:01:33Z'
+    #
+    # Returns a DateTime in UTC.
+    def update
+      response = @client.get('/posts/update')
+      Types::DateTime.from_parameter response.fetch('update_time')
+    end
+
+    # Public: Add a bookmark.
+    #
+    # url - A String containing the URL to be bookmarked.
+    # description - A String containing the title of the bookmark.
+    # options - The Hash options to be passed as arguments.
+    #           :extended - A String containing a description of the item.
+    #           :tags     - An Array containing up to 100 tags.
+    #           :dt       - A DateTime containing the creation time for this
+    #                       bookmark.
+    #           :replace  - A Boolean containing whether or not to replace any
+    #                       existing bookmark with this URL.
+    #           :shared   - A Boolean containing whether or not to make the
+    #                       bookmark public.
+    #           :toread   - A Boolean containing whether or not to mark the
+    #                       bookmark as unread.
+    #
+    # Examples
+    #
+    #   add('http://theinternate.com', 'The Internate')
+    #   add('http://theinternate.com', 'The Internate', tags: ['best', 'ruby'])
+    #
+    # Returns the Posts instance.
+    def add(url, description, options = {})
+      parameters = Specification.new(
+        url: Types::URL,
+        description: Types::Text,
+        extended: Types::Text,
+        tags: Types::Tags,
+        dt: Types::DateTime,
+        replace: Types::Boolean,
+        shared: Types::Boolean,
+        toread: Types::Boolean
+      ).parameters({ url: url, description: description }.merge(options))
+      @client.get('/posts/add', parameters)
+      self
+    end
+
+    # Public: Delete a bookmark.
+    #
+    # url - A String containing the URL of the bookmark to delete.
+    #
+    # Examples
+    #
+    #   delete('http://delicio.us')
+    #
+    # Returns the Posts instance
+    def delete(url)
+      parameters = Specification.new(url: Types::URL).parameters(url: url)
+      @client.get('/posts/delete', parameters)
+      self
+    end
+
+    # Public: Return one or more posts matching the arguments.
+    #
+    # options - The Hash options to be passed as arguments.
+    #          :tag  - An Array containing a up to three tags to filter by.
+    #          :dt   - A DateTime containing the date when the results were
+    #                  bookmarked.
+    #          :url  - A String containing the URL for the the bookmark.
+    #          :meta - A Boolean indicating whether or not to include a change
+    #                  detection signature.
+    #
+    # Examples
+    #
+    #   get(tag: 'webdev', meta: 'yes')
+    #   get(url: 'http://www.pinboard.in')
+    #
+    # Returns a list of Post instances.
+    def get(options = {})
+      parameters = Specification.new(
+        tag: Types::Tags,
+        dt: Types::DateTime,
+        url: Types::URL,
+        meta: Types::Boolean
+      ).parameters(options)
+      posts_from @client.get('/posts/get', parameters)
+    end
+
+    # Public: Return a list of the most recent posts.
+    #
+    # options - The Hash options to be passed as arguments.
+    #          :tag   - An Array containing a up to three tags to filter by.
+    #          :count - An Integer of the number of results to return. Default
+    #                   is 15, maximum is 100.
+    #
+    # Examples
+    #
+    #   recent(tag: 'webdev', count: 25)
+    #
+    # Returns a list of Post instances.
+    def recent(options = {})
+      parameters = Specification.new(
+        tag: Types::Tags,
+        count: Types::Integer
+      ).parameters(options)
+      posts_from @client.get('/posts/recent', parameters)
+    end
+
+    # Public: Return all posts in the account.
+    #
+    # options - The Hash options to be passed as arguments.
+    #          :tag     - A String containing a list of up to three tags to
+    #                     filter by.
+    #          :start   - An Integer offset value. Default is 0.
+    #          :results - An Integer of the number of results to return.
+    #          :fromdt  - Filter results to posts created after this DateTime.
+    #          :todt    - Filter results to posts created before this DateTime.
+    #          :meta    - A Boolean containing whether or not to include a
+    #                     change detection signature.
+    #
+    # Returns a list of Posts instances
+    def all(options = {})
+      parameters = Specification.new(
+        tag: Types::Tags,
+        start: Types::Integer,
+        results: Types::Integer,
+        fromdt: Types::DateTime,
+        todt: Types::DateTime,
+        meta: Types::Boolean
+      ).parameters(options)
+      results = @client.get('/posts/all', parameters)
+      results.map { |post_hash| Post.from_hash(post_hash) }
+    end
+
+    # Public: Return a list of popular and recommended tags for a URL.
+    #
+    # url - A String containing a URL to fetch suggested tags for.
+    #
+    # Returns a Hash with two entries, :popular is a list of popular tags,
+    # :recommended is a list of recommended tags.
+    def suggest(url)
+      parameters = Specification.new(url: Types::URL).parameters(url: url)
+      result = @client.get('/posts/suggest', parameters)
+      { popular: result.fetch('popular'),
+        recommended: result.fetch('recommended') }
+    end
+
+    # Public: Return a list dates with the count of posts made at each date.
+    #
+    # options - The Hash options to be passed as arguments
+    #          :tag - An Array containing a up to three tags to filter by.
+    #
+    # Returns a Hash of Strings => Integer entries. The Strings contain a date
+    # and the Integer is the count of posts made on that date.
+    def dates(options = {})
+      parameters = Specification.new(tag: Types::Tags).parameters(options)
+      response = @client.get('/posts/dates', parameters)
+      Hash[
+        response.fetch('dates', {}).map do |date, count|
+          [Types::Date.from_parameter(date), count.to_i]
+        end
+      ]
+    end
+
+    private
+
+    def posts_from(response)
+      response.fetch('posts', []).map { |post_hash| Post.from_hash(post_hash) }
+    end
+  end
+end

data/lib/thumbtack/specification.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Internal: Validates and translates user-provided parameters to their
+  # Pinboard-supported equivalents
+  class Specification
+
+    # Create a new Specification.
+    #
+    # type_handlers - A Hash mapping parameter names to their type handlers.
+    def initialize(type_handlers)
+      @type_handlers = type_handlers
+    end
+
+    # Validate and translate user-provided parameters to their
+    # Pinboard-supported equivalents.
+    #
+    # arguments - A Hash mapping parameter names to their user-provided values.
+    #
+    # Returns the parameters translated to their Pinboard equivalents.
+    def parameters(arguments)
+      Hash[
+        arguments.map do |name, value|
+          type_handler = @type_handlers.fetch(name)
+          type_handler.validate(value)
+          [name, type_handler.to_parameter(value)]
+        end
+      ]
+    end
+  end
+end

data/lib/thumbtack/tags.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Internal: Wraps API calls related to tags.
+  class Tags
+    # Internal: Creates a new Tags.
+    #
+    # client - a Thumbtack::Client to communicate with the Pinboard API.
+    def initialize(client)
+      @client = client
+    end
+
+    # Public: Returns a list of the user's tags with their counts.
+    def get
+      response = @client.get('/tags/get')
+      Hash[response.map { |tag, count| [tag, count.to_i] }]
+    end
+
+    # Public: Delete a tag.
+    #
+    # tag - A String containing the tag to delete.
+    #
+    # Returns the Tags instance.
+    def delete(tag)
+      parameters = Specification.new(tag: Types::Tags).parameters(tag: tag)
+      @client.get('/tags/delete', parameters)
+      self
+    end
+
+    # Public: Rename a tag.
+    #
+    # old - A String containing the tag to be renamed.
+    # new - A String containing the new name for the tag.
+    #
+    # Returns the Tags instance.
+    def rename(old, new)
+      parameters = Specification.new(
+        old: Types::Tags,
+        new: Types::Tags
+      ).parameters(old: old, new: new)
+      @client.get('/tags/rename', parameters)
+      self
+    end
+  end
+end

data/lib/thumbtack/types/boolean.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+module Thumbtack
+  module Types
+    # Internal: Handles conversion and validation of Boolean types to the 'yes'
+    # and 'no' parameters supported by the Pinboard API.
+    class Boolean
+      # Validate something is a Boolean parameter.
+      #
+      # value - A Boolean to validate.
+      #
+      # Returns nothing.
+      # Raises Types::ValidationError if the value is not true or false
+      def self.validate(value)
+        case value
+        when TrueClass, FalseClass
+          self
+        else
+          fail ValidationError, "#{value} must be true or false"
+        end
+      end
+
+      # Convert a Boolean value to a parameter acceptable to the Pinboard API.
+      #
+      # value - A Boolean to convert.
+      #
+      # Returns 'yes' or 'no'
+      def self.to_parameter(value)
+        case value
+        when TrueClass
+          'yes'
+        when FalseClass
+          'no'
+        end
+      end
+
+      # Convert a parameter from the Pinboard API to a Ruby Boolean.
+      #
+      # parameter - A String containing 'yes' or 'no'.
+      #
+      # Returns true or false.
+      def self.from_parameter(parameter)
+        case parameter
+        when 'yes'
+          true
+        when 'no'
+          false
+        end
+      end
+    end
+  end
+end

data/lib/thumbtack/types/date.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+module Thumbtack
+  module Types
+    # Internal: Handles conversion and validation of Date types to the String
+    # parameters supported by the Pinboard API.
+    class Date
+      # The earliest allowable date
+      EARLIEST = ::Date.new(1, 1, 1)
+      # The latest allowable date
+      LATEST = ::Date.new(2100, 1, 1)
+
+      # Validate a Date.
+      #
+      # value - The Date to validate.
+      #
+      # Returns nothing.
+      # Raises Types::ValidationError if the date is not between 0001-01-01 and
+      # 2100-01-01.
+      def self.validate(value)
+        unless value > EARLIEST && value < LATEST
+          fail ValidationError,
+               "#{value} must be between 0001-01-01 and 2100-01-01"
+        end
+        self
+      end
+
+      # Convert a Date value to a parameter acceptable to the Pinboard API.
+      #
+      # value - The Date to convert.
+      #
+      # Returns a String containing the date with format yyyy-mm-dd.
+      def self.to_parameter(value)
+        value.xmlschema
+      end
+
+      # Convert a parameter from the Pinboard API to a Ruby Date.
+      #
+      # parameter - A String of the date formatted yyyy-mm-dd.
+      #
+      # Returns a Date.
+      def self.from_parameter(parameter)
+        ::Date.xmlschema(parameter)
+      end
+    end
+  end
+end

data/lib/thumbtack/types/date_time.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+module Thumbtack
+  module Types
+    # Handles conversion and validation of DateTime types to the String
+    # parameters supported by the Pinboard API.
+    class DateTime
+      # The earliest allowable time
+      EARLIEST = ::DateTime.new(1, 1, 1)
+      # The latest allowable time
+      LATEST = ::DateTime.new(2100, 1, 1)
+      # The date format of the Pinboard API
+      FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
+
+      # Validate something is a valid DateTime parameter.
+      #
+      # value - The DateTime to validate.
+      #
+      # Returns nothing.
+      # Raises Types::ValidationError if the time is not between
+      # 0001-01-01 00:00:00 and 2100-01-01 00:00:00.
+      def self.validate(value)
+        unless value > EARLIEST && value < LATEST
+          fail ValidationError,
+               "#{value} must be between 0001-01-01 and 2100-01-01"
+        end
+        self
+      end
+
+      # Convert a DateTime value to a parameter acceptable to the Pinboard API.
+      #
+      # value - The DateTime to convert.
+      #
+      # Returns a String containing the date with format yyyy-mm-ddTHH:MM:SSZ.
+      def self.to_parameter(value)
+        value.strftime(FORMAT)
+      end
+
+      # Convert a parameter from the Pinboard API to a Ruby DateTime.
+      #
+      # parameter - A String of the date formatted yyyy-mm-ddTHH:MM:SSZ.
+      #
+      # Returns a DateTime.
+      def self.from_parameter(parameter)
+        ::DateTime.strptime(parameter)
+      end
+    end
+  end
+end

data/lib/thumbtack/types/identity.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Thumbtack
+  module Types
+    # Internal: An abstract type handler
+    class Identity
+
+      # Any value passed is valid.
+      #
+      # Returns nothing.
+      def self.validate(*)
+        self
+      end
+
+      # Return any value passed to this without conversion.
+      def self.to_parameter(value)
+        value
+      end
+
+      # Return any value passed to this without conversion.
+      def self.from_parameter(parameter)
+        parameter
+      end
+    end
+  end
+end

data/lib/thumbtack/types/integer.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+module Thumbtack
+  module Types
+    # Internal: Handles validation of Integer types as the values supported by
+    # the Pinboard API.
+    class Integer < Identity
+      # The minimum allowable integer.
+      MIN = 0
+      # The maximum allowable integer.
+      MAX = 2**32
+
+      # Validate something is a valid integer parameter.
+      #
+      # value - An integer to validate.
+      #
+      # Returns nothing.
+      # Raises Types::ValidationError if the value is not between 0 and 2^32.
+      def self.validate(value)
+        unless value >= MIN && value <= MAX
+          fail ValidationError, "#{value} must be in range 0..2^32"
+        end
+        self
+      end
+    end
+  end
+end