plancast 0.1.1 → 0.1.2

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.
Files changed (3) hide show
  1. data/lib/plancast.rb +1 -5
  2. data/lib/plancast/client.rb +179 -5
  3. metadata +5 -5
@@ -7,7 +7,7 @@ Hash.send :include, Hashie::HashExtensions
7
7
 
8
8
  module Plancast
9
9
 
10
- VERSION = "0.1.1".freeze
10
+ VERSION = "0.1.2".freeze
11
11
 
12
12
  def self.configure
13
13
  yield self
@@ -18,10 +18,6 @@ module Plancast
18
18
  "http://api.plancast.com/#{version}#{endpoint}.json"
19
19
  end
20
20
 
21
- # class << self
22
- # attr_accessor :api_key
23
- # attr_accessor :api_version
24
- # end
25
21
 
26
22
  def self.api_version
27
23
  @api_version || "02"
@@ -6,59 +6,169 @@ module Plancast
6
6
 
7
7
  attr_reader :username
8
8
 
9
+ # Create the API client
10
+ #
11
+ # @param username [String] Plancast username
12
+ # @param password [String] Plancast password
13
+ # @example
14
+ # client = Plancast::Client.new('pengwynn', 'ou812')
9
15
  def initialize(username, password)
10
16
  @username = username
11
17
  self.class.basic_auth username, password
12
18
  end
13
19
 
20
+ # Verify account credentials and gets information about the authenticated user
21
+ # @return [Hashie::Mash] Plancast user info
22
+ # @see http://groups.google.com/group/plancast-api/web/api-method---account-verify-credentials Plancast API docs: verify credentials
14
23
  def verify_credentials
15
24
  self.class.get("/account/verify_credentials.json")
16
25
  end
17
26
 
27
+ # Return information about a given user.
28
+ # @option query [String] :username Username of Plancast user
29
+ # @option query [Integer] :user_id ID of Plancast user
30
+ # @return [Hashie::Mash] Plancast user info
31
+ # @example
32
+ # client.user(:user_id => 1234)
33
+ # @example
34
+ # client.user(:username => 'pengwynn')
35
+ # @see http://groups.google.com/group/plancast-api/web/api-method---users-show Plancast API docs: User show
18
36
  def user(query={})
19
37
  self.class.get("/users/show.json", :query => query)
20
38
  end
21
39
 
40
+ # Return the users to which a given user is subscribed
41
+ #
42
+ # @option query [String] :username Username of Plancast user
43
+ # @option query [Integer] :user_id ID of Plancast user
44
+ # @option query [Integer] :page Page number of results to retrieve
45
+ # @return [Hashie::Mash] Subscriptions info
46
+ # @example
47
+ # subscriptions = client.subscriptions(:user_id => 30).users
48
+ # @see http://groups.google.com/group/plancast-api/web/api-methods---users-subscriptions Plancast API docs: User subscriptions
22
49
  def subscriptions(query={})
23
50
  self.class.get("/users/subscriptions.json", :query => query)
24
51
  end
25
52
 
53
+ # Subscribe the authenticated user to a target user and returns information about the target user. If the target user has enabled account protection, a subscription request will be sent.
54
+ #
55
+ # @option options [String] :username Username of Plancast user
56
+ # @option options [Integer] :user_id ID of Plancast user
57
+ # @return [Hashie::Mash] Subscribed user info
58
+ # @see http://groups.google.com/group/plancast-api/web/api-method---subscriptions-create Plancast API docs: Create subscription
26
59
  def update_subscription(options={})
27
60
  self.class.post("/subscriptions/update.json", :body => options)
28
61
  end
29
62
 
63
+ # Unsubscribe the authenticated user from a target user and returns information about the target user
64
+ #
65
+ # @option options [String] :username Username of Plancast user
66
+ # @option options [Integer] :user_id ID of Plancast user
67
+ # @return [Hashie::Mash] Unubscribed user info
68
+ # @see http://groups.google.com/group/plancast-api/web/api-method---subscriptions-destroy Plancast API docs: Destroy subscription
30
69
  def destroy_subscription(options={})
31
70
  self.class.post("/subscriptions/destroy.json", :body => options)
32
71
  end
33
72
 
73
+ # Return the users who are subscribed to a given user
74
+ #
75
+ # @option query [String] :username Username of Plancast user
76
+ # @option query [Integer] :user_id ID of Plancast user
77
+ # @option query [Integer] :page Page number of results to retrieve
78
+ # @return [Hashie::Mash] Subscribers info
79
+ # @example
80
+ # subscribers = client.subscribers(:user_id => 30).users
81
+ # @see http://groups.google.com/group/plancast-api/web/api-methods---users-subscribers Plancast API docs: User subscribers
34
82
  def subscribers(query={})
35
83
  self.class.get("/users/subscribers.json", :query => query)
36
84
  end
37
85
 
86
+ # Return the users connected to the authenticated user on a given network (Facebook or Twitter)
87
+ #
88
+ # @option query [String] :service Whether to return friends from 'facebook' or 'twitter'
89
+ # @option query [Integer] :page Page number of results to retrieve
90
+ # @return [Hashie::Mash] Friend info
91
+ # @example
92
+ # friends = client.discover_friends(:service => 'twitter').users
93
+ # @see http://groups.google.com/group/plancast-api/web/api-method---users-discover-friends Plancast API docs: Discover friends
38
94
  def discover_friends(query={})
39
95
  self.class.get("/users/discover_friends.json", :query => query)
40
96
  end
41
97
 
98
+ # Return up to 25 users that match the given keyword(s).
99
+ #
100
+ # @param [String] Keyword query
101
+ # @return [Hashie::Mash] User results
102
+ # @example
103
+ # client.search_users('ruby')
104
+ # @see http://groups.google.com/group/plancast-api/web/api-methods---users-search Plancast API docs: Search users
42
105
  def search_users(q, options={})
43
106
  self.class.get("/users/search.json", :query => options.merge({:q => q}))
44
107
  end
45
108
 
109
+ # Return a given user's plans
110
+ #
111
+ # @option query [String] :username Username of Plancast user
112
+ # @option query [Integer] :user_id ID of Plancast user
113
+ # @option query [String] :view_type ("schedule") Optional; The type of plans to return (possible values: schedule, stream, ongoing, past)
114
+ # @option query [Integer] :page (1) Optional: Page number
115
+ # @option query [Integer] :count (25) Optional: (maximum: 100) - Number of plans per page
116
+ # @option query [String] :extensions Optional: (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
117
+ # @return [Hashie::Mash] Plans info
118
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-user-get Plancast API Docs: User plans
119
+ # @example
120
+ # client.plans(:username => 'pengwynn', :count => 20, :page => 3, :extensions => "attendees,comments")
46
121
  def plans(query = {})
47
122
  self.class.get("/plans/user.json", :query => query)
48
123
  end
49
124
 
50
- def home
51
- self.class.get("/plans/home.json")
125
+ # Return plans on the session user's homepage (their own plans plus those of their subscriptions).
126
+ #
127
+ # @option query [String] :view_type ("schedule") Optional; The type of plans to return (possible values: schedule, stream, ongoing, past)
128
+ # @option query [Integer] :page (1) Optional: Page number
129
+ # @option query [Integer] :count (25) Optional: (maximum: 100) - Number of plans per page
130
+ # @option query [String] :extensions Optional: (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
131
+ # @return [Hashie::Mash] Plans info
132
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-home-get Plancast API Docs: User home
133
+ # @example
134
+ # client.home( :count => 20, :page => 3, :extensions => "attendees,comments")
135
+ def home(query = {})
136
+ self.class.get("/plans/home.json", :query => query)
52
137
  end
53
138
 
139
+ # Return the details for a given plan
140
+ #
141
+ # @option query [String] :attendance_id The ID of an attendance, in base 36
142
+ # @option query [String] :plan_id The ID of a plan, in base 36
143
+ # @option query [String] :extensions Optional: (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
144
+ # @return [Hashie::Mash] Plans info
145
+ # @example
146
+ # client.plan(:plan_id => 'enf')
147
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-show Plancast API Docs: Plan show
54
148
  def plan(query = {})
55
149
  self.class.get("/plans/show.json", :query => query)
56
150
  end
57
151
 
58
- def search_plans(query)
152
+ # Return up to 25 plans that match the given keyword(s).
153
+ #
154
+ # @option query [String] :q Keywords to search on
155
+ # @option query [String] :extensions Optional: (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
156
+ # @return [Hashie::Mash] Search results
157
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-search Plancast API docs: Plans search
158
+ # @example
159
+ # client.search_plans(:q => 'ruby')
160
+ def search_plans(query={})
59
161
  self.class.get("/plans/search.json", :query => query)
60
162
  end
61
163
 
164
+ # Parse a string for datetime information and returns the result if successful
165
+ # @param [String] Date/time string to parse
166
+ # @return [Hashie::Mash] Parsed time info
167
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-parse-when Plancast API docs: Parse when
168
+ # @example
169
+ # date_range = client.parse_when("next friday")
170
+ # date_range.start.year
171
+ # # => 2010
62
172
  def parse_when(q)
63
173
  date = self.class.get("/plans/parse_when.json", :query => {:when => q})
64
174
  date.start = Time.at(date.start)
@@ -66,16 +176,58 @@ module Plancast
66
176
  date
67
177
  end
68
178
 
179
+ # Parse a string for location information and returns the result if successful
180
+ # @param [String] Location string to parse
181
+ # @return [Hashie::Mash] Parsed time info
182
+ # @see http://groups.google.com/group/plancast-api/web/api-methods---plans-parse-where Plancast API docs: Parse where
183
+ # @example
184
+ # location = client.parse_where("Sixth Street, Austin, TX")
185
+ # # => [<#Hashie::Mash accuracy=6 address="W 6th St, Austin, Texas, US" id=66569 latitude=30.272467 longitude=-97.756405 maps=<#Hashie::Mash detect="http://plancast.com/uploads/maps/66569_detect.png"> name="W 6th St">]
186
+ # location.latitude
187
+ # # => 30.272467
69
188
  def parse_where(where)
70
189
  locations = self.class.get("/plans/parse_where.json", :query => {:where => where})
71
190
  locations.each{|l| l.latitude = l.latitude.to_f; l.longitude = l.longitude.to_f}
72
191
  locations
73
192
  end
74
193
 
194
+ # Create a new plan or update the details of an existing plan. Returns up-to-date information about the plan in either case.
195
+ #
196
+ # @option details [String] :what - Required - Brief descriptor of the plan
197
+ # @option details [String] :when - Required - String descriptor of plan's date/time, parsed into timestamps for you. You're highly recommended to use plans/parse_when to verify that the string is parseable first
198
+ # @option details [String] :where - Required - String descriptor of the plan's location
199
+ # @option details [String] :place_id - Optional but highly recommended - ID of a canonical place record retrieved using plans/parse_where
200
+ # @option details [String] :external_url - Optional - URL for more information about the plan elsewhere
201
+ # @option details [String] :description - Optional - Longer, more free-form descriptor of the plan
202
+ # @option details [Boolean] :syndicate_facebook - Optional (default: user's default) - Whether to syndicate the plan to Facebook, if authorization is available (only effective for new plans)
203
+ # @option details [Boolean] :syndicate_twitter - Optional (default: user's default) - Whether to syndicate the plan to Twitter, if authorization is available (only effective for new plans)
204
+ # @option details [String] :plan_id or attendance_id - Optional - Base-36 ID of an existing plan or attendance; provide this if you'd like to update a plan instead of creating a new one
205
+ # @return [Hashie::Mash] Plan info
206
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-update Plancast API docs: Update plan
207
+ # @example
208
+ # plan = client.update({
209
+ # :what => "Grabbing some BBQ",
210
+ # :when => "tomorrow night",
211
+ # :where => "Clark's Outpost, Tioga, TX"
212
+ # })
75
213
  def update(details={})
76
214
  self.class.post("/plans/update.json", :body => details)
77
215
  end
78
216
 
217
+ # Add an attendance for a particular plan for the authenticated user and return information about it
218
+ #
219
+ # @option details [Boolean] :syndicate_facebook - Optional (default: user's default) - Whether to syndicate the plan to Facebook, if authorization is available (only effective for new plans)
220
+ # @option details [Boolean] :syndicate_twitter - Optional (default: user's default) - Whether to syndicate the plan to Twitter, if authorization is available (only effective for new plans)
221
+ # @option details [String] :plan_id Base-36 ID of an existing plan
222
+ # @option details [String] :attendance_id - Base-36 ID of an existing attendance
223
+ # @return [Hashie::Mash] Plan info
224
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-attend Plancast API docs: Attend plan
225
+ # @example
226
+ # info = {
227
+ # :attendance_id => 'dho',
228
+ # :syndicate_twitter => false
229
+ # }
230
+ # attendance = client.attend(info)
79
231
  def attend(details={})
80
232
  self.class.post("/plans/attend.json", :body => details)
81
233
  end
@@ -84,22 +236,44 @@ module Plancast
84
236
  self.class.get("/plans/user_timeline.json")
85
237
  end
86
238
 
87
- def unattend(options)
239
+ # Delete an attendance for the authenticated user and returns its previous information
240
+ # @option options [String] :plan_id Base-36 ID of an existing plan
241
+ # @option options [String] :attendance_id - Base-36 ID of an existing attendance
242
+ # @return [Hashie::Mash] Deleted attendance info
243
+ # @see http://groups.google.com/group/plancast-api/web/api-method---plans-destroy Plancast API docs: Plan destroy
244
+ def unattend(options={})
88
245
  self.class.post("/plans/destroy.json", :body => options)
89
246
  end
90
247
 
248
+ # Create a new comment on a plan and return information about it
249
+ #
250
+ # @option details [String] :content Comment content
251
+ # @option details [String] :plan_id Base-36 ID of an existing plan
252
+ # @option details [String] :attendance_id - Base-36 ID of an existing attendance
253
+ # @return [Hashie::Mash] Comment info
254
+ # @see http://groups.google.com/group/plancast-api/web/api-method---comments-create Plancast API docs: Comment create
255
+ # @example
256
+ # comment = client.update_comment(:content => "Hey I'll see you there!", :attendance_id => "2xlm")
91
257
  def update_comment(details={})
92
258
  self.class.post("/comments/update.json", :body => details)
93
259
  end
94
260
 
261
+ # Delete a comment for the authenticated user and return its previous information
262
+ #
263
+ # @param [String] Comment ID
264
+ # @return [Hashie::Mash] Deleted comment info
265
+ # @see http://groups.google.com/group/plancast-api/web/api-method---comments-destroy Plancast API docs: Comment destroy
95
266
  def destroy_comment(comment_id)
96
267
  self.class.post("/comments/destroy.json", :body => {:comment_id => comment_id})
97
268
  end
98
269
 
99
-
270
+
271
+ # @private
100
272
  def self.get(*args); handle_response super end
273
+ # @private
101
274
  def self.post(*args); handle_response super end
102
275
 
276
+ # @private
103
277
  def self.handle_response(response)
104
278
  case response.code
105
279
  when 401; raise Unauthorized.new
metadata CHANGED
@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
5
5
  segments:
6
6
  - 0
7
7
  - 1
8
- - 1
9
- version: 0.1.1
8
+ - 2
9
+ version: 0.1.2
10
10
  platform: ruby
11
11
  authors:
12
12
  - Wynn Netherland
@@ -38,9 +38,9 @@ dependencies:
38
38
  - !ruby/object:Gem::Version
39
39
  segments:
40
40
  - 0
41
- - 1
42
- - 0
43
- version: 0.1.0
41
+ - 5
42
+ - 2
43
+ version: 0.5.2
44
44
  name: httparty
45
45
  prerelease: false
46
46
  requirement: *id002