cal-invite 0.1.2 → 0.1.4

data/lib/cal_invite/configuration.rb

@@ -1,13 +1,77 @@
+# frozen_string_literal: true
+
 # lib/cal_invite/configuration.rb
-module CalInvites
+# Configuration class for the CalInvite gem.
+# Handles all configurable options including cache settings, timezone, and webhook secrets.
+#
+# @attr_reader [ActiveSupport::Cache::Store, nil] cache_store The cache store to use
+# @attr_reader [String] cache_prefix The prefix to use for cache keys
+# @attr_reader [Integer] cache_expires_in The default cache expiration time in seconds
+# @attr_reader [String, nil] webhook_secret The secret key for webhook verification
+# @attr_reader [String] timezone The default timezone for events
+module CalInvite
   class Configuration
-    attr_accessor :cache_store, :cache_prefix, :webhook_secret, :timezone
+    attr_reader :cache_store, :cache_prefix, :cache_expires_in, :webhook_secret, :timezone
 
+    # Initializes a new Configuration instance with default values.
     def initialize
-      @cache_store = :memory_store
+      @cache_store = nil
       @cache_prefix = 'cal_invite'
+      @cache_expires_in = 24.hours # now this will work with active_support loaded
       @webhook_secret = nil
       @timezone = 'UTC'
     end
+
+    # Sets the cache store to use for caching calendar URLs.
+    #
+    # @param store [Symbol, #read, #write, #delete] The cache store to use
+    # @raise [ArgumentError] If an unsupported cache store is provided
+    #
+    # @example Set memory store
+    #   config.cache_store = :memory_store
+    def cache_store=(store)
+      @cache_store = case store
+      when :memory_store
+        ActiveSupport::Cache::MemoryStore.new
+      when :null_store
+        ActiveSupport::Cache::NullStore.new
+      when Symbol
+        raise ArgumentError, "Unsupported cache store: #{store}"
+      else
+        # Allow custom cache store objects that respond to read/write/delete
+        unless store.respond_to?(:read) && store.respond_to?(:write) && store.respond_to?(:delete)
+          raise ArgumentError, "Custom cache store must implement read/write/delete methods"
+        end
+        store
+      end
+    end
+
+    # Sets the prefix used for cache keys.
+    #
+    # @param prefix [#to_s] The prefix to use for cache keys
+    def cache_prefix=(prefix)
+      @cache_prefix = prefix.to_s
+    end
+
+    # Sets the default cache expiration time.
+    #
+    # @param duration [#to_i] The duration in seconds
+    def cache_expires_in=(duration)
+      @cache_expires_in = duration.to_i
+    end
+
+    # Sets the webhook secret for verification.
+    #
+    # @param secret [String, nil] The secret key
+    def webhook_secret=(secret)
+      @webhook_secret = secret
+    end
+
+    # Sets the default timezone for events.
+    #
+    # @param tz [#to_s] The timezone identifier
+    def timezone=(tz)
+      @timezone = tz.to_s
+    end
   end
 end

data/lib/cal_invite/event.rb

@@ -1,8 +1,23 @@
 # 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 [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
+# @attr_accessor [Array<String>] attendees The list of attendee email addresses
+# @attr_accessor [String] timezone The timezone for the event
+# @attr_accessor [Boolean] show_attendees Whether to include attendees in calendar invites
+# @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
 module CalInvite
-  # Represents a calendar event with its properties and validation rules
   class Event
     attr_accessor :title,
                   :start_time,
@@ -17,7 +32,7 @@ module CalInvite
                   :multi_day_sessions,
                   :all_day
 
-    # Initialize a new Event instance
+    # 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
@@ -26,27 +41,20 @@ module CalInvite
     # @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 List of event attendees
-    # @option attributes [String] :timezone The event timezone (default: 'UTC')
-    # @option attributes [Boolean] :show_attendees Whether to show attendees (default: false)
-    # @option attributes [String] :notes Additional notes for the event
-    # @option attributes [Array<Hash>] :multi_day_sessions List of sessions for multi-day events
-    # @option attributes [Boolean] :all_day Whether this is an all-day event (default: false)
-    # @raise [ArgumentError] if required attributes are missing
+    # @option attributes [Array<String>] :attendees The event attendees
+    # @option attributes [String] :timezone ('UTC') The event timezone
+    # @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
+    #
+    # @raise [ArgumentError] If required attributes are missing
     def initialize(attributes = {})
       @show_attendees = attributes.delete(:show_attendees) || false
       @timezone = attributes.delete(:timezone) || 'UTC'
       @multi_day_sessions = attributes.delete(:multi_day_sessions) || []
       @all_day = attributes.delete(:all_day) || false
 
-      # Convert times to UTC before storing
-      if attributes[:start_time]
-        attributes[:start_time] = ensure_utc(attributes[:start_time])
-      end
-      if attributes[:end_time]
-        attributes[:end_time] = ensure_utc(attributes[:end_time])
-      end
-
       attributes.each do |key, value|
         send("#{key}=", value) if respond_to?("#{key}=")
       end
@@ -54,62 +62,72 @@ module CalInvite
       validate!
     end
 
-    # Generate a calendar URL for the specified provider
+    # Generates a calendar URL for the specified provider.
     #
     # @param provider [Symbol] The calendar provider to generate the URL for
     # @return [String] The generated calendar URL
-    # @raise [ArgumentError] if required attributes are missing
-    def calendar_url(provider)
+    # @raise [ArgumentError] If required event attributes are missing
+    #
+    # @example Generate a Google Calendar URL
+    #   event.generate_calendar_url(:google)
+    #
+    # @example Generate an Outlook Calendar URL
+    #   event.generate_calendar_url(:outlook)
+    def generate_calendar_url(provider)
       validate!
+
+      if caching_enabled?
+        cache_key = cache_key_for(provider)
+        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)
-      generator.generate
-    end
+      url = generator.generate
 
-    # Convert a UTC time to event's timezone
-    #
-    # @param time [Time, nil] The time to convert
-    # @return [Time, nil] The converted time in the event's timezone
-    def localize_time(time)
-      return time unless time
-      # When timezone is UTC, we should preserve the UTC time
-      # without any conversion
-      return time if timezone == 'UTC'
-      time.getlocal(timezone_offset)
+      # Cache the result if caching is enabled
+      write_to_cache(cache_key, url) if caching_enabled?
+
+      url
     end
 
-    # Get all event sessions including multi-day sessions
+    # Updates the event attributes with new values.
     #
-    # @return [Array<Array<Time>>] Array of start and end time pairs
-    def sessions
-      return [@start_time, @end_time] if multi_day_sessions.empty?
-
-      multi_day_sessions.map do |session|
-        [session[:start_time], session[:end_time]]
+    # @param new_attributes [Hash] The new attributes to update
+    # @return [void]
+    # @raise [ArgumentError] If the updated attributes make the event invalid
+    #
+    # @example Update event title and time
+    #   event.update_attributes(
+    #     title: "Updated Meeting",
+    #     start_time: Time.now + 3600
+    #   )
+    def update_attributes(new_attributes)
+      new_attributes.each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
       end
-    end
 
-    private
-
-    def ensure_utc(time)
-      return nil unless time
-      time.is_a?(Time) ? time.utc : Time.parse(time.to_s).utc
+      invalidate_cache if caching_enabled?
+      validate!
     end
 
-    def timezone_offset
-      return '+00:00' if timezone == 'UTC'
-      timezone # assume timezone is already in offset format
-    end
+    private
 
+    # Capitalizes each part of the provider name.
+    #
+    # @param string [String] The provider name to capitalize
+    # @return [String] The capitalized provider name
+    # @example
+    #   capitalize_provider('google_calendar') # => "GoogleCalendar"
     def capitalize_provider(string)
-      # Handles both simple capitalization (ical -> Ical)
-      # and compound names (office365 -> Office365)
       string.split('_').map(&:capitalize).join
     end
 
-    # Validate the event attributes
+    # Validates the event attributes.
     #
-    # @raise [ArgumentError] if required attributes are missing
+    # @raise [ArgumentError] If required attributes are missing or invalid
     def validate!
       raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
@@ -118,5 +136,78 @@ module CalInvite
         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
+    # @return [String, nil] The cache key or nil if caching is disabled
+    def cache_key_for(provider)
+      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,
+          provider
+        ].map(&:to_s).join('|')
+      )
+
+      "cal_invite:event:#{attributes_hash}"
+    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)
+    end
+
+    # Writes a value to the cache store.
+    #
+    # @param key [String] The cache key
+    # @param value [String] The value to cache
+    # @return [void]
+    def write_to_cache(key, value)
+      return unless key && caching_enabled?
+
+      expires_in = CalInvite.configuration&.cache_expires_in
+      CalInvite.configuration.cache_store.write(
+        key,
+        value,
+        expires_in: expires_in
+      )
+    end
+
+    # Invalidates all cached URLs for this event.
+    #
+    # @return [void]
+    def invalidate_cache
+      return unless caching_enabled?
+
+      if CalInvite.configuration.cache_store.respond_to?(:delete_matched)
+        CalInvite.configuration.cache_store.delete_matched("cal_invite:event:*")
+      end
+    end
   end
 end

data/lib/cal_invite/providers/base_provider.rb

@@ -1,68 +1,85 @@
 # frozen_string_literal: true
 
-# lib/cal_invite/providers/base_provider.rb
-module CalInvite
-  module Providers
-    # Base class for calendar providers that implements common functionality
-    # and defines the interface that all providers must implement
-    class BaseProvider
-      # @return [CalInvite::Event] The event being processed
-      attr_reader :event
+# app/lib/base_provider.rb
+# Base class for calendar providers that implements common functionality
+# and defines the interface that all providers must implement.
+#
+# @abstract Subclass and override {#generate} to implement a calendar provider
+class BaseProvider
+  attr_reader :event
 
-      # Initialize a new calendar provider
-      #
-      # @param event [CalInvite::Event] The event to generate a calendar URL for
-      def initialize(event)
-        @event = event
-      end
+  # Initialize a new calendar provider
+  #
+  # @param event [CalInvite::Event] The event to generate a calendar URL for
+  def initialize(event)
+    @event = event
+  end
 
-      # Generate a calendar URL for the event
-      # This method must be implemented by all provider subclasses
-      #
-      # @abstract
-      # @raise [NotImplementedError] if the provider class doesn't implement this method
-      def generate
-        raise NotImplementedError, "#{self.class} must implement #generate"
-      end
+  # Generate a calendar URL or content for the event.
+  # This method must be implemented by all provider subclasses.
+  #
+  # @abstract
+  # @return [String] The generated calendar URL or content
+  # @raise [NotImplementedError] if the provider class doesn't implement this method
+  def generate
+    raise NotImplementedError, "#{self.class} must implement #generate"
+  end
 
-      protected
+  protected
 
-      # URL encode a string for use in calendar URLs
-      #
-      # @param str [#to_s] The string to encode
-      # @return [String] The URL encoded string
-      def url_encode(str)
-        URI.encode_www_form_component(str.to_s)
-      end
+  # URL encode a string for use in calendar URLs
+  #
+  # @param str [#to_s] The string to encode
+  # @return [String] The URL encoded string
+  def url_encode(str)
+    URI.encode_www_form_component(str.to_s)
+  end
 
-      # Format the event description including notes and URL if present
-      #
-      # @return [String, nil] The formatted description or nil if no content
-      def format_description
-        parts = []
-        parts << event.description if event.description
-        parts << "Notes: #{event.notes}" if event.notes
-        parts << "URL: #{event.url}" if event.url
-        parts.join("\n\n")
-      end
+  # Format the event description
+  # @return [String, nil] The formatted description or nil if no content
+  def format_description
+    parts = []
+    parts << event.description if event.description
+    parts << "Notes: #{event.notes}" if event.notes
+    parts.join("\n\n")
+  end
 
-      # Format the event location, combining physical location and URL if both present
-      #
-      # @return [String, nil] The formatted location or nil if neither location nor URL present
-      def format_location
-        return event.url if event.url && !event.location
-        return event.location if event.location && !event.url
-        return "#{event.location}\n#{event.url}" if event.location && event.url
-        nil
-      end
+  # Get just the physical location
+  # @return [String, nil] The location or nil if not present
+  def format_location
+    event.location
+  end
+
+  # Get the URL for virtual meetings
+  # @return [String, nil] The URL or nil if not present
+  def format_url
+    event.url
+  end
 
-      # Get the list of attendees if showing attendees is enabled
-      #
-      # @return [Array<String>] The list of attendees or empty array if disabled/none present
-      def attendees_list
-        return [] unless event.show_attendees && event.attendees&.any?
-        event.attendees
-      end
+  # Format description including URL if present
+  # @return [String, nil] The formatted description with URL
+  def format_description_with_url
+    parts = []
+    parts << format_description if format_description
+    parts << "Virtual Meeting URL: #{format_url}" if format_url
+    parts.join("\n\n")
+  end
+
+  def add_optional_params(params)
+    params[:description] = url_encode(format_description_with_url) if format_description || format_url
+    params[:location] = url_encode(format_location) if format_location
+
+    if event.show_attendees && event.attendees&.any?
+      params[:attendees] = event.attendees.join(',')
     end
+
+    params
+  end
+
+  # Get the list of attendees if showing attendees is enabled
+  # @return [Array<String>] The list of attendees or empty array if disabled/none present
+  def attendees_list
+    return [] unless event.show_attendees && event.attendees&.any?
+    event.attendees
   end
 end

data/lib/cal_invite/providers/google.rb

@@ -3,7 +3,34 @@
 # lib/cal_invite/providers/google.rb
 module CalInvite
   module Providers
+    # Google Calendar provider for generating event URLs.
+    # This provider generates URLs that open the Google Calendar event creation page
+    # with pre-filled event details.
+    #
+    # @example Creating a regular event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600
+    #   )
+    #   google = CalInvite::Providers::Google.new(event)
+    #   url = google.generate
+    #
+    # @example Creating an all-day event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Company Holiday",
+    #     all_day: true,
+    #     start_time: Date.today,
+    #     end_time: Date.today + 1
+    #   )
+    #   url = CalInvite::Providers::Google.new(event).generate
     class Google < BaseProvider
+      # Generates a Google Calendar URL for the event.
+      # Handles both regular and all-day events appropriately.
+      #
+      # @return [String] The generated Google Calendar URL
+      # @see #generate_all_day_event
+      # @see #generate_single_event
       def generate
         if event.all_day
           generate_all_day_event
@@ -14,36 +41,53 @@ module CalInvite
 
       private
 
+      # Generates a URL for an all-day event.
+      # Uses a simpler date format without time components.
+      #
+      # @return [String] The Google Calendar URL for an all-day event
+      # @see #format_all_day_dates
       def generate_all_day_event
         params = {
           action: 'TEMPLATE',
           text: url_encode(event.title),
           dates: format_all_day_dates
         }
-
         add_optional_params(params)
         build_url(params)
       end
 
+      # Generates a URL for a regular (time-specific) event.
+      #
+      # @return [String] The Google Calendar URL for a regular event
+      # @raise [ArgumentError] If start_time or end_time is missing
+      # @see #format_dates
       def generate_single_event
         params = {
           action: 'TEMPLATE',
           text: url_encode(event.title),
           dates: format_dates
         }
-
         add_optional_params(params)
         build_url(params)
       end
 
+      # Formats dates for an all-day event according to Google Calendar's requirements.
+      # If start_time is not specified, uses current date.
+      # If end_time is not specified, adds one day to start_time.
+      #
+      # @return [String] Date range in format 'YYYYMMDD/YYYYMMDD'
       def format_all_day_dates
-        # For all-day events, use current date if no start_time specified
         start_date = event.start_time || Time.now
         end_date = event.end_time || (start_date + 86400) # Add one day if no end_time
 
         "#{start_date.strftime('%Y%m%d')}/#{end_date.strftime('%Y%m%d')}"
       end
 
+      # Formats dates and times according to Google Calendar's requirements.
+      # Times are converted to UTC and formatted appropriately.
+      #
+      # @return [String] Date/time range in format 'YYYYMMDDTHHmmSSZ/YYYYMMDDTHHmmSSZ'
+      # @raise [ArgumentError] If either start_time or end_time is missing
       def format_dates
         raise ArgumentError, "Start time is required" unless event.start_time
         raise ArgumentError, "End time is required" unless event.end_time
@@ -54,12 +98,24 @@ module CalInvite
         "#{start_time.utc.strftime('%Y%m%dT%H%M%SZ')}/#{end_time.utc.strftime('%Y%m%dT%H%M%SZ')}"
       end
 
+      # Adds optional parameters to the URL parameters hash.
+      # Handles description, virtual meeting URL, and location.
+      #
+      # @param params [Hash] The parameters hash to update
+      # @return [Hash] The updated parameters hash with optional parameters added
       def add_optional_params(params)
-        params[:details] = url_encode(format_description) if format_description
+        description_parts = []
+        description_parts << format_description if format_description
+        description_parts << "Virtual Meeting URL: #{format_url}" if format_url
+        params[:details] = url_encode(description_parts.join("\n\n")) if description_parts.any?
         params[:location] = url_encode(format_location) if format_location
         params
       end
 
+      # Builds the final Google Calendar URL from the parameters hash.
+      #
+      # @param params [Hash] The parameters to include in the URL
+      # @return [String] The complete Google Calendar URL
       def build_url(params)
         query = params.map { |k, v| "#{k}=#{v}" }.join('&')
         "https://calendar.google.com/calendar/render?#{query}"