cal-invite 0.1.2 → 0.1.4

data/lib/cal_invite/providers/ical.rb

@@ -3,75 +3,166 @@
 # 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",
           "VERSION:2.0",
           "PRODID:-//CalInvite//Ruby//EN",
+          "CALSCALE:GREGORIAN",
+          "METHOD:PUBLISH",
+          generate_timezone,
           generate_events,
           "END:VCALENDAR"
-        ].join("\n")
+        ].compact.join("\r\n")
       end
 
       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("\n")
+          event.multi_day_sessions.map { |session| generate_vevent(session) }.join("\r\n")
         else
           generate_vevent
         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:#{format_time(start_time)}"
-          lines << "DTEND:#{format_time(end_time)}"
+          lines << "DTSTART;TZID=#{event.timezone}:#{format_local_time(start_time)}"
+          lines << "DTEND;TZID=#{event.timezone}:#{format_local_time(end_time)}"
         end
 
+        # Required fields
         lines.concat([
-          "SUMMARY:#{event.title}",
-          "UID:#{generate_uid}"
+          "SUMMARY:#{escape_text(event.title)}",
+          "UID:#{generate_uid}",
+          "DTSTAMP:#{format_timestamp(Time.now.utc)}"
         ])
 
-        lines << "DESCRIPTION:#{format_description}" if format_description
-        lines << "LOCATION:#{format_location}" if format_location
+        # Optional fields
+        lines << "DESCRIPTION:#{escape_text(format_description)}" if format_description
+        lines << "LOCATION:#{escape_text(format_location)}" if format_location
+        lines << "URL:#{escape_text(format_url)}" if format_url
 
+        # Attendees
         if attendees = attendees_list
           attendees.each do |attendee|
-            lines << "ATTENDEE:mailto:#{attendee}"
+            lines << "ATTENDEE;RSVP=TRUE:mailto:#{attendee}"
           end
         end
 
         lines << "END:VEVENT"
-        lines.join("\n")
+        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}",
+          "END:VTIMEZONE"
+        ].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
-        SecureRandom.uuid
+        "#{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
 
-      def format_time(time)
-        time.utc.strftime("%Y%m%dT%H%M%SZ")
+      # 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)
+        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')
+            .gsub(',', '\\,')
+            .gsub(';', '\\;')
       end
     end
   end

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",
@@ -13,8 +49,9 @@ module CalInvite
           "METHOD:PUBLISH"
         ]
 
-        # Add events (either single or multiple sessions)
-        if event.multi_day_sessions.any?
+        if event.all_day
+          calendar_lines.concat(generate_all_day_event)
+        elsif event.multi_day_sessions.any?
           event.multi_day_sessions.each do |session|
             calendar_lines.concat(generate_vevent(session[:start_time], session[:end_time]))
           end
@@ -28,62 +65,114 @@ 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",
+          "UID:#{generate_uid}",
+          "DTSTAMP:#{format_timestamp(Time.now.utc)}",
+          "DTSTART;VALUE=DATE:#{format_date(event.start_time)}",
+          "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",
           "UID:#{generate_uid}",
-          "DTSTAMP:#{format_timestamp(Time.now)}",
+          "DTSTAMP:#{format_timestamp(Time.now.utc)}",
           "DTSTART;TZID=#{event.timezone}:#{format_local_timestamp(start_time)}",
           "DTEND;TZID=#{event.timezone}:#{format_local_timestamp(end_time)}",
           "SUMMARY:#{escape_text(event.title)}"
         ]
+        add_optional_fields(vevent)
+        vevent << "END:VEVENT"
+        vevent
+      end
 
-        # Add description (including notes if present)
-        if desc = format_description
-          vevent << "DESCRIPTION:#{escape_text(desc)}"
+      # 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
 
-        # Add location and/or URL
-        if event.location
-          vevent << "LOCATION:#{escape_text(event.location)}"
+        if location = format_location
+          vevent << "LOCATION:#{escape_text(location)}"
         end
 
-        if event.url
-          vevent << "URL:#{escape_text(event.url)}"
+        if url = format_url
+          vevent << "URL:#{escape_text(url)}"
         end
 
-        # Add attendees if showing is enabled
         if attendees_list.any?
           attendees_list.each do |attendee|
             vevent << "ATTENDEE;RSVP=TRUE:mailto:#{attendee}"
           end
         end
-
-        vevent << "END:VEVENT"
-        vevent
       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)
-        event.localize_time(time).strftime("%Y%m%dT%H%M%S")
+        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
             .gsub('\\', '\\\\')
             .gsub("\n", '\\n')
             .gsub(',', '\\,')
             .gsub(';', '\\;')
-        end
+      end
     end
   end
 end

data/lib/cal_invite/providers/ics_content.rb

@@ -0,0 +1,184 @@
+# 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",
+          "VERSION:2.0",
+          "PRODID:-//CalInvite//EN",
+          "CALSCALE:GREGORIAN",
+          "METHOD:PUBLISH"
+        ]
+
+        if event.multi_day_sessions.any?
+          event.multi_day_sessions.each do |session|
+            calendar_lines.concat(generate_vevent(session[:start_time], session[:end_time]))
+          end
+        else
+          calendar_lines.concat(generate_vevent(event.start_time, event.end_time))
+        end
+
+        calendar_lines << "END:VCALENDAR"
+        calendar_lines.join("\r\n")
+      end
+
+      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",
+          "UID:#{generate_uid}",
+          "DTSTAMP:#{format_timestamp(Time.now.utc)}",
+          "DTSTART:#{format_timestamp(start_time)}",
+          "DTEND:#{format_timestamp(end_time)}",
+          "SUMMARY:#{escape_text(event.title)}",
+          description_line,
+          location_line,
+          url_line,
+          attendee_lines,
+          "END:VEVENT"
+        ].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
+            .gsub('\\', '\\\\')
+            .gsub("\n", '\\n')
+            .gsub(',', '\\,')
+            .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
+
+    # 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',
+          'Content-Disposition' => "attachment; filename=#{sanitize_filename(filename)}"
+        }
+      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")
+        {
+          content: content,
+          headers: headers(filename)
+        }
+      end
+    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,27 +81,39 @@ 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)
-        time.utc.strftime('%Y-%m-%dT%H:%M:%S')
+        # 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)
-        if description = format_description
-          params[:body] = url_encode(description)
-        end
-
-        if location = format_location
-          params[:location] = url_encode(location)
-        end
+        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
           params[:to] = url_encode(attendees.join(';'))
@@ -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}"