instapaper 0.3.0 → 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f676a4a48c703e736cfd38eb18782f59695b96a90f161dceef13ebdc3c2a59cb
+  data.tar.gz: 7578b717fbc477c7b1607ad66fbf71474c9ab74d6feaf2732cf01e91372499cd
+SHA512:
+  metadata.gz: b0bb55c79906debe49a45b95413ede8d85de5bb6f583d7a51b9ff3fda0795f0e4342eee24da19ddd24360d989c251c3946bd58b473d4256011c480ccaa3b632e
+  data.tar.gz: 540559d498d6a4d8dcddbfa1f48ee8f19ab7bcb4df03fd3331cccb96c8642f3cfc28bcfa1fe604f5bcbefce2be3ccc054ca7998d656b9b85e63794b96b9f9c30

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Steve Agalloco
+Copyright (c) 2015 Steve Agalloco
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,6 +1,15 @@
 # Instapaper
 
-Instapaper is a ruby wrapper for interacting with [Instapaper's Full Developer API](http://www.instapaper.com/api/full).  Note that access to the Full API is restricted to Instapaper subscribers only.
+[![Gem Version](http://img.shields.io/gem/v/instapaper.svg)][gem]
+[![Build Status](http://img.shields.io/travis/stve/instapaper.svg)][travis]
+[![Code Climate](https://img.shields.io/codeclimate/maintainability/stve/instapaper.svg)][codeclimate]
+
+[gem]: https://rubygems.org/gems/instapaper
+[travis]: https://travis-ci.org/stve/instapaper
+[codeclimate]: https://codeclimate.com/github/stve/instapaper
+
+
+Instapaper is a ruby wrapper for interacting with [Instapaper's Full API](https://www.instapaper.com/api/full).  Note that access to the Full API is restricted to Instapaper subscribers only.
 
 ## Installation
 
@@ -8,16 +17,28 @@ Instapaper is a ruby wrapper for interacting with [Instapaper's Full Developer A
 
 ## Usage
 
-Instapaper offers full support for all methods exposed through the Full API.  Note that Instapaer does not support the request-token/authorize workflow.  To obtain an access token, use the `access_token` method.
+This library offers full support for all methods exposed through Instapaper's Full API.  Note that Instapaper's API does not support the request-token/authorize workflow. To obtain an access token, use the `access_token` method.
+
+## Changes in 1.0.0
+
+If you've used earlier versions of this library, a lot has changed in version `1.x`. While not a total rewrite, I've changed a number of things based on my experience writing API libraries:
+
+* swapped out Faraday for http.rb
+* responses now return custom classes instead of Hashie::Rash objects
+* most API methods are more clear as to their behavior (i.e., `#star_bookmark` instead of just `#star`)
+* module-based configuration and invocation has been removed, you'll now need to instantiate an `Instapaper::Client` instead (see usage below)
+* Improved error handling
+* Updates for version 1.1 of Instapaper's API
+* Support for Highlights API
 
 ## Configuration
 
 ```ruby
-Instapaper.configure do |config|
-  config.consumer_key = YOUR_CONSUMER_KEY
-  config.consumer_secret = YOUR_CONSUMER_SECRET
-  config.oauth_token = YOUR_OAUTH_TOKEN
-  config.oauth_token_secret = YOUR_OAUTH_TOKEN_SECRET
+client = Instapaper::Client.new do |client|
+  client.consumer_key = YOUR_CONSUMER_KEY
+  client.consumer_secret = YOUR_CONSUMER_SECRET
+  client.oauth_token = YOUR_OAUTH_TOKEN
+  client.oauth_token_secret = YOUR_OAUTH_TOKEN_SECRET
 end
 ```
 
@@ -26,13 +47,13 @@ end
 To obtain an access token via xAuth:
 
 ```ruby
-Instapaper.access_token(username, password)
+client.access_token(username, password)
 ```
 
 You can also verify credentials once you have received tokens:
 
 ```ruby
-Instapaper.verify_credentials
+client.verify_credentials
 ```
 
 ## Bookmark Operations
@@ -40,51 +61,56 @@ Instapaper.verify_credentials
 Retrieve a list of bookmarks:
 
 ```ruby
-Instapaper.bookmarks
+client.bookmarks
 ```
 
 Add a new bookmark:
 
 ```ruby
-Instapaper.add_bookmark('http://someurl.com', :title => 'This is the title', :description => 'This is the description')
+bookmark = {
+  title: 'This is the title',
+  description: 'This is the description',
+}
+
+client.add_bookmark('http://someurl.com', bookmark)
 ```
 
 Remove a bookmark:
 
 ```ruby
-Instapaper.delete_bookmark(bookmark_id)
+client.delete_bookmark(bookmark_id)
 ```
 
 Update read progress:
 
 ```ruby
-Instapaper.update_read_progress(bookmark_id, 0.5)
+client.update_read_progress(bookmark_id, 0.5)
 ```
 
 Star/Un-star a bookmark:
 
 ```ruby
-Instapaper.star(bookmark_id)
-Instapaper.unstar(bookmark_id)
+client.star_bookmark(bookmark_id)
+client.unstar_bookmark(bookmark_id)
 ```
 
 Archive/Un-archive a bookmark:
 
 ```ruby
-Instapaper.archive(bookmark_id)
-Instapaper.unarchive(bookmark_id)
+client.archive_bookmark(bookmark_id)
+client.unarchive_bookmark(bookmark_id)
 ```
 
 Move a bookmark to a folder:
 
 ```ruby
-Instapaper.move(bookmark_id, folder_id)
+client.move_bookmark(bookmark_id, folder_id)
 ```
 
 Obtain the text of a bookmark:
 
 ```ruby
-Instapaper.text(bookmark_id)
+client.get_text(bookmark_id)
 ```
 
 ## Folder Operations
@@ -93,48 +119,51 @@ Instapaper.text(bookmark_id)
 To obtain the list of folders:
 
 ```ruby
-Instapaper.folders
+client.folders
 ```
 
 You can add by passing a name:
 
 ```ruby
-Instapaper.add_folder('eventmachine')
+client.add_folder('eventmachine')
 ```
 
 And remove folders by referencing a folder by it's id.
 
 ```ruby
-Instapaper.delete_folder(folder_id)
+client.delete_folder(folder_id)
 ```
 
 Lastly, the folders can be reordered:
 
 ```ruby
-Instapaper.set_order(['folder_id1:2','folder_id2:1'])
+client.set_order(['folder_id1:2','folder_id2:1'])
 ```
 
-## Restrictions
+## Highlights Operations
 
-Users without an Instapaper Subscription may only invoke the following calls:
+Obtain highlights for a bookmark:
 
 ```ruby
-Instapaper.access_token
-Instapaper.verify_credentials
-Instapaper.add_bookmark
-Instapaper.folders
+client.highlights(bookmark_id)
 ```
 
-## <a name="build"></a>Build Status
-[![Build Status](https://secure.travis-ci.org/spagalloco/instapaper.png?branch=master)][travis]
+Add a highlight for a bookmark:
 
-[travis]: http://travis-ci.org/spagalloco/instapaper
+```ruby
+highlight = {
+  text: 'And so we beat on, boats against the current, borne back ceaselessly into the past.',
+  position: 20,
+}
 
-## <a name="dependencies"></a>Dependency Status
-[![Dependency Status](https://gemnasium.com/spagalloco/instapaper.png?travis)][gemnasium]
+client.add_highlight(bookmark_id, highlight)
+```
 
-[gemnasium]: https://gemnasium.com/spagalloco/instapaper
+Remove a highlight:
 
+```ruby
+client.delete_highlight(highlight_id)
+```
 
 ## Documentation
 
@@ -146,10 +175,10 @@ Instapaper.folders
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
   future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
+* Commit, do not mess with Rakefile, gem version, or history.
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 ## Copyright
 
-Copyright (c) 2011 Steve Agalloco. See [LICENSE](https://github.com/spagalloco/instapaper/blob/master/LICENSE.md) for details.
+Copyright (c) 2015 Steve Agalloco. See [LICENSE](https://github.com/stve/instapaper/blob/master/LICENSE.md) for details.

data/instapaper.gemspec

@@ -1,32 +1,23 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "instapaper/version"
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'instapaper/version'
 
-Gem::Specification.new do |gem|
-  gem.name        = "instapaper"
-  gem.version     = Instapaper::VERSION
-
-  gem.author      = "Steve Agalloco"
-  gem.email       = "steve.agalloco@gmail.com"
-  gem.homepage    = "https://github.com/spagalloco/instapaper"
-  gem.summary     = %q{Ruby Instapaper Client}
-  gem.description = %q{Ruby Instapaper Client}
-
-  gem.add_development_dependency('rake', '~> 0.9')
-  gem.add_development_dependency('rdiscount', '~> 1.6')
-  gem.add_development_dependency('rspec', '~> 2.7')
-  gem.add_development_dependency('simplecov', '~> 0.5')
-  gem.add_development_dependency('yard', '~> 0.7')
-  gem.add_development_dependency('json', '>= 0')
-  gem.add_development_dependency('webmock', '~> 1.7')
-
-  gem.add_runtime_dependency('faraday_middleware', '~> 0.7')
-  gem.add_runtime_dependency('multi_json', '~> 1')
-  gem.add_runtime_dependency('rash', '~> 0.3')
-  gem.add_runtime_dependency('simple_oauth', '~> 0.1')
-
-  gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  gem.require_paths = ["lib"]
+Gem::Specification.new do |spec|
+  spec.add_dependency 'addressable', '~> 2.3'
+  spec.add_dependency 'http', '>= 2', '< 6'
+  spec.add_dependency 'multi_json', '~> 1'
+  spec.add_dependency 'simple_oauth', '~> 0.3'
+  spec.add_dependency 'virtus', '~> 1'
+  spec.add_development_dependency 'bundler'
+  spec.author        = 'Steve Agalloco'
+  spec.description   = "Ruby Client for Instapaper's Full API"
+  spec.email         = 'steve.agalloco@gmail.com'
+  spec.files         = %w[LICENSE.md README.md instapaper.gemspec] + Dir['lib/**/*.rb']
+  spec.homepage      = 'https://github.com/stve/instapaper'
+  spec.licenses      = %w[MIT]
+  spec.name          = 'instapaper'
+  spec.require_paths = %w[lib]
+  spec.required_ruby_version = '>= 2.0.0'
+  spec.summary       = 'Ruby Instapaper Client'
+  spec.version       = Instapaper::VERSION
 end

data/lib/instapaper/{client/account.rb → api/accounts.rb}

@@ -1,13 +1,13 @@
+require 'instapaper/user'
+
 module Instapaper
-  class Client
+  module API
     # Defines methods related to accounts
-    module Account
-
+    module Accounts
       # Returns the currently logged in user.
       def verify_credentials
-        post('account/verify_credentials')
+        perform_post_with_object('/api/1.1/account/verify_credentials', {}, Instapaper::User)
       end
-
     end
   end
 end

data/lib/instapaper/api/bookmarks.rb

@@ -0,0 +1,77 @@
+require 'instapaper/bookmark'
+require 'instapaper/bookmark_list'
+
+module Instapaper
+  module API
+    # Defines methods related to bookmarks
+    module Bookmarks
+      # Lists the user's unread bookmarks, and can also synchronize reading positions.
+      # @option limit: Optional. A number between 1 and 500, default 25.
+      # @option folder_id: Optional. Possible values are unread (default), starred, archive, or a folder_id value from /api/1.1/folders/list.
+      # @option have: Optional. A concatenation of bookmark_id values that the client already has from the specified folder. See below.
+      # @option highlights: Optional. A '-' delimited list of highlight IDs that the client already has from the specified bookmarks.
+      def bookmarks(options = {})
+        perform_post_with_object('/api/1.1/bookmarks/list', options, Instapaper::BookmarkList)
+      end
+
+      # Updates the user's reading progress on a single article.
+      # @param bookmark_id [String] The id of the bookmark to update.
+      # @param progress [Float] The user's progress, as a floating-point number between 0.0 and 1.0, defined as the top edge of the user's current viewport, expressed as a percentage of the article's total length.
+      # @param progress_timestamp [Integer] The Unix timestamp value of the time that the progress was recorded.
+      def update_read_progress(bookmark_id, progress, progress_timestamp = Time.now)
+        perform_post_with_object('/api/1.1/bookmarks/update_read_progress', {bookmark_id: bookmark_id, progress: progress, progress_timestamp: progress_timestamp.to_i}, Instapaper::Bookmark)
+      end
+
+      # Adds a new unread bookmark to the user's account.
+      # @param url [String] The url of the bookmark.
+      def add_bookmark(url, options = {})
+        perform_post_with_object('/api/1.1/bookmarks/add', options.merge(url: url), Instapaper::Bookmark)
+      end
+
+      # Permanently deletes the specified bookmark.
+      # This is NOT the same as Archive. Please be clear to users if you're going to do this.
+      # @param bookmark_id [String] The id of the bookmark.
+      def delete_bookmark(bookmark_id)
+        perform_post_with_objects('/api/1.1/bookmarks/delete', {bookmark_id: bookmark_id}, Array)
+      end
+
+      # Stars the specified bookmark.
+      # @param bookmark_id [String] The id of the bookmark.
+      def star_bookmark(bookmark_id)
+        perform_post_with_object('/api/1.1/bookmarks/star', {bookmark_id: bookmark_id}, Instapaper::Bookmark)
+      end
+
+      # Un-stars the specified bookmark.
+      # @param bookmark_id [String] The id of the bookmark.
+      def unstar_bookmark(bookmark_id)
+        perform_post_with_object('/api/1.1/bookmarks/unstar', {bookmark_id: bookmark_id}, Instapaper::Bookmark)
+      end
+
+      # Moves the specified bookmark to the Archive.
+      # @param bookmark_id [String] The id of the bookmark.
+      def archive_bookmark(bookmark_id)
+        perform_post_with_object('/api/1.1/bookmarks/archive', {bookmark_id: bookmark_id}, Instapaper::Bookmark)
+      end
+
+      # Moves the specified bookmark to the top of the Unread folder.
+      # @param bookmark_id [String] The id of the bookmark.
+      def unarchive_bookmark(bookmark_id)
+        perform_post_with_object('/api/1.1/bookmarks/unarchive', {bookmark_id: bookmark_id}, Instapaper::Bookmark)
+      end
+
+      # Moves the specified bookmark to a user-created folder.
+      # @param bookmark_id [String] The id of the bookmark.
+      # @param folder_id [String] The id of the folder to move the bookmark to.
+      def move_bookmark(bookmark_id, folder_id)
+        perform_post_with_object('/api/1.1/bookmarks/move', {bookmark_id: bookmark_id, folder_id: folder_id}, Instapaper::Bookmark)
+      end
+
+      # Returns the specified bookmark's processed text-view HTML, which is
+      # always text/html encoded as UTF-8.
+      # @param bookmark_id [String] The id of the bookmark.
+      def get_text(bookmark_id)
+        perform_post_with_unparsed_response('/api/1.1/bookmarks/get_text', bookmark_id: bookmark_id)
+      end
+    end
+  end
+end

data/lib/instapaper/{client/folder.rb → api/folders.rb}

@@ -1,34 +1,35 @@
+require 'instapaper/folder'
+
 module Instapaper
-  class Client
+  module API
     # Defines methods related to folders
-    module Folder
-
-      # List the account’s user-created folders.
+    module Folders
+      # List the account's user-created folders.
       # @note This only includes organizational folders and does not include RSS-feed folders or starred-subscription folders
       def folders
-        post('folders/list')
+        perform_post_with_objects('/api/1.1/folders/list', {}, Instapaper::Folder)
       end
 
       # Creates an organizational folder.
       # @param title [String] The title of the folder to create
       def add_folder(title)
-        post('folders/add', :title => title)
+        perform_post_with_object('/api/1.1/folders/add', {title: title}, Instapaper::Folder)
       end
 
       # Deletes the folder and moves any articles in it to the Archive.
       # @param folder_id [String] The id of the folder.
       def delete_folder(folder_id)
-        post('folders/delete', :folder_id => folder_id)
+        perform_post_with_unparsed_response('/api/1.1/folders/delete', folder_id: folder_id)
+        true
       end
 
-      # Re-orders a user’s folders.
+      # Re-orders a user's folders.
       # @param order [Array] An array of folder_id:position pairs joined by commas.
       # @example Ordering folder_ids 100, 200, and 300
       #   Instapaper.set_order(['100:1','200:2','300:3'])
-      def set_order(order=[])
-        post('folders/set_order', :order => order.join(','))
+      def set_order(order = []) # rubocop:disable Naming/AccessorMethodName
+        perform_post_with_objects('/api/1.1/folders/set_order', {order: order.join(',')}, Instapaper::Folder)
       end
-
     end
   end
 end

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,18 @@
+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)
+        raise Instapaper::Error::OAuthError, parsed_response['error'] if parsed_response.key?('error')
+
+        Instapaper::Credentials.new(parsed_response)
+      end
+    end
+  end
+end

data/lib/instapaper/api.rb

@@ -0,0 +1,15 @@
+require 'instapaper/api/accounts'
+require 'instapaper/api/bookmarks'
+require 'instapaper/api/folders'
+require 'instapaper/api/highlights'
+require 'instapaper/api/oauth'
+
+module Instapaper
+  module API
+    include Instapaper::API::Accounts
+    include Instapaper::API::Bookmarks
+    include Instapaper::API::Folders
+    include Instapaper::API::Highlights
+    include Instapaper::API::OAuth
+  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(&block)
+      bookmarks.each(&block)
+    end
+  end
+end

data/lib/instapaper/client.rb

@@ -1,43 +1,57 @@
-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])
-      end
+    # Initializes a new Client object
+    #
+    # @param options [Hash]
+    # @return [Instapaper::Client]
+    def initialize(options = {})
+      @oauth_token = options[:oauth_token]
+      @oauth_token_secret = options[:oauth_token_secret]
+      @consumer_key = options[:consumer_key]
+      @consumer_secret = options[:consumer_secret]
+      @proxy = options[:proxy]
+      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