cal-invite 0.2.0 → 0.3.0

data/lib/cal_invite/event.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
-require 'digest'
-
 # lib/cal_invite/event.rb
 # Represents a calendar event with all its attributes and generation capabilities.
 #
 # @attr_accessor [String] title The title of the event
-# @attr_accessor [Time] start_time The start time of the event
-# @attr_accessor [Time] end_time The end time of the event
+# @attr_accessor [Time] start_time The start time of the event (defaults to the earliest multi_day_sessions start)
+# @attr_accessor [Time] end_time The end time of the event (defaults to the latest multi_day_sessions end)
 # @attr_accessor [String] description The description of the event
 # @attr_accessor [String] location The location of the event
 # @attr_accessor [String] url The URL associated with the event
@@ -19,7 +17,7 @@ require 'digest'
 # @attr_accessor [String] notes Additional notes for the event
 # @attr_accessor [Array<Hash>] multi_day_sessions Sessions for multi-day events
 # @attr_accessor [Boolean] all_day Whether this is an all-day event
-# @attr_accessor [Hash] organizer The event organizer, e.g. { name: "Jane Doe", email: "jane@example.com" }
+# @attr_accessor [String, Hash] organizer The event organizer: an email string, or e.g. { name: "Jane Doe", email: "jane@example.com" }
 # @attr_accessor [String] uid Stable RFC 5545 UID identifying this event across its lifecycle
 # @attr_accessor [Integer] sequence RFC 5545 SEQUENCE number; bump on every REQUEST/CANCEL update
 # @attr_accessor [Array<Float>, Hash] geo Location coordinates, e.g. [37.4595, -122.1418] or { lat:, lng: }
@@ -35,9 +33,8 @@ require 'digest'
 #   this; other clients don't expose an equivalent control
 module CalInvite
   class Event
+    attr_writer :start_time, :end_time
     attr_accessor :title,
-                  :start_time,
-                  :end_time,
                   :description,
                   :location,
                   :url,
@@ -59,22 +56,42 @@ module CalInvite
                   :importance,
                   :allow_counter
 
+    # The event start. Without an explicit value, a multi-day event spans
+    # from its earliest session start, so single-event URL providers (Google,
+    # Outlook, Office 365) show the overall range.
+    #
+    # @return [Time, nil]
+    def start_time
+      @start_time || multi_day_sessions&.map { |session| session[:start_time] }&.compact&.min
+    end
+
+    # The event end. Without an explicit value, a multi-day event ends at its
+    # latest session end.
+    #
+    # @return [Time, nil]
+    def end_time
+      @end_time || multi_day_sessions&.map { |session| session[:end_time] }&.compact&.max
+    end
+
     # Initializes a new Event instance with the given attributes.
     #
     # @param attributes [Hash] The attributes to initialize the event with
     # @option attributes [String] :title The event title
-    # @option attributes [Time] :start_time The event start time
-    # @option attributes [Time] :end_time The event end time
+    # @option attributes [Time] :start_time The event start time. Optional with :multi_day_sessions
+    #   (defaults to the earliest session start).
+    # @option attributes [Time] :end_time The event end time. Optional with :multi_day_sessions
+    #   (defaults to the latest session end).
     # @option attributes [String] :description The event description
     # @option attributes [String] :location The event location
     # @option attributes [String] :url The event URL
     # @option attributes [Array<String>] :attendees The event attendees
-    # @option attributes [String] :timezone ('UTC') The event timezone
+    # @option attributes [String] :timezone The event timezone. Defaults to
+    #   CalInvite.configuration.timezone ('UTC' unless configured).
     # @option attributes [Boolean] :show_attendees (false) Whether to show attendees
     # @option attributes [String] :notes Additional notes
     # @option attributes [Array<Hash>] :multi_day_sessions Multi-day session details
     # @option attributes [Boolean] :all_day (false) Whether it's an all-day event
-    # @option attributes [Hash] :organizer The event organizer, e.g. { name: "Jane Doe", email: "jane@example.com" }
+    # @option attributes [String, Hash] :organizer The event organizer: an email string, or e.g. { name: "Jane Doe", email: "jane@example.com" }
     # @option attributes [String] :uid A stable identifier for this event. If omitted, a random one
     #   is generated and memoized on this instance. To update or cancel a previously sent invite,
     #   you MUST pass the same :uid used originally — mail/calendar clients match REQUEST/CANCEL
@@ -91,10 +108,11 @@ module CalInvite
     # @option attributes [Symbol, String] :importance :low, :normal, or :high
     # @option attributes [Boolean] :allow_counter (true) false emits X-MICROSOFT-DISALLOW-COUNTER
     #
-    # @raise [ArgumentError] If required attributes are missing
+    # @raise [ArgumentError] If required attributes are missing or invalid, or a key isn't an Event attribute
     def initialize(attributes = {})
+      attributes = attributes.dup # never mutate the caller's hash
       @show_attendees = attributes.delete(:show_attendees) || false
-      @timezone = attributes.delete(:timezone) || 'UTC'
+      @timezone = attributes.delete(:timezone) || CalInvite.configuration&.timezone || 'UTC'
       @multi_day_sessions = attributes.delete(:multi_day_sessions) || []
       @all_day = attributes.delete(:all_day) || false
       @uid = attributes.delete(:uid) || generate_uid
@@ -103,9 +121,7 @@ module CalInvite
       @visibility = attributes.delete(:visibility) || :public
       @allow_counter = attributes.key?(:allow_counter) ? attributes.delete(:allow_counter) : true
 
-      attributes.each do |key, value|
-        send("#{key}=", value) if respond_to?("#{key}=")
-      end
+      assign_attributes(attributes)
 
       validate!
     end
@@ -113,7 +129,8 @@ module CalInvite
     # Generates a calendar URL (or, for the ics/ical/ics_content providers, raw
     # iCalendar content) for the specified provider.
     #
-    # @param provider [Symbol] The calendar provider to generate the URL for
+    # @param provider [Symbol, String] One of {CalInvite::Providers::SUPPORTED_PROVIDERS}
+    #   (`:ics_content` is also accepted as a legacy alias of `:ics`)
     # @param method [Symbol] The iCalendar METHOD to use (:publish, :request, :cancel,
     #   :reply, :counter, or :decline_counter). Only honored by the ics-family providers
     #   (ics, ical, ics_content); ignored by URL-based providers.
@@ -130,7 +147,7 @@ module CalInvite
     #     "Attendee-proposed reschedules (COUNTER)".
     #   - :decline_counter is the organizer rejecting a :counter proposal.
     # @return [String] The generated calendar URL or content
-    # @raise [ArgumentError] If required event attributes are missing
+    # @raise [ArgumentError] If required event attributes are missing or the provider is unsupported
     #
     # @example Generate a Google Calendar URL
     #   event.generate_calendar_url(:google)
@@ -148,29 +165,14 @@ module CalInvite
     #   event.generate_calendar_url(:ics, method: :cancel)
     def generate_calendar_url(provider, method: :publish)
       validate!
-
-      if caching_enabled?
-        cache_key = cache_key_for(provider, method)
-        cached_url = fetch_from_cache(cache_key)
-        return cached_url if cached_url
-      end
-
-      # Generate the URL
-      provider_class = CalInvite::Providers.const_get(capitalize_provider(provider.to_s))
-      generator = provider_class.new(self, method: method)
-      url = generator.generate
-
-      # Cache the result if caching is enabled
-      write_to_cache(cache_key, url) if caching_enabled?
-
-      url
+      provider_class_for(provider).new(self, method: method).generate
     end
 
     # Updates the event attributes with new values.
     #
     # @param new_attributes [Hash] The new attributes to update
     # @return [void]
-    # @raise [ArgumentError] If the updated attributes make the event invalid
+    # @raise [ArgumentError] If a key isn't an Event attribute (nothing is changed), or the updated attributes make the event invalid
     #
     # @example Update event title and time
     #   event.update_attributes(
@@ -178,11 +180,7 @@ module CalInvite
     #     start_time: Time.now + 3600
     #   )
     def update_attributes(new_attributes)
-      new_attributes.each do |key, value|
-        send("#{key}=", value) if respond_to?("#{key}=")
-      end
-
-      invalidate_cache if caching_enabled?
+      assign_attributes(new_attributes)
       validate!
     end
 
@@ -196,6 +194,27 @@ module CalInvite
       "#{Time.now.to_i}-#{SecureRandom.hex(8)}@cal-invite"
     end
 
+    # Legacy provider symbols that still resolve; `:ics_content` has produced the
+    # same output as `:ics` since IcsContent became a subclass of Ics.
+    PROVIDER_ALIASES = { ics_content: :ics }.freeze
+
+    # Resolves a provider symbol to its class, accepting only
+    # {CalInvite::Providers::SUPPORTED_PROVIDERS} (plus {PROVIDER_ALIASES}).
+    #
+    # @param provider [Symbol, String] The provider name
+    # @return [Class] The provider class
+    # @raise [ArgumentError] If the provider isn't supported
+    def provider_class_for(provider)
+      key = provider.to_s.to_sym
+      key = PROVIDER_ALIASES.fetch(key, key)
+      unless CalInvite::Providers::SUPPORTED_PROVIDERS.include?(key)
+        raise ArgumentError,
+              "Unsupported provider #{provider.inspect}; supported: #{CalInvite::Providers::SUPPORTED_PROVIDERS.join(', ')}"
+      end
+
+      CalInvite::Providers.const_get(capitalize_provider(key.to_s), false)
+    end
+
     # Capitalizes each part of the provider name.
     #
     # @param string [String] The provider name to capitalize
@@ -216,92 +235,46 @@ module CalInvite
         raise ArgumentError, "Start time is required for non-all-day events" if start_time.nil?
         raise ArgumentError, "End time is required for non-all-day events" if end_time.nil?
       end
-    end
-
-    # Checks if caching is enabled in the configuration.
-    #
-    # @return [Boolean] true if caching is enabled, false otherwise
-    def caching_enabled?
-      CalInvite.configuration &&
-        CalInvite.configuration.respond_to?(:cache_store) &&
-        CalInvite.configuration.cache_store
-    end
 
-    # Generates a cache key for the event and provider combination.
-    #
-    # @param provider [Symbol] The calendar provider
-    # @param method [Symbol] The iCalendar METHOD used to generate the content
-    # @return [String, nil] The cache key or nil if caching is disabled
-    def cache_key_for(provider, method = :publish)
-      return nil unless caching_enabled?
-
-      attributes_hash = Digest::MD5.hexdigest(
-        [
-          title,
-          start_time&.to_i,
-          end_time&.to_i,
-          description,
-          location,
-          url,
-          attendees,
-          timezone,
-          show_attendees,
-          notes,
-          multi_day_sessions,
-          all_day,
-          organizer,
-          uid,
-          sequence,
-          geo,
-          reminders,
-          busy,
-          visibility,
-          rrule,
-          calendar_name,
-          importance,
-          allow_counter,
-          provider,
-          method
-        ].map(&:to_s).join('|')
-      )
+      validate_time_order!(start_time, end_time, "End time")
+      multi_day_sessions.each_with_index do |session, index|
+        label = "Session #{index + 1}"
+        raise ArgumentError, "#{label} requires start_time and end_time" unless session[:start_time] && session[:end_time]
 
-      "cal_invite:event:#{attributes_hash}"
-    end
+        validate_time_order!(session[:start_time], session[:end_time], "#{label} end_time")
+      end
 
-    # Retrieves a value from the cache store.
-    #
-    # @param key [String] The cache key
-    # @return [String, nil] The cached value or nil if not found
-    def fetch_from_cache(key)
-      return nil unless key && caching_enabled?
-      CalInvite.configuration.cache_store.read(key)
+      unless CalInvite::IcalTimezone.valid?(timezone)
+        raise ArgumentError, "Unknown timezone #{timezone.inspect}: use 'UTC' or an IANA identifier such as 'America/New_York'"
+      end
     end
 
-    # Writes a value to the cache store.
+    # Assigns attributes through their setters. Checks every key first, so an
+    # unknown key (e.g. a typo like `locaton:`) raises before anything changes
+    # instead of being silently dropped.
     #
-    # @param key [String] The cache key
-    # @param value [String] The value to cache
+    # @param attributes [Hash] Attribute names (symbols or strings) to values
+    # @raise [ArgumentError] If any key isn't an Event attribute
     # @return [void]
-    def write_to_cache(key, value)
-      return unless key && caching_enabled?
+    def assign_attributes(attributes)
+      unknown = attributes.keys.reject { |key| respond_to?("#{key}=") }
+      raise ArgumentError, "Unknown attribute(s): #{unknown.join(', ')}" if unknown.any?
 
-      expires_in = CalInvite.configuration&.cache_expires_in
-      CalInvite.configuration.cache_store.write(
-        key,
-        value,
-        expires_in: expires_in
-      )
+      attributes.each { |key, value| send("#{key}=", value) }
     end
 
-    # Invalidates all cached URLs for this event.
+    # Raises unless the end comes after the start. RFC 5545 requires DTEND to be
+    # later than DTSTART; all-day events may start and end on the same date.
     #
-    # @return [void]
-    def invalidate_cache
-      return unless caching_enabled?
+    # @param start_at [Time, Date, nil] The start
+    # @param end_at [Time, Date, nil] The end
+    # @param label [String] What to call the end in the error message
+    # @raise [ArgumentError] If the end is before (or, for timed events, equal to) the start
+    def validate_time_order!(start_at, end_at, label)
+      return unless start_at && end_at
+      return if end_at > start_at || (all_day && end_at == start_at)
 
-      if CalInvite.configuration.cache_store.respond_to?(:delete_matched)
-        CalInvite.configuration.cache_store.delete_matched("cal_invite:event:*")
-      end
+      raise ArgumentError, "#{label} must be after start time"
     end
   end
 end

data/lib/cal_invite/ical_timezone.rb

@@ -9,23 +9,52 @@ module CalInvite
   # time for a given IANA/Olson timezone identifier, using TZInfo (already pulled in
   # transitively via activesupport).
   #
-  # Both entry points fail soft: if `tzid` isn't a TZInfo-recognized identifier (e.g.
-  # a raw UTC offset string like "+01:00", or 'UTC' itself), they return nil so
-  # callers can fall back to their previous behavior instead of raising.
+  # Only uses TZInfo APIs available in both tzinfo 1.2+ (pinned by Rails 6.0) and
+  # 2.x; the few period accessors renamed in 2.x go through {period_starts_at},
+  # {period_ends_at} and {period_local_ends_at}.
+  #
+  # Event validates `timezone` with {valid?}, so by the time a provider runs it's
+  # either UTC or a TZInfo-recognized identifier. {local_time} and
+  # {vtimezone_lines} still fail soft (return nil) for UTC or unrecognized input.
   #
   # @api private
   module IcalTimezone
     module_function
 
+    # Whether `tzid` means UTC (case-insensitive 'UTC'), which needs no VTIMEZONE:
+    # times are emitted as `Z`-suffixed UTC timestamps instead.
+    #
+    # @param tzid [String, nil] The timezone identifier
+    # @return [Boolean]
+    def utc?(tzid)
+      tzid.to_s.upcase == 'UTC'
+    end
+
+    # Whether `tzid` is usable as an event timezone: UTC or a TZInfo-recognized
+    # IANA identifier (e.g. "America/New_York"). Raw offsets like "+01:00" aren't:
+    # they have no VTIMEZONE definition.
+    #
+    # @param tzid [String, nil] The timezone identifier
+    # @return [Boolean]
+    def valid?(tzid)
+      return true if utc?(tzid)
+      return false if tzid.nil? || tzid.to_s.strip.empty?
+
+      TZInfo::Timezone.get(tzid.to_s)
+      true
+    rescue TZInfo::InvalidTimezoneIdentifier
+      false
+    end
+
     # Converts a UTC time to local wall-clock time for the given timezone.
     #
     # @param tzid [String] An IANA timezone identifier, e.g. "America/New_York"
     # @param utc_time [Time] The time to convert (interpreted as UTC)
     # @return [Time, nil] The local wall-clock time, or nil if tzid is unrecognized
     def local_time(tzid, utc_time)
-      return nil if tzid.nil? || tzid.to_s.strip.empty? || tzid.to_s.upcase == 'UTC'
+      return nil if utc?(tzid) || tzid.nil? || tzid.to_s.strip.empty?
 
-      TZInfo::Timezone.get(tzid.to_s).to_local(utc_time.utc)
+      TZInfo::Timezone.get(tzid.to_s).utc_to_local(utc_time.utc)
     rescue TZInfo::InvalidTimezoneIdentifier
       nil
     end
@@ -38,10 +67,10 @@ module CalInvite
     # @return [Array<String>, nil] iCalendar lines for the VTIMEZONE component, or
     #   nil if tzid is unrecognized, is UTC, or the component can't be built
     def vtimezone_lines(tzid)
-      return nil if tzid.nil? || tzid.to_s.strip.empty? || tzid.to_s.upcase == 'UTC'
+      return nil if utc?(tzid) || tzid.nil? || tzid.to_s.strip.empty?
 
       tz = TZInfo::Timezone.get(tzid.to_s)
-      current = tz.period_for(Time.now.utc)
+      current = tz.period_for_utc(Time.now.utc)
 
       if current.dst?
         dst_period = current
@@ -71,28 +100,45 @@ module CalInvite
 
     # @api private
     def period_before(tz, period)
-      return nil unless period.starts_at
+      starts_at = period_starts_at(period)
+      return nil unless starts_at
 
-      tz.period_for(period.starts_at.to_time - 1)
+      tz.period_for_utc(starts_at.to_time - 1)
     end
 
     # @api private
     def period_after(tz, period)
-      return nil unless period&.ends_at
+      ends_at = period && period_ends_at(period)
+      return nil unless ends_at
 
-      tz.period_for(period.ends_at.to_time)
+      tz.period_for_utc(ends_at.to_time)
+    end
+
+    # @api private
+    def period_starts_at(period)
+      period.respond_to?(:starts_at) ? period.starts_at : period.utc_start
+    end
+
+    # @api private
+    def period_ends_at(period)
+      period.respond_to?(:ends_at) ? period.ends_at : period.utc_end
+    end
+
+    # @api private
+    def period_local_ends_at(period)
+      period.respond_to?(:local_ends_at) ? period.local_ends_at : period.local_end
     end
 
     # @api private
     def observance_lines(kind, from_period, to_period)
-      transition_time = from_period.local_ends_at.to_time
+      transition_time = period_local_ends_at(from_period).to_time
 
       [
         "BEGIN:#{kind}",
         "DTSTART:#{transition_time.strftime('%Y%m%dT%H%M%S')}",
-        "TZOFFSETFROM:#{format_offset(from_period.offset.observed_utc_offset)}",
-        "TZOFFSETTO:#{format_offset(to_period.offset.observed_utc_offset)}",
-        "TZNAME:#{to_period.offset.abbreviation}",
+        "TZOFFSETFROM:#{format_offset(from_period.utc_total_offset)}",
+        "TZOFFSETTO:#{format_offset(to_period.utc_total_offset)}",
+        "TZNAME:#{to_period.abbreviation}",
         rrule_line(transition_time),
         "END:#{kind}"
       ]
@@ -103,9 +149,9 @@ module CalInvite
       [
         "BEGIN:STANDARD",
         "DTSTART:16010101T000000",
-        "TZOFFSETFROM:#{format_offset(period.offset.observed_utc_offset)}",
-        "TZOFFSETTO:#{format_offset(period.offset.observed_utc_offset)}",
-        "TZNAME:#{period.offset.abbreviation}",
+        "TZOFFSETFROM:#{format_offset(period.utc_total_offset)}",
+        "TZOFFSETTO:#{format_offset(period.utc_total_offset)}",
+        "TZNAME:#{period.abbreviation}",
         "END:STANDARD"
       ]
     end