google_calendar 0.3.1 → 0.4.0

data/lib/google/connection.rb

@@ -1,120 +1,155 @@
+require 'signet/oauth_2/client'
 require "addressable/uri"
-require 'google/net/https'
 
 module Google
 
-  # This is a utility class that performs all of the
-  # communication with the google calendar api.
+  #
+  # This is a utility class that communicates with the google calendar api.
   #
   class Connection
-    # set the username, password, auth_url, app_name, and login.
+    BASE_URI = "https://www.googleapis.com/calendar/v3"
+
+    attr_accessor :client
+
+    #
+    # Prepare a connection to google for fetching a calendar events
+    #
+    #  the +params+ paramater accepts
+    # * :client_id => the client ID that you received from Google after registering your application with them (https://console.developers.google.com/)
+    # * :client_secret => the client secret you received from Google after registering your application with them.
+    # * :redirect_uri => the url where your users will be redirected to after they have successfully permitted access to their calendars. Use 'urn:ietf:wg:oauth:2.0:oob' if you are using an 'application'"
+    # * :refresh_token => if a user has already given you access to their calendars, you can specify their refresh token here and you will be 'logged on' automatically (i.e. they don't need to authorize access again)
     #
     def initialize(params)
-      @username = params[:username]
-      @password = params[:password]
-      @auth_url = params[:auth_url] || "https://www.google.com/accounts/ClientLogin"
-      @app_name = params[:app_name] || "northworld.com-googlecalendar-integration"
 
-      login()
+      raise ArgumentError unless Connection.credentials_provided?(params)
+
+      @client = Signet::OAuth2::Client.new(
+        :client_id => params[:client_id],
+        :client_secret => params[:client_secret],
+        :redirect_uri => params[:redirect_url],
+        :refresh_token => params[:refresh_token],
+        :authorization_uri => 'https://accounts.google.com/o/oauth2/auth',
+        :token_credential_uri => 'https://accounts.google.com/o/oauth2/token',
+        :scope => "https://www.googleapis.com/auth/calendar"
+      )
+
+      calendar_id = params[:calendar_id]
+
+      # raise CalenarIDMissing unless calendar_id
+      @events_url = "#{BASE_URI}/calendars/#{CGI::escape calendar_id}/events"
+
+      # try to get an access token if possible.
+      if params[:refresh_token]
+        @client.refresh_token = params[:refresh_token]
+        @client.grant_type = 'refresh_token'
+        Connection.get_new_access_token(@client)
+      end
+
     end
 
-    # login to the google calendar and grab an auth token.
     #
-    def login()
-      content = {
-        'Email' => @username,
-        'Passwd' => @password,
-        'source' => @app_name,
-        'accountType' => 'HOSTED_OR_GOOGLE',
-        'service' => 'cl'}
+    # The URL you need to send a user in order to let them grant you access to their calendars.
+    #
+    def authorize_url
+      @client.authorization_uri
+    end
 
-      response = send(Addressable::URI.parse(@auth_url), :post_form, content)
+    #
+    # The single use auth code that google uses during the auth process.
+    #
+    def auth_code
+      @client.code
+    end
 
-      raise HTTPRequestFailed unless response.kind_of? Net::HTTPSuccess
+    #
+    # The current access token.  Used during a session, typically expires in a hour.
+    #
+    def access_token
+      @client.access_token
+    end
 
-      @token = response.body.split('=').last
-      @headers = {
-         'Authorization' => "GoogleLogin auth=#{@token}",
-         'Content-Type'  => 'application/atom+xml'
-       }
-       @update_header = @headers.clone
-       @update_header["If-Match"] = "*"
+    #
+    # The refresh token is used to obtain a new access token.  It remains valid until a user revokes access.
+    #
+    def refresh_token
+      @client.refresh_token
     end
 
-    # send a request to google.
     #
-    def send(uri, method, content = '', redirect_count = 10)
-      raise HTTPTooManyRedirections if redirect_count == 0
+    # Convenience method used to streamline the process of logging in with a auth code.
+    #
+    def login_with_auth_code(auth_code)
+      @client.code = auth_code
+      Connection.get_new_access_token(@client)
+      @client.refresh_token
+    end
 
-      set_session_if_necessary(uri)
+    #
+    # Convenience method used to streamline the process of logging in with a refresh token.
+    #
+    def login_with_refresh_token(refresh_token)
+      @client.refresh_token = refresh_token
+      @client.grant_type = 'refresh_token'
+      Connection.get_new_access_token(@client)
+    end
 
-      http = (uri.scheme == 'https' ? Net::HTTPS.new(uri.host, uri.inferred_port) : Net::HTTP.new(uri.host, uri.inferred_port))
-      response =  http.request(build_request(uri, method, content))
+    #
+    # Send a request to google.
+    #
+    def send(uri, method, content = '')
 
-      # recurse if necessary.
-      if response.kind_of? Net::HTTPRedirection
-        response = send(Addressable::URI.parse(response['location']), method, content, redirect_count - 1)
-      end
+      response = @client.fetch_protected_resource(
+        :uri => uri,
+        :method => method,
+        :body  => content,
+        :headers => {'Content-type' => 'application/json'}
+      )
 
       check_for_errors(response)
 
       return response
     end
 
-    protected
+    #
+    # Wraps the `send` method. Send an event related request to Google.
+    #
+    def send_events_request(path_and_query_string, method, content = '')
+      send(Addressable::URI.parse(@events_url + path_and_query_string), method, content)
+    end
 
-    # Check to see if we are using a session and extract it's values if required.
-    # 
-    def set_session_if_necessary(uri) #:nodoc:
-      # only extract the session if we don't already have one.
-      @session_id = uri.query_values['gsessionid'] if @session_id == nil && uri.query
+    protected
 
-      if @session_id
-        uri.query ||= ''
-        uri.query_values = uri.query_values.merge({'gsessionid' => @session_id})
+    #
+    # Utility method to centralize the process of getting an access token.
+    #
+    def self.get_new_access_token(client) #:nodoc:
+      begin 
+        client.fetch_access_token!
+      rescue Signet::AuthorizationError
+        raise HTTPAuthorizationFailed
       end
     end
 
-    # Construct the appropriate request object.
     #
-    def build_request(uri, method, content) #:nodoc
-      case method
-      when :delete
-        request = Net::HTTP::Delete.new(uri.to_s, @update_header)
-
-      when :get
-        request = Net::HTTP::Get.new(uri.to_s, @headers)
-
-      when :post_form
-        request = Net::HTTP::Post.new(uri.to_s, @headers)
-        request.set_form_data(content)
-
-      when :post
-        request = Net::HTTP::Post.new(uri.to_s, @headers)
-        request.body = content
-
-      when :put
-        request = Net::HTTP::Put.new(uri.to_s, @update_header)
-        request.body = content
-      end # case
-
-      return request
-    end
-
     # Check for common HTTP Errors and raise the appropriate response.
     #
     def check_for_errors(response) #:nodoc
-      if response.kind_of? Net::HTTPForbidden
-        raise HTTPAuthorizationFailed, response.body
+      case response.status
+        when 400 then raise HTTPRequestFailed, response.body
+        when 404 then raise HTTPNotFound, response.body
+      end
+    end
 
-      elsif response.kind_of? Net::HTTPBadRequest
-        raise HTTPRequestFailed, response.body
+    private
 
-      elsif response.kind_of? Net::HTTPNotFound
-        raise HTTPNotFound, response.body
-      end
+    #
+    # 
+    #
+    def self.credentials_provided?(params) #:nodoc:
+      blank = /[^[:space:]]/
+      !(params[:client_id] !~ blank) && !(params[:client_secret] !~ blank)
     end
 
   end
-
-end
+end

data/lib/google/errors.rb

@@ -4,4 +4,5 @@ module Google
   class HTTPNotFound < StandardError; end
   class HTTPTooManyRedirections < StandardError; end
   class InvalidCalendar < StandardError; end
-end
+  class CalenarIDMissing < StandardError; end
+end

data/lib/google/event.rb

@@ -1,60 +1,69 @@
-require 'nokogiri'
 require 'time'
 
 module Google
 
+  #
   # Represents a Google Event.
   #
   # === Attributes
   #
-  # * +id+ - The google assigned id of the event (nil until saved), read only.
-  # * +title+ - The title of the event, read/write.
-  # * +content+ - The content of the event, read/write.
-  # * +start_time+ - The start time of the event (Time object, defaults to now), read/write.
-  # * +end_time+ - The end time of the event (Time object, defaults to one hour from now), read/write.
-  # * +calendar+ - What calendar the event belongs to, read/write.
-  # * +raw_xml+ - The full google xml representation of the event.
-  # * +html_link+ - An absolute link to this event in the Google Calendar Web UI. Read-only.
-  # * +published_time+ - The time of the event creation. Read-only.
-  # * +updated_time+ - The last update time of the event. Read-only.
+  # * +id+ - The google assigned id of the event (nil until saved). Read only.
+  # * +title+ - The title of the event. Read Write.
+  # * +description+ - The content of the event. Read Write.
+  # * +location+ - The location of the event. Read Write.
+  # * +start_time+ - The start time of the event (Time object, defaults to now). Read Write.
+  # * +end_time+ - The end time of the event (Time object, defaults to one hour from now).  Read Write.
+  # * +calendar+ - What calendar the event belongs to. Read Write.
+  # * +all_day + - Does the event run all day. Read Write.
+  # * +quickadd+ - A string that Google parses when setting up a new event.  If set and then saved it will take priority over any attributes you have set. Read Write.
+  # * +reminders+ - A hash containing reminders. Read Write.
+  # * +attendees+ - An array of hashes containing information about attendees. Read Write
+  # * +transparency+ - Does the event 'block out space' on the calendar.  Valid values are true, false or 'transparent', 'opaque'. Read Write.
+  # * +duration+ - The duration of the event in seconds. Read only.
+  # * +html_link+ - An absolute link to this event in the Google Calendar Web UI. Read only.
+  # * +raw+ - The full google json representation of the event. Read only.
   #
   class Event
-    attr_reader :id, :raw_xml, :html_link, :updated_time, :published_time
-    attr_accessor :title, :content, :where, :calendar, :quickadd, :transparency
+    attr_reader :id, :raw, :html_link
+    attr_accessor :title, :location, :calendar, :quickadd, :transparency, :attendees, :description, :reminders
 
+    #
     # Create a new event, and optionally set it's attributes.
     #
     # ==== Example
-    #  Event.new(:title => 'Swimming',
-    #           :content => 'Do not forget a towel this time',
-    #           :where => 'The Ocean',
-    #           :start_time => Time.now,
-    #           :end_time => Time.now + (60 * 60),
-    #           :calendar => calendar_object)
+    #
+    # event = Google::Event.new
+    # event.calendar = AnInstanceOfGoogleCalendaer
+    # event.start_time = Time.now
+    # event.end_time = Time.now + (60 * 60)
+    # event.title = "Go Swimming"
+    # event.description = "The polar bear plunge"
+    # event.location = "In the arctic ocean"
+    # event.transparency = "opaque"
+    # event.reminders = { 'useDefault'  => false, 'overrides' => ['minutes' => 10, 'method' => "popup"]}
+    # event.attendees = [
+    #                     {'email' => 'some.a.one@gmail.com', 'displayName' => 'Some A One', 'responseStatus' => 'tentative'},
+    #                     {'email' => 'some.b.one@gmail.com', 'displayName' => 'Some B One', 'responseStatus' => 'tentative'}
+    #                   ]
     #
     def initialize(params = {})
-      @id             = params[:id]
-      @title          = params[:title]
-      @where          = params[:where]
-      @raw_xml        = params[:raw_xml]
-      @content        = params[:content]
-      @calendar       = params[:calendar]
-      @end_time       = params[:end_time]
-      @quickadd       = params[:quickadd]
-      @html_link      = params[:html_link]
-      @start_time     = params[:start_time]
-      self.all_day    = params[:all_day] if params[:all_day]
-      @updated_time   = params[:updated]
-      @transparency   = params[:transparency]
-      @published_time = params[:published]
-    end
-
-    # Sets the start time of the Event.  Must be a Time object or a parsable string representation of a time.
+      [:id, :raw, :html_link, 
+       :title, :location, :calendar, :quickadd, :attendees, :description, :reminders, :start_time, :end_time,  ].each do |attribute|
+        instance_variable_set("@#{attribute}", params[attribute])
+      end
+
+      self.transparency = params[:transparency]
+      self.all_day      = params[:all_day] if params[:all_day]
+    end
+
+    #
+    # Sets the start time of the Event.  Must be a Time object or a parse-able string representation of a time.
     #
     def start_time=(time)
       @start_time = parse_time(time)
     end
 
+    #
     # Get the start_time of the event.
     #
     # If no time is set (i.e. new event) it defaults to the current time.
@@ -64,6 +73,7 @@ module Google
       (@start_time.is_a? String) ? @start_time : @start_time.xmlschema
     end
 
+    #
     # Get the end_time of the event.
     #
     # If no time is set (i.e. new event) it defaults to one hour in the future.
@@ -73,7 +83,8 @@ module Google
       (@end_time.is_a? String) ? @end_time : @end_time.xmlschema
     end
 
-    # Sets the end time of the Event.  Must be a Time object or a parsable string representation of a time.
+    #
+    # Sets the end time of the Event.  Must be a Time object or a parse-able string representation of a time.
     #
     def end_time=(time)
       @end_time = parse_time(time)
@@ -81,13 +92,18 @@ module Google
       @end_time = (time.is_a? String) ? Time.parse(time) : time.dup.utc
     end
 
+    #
     # Returns whether the Event is an all-day event, based on whether the event starts at the beginning and ends at the end of the day.
     #
     def all_day?
-      time = Time.parse(@start_time)
+      time = (@start_time.is_a?  String) ? Time.parse(@start_time) : @start_time.dup.utc
       duration % (24 * 60 * 60) == 0 && time == Time.local(time.year,time.month,time.day)
     end
 
+    #
+    # Makes an event all day, by setting it's start time to the passed in time and it's end time 24 hours later.
+    # Note: this will clobber both the start and end times currently set.
+    #
     def all_day=(time)
       if time.class == String
         time = Time.parse(time)
@@ -96,61 +112,138 @@ module Google
       @end_time = (time + 24*60*60).strftime("%Y-%m-%d")
     end
 
-    # Duration in seconds
+    #
+    # Duration of the event in seconds
+    #
     def duration
       Time.parse(end_time) - Time.parse(start_time)
     end
 
+    #
+    # Stores reminders for this event. Multiple reminders are allowed.
+    #
+    # Examples
+    #  
+    # event = cal.create_event do |e|
+    #   e.title = 'Some Event'
+    #   e.start_time = Time.now + (60 * 10)
+    #   e.end_time = Time.now + (60 * 60) # seconds * min
+    #   e.reminders = { 'useDefault'  => false, 'overrides' => [{method: 'email', minutes: 4}, {method: 'popup', minutes: 60}, {method: 'sms', minutes: 30}]} 
+    # end
+    # 
+    # event = Event.new :start_time => "2012-03-31", :end_time => "2012-04-03", :reminders => { 'useDefault'  => false, 'overrides' => [{'minutes' => 10, 'method' => "popup"}]}
+    #
+    def reminders
+      @reminders ||= {}
+    end
+
+    # 
+    # Utility method that simplifies setting the transparency of an event.
+    # You can pass true or false.  Defaults to transparent.
+    #
+    def transparency=(val)
+      if val == false || val.to_s.downcase == 'opaque'
+        @transparency = 'opaque'
+      else
+        @transparency = 'transparent'
+      end
+    end
+
+    #
+    # Returns true if the event is transparent otherwise returns false.
+    # Transparent events do not block time on a calendar.
+    #
     def transparent?
-      transparency == "transparent"
+      @transparency == "transparent"
     end
 
+    #
+    # Returns true if the event is opaque otherwise returns false.
+    # Opaque events block time on a calendar.
+    # 
     def opaque?
-      transparency == "opaque"
+      @transparency == "opaque"
+    end
+
+    #
+    # Convenience method used to build an array of events from a Google feed.
+    #
+    def self.build_from_google_feed(response, calendar)
+      events = response['items'] ? response['items'] : [response]
+      events.collect {|e| new_from_feed(e, calendar)}.flatten
     end
 
     #
-    def self.build_from_google_feed(xml, calendar)
-      Nokogiri::XML(xml).xpath("//xmlns:entry").collect {|e| new_from_xml(e, calendar)}
+    # Google JSON representation of an event object.
+    #
+    def to_json
+      "{
+        \"summary\": \"#{title}\",
+        \"description\": \"#{description}\", 
+        \"location\": \"#{location}\", 
+        \"start\": {
+          \"dateTime\": \"#{start_time}\"
+        },
+        \"end\": {
+          \"dateTime\": \"#{end_time}\"
+        },
+        #{attendees_json}
+        \"reminders\": {
+          #{reminders_json}
+        }
+      }"
     end
+    
+    #
+    # JSON representation of attendees
+    #
+    def attendees_json
+      return unless @attendees
 
-    # Google XMl representation of an evetn object.
+      attendees = @attendees.map do |attendee|
+        "{
+          \"displayName\": \"#{attendee['displayName']}\", 
+          \"email\": \"#{attendee['email']}\",
+          \"responseStatus\": \"#{attendee['responseStatus']}\"
+        }"
+      end.join(",\n")
+
+      "\"attendees\": [\n#{attendees}],"
+    end
+
+    #
+    # JSON representation of a reminder
     #
-    def to_xml
-      unless quickadd
-        "<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
-          <category scheme='http://schemas.google.com/g/2005#kind' term='http://schemas.google.com/g/2005#event'></category>
-          <title type='text'>#{title}</title>
-          <content type='text'>#{content}</content>
-          <gd:transparency value='http://schemas.google.com/g/2005#event.#{transparency}'></gd:transparency>
-          <gd:eventStatus value='http://schemas.google.com/g/2005#event.confirmed'></gd:eventStatus>
-          <gd:where valueString=\"#{where}\"></gd:where>
-          <gd:when startTime=\"#{start_time}\" endTime=\"#{end_time}\"></gd:when>
-         </entry>"
+    def reminders_json
+      if reminders && reminders.is_a?(Hash) && reminders['overrides'] 
+        overrides = reminders['overrides'].map do |reminder|
+          "{
+            \"method\": \"#{reminder['method']}\", 
+            \"minutes\": #{reminder['minutes']}
+          }"
+        end.join(",\n")
+        "\n\"useDefault\": false,\n\"overrides\": [\n#{overrides}]"
       else
-        %Q{<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gCal='http://schemas.google.com/gCal/2005'>
-            <content type="html">#{content}</content>
-            <gCal:quickadd value="true"/>
-          </entry>}
+        "\"useDefault\": true"
       end
     end
 
+    #
     # String representation of an event object.
     #
     def to_s
-      s = "#{title} (#{self.id})\n\t#{start_time}\n\t#{end_time}\n\t#{where}\n\t#{content}"
-      s << "\n\t#{quickadd}" if quickadd
-      s
+      "Event Id '#{self.id}'\n\tTitle: #{title}\n\tStarts: #{start_time}\n\tEnds: #{end_time}\n\tLocation: #{location}\n\tDescription: #{description}\n\n"
     end
 
+    #
     # Saves an event.
-    #  Note: If using this on an event you created without using a calendar object,
-    #  make sure to set the calendar before calling this method.
+    #  Note: make sure to set the calendar before calling this method.
     #
     def save
       update_after_save(@calendar.save_event(self))
     end
 
+    #
     # Deletes an event.
     #  Note: If using this on an event you created without using a calendar object,
     #  make sure to set the calendar before calling this method.
@@ -160,49 +253,53 @@ module Google
       @id = nil
     end
 
-    protected
-
-    # Create a new event from a google 'entry' xml block.
     #
-    def self.new_from_xml(xml, calendar) #:nodoc:
-      id = xml.at_xpath("gCal:uid")['value'].split('@').first
+    # Returns true if the event will use quickadd when it is saved.
+    #
+    def use_quickadd?
+      quickadd && id == nil
+    end
 
-      # Check if this event came from an apple program (ios, iCal, Calendar, etc)
-      # Id format ex: E52411E2-8DB9-4A26-AD5A-8B6104320D3C
-      if id.match( /[0-9A-Z]{8}-([0-9A-Z]{4}-){3}[0-9A-Z]{12}/ )
-        # Use the ID field instead of the UID which apple overwrites for its own purposes.
-        # TODO With proper testing, this should be way to parse all event id's
-        id = xml.at_xpath("xmlns:id").content.split('/').last
-      end
+    #
+    # Returns true if this a new event.
+    #
+    def new_event?
+      id == nil || id == ''
+    end
 
-      event_time_data = xml.at_xpath("gd:when")
+    protected
 
-      Event.new(:id           => id,
+    #
+    # Create a new event from a google 'entry'
+    #
+    def self.new_from_feed(e, calendar) #:nodoc:
+      Event.new(:id           => e['id'],
                 :calendar     => calendar,
-                :raw_xml      => xml,
-                :title        => xml.at_xpath("xmlns:title").content,
-                :content      => xml.at_xpath("xmlns:content").content,
-                :where        => xml.at_xpath("gd:where")['valueString'],
-                :start_time   => (event_time_data.nil? ? nil : xml.at_xpath("gd:when")['startTime']),
-                :end_time     => (event_time_data.nil? ? nil : xml.at_xpath("gd:when")['endTime']),
-                :transparency => xml.at_xpath("gd:transparency")['value'].split('.').last,
-                :quickadd     => (xml.at_xpath("gCal:quickadd") ? (xml.at_xpath("gCal:quickadd")['quickadd']) : nil),
-                :html_link    => xml.at_xpath('//xmlns:link[@title="alternate" and @rel="alternate" and @type="text/html"]')['href'],
-                :published    => xml.at_xpath("xmlns:published").content,
-                :updated      => xml.at_xpath("xmlns:updated").content )
+                :raw          => e,
+                :title        => e['summary'],
+                :description  => e['description'],
+                :location     => e['location'],
+                :start_time   => (e['start'] ? e['start']['dateTime'] : ''),
+                :end_time     => (e['end']   ? e['end']['dateTime'] : ''),
+                :transparency => e['transparency'],
+                :html_link    => e['htmlLink'],
+                :updated      => e['updated'],
+                :reminders    => e['reminders'],
+                :attendees    => e['attendees'] )
+
     end
 
+    #
     # Set the ID after google assigns it (only necessary when we are creating a new event)
     #
     def update_after_save(respose) #:nodoc:
       return if @id && @id != ''
-
-      xml = Nokogiri::XML(respose.body).at_xpath("//xmlns:entry")
-      @id = xml.at_xpath("gCal:uid")['value'].split('@').first
-      @html_link    = xml.at_xpath('//xmlns:link[@title="alternate" and @rel="alternate" and @type="text/html"]')['href']
-      @raw_xml = xml
+      @raw = JSON.parse(respose.body)
+      @id = @raw['id']
+      @html_link = @raw['htmlLink']
     end
 
+    #
     # A utility method used centralize time parsing.
     #
     def parse_time(time) #:nodoc