cal-invite 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c410ac7a9f4a0163b9984196b0b9eb0f68974c92c9baf55fdd0d5b3048478dab
-  data.tar.gz: a9e3f6f5ed24978f5f891f2a8818f68fa6457f0d28570ff0d5a19c0b4460e3c1
+  metadata.gz: 100b68a6d13bbb3b58234eee38701ffc1c6d215daf126ba98c89e249829d716e
+  data.tar.gz: ed0388023bf7245fb09c14294ce91610c189996f7c49cf246f47589efd17c1d2
 SHA512:
-  metadata.gz: 7ae7e0b223af18c95eff52db6614ff44c4efc3277b146ab909a60582b86c66140e82bade3fc6507a9eb1f198c404de0896ffcd3bda8b7846bf7917d45500f7b5
-  data.tar.gz: 97e1766052ab48c325eaab422d06420e7f98d94cdddd6d9320f9605b5180a1fed783b9d5555bfff47f0ea1ceeaa15225d504f2b538def27395272e8a2752c140
+  metadata.gz: 9755f61af9fbed611988f3355647991c4dabe8b9a1f4ff3c0c8e77aa0c9d2c744e270aa09e01c0f7284fd0c40bce1af07a0a0a68f557e19be901969a89f32c3d
+  data.tar.gz: 18b4e856b14b6d5a49a2dce096b56e8b068813f058cf6648ceb9f37f04d5793454ff46bb1a7f1ed4e1f35f1e8faa796595915e84334d9763323b814744d47808

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,6 +2,14 @@
 
 ## [Released]
 
+## [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
 
 - Add support to Microsoft office 365 calendar invite URL

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,7 +236,7 @@ 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
 
@@ -117,4 +248,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## 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/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

data/lib/cal_invite/configuration.rb

@@ -1,13 +1,49 @@
+# frozen_string_literal: true
+
 # lib/cal_invite/configuration.rb
-module CalInvites
+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
 
     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
+
+    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
+
+    def cache_prefix=(prefix)
+      @cache_prefix = prefix.to_s
+    end
+
+    def cache_expires_in=(duration)
+      @cache_expires_in = duration.to_i
+    end
+
+    def webhook_secret=(secret)
+      @webhook_secret = secret
+    end
+
+    def timezone=(tz)
+      @timezone = tz.to_s
+    end
   end
 end