Class: CalInvite::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/cal_invite/event.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes = {}) ⇒ Event

Initializes a new Event instance with the given attributes.

Parameters:

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

    The attributes to initialize the event with

Options Hash (attributes):

  • :title (String) —

    The event title

  • :start_time (Time) —

    The event start time

  • :end_time (Time) —

    The event end time

  • :description (String) —

    The event description

  • :location (String) —

    The event location

  • :url (String) —

    The event URL

  • :attendees (Array<String>) —

    The event attendees

  • :timezone (String) — default: 'UTC' —

    The event timezone

  • :show_attendees (Boolean) — default: false —

    Whether to show attendees

  • :notes (String) —

    Additional notes

  • :multi_day_sessions (Array<Hash>) —

    Multi-day session details

  • :all_day (Boolean) — default: false —

    Whether it's an all-day event

  • :organizer (Hash) —

    The event organizer, e.g. { name: "Jane Doe", email: "jane@example.com" }

  • :uid (String) —

    A stable identifier for this event. If omitted, a random one is generated and memoized on this instance. To update or cancel a previously sent invite, you MUST pass the same :uid used originally — mail/calendar clients match REQUEST/CANCEL messages to an existing event by UID, not by content.

  • :sequence (Integer) — default: 0 —

    RFC 5545 SEQUENCE number. Increment it yourself each time you re-send a REQUEST or a CANCEL for the same :uid.

  • :geo (Array<Float>, Hash) —

    Location coordinates, e.g. [37.4595, -122.1418] or { lat:, lng: }

  • :reminders (Array<Integer>) —

    Minutes-before-start values; one VALARM per entry

  • :busy (Boolean) — default: true —

    Whether this event shows as busy on free/busy lookups

  • :visibility (Symbol, String) — default: :public —

    :public, :private, or :confidential

  • :rrule (String) —

    A raw RFC 5545 recurrence rule value, e.g. "FREQ=WEEKLY;COUNT=5"

  • :calendar_name (String) —

    Calendar-level display name (X-WR-CALNAME)

  • :importance (Symbol, String) —

    :low, :normal, or :high

  • :allow_counter (Boolean) — default: true —

    false emits X-MICROSOFT-DISALLOW-COUNTER

Raises:

  • (ArgumentError) —

    If required attributes are missing



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/cal_invite/event.rb', line 95

def initialize(attributes = {})
  @show_attendees = attributes.delete(:show_attendees) || false
  @timezone = attributes.delete(:timezone) || 'UTC'
  @multi_day_sessions = attributes.delete(:multi_day_sessions) || []
  @all_day = attributes.delete(:all_day) || false
  @uid = attributes.delete(:uid) || generate_uid
  @sequence = attributes.delete(:sequence) || 0
  @busy = attributes.key?(:busy) ? attributes.delete(:busy) : true
  @visibility = attributes.delete(:visibility) || :public
  @allow_counter = attributes.key?(:allow_counter) ? attributes.delete(:allow_counter) : true

  attributes.each do |key, value|
    send("#{key}=", value) if respond_to?("#{key}=")
  end

  validate!
end

Instance Attribute Details

#all_day ⇒ Object

Returns the value of attribute all_day.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def all_day
  @all_day
end

#allow_counter ⇒ Object

Returns the value of attribute allow_counter.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def allow_counter
  @allow_counter
end

#attendees ⇒ Object

Returns the value of attribute attendees.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def attendees
  @attendees
end

#busy ⇒ Object

Returns the value of attribute busy.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def busy
  @busy
end

#calendar_name ⇒ Object

Returns the value of attribute calendar_name.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def calendar_name
  @calendar_name
end

#description ⇒ Object

Returns the value of attribute description.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def description
  @description
end

#end_time ⇒ Object

Returns the value of attribute end_time.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def end_time
  @end_time
end

#geo ⇒ Object

Returns the value of attribute geo.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def geo
  @geo
end

#importance ⇒ Object

Returns the value of attribute importance.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def importance
  @importance
end

#location ⇒ Object

Returns the value of attribute location.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def location
  @location
end

#multi_day_sessions ⇒ Object

Returns the value of attribute multi_day_sessions.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def multi_day_sessions
  @multi_day_sessions
end

#notes ⇒ Object

Returns the value of attribute notes.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def notes
  @notes
end

#organizer ⇒ Object

Returns the value of attribute organizer.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def organizer
  @organizer
end

#reminders ⇒ Object

Returns the value of attribute reminders.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def reminders
  @reminders
end

#rrule ⇒ Object

Returns the value of attribute rrule.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def rrule
  @rrule
end

#sequence ⇒ Object

Returns the value of attribute sequence.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def sequence
  @sequence
end

#show_attendees ⇒ Object

Returns the value of attribute show_attendees.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def show_attendees
  @show_attendees
end

#start_time ⇒ Object

Returns the value of attribute start_time.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def start_time
  @start_time
end

#timezone ⇒ Object

Returns the value of attribute timezone.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def timezone
  @timezone
end

#title ⇒ Object

Returns the value of attribute title.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def title
  @title
end

#uid ⇒ Object

Returns the value of attribute uid.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def uid
  @uid
end

#url ⇒ Object

Returns the value of attribute url.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def url
  @url
end

#visibility ⇒ Object

Returns the value of attribute visibility.



38
39
40
 
# File 'lib/cal_invite/event.rb', line 38

def visibility
  @visibility
end

Instance Method Details

#generate_calendar_url(provider, method: :publish) ⇒ String

Generates a calendar URL (or, for the ics/ical/ics_content providers, raw iCalendar content) for the specified provider.

Examples:

Generate a Google Calendar URL

event.generate_calendar_url(:google)

Generate an Outlook Calendar URL

event.generate_calendar_url(:outlook)

Generate an RFC 5545 meeting request for emailing as an invite

event.organizer = { name: "Jane Doe", email: "jane@example.com" }
event.generate_calendar_url(:ics, method: :request)

Cancel a previously sent invite

event.uid = "the-original-uid@cal-invite"  # must match the original REQUEST
event.sequence = 1                          # incremented from the original
event.generate_calendar_url(:ics, method: :cancel)

Parameters:

  • provider (Symbol) —

    The calendar provider to generate the URL for

  • method (Symbol) (defaults to: :publish) —

    The iCalendar METHOD to use (:publish, :request, :cancel, :reply, :counter, or :decline_counter). Only honored by the ics-family providers (ics, ical, ics_content); ignored by URL-based providers.

    • :request (with an #organizer set) produces an invite that mail clients (Gmail, Outlook, Apple Mail) recognize and render with Accept/Decline actions rather than as a plain attachment.
    • :cancel produces a cancellation (STATUS:CANCELLED) for a previously sent :request. Reuse the same #uid and bump #sequence so clients match it to the original invite instead of creating a new event.
    • :reply carries an attendee's own PARTSTAT back to the organizer.
    • :counter carries an attendee's proposed new #start_time/#end_time back to the organizer, keeping the original #uid/#sequence. Client support for rendering this as an actionable UI is inconsistent — see CONFIGURATION.md's "Attendee-proposed reschedules (COUNTER)".
    • :decline_counter is the organizer rejecting a :counter proposal.

Returns:

  • (String) —

    The generated calendar URL or content

Raises:

  • (ArgumentError) —

    If required event attributes are missing



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/cal_invite/event.rb', line 149

def generate_calendar_url(provider, method: :publish)
  validate!

  if caching_enabled?
    cache_key = cache_key_for(provider, method)
    cached_url = fetch_from_cache(cache_key)
    return cached_url if cached_url
  end

  # Generate the URL
  provider_class = CalInvite::Providers.const_get(capitalize_provider(provider.to_s))
  generator = provider_class.new(self, method: method)
  url = generator.generate

  # Cache the result if caching is enabled
  write_to_cache(cache_key, url) if caching_enabled?

  url
end

#update_attributes(new_attributes) ⇒ void

This method returns an undefined value.

Updates the event attributes with new values.

Examples:

Update event title and time

event.update_attributes(
  title: "Updated Meeting",
  start_time: Time.now + 3600
)

Parameters:

  • new_attributes (Hash) —

    The new attributes to update

Raises:

  • (ArgumentError) —

    If the updated attributes make the event invalid



180
181
182
183
184
185
186
187
 
# File 'lib/cal_invite/event.rb', line 180

def update_attributes(new_attributes)
  new_attributes.each do |key, value|
    send("#{key}=", value) if respond_to?("#{key}=")
  end

  invalidate_cache if caching_enabled?
  validate!
end