cal-invite 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c410ac7a9f4a0163b9984196b0b9eb0f68974c92c9baf55fdd0d5b3048478dab
-  data.tar.gz: a9e3f6f5ed24978f5f891f2a8818f68fa6457f0d28570ff0d5a19c0b4460e3c1
+  metadata.gz: c3f79844d8b3618ca4539da1033070e310d84d8d6a004d921ce28b7230fda371
+  data.tar.gz: c7f43118837065df3744b139fc5e0abcbedbb4e9a6490f660c0d79b0bff85d6b
 SHA512:
-  metadata.gz: 7ae7e0b223af18c95eff52db6614ff44c4efc3277b146ab909a60582b86c66140e82bade3fc6507a9eb1f198c404de0896ffcd3bda8b7846bf7917d45500f7b5
-  data.tar.gz: 97e1766052ab48c325eaab422d06420e7f98d94cdddd6d9320f9605b5180a1fed783b9d5555bfff47f0ea1ceeaa15225d504f2b538def27395272e8a2752c140
+  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/CACHING.md

@@ -0,0 +1,148 @@
+## Caching
+
+CalInvite supports flexible caching options when used within a Rails application. You can configure the cache store to use any of Rails' supported cache stores including memory store, Redis, or a custom cache store implementation.
+
+### Basic Configuration
+
+Configure caching in your Rails application's initializer:
+
+```ruby
+# config/initializers/cal_invite.rb
+CalInvite.configure do |config|
+  # Use Rails.cache by default
+  config.cache_store = Rails.cache
+  
+  # Optional: Set a custom prefix for cache keys
+  config.cache_prefix = 'my_app_cal_invite'
+  
+  # Optional: Set cache expiration (in seconds)
+  config.cache_expires_in = 3600 # 1 hour
+end
+```
+
+### Available Cache Stores
+
+CalInvite supports the following cache stores:
+
+1. Memory Store (default)
+```ruby
+config.cache_store = :memory_store
+```
+
+2. Null Store (for disabling caching)
+```ruby
+config.cache_store = :null_store
+```
+
+3. Custom Cache Store
+```ruby
+# Any object that implements read/write/delete methods
+config.cache_store = MyCacheStore.new
+```
+
+4. Rails Cache
+```ruby
+# Use your Rails application's configured cache
+config.cache_store = Rails.cache
+```
+
+### Cache Configuration Options
+
+- `cache_store`: The storage mechanism for cached data
+- `cache_prefix`: Prefix for all cache keys (default: 'cal_invite')
+- `cache_expires_in`: Default cache expiration time in seconds
+- `timezone`: Default timezone for cache keys (default: 'UTC')
+
+### Custom Cache Adapters
+
+You can implement custom cache adapters by creating a class that responds to the following methods:
+
+```ruby
+class CustomCacheStore
+  def read(key)
+    # Implementation for retrieving cached value
+  end
+
+  def write(key, value, options = {})
+    # Implementation for storing value in cache
+    # options may include :expires_in
+  end
+
+  def delete(key)
+    # Implementation for removing cached value
+  end
+
+  def clear
+    # Implementation for clearing all cached values
+  end
+end
+
+# Configure CalInvite to use your custom cache store
+CalInvite.configure do |config|
+  config.cache_store = CustomCacheStore.new
+end
+```
+
+### Automatic Cache Invalidation
+
+The cache is automatically invalidated in the following scenarios:
+
+1. When event attributes are updated via `update_attributes`
+2. When a new calendar URL is generated
+3. When the configuration changes
+
+### Best Practices
+
+1. **Cache Store Selection**: Choose an appropriate cache store based on your needs:
+   - Use `:memory_store` for development and small applications
+   - Use Rails.cache for production applications
+   - Implement a custom cache store for specific requirements
+
+2. **Cache Key Management**:
+   - The gem automatically generates unique cache keys based on event attributes
+   - Keys include a prefix for namespace isolation
+   - Consider your timezone settings when debugging cache issues
+
+3. **Expiration Strategy**:
+   - Set appropriate expiration times based on your use case
+   - Consider using shorter expiration times for frequently changing data
+   - Use `nil` expiration for permanent caching (until manual invalidation)
+
+### Example Rails Integration
+
+Here's a complete example of setting up caching in a Rails application:
+
+```ruby
+# config/initializers/cal_invite.rb
+CalInvite.configure do |config|
+  if Rails.env.production?
+    # Use Rails cache in production
+    config.cache_store = Rails.cache
+    config.cache_expires_in = 1.hour
+  else
+    # Use memory store in development
+    config.cache_store = :memory_store
+    config.cache_expires_in = 5.minutes
+  end
+
+  config.cache_prefix = "cal_invite:#{Rails.env}"
+  config.timezone = 'UTC'
+end
+```
+
+### Testing with Caching
+
+When writing tests that involve caching:
+
+```ruby
+# In your test setup
+CalInvite.configure do |config|
+  config.cache_store = :memory_store
+  config.cache_expires_in = 3600 # 1 hour in seconds
+end
+
+# Clear cache between tests
+def setup
+  CalInvite.configuration.cache_store.clear
+end
+```

data/CHANGELOG.md

@@ -2,8 +2,22 @@
 
 ## [Released]
 
+## [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
+- Updating the README file to reflect latest usage changes
+- Minor bug fixes and improvments.
+
 ## [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
@@ -11,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

@@ -4,7 +4,6 @@ A Ruby gem for generating calendar invitations across multiple calendar platform
 
 [![Gem Version](https://badge.fury.io/rb/cal-invite.svg)](https://badge.fury.io/rb/cal-invite)
 ![Build Status](https://github.com/the-pew-inc/cal-invite/actions/workflows/main.yml/badge.svg)
-
 [![License](https://img.shields.io/github/license/the-pew-inc/cal-invite.svg)]
 
 ## Compatibility
@@ -15,7 +14,7 @@ A Ruby gem for generating calendar invitations across multiple calendar platform
 ## Supported Calendar Platforms
 
 Direct Integration:
-- Apple iCal
+- Apple iCal (with proper timezone support)
 - Microsoft Outlook
 - Microsoft Outlook 365
 - Google Calendar
@@ -52,21 +51,47 @@ $ gem install cal-invite
 
 ### Basic Event Creation
 
+Important notes:
+- Always provide times in UTC
+- Use the timezone parameter to specify the display timezone
+- Location and URL are handled separately for better calendar integration
+
 ```ruby
-# Single day event
+# Create an event with physical location
 event = CalInvite::Event.new(
   title: "Team Meeting",
-  start_time: Time.current,
-  end_time: Time.current + 2.hours,
+  start_time: Time.current.utc,  # Always use UTC times
+  end_time: Time.current.utc + 2.hours,
   description: "Weekly team sync",
-  location: "Conference Room A",
-  url: "https://zoom.us/j/123456789",
+  location: "Conference Room A",  # Physical location
+  timezone: "America/New_York",  # Display timezone
   attendees: ["person@example.com"],
   show_attendees: true,
-  timezone: "America/New_York",
   notes: "Please bring your laptop"
 )
 
+# Create an event with both physical and virtual locations
+event = CalInvite::Event.new(
+  title: "Hybrid Meeting",
+  start_time: Time.current.utc,
+  end_time: Time.current.utc + 2.hours,
+  description: "Weekly team sync",
+  location: "Conference Room A",  # Physical location
+  url: "https://zoom.us/j/123456789",  # Virtual meeting URL
+  timezone: "America/New_York",
+  attendees: ["person@example.com"],
+  show_attendees: true
+)
+
+# All-day event
+event = CalInvite::Event.new(
+  title: "Company All-Day Event",
+  start_time: Date.today.beginning_of_day.utc,
+  end_time: Date.today.end_of_day.utc,
+  all_day: true,
+  timezone: "America/New_York"
+)
+
 # Multi-day event
 event = CalInvite::Event.new(
   title: "Training Workshop",
@@ -82,19 +107,125 @@ event = CalInvite::Event.new(
   ],
   description: "Advanced Ruby Training",
   location: "Training Center",
-  url: "https://zoom.us/j/123456789",
+  url: "https://zoom.us/j/123456789",  # Virtual meeting URL kept separate
   timezone: "America/New_York",
   notes: "Bring your own laptop"
 )
 
-ical_url       = event.calendar_url(:ical)
-google_url     = event.calendar_url(:google)
-outlook_url    = event.calendar_url(:outlook)
-outlook365_url = event.calendar_url(:office365)
-yahoo_url      = event.calendar_url(:yahoo)
-ics_content    = event.calendar_url(:ics)
+# Generate calendar URLs
+ical_url       = event.generate_calendar_url(:ical)
+google_url     = event.generate_calendar_url(:google)
+outlook_url    = event.generate_calendar_url(:outlook)
+outlook365_url = event.generate_calendar_url(:office365)
+yahoo_url      = event.generate_calendar_url(:yahoo)
+```
+
+### Implementing ICS Downloads
+
+To enable ICS file downloads in your application, you'll need to:
+
+1. Create an endpoint that will handle the download request
+2. Generate the ICS content
+3. Send the file to the user
+
+Here's a basic example of the controller logic:
+
+```ruby
+# In your controller action
+def download_calendar
+  event = # ... your event creation logic ...
+  
+  content = CalInvite::Providers::Ics.new(event).generate
+  filename = "#{event.title.downcase.gsub(/[^0-9A-Za-z.\-]/, '_')}_#{Time.now.strftime('%Y%m%d')}.ics"
+  
+  send_data(
+    content,
+    filename: filename,
+    type: 'text/calendar; charset=UTF-8',
+    disposition: 'attachment'
+  )
+end
+```
+
+You can implement this in any controller and route that makes sense for your application's architecture.
+
+### ICS File Generation
+
+The gem provides two ways to generate ICS files:
+
+1. Direct content generation:
+```ruby
+event = CalInvite::Event.new(
+  title: "Meeting",
+  start_time: Time.current.utc,
+  end_time: Time.current.utc + 1.hour,
+  timezone: "America/New_York"
+)
+
+# Generate ICS content
+content = CalInvite::Providers::Ics.new(event).generate
+```
+
+2. Rails controller integration:
+```ruby
+# In your controller
+def download_ics
+  event = CalInvite::Event.new(
+    title: "Meeting",
+    start_time: Time.current.utc,
+    end_time: Time.current.utc + 1.hour,
+    timezone: "America/New_York"
+  )
+  
+  content = CalInvite::Providers::Ics.new(event).generate
+  filename = "#{event.title.downcase.gsub(/[^0-9A-Za-z.\-]/, '_')}_#{Time.now.strftime('%Y%m%d')}.ics"
+  
+  send_data(
+    content,
+    filename: filename,
+    type: 'text/calendar; charset=UTF-8',
+    disposition: 'attachment'
+  )
+end
+```
+
+### Important Notes
+
+1. Time Handling:
+   - Always provide times in UTC to the Event constructor
+   - Use the timezone parameter to specify the display timezone
+   - All-day events should use beginning_of_day.utc and end_of_day.utc
+
+2. Location and URL:
+   - Physical location goes in the `location` parameter
+   - Virtual meeting URL goes in the `url` parameter
+   - They are handled separately for better calendar integration
+
+3. ICS Files:
+   - Both Apple iCal and standard ICS files now properly handle timezones
+   - Attendees are properly formatted with RSVP options
+   - Virtual meeting URLs are properly separated from physical locations
+
+## Caching Support
+
+CalInvite includes built-in caching support to improve performance when generating calendar URLs. To enable caching in your Rails application:
+
+```ruby
+# config/initializers/cal_invite.rb
+CalInvite.configure do |config|
+  # Use Rails cache by default
+  config.cache_store = Rails.cache
+  
+  # Optional: Set cache prefix
+  config.cache_prefix = 'my_app_cal_invite'
+  
+  # Optional: Set expiration time (in seconds)
+  config.cache_expires_in = 3600 # 1 hour
+end
 ```
 
+For detailed information about configuring caching in Rails applications and available options, see our [Caching Guide](https://github.com/the-pew-inc/cal-invite/blob/master/CACHING.md)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -105,16 +236,22 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Add test(s) as necessary.
 
-Run all the tests before submiting: `bundle exec rake test`
+Run all the tests before submitting: `bundle exec rake test`
 
 ## Contributing
 
 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).
 
 ## Code of Conduct
 
-Everyone interacting in the Cal::Invite project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/the-pew-inc/cal-invite/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Cal::Invite project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/the-pew-inc/cal-invite/blob/master/CODE_OF_CONDUCT.md).

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/caching.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# lib/cal_invite/caching.rb
+require 'active_support/concern'
+
+module CalInvite
+  module Caching
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def fetch_from_cache(key, options = {}, &block)
+        full_key = generate_cache_key(key)
+        store = CalInvite.configuration.cache_store
+
+        if store.respond_to?(:fetch)
+          store.fetch(full_key, options, &block)
+        else
+          cached = store.read(full_key)
+          return cached if cached
+
+          value = block.call
+          store.write(full_key, value, options)
+          value
+        end
+      end
+
+      def write_to_cache(key, value, options = {})
+        full_key = generate_cache_key(key)
+        options[:expires_in] ||= CalInvite.configuration.cache_expires_in
+        CalInvite.configuration.cache_store.write(full_key, value, options)
+      end
+
+      def read_from_cache(key)
+        full_key = generate_cache_key(key)
+        CalInvite.configuration.cache_store.read(full_key)
+      end
+
+      def clear_cache!
+        store = CalInvite.configuration.cache_store
+        if store.respond_to?(:delete_matched)
+          store.delete_matched("#{CalInvite.configuration.cache_prefix}:*")
+        else
+          store.clear
+        end
+      end
+
+      def clear_event_cache!(event_id)
+        delete_cache_pattern("events:#{event_id}")
+      end
+
+      def clear_provider_cache!(provider)
+        delete_cache_pattern("providers:#{provider}")
+      end
+
+      def generate_cache_key(*parts)
+        ([CalInvite.configuration.cache_prefix] + parts).join(':')
+      end
+
+      private
+
+      def delete_cache_pattern(pattern)
+        store = CalInvite.configuration.cache_store
+        full_pattern = generate_cache_key(pattern)
+
+        if store.respond_to?(:delete_matched)
+          store.delete_matched("#{full_pattern}:*")
+        else
+          # Fallback for stores that don't support pattern deletion
+          store.delete(full_pattern)
+        end
+      end
+    end
+  end
+end