cal-invite 0.1.2 → 0.1.4

data/lib/cal_invite/providers/outlook.rb

@@ -3,7 +3,42 @@
 # lib/cal_invite/providers/outlook.rb
 module CalInvite
   module Providers
+    # Microsoft Outlook Live (outlook.live.com) provider for generating calendar event URLs.
+    # This provider generates URLs that open the Outlook.com web calendar
+    # with a pre-filled event creation form. Supports both all-day and
+    # time-specific events.
+    #
+    # Note: This is for personal Outlook.com accounts. For corporate Office 365,
+    # use the {Office365} provider instead.
+    #
+    # @example Creating a regular event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     description: "Weekly team sync"
+    #   )
+    #   outlook = CalInvite::Providers::Outlook.new(event)
+    #   url = outlook.generate
+    #
+    # @example Creating an all-day event URL with attendees
+    #   event = CalInvite::Event.new(
+    #     title: "Company Holiday",
+    #     all_day: true,
+    #     start_time: Date.today,
+    #     end_time: Date.today + 1,
+    #     attendees: ["john@example.com", "jane@example.com"],
+    #     show_attendees: true
+    #   )
+    #   url = CalInvite::Providers::Outlook.new(event).generate
+    #
+    # @see Office365 For corporate Office 365 calendar URLs
     class Outlook < BaseProvider
+      # Generates an Outlook.com calendar URL for the event.
+      # Automatically handles both all-day and time-specific events.
+      #
+      # @return [String] The Outlook.com calendar URL
+      # @raise [ArgumentError] If required time fields are missing for non-all-day events
       def generate
         if event.all_day
           generate_all_day_event
@@ -14,6 +49,10 @@ module CalInvite
 
       private
 
+      # Generates a URL for an all-day event.
+      # Uses simplified date format and sets the allday flag.
+      #
+      # @return [String] The Outlook.com calendar URL for an all-day event
       def generate_all_day_event
         params = {
           path: '/calendar/0/action/compose',
@@ -21,10 +60,9 @@ module CalInvite
           allday: 'true'
         }
 
-        # Use current date if no start_time specified
+        # Set start and end dates
         start_date = event.start_time || Time.now
-        end_date = event.end_time || (start_date + 86400) # Add one day if no end_time
-
+        end_date = event.end_time || (start_date + 86400)
         params[:startdt] = format_date(start_date)
         params[:enddt] = format_date(end_date)
 
@@ -32,6 +70,11 @@ module CalInvite
         build_url(params)
       end
 
+      # Generates a URL for a regular (time-specific) event.
+      # Includes specific start and end times in UTC format.
+      #
+      # @return [String] The Outlook.com calendar URL for a regular event
+      # @raise [ArgumentError] If start_time or end_time is missing
       def generate_single_event
         params = {
           path: '/calendar/0/action/compose',
@@ -43,21 +86,38 @@ module CalInvite
 
         params[:startdt] = format_time(event.start_time)
         params[:enddt] = format_time(event.end_time)
-
         add_optional_params(params)
         build_url(params)
       end
 
+      # Formats a time object as a date string for Outlook.com.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted date (YYYY-MM-DD)
       def format_date(time)
         time.strftime('%Y-%m-%d')
       end
 
+      # Formats a time object as a UTC timestamp for Outlook.com.
+      # Outlook.com handles timezone conversion on their end.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC time (YYYY-MM-DDThh:mm:ssZ)
       def format_time(time)
-        time.utc.strftime('%Y-%m-%dT%H:%M:%S')
+        # Always use UTC format, timezone is handled by the calendar
+        time.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
       end
 
+      # Adds optional parameters to the URL parameters hash.
+      # Handles description, virtual meeting URL, location, and attendees.
+      #
+      # @param params [Hash] The parameters hash to update
+      # @return [Hash] The updated parameters hash
       def add_optional_params(params)
-        params[:body] = 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[:body] = url_encode(description_parts.join("\n\n")) if description_parts.any?
         params[:location] = url_encode(format_location) if format_location
 
         if attendees = attendees_list
@@ -67,6 +127,10 @@ module CalInvite
         params
       end
 
+      # Builds the final Outlook.com calendar URL.
+      #
+      # @param params [Hash] The parameters to include in the URL
+      # @return [String] The complete Outlook.com calendar URL
       def build_url(params)
         query = params.map { |k, v| "#{k}=#{v}" }.join('&')
         "https://outlook.live.com/calendar/0/action/compose?#{query}"

data/lib/cal_invite/providers/yahoo.rb

@@ -3,9 +3,44 @@
 # lib/cal_invite/providers/yahoo.rb
 module CalInvite
   module Providers
+    # Yahoo Calendar provider for generating calendar event URLs.
+    # This provider generates URLs that open the Yahoo Calendar with a pre-filled
+    # event creation form. Supports all-day events, regular events, and multi-day
+    # sessions with proper timezone handling.
+    #
+    # Note: Yahoo Calendar handles multi-day sessions differently from other providers,
+    # generating separate event URLs for each session.
+    #
+    # @example Creating a regular event URL
+    #   event = CalInvite::Event.new(
+    #     title: "Team Meeting",
+    #     start_time: Time.now,
+    #     end_time: Time.now + 3600,
+    #     description: "Weekly team sync",
+    #     timezone: "America/New_York"
+    #   )
+    #   yahoo = CalInvite::Providers::Yahoo.new(event)
+    #   url = yahoo.generate
+    #
+    # @example Creating a multi-day event URL
+    #   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") }
+    #     ]
+    #   )
+    #   urls = CalInvite::Providers::Yahoo.new(event).generate # Returns multiple URLs
     class Yahoo < BaseProvider
+      # Base URL for Yahoo Calendar
       BASE_URL = "https://calendar.yahoo.com"
 
+      # Generates Yahoo Calendar URL(s) for the event.
+      # Handles all event types: all-day, regular, and multi-day sessions.
+      #
+      # @return [String] A single URL for regular or all-day events, or
+      #   multiple URLs (separated by newlines) for multi-day sessions
+      # @raise [ArgumentError] If required time fields are missing for non-all-day events
       def generate
         if event.all_day
           generate_all_day_event
@@ -18,6 +53,10 @@ module CalInvite
 
       private
 
+      # Generates a URL for an all-day event.
+      # Uses simplified date format and sets the allday flag.
+      #
+      # @return [String] The Yahoo Calendar URL for an all-day event
       def generate_all_day_event
         start_date = event.start_time || Time.now
         end_date = event.end_time || (start_date + 86400)
@@ -38,10 +77,19 @@ module CalInvite
         "#{BASE_URL}/?#{URI.encode_www_form(params)}"
       end
 
+      # Generates a URL for a regular (time-specific) event.
+      # Includes specific start and end times with timezone information.
+      #
+      # @return [String] The Yahoo Calendar URL for a regular event
+      # @raise [ArgumentError] If start_time or end_time is missing
       def generate_single_event
         raise ArgumentError, "Start time is required" unless event.start_time
         raise ArgumentError, "End time is required" unless event.end_time
 
+        description_parts = []
+        description_parts << format_description if format_description
+        description_parts << "Virtual Meeting URL: #{format_url}" if format_url
+
         params = {
           v: 60,
           view: 'd',
@@ -49,7 +97,7 @@ module CalInvite
           title: event.title,
           st: format_time(event.start_time),
           et: format_time(event.end_time),
-          desc: format_description,
+          desc: description_parts.join("\n\n"),
           in_loc: format_location,
           crnd: event.timezone
         }
@@ -57,9 +105,11 @@ module CalInvite
         "#{BASE_URL}/?#{URI.encode_www_form(params)}"
       end
 
+      # Generates multiple URLs for multi-day events, one for each session.
+      # Yahoo Calendar doesn't support multiple sessions in a single URL.
+      #
+      # @return [String] Multiple Yahoo Calendar URLs, one per line
       def generate_multi_day_event
-        # Yahoo doesn't support multi-day events in a single URL
-        # Return multiple URLs, one for each session
         sessions = event.multi_day_sessions.map do |session|
           params = {
             v: 60,
@@ -79,12 +129,22 @@ module CalInvite
         sessions.join("\n")
       end
 
+      # Formats a time object as a date string for Yahoo Calendar.
+      #
+      # @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 UTC timestamp for Yahoo Calendar.
+      # Yahoo Calendar accepts timezone separately in the crnd parameter.
+      #
+      # @param time [Time] The time to format
+      # @return [String] The formatted UTC time (YYYYMMDDTHHmmSSZ)
       def format_time(time)
-        time.utc.strftime("%Y%m%dT%H%M%S")
+        # Always use UTC format for the URL, timezone is passed separately
+        time.utc.strftime("%Y%m%dT%H%M%SZ")
       end
     end
   end

data/lib/cal_invite/providers.rb

@@ -1,17 +1,24 @@
 # frozen_string_literal: true
 
+require_relative 'providers/base_provider'
+
 # lib/cal_invite/providers.rb
+# Namespace module for all calendar providers supported by CalInvite.
+# Each provider implements the interface defined by BaseProvider.
+#
+# @see CalInvite::Providers::BaseProvider
 module CalInvite
   module Providers
+    # List of supported calendar provider symbols
     SUPPORTED_PROVIDERS = %i[google ical outlook yahoo ics office365].freeze
 
-    autoload :BaseProvider, 'cal_invite/providers/base_provider'
     autoload :Google, 'cal_invite/providers/google'
     autoload :Ical, 'cal_invite/providers/ical'
     autoload :Outlook, 'cal_invite/providers/outlook'
     autoload :Office365, 'cal_invite/providers/office365'
     autoload :Yahoo, 'cal_invite/providers/yahoo'
+    autoload :IcsContent, 'cal_invite/providers/ics_content'
+    autoload :IcsDownload, 'cal_invite/providers/ics_content'
     autoload :Ics, 'cal_invite/providers/ics'
-
   end
 end

data/lib/cal_invite/version.rb

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

data/lib/cal_invite.rb

@@ -1,26 +1,65 @@
 # lib/cal_invite.rb
+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/event'
 require 'cal_invite/providers'
 
+# The main module for the CalInvite gem. This module provides functionality for generating
+# calendar invites across different calendar 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
+#   event = CalInvite::Event.new(
+#     title: "Team Meeting",
+#     start_time: Time.now,
+#     end_time: Time.now + 3600
+#   )
+#   google_url = event.generate_calendar_url(:google)
+#
 module CalInvite
   class Error < StandardError; end
 
   class << self
+    # Returns the current configuration object.
+    # @return [CalInvite::Configuration] The current configuration object
     attr_accessor :configuration
 
+    # Configures the CalInvite gem through a block.
+    #
+    # @yield [config] The configuration object to be modified
+    # @yieldparam config [CalInvite::Configuration] The configuration object
+    # @return [void]
+    #
+    # @example
+    #   CalInvite.configure do |config|
+    #     config.timezone = 'UTC'
+    #     config.cache_store = :memory_store
+    #   end
     def configure
       self.configuration ||= Configuration.new
       yield(configuration)
     end
 
+    # Resets the configuration to default values.
+    #
+    # @return [void]
     def reset_configuration!
       self.configuration = Configuration.new
     end
+
+    # Include caching methods at the module level
+    include Caching
   end
 end

data/lib/tasks/rdoc.rake

@@ -0,0 +1,13 @@
+# lib/tasks/rdoc.rake
+require 'rdoc/task'
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'CalInvite Documentation'
+  rdoc.main     = 'README.md'
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--charset' << 'UTF-8'
+  rdoc.options << '--markup' << 'markdown'
+  rdoc.rdoc_files.include('README.md', 'LICENSE', 'lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/cal_invite/version.rb')
+end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: cal-invite
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Stephane Paquet
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-17 00:00:00.000000000 Z
-dependencies: []
+date: 2024-12-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
 description: CalInvite provides a simple way to generate calendar invite URLs for
   various providers (Google, Outlook, Yahoo) and ICS files
 email:
@@ -18,7 +46,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
+- ".rdoc_options"
 - ".rubocop.yml"
+- CACHING.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -27,7 +58,10 @@ 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/providers.rb
@@ -35,10 +69,12 @@ files:
 - lib/cal_invite/providers/google.rb
 - lib/cal_invite/providers/ical.rb
 - lib/cal_invite/providers/ics.rb
+- lib/cal_invite/providers/ics_content.rb
 - lib/cal_invite/providers/office365.rb
 - 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/the-pew-inc/cal-invite
 licenses:
@@ -48,7 +84,21 @@ metadata:
   source_code_uri: https://github.com/the-pew-inc/cal-invite
   changelog_uri: https://github.com/the-pew-inc/cal-invite/blob/master/CHANGELOG.md
 post_install_message:
-rdoc_options: []
+rdoc_options:
+- "--title"
+- CalInvite Documentation
+- "--main"
+- README.md
+- "--line-numbers"
+- "--all"
+- "--charset"
+- UTF-8
+- "--markup"
+- markdown
+- "--exclude"
+- "^(test|spec|features)/"
+- "--exclude"
+- lib/cal_invite/version.rb
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement