cal-invite 0.2.1 → 0.3.1

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.1"
 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.1
 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,13 +102,11 @@ 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
@@ -118,10 +116,7 @@ files:
 - 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
@@ -135,7 +130,6 @@ files:
 - lib/cal_invite/providers/outlook.rb
 - lib/cal_invite/providers/yahoo.rb
 - lib/cal_invite/version.rb
-- lib/tasks/rdoc.rake
 - sig/cal/invite.rbs
 homepage: https://github.com/DashAPI-ai/cal-invite
 licenses:
@@ -143,7 +137,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/DashAPI-ai/cal-invite
   source_code_uri: https://github.com/DashAPI-ai/cal-invite
-  changelog_uri: https://github.com/DashAPI-ai/cal-invite/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/DashAPI-ai/cal-invite/blob/main/CHANGELOG.md
+  documentation_uri: https://dashapi-ai.github.io/cal-invite/
 post_install_message:
 rdoc_options:
 - "--title"

data/CLAUDE.md

@@ -1,49 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Overview
-
-CalInvite is a Ruby gem for generating calendar invitations (URLs and .ics files) across multiple platforms: Google, Outlook, Outlook 365, Yahoo, Apple iCal, and generic .ics. Ruby >= 3.0.0, Rails 6.0–8.0 compatible, depends on `activesupport`.
-
-## Commands
-
-```bash
-bundle install          # install dependencies
-rake test                # run full test suite (default rake task)
-rake test TEST=test/cal_invite/event_test.rb   # run a single test file
-ruby -Itest -Ilib test/cal_invite/event_test.rb # run a single test file directly
-rake rdoc                # generate RDoc documentation into doc/
-rake rdoc:clean          # remove generated doc/
-```
-
-Tests are Minitest-based, files live under `test/cal_invite/`, named `*_test.rb`. Coverage is collected via SimpleCov (see `coverage/`).
-
-## Architecture
-
-- **`CalInvite` module** (`lib/cal_invite.rb`) — top-level entry point. Holds a singleton `CalInvite.configuration` (a `Configuration` instance) set via `CalInvite.configure { |c| ... }`. Mixes in `Caching` at the module level for class-level cache helpers.
-
-- **`CalInvite::Event`** (`lib/cal_invite/event.rb`) — the central object. Holds all event attributes (title, start/end time, location, url, attendees, timezone, notes, multi-day sessions, all-day flag). `generate_calendar_url(provider)` is the main API: it validates the event, checks the cache (MD5 hash of all attributes + provider as key), and if not cached, resolves `CalInvite::Providers::<CapitalizedProvider>`, instantiates it with `self`, and calls `#generate`. Location and virtual-meeting URL are intentionally separate fields (not merged) so each provider can format them appropriately.
-
-- **`CalInvite::Providers`** (`lib/cal_invite/providers.rb`) — namespace with `SUPPORTED_PROVIDERS = %i[google ical outlook yahoo ics office365]`. Provider classes are autoloaded from `lib/cal_invite/providers/*.rb`. To add a new provider: create a class extending `BaseProvider`, implement `#generate`, register it here with `autoload`, and add its symbol to `SUPPORTED_PROVIDERS`.
-
-- **`BaseProvider`** (`lib/cal_invite/providers/base_provider.rb`) — abstract base class (note: it's a top-level `class BaseProvider`, not namespaced under `CalInvite::Providers`). Defines the `#generate` contract (must raise `NotImplementedError` if not overridden) plus shared helpers used by subclasses: URL-building (`url_encode`, `format_description`, `format_location`, `format_url`, `format_description_with_url`, `add_optional_params`) and iCalendar property formatting (`attendees_list`, `attendee_emails`, `attendee_hash_value`, `attendee_line`, `organizer_line`, `method_value`, `status_line`, `geo_line`, `transp_line`, `busystatus_line`, `class_line`, `importance_lines`, `disallow_counter_line`, `rrule_line`, `valarm_lines`, `local_wall_time`, `vtimezone_lines`). `attendee_hash_value(attendee, key)` is the correct way to read an attendee-hash field (tries symbol then string key) — don't reintroduce `attendee[:key] || attendee["key"]`, which silently drops explicit `false` values. Each concrete provider (`Google`, `Outlook`, `Office365`, `Yahoo`, `Ical`, `Ics`) builds a provider-specific URL or content string from the `Event` using these helpers.
-
-- **`Ics` / `IcsContent` providers** (`ics.rb`, `ics_content.rb`) — generate actual `.ics` file content (RFC 5545) rather than a URL, for direct download flows (see README's `send_data` controller example). `IcsDownload` lives in `ics_content.rb` alongside `IcsContent` (not an alias). All ics-family providers accept a `method:` (`:publish`/`:request`/`:cancel`/`:reply`/`:counter`/`:decline_counter`) passed through `Event#generate_calendar_url`. Use `BaseProvider#method_value` (not `method.to_s.upcase`) when emitting the `METHOD:` line — `:decline_counter` must render as `METHOD:DECLINECOUNTER` (one word) per RFC 5545, unlike its Ruby symbol. `:request` plus `Event#organizer` produces an RFC 5545 meeting request that mail clients render with RSVP actions; `:cancel` (reusing the same `Event#uid`, with `Event#sequence` bumped) produces a real cancellation; `:reply`/`:counter`/`:decline_counter` all omit `RSVP=TRUE` on `ATTENDEE` lines (none of them request a further response). `Event#uid` is stable (auto-generated and memoized per instance, or pass your own) — required so a later `:request`/`:cancel` is recognized as updating the original invite rather than creating a new one. `Event#attendees` entries can be plain email strings or `{ email:, name:, partstat:, rsvp: }` hashes (`partstat:` drives `PARTSTAT=` on the `ATTENDEE` line, default `NEEDS-ACTION`; `rsvp:` overrides the method-derived `RSVP=TRUE`/absent default — needed for e.g. a registration-confirmation invite where the attendee is already `:accepted` and `rsvp: false` suppresses it under `method: :request`). Optional `Event` fields `geo`, `reminders`, `busy`, `visibility`, `rrule`, `calendar_name` map to `GEO:`, `VALARM`, `TRANSP:`, `CLASS:`, `RRULE:`, and `X-WR-CALNAME` respectively; `importance`/`allow_counter` map to Outlook's non-standard `X-MICROSOFT-CDO-IMPORTANCE`/`X-MICROSOFT-DISALLOW-COUNTER` (plus standard `PRIORITY:` and `X-MICROSOFT-CDO-BUSYSTATUS` alongside `TRANSP:`) — safe to always emit since unrecognized `X-` properties are required to be ignored by other clients. See `CONFIGURATION.md`.
-- **Timezones** — `:ics`/`:ical` build a real `VTIMEZONE` (via `CalInvite::IcalTimezone`, backed by `tzinfo`) for any recognized IANA `timezone` other than `'UTC'`, and correctly convert `start_time`/`end_time` (always UTC) to that zone's local wall-clock time for `DTSTART;TZID=...`. `'UTC'` uses plain `Z`-suffixed timestamps with no `VTIMEZONE`.
-
-- **`Caching`** (`lib/cal_invite/caching.rb`) — an `ActiveSupport::Concern` mixed into `CalInvite` at the class level. Provides `fetch_from_cache`, `write_to_cache`, `read_from_cache`, `clear_cache!`, `clear_event_cache!`, `clear_provider_cache!`, all keyed under `CalInvite.configuration.cache_prefix`. Works with any `ActiveSupport::Cache::Store`-compatible store, or a custom object responding to `read`/`write`/`delete`. See also `CACHING.md`.
-
-- **`Configuration`** (`lib/cal_invite/configuration.rb`) — holds `cache_store`, `cache_prefix` (default `'cal_invite'`), `cache_expires_in` (default 24 hours), `webhook_secret`, `timezone` (default `'UTC'`). `cache_store=` accepts `:memory_store`, `:null_store`, or any object implementing `read`/`write`/`delete`.
-
-## Conventions
-
-- Always pass times to `Event.new` in UTC; use the `timezone` attribute only to control display/formatting in the generated invite.
-- `location` (physical) and `url` (virtual meeting link) are kept as distinct fields throughout the provider layer — don't conflate them when adding provider logic.
-- All-day events skip `start_time`/`end_time` validation; multi-day events use the separate `multi_day_sessions` array instead of `start_time`/`end_time`.
-- YARD-style doc comments (`@param`, `@return`, `@example`) are used throughout `lib/` and feed the RDoc-generated docs published to GitHub Pages (`.github/workflows/documentation.yml`) — keep them accurate when changing public method signatures.
-- CalInvite is outbound-only: it renders `.ics` content/URLs and has no concept of inbound RSVP replies. It also can't express Google/Microsoft Calendar-API-only concepts like guest permissions (`guestsCanInviteOthers` etc.) since those have no `.ics`/URL representation at all — but it does generate the genuinely protocol-level equivalents that exist: `METHOD:COUNTER`/`DECLINECOUNTER` and Outlook's `X-MICROSOFT-*` extensions (`allow_counter`, `importance`, `busy`). See CONFIGURATION.md's "Tracking RSVPs" and "Guest permissions" sections for the full breakdown of what's real vs. not addable, and why.
-
-## Example app (`Example/calendar_app`)
-
-Rails 8.1 app demonstrating the gem. Its Gemfile depends on the **published** `cal-invite` gem (never commit it pointing at `path: "../.."`) — when testing example-app changes that rely on unreleased gem code (like the `Meeting` demo below, which needs the still-unreleased 0.2.0), temporarily uncomment the `path: "../.."` line locally, `bundle install`, test, then revert the Gemfile and re-run `bundle install` against rubygems before committing. `Meeting`/`MeetingAttendee` (with a migration) is a working reference implementation of the `uid`/`sequence` persistence pattern CONFIGURATION.md describes — see `app/models/meeting.rb`, `app/controllers/meetings_controller.rb` (create/reschedule/cancel), and `app/controllers/event_replies_controller.rb` (illustrative inbound `METHOD:REPLY` parsing, not wired to a real inbound-email provider). This demo won't actually run against the currently-published gem until 0.2.0 ships.