# Upcoming is an interface to access the Upcoming.org[http://upcoming.org] api in Ruby.
#
# Main page:: http://derek.leftwise.com/software/upcoming.html
# Author:: Derek Greentree <derekgr@gmail.com>
# Version:: 0.1
# License:: GPL

require 'upcoming/call'
require 'upcoming/parse'

module Upcoming
  Copyright = 'Copyright 2005 Derek Greentree <derekgr@gmail.com>'
  Version = '0.2'

  # The Upcoming class declares all the methods to actually access the api. You can easily make custom calls
  # or modify existing calls by using the basic_call and auth_call methods defined here.
  class Upcoming
    attr_reader :username, :password, :apikey
    def initialize(api, username='', password='')
      @apikey = api
      @username = username
      @password = password

      @parser = Parse.new
    end

    # Calls the upcoming.org api method specified by 'method', with parameters given by the 'parameters' hash.
    # Automatically passes the api_key parameter. If you need to also pass username and password, consider the
    # more convenient auth_call method.
    # 'post' specifies whether or not this call uses HTTP POST. The default is false (i.e. use HTTP GET), but some
    # api methods are only accessible via POST.
    def basic_call(parameters, method, post = false)
      apiCall = Call.new(method)
      realParams = { 'api_key' => @apikey }.merge(parameters)
      if post
        @parser.parseResponse(apiCall.call_post(realParams))
      else
        @parser.parseResponse(apiCall.call(realParams))
      end
    end

    # Much like basic_call, but also automatically adds the 'username' and 'password' parameters.
    def auth_call(parameters, method, post = false)
      apiCall = Call.new(method)
      realParams = { 'api_key' => @apikey, 'username' => @username, 'password' => @password }.merge(parameters)
      if post
        @parser.parseResponse(apiCall.call_post(realParams))
      else
        @parser.parseResponse(apiCall.call(realParams))
      end
    end

    # Implements the 'metro.getList' api call. Returns an array of Upcoming::Metro objects.
    def getMetroList(state_id)
      self.basic_call( {'state_id' => state_id}, 'metro.getList' )
    end

    # Implements the 'metro.getInfo' api call. Returns an array of Upcoming::Metro objects. The array 
    # contains only one elements: the Metro object specified. By defalt, this method will pass username
    # and password, so that you can request a private metro. To override this, pass 'false' as the second
    # parameter.
    def getMetroInfo(metro_id, privateMetro = true)
      if privateMetro
        self.basic_call( {'metro_id' => metro_id}, 'metro.getInfo' )
      else
        self.auth_call( {'metro_id' => metro_id}, 'metro.getInfo' )
      end
    end

    # Implements the 'metro.search' api call. Returns an array of Upcoming::Metro objects.
    def searchMetros(search_text = '', country_id = '', state_id = '')
      self.basic_call( {'search_text' => search_text, 'country_id' => country_id, 'state_id' => state_id }, 'metro.search')
    end

    # Implements the 'metro.getStateList' api call. Returns an array of Upcoming::State objects.
    def getStateList(country_id)
      self.basic_call( {'country_id' => country_id }, 'metro.getStateList' )
    end

    # Implements the 'metro.getCountryList' api call. Returns an array of Upcoming::Country objects.
    def getCountryList
      self.basic_call( {}, 'metro.getCountryList' )
    end

    # Implements the 'event.getInfo' api call. Returns an array of Upcoming::Event objects. The array will only contain 
    # one element. By default, this will attempt to pass username and password, so that the list returned contains
    # private events. If you wish to override this behavior, pass 'false' as the second parameter.
    def getEventInfo(event_id, privateEvent = true)
      if privateEvent
        self.auth_call( {'event_id' => event_id}, 'event.getInfo' )
      else
        self.basic_call( {'event_id' => event_id}, 'event.getInfo' )
      end
    end 

    # Implements the 'event.add' api call. Returns an array of Upcoming::Event objects. The array only contains one
    # element, which is the event you just created.
    def addEvent(name, metro_id, venue_id, category_id, start_date, end_date = '', start_time = '', end_time = '', 
                 description = '', personal = '0', selfpromotion = '0')
      self.auth_call({ 'name' => name, 'metro_id' => metro_id, 'venue_id' => venue_id, 'category_id' => category_id, 
                       'start_date' => start_date, 'end_date' => end_date, 'start_time' => start_time, 'end_time' => end_time,
                       'description' => description, 'personal' => personal, 'selfpromotion' => selfpromotion },
                     'event.add', true);
    end

    # Implements the 'event.search' api call. Returns an array of Upcoming::Event objects which match the query.
    # By default, this will attempt to pass username and password, so that the list returned contains
    # private events. If you wish to override this behavior, pass 'false' as the last parameter.
    def searchEvents(search_text = '', country_id = '', state_id = '', metro_id = '', venue_id = '', min_date = '', 
                     max_date = '', tags = '', per_page = '100', page = '1', sort = 'start-date-asc', privateEvents = true)
      params = { 'search_text' => search_text, 'country_id' => country_id, 'state_id' => state_id, 'metro_id' => metro_id,
        'venue_id' => venue_id, 'min_date' => min_date, 'max_date' => max_date, 'tags' => tags, 'per_page' => per_page,
        'page' => page, 'sort' => sort }
      if privateEvents
        self.auth_call(params, 'event.search')
      else
        self.basic_call(params, 'event.search')
      end
    end

    # Implements the 'event.getWatchList' api call. Returns an array of Upcoming::Watchlist objects. The array will
    # only contain one element.
    def getEventWatchlist(event_id)
      self.auth_call({'event_id' => event_id}, 'event.getWatchlist')
    end

    # Implements the 'venue.add' api call. Returns an array of Upcoming::Venue objects. The array will
    # only contain one element - the venue which was just created.
    def addVenue(venuename, venueaddress, venuecity, metro_id, venuezip = '', venuephone = '', venueurl = '', 
                 venuedescription = '', private ='0')
      self.auth_call( { 'venuename' => venuename, 'venueaddress' => venueaddress, 'venuecity' => venuecity,
                        'metro_id' => metro_id, 'venuezip' => venuezip, 'venuephone' => venuephone,
                        'venueurl' => venueurl, 'venuedescription' => venuedescription, 'private' => private },
                      'venue.add', true);
    end

    # Implements the 'venue.getInfo' api call. Returns an array of Upcoming::Venue objects. The array
    # will only contain one element.
    # By default, this will attempt to pass username and password, so that the call can retrieve 
    # private venues. If you wish to override this behavior, pass 'false' as the last parameter.
    def getVenueInfo(venue_id, privateVenue = true)
      if privateVenue
        self.auth_call( {'venue_id' => venue_id}, 'venue.getInfo')
      else
        self.basic_call( {'venue_id' => venue_id}, 'venue.getInfo')
      end
    end
    
    # Implements the 'venue.getList' api call. Returns an array of Upcoming::Venue objects. 
    # By default, this will attempt to pass username and password, so that the call can retrieve 
    # private venues. If you wish to override this behavior, pass 'false' as the last parameter.
    def getVenueList(metro_id, privateVenue = true)
      if privateVenue
        self.auth_call({'metro_id' => metro_id}, 'venue.getList')
      else
        self.basic_call({'metro_id' => metro_id}, 'venue.getList')
      end
    end

    # Implements the 'venue.search' api call. Returns an array of Upcoming::Venue objects. 
    # By default, this will attempt to pass username and password, so that the call can retrieve 
    # private venues. If you wish to override this behavior, pass 'false' as the last parameter.
    def searchVenues(search_text = '', country_id = '', state_id = '', metro_id = '', privateVenues = true)
      params = { 'search_text' => search_text, 'country_id' => country_id, 'state_id' => state_id, 'metro_id' => metro_id }
      if privateVenues
        self.auth_call(params, 'venue.search')
      else
        self.basic_call(params, 'venue.search')
      end
    end

    # Implements the 'category.getList' api call. Returns an array of Upcoming::Category objects.
    def getCategoryList
      self.basic_call( {}, 'category.getList' )
    end

    # Implements the 'watchlist.getList' api call. Returns an array of Upcoming::Watchlist objects.
    def getWatchlistList(min_date = '', max_date = '')
      self.auth_call( {'min_date' => min_date, 'max_date' => max_date}, 'watchlist.getList')
    end

    # Implements the 'watchlist.add' api call. Returns an array of Upcoming::Watchlist objects. The array
    # will contain only one element - the watchlist that was just added.
    def addWatchlist(event_id, status = 'watch')
      self.auth_call( { 'event_id' => event_id, 'status' => status }, 'watchlist.add', true);
    end

    # Implements the 'watchlist.remove' api call. Returns an empty array.
    def removeWatchlist(watchlist_id)
      self.auth_call( { 'watchlist_id' => watchlist_id}, 'watchlist.remove', true);
    end

    # Implements the 'user.getInfo' api call. Returns an array of Upcoming::User objects. The array will
    # only contain one object. 
    # By default, this will attempt to pass username and password, so that the call can retrieve 
    # private users. If you wish to override this behavior, pass 'false' as the last parameter.
    def getUserInfo(user_id, privateUser = true)
      if privateUser
        self.auth_call( {'user_id' => user_id}, 'user.getInfo')
      else
        self.basic_call( {'user_id' => user_id}, 'user.getInfo')
      end
    end

    # Implements the 'user.getMetroList' api call. Returns an array of Upcoming::Metro objects.
    def getMetroListForUser
      self.auth_call( {}, 'user.getMetroList' )
    end

    # Implements the 'user.getWatchlist' api call. Returns an array of Upcoming::Watchlist objects.
    def getWatchlistForUser(user_id)
      self.auth_call( {'user_id' => user_id}, 'user.getWatchlist')
    end

  end

  class User
    attr_accessor :id, :name, :username, :zip, :photourl, :url
  end

  class Watchlist
    attr_accessor :id, :event_id, :status
  end

  class Category
    attr_accessor :id, :name, :description
  end

  class Venue
    attr_accessor :id, :name, :address, :city, :zip, :phone, :url, :description, :user_id, :private
  end

  class Country
    attr_accessor :id, :name, :code
  end

  class State
    attr_accessor :id, :name, :code
  end

  class Metro
    attr_accessor :name, :code, :id, :state_id, :state_code, :country_code, :url
  end

  class Event
    attr_accessor :id, :name, :tags, :description, :start_date, :end_date, :start_time, :end_time, :personal, :selfpromotion,
      :metro_id, :venue_id, :user_id, :category_id, :date_posted, :username, :status
  end

end