Class: Plancast::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/plancast/client.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(username, password) ⇒ Client

Create the API client

Examples:

client = Plancast::Client.new('pengwynn', 'ou812')

Parameters:

  • username (String) —

    Plancast username

  • password (String) —

    Plancast password



15
16
17
18
 
# File 'lib/plancast/client.rb', line 15

def initialize(username, password)
  @username = username
  self.class.basic_auth username, password
end

Instance Attribute Details

#username ⇒ Object (readonly)

Returns the value of attribute username.



7
8
9
 
# File 'lib/plancast/client.rb', line 7

def username
  @username
end

Class Method Details

.get(*args) ⇒ Object 



268
 
# File 'lib/plancast/client.rb', line 268

def self.get(*args); handle_response super end

.handle_response(response) ⇒ Object 



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/plancast/client.rb', line 273

def self.handle_response(response)
  case response.code
  when 401; raise Unauthorized.new
  when 403; raise RateLimitExceeded.new
  when 404; raise NotFound.new
  when 400...500; raise ClientError.new
  when 500...600; raise ServerError.new(response.code)
  else; response
  end
  if response.is_a?(Array)
    response.map{|item| Hashie::Mash.new(item)}
  else
    Hashie::Mash.new(response)
  end
end

.post(*args) ⇒ Object 



270
 
# File 'lib/plancast/client.rb', line 270

def self.post(*args); handle_response super end

Instance Method Details

#attend(details = {}) ⇒ Hashie::Mash

Add an attendance for a particular plan for the authenticated user and return information about it

Examples:

info = {
  :attendance_id => 'dho',
  :syndicate_twitter => false
}
attendance = client.attend(info)

Parameters:

  • details (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (details):

  • :syndicate_facebook (Boolean) —

    • Optional (default: user’s default) - Whether to syndicate the plan to Facebook, if authorization is available (only effective for new plans)

  • :syndicate_twitter (Boolean) —

    • Optional (default: user’s default) - Whether to syndicate the plan to Twitter, if authorization is available (only effective for new plans)

  • :plan_id (String) —

    Base-36 ID of an existing plan

  • :attendance_id (String) —

    • Base-36 ID of an existing attendance

Returns:

  • (Hashie::Mash) —

    Plan info

See Also:



231
232
233
 
# File 'lib/plancast/client.rb', line 231

def attend(details={})
  self.class.post("/plans/attend.json", :body => details)
end

#destroy_comment(comment_id) ⇒ Hashie::Mash

Delete a comment for the authenticated user and return its previous information

Parameters:

  • Comment (String) —

    ID

Returns:

  • (Hashie::Mash) —

    Deleted comment info

See Also:



262
263
264
 
# File 'lib/plancast/client.rb', line 262

def destroy_comment(comment_id)
  self.class.post("/comments/destroy.json", :body => {:comment_id => comment_id})
end

#destroy_subscription(options = {}) ⇒ Hashie::Mash

Unsubscribe the authenticated user from a target user and returns information about the target user

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :username (String) —

    Username of Plancast user

  • :user_id (Integer) —

    ID of Plancast user

Returns:

  • (Hashie::Mash) —

    Unubscribed user info

See Also:



69
70
71
 
# File 'lib/plancast/client.rb', line 69

def destroy_subscription(options={})
  self.class.post("/subscriptions/destroy.json", :body => options)
end

#discover_friends(query = {}) ⇒ Hashie::Mash

Return the users connected to the authenticated user on a given network (Facebook or Twitter)

Examples:

friends = client.discover_friends(:service => 'twitter').users

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :service (String) —

    Whether to return friends from ‘facebook’ or ‘twitter’

  • :page (Integer) —

    Page number of results to retrieve

Returns:

  • (Hashie::Mash) —

    Friend info

See Also:



94
95
96
 
# File 'lib/plancast/client.rb', line 94

def discover_friends(query={})
  self.class.get("/users/discover_friends.json", :query => query)
end

#home(query = {}) ⇒ Hashie::Mash

Return plans on the session user’s homepage (their own plans plus those of their subscriptions).

Examples:

client.home( :count => 20, :page => 3, :extensions => "attendees,comments")

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :view_type (String) — default: "schedule" —

    Optional; The type of plans to return (possible values: schedule, stream, ongoing, past)

  • :page (Integer) — default: 1 —

    Optional: Page number

  • :count (Integer) — default: 25 —

    Optional: (maximum: 100) - Number of plans per page

  • :extensions (String) —

    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

Returns:

  • (Hashie::Mash) —

    Plans info

See Also:



135
136
137
 
# File 'lib/plancast/client.rb', line 135

def home(query = {})
  self.class.get("/plans/home.json", :query => query)
end

#parse_when(q) ⇒ Hashie::Mash

Parse a string for datetime information and returns the result if successful

Examples:

date_range = client.parse_when("next friday")
date_range.start.year
# => 2010

Parameters:

  • Date/time (String) —

    string to parse

Returns:

  • (Hashie::Mash) —

    Parsed time info

See Also:



172
173
174
175
176
177
 
# File 'lib/plancast/client.rb', line 172

def parse_when(q)
  date = self.class.get("/plans/parse_when.json", :query => {:when => q})
  date.start = Time.at(date.start)
  date.stop = Time.at(date.stop)
  date
end

#parse_where(where) ⇒ Hashie::Mash

Parse a string for location information and returns the result if successful

Examples:

location = client.parse_where("Sixth Street, Austin, TX")
# => [<#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">]
location.latitude
# => 30.272467

Parameters:

  • Location (String) —

    string to parse

Returns:

  • (Hashie::Mash) —

    Parsed time info

See Also:



188
189
190
191
192
 
# File 'lib/plancast/client.rb', line 188

def parse_where(where)
  locations = self.class.get("/plans/parse_where.json", :query => {:where => where})
  locations.each{|l| l.latitude = l.latitude.to_f; l.longitude = l.longitude.to_f}
  locations
end

#plan(query = {}) ⇒ Hashie::Mash

Return the details for a given plan

Examples:

client.plan(:plan_id => 'enf')

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :attendance_id (String) —

    The ID of an attendance, in base 36

  • :plan_id (String) —

    The ID of a plan, in base 36

  • :extensions (String) —

    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

Returns:

  • (Hashie::Mash) —

    Plans info

See Also:



148
149
150
 
# File 'lib/plancast/client.rb', line 148

def plan(query = {})
  self.class.get("/plans/show.json", :query => query)
end

#plans(query = {}) ⇒ Hashie::Mash

Return a given user’s plans

Examples:

client.plans(:username => 'pengwynn', :count => 20, :page => 3, :extensions => "attendees,comments")

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :username (String) —

    Username of Plancast user

  • :user_id (Integer) —

    ID of Plancast user

  • :view_type (String) — default: "schedule" —

    Optional; The type of plans to return (possible values: schedule, stream, ongoing, past)

  • :page (Integer) — default: 1 —

    Optional: Page number

  • :count (Integer) — default: 25 —

    Optional: (maximum: 100) - Number of plans per page

  • :extensions (String) —

    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

Returns:

  • (Hashie::Mash) —

    Plans info

See Also:



121
122
123
 
# File 'lib/plancast/client.rb', line 121

def plans(query = {})
  self.class.get("/plans/user.json", :query => query)
end

#search_plans(query = {}) ⇒ Hashie::Mash

Return up to 25 plans that match the given keyword(s).

Examples:

client.search_plans(:q => 'ruby')

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :q (String) —

    Keywords to search on

  • :extensions (String) —

    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

Returns:

  • (Hashie::Mash) —

    Search results

See Also:



160
161
162
 
# File 'lib/plancast/client.rb', line 160

def search_plans(query={})
  self.class.get("/plans/search.json", :query => query)
end

#search_users(q, options = {}) ⇒ Hashie::Mash

Return up to 25 users that match the given keyword(s).

Examples:

client.search_users('ruby')

Parameters:

  • Keyword (String) —

    query

Returns:

  • (Hashie::Mash) —

    User results

See Also:



105
106
107
 
# File 'lib/plancast/client.rb', line 105

def search_users(q, options={})
  self.class.get("/users/search.json", :query => options.merge({:q => q}))
end

#subscribers(query = {}) ⇒ Hashie::Mash

Return the users who are subscribed to a given user

Examples:

subscribers = client.subscribers(:user_id => 30).users

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :username (String) —

    Username of Plancast user

  • :user_id (Integer) —

    ID of Plancast user

  • :page (Integer) —

    Page number of results to retrieve

Returns:

  • (Hashie::Mash) —

    Subscribers info

See Also:



82
83
84
 
# File 'lib/plancast/client.rb', line 82

def subscribers(query={})
  self.class.get("/users/subscribers.json", :query => query)
end

#subscriptions(query = {}) ⇒ Hashie::Mash

Return the users to which a given user is subscribed

Examples:

subscriptions = client.subscriptions(:user_id => 30).users

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :username (String) —

    Username of Plancast user

  • :user_id (Integer) —

    ID of Plancast user

  • :page (Integer) —

    Page number of results to retrieve

Returns:

  • (Hashie::Mash) —

    Subscriptions info

See Also:



49
50
51
 
# File 'lib/plancast/client.rb', line 49

def subscriptions(query={})
  self.class.get("/users/subscriptions.json", :query => query)
end

#unattend(options = {}) ⇒ Hashie::Mash

Delete an attendance for the authenticated user and returns its previous information

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :plan_id (String) —

    Base-36 ID of an existing plan

  • :attendance_id (String) —

    • Base-36 ID of an existing attendance

Returns:

  • (Hashie::Mash) —

    Deleted attendance info

See Also:



240
241
242
 
# File 'lib/plancast/client.rb', line 240

def unattend(options={})
 self.class.post("/plans/destroy.json", :body => options)
end

#update(details = {}) ⇒ Hashie::Mash

Create a new plan or update the details of an existing plan. Returns up-to-date information about the plan in either case.

Examples:

plan = client.update({
  :what => "Grabbing some BBQ",
  :when => "tomorrow night",
  :where => "Clark's Outpost, Tioga, TX"
})

Parameters:

  • details (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (details):

  • :what (String) —

    • Required - Brief descriptor of the plan

  • :when (String) —

    • 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

  • :where (String) —

    • Required - String descriptor of the plan’s location

  • :place_id (String) —

    • Optional but highly recommended - ID of a canonical place record retrieved using plans/parse_where

  • :external_url (String) —

    • Optional - URL for more information about the plan elsewhere

  • :description (String) —

    • Optional - Longer, more free-form descriptor of the plan

  • :syndicate_facebook (Boolean) —

    • Optional (default: user’s default) - Whether to syndicate the plan to Facebook, if authorization is available (only effective for new plans)

  • :syndicate_twitter (Boolean) —

    • Optional (default: user’s default) - Whether to syndicate the plan to Twitter, if authorization is available (only effective for new plans)

  • :plan_id (String) —

    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

Returns:

  • (Hashie::Mash) —

    Plan info

See Also:



213
214
215
 
# File 'lib/plancast/client.rb', line 213

def update(details={})
  self.class.post("/plans/update.json", :body => details)
end

#update_comment(details = {}) ⇒ Hashie::Mash

Create a new comment on a plan and return information about it

Examples:

comment = client.update_comment(:content => "Hey I'll see you there!", :attendance_id => "2xlm")

Parameters:

  • details (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (details):

  • :content (String) —

    Comment content

  • :plan_id (String) —

    Base-36 ID of an existing plan

  • :attendance_id (String) —

    • Base-36 ID of an existing attendance

Returns:

  • (Hashie::Mash) —

    Comment info

See Also:



253
254
255
 
# File 'lib/plancast/client.rb', line 253

def update_comment(details={})
  self.class.post("/comments/update.json", :body => details)
end

#update_subscription(options = {}) ⇒ Hashie::Mash

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.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :username (String) —

    Username of Plancast user

  • :user_id (Integer) —

    ID of Plancast user

Returns:

  • (Hashie::Mash) —

    Subscribed user info

See Also:



59
60
61
 
# File 'lib/plancast/client.rb', line 59

def update_subscription(options={})
  self.class.post("/subscriptions/update.json", :body => options)
end

#user(query = {}) ⇒ Hashie::Mash

Return information about a given user.

Examples:

client.user(:user_id => 1234)
client.user(:username => 'pengwynn')

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :username (String) —

    Username of Plancast user

  • :user_id (Integer) —

    ID of Plancast user

Returns:

  • (Hashie::Mash) —

    Plancast user info

See Also:



36
37
38
 
# File 'lib/plancast/client.rb', line 36

def user(query={})
  self.class.get("/users/show.json", :query => query)
end

#verify_credentials ⇒ Hashie::Mash

Verify account credentials and gets information about the authenticated user

Returns:

  • (Hashie::Mash) —

    Plancast user info

See Also:



23
24
25
 
# File 'lib/plancast/client.rb', line 23

def verify_credentials
  self.class.get("/account/verify_credentials.json")
end