protocol-caldav 1.0.0

data/lib/protocol/caldav/filter/parser.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require 'rexml/document'
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Filter
+      module Parser
+        CALDAV_NS  = Constants::CALDAV_NS
+        CARDDAV_NS = Constants::CARDDAV_NS
+
+        module_function
+
+        def parse_calendar(xml_string)
+          return nil if xml_string.nil? || xml_string.strip.empty?
+
+          doc = REXML::Document.new(xml_string)
+          ns = { 'c' => CALDAV_NS }
+
+          filter_el = REXML::XPath.first(doc, './/c:filter', ns)
+          return nil unless filter_el
+
+          comp_el = REXML::XPath.first(filter_el, 'c:comp-filter', ns)
+          return nil unless comp_el
+
+          parse_comp_filter(comp_el, ns)
+        rescue REXML::ParseException => e
+          raise ParseError, "Malformed XML: #{e.message}"
+        end
+
+        def parse_addressbook(xml_string)
+          return nil if xml_string.nil? || xml_string.strip.empty?
+
+          doc = REXML::Document.new(xml_string)
+          ns = { 'cr' => CARDDAV_NS }
+
+          filter_el = REXML::XPath.first(doc, './/cr:filter', ns)
+          return nil unless filter_el
+
+          test = filter_el.attributes['test'] || 'anyof'
+          prop_filters = REXML::XPath.match(filter_el, 'cr:prop-filter', ns).map do |el|
+            parse_addressbook_prop_filter(el, ns)
+          end
+
+          Addressbook::Filter.new(test: test, prop_filters: prop_filters)
+        rescue REXML::ParseException => e
+          raise ParseError, "Malformed XML: #{e.message}"
+        end
+
+        # --- Private helpers ---
+
+        def parse_comp_filter(el, ns)
+          name = el.attributes['name']
+          raise ParseError, "comp-filter missing required 'name' attribute" unless name
+
+          is_not_defined = REXML::XPath.first(el, 'c:is-not-defined', ns) != nil
+          time_range = parse_time_range(REXML::XPath.first(el, 'c:time-range', ns))
+
+          prop_filters = REXML::XPath.match(el, 'c:prop-filter', ns).map do |pf_el|
+            parse_prop_filter(pf_el, ns)
+          end
+
+          comp_filters = REXML::XPath.match(el, 'c:comp-filter', ns).map do |cf_el|
+            parse_comp_filter(cf_el, ns)
+          end
+
+          Calendar::CompFilter.new(
+            name: name,
+            is_not_defined: is_not_defined,
+            time_range: time_range,
+            prop_filters: prop_filters,
+            comp_filters: comp_filters
+          )
+        end
+
+        def parse_prop_filter(el, ns)
+          name = el.attributes['name']
+          raise ParseError, "prop-filter missing required 'name' attribute" unless name
+
+          is_not_defined = REXML::XPath.first(el, 'c:is-not-defined', ns) != nil
+          time_range = parse_time_range(REXML::XPath.first(el, 'c:time-range', ns))
+          text_match = parse_text_match(REXML::XPath.first(el, 'c:text-match', ns))
+
+          param_filters = REXML::XPath.match(el, 'c:param-filter', ns).map do |pf_el|
+            parse_param_filter(pf_el, ns)
+          end
+
+          Calendar::PropFilter.new(
+            name: name,
+            is_not_defined: is_not_defined,
+            time_range: time_range,
+            text_match: text_match,
+            param_filters: param_filters
+          )
+        end
+
+        def parse_param_filter(el, ns)
+          name = el.attributes['name']
+          is_not_defined = REXML::XPath.first(el, 'c:is-not-defined', ns) != nil
+          text_match = parse_text_match(REXML::XPath.first(el, 'c:text-match', ns))
+
+          Calendar::ParamFilter.new(name: name, is_not_defined: is_not_defined, text_match: text_match)
+        end
+
+        def parse_text_match(el)
+          return nil unless el
+
+          Calendar::TextMatch.new(
+            value: el.text&.strip || '',
+            collation: el.attributes['collation'] || 'i;ascii-casemap',
+            match_type: el.attributes['match-type'] || 'contains',
+            negate_condition: el.attributes['negate-condition'] == 'yes'
+          )
+        end
+
+        def parse_time_range(el)
+          return nil unless el
+
+          Calendar::TimeRange.new(
+            start_time: el.attributes['start'],
+            end_time: el.attributes['end']
+          )
+        end
+
+        def parse_addressbook_prop_filter(el, ns)
+          name = el.attributes['name']
+          raise ParseError, "prop-filter missing required 'name' attribute" unless name
+
+          is_not_defined = REXML::XPath.first(el, 'cr:is-not-defined', ns) != nil
+          text_match_el = REXML::XPath.first(el, 'cr:text-match', ns)
+          text_match = if text_match_el
+            Addressbook::TextMatch.new(
+              value: text_match_el.text&.strip || '',
+              collation: text_match_el.attributes['collation'] || 'i;ascii-casemap',
+              match_type: text_match_el.attributes['match-type'] || 'contains',
+              negate_condition: text_match_el.attributes['negate-condition'] == 'yes'
+            )
+          end
+
+          param_filters = REXML::XPath.match(el, 'cr:param-filter', ns).map do |pf_el|
+            pf_name = pf_el.attributes['name']
+            pf_is_not_defined = REXML::XPath.first(pf_el, 'cr:is-not-defined', ns) != nil
+            pf_text_match_el = REXML::XPath.first(pf_el, 'cr:text-match', ns)
+            pf_text_match = if pf_text_match_el
+              Addressbook::TextMatch.new(
+                value: pf_text_match_el.text&.strip || '',
+                collation: pf_text_match_el.attributes['collation'] || 'i;ascii-casemap',
+                match_type: pf_text_match_el.attributes['match-type'] || 'contains',
+                negate_condition: pf_text_match_el.attributes['negate-condition'] == 'yes'
+              )
+            end
+            Addressbook::ParamFilter.new(name: pf_name, is_not_defined: pf_is_not_defined, text_match: pf_text_match)
+          end
+
+          Addressbook::PropFilter.new(
+            name: name,
+            is_not_defined: is_not_defined,
+            text_match: text_match,
+            param_filters: param_filters
+          )
+        end
+
+        private_class_method :parse_comp_filter, :parse_prop_filter, :parse_param_filter,
+                             :parse_text_match, :parse_time_range, :parse_addressbook_prop_filter
+      end
+    end
+
+    class ParseError < StandardError; end
+  end
+end
+
+
+test do
+  describe "Protocol::Caldav::Filter::Parser" do
+    describe "calendar parser" do
+      it "parses a single comp-filter" do
+        xml = '<c:filter xmlns:c="urn:ietf:params:xml:ns:caldav"><c:comp-filter name="VCALENDAR"/></c:filter>'
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        f.name.should.equal "VCALENDAR"
+      end
+
+      it "parses nested comp-filters" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:comp-filter name="VEVENT"/>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        f.comp_filters.length.should.equal 1
+        f.comp_filters[0].name.should.equal "VEVENT"
+      end
+
+      it "parses is-not-defined" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:comp-filter name="VTODO"><c:is-not-defined/></c:comp-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        f.comp_filters[0].is_not_defined.should.equal true
+      end
+
+      it "parses prop-filter with no children as defined-only check" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:prop-filter name="SUMMARY"/>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        f.prop_filters.length.should.equal 1
+        f.prop_filters[0].name.should.equal "SUMMARY"
+        f.prop_filters[0].text_match.should.be.nil
+      end
+
+      it "parses text-match with default collation and match-type" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:prop-filter name="SUMMARY">
+                <c:text-match>Meeting</c:text-match>
+              </c:prop-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        tm = f.prop_filters[0].text_match
+        tm.value.should.equal "Meeting"
+        tm.collation.should.equal "i;ascii-casemap"
+        tm.match_type.should.equal "contains"
+      end
+
+      it "parses text-match with explicit attributes" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:prop-filter name="SUMMARY">
+                <c:text-match collation="i;octet" match-type="equals">X</c:text-match>
+              </c:prop-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        tm = Protocol::Caldav::Filter::Parser.parse_calendar(xml).prop_filters[0].text_match
+        tm.collation.should.equal "i;octet"
+        tm.match_type.should.equal "equals"
+      end
+
+      it "parses negate-condition" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:prop-filter name="SUMMARY">
+                <c:text-match negate-condition="yes">X</c:text-match>
+              </c:prop-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        tm = Protocol::Caldav::Filter::Parser.parse_calendar(xml).prop_filters[0].text_match
+        tm.negate_condition.should.equal true
+      end
+
+      it "parses time-range with start and end" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:comp-filter name="VEVENT">
+                <c:time-range start="20260101T000000Z" end="20260201T000000Z"/>
+              </c:comp-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        tr = Protocol::Caldav::Filter::Parser.parse_calendar(xml).comp_filters[0].time_range
+        tr.start_time.should.equal "20260101T000000Z"
+        tr.end_time.should.equal "20260201T000000Z"
+      end
+
+      it "parses time-range with only start" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:comp-filter name="VEVENT">
+                <c:time-range start="20260101T000000Z"/>
+              </c:comp-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        tr = Protocol::Caldav::Filter::Parser.parse_calendar(xml).comp_filters[0].time_range
+        tr.start_time.should.equal "20260101T000000Z"
+        tr.end_time.should.be.nil
+      end
+
+      it "returns nil for missing filter element" do
+        Protocol::Caldav::Filter::Parser.parse_calendar('<d:propfind xmlns:d="DAV:"/>').should.be.nil
+      end
+
+      it "returns nil for empty filter" do
+        Protocol::Caldav::Filter::Parser.parse_calendar('<c:filter xmlns:c="urn:ietf:params:xml:ns:caldav"/>').should.be.nil
+      end
+
+      it "returns nil for nil input" do
+        Protocol::Caldav::Filter::Parser.parse_calendar(nil).should.be.nil
+      end
+
+      it "accepts any namespace prefix bound to caldav NS" do
+        xml = '<cal:filter xmlns:cal="urn:ietf:params:xml:ns:caldav"><cal:comp-filter name="VCALENDAR"/></cal:filter>'
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        f.name.should.equal "VCALENDAR"
+      end
+
+      it "parses param-filter inside prop-filter" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:comp-filter name="VEVENT">
+                <c:prop-filter name="ATTENDEE">
+                  <c:param-filter name="PARTSTAT">
+                    <c:text-match>ACCEPTED</c:text-match>
+                  </c:param-filter>
+                </c:prop-filter>
+              </c:comp-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        pf = f.comp_filters[0].prop_filters[0]
+        pf.name.should.equal "ATTENDEE"
+        pf.param_filters.length.should.equal 1
+        pf.param_filters[0].name.should.equal "PARTSTAT"
+        pf.param_filters[0].text_match.value.should.equal "ACCEPTED"
+      end
+
+      it "parses param-filter with is-not-defined" do
+        xml = <<~XML
+          <c:filter xmlns:c="urn:ietf:params:xml:ns:caldav">
+            <c:comp-filter name="VCALENDAR">
+              <c:comp-filter name="VEVENT">
+                <c:prop-filter name="ATTENDEE">
+                  <c:param-filter name="PARTSTAT">
+                    <c:is-not-defined/>
+                  </c:param-filter>
+                </c:prop-filter>
+              </c:comp-filter>
+            </c:comp-filter>
+          </c:filter>
+        XML
+        f = Protocol::Caldav::Filter::Parser.parse_calendar(xml)
+        pf = f.comp_filters[0].prop_filters[0].param_filters[0]
+        pf.is_not_defined.should.equal true
+      end
+
+      it "raises on comp-filter with no name attribute" do
+        xml = '<c:filter xmlns:c="urn:ietf:params:xml:ns:caldav"><c:comp-filter/></c:filter>'
+        lambda { Protocol::Caldav::Filter::Parser.parse_calendar(xml) }.should.raise Protocol::Caldav::ParseError
+      end
+    end
+
+    describe "addressbook parser" do
+      it "parses a prop-filter" do
+        xml = '<cr:filter xmlns:cr="urn:ietf:params:xml:ns:carddav"><cr:prop-filter name="FN"/></cr:filter>'
+        f = Protocol::Caldav::Filter::Parser.parse_addressbook(xml)
+        f.prop_filters.length.should.equal 1
+        f.prop_filters[0].name.should.equal "FN"
+      end
+
+      it "parses test attribute on filter" do
+        xml = '<cr:filter xmlns:cr="urn:ietf:params:xml:ns:carddav" test="allof"><cr:prop-filter name="FN"/></cr:filter>'
+        f = Protocol::Caldav::Filter::Parser.parse_addressbook(xml)
+        f.test.should.equal "allof"
+      end
+
+      it "defaults test to anyof" do
+        xml = '<cr:filter xmlns:cr="urn:ietf:params:xml:ns:carddav"><cr:prop-filter name="FN"/></cr:filter>'
+        f = Protocol::Caldav::Filter::Parser.parse_addressbook(xml)
+        f.test.should.equal "anyof"
+      end
+
+      it "returns nil for nil input" do
+        Protocol::Caldav::Filter::Parser.parse_addressbook(nil).should.be.nil
+      end
+    end
+  end
+end

data/lib/protocol/caldav/ical/component.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Ical
+      Component = Struct.new(:name, :properties, :components, keyword_init: true) do
+        def initialize(name:, properties: [], components: [])
+          super(name: name, properties: properties, components: components)
+        end
+
+        def find_property(prop_name)
+          properties.find { |p| p.name.casecmp?(prop_name) }
+        end
+
+        def find_all_properties(prop_name)
+          properties.select { |p| p.name.casecmp?(prop_name) }
+        end
+
+        def find_components(comp_name)
+          components.select { |c| c.name.casecmp?(comp_name) }
+        end
+      end
+    end
+  end
+end
+
+test do
+  describe "Protocol::Caldav::Ical::Component" do
+    def prop(name, value, params: {})
+      Protocol::Caldav::Ical::Property.new(name: name, params: params, value: value)
+    end
+
+    def comp(name, properties: [], components: [])
+      Protocol::Caldav::Ical::Component.new(name: name, properties: properties, components: components)
+    end
+
+    it "find_property returns the first property with that name" do
+      c = comp("VEVENT", properties: [prop("SUMMARY", "First"), prop("SUMMARY", "Second")])
+      c.find_property("SUMMARY").value.should.equal "First"
+    end
+
+    it "find_property is case-insensitive" do
+      c = comp("VEVENT", properties: [prop("SUMMARY", "Hello")])
+      c.find_property("summary").value.should.equal "Hello"
+    end
+
+    it "find_property returns nil when absent" do
+      c = comp("VEVENT", properties: [])
+      c.find_property("SUMMARY").should.be.nil
+    end
+
+    it "find_components returns all matching children" do
+      c = comp("VCALENDAR", components: [comp("VEVENT"), comp("VTODO"), comp("VEVENT")])
+      c.find_components("VEVENT").length.should.equal 2
+    end
+
+    it "find_components returns empty array when none match" do
+      c = comp("VCALENDAR", components: [comp("VEVENT")])
+      c.find_components("VTODO").should.equal []
+    end
+
+    it "find_components does not recurse into grandchildren" do
+      inner = comp("VALARM")
+      vevent = comp("VEVENT", components: [inner])
+      vcal = comp("VCALENDAR", components: [vevent])
+      vcal.find_components("VALARM").should.equal []
+    end
+
+    it "a component with no properties or sub-components is valid" do
+      c = comp("VEVENT")
+      c.properties.should.equal []
+      c.components.should.equal []
+    end
+
+    it "find_all_properties returns all matching" do
+      c = comp("VEVENT", properties: [prop("ATTENDEE", "a"), prop("SUMMARY", "x"), prop("ATTENDEE", "b")])
+      c.find_all_properties("ATTENDEE").length.should.equal 2
+    end
+  end
+end

data/lib/protocol/caldav/ical/expand.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "scampi"
+
+require "protocol/caldav"
+
+module Protocol
+  module Caldav
+    module Ical
+      module Expand
+        module_function
+
+        # Expand a recurring VCALENDAR into individual instances.
+        # Returns a serialized VCALENDAR string with RRULE removed
+        # and each occurrence as a separate VEVENT with RECURRENCE-ID.
+        def expand(component, range_start:, range_end:, max_occurrences: 10000)
+          return serialize_component(component) unless component.name.casecmp?('VCALENDAR')
+
+          # Find the base VEVENT with RRULE
+          base = component.find_components('VEVENT').find { |v| v.find_property('RRULE') }
+          return serialize_component(component) unless base
+
+          # Collect override VEVENTs (same UID, has RECURRENCE-ID)
+          uid = base.find_property('UID')&.value
+          overrides = {}
+          component.find_components('VEVENT').each do |v|
+            rid = v.find_property('RECURRENCE-ID')
+            if rid && v.find_property('UID')&.value == uid
+              rid_time = Filter::Match.send(:parse_datetime_string, rid.value.strip)
+              overrides[rid_time] = v if rid_time
+            end
+          end
+
+          dtstart_prop = base.find_property('DTSTART')
+          dtstart = Filter::Match.send(:parse_datetime_string, dtstart_prop.value.strip)
+          return serialize_component(component) unless dtstart
+
+          dtend = Filter::Match.send(:parse_ical_datetime, base, 'DTEND')
+          duration = dtend ? (dtend - dtstart).to_i : 3600
+
+          rrule = base.find_property('RRULE').value.strip
+          exdates = base.find_all_properties('EXDATE').filter_map do |ex|
+            Filter::Match.send(:parse_datetime_string, ex.value.strip)
+          end
+
+          occurrences = Rrule.expand(
+            dtstart: dtstart,
+            rrule_value: rrule,
+            range_start: range_start,
+            range_end: range_end,
+            exdates: exdates,
+            max_count: max_occurrences
+          )
+
+          instances = occurrences.map do |occ_start|
+            override = overrides[occ_start]
+            if override
+              serialize_vevent_instance(override, occ_start)
+            else
+              serialize_expanded_instance(base, occ_start, duration)
+            end
+          end
+
+          # Also include overrides that aren't in the base RRULE expansion
+          overrides.each do |rid_time, override_vevent|
+            next if occurrences.any? { |o| Rrule.send(:times_equal?, o, rid_time) }
+            odt = Filter::Match.send(:parse_ical_datetime, override_vevent, 'DTSTART')
+            next unless odt && odt >= range_start && odt < range_end
+            instances << serialize_vevent_instance(override_vevent, rid_time)
+          end
+
+          "BEGIN:VCALENDAR\r\n#{instances.join}END:VCALENDAR\r\n"
+        end
+
+        def serialize_expanded_instance(base, occ_start, duration)
+          occ_end = occ_start + duration
+          lines = []
+          lines << "BEGIN:VEVENT"
+          lines << "RECURRENCE-ID:#{format_utc(occ_start)}"
+          lines << "DTSTART:#{format_utc(occ_start)}"
+          lines << "DTEND:#{format_utc(occ_end)}"
+
+          base.properties.each do |prop|
+            next if %w[DTSTART DTEND RRULE EXDATE RDATE EXRULE RECURRENCE-ID DURATION].include?(prop.name.upcase)
+            lines << "#{prop.name}:#{prop.value}"
+          end
+
+          lines << "END:VEVENT"
+          lines.map { |l| "#{l}\r\n" }.join
+        end
+
+        def serialize_vevent_instance(vevent, rid_time)
+          lines = []
+          lines << "BEGIN:VEVENT"
+          has_rid = false
+          vevent.properties.each do |prop|
+            next if %w[RRULE EXDATE RDATE EXRULE].include?(prop.name.upcase)
+            has_rid = true if prop.name.casecmp?('RECURRENCE-ID')
+            lines << "#{prop.name}:#{prop.value}"
+          end
+          lines.insert(1, "RECURRENCE-ID:#{format_utc(rid_time)}") unless has_rid
+          lines << "END:VEVENT"
+          lines.map { |l| "#{l}\r\n" }.join
+        end
+
+        def serialize_component(component)
+          lines = ["BEGIN:#{component.name}\r\n"]
+          component.properties.each { |p| lines << "#{p.name}:#{p.value}\r\n" }
+          component.components.each { |c| lines << serialize_component(c) }
+          lines << "END:#{component.name}\r\n"
+          lines.join
+        end
+
+        def format_utc(time)
+          time.utc.strftime('%Y%m%dT%H%M%SZ')
+        end
+
+        private_class_method :serialize_expanded_instance, :serialize_vevent_instance,
+                             :serialize_component, :format_utc
+      end
+    end
+  end
+end
+
+test do
+  describe "Protocol::Caldav::Ical::Expand" do
+    def parse(text)
+      Protocol::Caldav::Ical::Parser.parse(text)
+    end
+
+    it "returns serialized component when not VCALENDAR" do
+      vevent = parse("BEGIN:VEVENT\r\nSUMMARY:Hello\r\nEND:VEVENT")
+      result = Protocol::Caldav::Ical::Expand.expand(vevent, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 12, 31))
+      result.should.include "BEGIN:VEVENT"
+      result.should.include "SUMMARY:Hello"
+      result.should.include "END:VEVENT"
+    end
+
+    it "returns serialized component when no RRULE found" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nSUMMARY:Once\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 12, 31))
+      result.should.include "BEGIN:VCALENDAR"
+      result.should.include "SUMMARY:Once"
+      result.should.include "END:VCALENDAR"
+    end
+
+    it "expands daily RRULE into individual instances" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nRRULE:FREQ=DAILY;COUNT=3\r\nUID:expand-test\r\nSUMMARY:Daily\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 1, 10))
+      result.scan("BEGIN:VEVENT").length.should.equal 3
+      result.should.include "RECURRENCE-ID"
+      result.should.include "SUMMARY:Daily"
+    end
+
+    it "removes RRULE from expanded output" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nRRULE:FREQ=DAILY;COUNT=2\r\nUID:no-rrule\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 1, 10))
+      result.should.not.include "RRULE"
+    end
+
+    it "applies override VEVENT replacing base occurrence" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nRRULE:FREQ=DAILY;COUNT=3\r\nUID:override-test\r\nSUMMARY:Base\r\nEND:VEVENT\r\nBEGIN:VEVENT\r\nDTSTART:20260102T140000Z\r\nDTEND:20260102T150000Z\r\nRECURRENCE-ID:20260102T090000Z\r\nUID:override-test\r\nSUMMARY:Override\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 1, 10))
+      result.scan("BEGIN:VEVENT").length.should.equal 3
+      result.should.include "SUMMARY:Override"
+      result.should.include "SUMMARY:Base"
+    end
+
+    it "non-recurring event passes through unchanged" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nUID:single\r\nSUMMARY:Once\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 12, 31))
+      result.scan("BEGIN:VEVENT").length.should.equal 1
+      result.should.include "SUMMARY:Once"
+      result.should.not.include "RECURRENCE-ID"
+    end
+
+    it "respects EXDATE exclusions" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nRRULE:FREQ=DAILY;COUNT=3\r\nEXDATE:20260102T090000Z\r\nUID:exdate-test\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 1, 10))
+      result.scan("BEGIN:VEVENT").length.should.equal 2
+    end
+
+    it "only returns instances within range" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nRRULE:FREQ=DAILY;COUNT=10\r\nUID:range-test\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 3), range_end: Time.utc(2026, 1, 6))
+      result.scan("BEGIN:VEVENT").length.should.equal 3
+      result.should.include "20260103T090000Z"
+      result.should.include "20260105T090000Z"
+    end
+
+    it "preserves non-recurrence properties in expanded instances" do
+      ical = "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nDTSTART:20260101T090000Z\r\nDTEND:20260101T100000Z\r\nRRULE:FREQ=DAILY;COUNT=2\r\nUID:props-test\r\nSUMMARY:Keep Me\r\nLOCATION:Room 1\r\nEND:VEVENT\r\nEND:VCALENDAR"
+      component = parse(ical)
+      result = Protocol::Caldav::Ical::Expand.expand(component, range_start: Time.utc(2026, 1, 1), range_end: Time.utc(2026, 1, 10))
+      # Both instances should have SUMMARY and LOCATION
+      result.scan("SUMMARY:Keep Me").length.should.equal 2
+      result.scan("LOCATION:Room 1").length.should.equal 2
+    end
+  end
+end