cal-invite 0.1.3 → 0.1.5

data/lib/cal_invite/providers/ical.rb

@@ -3,7 +3,35 @@
 # lib/cal_invite/providers/ical.rb
 module CalInvite
   module Providers
+    # iCalendar format provider for generating ICS (iCalendar) content.
+    # This provider generates calendar content following the iCalendar specification (RFC 5545).
+    # It supports single events, all-day events, and multi-day sessions with proper timezone handling.
+    #
+    # @example Creating a regular event
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     timezone: 'America/New_York'
+    #   )
+    #   ical = CalInvite::Providers::Ical.new(event)
+    #   ics_content = ical.generate
+    #
+    # @example Creating a multi-day event
+    #   event = CalInvite::Event.new(
+    #     title: "Conference",
+    #     multi_day_sessions: [
+    #       { start_time: Time.now, end_time: Time.now + 3600 },
+    #       { start_time: Time.now + 86400, end_time: Time.now + 90000 }
+    #     ]
+    #   )
+    #   ics_content = CalInvite::Providers::Ical.new(event).generate
     class Ical < BaseProvider
+      # Generates an iCalendar format string containing the event details.
+      # Includes proper calendar headers, timezone information (if needed),
+      # and one or more event blocks.
+      #
+      # @return [String] The complete iCalendar format content
       def generate
         [
           "BEGIN:VCALENDAR",
@@ -19,6 +47,10 @@ module CalInvite
 
       private
 
+      # Generates the event blocks (VEVENT) for the calendar.
+      # Handles both single events and multi-day sessions.
+      #
+      # @return [String] The formatted event block(s)
       def generate_events
         if event.multi_day_sessions.any?
           event.multi_day_sessions.map { |session| generate_vevent(session) }.join("\r\n")
@@ -27,22 +59,25 @@ module CalInvite
         end
       end
 
+      # Generates a single VEVENT block with all event details.
+      # Handles both all-day events and time-specific events.
+      #
+      # @param session [Hash, nil] Optional session details for multi-day events
+      # @return [String] The formatted VEVENT block
+      # @raise [ArgumentError] If required time fields are missing for non-all-day events
       def generate_vevent(session = nil)
         lines = ["BEGIN:VEVENT"]
 
         if event.all_day
           start_date = event.start_time || Time.now
           end_date = event.end_time || (start_date + 86400)
-
           lines << "DTSTART;VALUE=DATE:#{format_date(start_date)}"
           lines << "DTEND;VALUE=DATE:#{format_date(end_date)}"
         else
           start_time = session ? session[:start_time] : event.start_time
           end_time = session ? session[:end_time] : event.end_time
-
           raise ArgumentError, "Start time is required for non-all-day events" unless start_time
           raise ArgumentError, "End time is required for non-all-day events" unless end_time
-
           lines << "DTSTART;TZID=#{event.timezone}:#{format_local_time(start_time)}"
           lines << "DTEND;TZID=#{event.timezone}:#{format_local_time(end_time)}"
         end
@@ -70,9 +105,12 @@ module CalInvite
         lines.join("\r\n")
       end
 
+      # Generates the timezone block (VTIMEZONE) for the calendar.
+      # Only included for non-all-day events.
+      #
+      # @return [String, nil] The formatted timezone block, or nil for all-day events
       def generate_timezone
         return nil if event.all_day # No timezone needed for all-day events
-
         [
           "BEGIN:VTIMEZONE",
           "TZID:#{event.timezone}",
@@ -80,26 +118,46 @@ module CalInvite
         ].join("\r\n")
       end
 
+      # Generates a unique identifier for the calendar event.
+      # Format: timestamp-randomhex@cal-invite
+      #
+      # @return [String] The generated UID
       def generate_uid
         "#{Time.now.to_i}-#{SecureRandom.hex(8)}@cal-invite"
       end
 
+      # Formats a time object as a date string in iCalendar format.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted date (YYYYMMDD)
       def format_date(time)
         time.strftime("%Y%m%d")
       end
 
+      # Formats a time object as a local time string in iCalendar format.
+      # Times are assumed to be in the correct timezone already.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted local time (YYYYMMDDTHHmmSS)
       def format_local_time(time)
-        # All times are already in UTC, just format them
         time.strftime("%Y%m%dT%H%M%S")
       end
 
+      # Formats a time object as an UTC timestamp in iCalendar format.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC timestamp (YYYYMMDDTHHmmSSZ)
       def format_timestamp(time)
         time.strftime("%Y%m%dT%H%M%SZ")
       end
 
+      # Escapes special characters in text according to iCalendar spec.
+      # Handles backslashes, newlines, commas, and semicolons.
+      #
+      # @param text [String, nil] The text to escape
+      # @return [String] The escaped text
       def escape_text(text)
         return '' if text.nil?
-
         text.to_s
             .gsub('\\', '\\\\')
             .gsub("\n", '\\n')

data/lib/cal_invite/providers/ics.rb

@@ -3,7 +3,43 @@
 # lib/cal_invite/providers/ics.rb
 module CalInvite
   module Providers
+    # Generic ICS provider for generating standard iCalendar (.ics) files.
+    # This provider generates ICS files that are compatible with most calendar applications.
+    # Supports all-day events, regular events, and multi-day sessions with proper timezone handling.
+    #
+    # @example Creating a regular event ICS file
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     timezone: 'America/New_York'
+    #   )
+    #   ics = CalInvite::Providers::Ics.new(event)
+    #   ics_content = ics.generate
+    #
+    # @example Creating an all-day event ICS file
+    #   event = CalInvite::Event.new(
+    #     title: "Company Holiday",
+    #     all_day: true,
+    #     start_time: Date.today,
+    #     end_time: Date.today + 1
+    #   )
+    #   ics_content = CalInvite::Providers::Ics.new(event).generate
+    #
+    # @example Creating a multi-day event ICS file
+    #   event = CalInvite::Event.new(
+    #     title: "Conference",
+    #     multi_day_sessions: [
+    #       { start_time: Time.parse("2024-04-01 09:00"), end_time: Time.parse("2024-04-01 17:00") },
+    #       { start_time: Time.parse("2024-04-02 09:00"), end_time: Time.parse("2024-04-02 17:00") }
+    #     ]
+    #   )
+    #   ics_content = CalInvite::Providers::Ics.new(event).generate
     class Ics < BaseProvider
+      # Generates the complete ICS calendar content with proper calendar properties.
+      # Handles all event types: all-day, regular, and multi-day sessions.
+      #
+      # @return [String] The complete ICS calendar content in iCalendar format
       def generate
         calendar_lines = [
           "BEGIN:VCALENDAR",
@@ -29,6 +65,9 @@ module CalInvite
 
       private
 
+      # Generates an all-day event component (VEVENT) with appropriate formatting.
+      #
+      # @return [Array<String>] Array of iCalendar format lines for the all-day event
       def generate_all_day_event
         vevent = [
           "BEGIN:VEVENT",
@@ -38,12 +77,16 @@ module CalInvite
           "DTEND;VALUE=DATE:#{format_date(event.end_time)}",
           "SUMMARY:#{escape_text(event.title)}"
         ]
-
         add_optional_fields(vevent)
         vevent << "END:VEVENT"
         vevent
       end
 
+      # Generates a regular or multi-day session event component (VEVENT).
+      #
+      # @param start_time [Time] The event start time
+      # @param end_time [Time] The event end time
+      # @return [Array<String>] Array of iCalendar format lines for the event
       def generate_vevent(start_time, end_time)
         vevent = [
           "BEGIN:VEVENT",
@@ -53,16 +96,19 @@ module CalInvite
           "DTEND;TZID=#{event.timezone}:#{format_local_timestamp(end_time)}",
           "SUMMARY:#{escape_text(event.title)}"
         ]
-
         add_optional_fields(vevent)
         vevent << "END:VEVENT"
         vevent
       end
 
+      # Adds optional fields to the event component if they exist.
+      # Handles description, location, URL, and attendees.
+      #
+      # @param vevent [Array<String>] The current event lines array
+      # @return [void]
       def add_optional_fields(vevent)
         description_parts = []
         description_parts << format_description if format_description
-
         if description_parts.any?
           vevent << "DESCRIPTION:#{escape_text(description_parts.join('\n\n'))}"
         end
@@ -82,23 +128,43 @@ module CalInvite
         end
       end
 
+      # Formats a time object as an UTC timestamp in iCalendar format.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC timestamp (YYYYMMDDTHHmmSSZ)
       def format_timestamp(time)
         time.utc.strftime("%Y%m%dT%H%M%SZ")
       end
 
+      # Formats a time object as a date string in iCalendar format.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted date (YYYYMMDD)
       def format_date(time)
         time.strftime("%Y%m%d")
       end
 
+      # Formats a time object as a local timestamp in iCalendar format.
+      # Note: Times are expected to be in UTC already.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted local time (YYYYMMDDTHHmmSS)
       def format_local_timestamp(time)
-        # All times are already in UTC, just format them
         time.strftime("%Y%m%dT%H%M%S")
       end
 
+      # Generates a unique identifier for the calendar event.
+      # Format: timestamp-randomhex@cal-invite
+      #
+      # @return [String] The generated UID
       def generate_uid
         "#{Time.now.to_i}-#{SecureRandom.hex(8)}@cal-invite"
       end
 
+      # Escapes special characters in text according to iCalendar spec.
+      #
+      # @param text [String, nil] The text to escape
+      # @return [String] The escaped text, or empty string if input was nil
       def escape_text(text)
         return '' if text.nil?
         text.to_s

data/lib/cal_invite/providers/ics_content.rb

@@ -1,7 +1,35 @@
+# frozen_string_literal: true
+
 # lib/cal_invite/providers/ics_content.rb
 module CalInvite
   module Providers
+    # ICS content provider for generating calendar files in iCalendar format.
+    # This provider focuses on generating standards-compliant ICS content
+    # that can be used directly or wrapped for file download.
+    #
+    # @example Generate ICS content for a single event
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600
+    #   )
+    #   generator = CalInvite::Providers::IcsContent.new(event)
+    #   ics_content = generator.generate
+    #
+    # @example Generate ICS content for a multi-day event
+    #   event = CalInvite::Event.new(
+    #     title: "Conference",
+    #     multi_day_sessions: [
+    #       { start_time: Time.parse("2024-04-01 09:00"), end_time: Time.parse("2024-04-01 17:00") },
+    #       { start_time: Time.parse("2024-04-02 09:00"), end_time: Time.parse("2024-04-02 17:00") }
+    #     ]
+    #   )
+    #   ics_content = CalInvite::Providers::IcsContent.new(event).generate
     class IcsContent < BaseProvider
+      # Generates the complete ICS calendar content with all event details.
+      # Handles both single events and multi-day sessions.
+      #
+      # @return [String] The complete ICS calendar content in iCalendar format
       def generate
         calendar_lines = [
           "BEGIN:VCALENDAR",
@@ -25,6 +53,11 @@ module CalInvite
 
       private
 
+      # Generates a single VEVENT component with proper event properties.
+      #
+      # @param start_time [Time] The event start time
+      # @param end_time [Time] The event end time
+      # @return [Array<String>] Array of iCalendar format lines for the event
       def generate_vevent(start_time, end_time)
         [
           "BEGIN:VEVENT",
@@ -41,14 +74,26 @@ module CalInvite
         ].compact
       end
 
+      # Formats a time object as an UTC timestamp in iCalendar format.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC timestamp (YYYYMMDDTHHmmSSZ)
       def format_timestamp(time)
         time.utc.strftime("%Y%m%dT%H%M%SZ")
       end
 
+      # Generates a unique identifier for the calendar event.
+      # Format: timestamp-randomhex@cal-invite
+      #
+      # @return [String] The generated UID
       def generate_uid
         "#{Time.now.to_i}-#{SecureRandom.hex(8)}@cal-invite"
       end
 
+      # Escapes special characters in text according to iCalendar spec.
+      #
+      # @param text [String, nil] The text to escape
+      # @return [String] The escaped text, or empty string if input was nil
       def escape_text(text)
         return '' if text.nil?
         text.to_s
@@ -58,29 +103,46 @@ module CalInvite
             .gsub(';', '\\;')
       end
 
+      # Generates the DESCRIPTION line if a description exists.
+      #
+      # @return [String, nil] The formatted DESCRIPTION line, or nil if no description
       def description_line
         return nil unless event.description
         "DESCRIPTION:#{escape_text(event.description)}"
       end
 
+      # Generates the LOCATION line if a location exists.
+      #
+      # @return [String, nil] The formatted LOCATION line, or nil if no location
       def location_line
         return nil unless event.location
         "LOCATION:#{escape_text(event.location)}"
       end
 
+      # Generates the URL line if a URL exists.
+      #
+      # @return [String, nil] The formatted URL line, or nil if no URL
       def url_line
         return nil unless event.url
         "URL:#{escape_text(event.url)}"
       end
 
+      # Generates ATTENDEE lines for all attendees if showing attendees is enabled.
+      #
+      # @return [Array<String>, nil] Array of ATTENDEE lines, or nil if no attendees or not showing
       def attendee_lines
         return nil unless event.show_attendees && event.attendees&.any?
         event.attendees.map { |attendee| "ATTENDEE;RSVP=TRUE:mailto:#{attendee}" }
       end
     end
 
-    # Optional download wrapper
+    # Module for handling ICS file downloads with proper headers and file naming.
+    # Provides utility methods for preparing ICS content for HTTP download.
     module IcsDownload
+      # Generates appropriate HTTP headers for ICS file download.
+      #
+      # @param filename [String] The desired filename for the download
+      # @return [Hash] HTTP headers for the ICS file download
       def self.headers(filename)
         {
           'Content-Type' => 'text/calendar; charset=UTF-8',
@@ -88,10 +150,22 @@ module CalInvite
         }
       end
 
+      # Sanitizes a filename by removing potentially problematic characters.
+      #
+      # @param filename [String] The filename to sanitize
+      # @return [String] The sanitized filename
       def self.sanitize_filename(filename)
         filename.gsub(/[^0-9A-Za-z.\-]/, '_')
       end
 
+      # Wraps ICS content with appropriate download information.
+      #
+      # @param content [String] The ICS calendar content
+      # @param title [String] The event title to use in the filename
+      # @return [Hash] Hash containing content and headers for download
+      # @example
+      #   result = IcsDownload.wrap_for_download(ics_content, "team-meeting")
+      #   # => { content: "BEGIN:VCALENDAR...", headers: { 'Content-Type' => '...' } }
       def self.wrap_for_download(content, title)
         filename = sanitize_filename("#{title.downcase}_#{Time.now.strftime('%Y%m%d')}.ics")
         {
@@ -101,11 +175,10 @@ module CalInvite
       end
     end
 
-    # For compatibility, keep the original classes but inherit from IcsContent
-    class Ics < IcsContent
-    end
-
-    class Ical < IcsContent
-    end
+    # Compatibility class aliases
+    # @api private
+    class Ics < IcsContent; end
+    # @api private
+    class Ical < IcsContent; end
   end
 end

data/lib/cal_invite/providers/office365.rb

@@ -3,7 +3,37 @@
 # lib/cal_invite/providers/office365.rb
 module CalInvite
   module Providers
+    # Microsoft Office 365 provider for generating calendar event URLs.
+    # This provider generates URLs that open the Office 365 web calendar
+    # with a pre-filled event creation form. Supports both all-day and
+    # time-specific events with proper timezone handling.
+    #
+    # @example Creating a regular event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     description: "Weekly team sync"
+    #   )
+    #   office365 = CalInvite::Providers::Office365.new(event)
+    #   url = office365.generate
+    #
+    # @example Creating an all-day event URL with attendees
+    #   event = CalInvite::Event.new(
+    #     title: "Company Off-Site",
+    #     all_day: true,
+    #     start_time: Date.today,
+    #     end_time: Date.today + 1,
+    #     attendees: ["john@example.com", "jane@example.com"],
+    #     show_attendees: true
+    #   )
+    #   url = CalInvite::Providers::Office365.new(event).generate
     class Office365 < BaseProvider
+      # Generates an Office 365 calendar URL for the event.
+      # Automatically handles both all-day and time-specific events.
+      #
+      # @return [String] The Office 365 calendar URL
+      # @raise [ArgumentError] If required time fields are missing for non-all-day events
       def generate
         if event.all_day
           generate_all_day_event
@@ -14,6 +44,10 @@ module CalInvite
 
       private
 
+      # Generates a URL for an all-day event.
+      # Uses simplified date format and sets the allday flag.
+      #
+      # @return [String] The Office 365 calendar URL for an all-day event
       def generate_all_day_event
         params = {
           subject: url_encode(event.title),
@@ -27,11 +61,15 @@ module CalInvite
 
         params[:startdt] = url_encode(format_date(start_date))
         params[:enddt] = url_encode(format_date(end_date))
-
         add_optional_params(params)
         build_url(params)
       end
 
+      # Generates a URL for a regular (time-specific) event.
+      # Includes specific start and end times in UTC format.
+      #
+      # @return [String] The Office 365 calendar URL for a regular event
+      # @raise [ArgumentError] If start_time or end_time is missing
       def generate_single_event
         params = {
           subject: url_encode(event.title),
@@ -43,26 +81,38 @@ module CalInvite
 
         params[:startdt] = url_encode(format_time(event.start_time))
         params[:enddt] = url_encode(format_time(event.end_time))
-
         add_optional_params(params)
         build_url(params)
       end
 
+      # Formats a time object as a date string for Office 365.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted date (YYYY-MM-DD)
       def format_date(time)
         time.strftime('%Y-%m-%d')
       end
 
+      # Formats a time object as a UTC timestamp for Office 365.
+      # Office 365 handles timezone conversion on their end.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC time (YYYY-MM-DDThh:mm:ssZ)
       def format_time(time)
         # Always use UTC format, timezone is handled by the calendar
         time.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
       end
 
+      # Adds optional parameters to the URL parameters hash.
+      # Handles description, virtual meeting URL, location, and attendees.
+      #
+      # @param params [Hash] The parameters hash to update
+      # @return [Hash] The updated parameters hash
       def add_optional_params(params)
         description_parts = []
         description_parts << format_description if format_description
         description_parts << "Virtual Meeting URL: #{format_url}" if format_url
         params[:body] = url_encode(description_parts.join("\n\n")) if description_parts.any?
-
         params[:location] = url_encode(format_location) if format_location
 
         if attendees = attendees_list
@@ -72,6 +122,10 @@ module CalInvite
         params
       end
 
+      # Builds the final Office 365 calendar URL.
+      #
+      # @param params [Hash] The parameters to include in the URL
+      # @return [String] The complete Office 365 calendar URL
       def build_url(params)
         query = params.map { |k, v| "#{k}=#{v}" }.join('&')
         "https://outlook.office.com/owa/?#{query}"

data/lib/cal_invite/providers/outlook.rb

@@ -1,8 +1,44 @@
 # frozen_string_literal: true
 
+# lib/cal_invite/providers/outlook.rb
 module CalInvite
   module Providers
+    # Microsoft Outlook Live (outlook.live.com) provider for generating calendar event URLs.
+    # This provider generates URLs that open the Outlook.com web calendar
+    # with a pre-filled event creation form. Supports both all-day and
+    # time-specific events.
+    #
+    # Note: This is for personal Outlook.com accounts. For corporate Office 365,
+    # use the {Office365} provider instead.
+    #
+    # @example Creating a regular event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     description: "Weekly team sync"
+    #   )
+    #   outlook = CalInvite::Providers::Outlook.new(event)
+    #   url = outlook.generate
+    #
+    # @example Creating an all-day event URL with attendees
+    #   event = CalInvite::Event.new(
+    #     title: "Company Holiday",
+    #     all_day: true,
+    #     start_time: Date.today,
+    #     end_time: Date.today + 1,
+    #     attendees: ["john@example.com", "jane@example.com"],
+    #     show_attendees: true
+    #   )
+    #   url = CalInvite::Providers::Outlook.new(event).generate
+    #
+    # @see Office365 For corporate Office 365 calendar URLs
     class Outlook < BaseProvider
+      # Generates an Outlook.com calendar URL for the event.
+      # Automatically handles both all-day and time-specific events.
+      #
+      # @return [String] The Outlook.com calendar URL
+      # @raise [ArgumentError] If required time fields are missing for non-all-day events
       def generate
         if event.all_day
           generate_all_day_event
@@ -13,6 +49,10 @@ module CalInvite
 
       private
 
+      # Generates a URL for an all-day event.
+      # Uses simplified date format and sets the allday flag.
+      #
+      # @return [String] The Outlook.com calendar URL for an all-day event
       def generate_all_day_event
         params = {
           path: '/calendar/0/action/compose',
@@ -20,9 +60,9 @@ module CalInvite
           allday: 'true'
         }
 
+        # Set start and end dates
         start_date = event.start_time || Time.now
         end_date = event.end_time || (start_date + 86400)
-
         params[:startdt] = format_date(start_date)
         params[:enddt] = format_date(end_date)
 
@@ -30,6 +70,11 @@ module CalInvite
         build_url(params)
       end
 
+      # Generates a URL for a regular (time-specific) event.
+      # Includes specific start and end times in UTC format.
+      #
+      # @return [String] The Outlook.com calendar URL for a regular event
+      # @raise [ArgumentError] If start_time or end_time is missing
       def generate_single_event
         params = {
           path: '/calendar/0/action/compose',
@@ -41,26 +86,38 @@ module CalInvite
 
         params[:startdt] = format_time(event.start_time)
         params[:enddt] = format_time(event.end_time)
-
         add_optional_params(params)
         build_url(params)
       end
 
+      # Formats a time object as a date string for Outlook.com.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted date (YYYY-MM-DD)
       def format_date(time)
         time.strftime('%Y-%m-%d')
       end
 
+      # Formats a time object as a UTC timestamp for Outlook.com.
+      # Outlook.com handles timezone conversion on their end.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC time (YYYY-MM-DDThh:mm:ssZ)
       def format_time(time)
         # Always use UTC format, timezone is handled by the calendar
         time.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
       end
 
+      # Adds optional parameters to the URL parameters hash.
+      # Handles description, virtual meeting URL, location, and attendees.
+      #
+      # @param params [Hash] The parameters hash to update
+      # @return [Hash] The updated parameters hash
       def add_optional_params(params)
         description_parts = []
         description_parts << format_description if format_description
         description_parts << "Virtual Meeting URL: #{format_url}" if format_url
         params[:body] = url_encode(description_parts.join("\n\n")) if description_parts.any?
-
         params[:location] = url_encode(format_location) if format_location
 
         if attendees = attendees_list
@@ -70,6 +127,10 @@ module CalInvite
         params
       end
 
+      # Builds the final Outlook.com calendar URL.
+      #
+      # @param params [Hash] The parameters to include in the URL
+      # @return [String] The complete Outlook.com calendar URL
       def build_url(params)
         query = params.map { |k, v| "#{k}=#{v}" }.join('&')
         "https://outlook.live.com/calendar/0/action/compose?#{query}"