google_calendar 0.4.4 → 0.5

data/lib/google/event.rb

@@ -8,13 +8,14 @@ module Google
   #
   # === Attributes
   #
-  # * +id+ - The google assigned id of the event (nil until saved). Read only.
+  # * +id+ - The google assigned id of the event (nil until saved). Read Write.
   # * +status+ - The status of the event (confirmed, tentative or cancelled). 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.
+  # * +recurrence+ - A hash containing recurrence info for repeating events. 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.
@@ -24,10 +25,11 @@ module Google
   # * +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.
+  # * +visibility+ - The visibility of the event (*'default'*, 'public', 'private', 'confidential'). Read Write.
   #
   class Event
-    attr_reader :id, :raw, :html_link, :status
-    attr_accessor :title, :location, :calendar, :quickadd, :transparency, :attendees, :description, :reminders
+    attr_reader :raw, :html_link, :status
+    attr_accessor :id, :title, :location, :calendar, :quickadd, :transparency, :attendees, :description, :reminders, :recurrence, :visibility, :creator_name, :color_id
 
     #
     # Create a new event, and optionally set it's attributes.
@@ -36,25 +38,37 @@ module Google
     #
     # event = Google::Event.new
     # event.calendar = AnInstanceOfGoogleCalendaer
+    # event.id = "0123456789abcdefghijklmopqrstuv"
     # event.start_time = Time.now
     # event.end_time = Time.now + (60 * 60)
+    # event.recurrence = {'freq' => 'monthly'}
     # 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.visibility = "public"
+    # 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, :status, :raw, :html_link, :title, :location, :calendar, :quickadd, :attendees, :description, :reminders, :start_time, :end_time,  ].each do |attribute|
+      [:id, :status, :raw, :html_link, :title, :location, :calendar, :quickadd, :attendees, :description, :reminders, :recurrence, :start_time, :end_time, :color_id].each do |attribute|
         instance_variable_set("@#{attribute}", params[attribute])
       end
 
+      self.visibility   = params[:visibility]
       self.transparency = params[:transparency]
       self.all_day      = params[:all_day] if params[:all_day]
+      self.creator_name = params[:creator]['displayName'] if params[:creator]
+    end
+
+    #
+    # Sets the id of the Event.
+    #
+    def id=(id)
+      @id = Event.parse_id(id) unless id.nil?
     end
 
     #
@@ -124,21 +138,50 @@ module Google
     # 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}]} 
+    #   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
 
-    # 
+    #
+    # Stores recurrence rules for repeating events.
+    #
+    # Allowed contents:
+    # :freq => frequence information ("daily", "weekly", "monthly", "yearly")   REQUIRED
+    # :count => how many times the repeating event should occur                 OPTIONAL
+    # :until => Time class, until when the event should occur                   OPTIONAL
+    # :interval => how often should the event occur (every "2" weeks, ...)      OPTIONAL
+    # :byday => if frequence is "weekly", contains ordered (starting with       OPTIONAL
+    #             Sunday)comma separated abbreviations of days the event
+    #             should occur on ("su,mo,th")
+    #           if frequence is "monthly", can specify which day of month
+    #             the event should occur on ("2mo" - second Monday, "-1th" - last Thursday,
+    #             allowed indices are 1,2,3,4,-1)
+    #
+    # Note: The hash should not contain :count and :until keys simultaneously.
+    #
+    # ===== Example
+    # event = cal.create_event do |e|
+    #   e.title = 'Work-day Event'
+    #   e.start_time = Time.now
+    #   e.end_time = Time.now + (60 * 60) # seconds * min
+    #   e.recurrence = {freq: "weekly", byday: "mo,tu,we,th,fr"}
+    # end
+    #
+    def recurrence
+      @recurrence ||= {}
+    end
+
+    #
     # Utility method that simplifies setting the transparency of an event.
     # You can pass true or false.  Defaults to transparent.
     #
@@ -161,11 +204,22 @@ module Google
     #
     # Returns true if the event is opaque otherwise returns false.
     # Opaque events block time on a calendar.
-    # 
+    #
     def opaque?
       @transparency == "opaque"
     end
 
+    #
+    # Sets the visibility of the Event.
+    #
+    def visibility=(val)
+      if val
+        @visibility = Event.parse_visibility(val)
+      else
+        @visibility = "default"      
+      end
+    end
+
     #
     # Convenience method used to build an array of events from a Google feed.
     #
@@ -180,21 +234,30 @@ module Google
     def to_json
       "{
         \"summary\": \"#{title}\",
-        \"description\": \"#{description}\", 
-        \"location\": \"#{location}\", 
+        \"visibility\": \"#{visibility}\",
+        \"description\": \"#{description}\",
+        \"location\": \"#{location}\",
         \"start\": {
           \"dateTime\": \"#{start_time}\"
+          #{timezone_needed? ? local_timezone_json : ''}
         },
         \"end\": {
           \"dateTime\": \"#{end_time}\"
+          #{timezone_needed? ? local_timezone_json : ''}
         },
+        #{recurrence_json}
+        #{color_json}
         #{attendees_json}
         \"reminders\": {
           #{reminders_json}
         }
       }"
     end
-    
+
+    def color_json
+      return unless color_id
+      "\"colorId\": \"#{color_id}\","
+    end
     #
     # JSON representation of attendees
     #
@@ -203,7 +266,7 @@ module Google
 
       attendees = @attendees.map do |attendee|
         "{
-          \"displayName\": \"#{attendee['displayName']}\", 
+          \"displayName\": \"#{attendee['displayName']}\",
           \"email\": \"#{attendee['email']}\",
           \"responseStatus\": \"#{attendee['responseStatus']}\"
         }"
@@ -216,10 +279,10 @@ module Google
     # JSON representation of a reminder
     #
     def reminders_json
-      if reminders && reminders.is_a?(Hash) && reminders['overrides'] 
+      if reminders && reminders.is_a?(Hash) && reminders['overrides']
         overrides = reminders['overrides'].map do |reminder|
           "{
-            \"method\": \"#{reminder['method']}\", 
+            \"method\": \"#{reminder['method']}\",
             \"minutes\": #{reminder['minutes']}
           }"
         end.join(",\n")
@@ -229,11 +292,38 @@ module Google
       end
     end
 
+    #
+    # Timezone info is needed only at recurring events
+    #
+    def timezone_needed?
+      @recurrence && @recurrence[:freq]
+    end
+
+    #
+    # JSON representation of local timezone
+    #
+    def local_timezone_json
+      ",\"timeZone\" : \"#{Time.now.getlocal.zone}\""
+    end
+
+    #
+    # JSON representation of recurrence rules for repeating events
+    #
+    def recurrence_json
+      return unless @recurrence && @recurrence[:freq]
+
+      @recurrence[:until] = @recurrence[:until].strftime('%Y%m%dT%H%M%SZ') if @recurrence[:until]
+      rrule = "RRULE:" + @recurrence.collect { |k,v| "#{k}=#{v}" }.join(';').upcase
+      @recurrence[:until] = Time.parse(@recurrence[:until]) if @recurrence[:until]
+
+      "\"recurrence\": [\n\"#{rrule}\"],"
+    end
+
     #
     # String representation of an event object.
     #
     def to_s
-      "Event Id '#{self.id}'\n\tStatus: #{status}\n\tTitle: #{title}\n\tStarts: #{start_time}\n\tEnds: #{end_time}\n\tLocation: #{location}\n\tDescription: #{description}\n\n"
+      "Event Id '#{self.id}'\n\tStatus: #{status}\n\tTitle: #{title}\n\tStarts: #{start_time}\n\tEnds: #{end_time}\n\tLocation: #{location}\n\tDescription: #{description}\n\tColor: #{color_id}\n\n"
     end
 
     #
@@ -281,16 +371,34 @@ module Google
                 :title        => e['summary'],
                 :description  => e['description'],
                 :location     => e['location'],
+                :creator      => e['creator'],
                 :start_time   => Event.parse_json_time(e['start']),
                 :end_time     => Event.parse_json_time(e['end']),
                 :transparency => e['transparency'],
                 :html_link    => e['htmlLink'],
                 :updated      => e['updated'],
                 :reminders    => e['reminders'],
-                :attendees    => e['attendees'] )
+                :attendees    => e['attendees'],
+                :recurrence   => Event.parse_recurrence_rule(e['recurrence']),
+                :visibility   => e['visibility'],
+                :color_id     => e['colorId'])
 
     end
 
+    #
+    # Parse recurrence rule
+    # Returns hash with recurrence info
+    #
+    def self.parse_recurrence_rule(recurrence_entry)
+      return {} unless recurrence_entry && recurrence_entry != []
+
+      rrule = recurrence_entry[0].sub('RRULE:', '')
+      rhash = Hash[*rrule.downcase.split(/[=;]/)]
+
+      rhash[:until] = Time.parse(rhash[:until]) if rhash[:until]
+      rhash
+    end
+
     #
     # Set the ID after google assigns it (only necessary when we are creating a new event)
     #
@@ -308,7 +416,7 @@ module Google
         Time.parse(time_hash['dateTime']).utc
       else
         Time.now.utc
-      end      
+      end
     end
 
     #
@@ -319,5 +427,20 @@ module Google
       (time.is_a? String) ? Time.parse(time) : time.dup.utc
     end
 
+    #
+    # Validates id format
+    #
+    def self.parse_id(id)
+      raise ArgumentError, "Event ID is invalid. Please check Google documentation: https://developers.google.com/google-apps/calendar/v3/reference/events/insert" unless id.gsub(/(^[a-v0-9]{5,1024}$)/o)      
+    end
+
+    #
+    # Validates visibility value
+    #
+    def self.parse_visibility(visibility)
+      raise ArgumentError, "Event visibility must be 'default', 'public', 'private' or 'confidential'." unless ['default', 'public', 'private', 'confidential'].include?(visibility)    
+      return visibility
+    end
+
   end
 end

data/lib/google/freebusy.rb

@@ -0,0 +1,76 @@
+require 'time'
+require 'json'
+
+module Google
+
+  #
+  # Freebusy returns free/busy information for a set of calendars
+  #
+  class Freebusy
+
+    attr_reader :connection
+
+    #
+    # Setup and query the free/busy status of a collection of calendars.
+    #
+    # The +params+ parameter accepts
+    # * :client_id => the client ID that you received from Google after registering your application with them (https://console.developers.google.com/). REQUIRED
+    # * :client_secret => the client secret you received from Google after registering your application with them. REQUIRED
+    # * :redirect_url => 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'" REQUIRED
+    # * :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). OPTIONAL
+    #
+    # See Readme.rdoc or readme_code.rb for an explication on the OAuth2 authorization process.
+    #
+    def initialize(params={}, connection=nil)
+      @connection = connection || Connection.new(
+        :client_id => params[:client_id],
+        :client_secret => params[:client_secret],
+        :refresh_token => params[:refresh_token],
+        :redirect_url => params[:redirect_url]
+      )
+    end
+
+    #
+    # Find the busy times of the supplied calendar IDs, within the boundaries
+    # of the supplied start_time and end_time
+    #
+    # The arguments supplied are
+    # * calendar_ids => array of Google calendar IDs as strings
+    # * start_time => a Time object, the start of the interval for the query.
+    # * end_time => a Time object, the end of the interval for the query.
+    #
+    def query(calendar_ids, start_time, end_time)
+      query_content = json_for_query(calendar_ids, start_time, end_time)
+      response = @connection.send("/freeBusy", :post, query_content)
+
+      return nil if response.status != 200 || response.body.empty?
+
+      parse_freebusy_response(response.body)
+    end
+
+    private
+
+    #
+    # Prepare the JSON 
+    #
+    def json_for_query(calendar_ids, start_time, end_time)
+      {}.tap{ |obj|
+        obj[:items] = calendar_ids.map {|id| Hash[:id, id] }
+        obj[:timeMin] = start_time.utc.iso8601
+        obj[:timeMax] = end_time.utc.iso8601
+      }.to_json
+    end
+
+    def parse_freebusy_response(response_body)
+      query_result = JSON.parse(response_body)
+
+      return nil unless query_result['calendars'].is_a? Hash
+
+      query_result['calendars'].each_with_object({}) do |(calendar_id, value), result|
+        result[calendar_id] = value['busy'] || []
+      end
+    end
+
+  end
+
+end

data/lib/google_calendar.rb

@@ -1,6 +1,9 @@
 module Google
   require 'google/errors'
   require 'google/calendar'
+  require 'google/calendar_list'
+  require 'google/calendar_list_entry'
   require 'google/connection'
   require 'google/event'
+  require 'google/freebusy'
 end

data/readme_code.rb

@@ -54,6 +54,7 @@ puts event
 event = cal.find_or_create_event_by_id(event.id) do |e|
   e.title = 'An Updated Cool Event'
   e.end_time = Time.now + (60 * 60 * 2) # seconds * min * hours
+  e.color_id = 3  # google allows colors 0-11
 end
 
 puts event

data/test/helper.rb

@@ -14,7 +14,7 @@ rescue Bundler::BundlerError => e
 end
 
 require "minitest/autorun"
-require 'minitest/reporters' 
+require 'minitest/reporters'
 require 'shoulda/context'
 require 'mocha/setup'
 require 'faraday'
@@ -27,4 +27,4 @@ Minitest::Reporters.use! Minitest::Reporters::SpecReporter.new
 
 class Minitest::Test
   @@mock_path = File.expand_path(File.join(File.dirname(__FILE__), 'mocks'))
-end
+end

data/test/mocks/find_calendar_list.json

@@ -0,0 +1,69 @@
+{
+  "kind": "calendar#calendarList",
+  "etag": "\"1420633154361000\"",
+  "nextSyncToken": "00001420633154361000",
+  "items": [
+    {
+      "kind": "calendar#calendarListEntry",
+      "etag": "\"1420564622795000\"",
+      "id": "initech.com_ed493d0a9b46ea46c3a0d48611ce@resource.calendar.google.com",
+      "summary": "Small cubicle",
+      "timeZone": "America/Los_Angeles",
+      "colorId": "2",
+      "backgroundColor": "#d06b64",
+      "foregroundColor": "#000000",
+      "accessRole": "owner",
+      "defaultReminders": []
+    },
+    {
+      "kind": "calendar#calendarListEntry",
+      "etag": "\"1420564132697000\"",
+      "id": "initech.com_db18a4e59c230a5cc5d2b069a30f@resource.calendar.google.com",
+      "summary": "Large cubicle",
+      "timeZone": "America/Los_Angeles",
+      "colorId": "3",
+      "backgroundColor": "#f83a22",
+      "foregroundColor": "#000000",
+      "accessRole": "reader",
+      "defaultReminders": []
+    },
+    {
+      "kind": "calendar#calendarListEntry",
+      "etag": "\"1420564622222000\"",
+      "id": "bob@initech.com",
+      "summary": "Bob's Calendar",
+      "timeZone": "Europe/London",
+      "colorId": "17",
+      "backgroundColor": "#9a9cff",
+      "foregroundColor": "#000000",
+      "accessRole": "owner",
+      "defaultReminders": [
+        {
+          "method": "popup",
+          "minutes": 10
+        }
+      ],
+      "notificationSettings": {
+        "notifications": [
+          {
+            "type": "eventCreation",
+            "method": "email"
+          },
+          {
+            "type": "eventChange",
+            "method": "email"
+          },
+          {
+            "type": "eventCancellation",
+            "method": "email"
+          },
+          {
+            "type": "eventResponse",
+            "method": "email"
+          }
+        ]
+      },
+      "primary": true
+    }
+  ]
+}