upcoming-events 0.0.1

data/lib/upcoming/group.rb

@@ -0,0 +1,224 @@
+module Upcoming
+  class Group
+    include Upcoming::Defaults
+    
+    # Retrieve group information and metadata for public and private groups.
+    #
+    # +group_id+ (Required)
+    # The id number of the group. You can also pass multiple group_id's separated by commas to getInfo on multiple groups.
+    # 
+    # +token+ (Optional)
+    # An authentication token. Pass to see even private groups.
+    #
+    def self.info(group_id, token=nil)
+      group_id = group_id.join(',') if group_id.is_a?(Array)
+      token = token['token'] if token and token['token']
+      query = {:method => 'group.getInfo', :group_id => group_id}
+      query.merge!(:token => token) if token
+      Mash.new(self.get('/', :query => query.merge(Upcoming.default_options))).rsp.group
+    end
+    
+    # Retrieve group member user information and metadata for any public group or private group that the authenticated user is a member of.
+    # 
+    # +token+ (Required)
+    # An authentication token.
+    # 
+    # +group_id+ (Numeric, Required)
+    # The group id requested.
+    # 
+    # +members_per_page+ (Numeric, Optional)
+    # To restrict the number of members per page of results. Default is 100.
+    # 
+    # +page+ (Numeric, Optional)
+    # Page # to return. Starts with 1.
+    # 
+    # +order+ (Either 'member_timestamp' or 'username', default: 'username')
+    # Member_timestamp orders by date joined.
+    # 
+    # +dir+ (Either 'asc' or 'desc', default: asc)
+    # Sort direction.
+    #
+    def self.members(group_id, token, options={})
+      opts = {:membersPerPage => 100, :page => 1, :order => 'username', :dir => 'asc'}
+      opts.merge! options
+      opts[:membersPerPage] = opts.delete(:members_per_page) if opts[:members_per_page]
+      token = token['token'] if token and token['token']
+      query = {:method => 'group.getMembers', :group_id => group_id, :token => token}
+      Mash.new(self.get('/', :query => query.merge(opts).merge(Upcoming.default_options))).rsp.user
+    end
+    
+    # Retrieve group event information and metadata for any public group or private group that the authenticated user is a member of.
+    # 
+    # +token+ (Optional)
+    # An authentication token. 
+    # 
+    # +group_id+ (Numeric, Required)
+    # The group id requested.
+    # 
+    # +events_per_page+ (Numeric, Optional)
+    # To restrict the number of members per page of results.
+    # 
+    # +page+ (Numeric, Optional)
+    # Page # to return. Starts with 1.
+    # 
+    # +order+ (Either 'event_time' or 'time_added', default: 'event_time')
+    # Event_time orders by event start date, time_added orders by the time the event was added to the group.
+    # 
+    # +dir+ (Either 'asc' or 'desc', default: asc)
+    # Sort direction.
+    # 
+    # +show_past+ (Either 1 or 0, default: 0)
+    # Whether to exclusively show past results (instead of upcoming) in the event results.
+    def self.events(group_id, token, options={})
+      opts = {:eventsPerPage => 100, :page => 1, :order => 'event_time', :dir => 'asc', :show_past => 0}
+      opts.merge! options
+      opts[:eventsPerPage] = opts.delete(:events_per_page) if opts[:events_per_page]
+      token = token['token'] if token and token['token']
+      query = {:method => 'group.getEvents', :group_id => group_id, :token => token}
+      Mash.new(self.get('/', :query => query.merge(opts).merge(Upcoming.default_options))).rsp.event
+    end
+    
+    # Retrieve group information and metadata for all groups that the authenticated user is a member of. This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token.
+    def self.my_groups(token)
+      Mash.new(self.get('/', :query => {:method => 'getMyGroups', :token => token}.merge(Upcoming.default_options))).rsp.event
+    end
+    
+    # Add a new group to the database. This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +name+ (Required)
+    # The name of the group.
+    # 
+    # +description+ (Optional)
+    # The group's description. May contain some HTML.
+    # 
+    # +event_moderation+ (Numeric, either 1 or 0)
+    # Whether to enable moderation of event suggestions. Default is 0.
+    # 
+    # +member_moderation+ (Numeric, either 1 or 0)
+    # Whether to enable moderation of new members. Default is 0.
+    # 
+    # +is_private+ (Number, 1 or 0)
+    # Indicates whether it should be a private, invite-only group(1), or available for public view and searching (0).
+    def self.add(info, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'group.add', :token => token}
+      body.merge!(info)
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.group
+    end
+    
+    # Edit a group. Only an admin of a group may edit it.This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +group_id+ (Numeric, Required)
+    # The id of the group to edit.
+    # 
+    # +name+ (Required)
+    # The name of the group.
+    # 
+    # +description+ (Optional)
+    # The group's description. May contain some HTML.
+    # 
+    # +event_moderation+ (Numeric, either 1 or 0)
+    # Whether to enable moderation of event suggestions. Default is 0.
+    # 
+    # +member_moderation+ (Numeric, either 1 or 0)
+    # Whether to enable moderation of new members. Default is 0.
+    # 
+    # +is_private+ (Number, 1 or 0)
+    # Indicates whether it should be a private, invite-only group(1), or available for public view and searching (0).
+    # 
+    def self.edit(group, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'group.edit', :token => token}
+      body.merge!(info)
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.group
+    end
+    
+    # Try to join a group. If the group is moderated, the request may be queued for administrator review instead of processed immediately. This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +group_id+ (Required)
+    # The id of the group to join.
+    def self.join(group_id, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'group.join', :group_id => group_id,  :token => token}
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.group
+    end
+    
+    # Try to leave a group. If the user leaving was the last member of the group, the group is permanently deleted, and may not be rejoined. If the user who left was the last admin in the group, the user remaining with the earliest join timestamp becomes an admin. This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +group_id+ (Required)
+    # The id of the group to leave.
+    def self.leave(group_id, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'group.leave', :group_id => group_id,  :token => token}
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.stat == 'ok'
+    end
+    
+    # Try to add an event to a group. If the group is moderated, the request may be queued for administrator review instead of processed immediately.This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +group_id+ (Required)
+    # The id of the group.
+    # 
+    # +event_id+ (Required)
+    # The id of the event to send.
+    #
+    def self.add_event(group_id, event_id, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'group.addEventTo', :group_id => group_id,  :event_id => event_id, :token => token}
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.group
+    end
+    
+    # Try to remove an event to a group. This method can only be called by an authenticated group admin, or by the user who added the event to the group. This method requires authentication.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +group_id+ (Required)
+    # The id of the group.
+    # 
+    # +event_id+ (Required)
+    # The id of the event to remove.
+    #
+    def self.remove_event(group_id, event_id, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'group.removeEvent', :group_id => group_id, :event_id => event, :token => token}
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.stat == 'ok'
+    end
+    
+  end
+end

data/lib/upcoming/metro.rb

@@ -0,0 +1,78 @@
+module Upcoming
+  class Metro
+    include Upcoming::Defaults
+    
+    # Retrieve the details about a metro.
+    # 
+    # +metro_id+ (Required)
+    # The metro_id number of the metro to look within. To find metro_id's, use metro.getList. To run getInfo on multiple metros, simply pass a comma-separated list of metro_id numbers.
+    #
+    def self.info(metro_id)
+      metro_id = metro_id.join(',') if metro_id.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'metro.getInfo', :metro_id => metro_id}.merge(Upcoming.default_options))).rsp.metro
+    end
+    
+    # Retrieve the single record of the most popular metro in the area of a latitude and longitude coordinate. Will return a 404 Not Found if one cannot be found. Only the US and some of Canada is currently supported. To get a Lat/Lon from a street address, try Yahoo!'s Geocoding API. Useful for adding new venues.
+    # 
+    # +latitude+ (Float, Required)
+    # Latitude coordinate.
+    # 
+    # +longitude+ (Float, Required)
+    # Longitude coordinate.
+    #
+    def self.for_latitude_and_longitude(latitude, longitude)
+      Mash.new(self.get('/', :query => {:method => 'metro.getForLatLon', :latitude => latitude, :longitude => longitude}.merge(Upcoming.default_options))).rsp.metro
+    end
+    
+    # Searches for metros whose name or "code" matches the search_text.
+    #
+    # +search_text+ (Optional)
+    # The search text to use. Supports quoted strings and empty parameter (to display all). Please restrict by another parameter when using blank values.
+    # 
+    # +country_id+ (Numeric, Optional)
+    # The country_id of the event, used to narrow down the responses. To get a country_id, try the metro.getCountryList function.
+    # 
+    # +state_id+ (Numeric, Optional)
+    # The state_id of the event, used to narrow down the responses. To get a state_id, try the metro.getStateList function.
+    #
+    def self.search(query={})
+      Mash.new(self.get('/', :query => query.merge({:method => 'metro.search'}).merge(Upcoming.default_options))).rsp.metro
+    end
+    
+    # Retrieve a list of metros for a particular state.
+    #
+    # +token+ (Required)
+    # An authentication token.
+    #
+    def self.my_list(token)
+      token = Upcoming::Auth.token_code(token)
+      Mash.new(self.get('/', :query => {:method => 'metro.getMyList', :token => token}.merge(Upcoming.default_options))).rsp.metro
+    end
+    
+    # Retrieve a list of metros for a particular state.
+    # 
+    # +state_id+ (Required)
+    # The state_id number of the state to look within. To find state_id's, use metro.getStateList.
+    #
+    def self.list(state_id)
+      state_id = state_id.join(',') if state_id.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'metro.getList', :state_id => state_id}.merge(Upcoming.default_options))).rsp.metro
+    end
+    
+    # Retrieve a list of states for a particular country.
+    # 
+    # +country_id+ (Required)
+    # The country_id number of the country to look within. To find country_id's, use metro.getCountryList.
+    #
+    def self.state_list(country_id)
+      country_id = country_id.join(',') if country_id.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'metro.getStateList', :country_id => country_id}.merge(Upcoming.default_options))).rsp.state
+    end
+    
+    # Retrieve a list of all countries in the database.
+    #
+    def self.country_list
+      Mash.new(self.get('/', :query => {:method => 'metro.getCountryList'}.merge(Upcoming.default_options))).rsp.country
+    end    
+  end
+end

data/lib/upcoming/state.rb

@@ -0,0 +1,13 @@
+module Upcoming
+  class State
+    include Upcoming::Defaults
+    
+    # +state_id+ (Required)
+    # The state_id number of the state to look within. State ID's are referenced in other methods, such as metro.getStateList and metro.getInfo. To run getInfo on multiple states, simply pass an array or a comma-separated list of state_id numbers.
+    #
+    def self.info(state_id)
+      state_id = state_id.join(',') if state_id.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'state.getInfo', :state_id => state_id}.merge(Upcoming.default_options))).rsp.state
+    end
+  end
+end

data/lib/upcoming/user.rb

@@ -0,0 +1,83 @@
+module Upcoming
+  class User
+    include Upcoming::Defaults
+    
+    # Retrieve the details about a user.
+    # 
+    # +user_id+ (Required)
+    # The user_id number of the user to look within. To run getInfo on multiple users, simply pass a comma-separated list of user_id numbers.
+    # 
+    def self.info(user_id)
+      user_id = user_id.join(',') if user_id.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'user.getInfo', :user_id => user_id}.merge(Upcoming.default_options))).rsp.user
+    end
+    
+    # Retrieve the details about a user by username/screenname.
+    # 
+    # +username+ (Required)
+    # The username (or screen name) of the user to look within. To run getInfoByUsername on multiple users, simply pass a comma-separated list of username strings.
+    # 
+    def self.info_by_username(username)
+      username = username.join(',') if username.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'user.getInfoByUsername', :username => username}.merge(Upcoming.default_options))).rsp.user
+    end
+    
+    # Retrieve the details about a user by email
+    # 
+    # +email+ (Required)
+    # The email of the user to look within. To run getInfoByEmail on multiple addresses, simply pass a comma-separated list of valid email addresses.
+    # 
+    def self.info_by_email(email)
+      email = email.join(',') if email.is_a?(Array)
+      Mash.new(self.get('/', :query => {:method => 'user.getInfoByEmail', :email => email}.merge(Upcoming.default_options))).rsp.user
+    end
+    
+    # Retrieve a list of metros for a particular user.
+    # 
+    # +token+ (Required)
+    # An authentication token.
+    def self.metro_list(token)
+      token = Upcoming::Auth.token_code(token)
+      Mash.new(self.get('/', :query => {:method => 'user.getMetroList', :token => token}.merge(Upcoming.default_options))).rsp.metro
+    end
+    
+    # Gets all events in the watchlist for a user. You may optionally pass authentication parameters for this function to get back private events from people who have authenticated user as a friend. The 'username' returned is the username of the watchlist owner. It also returns either status="attend" or status="watch". Watchlists for personal events that are created by friends of the user authenticated are shown.
+    # 
+    # In other words, you pass a username and password. Naturally, you'll have access to see any events created by others who have you as a friend. If the user_id you query has any of those specific personal events as an item in their watchlist, they will show up in this function.
+    # 
+    # Additionally, by default, user.getWatchlist only returns events with a start date >= today, or upcoming events. To get all events ever in a user's watchlist, or to get past events only, pass the "show" parameter.
+    # 
+    # +token+ (Optional)
+    # An authentication token. 
+    # 
+    # +user_id+ (Required)
+    # The user_id requested.
+    # 
+    # +show+ (Optional, Default: 'upcoming')
+    # May be 'upcoming', 'all', or 'past' to retrieve corresponding events.
+    #
+    def self.watchlist(user_id, show='upcoming', token=nil)
+      token = Upcoming::Auth.token_code(token)
+      query = {:method => 'user.getWatchlist', :show => show}
+      query.merge!(:token => token) if token
+      Mash.new(self.get('/', :query => query.merge(Upcoming.default_options))).rsp.event
+    end
+    
+    # Retrieve the events being watched/attended by a user's friends. These events can either be public or created by a person who calls the user a friend.
+    # 
+    # +token+ (Required)
+    # An authentication token required to see the user's friends events. 
+    # 
+    # +per_page+ (Numeric, Optional, Default = 100)
+    # Number of results to return per page. Max is 100 per page.
+    # 
+    # +page+ (Numeric, Optional, Default = 1)
+    # The page number of results to return.
+    def self.friends_events(token, per_page=100, page=1)
+      token = Upcoming::Auth.token_code(token)
+      query = {:method => 'user.getMyFriendsEvents', :per_page => per_page, :page => page}
+      Mash.new(self.get('/', :query => query.merge(Upcoming.default_options))).rsp.event
+    end
+      
+  end
+end

data/lib/upcoming/venue.rb

@@ -0,0 +1,170 @@
+module Upcoming
+  class Venue
+    include Upcoming::Defaults
+    
+    # Retrieve the details about a venue.
+    #
+    # venue_id (Required)
+    # The venue_id number of the venue to look within. To find venue_id's, use venue.getList. You can also pass multiple venue_id's separated by commas to getInfo on multiple venues.
+    # 
+    # token (Optional)
+    # An authentication token. Optional for viewing private venues. 
+    # 
+    def self.info(venue_id, token=nil)
+      venue_id = venue_id.join(',') if venue_id.is_a?(Array)
+      token = token['token'] if token and token['token']
+      query = {:method => 'venue.getInfo', :venue_id => venue_id}
+      query.merge!({:token => token}) if token
+      Mash.new(self.get('/', :query => query.merge(Upcoming.default_options))).rsp.venue
+    end
+    
+    # Retrieve a list of venues for a particular metro.
+    # 
+    # metro_id (Required)
+    # The metro_id number of the metro to look within. To find metro_id's, use metro.getList.
+    # 
+    # token (Optional)
+    # An authentication token. Pass to return private venues.
+    #
+    def self.list(metro_id, token=nil)
+      metro_id = metro_id.join(',') if metro_id.is_a?(Array)
+      token = token['token'] if token and token['token']
+      query = {:method => 'venue.getList', :metro_id => metro_id}
+      query.merge!({:token => token}) if token
+      Mash.new(self.get('/', :query => query.merge(Upcoming.default_options))).rsp.venue
+    end
+    
+    # Allows searching through venues.
+    # 
+    # +search_text+ (Optional)
+    # The search string to use when looking for venues. Supports quoted phrases and blank values for searching all venues. Please restrict by another parameter when using blank values.
+    # 
+    # +location+ (Optional)
+    # Only for use in proximity search within the US, the location parameter, if provided, will attempt to restrict search results to areas near that location. This may either be formatted as a comma-separated latitude and longitude (i.e. "37.821, -111.179"), or a fulltext location similar to the following:
+    # 
+    #     * City, State
+    #     * City, State, Zip
+    #     * Zip
+    #     * Street, City, State
+    #     * Street, City, State, Zip
+    #     * Street, Zip
+    # 
+    # Any search that uses the location parameter will add the additional data elements "distance" and "distance_units" to the result set.
+    # 
+    # +radius+ (mi) (Optional, Default: 50mi., Max: 100mi.)
+    # If location is specified, then event.search will look for a radius parameter. Otherwise, it will use 50mi. as the radius of the search.
+    # 
+    # +country_id+ (Numeric, Optional)
+    # The country_id of the event, used to narrow down the responses. To get a country_id, try the metro.getCountryList function.
+    # 
+    # +state_id+ (Numeric, Optional)
+    # The state_id of the event, used to narrow down the responses. To get a state_id, try the metro.getStateList function.
+    # 
+    # +metro_id+ (Numeric, Optional)
+    # The metro_id of the event, used to narrow down the responses. To get a metro_id, try the metro.getList function.
+    # 
+    # +per_page+ (Numeric, Optional, Default = 100)
+    # Number of results to return per page. Max is 100 per page.
+    # 
+    # +page+ (Numeric, Optional, Default = 1)
+    # The page number of results to return.
+    # 
+    # +sort+ (One of name-desc, name-asc, distance-asc, distance-desc, Default = name-asc)
+    # The field and direction on which to sort the results. Distance sorts must ONLY be used if location is specified.
+    def self.search(options={})
+      Mash.new(self.get('/', :query => {:method => 'venue.search'}.merge(options).merge(Upcoming.default_options))).rsp.venue
+    end
+    
+    # Add a new venue to the database. You must pass authentication parameters for this function.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +venuename+ (Required)
+    # The name of the venue.
+    # 
+    # +venueaddress+ (Required)
+    # The name of the venue.
+    # 
+    # +venuecity+ (Required)
+    # The name of the venue.
+    # 
+    # +metro_id+ (Numeric,required if no location )
+    # The metro_id of the venue. To get a metro_id, try the metro.* series of functions.
+    # 
+    # +location+ (Required if no metro_id)
+    # Location parameter accepts comma separated address fields and adds the venue based on your input.
+    # 
+    # +venuezip+ (Optional)
+    # The venue's Zip Code or equivalent.
+    # 
+    # +venuephone+ (Optional)
+    # The venue's phone number.
+    # 
+    # +venueurl+ (Optional)
+    # The url of the venue's website (if any).
+    # 
+    # +venuedescription+ (Optional)
+    # A textual description of the venue.
+    # 
+    # +private+ (1 or 0, Optional, Defaults to 0)
+    # A flag indicating whether the venue should be public (0), or shown only to your friends (1).
+    #
+    def self.add(info, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'venue.add'}
+      body.merge!({:token => token})
+      body.merge!(info)
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.venue
+    end
+    
+    # Edit a venue. Only the authenticated user that added the venue may edit it. You must pass authentication parameters for this function.
+    # 
+    # +token+ (Required)
+    # An authentication token. 
+    # 
+    # +venue_id+ (Numeric, Required)
+    # The id of the venue.
+    # 
+    # +venuename+ (Required)
+    # The name of the venue.
+    # 
+    # +venueaddress+ (Required)
+    # The name of the venue.
+    # 
+    # +venuecity+ (Required)
+    # The name of the venue.
+    # 
+    # +metro_id+ (Numeric, Required)
+    # The metro_id of the venue. To get a metro_id, try the metro.* series of functions.
+    # 
+    # +venuezip+ (Optional)
+    # The venue's Zip Code or equivalent.
+    # 
+    # +venuephone+ (Optional)
+    # The venue's phone number.
+    # 
+    # +venueurl+ (Optional)
+    # The url of the venue's website (if any).
+    # 
+    # +venuedescription+ (Optional)
+    # A textual description of the venue.
+    # 
+    # +private+ (1 or 0, Optional, Defaults to 0)
+    # A flag indicating whether the venue should be public (0), or shown only to your friends (1).
+    #
+    def self.edit(venue, token)
+      token = Upcoming::Auth.token_code(token)
+      format :xml
+      body = {:method => 'venue.edit'}
+      body.merge!({:token => token})
+      body.merge!(event)
+      body.merge!(Upcoming.default_options)
+      body.merge!({:format => 'xml'})
+      Mash.new(self.post('/', :body => body)).rsp.venue
+    end
+  end
+end