read_it_later 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/.gitignore CHANGED
@@ -1 +1,2 @@
1
1
  config/test.yml
2
+ read_it_later-*.gem
data/README.textile CHANGED
@@ -1,16 +1,5 @@
1
1
  h1. ReadItLater API Library for Ruby
2
2
 
3
- p. Please see sample_usage.rb for examples of use.
4
-
5
- p. For details on the ReadItLater API see http://readitlaterlist.com/api/docs/
6
-
7
- p. For details on what is ReadItLater see http://readitlaterlist.com/
8
-
9
- p. NEW: Has been deployed to gemcutter as a gem, you can install it like this:
10
-
11
- <pre><code>sudo gem install read_it_later</code></pre>
12
-
13
- p. And that's it, then just require it from you Ruby programs.
14
-
15
-
3
+ p. This is an implementation of the API for the Firefox extension "Read It Later":http://readitlaterlist.com
16
4
 
5
+ p. See the "Wiki":http://wiki.github.com/rha7dotcom/read_it_later/
data/VERSION CHANGED
@@ -1 +1 @@
1
- 0.2.2
1
+ 0.2.3
data/lib/read_it_later.rb CHANGED
@@ -1,15 +1,45 @@
1
+ # The ReadItLater class is a Ruby implementation
2
+ # of the API provided by readitlaterlist.com
3
+ # It's pretty much a one-to-one method-by-method
4
+ # implementation in ruby.
5
+
6
+ # Author:: Gabriel Medina (mailto:rha7.com@gmail.com)
7
+ # Copyright:: Copyright (c) 2010 Gabriel Medina
8
+ # License:: LGPL
9
+
1
10
  require 'open-uri'
2
11
  require 'json'
3
12
 
13
+ # This is the main class for the ReadItLater library,
14
+ # it allows you to interact with the service.
15
+ # Typical usage is as follows:
16
+ #
17
+ # usr = ReadItLater::User.new('username', 'password')
18
+ # ril = ReadItLater.new('YOUR API KEY HERE')
19
+ # res = ril.add(usr, 'http://www.google.com/') # { :status => 200, :text => "200 OK", ... }
20
+ #
4
21
  class ReadItLater
5
22
 
23
+ # For responses status code indicating success.
6
24
  STATUS_SUCCESS = 200
25
+
26
+ # For responses status code indicating invalid request (wrong arguments).
7
27
  STATUS_INVALID = 400
28
+
29
+ # For responses status code indicating denied access (usually, login/pass wrong).
8
30
  STATUS_DENIED = 401
31
+
32
+ # For responses status code indicating access rate exceeded, wait a few minutes before trying again,
33
+ # or issue a 'stat' or 'api' method calls to see more details.
9
34
  STATUS_EXCEEDED = 403
35
+
36
+ # For responses status code indicating the service is down for maintenance.
10
37
  STATUS_MAINTENANCE = 503
11
38
 
39
+ # The readitlaterlist.com base URL for requests via http.
12
40
  URL_BASE = 'https://readitlaterlist.com/v2'
41
+
42
+ # The specific URLs for methods, with http base URL_BASE
13
43
  URLS = {
14
44
  :add => ReadItLater::URL_BASE+'/add' ,
15
45
  :send => ReadItLater::URL_BASE+'/send' ,
@@ -20,25 +50,95 @@ class ReadItLater
20
50
  :api => ReadItLater::URL_BASE+'/api'
21
51
  }
22
52
 
53
+ # Holds the response to the last request/method call.
23
54
  attr_reader :last_response
24
55
 
56
+ # Inner class to ReadItLater to hold user details
25
57
  class User
26
- attr_accessor :username, :password
58
+
59
+ # User name for User object
60
+ attr_accessor :username
61
+
62
+ # Password for User object
63
+ attr_accessor :password
64
+
65
+ # Create a new ReadItLater::User object, to be used in subsequent calls.
66
+ #
67
+ # @param [String] username The user name for this instance
68
+ # @param [String] password The password for this instance
27
69
  def initialize(username=nil, password=nil)
28
70
  @username, @password, @last_response = username, password, ""
29
71
  end
30
72
  end
31
73
 
74
+ # Holds the api_key assigned to this ReadItLater instance
32
75
  attr_accessor :api_key
33
76
 
77
+ # Holds the last response received from Read It Later API
78
+ # The response is similar to the following, although it may vary:
79
+ #
80
+ # {:status=>200,
81
+ # :key=>{:limit=>1000, :remaining=>996, :reset=>3556},
82
+ # :text=>"200 OK",
83
+ # :error=>nil,
84
+ # :user=>{:limit=>120, :remaining=>113, :reset=>3556}}
85
+ #
86
+ # Some method calls may return additional information in a :data key in the response Hash
87
+ #
88
+ # @param [Integer] status is a numeric code corresponding to the STATUS_* constants.
89
+ # @param [String] text is the text as received from the server.
90
+ # @param [String] error is the error message sent from the server (if there was an error, nil otherwise).
91
+ # @param [Hash] key contains the limit of requests this API key can make per hour, remaining calls and seconds until counters reset.
92
+ # @param [Hash] user contains the limit of requests this user can make per hour, remaining calls and seconds until counters reset.
93
+ #
94
+ attr_accessor :last_response
95
+
96
+ # Create a new ReadItLater instance
97
+ #
98
+ # @param [String] api_key Must be the API key generated from the readitlaterlist.com
34
99
  def initialize(api_key)
35
100
  @api_key = api_key
36
101
  end
37
102
 
103
+ # Add a new URL to a User bookmarks list
104
+ #
105
+ # @param [ReadItLater::User] user The ReadItLater::User instance representing the user
106
+ # @param [String] url The URL string to be added to the bookmark list
107
+ # @return [Hash] See @last_response.
38
108
  def add(user, url)
39
109
  @last_response = query(:add, user, :url => url)
40
110
  end
41
111
 
112
+ # Send several changes to readitlaterlist.com
113
+ # The params hash is built as described in http://readitlaterlist.com/api/docs/#send, but in ruby a Ruby Hash.
114
+ # Example:
115
+ #
116
+ # params = {
117
+ # :new => [
118
+ # { :url => "http://www.url1.com/", :title => "URL New 1" },
119
+ # { :url => "http://www.url2.com/", :title => "URL New 2" },
120
+ # { :url => "http://www.url3.com/", :title => "URL New 3" }
121
+ # ],
122
+ # :read => [
123
+ # { :url => "http://www.url1.com/" },
124
+ # { :url => "http://www.url2.com/" },
125
+ # { :url => "http://www.url3.com/" }
126
+ # ],
127
+ # :update_title => [
128
+ # { :url => "http://www.url1.com/", :title => "Updated URL New 1" },
129
+ # { :url => "http://www.url2.com/", :title => "Updated URL New 2" },
130
+ # { :url => "http://www.url3.com/", :title => "Updated URL New 3" }
131
+ # ],
132
+ # :update_tags => [
133
+ # { :url => "http://www.url1.com/", :tags => "url1tag1, url1tag2, url1tag3" },
134
+ # { :url => "http://www.url2.com/", :tags => "url2tag1, url2tag2, url2tag3" },
135
+ # { :url => "http://www.url3.com/", :tags => "url3tag1, url3tag2, url3tag3" }
136
+ # ]
137
+ # }
138
+ #
139
+ # @param [ReadItLater::User] user The ReadItLater::User instance representing the user
140
+ # @param [Hash] params The changes to be sent as described in http://readitlaterlist.com/api/docs/#send, in Ruby hash format
141
+ # @return [Hash] See @last_response.
42
142
  def send(user, params)
43
143
  %w(new read update_title update_tags).map(&:to_sym).each do |param|
44
144
  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]
@@ -46,6 +146,18 @@ class ReadItLater
46
146
  @last_response = query(:send, user, params)
47
147
  end
48
148
 
149
+
150
+ # Returns statistics on usage of bookmarks, number of bookmarks added, etc.
151
+ # Response Hash contains additionaly a :data key as follows:
152
+ #
153
+ # :data=>
154
+ # {:user_since=>Wed Aug 27 00:16:27 -0600 2008,
155
+ # :count_unread=>"221",
156
+ # :count_list=>"389",
157
+ # :count_read=>"168"},
158
+ #
159
+ # @param [ReadItLater::User] user The ReadItLater::User instance representing the user
160
+ # @return [Hash] See @last_response.
49
161
  def stats(user)
50
162
  response = query(:stats, user, :format => "json")
51
163
  response[:data] = stringify_keys(JSON.parse(response[:text]))
@@ -53,6 +165,18 @@ class ReadItLater
53
165
  @last_response = response
54
166
  end
55
167
 
168
+ # Gets a list of bookmarks according to call parameters.
169
+ # The call_params parameter may contain selected options as keys in a Hash as follows:
170
+ # :state => :read | :unread # Get read/unread only bookmarks, all if not specified.
171
+ # :mine_only => Boolean # Get bookmarks added by this app only if true, false/nil return everything
172
+ # :since => Date # Get bookmarks added after this date, or all if not specified.
173
+ # :count => Integer # Get this number of bookmarks at most, all of not specified.
174
+ # :page => Integer # Get this page of results for paginated requests (used with :count). All/First if not specified.
175
+ # :tags => Boolean # Get only bookmarks with tags, if true, only without tags if false, all if not specified.
176
+ #
177
+ # @param [ReadItLater::User] user The ReadItLater::User instance representing the user
178
+ # @param [Hash] call_params The specifics of the data to be retrieved.
179
+ # @return [Hash] See @last_response.
56
180
  def get(user, call_params)
57
181
  params = { :format => "json" }
58
182
  params[:state] = call_params[:state].to_s.strip if call_params[:state]
@@ -68,15 +192,26 @@ class ReadItLater
68
192
  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}}
69
193
  @last_response = response
70
194
  end
71
-
195
+
196
+ # Authenticate a user.
197
+ #
198
+ # @param [ReadItLater::User] user User to authenticate.
199
+ # @return [Hash] See @last_response.
72
200
  def auth(user)
73
201
  @last_reponse = query(:auth, user)
74
202
  end
75
203
 
204
+ # Sign up a new user.
205
+ #
206
+ # @param [ReadItLater::User] user User to sign up.
207
+ # @return [Hash] See @last_response.
76
208
  def signup(user)
77
209
  @last_reponse = query(:signup, user)
78
210
  end
79
211
 
212
+ # API Key usage information.
213
+ #
214
+ # @return [Hash] See @last_response.
80
215
  def api
81
216
  @last_response = query(:api, User.new('',''))
82
217
  end
@@ -5,11 +5,11 @@
5
5
 
6
6
  Gem::Specification.new do |s|
7
7
  s.name = %q{read_it_later}
8
- s.version = "0.2.2"
8
+ s.version = "0.2.3"
9
9
 
10
10
  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
11
  s.authors = ["Gabriel Medina"]
12
- s.date = %q{2010-02-15}
12
+ s.date = %q{2010-02-18}
13
13
  s.description = %q{A very simple one-to-one api library for Read It Later API}
14
14
  s.email = %q{rha7.com@gmail.com}
15
15
  s.extra_rdoc_files = [
@@ -28,9 +28,6 @@ Gem::Specification.new do |s|
28
28
  "features/step_definitions/read_it_later_user_steps.rb",
29
29
  "features/support/env.rb",
30
30
  "lib/read_it_later.rb",
31
- "pkg/read_it_later-0.2.1.gem",
32
- "read_it_later-0.2.0.gem",
33
- "read_it_later-0.2.1.gem",
34
31
  "read_it_later.gemspec",
35
32
  "sample_usage.rb"
36
33
  ]
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: read_it_later
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.2
4
+ version: 0.2.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Gabriel Medina
@@ -9,7 +9,7 @@ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
11
 
12
- date: 2010-02-15 00:00:00 -07:00
12
+ date: 2010-02-18 00:00:00 -07:00
13
13
  default_executable:
14
14
  dependencies:
15
15
  - !ruby/object:Gem::Dependency
@@ -43,9 +43,6 @@ files:
43
43
  - features/step_definitions/read_it_later_user_steps.rb
44
44
  - features/support/env.rb
45
45
  - lib/read_it_later.rb
46
- - pkg/read_it_later-0.2.1.gem
47
- - read_it_later-0.2.0.gem
48
- - read_it_later-0.2.1.gem
49
46
  - read_it_later.gemspec
50
47
  - sample_usage.rb
51
48
  has_rdoc: true
Binary file
Binary file
Binary file