cal-invite 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 100b68a6d13bbb3b58234eee38701ffc1c6d215daf126ba98c89e249829d716e
-  data.tar.gz: ed0388023bf7245fb09c14294ce91610c189996f7c49cf246f47589efd17c1d2
+  metadata.gz: c3f79844d8b3618ca4539da1033070e310d84d8d6a004d921ce28b7230fda371
+  data.tar.gz: c7f43118837065df3744b139fc5e0abcbedbb4e9a6490f660c0d79b0bff85d6b
 SHA512:
-  metadata.gz: 9755f61af9fbed611988f3355647991c4dabe8b9a1f4ff3c0c8e77aa0c9d2c744e270aa09e01c0f7284fd0c40bce1af07a0a0a68f557e19be901969a89f32c3d
-  data.tar.gz: 18b4e856b14b6d5a49a2dce096b56e8b068813f058cf6648ceb9f37f04d5793454ff46bb1a7f1ed4e1f35f1e8faa796595915e84334d9763323b814744d47808
+  metadata.gz: 884ac33c88abc0b496496ba495e6bc4381c617df1c327cfd52e8995121f3a607c576724f3c7095b8186a3ffc10c5020ddd7643c4d79ad7746e7419b4da4277f0
+  data.tar.gz: b026672548b98ad349ab094a5def2d1f3c7b7904592ed1528caec8978c9d6c0c4f584e68706d307d31fdcfe769ca119d71df516f535bbc5ccc50a03768fefeac

data/.rdoc_options

@@ -0,0 +1,85 @@
+---
+encoding: UTF-8
+static_path: ["./doc/images"]
+charset: UTF-8
+exclude: ["vendor/*", "tmp/*", ".*/*"]
+hyperlink_all: true
+line_numbers: true
+locale: en
+main: README.md
+markup: markdown
+output_decoration: true
+show_hash: false
+tab_width: 2
+template_stylesheets: []
+title: "CalInvite - Calendar Invite Generator by DashAPI"
+visibility: :public
+webcvs: https://github.com/the-pew-inc/cal-invite
+
+# Custom sections for better organization
+sections:
+  - title: Calendar Providers
+    dir: lib/cal_invite/providers
+    include: ["**/*.rb"]
+  - title: Core
+    dir: lib/cal_invite
+    include: ["*.rb"]
+
+extra_docs:
+  - README.md
+  - CHANGELOG.md
+  - LICENSE.txt
+
+# Options for better documentation organization
+options:
+  all:
+    - "--title=CalInvite - Calendar Invite Generator by DashAPI"
+    - "--line-numbers"
+    - "--diagram"  # Include diagrams if you have any
+    - "--main=README.md"
+  SystemExtension:
+    - "--title=CalInvite System Extensions"
+  
+# Documentation sections
+doc_sections:
+  - "Calendar Provider Implementation"
+  - "Configuration"
+  - "Event Management"
+  - "Utility Functions"
+
+# Additional documentation metadata
+metadata:
+  copyright: "© 2024 ThePew Inc. All rights reserved."
+  authors:
+    - "Stephane Paquet"
+  website: "https://github.com/the-pew-inc/cal-invite"
+  license: "MIT"
+
+# Documentation themes and styles
+template:
+  css: []  # You can add custom CSS files if needed
+  javascript: []  # You can add custom JS files if needed
+
+# Search engine optimization
+search_index:
+  include:
+    - "**/*.rb"
+  exclude:
+    - "test/**/*"
+    - "spec/**/*"
+    - "vendor/**/*"
+
+# Documentation organization
+groups:
+  Core:
+    - CalInvite
+    - CalInvite::Configuration
+    - CalInvite::Event
+  Providers:
+    - CalInvite::Providers::BaseProvider
+    - CalInvite::Providers::Google
+    - CalInvite::Providers::Outlook
+    - CalInvite::Providers::Office365
+    - CalInvite::Providers::Yahoo
+    - CalInvite::Providers::Ics
+    - CalInvite::Providers::Ical

data/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## [v0.1.3] - 2024-12-19
 
+- Add support to RDoc
+
+## [v0.1.3] - 2024-12-19
+
 - Apple iCal and ics file can now be either generated or wrap to be downloaded
 - Add Caching management support
 - Add CACHING.md for more details about how to use caching in a Rails app
@@ -12,6 +16,8 @@
 
 ## [v0.1.2] - 2024-12-17
 
+⚠️ This version should not be used
+
 - Add support to Microsoft office 365 calendar invite URL
 - Update the README
 - Add an example
@@ -19,6 +25,8 @@
 
 ## [v0.1.1] - 2024-12-17
 
+⚠️ This version should not be used
+
 Fixing a bug in the gemspec file
 
 ## [Unreleased]

data/README.md

@@ -242,6 +242,12 @@ Run all the tests before submitting: `bundle exec rake test`
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/the-pew-inc/cal-invite. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/the-pew-inc/cal-invite/blob/master/CODE_OF_CONDUCT.md).
 
+## Documentation
+
+The documentation is spread accross the README, CAHCING and the doc folder.
+
+The documentation can be generated using `bundle exec rake rdoc`
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -2,11 +2,37 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rdoc/task"
 
+# Test task configuration
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+# RDoc task configuration
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'CalInvite Documentation'
+  rdoc.main     = 'README.md'
+
+  # Configure RDoc options
+  rdoc.options << '--line-numbers'
+  rdoc.options << '--charset' << 'UTF-8'
+  rdoc.options << '--markup' << 'markdown'
+  rdoc.options << '--all'
+  rdoc.options << '--exclude' << '^(test|spec|features)/'
+
+  # Include files to document
+  rdoc.rdoc_files.include('README.md', 'LICENSE.txt', 'lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/cal_invite/version.rb')
+end
+
+# Define a task to clean documentation
+task 'rdoc:clean' do
+  rm_rf 'doc'
+end
+
+# Keep test as the default task
 task default: :test

data/lib/cal_invite/configuration.rb

@@ -1,10 +1,19 @@
 # frozen_string_literal: true
 
 # lib/cal_invite/configuration.rb
+# 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_reader :cache_store, :cache_prefix, :cache_expires_in, :webhook_secret, :timezone
 
+    # Initializes a new Configuration instance with default values.
     def initialize
       @cache_store = nil
       @cache_prefix = 'cal_invite'
@@ -13,6 +22,13 @@ module CalInvite
       @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
@@ -30,18 +46,30 @@ module CalInvite
       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

data/lib/cal_invite/event.rb

@@ -1,7 +1,22 @@
 # frozen_string_literal: true
-# lib/cal_invite/event.rb
+
 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
   class Event
     attr_accessor :title,
@@ -17,6 +32,23 @@ module CalInvite
                   :multi_day_sessions,
                   :all_day
 
+    # 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 [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 [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'
@@ -30,6 +62,17 @@ module CalInvite
       validate!
     end
 
+    # 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 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!
 
@@ -50,6 +93,17 @@ module CalInvite
       url
     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
+    #
+    # @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}=")
@@ -61,10 +115,19 @@ module CalInvite
 
     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)
       string.split('_').map(&:capitalize).join
     end
 
+    # Validates the event attributes.
+    #
+    # @raise [ArgumentError] If required attributes are missing or invalid
     def validate!
       raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
@@ -74,12 +137,19 @@ module CalInvite
       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?
 
@@ -104,11 +174,20 @@ module CalInvite
       "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?
 
@@ -120,6 +199,9 @@ module CalInvite
       )
     end
 
+    # Invalidates all cached URLs for this event.
+    #
+    # @return [void]
     def invalidate_cache
       return unless caching_enabled?
 

data/lib/cal_invite/providers/base_provider.rb

@@ -1,17 +1,36 @@
+# frozen_string_literal: true
+
 # 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
 
+  # 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
 
+  # 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

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,16 +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)
         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}"