instapaper 0.3.0 → 1.0.0.pre2

data/lib/instapaper/api/highlights.rb

@@ -0,0 +1,33 @@
+require 'instapaper/highlight'
+
+module Instapaper
+  module API
+    # Defines methods related to highlights
+    module Highlights
+      # List highlights for a bookmark
+      # @param bookmark_id [String, Integer]
+      def highlights(bookmark_id)
+        perform_get_with_objects("/api/1.1/bookmarks/#{bookmark_id}/highlights", {}, Instapaper::Highlight)
+      end
+
+      # Create a new highlight
+      # @note Non-subscribers are limited to 5 highlights per month.
+      # @param bookmark_id [String, Integer]
+      # @param options [Hash]
+      # @option options [String] :text The text for the highlight (HTML tags in text parameter should be unescaped.)
+      # @option options [String, Integer] :posiiton The 0-indexed position of text in the content. Defaults to 0.
+      # @return [Instapaper::Highlight]
+      def add_highlight(bookmark_id, options = {})
+        perform_post_with_object("/api/1.1/bookmarks/#{bookmark_id}/highlight", options, Instapaper::Highlight)
+      end
+
+      # Delete a highlight
+      # @param highlight_id [String, Integer]
+      # @return [Boolean]
+      def delete_highlight(highlight_id, options = {})
+        perform_post_with_unparsed_response("/api/1.1/highlights/#{highlight_id}/delete", options)
+        true
+      end
+    end
+  end
+end

data/lib/instapaper/api/oauth.rb

@@ -0,0 +1,17 @@
+require 'instapaper/credentials'
+require 'instapaper/http/qline_parser'
+
+module Instapaper
+  module API
+    # Defines methods related to OAuth
+    module OAuth
+      # Gets an OAuth access token for a user.
+      def access_token(username, password)
+        response = perform_post_with_unparsed_response('/api/1.1/oauth/access_token', x_auth_username: username, x_auth_password: password, x_auth_mode: 'client_auth')
+        parsed_response = QLineParser.parse(response)
+        fail Instapaper::Error::OAuthError, parsed_response['error'] if parsed_response.key?('error')
+        Instapaper::Credentials.new(parsed_response)
+      end
+    end
+  end
+end

data/lib/instapaper/bookmark.rb

@@ -0,0 +1,21 @@
+require 'virtus'
+
+module Instapaper
+  class Bookmark
+    include Virtus.value_object
+
+    values do
+      attribute :instapaper_hash, String
+      attribute :description, String
+      attribute :bookmark_id, Integer
+      attribute :private_source, String
+      attribute :title, String
+      attribute :url, String
+      attribute :progress_timestamp, DateTime
+      attribute :time, DateTime
+      attribute :progress, String
+      attribute :starred, String
+      attribute :type, String
+    end
+  end
+end

data/lib/instapaper/bookmark_list.rb

@@ -0,0 +1,20 @@
+require 'instapaper/bookmark'
+require 'instapaper/highlight'
+require 'instapaper/user'
+
+module Instapaper
+  class BookmarkList
+    include Virtus.value_object
+
+    values do
+      attribute :user, Instapaper::User
+      attribute :bookmarks, Array[Instapaper::Bookmark]
+      attribute :highlights, Array[Instapaper::Highlight]
+      attribute :delete_ids, Array[Integer]
+    end
+
+    def each
+      bookmarks.each { |bookmark| yield(bookmark) }
+    end
+  end
+end

data/lib/instapaper/client.rb

@@ -1,43 +1,55 @@
-require 'instapaper/connection'
-require 'instapaper/request'
-require 'instapaper/authentication'
+require 'instapaper/api'
+require 'instapaper/http/utils'
+require 'instapaper/version'
 
 module Instapaper
   # Wrapper for the Instapaper REST API
   class Client
-    # @private
-    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+    include Instapaper::API
+    include Instapaper::HTTP::Utils
 
-    alias :api_endpoint :endpoint
-    alias :api_version :version
+    attr_accessor :oauth_token, :oauth_token_secret, :consumer_key, :consumer_secret, :proxy
+    attr_writer :user_agent
 
-    # Creates a new API
-    def initialize(options={})
-      options = Instapaper.options.merge(options)
-      Configuration::VALID_OPTIONS_KEYS.each do |key|
-        send("#{key}=", options[key])
+    # Initializes a new Client object
+    #
+    # @param options [Hash]
+    # @return [Instapaper::Client]
+    def initialize(options = {})
+      options.each do |key, value|
+        instance_variable_set("@#{key}", value)
       end
+      yield(self) if block_given?
     end
 
-    def endpoint_with_prefix
-      api_endpoint + path_prefix
+    # @return [String]
+    def user_agent
+      @user_agent ||= "InstapaperRubyGem/#{Instapaper::VERSION}"
     end
 
-    include Connection
-    include Request
-    include Authentication
+    # Authentication hash
+    #
+    # @return [Hash]
+    def credentials
+      {
+        consumer_key: @consumer_key,
+        consumer_secret: @consumer_secret,
+        oauth_token: @oauth_token,
+        oauth_token_secret: @oauth_token_secret,
+      }
+    end
 
-    # Require client method modules after initializing the Client class in
-    # order to avoid a superclass mismatch error, allowing those modules to be
-    # Client-namespaced.
-    require 'instapaper/client/account'
-    require 'instapaper/client/user'
-    require 'instapaper/client/bookmark'
-    require 'instapaper/client/folder'
+    # @return [Hash]
+    def consumer_credentials
+      {
+        consumer_key: @consumer_key,
+        consumer_secret: @consumer_secret,
+      }
+    end
 
-    include Instapaper::Client::Account
-    include Instapaper::Client::User
-    include Instapaper::Client::Bookmark
-    include Instapaper::Client::Folder
+    # @return [Boolean]
+    def credentials?
+      credentials.values.all?
+    end
   end
 end

data/lib/instapaper/credentials.rb

@@ -0,0 +1,12 @@
+require 'virtus'
+
+module Instapaper
+  class Credentials
+    include Virtus.value_object
+
+    values do
+      attribute :oauth_token, String
+      attribute :oauth_token_secret, String
+    end
+  end
+end

data/lib/instapaper/error.rb

@@ -0,0 +1,78 @@
+module Instapaper
+  # Custom error class for rescuing from all Instapaper errors
+  class Error < StandardError
+    # @return [Integer]
+    attr_reader :code
+
+    ServiceUnavailableError = Class.new(self)
+    BookmarkError = Class.new(self)
+    FolderError = Class.new(self)
+    HighlightError = Class.new(self)
+    OAuthError = Class.new(self)
+
+    ERRORS = {
+      1040 => 'Rate-limit exceeded',
+      1041 => 'Premium account required',
+      1042 => 'Application is suspended',
+      1500 => 'Unexpected service error',
+      1550 => 'Error generating text version of this URL',
+    }
+
+    BOOKMARK_ERRORS = {
+      1220 => 'Domain requires full content to be supplied',
+      1221 => 'Domain has opted out of Instapaper compatibility',
+      1240 => 'Invalid URL specified',
+      1241 => 'Invalid or missing bookmark_id',
+      1242 => 'Invalid or missing folder_id',
+      1243 => 'Invalid or missing progress',
+      1244 => 'Invalid or missing progress_timestamp',
+      1245 => 'Private bookmarks require supplied content',
+      1250 => 'Unexpected error when saving bookmark',
+    }
+
+    FOLDER_ERRORS = {
+      1250 => 'Invalid or missing title',
+      1251 => 'User already has a folder with this title',
+      1252 => 'Cannot add bookmarks to this folder',
+    }
+
+    HIGHLIGHT_ERRORS = {
+      1600 => 'Cannot create highlight with empty text',
+      1601 => 'Duplicate highlight',
+    }
+
+    CODES = [
+      ERRORS,
+      BOOKMARK_ERRORS,
+      FOLDER_ERRORS,
+      HIGHLIGHT_ERRORS,
+    ].collect(&:keys).flatten
+
+    # Create a new error from an HTTP response
+    #
+    # @param response [HTTP::Response]
+    # @return [Instapaper::Error]
+    def self.from_response(code, path)
+      if ERRORS.keys.include?(code)
+        new(ERRORS[code], code)
+      else
+        case path
+        when /highlights/ then HighlightError.new(HIGHLIGHT_ERRORS[code], code)
+        when /bookmarks/ then BookmarkError.new(BOOKMARK_ERRORS[code], code)
+        when /folders/ then FolderError.new(FOLDER_ERRORS[code], code)
+        else new('Unknown Error Code', code)
+        end
+      end
+    end
+
+    # Initializes a new Error object
+    #
+    # @param message [Exception, String]
+    # @param code [Integer]
+    # @return [Instapaper::Error]
+    def initialize(message = '', code = nil)
+      super(message)
+      @code = code
+    end
+  end
+end

data/lib/instapaper/folder.rb

@@ -0,0 +1,17 @@
+require 'virtus'
+
+module Instapaper
+  class Folder
+    include Virtus.value_object
+
+    values do
+      attribute :title, String
+      attribute :display_title, String
+      attribute :sync_to_mobile, Axiom::Types::Boolean
+      attribute :folder_id, Integer
+      attribute :position, String
+      attribute :type, String
+      attribute :slug, String
+    end
+  end
+end

data/lib/instapaper/highlight.rb

@@ -0,0 +1,16 @@
+require 'virtus'
+
+module Instapaper
+  class Highlight
+    include Virtus.value_object
+
+    values do
+      attribute :type, String
+      attribute :highlight_id, String
+      attribute :bookmark_id, String
+      attribute :text, String
+      attribute :position, String
+      attribute :time, String
+    end
+  end
+end

data/lib/instapaper/http/headers.rb

@@ -0,0 +1,45 @@
+require 'addressable/uri'
+require 'base64'
+require 'simple_oauth'
+
+module Instapaper
+  module HTTP
+    class Headers
+      def initialize(client, request_method, url, options = {})
+        @client = client
+        @request_method = request_method.to_sym
+        @uri = Addressable::URI.parse(url)
+        @options = options
+      end
+
+      def request_headers
+        {
+          user_agent: @client.user_agent,
+          authorization: oauth_header,
+        }
+      end
+
+      private
+
+      def oauth_header
+        SimpleOAuth::Header.new(@request_method, @uri, @options, credentials.merge(ignore_extra_keys: true))
+      end
+
+      # Authentication hash
+      #
+      # @return [Hash]
+      def credentials
+        if @client.credentials?
+          {
+            consumer_key: @client.consumer_key,
+            consumer_secret: @client.consumer_secret,
+            token: @client.oauth_token,
+            token_secret: @client.oauth_token_secret,
+          }
+        else
+          @client.consumer_credentials
+        end
+      end
+    end
+  end
+end

data/lib/instapaper/http/qline_parser.rb

@@ -0,0 +1,9 @@
+module Instapaper
+  class QLineParser
+    def self.parse(response)
+      values = response.split('&').map { |part| part.split('=') }.flatten
+      values.unshift('error') if values.length == 1
+      Hash[*values]
+    end
+  end
+end

data/lib/instapaper/http/request.rb

@@ -0,0 +1,84 @@
+require 'addressable/uri'
+require 'http'
+require 'json'
+require 'net/https'
+require 'openssl'
+require 'instapaper/error'
+require 'instapaper/http/headers'
+
+module Instapaper
+  module HTTP
+    class Request
+      BASE_URL = 'https://www.instapaper.com'
+      attr_accessor :client, :headers, :multipart, :options, :path,
+                    :rate_limit, :request_method, :uri
+      alias_method :verb, :request_method
+
+      # @param client [Instapaper::Client]
+      # @param request_method [String, Symbol]
+      # @param path [String]
+      # @param options [Hash]
+      # @return [Instapaper::HTTP::Request]
+      def initialize(client, request_method, path, options = {})
+        @client = client
+        @request_method = request_method
+        @uri = Addressable::URI.parse(path.start_with?('http') ? path : BASE_URL + path)
+        @path = uri.path
+        @options = options
+      end
+
+      # @return [Array, Hash]
+      def perform
+        perform_request
+      end
+
+      private
+
+      def perform_request
+        raw = @options.delete(:raw)
+        @headers = Instapaper::HTTP::Headers.new(@client, @request_method, @uri, @options).request_headers
+        options_key = @request_method == :get ? :params : :form
+        response = ::HTTP.with(@headers).public_send(@request_method, @uri.to_s, options_key => @options)
+        fail_if_error(response, raw)
+        raw ? response.to_s : parsed_response(response)
+      end
+
+      def fail_if_error(response, raw)
+        fail_if_error_unparseable_response(response) unless raw
+        fail_if_error_in_body(parsed_response(response))
+        fail_if_error_response_code(response)
+      end
+
+      def fail_if_error_response_code(response)
+        fail Instapaper::Error::ServiceUnavailableError if response.status != 200
+      end
+
+      def fail_if_error_unparseable_response(response)
+        response.parse(:json)
+      rescue JSON::ParserError
+        raise Instapaper::Error::ServiceUnavailableError
+      end
+
+      def fail_if_error_in_body(response)
+        error = error(response)
+        fail(error) if error
+      end
+
+      def error(response)
+        return unless response.is_a?(Array)
+        return unless response.size > 0
+        return unless response.first['type'] == 'error'
+
+        Instapaper::Error.from_response(response.first['error_code'], @path)
+      end
+
+      def parsed_response(response)
+        @parsed_response ||= begin
+          response.parse(:json)
+        rescue
+          response.body
+        end
+      end
+    end
+  end
+end