read_it_later 0.2.0

data/.gitignore

@@ -0,0 +1 @@
+config/test.yml

data/README.textile

@@ -0,0 +1,7 @@
+h1. ReadItLater API Library for Ruby
+
+p. Please see sample_usage.rb for examples of use.
+
+p. For details on the ReadItLater API see http://readitlaterlist.com/api/docs/
+
+p. For details on what is ReadItLater see http://readitlaterlist.com/

data/Rakefile

@@ -0,0 +1,14 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "read_it_later"
+    gemspec.summary = "ReadItLaterList.com API Library for Ruby"
+    gemspec.description = "A very simple one-to-one api library for Read It Later API"
+    gemspec.email = "rha7.com@gmail.com"
+    gemspec.homepage = "http://github.com/rha7dotcom/read_it_later"
+    gemspec.authors = ["Gabriel Medina"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/config/cucumber.yml

@@ -0,0 +1 @@
+default: --format pretty --color features

data/config/test.yml.dist

@@ -0,0 +1,3 @@
+:api_key: <Your Read It Later API Key Here>
+:username: <Your user name>
+:password: <Your password>

data/features/read_it_later.feature

@@ -0,0 +1,69 @@
+Feature: Read It Later Management
+  In order to manage a list of bookmarks from read it later lists,
+  I should be able to add, get and mark as read bookmarks.
+  
+  Scenario: Add a new bookmark
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object 
+    And I add a new bookmark
+    Then I should get back a success response from RIL server
+    And I should receive usual user and key limits
+
+  Scenario: Send several updates at once
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object 
+    And I send several updates
+    Then I should get back a success response from RIL server
+    And I should receive usual user and key limits
+
+  Scenario: Request statistics of Read It Later bookmarks
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object 
+    And I send a statistics request
+    Then I should get back a success response from RIL server
+    And I should receive usual user and key limits
+    And I should receive statistics of usage
+
+  Scenario Outline: Get a list of bookmarks from Read It Later
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object
+    And I send a request for a list of "<count>" "<state>" Read It Later bookmarks for page "<page>", which are "<mine_only>", since "<since>", with tags "<tags>" 
+    Then I should get back a success response from RIL server
+    And I should receive data about the list of bookmarks
+    And I should receive a list of bookmarks, although it can be empty
+
+    Examples:
+      | state  | mine_only | since      | count | page | tags  |
+      | read   |           |            |       |      |       |
+      | unread |           |            |       |      |       |
+      |        | true      |            |       |      |       |
+      |        | false     |            |       |      |       |
+      |        |           | 2000-01-01 |       |      |       |
+      |        |           |            | 10    |      |       |
+      |        |           |            | 10    | 2    |       |
+      |        |           |            |       |      | true  |
+      |        |           |            |       |      | false |
+
+  Scenario: Authenticate an existing user
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object 
+    And I authenticate an existing user
+    Then I should get back a success response from RIL server
+    And I should receive usual user and key limits
+
+  Scenario:Sign up a new user
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object 
+    And I sign up a new user
+    Then I should get back a success response from RIL server
+    And I should receive usual user and key limits
+
+  Scenario: Get bookmark list statistics
+    Given I have a valid API Key and User
+    When I create a ReadItLater API Object 
+    And I send an API bookmarks list statistics request
+    Then I should get back a success response from RIL server
+    And I should receive usual user and key limits
+
+    
+

data/features/read_it_later_users.feature

@@ -0,0 +1,24 @@
+Feature: ReadItLater User Management
+  In order to make requests to ReadItLaterList.com API
+  Library user should be able to create User objects.
+
+  Scenario: User object created with both a user name and a password
+    When I create a User object with a user name "sample" and password "mypassword"
+    Then I should get a User object with no errors
+    And The User object should have a "user name" of "sample"
+    And The User object should have a "password" of "mypassword"
+
+  Scenario: User object created with a user name only
+    When I create a User object with a user name "sample" and password "unspecified"
+    Then I should get a User object with no errors
+    And The User object should have a "user name" of "sample"
+    And The User object should have a "password" of "unspecified"
+
+  Scenario: User object created without a user name or password
+    When I create a User object with a user name "unspecified" and password "unspecified"
+    Then I should get a User object with no errors
+    And The User object should have a "user name" of "unspecified"
+    And The User object should have a "password" of "unspecified"
+
+
+

data/features/step_definitions/read_it_later_steps.rb

@@ -0,0 +1,101 @@
+require 'yaml'
+require 'erb'
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'read_it_later')
+
+CONFIG=YAML.load(ERB.new(File.open(File.join(File.dirname(__FILE__), '..', '..', 'config', 'test.yml')).read).result)
+
+Given /^I have a valid API Key and User$/ do
+  @api_key = CONFIG[:api_key]
+  @username = CONFIG[:username]
+  @password = CONFIG[:password]
+end
+
+When /^I create a ReadItLater API Object$/ do
+  @ril = ReadItLater.new(@api_key)
+  @usr = ReadItLater::User.new(@username, @password)
+end
+
+When /^I add a new bookmark$/ do
+  @response = @ril.add(@usr, "http://www.google.com/search?q=#{rand(999999)}")
+end
+
+When /^I send several updates$/ do
+  @response = @ril.send(@usr,
+    :new => [
+      { :url => "http://www.url1.com/", :title => "URL New 1" },
+      { :url => "http://www.url2.com/", :title => "URL New 2" },
+      { :url => "http://www.url3.com/", :title => "URL New 3" }
+    ],
+    :read => [
+        { :url => "http://www.url1.com/" },
+        { :url => "http://www.url2.com/" },
+        { :url => "http://www.url3.com/" }
+    ],
+    :update_title => [
+      { :url => "http://www.url1.com/", :title => "Updated URL New 1" },
+      { :url => "http://www.url2.com/", :title => "Updated URL New 2" },
+      { :url => "http://www.url3.com/", :title => "Updated URL New 3" }
+    ],
+    :update_tags => [
+      { :url => "http://www.url1.com/", :tags => "url1tag1, url1tag2, url1tag3" },
+      { :url => "http://www.url2.com/", :tags => "url2tag1, url2tag2, url2tag3" },
+      { :url => "http://www.url3.com/", :tags => "url3tag1, url3tag2, url3tag3" }
+    ]
+  )
+end
+
+When /^I send a statistics request$/ do
+  @response = @ril.stats(@usr)
+end
+
+When /^I send a request for a list of "([^\"]*)" "([^\"]*)" Read It Later bookmarks for page "([^\"]*)", which are "([^\"]*)", since "([^\"]*)", with tags "([^\"]*)"$/ do |count, state, page, mine_only, since, tags|
+  params = {}
+  params[:state] = state.to_sym unless state.empty? if state
+  params[:count] = count.to_i unless count.empty? if count
+  params[:page] = page.to_i unless page.empty? if page
+  params[:mine_only] = eval(mine_only) unless mine_only.empty? if mine_only
+  params[:tags] = eval(tags) unless tags.empty? if tags
+  params[:since] = Time.parse(since) unless since.empty? if since
+  @response = @ril.get(@usr, params)
+end
+
+When /^I authenticate an existing user$/ do
+  @response = @ril.auth(@usr)
+end
+
+When /^I send an API bookmarks list statistics request$/ do
+  @response = @ril.api
+end
+
+When /^I sign up a new user$/ do
+  @response = @ril.api
+end
+
+Then /^I should get back a success response from RIL server$/ do
+  @response[:status].should == ReadItLater::STATUS_SUCCESS
+end
+
+Then /^I should receive usual user and key limits$/ do
+  @response.has_key?(:key).should be_true
+  @response.has_key?(:user).should be_true
+  @response.has_key?(:text).should be_true
+  @response.has_key?(:status).should be_true
+end
+
+Then /^I should receive statistics of usage$/ do
+  @response.has_key?(:data).should be_true
+  @response[:data].has_key?(:user_since).should be_true
+  @response[:data].has_key?(:count_unread).should be_true
+  @response[:data].has_key?(:count_read).should be_true
+  @response[:data].has_key?(:count_list).should be_true
+end
+
+Then /^I should receive data about the list of bookmarks$/ do
+  @response.should have_key(:data)
+end
+
+Then /^I should receive a list of bookmarks, although it can be empty$/ do
+  @response[:data].should have_key(:list)
+end
+
+

data/features/step_definitions/read_it_later_user_steps.rb

@@ -0,0 +1,35 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 'read_it_later')
+
+When /^I create a User object with a user name "([^\"]*)" and password "([^\"]*)"$/ do |username, password|
+  @username = (username == "unspecified" ? nil : username)
+  @password = (password == "unspecified" ? nil : password)
+end
+
+Then /^I should get a User object with no errors$/ do
+  lambda {
+    if @username and @password
+      @user = ReadItLater::User.new(@username, @password)
+    elsif @username
+      @user = ReadItLater::User.new(@username)
+    else
+      @user = ReadItLater::User.new
+    end
+  }.should_not raise_error
+end
+
+Then /^The User object should have a "([^\"]*)" of "([^\"]*)"$/ do |field_name, value|
+  if field_name == "user name"
+    if value == "unspecified"
+      @user.username.should be_nil
+    else
+      @user.username.should == value
+    end
+  else
+    if value == "unspecified"
+      @user.password.should be_nil
+    else
+      @user.password.should == value
+    end
+  end
+end
+

data/features/support/env.rb

@@ -0,0 +1,2 @@
+require 'spec/expectations'
+

data/lib/read_it_later.rb

@@ -0,0 +1,132 @@
+require 'open-uri'
+require 'json'
+
+class ReadItLater
+  
+  STATUS_SUCCESS     = 200
+  STATUS_INVALID     = 400
+  STATUS_DENIED      = 401
+  STATUS_EXCEEDED    = 403
+  STATUS_MAINTENANCE = 503
+  
+  URL_BASE = 'https://readitlaterlist.com/v2'
+  URLS = {
+    :add    => ReadItLater::URL_BASE+'/add'   ,
+    :send   => ReadItLater::URL_BASE+'/send'  ,
+    :stats  => ReadItLater::URL_BASE+'/stats' ,
+    :get    => ReadItLater::URL_BASE+'/get'   ,
+    :auth   => ReadItLater::URL_BASE+'/auth'  ,
+    :signup => ReadItLater::URL_BASE+'/signup',
+    :api    => ReadItLater::URL_BASE+'/api'   
+  }
+
+  attr_reader :last_response
+  
+  class User
+    attr_accessor :username, :password
+    def initialize(username=nil, password=nil)
+      @username, @password, @last_response = username, password, ""
+    end
+  end
+  
+  attr_accessor :api_key
+  
+  def initialize(api_key)
+    @api_key = api_key
+  end
+  
+  def add(user, url)
+    @last_response = query(:add, user, :url => url)
+  end
+  
+  def send(user, params)
+    %w(new read update_title update_tags).map(&:to_sym).each do |param|
+      params[param] = URI.escape((0..params[param].size-1).to_a.map{|n|{n.to_s=>params[param][n]}}.inject(){|a,b|a.merge(b)}.to_json) if params[param]
+    end
+    @last_response = query(:send, user, params)
+  end
+  
+  def stats(user)
+    response = query(:stats, user, :format => "json")
+    response[:data] = stringify_keys(JSON.parse(response[:text]))
+    response[:data][:user_since] = Time.at(response[:data][:user_since].to_i) 
+    @last_response = response
+  end
+  
+  def get(user, call_params)
+    params = { :format => "json" }
+    params[:state] = call_params[:state].to_s.strip if call_params[:state]
+    params[:myAppOnly] = (call_params[:mine_only] ? "1" : "0") if call_params[:mine_only]
+    params[:since] = call_params[:since].to_i if call_params[:since]
+    params[:count] = call_params[:count] if call_params[:count]
+    params[:page] = call_params[:page] if call_params[:page]
+    params[:tags] = (call_params[:tags] ? "1" : "0") if call_params[:tags]
+    response = query(:get, user, params)
+    response[:data] = stringify_keys(JSON.parse(response[:text]))
+    response[:data][:since] = Time.at(response[:data][:since])
+    response[:data][:status] = response[:data][:status] == 1 ? :normal : :no_changes 
+    response[:data][:list] = response[:data][:list].map{|k,v|v.merge(:time_added => Time.at(v[:time_added].to_i), :time_updated => Time.at(v[:time_updated].to_i), :item_id => v[:item_id].to_i, :read => (v[:state].strip == "0")).delete_if{|k,v|k==:state}} 
+    @last_response = response
+  end
+  
+  def auth(user)
+    @last_reponse = query(:auth, user)
+  end
+  
+  def signup(user)
+    @last_reponse = query(:signup, user)
+  end
+  
+  def api
+    @last_response = query(:api, User.new('',''))
+  end
+  
+  private
+  
+  def ril_api_url(method, user, params={})
+    params = { :apikey => @api_key, :username => user.username, :password => user.password }.merge(params)
+    query_str = URLS[method] + "?" + params.map{|k,v| "#{k.to_s}=#{URI.escape(v.to_s)}" }.join("&")
+    return query_str
+  end
+  
+  def unique_id
+    return (1..24).to_a.map{|i|(('a'..'z').to_a+('0'..'9').to_a)[rand(36)]}.join
+  end
+
+  def query(method, user, params={})
+    response = nil
+    begin
+      open(ril_api_url(method, user, params)) do |f|
+        response = build_response(f)
+      end
+    rescue OpenURI::HTTPError => e
+      response = build_response(e.io)
+    end
+    return response
+  end
+  
+  def build_response(io_object)
+    return {
+      :text => io_object.read.strip,
+      :status => io_object.meta["status"].split[0].strip.to_i,
+      :user => {
+        :limit     => (io_object.meta["x-limit-user-limit"    ] || "-1").to_i,
+        :remaining => (io_object.meta["x-limit-user-remaining"] || "-1").to_i,
+        :reset     => (io_object.meta["x-limit-user-reset"    ] || "-1").to_i
+      },
+      :key => {
+        :limit     => (io_object.meta["x-limit-key-limit"     ] || "-1").to_i,
+        :remaining => (io_object.meta["x-limit-key-remaining" ] || "-1").to_i,
+        :reset     => (io_object.meta["x-limit-key-reset"     ] || "-1").to_i
+      },
+      :error => io_object.meta["x-error"]
+    }    
+  end
+  
+  def stringify_keys(hsh)
+    hsh.map{|k,v|{k.to_sym => (v.class == Hash ? stringify_keys(v) : v)}}.inject(){|a,b|a.merge(b)}
+  end
+  
+end
+
+

data/read_it_later.gemspec

@@ -0,0 +1,50 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{read_it_later}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gabriel Medina"]
+  s.date = %q{2010-02-15}
+  s.description = %q{A very simple one-to-one api library for Read It Later API}
+  s.email = %q{rha7.com@gmail.com}
+  s.extra_rdoc_files = [
+    "README.textile"
+  ]
+  s.files = [
+    ".gitignore",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "config/cucumber.yml",
+     "config/test.yml.dist",
+     "features/read_it_later.feature",
+     "features/read_it_later_users.feature",
+     "features/step_definitions/read_it_later_steps.rb",
+     "features/step_definitions/read_it_later_user_steps.rb",
+     "features/support/env.rb",
+     "lib/read_it_later.rb",
+     "read_it_later.gemspec",
+     "sample_usage.rb"
+  ]
+  s.homepage = %q{http://github.com/rha7dotcom/read_it_later}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{ReadItLaterList.com API Library for Ruby}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/sample_usage.rb

@@ -0,0 +1,64 @@
+#!/usr/local/bin/ruby
+
+require "lib/read_it_later"
+
+ril = ReadItLater.new("<Your ReadItLater API Key Here>")
+usr = ReadItLater::User.new('SomeUserName', 'SomeUserPass')
+
+# Add method
+# ===================================================================================
+# pp ril.add(usr, "http://www.google.com/search?q=add+to+ril")
+
+# Send method
+# ===================================================================================
+# pp ril.send(usr,
+#     :new => [
+#       { :url => "http://www.url1.com/", :title => "URL New 1" },
+#       { :url => "http://www.url2.com/", :title => "URL New 2" },
+#       { :url => "http://www.url3.com/", :title => "URL New 3" }
+#     ],
+#     :read => [
+#         { :url => "http://www.url1.com/" },
+#         { :url => "http://www.url2.com/" },
+#         { :url => "http://www.url3.com/" }
+#     ],
+#     :update_title => [
+#       { :url => "http://www.url1.com/", :title => "Updated URL New 1" },
+#       { :url => "http://www.url2.com/", :title => "Updated URL New 2" },
+#       { :url => "http://www.url3.com/", :title => "Updated URL New 3" }
+#     ],
+#     :update_tags => [
+#       { :url => "http://www.url1.com/", :tags => "url1tag1, url1tag2, url1tag3" },
+#       { :url => "http://www.url2.com/", :tags => "url2tag1, url2tag2, url2tag3" },
+#       { :url => "http://www.url3.com/", :tags => "url3tag1, url3tag2, url3tag3" }
+#     ]
+# )
+
+# Stats method
+# ===================================================================================
+# pp ril.stats(usr)
+
+# Get method
+# ===================================================================================
+# pp ril.get(usr,
+#   :state => :unread, 
+#   :mine_only => false, 
+#   :since => (Time.now-30*24*60*60), 
+#   :count => 10, 
+#   :page => 2, 
+#   :tags => false)
+
+# Auth method
+# ===================================================================================
+# pp ril.auth(usr)
+
+# Sign Up method
+# ===================================================================================
+# pp ril.auth(usr)
+
+# API method
+# ===================================================================================
+# pp ril.api
+
+
+

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: read_it_later
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Gabriel Medina
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-15 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A very simple one-to-one api library for Read It Later API
+email: rha7.com@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- .gitignore
+- README.textile
+- Rakefile
+- VERSION
+- config/cucumber.yml
+- config/test.yml.dist
+- features/read_it_later.feature
+- features/read_it_later_users.feature
+- features/step_definitions/read_it_later_steps.rb
+- features/step_definitions/read_it_later_user_steps.rb
+- features/support/env.rb
+- lib/read_it_later.rb
+- read_it_later.gemspec
+- sample_usage.rb
+has_rdoc: true
+homepage: http://github.com/rha7dotcom/read_it_later
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: ReadItLaterList.com API Library for Ruby
+test_files: []
+