instapaper 0.1.0 → 0.2.0

data/.gitignore

@@ -0,0 +1,11 @@
+*.gem
+*.rbc
+.DS_Store
+.bundle
+.rvmrc
+.yardoc
+Gemfile.lock
+coverage/*
+doc/*
+log/*
+pkg/*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=nested
+--backtrace

data/.simplecov

@@ -0,0 +1 @@
+SimpleCov.start

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+-
+LICENSE.md

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Steve Agalloco
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+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.
+
+Installation
+------------
+    gem install instapaper
+
+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.
+
+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
+end
+```
+
+Authentication
+--------------
+
+To obtain an access token via xAuth:
+
+```ruby
+Instapaper.access_token(username, password)
+```
+
+You can also verify credentials once you have received tokens:
+
+```ruby
+Instapaper.verify_credentials
+```
+
+Bookmark Operations
+-------------------
+
+Retrieve a list of bookmarks:
+
+```ruby
+Instapaper.bookmarks
+```
+
+Add a new bookmark:
+
+```ruby
+Instapaper.add_bookmark('http://someurl.com', :title => 'This is the title', :description => 'This is the description')
+```
+
+Remove a bookmark:
+
+```ruby
+Instapaper.delete_bookmark(bookmark_id)
+```
+
+Update read progress:
+
+```ruby
+Instapaper.update_read_progress(bookmark_id, 0.5)
+```
+
+Star/Un-star a bookmark:
+
+```ruby
+Instapaper.star(bookmark_id)
+Instapaper.unstar(bookmark_id)
+```
+
+Archive/Un-archive a bookmark:
+
+```ruby
+Instapaper.archive(bookmark_id)
+Instapaper.unarchive(bookmark_id)
+```
+
+Move a bookmark to a folder:
+
+```ruby
+Instapaper.move(bookmark_id, folder_id)
+```
+
+Obtain the text of a bookmark:
+
+```ruby
+Instapaper.text(bookmark_id)
+```
+
+Folder Operations
+-----------------
+
+To obtain the list of folders:
+
+```ruby
+Instapaper.folders
+```
+
+You can add by passing a name:
+
+```ruby
+Instapaper.add_folder('eventmachine')
+```
+
+And remove folders by referencing a folder by it's id.
+
+```ruby
+Instapaper.delete_folder(folder_id)
+```
+
+Lastly, the folders can be reordered:
+
+```ruby
+Instapaper.set_order(['folder_id1:2','folder_id2:1'])
+```
+
+Restrictions
+------------
+
+Users without an Instapaper Subscription may only invoke the following calls:
+
+```ruby
+Instapaper.access_token
+Instapaper.verify_credentials
+Instapaper.add_bookmark
+Instapaper.folders
+```
+
+Documentation
+-------------
+
+[http://rdoc.info/gems/instapaper](http://rdoc.info/gems/instapaper)
+
+Note on Patches/Pull Requests
+-----------------------------
+
+* Fork the project.
+* 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.
+  (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.

data/Rakefile

@@ -1,4 +1,13 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
-
-Dir['tasks/**/*.rake'].each { |rake| load rake }
+#!/usr/bin/env rake
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/instapaper.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+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('hashie', '~> 1.1.0')
+  gem.add_runtime_dependency('faraday_middleware', '~> 0.7')
+  gem.add_runtime_dependency('multi_json', '~> 1.0.3')
+  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"]
+end

data/lib/faraday/response/raise_http_1xxx.rb

@@ -0,0 +1,65 @@
+require 'faraday'
+
+# @private
+module Faraday
+  # @private
+  class Response::RaiseHttp1xxx < Response::Middleware
+    def on_complete(env)
+      case env[:status].to_i
+
+      # general errors
+
+      when 1040
+        raise Instapaper::Error.new(error_message(env, "Rate-limit exceeded."))
+      when 1041
+        raise Instapaper::Error.new(error_message(env, "Subscription account required."))
+      when 1042
+        raise Instapaper::Error.new(error_message(env, "Application is suspended."))
+
+      # bookmark errors
+
+      when 1220
+        raise Instapaper::Error.new(error_message(env, "Domain requires full content to be supplied."))
+      when 1221
+        raise Instapaper::Error.new(error_message(env, "Domain has opted out of Instapaper compatibility."))
+      when 1240
+        raise Instapaper::Error.new(error_message(env, "Invalid URL specified."))
+      when 1241
+        raise Instapaper::Error.new(error_message(env, "Invalid or missing bookmark_id."))
+      when 1242
+        raise Instapaper::Error.new(error_message(env, "Invalid or missing folder_id."))
+      when 1243
+        raise Instapaper::Error.new(error_message(env, "Invalid or missing progress."))
+      when 1244
+        raise Instapaper::Error.new(error_message(env, "Invalid or missing progress_timestamp."))
+      when 1245
+        raise Instapaper::Error.new(error_message(env, "Private bookmarks require supplied content."))
+      when 1250
+        raise Instapaper::Error.new(error_message(env, "Unexpected error when saving bookmark."))
+
+      # folder errors
+
+      when 1250
+        raise Instapaper::Error.new(error_message(env, "Invalid or missing title."))
+      when 1251
+        raise Instapaper::Error.new(error_message(env, "User already has a folder with this title."))
+      when 1252
+        raise Instapaper::Error.new(error_message(env, "Cannot add bookmarks to this folder."))
+
+      # operational errors
+
+      when 1500
+        raise Instapaper::Error.new(error_message(env, "Unexpected service error."))
+      when 1550
+        raise Instapaper::Error.new(error_message(env, "Error generating text version of this URL."))
+
+      end
+    end
+
+    private
+
+    def error_message(env, body=nil)
+      "#{env[:method].to_s.upcase} #{env[:url].to_s}: #{[env[:status].to_s + ':', body].compact.join(' ')}."
+    end
+  end
+end

data/lib/instapaper.rb

@@ -1,10 +1,26 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
-
-require 'instapaper/version'
-require 'instapaper/exceptions'
-require 'instapaper/constants'
-require 'instapaper/protocol'
-require 'instapaper/request'
-require 'instapaper/response'
-require 'instapaper/base'
+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/authentication.rb

@@ -0,0 +1,32 @@
+module Instapaper
+  # @private
+  module Authentication
+    private
+
+    # Authentication hash
+    #
+    # @return [Hash]
+    def authentication
+      {
+        :consumer_key => consumer_key,
+        :consumer_secret => consumer_secret,
+        :token => oauth_token,
+        :token_secret => oauth_token_secret
+      }
+    end
+
+    def consumer_tokens
+      {
+        :consumer_key => consumer_key,
+        :consumer_secret => consumer_secret
+      }
+    end
+
+    # Check whether user is authenticated
+    #
+    # @return [Boolean]
+    def authenticated?
+      authentication.values.all?
+    end
+  end
+end

data/lib/instapaper/client.rb

@@ -0,0 +1,43 @@
+require 'instapaper/connection'
+require 'instapaper/request'
+require 'instapaper/authentication'
+
+module Instapaper
+  # Wrapper for the Instapaper REST API
+  class Client
+    # @private
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    alias :api_endpoint :endpoint
+    alias :api_version :version
+
+    # Creates a new API
+    def initialize(options={})
+      options = Instapaper.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    def endpoint_with_prefix
+      api_endpoint + path_prefix
+    end
+
+    include Connection
+    include Request
+    include Authentication
+
+    # 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'
+
+    include Instapaper::Client::Account
+    include Instapaper::Client::User
+    include Instapaper::Client::Bookmark
+    include Instapaper::Client::Folder
+  end
+end

data/lib/instapaper/client/account.rb

@@ -0,0 +1,13 @@
+module Instapaper
+  class Client
+    # Defines methods related to accounts
+    module Account
+
+      # Returns the currently logged in user.
+      def verify_credentials
+        post('account/verify_credentials')
+      end
+
+    end
+  end
+end