cal-invite 0.2.1 → 0.3.0

data/lib/cal_invite/providers/ical.rb

@@ -3,166 +3,21 @@
 # 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.
+    # iCalendar provider (`:ical`), for Apple Calendar and other iCalendar apps.
+    # Produces the same RFC 5545 content as {Ics}; kept as its own provider
+    # symbol for backward compatibility.
     #
-    # @example Creating a regular event
+    # @example
     #   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:#{method_value}",
-          (event.calendar_name ? "X-WR-CALNAME:#{escape_text(event.calendar_name)}" : nil),
-          generate_timezone,
-          generate_events,
-          "END:VCALENDAR"
-        ].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("\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;TZID=#{event.timezone}:#{format_local_time(start_time)}"
-          lines << "DTEND;TZID=#{event.timezone}:#{format_local_time(end_time)}"
-        end
-
-        # Required fields
-        lines.concat([
-          "SUMMARY:#{escape_text(event.title)}",
-          "UID:#{event.uid}",
-          "DTSTAMP:#{format_timestamp(Time.now.utc)}"
-        ])
-
-        # 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
-        lines << geo_line if geo_line
-        lines << organizer_line if organizer_line
-
-        # Attendees
-        attendees_list.each { |attendee| lines << attendee_line(attendee) }
-
-        lines << rrule_line if rrule_line
-        lines << "SEQUENCE:#{event.sequence}"
-        lines << status_line
-        lines << transp_line
-        lines << busystatus_line
-        lines << class_line
-        lines.concat(importance_lines)
-        lines << disallow_counter_line if disallow_counter_line
-        lines.concat(valarm_lines)
-        lines << "END:VEVENT"
-        lines.join("\r\n")
-      end
-
-      # Generates the timezone block (VTIMEZONE) for the calendar, with real
-      # STANDARD/DAYLIGHT observances derived from the timezone's transition rules.
-      # Only included for non-all-day events with a recognized, non-UTC timezone.
-      #
-      # @return [String, nil] The formatted timezone block, or nil if not applicable
-      def generate_timezone
-        return nil if event.all_day # No timezone needed for all-day events
-
-        vtimezone_lines&.join("\r\n")
-      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.
-      # Converts from UTC to the event's timezone; 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_time(time)
-        local_wall_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
+    #
+    # @see Ics
+    class Ical < Ics
     end
   end
 end

data/lib/cal_invite/providers/ics.rb

@@ -7,6 +7,9 @@ module CalInvite
     # 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.
     #
+    # This is the single RFC 5545 generator for the gem: {Ical} and {IcsContent}
+    # are subclasses kept for their public names and produce identical output.
+    #
     # @example Creating a regular event ICS file
     #   event = CalInvite::Event.new(
     #     title: "Team Meeting",
@@ -66,21 +69,60 @@ module CalInvite
         end
 
         calendar_lines << "END:VCALENDAR"
-        calendar_lines.join("\r\n")
+        ensure_single_line_values!(calendar_lines)
+        calendar_lines.map { |line| fold_line(line) }.join("\r\n")
       end
 
       private
 
+      # Maximum content line length in octets, excluding the CRLF (RFC 5545 §3.1).
+      MAX_LINE_OCTETS = 75
+
+      # Folds a content line longer than 75 octets into CRLF + single-space
+      # continuation lines (RFC 5545 §3.1). Splits only between characters, so a
+      # multi-byte UTF-8 character is never cut in half.
+      #
+      # @param line [String] A single unfolded content line
+      # @return [String] The folded line (unchanged if already short enough)
+      def fold_line(line)
+        return line if line.bytesize <= MAX_LINE_OCTETS
+
+        segments = [+""]
+        line.each_char do |char|
+          segments << +" " if segments.last.bytesize + char.bytesize > MAX_LINE_OCTETS
+          segments.last << char
+        end
+        segments.join("\r\n")
+      end
+
+      # Last line of defense against content-line injection: a CR or LF inside a
+      # value would end the line and let the rest of the value be parsed as new
+      # properties/components. TEXT values are escaped before reaching here, so
+      # this only fires for unescaped values (UID, URL, RRULE, emails, ...).
+      #
+      # @param lines [Array<String>] The content lines about to be joined
+      # @raise [ArgumentError] if any line contains a CR or LF
+      # @return [void]
+      def ensure_single_line_values!(lines)
+        line = lines.find { |l| l.match?(/[\r\n]/) }
+        return unless line
+
+        raise ArgumentError, "#{line[/\A[A-Z-]+/]} value must not contain line breaks"
+      end
+
       # Generates an all-day event component (VEVENT) with appropriate formatting.
+      # Defaults to today (and a one-day span) when start/end times are omitted.
       #
       # @return [Array<String>] Array of iCalendar format lines for the all-day event
       def generate_all_day_event
+        start_date = event.start_time || Time.now
+        end_date = event.end_time || (start_date + 86400)
         vevent = [
           "BEGIN:VEVENT",
           "UID:#{event.uid}",
           "DTSTAMP:#{format_timestamp(Time.now.utc)}",
-          "DTSTART;VALUE=DATE:#{format_date(event.start_time)}",
-          "DTEND;VALUE=DATE:#{format_date(event.end_time)}",
+          "DTSTART;VALUE=DATE:#{format_date(start_date)}",
+          "DTEND;VALUE=DATE:#{format_date(end_date)}",
           "SUMMARY:#{escape_text(event.title)}"
         ]
         add_optional_fields(vevent)
@@ -98,8 +140,8 @@ module CalInvite
           "BEGIN:VEVENT",
           "UID:#{event.uid}",
           "DTSTAMP:#{format_timestamp(Time.now.utc)}",
-          "DTSTART;TZID=#{event.timezone}:#{format_local_timestamp(start_time)}",
-          "DTEND;TZID=#{event.timezone}:#{format_local_timestamp(end_time)}",
+          date_time_line("DTSTART", start_time),
+          date_time_line("DTEND", end_time),
           "SUMMARY:#{escape_text(event.title)}"
         ]
         add_optional_fields(vevent)
@@ -125,7 +167,8 @@ module CalInvite
         end
 
         if url = format_url
-          vevent << "URL:#{escape_text(url)}"
+          # URL is a URI value, not TEXT: RFC 5545 escaping would corrupt it.
+          vevent << "URL:#{url}"
         end
 
         vevent << geo_line if geo_line
@@ -137,7 +180,7 @@ module CalInvite
         attendees_list.each { |attendee| vevent << attendee_line(attendee) }
 
         vevent << rrule_line if rrule_line
-        vevent << "SEQUENCE:#{event.sequence}"
+        vevent << sequence_line
         vevent << status_line
         vevent << transp_line
         vevent << busystatus_line
@@ -163,6 +206,20 @@ module CalInvite
         time.strftime("%Y%m%d")
       end
 
+      # Builds a DTSTART/DTEND line: a `Z`-suffixed UTC timestamp for UTC events,
+      # otherwise local wall-clock time referencing the event's VTIMEZONE.
+      #
+      # @param name [String] The property name ("DTSTART" or "DTEND")
+      # @param time [Time] The time to format (UTC)
+      # @return [String] The content line
+      def date_time_line(name, time)
+        if CalInvite::IcalTimezone.utc?(event.timezone)
+          "#{name}:#{format_timestamp(time)}"
+        else
+          "#{name};TZID=#{event.timezone}:#{format_local_timestamp(time)}"
+        end
+      end
+
       # Formats a time object as a local timestamp in iCalendar format.
       # Converts from UTC to the event's timezone; times are expected to be in
       # UTC already.
@@ -173,17 +230,15 @@ module CalInvite
         local_wall_time(time).strftime("%Y%m%dT%H%M%S")
       end
 
-      # Escapes special characters in text according to iCalendar spec.
+      # Escapes a TEXT value per RFC 5545 §3.3.11: backslash, semicolon and comma
+      # are backslash-escaped, and any line break (CRLF, CR or LF) becomes `\n`.
       #
       # @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(';', '\\;')
+
+        text.to_s.gsub(/\r\n|[\r\n\\;,]/) { |match| match.match?(/[\r\n]/) ? '\\n' : "\\#{match}" }
       end
     end
   end

data/lib/cal_invite/providers/ics_content.rb

@@ -3,142 +3,20 @@
 # 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.
+    # ICS content provider, for generating `.ics` content directly (outside
+    # Event#generate_calendar_url). Produces the same RFC 5545 content as {Ics};
+    # kept for backward compatibility. Pair with {IcsDownload} to serve it as a file.
     #
-    # @example Generate ICS content for a single event
+    # @example
     #   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:#{method_value}"
-        ]
-
-        calendar_lines << "X-WR-CALNAME:#{escape_text(event.calendar_name)}" if event.calendar_name
-
-        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:#{event.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,
-          geo_line,
-          organizer_line,
-          attendee_lines,
-          rrule_line,
-          "SEQUENCE:#{event.sequence}",
-          status_line,
-          transp_line,
-          busystatus_line,
-          class_line,
-          importance_lines,
-          disallow_counter_line,
-          valarm_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
-
-      # 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 if attendees_list.empty?
-        attendees_list.map { |attendee| attendee_line(attendee) }
-      end
+    #
+    # @see Ics
+    class IcsContent < Ics
     end
 
     # Module for handling ICS file downloads with proper headers and file naming.

data/lib/cal_invite/providers.rb

@@ -22,3 +22,11 @@ module CalInvite
     autoload :Ics, 'cal_invite/providers/ics'
   end
 end
+
+# Deprecated top-level alias, kept for one release so code that referenced
+# ::BaseProvider keeps working. Skipped if the host app defines its own.
+# Remove in 0.4.0.
+unless Object.const_defined?(:BaseProvider, false)
+  BaseProvider = CalInvite::Providers::BaseProvider
+  Object.deprecate_constant(:BaseProvider)
+end

data/lib/cal_invite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CalInvite
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/cal_invite.rb

@@ -3,14 +3,12 @@ require 'logger'
 require 'mutex_m'
 require 'bigdecimal'
 require 'active_support'
-require 'active_support/core_ext'
 require 'securerandom'
 require 'time'
 require 'uri'
 
 require 'cal_invite/version'
 require 'cal_invite/configuration'
-require 'cal_invite/caching'
 require 'cal_invite/ical_timezone'
 require 'cal_invite/event'
 require 'cal_invite/providers'
@@ -21,7 +19,6 @@ require 'cal_invite/providers'
 # @example Configure the gem
 #   CalInvite.configure do |config|
 #     config.timezone = 'America/New_York'
-#     config.cache_store = :memory_store
 #   end
 #
 # @example Create and generate a calendar URL
@@ -49,8 +46,7 @@ module CalInvite
     # @example
     #   CalInvite.configure do |config|
     #     config.timezone = 'UTC'
-    #     config.cache_store = :memory_store
-    #   end
+        #   end
     def configure
       self.configuration ||= Configuration.new
       yield(configuration)
@@ -62,8 +58,5 @@ module CalInvite
     def reset_configuration!
       self.configuration = Configuration.new
     end
-
-    # Include caching methods at the module level
-    include Caching
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cal-invite
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Stephane Paquet
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -102,26 +102,21 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".DS_Store"
 - ".rdoc_options"
 - ".rubocop.yml"
 - AGENTS.md
-- CACHING.md
 - CHANGELOG.md
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - CONFIGURATION.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - SECURITY.md
+- assets/social/cal-invite-github.png
 - gemfiles/Gemfile.rails6
 - gemfiles/Gemfile.rails7
 - gemfiles/Gemfile.rails8
-- lib/.DS_Store
 - lib/cal_invite.rb
-- lib/cal_invite/.DS_Store
-- lib/cal_invite/caching.rb
 - lib/cal_invite/configuration.rb
 - lib/cal_invite/event.rb
 - lib/cal_invite/ical_timezone.rb