instapaper 0.3.0 → 1.0.0.pre2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f6911bf834c466bf44a4ad781b290748a755afb0
+  data.tar.gz: 58b7928393bfbf9e2569b055d5d87f6438d68efb
+SHA512:
+  metadata.gz: 3102c9408cf4579078b29516321f43681873632f93dd154ee8d4422b7f5e4609cf2c2272f8cc3e7fa6319304b1e5974dafbb2777f88bcb0571877548e5aa7ebf
+  data.tar.gz: b4b75bea5a250eae3ea9f3678714b029438a6db0cc5fc85e377e64b4fbaa4062bd767e3300412de2946cabba64e1be7e491a32443b0a80110db4b2e1b21eaac1

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,10 @@
-# Instapaper
+# Instapaper [![Build Status](https://secure.travis-ci.org/stve/instapaper.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/stve/instapaper.png?travis)][gemnasium]
 
-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.
+[travis]: http://travis-ci.org/stve/instapaper
+[gemnasium]: https://gemnasium.com/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 +12,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 +42,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 +56,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 +114,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 +170,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', __FILE__)
+$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', '~> 0.9'
+  spec.add_dependency 'multi_json', '~> 1'
+  spec.add_dependency 'simple_oauth', '~> 0.3'
+  spec.add_dependency 'virtus', '~> 1'
+  spec.add_development_dependency 'bundler', '~> 1.0'
+  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.rb

@@ -1,26 +1 @@
-require 'instapaper/configuration'
 require 'instapaper/client'
-
-module Instapaper
-  extend Configuration
-
-  # Alias for Instapaper::Client.new
-  #
-  # @return [Instapaper::Client]
-  def self.client(options={})
-    Instapaper::Client.new(options)
-  end
-
-  # Delegate to Instapaper::Client
-  def self.method_missing(method, *args, &block)
-    return super unless client.respond_to?(method)
-    client.send(method, *args, &block)
-  end
-
-  def self.respond_to?(method, include_private = false)
-    client.respond_to?(method, include_private) || super(method, include_private)
-  end
-
-  # Custom error class for rescuing from all Instapaper errors
-  class Error < StandardError; 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/{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 Style/AccessorMethodName
+        perform_post_with_objects('/api/1.1/folders/set_order', {order: order.join(',')}, Instapaper::Folder)
       end
-
     end
   end
 end