cal-invite 0.2.1 → 0.3.0

data/CACHING.md

@@ -1,148 +0,0 @@
-## 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/CLAUDE.md

@@ -1,49 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Overview
-
-CalInvite is a Ruby gem for generating calendar invitations (URLs and .ics files) across multiple platforms: Google, Outlook, Outlook 365, Yahoo, Apple iCal, and generic .ics. Ruby >= 3.0.0, Rails 6.0–8.0 compatible, depends on `activesupport`.
-
-## Commands
-
-```bash
-bundle install          # install dependencies
-rake test                # run full test suite (default rake task)
-rake test TEST=test/cal_invite/event_test.rb   # run a single test file
-ruby -Itest -Ilib test/cal_invite/event_test.rb # run a single test file directly
-rake rdoc                # generate RDoc documentation into doc/
-rake rdoc:clean          # remove generated doc/
-```
-
-Tests are Minitest-based, files live under `test/cal_invite/`, named `*_test.rb`. Coverage is collected via SimpleCov (see `coverage/`).
-
-## Architecture
-
-- **`CalInvite` module** (`lib/cal_invite.rb`) — top-level entry point. Holds a singleton `CalInvite.configuration` (a `Configuration` instance) set via `CalInvite.configure { |c| ... }`. Mixes in `Caching` at the module level for class-level cache helpers.
-
-- **`CalInvite::Event`** (`lib/cal_invite/event.rb`) — the central object. Holds all event attributes (title, start/end time, location, url, attendees, timezone, notes, multi-day sessions, all-day flag). `generate_calendar_url(provider)` is the main API: it validates the event, checks the cache (MD5 hash of all attributes + provider as key), and if not cached, resolves `CalInvite::Providers::<CapitalizedProvider>`, instantiates it with `self`, and calls `#generate`. Location and virtual-meeting URL are intentionally separate fields (not merged) so each provider can format them appropriately.
-
-- **`CalInvite::Providers`** (`lib/cal_invite/providers.rb`) — namespace with `SUPPORTED_PROVIDERS = %i[google ical outlook yahoo ics office365]`. Provider classes are autoloaded from `lib/cal_invite/providers/*.rb`. To add a new provider: create a class extending `BaseProvider`, implement `#generate`, register it here with `autoload`, and add its symbol to `SUPPORTED_PROVIDERS`.
-
-- **`BaseProvider`** (`lib/cal_invite/providers/base_provider.rb`) — abstract base class (note: it's a top-level `class BaseProvider`, not namespaced under `CalInvite::Providers`). Defines the `#generate` contract (must raise `NotImplementedError` if not overridden) plus shared helpers used by subclasses: URL-building (`url_encode`, `format_description`, `format_location`, `format_url`, `format_description_with_url`, `add_optional_params`) and iCalendar property formatting (`attendees_list`, `attendee_emails`, `attendee_hash_value`, `attendee_line`, `organizer_line`, `method_value`, `status_line`, `geo_line`, `transp_line`, `busystatus_line`, `class_line`, `importance_lines`, `disallow_counter_line`, `rrule_line`, `valarm_lines`, `local_wall_time`, `vtimezone_lines`). `attendee_hash_value(attendee, key)` is the correct way to read an attendee-hash field (tries symbol then string key) — don't reintroduce `attendee[:key] || attendee["key"]`, which silently drops explicit `false` values. Each concrete provider (`Google`, `Outlook`, `Office365`, `Yahoo`, `Ical`, `Ics`) builds a provider-specific URL or content string from the `Event` using these helpers.
-
-- **`Ics` / `IcsContent` providers** (`ics.rb`, `ics_content.rb`) — generate actual `.ics` file content (RFC 5545) rather than a URL, for direct download flows (see README's `send_data` controller example). `IcsDownload` lives in `ics_content.rb` alongside `IcsContent` (not an alias). All ics-family providers accept a `method:` (`:publish`/`:request`/`:cancel`/`:reply`/`:counter`/`:decline_counter`) passed through `Event#generate_calendar_url`. Use `BaseProvider#method_value` (not `method.to_s.upcase`) when emitting the `METHOD:` line — `:decline_counter` must render as `METHOD:DECLINECOUNTER` (one word) per RFC 5545, unlike its Ruby symbol. `:request` plus `Event#organizer` produces an RFC 5545 meeting request that mail clients render with RSVP actions; `:cancel` (reusing the same `Event#uid`, with `Event#sequence` bumped) produces a real cancellation; `:reply`/`:counter`/`:decline_counter` all omit `RSVP=TRUE` on `ATTENDEE` lines (none of them request a further response). `Event#uid` is stable (auto-generated and memoized per instance, or pass your own) — required so a later `:request`/`:cancel` is recognized as updating the original invite rather than creating a new one. `Event#attendees` entries can be plain email strings or `{ email:, name:, partstat:, rsvp: }` hashes (`partstat:` drives `PARTSTAT=` on the `ATTENDEE` line, default `NEEDS-ACTION`; `rsvp:` overrides the method-derived `RSVP=TRUE`/absent default — needed for e.g. a registration-confirmation invite where the attendee is already `:accepted` and `rsvp: false` suppresses it under `method: :request`). Optional `Event` fields `geo`, `reminders`, `busy`, `visibility`, `rrule`, `calendar_name` map to `GEO:`, `VALARM`, `TRANSP:`, `CLASS:`, `RRULE:`, and `X-WR-CALNAME` respectively; `importance`/`allow_counter` map to Outlook's non-standard `X-MICROSOFT-CDO-IMPORTANCE`/`X-MICROSOFT-DISALLOW-COUNTER` (plus standard `PRIORITY:` and `X-MICROSOFT-CDO-BUSYSTATUS` alongside `TRANSP:`) — safe to always emit since unrecognized `X-` properties are required to be ignored by other clients. See `CONFIGURATION.md`.
-- **Timezones** — `:ics`/`:ical` build a real `VTIMEZONE` (via `CalInvite::IcalTimezone`, backed by `tzinfo`) for any recognized IANA `timezone` other than `'UTC'`, and correctly convert `start_time`/`end_time` (always UTC) to that zone's local wall-clock time for `DTSTART;TZID=...`. `'UTC'` uses plain `Z`-suffixed timestamps with no `VTIMEZONE`.
-
-- **`Caching`** (`lib/cal_invite/caching.rb`) — an `ActiveSupport::Concern` mixed into `CalInvite` at the class level. Provides `fetch_from_cache`, `write_to_cache`, `read_from_cache`, `clear_cache!`, `clear_event_cache!`, `clear_provider_cache!`, all keyed under `CalInvite.configuration.cache_prefix`. Works with any `ActiveSupport::Cache::Store`-compatible store, or a custom object responding to `read`/`write`/`delete`. See also `CACHING.md`.
-
-- **`Configuration`** (`lib/cal_invite/configuration.rb`) — holds `cache_store`, `cache_prefix` (default `'cal_invite'`), `cache_expires_in` (default 24 hours), `webhook_secret`, `timezone` (default `'UTC'`). `cache_store=` accepts `:memory_store`, `:null_store`, or any object implementing `read`/`write`/`delete`.
-
-## Conventions
-
-- Always pass times to `Event.new` in UTC; use the `timezone` attribute only to control display/formatting in the generated invite.
-- `location` (physical) and `url` (virtual meeting link) are kept as distinct fields throughout the provider layer — don't conflate them when adding provider logic.
-- All-day events skip `start_time`/`end_time` validation; multi-day events use the separate `multi_day_sessions` array instead of `start_time`/`end_time`.
-- YARD-style doc comments (`@param`, `@return`, `@example`) are used throughout `lib/` and feed the RDoc-generated docs published to GitHub Pages (`.github/workflows/documentation.yml`) — keep them accurate when changing public method signatures.
-- CalInvite is outbound-only: it renders `.ics` content/URLs and has no concept of inbound RSVP replies. It also can't express Google/Microsoft Calendar-API-only concepts like guest permissions (`guestsCanInviteOthers` etc.) since those have no `.ics`/URL representation at all — but it does generate the genuinely protocol-level equivalents that exist: `METHOD:COUNTER`/`DECLINECOUNTER` and Outlook's `X-MICROSOFT-*` extensions (`allow_counter`, `importance`, `busy`). See CONFIGURATION.md's "Tracking RSVPs" and "Guest permissions" sections for the full breakdown of what's real vs. not addable, and why.
-
-## Example app (`Example/calendar_app`)
-
-Rails 8.1 app demonstrating the gem. Its Gemfile depends on the **published** `cal-invite` gem (never commit it pointing at `path: "../.."`) — when testing example-app changes that rely on unreleased gem code (like the `Meeting` demo below, which needs the still-unreleased 0.2.0), temporarily uncomment the `path: "../.."` line locally, `bundle install`, test, then revert the Gemfile and re-run `bundle install` against rubygems before committing. `Meeting`/`MeetingAttendee` (with a migration) is a working reference implementation of the `uid`/`sequence` persistence pattern CONFIGURATION.md describes — see `app/models/meeting.rb`, `app/controllers/meetings_controller.rb` (create/reschedule/cancel), and `app/controllers/event_replies_controller.rb` (illustrative inbound `METHOD:REPLY` parsing, not wired to a real inbound-email provider). This demo won't actually run against the currently-published gem until 0.2.0 ships.

data/lib/cal_invite/caching.rb

@@ -1,74 +0,0 @@
-# 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