cal-invite 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acfc7fb8536f80559ceccfb16ab9d19a79d3b29ee7d5dc082859d5676e600951
-  data.tar.gz: 244cac5a83e5874bdc037bb13d8550fae3691acddac5403a5fe98714d726f9d6
+  metadata.gz: af172acc91308a8bcfdf60019e87a5e01fb8f23baa9287b7d1d2c72b282f58be
+  data.tar.gz: dd38efbb8511d896e5d6f9c427f060ea8b1a04e7c6b8561b790ff14cdf63effe
 SHA512:
-  metadata.gz: '0318e32174bf7946585e98498661c76c2470b05c06a17fa08a469c04ec006485613af7b70bf874c195405eb079e3d993d3ec43a54fe4e2ee457773245c782b65'
-  data.tar.gz: e328f2f90f38e8104f2180ce79b14cdf12868817d936e28dc52e561aef9c3f58c9f0deb06de35c3173512c8fa78f083229a49f218e6ab1130402c477fcf2da06
+  metadata.gz: 82b6aeffacee1b90bce91595a28d864f879d09be68a9503abf3290529ca738080cf90fd4cb7c5dec3d641789c6ea4c36d7193aa8b9d76a7605ed510f72c0a59f
+  data.tar.gz: 6663085d67c0376b52556b6d09a5a575f8bb8005f6276719e27d1acf3233c0087a656b56df4bf29a835230db602048c3759cf31f3fc9912c0c2509f89e58bb31

data/AGENTS.md

@@ -21,26 +21,31 @@ Tests are Minitest-based, files live under `test/cal_invite/`, named `*_test.rb`
 
 ## 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` module** (`lib/cal_invite.rb`) — top-level entry point. Holds a singleton `CalInvite.configuration` (a `Configuration` instance) set via `CalInvite.configure { |c| ... }`.
 
-- **`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::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, resolves `CalInvite::Providers::<CapitalizedProvider>`, instantiates it with `self`, and calls `#generate`. The gem deliberately caches **nothing** (output caching and the cache helpers were removed in 0.3.0; see CONFIGURATION.md's `generate_calendar_url` section for why) — don't reintroduce it. 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_encode`, `format_description`, `format_location`, `format_url`, `format_description_with_url`, `add_optional_params`, `attendees_list`. Each concrete provider (`Google`, `Outlook`, `Office365`, `Yahoo`, `Ical`, `Ics`) builds a provider-specific URL or content string from the `Event` using these helpers.
+- **`CalInvite::Providers::BaseProvider`** (`lib/cal_invite/providers/base_provider.rb`) — abstract base class. A deprecated top-level `::BaseProvider` alias (defined in `providers.rb` via `Object.deprecate_constant`, skipped if the host app already has a `BaseProvider`) remains until 0.4.0 — don't reference it from gem code. 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` is aliased to `IcsContent` via autoload.
+- **`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). `Ics` is the **only** `.ics` generator: `Ical` and `IcsContent` are empty subclasses kept for their public names, so make content changes in `ics.rb` only. `IcsDownload` (HTTP header/filename helpers) 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`. `Event#validate!` rejects any other `timezone` (`IcalTimezone.valid?`), so providers can rely on it being UTC or a real IANA zone.
 
-- **`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`.
+- **`Configuration`** (`lib/cal_invite/configuration.rb`) — holds `webhook_secret` and `timezone` (default `'UTC'`; the default `Event#timezone` when `timezone:` isn't passed). `cache_store`/`cache_prefix`/`cache_expires_in` are deprecated no-ops kept until 0.4.0: their setters warn (`uplevel: 2`, so the warning points at the caller's initializer) but still store the value so app code reading them keeps working.
 
 ## Conventions
 
 - Always pass times to `Event.new` in UTC; use the `timezone` attribute only to control display/formatting in the generated invite.
+- **Treat every `Event` attribute as untrusted input** (host apps pass end-user strings: titles, display names, ...). In `.ics` output: TEXT values go through `Ics#escape_text`; parameter values (e.g. `CN=`) through `BaseProvider#quoted_param` (RFC 6868); enumerated/numeric values are whitelisted or coerced (`class_line`, `geo_line`, `sequence_line`); and `Ics#ensure_single_line_values!` raises on any CR/LF left in a content line — never bypass it or interpolate a raw attribute into a property/parameter. URL providers must pass every value through `url_encode`. Add a case to `test/cal_invite/ics_security_test.rb` for any new property.
 - `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`.
+- 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`. `Event#start_time`/`#end_time` are readers that fall back to the earliest session start / latest session end when not set explicitly (computed on read, so they follow `update_attributes`), which is what single-range URL providers use.
 - 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, 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, plus `show` serving a cached `.ics` with `stale?` + `Rails.cache` per CACHING.md), and `app/controllers/event_replies_controller.rb` (illustrative inbound `METHOD:REPLY` parsing, not wired to a real inbound-email provider).
 
 ## PRs & commits
 

data/CACHING.md

@@ -1,148 +1,240 @@
-## Caching
+# Caching CalInvite output in your application
 
-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.
+CalInvite doesn't cache anything (see the [0.3.0 changelog](CHANGELOG.md)). Building a URL or `.ics` file is in-memory string work that takes microseconds, and the gem can't know when your data changes. Your application does, so caching belongs there.
 
-### Basic Configuration
+This guide shows a few ways to do it in plain Ruby, Rails, Sinatra, Hanami and Grape. It isn't exhaustive. Every example was run against the framework version named in its section.
 
-Configure caching in your Rails application's initializer:
+## Contents
+
+- [Do you need a cache?](#do-you-need-a-cache)
+- [Four rules for correct caching](#four-rules-for-correct-caching)
+- [The example model](#the-example-model)
+- [Plain Ruby](#plain-ruby)
+- [Rails 8.1](#rails-81)
+- [Sinatra](#sinatra)
+- [Hanami](#hanami)
+- [Grape](#grape)
+
+## Do you need a cache?
+
+Usually not for the output itself. Caching it pays off in two cases:
+
+- **Repeated downloads of the same `.ics`.** Calendar apps that subscribe to a feed poll it every few minutes to hours. HTTP caching (`ETag`/`Last-Modified` and a `304 Not Modified` reply) saves the bandwidth and lets the client skip re-importing an unchanged file. This is the most useful kind of caching for calendar files.
+- **Expensive work before the gem runs.** If building the `Event` means loading a meeting, its attendees and its venue from the database, cache the result to skip those queries. CalInvite's own share of the time is negligible.
+
+Don't cache invites you send by email (`method: :request`, `:cancel`, ...). Each send should be generated when it's sent; see rule 3.
+
+## Four rules for correct caching
+
+1. **Key on the data's version, not on the output.** The key needs the record's identity, something that changes whenever the record changes (`updated_at`, a version column, the invite `sequence`), and every input that changes the output: provider, `method:`, and anything that varies per viewer, such as whether attendees are shown.
+2. **Persist the event's `uid`.** Without an explicit `uid:`, each `Event` gets a random one, so two builds of the same meeting produce different `.ics` content. Store the `uid` on your record and pass it in.
+3. **Never build an `ETag` by hashing the `.ics` content.** Every generation writes the current time into `DTSTAMP`, so the hash changes on every request and the client never gets a `304`. Derive the `ETag` from the record's version. A cached `.ics` also keeps the `DTSTAMP` from when it was cached. That's harmless for downloads and feeds, but it's another reason to generate emailed invites fresh.
+4. **Include the configured timezone if it can change at runtime.** `CalInvite.configuration.timezone` is the default `timezone` for events. Most apps set it once at boot, so it doesn't need to be in the key.
+
+## The example model
+
+The plain Ruby, Sinatra, Hanami and Grape examples use this stand-in for a database record. In Rails it's an Active Record model with the same `to_cal_invite_event` method.
 
 ```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
+require "cal_invite"
+
+Meeting = Struct.new(:id, :title, :starts_at, :ends_at, :uid, :sequence, :updated_at, keyword_init: true) do
+  def to_cal_invite_event
+    CalInvite::Event.new(title: title, start_time: starts_at, end_time: ends_at, uid: uid, sequence: sequence)
+  end
+
+  # Changes whenever the meeting changes (rule 1).
+  def cache_version
+    "#{id}-#{updated_at.to_i}-#{sequence}"
+  end
 end
+
+MEETINGS = {
+  1 => Meeting.new(id: 1, title: "Design review", uid: "meeting-1@example.com", sequence: 0,
+                   starts_at: Time.utc(2026, 11, 2, 15), ends_at: Time.utc(2026, 11, 2, 16),
+                   updated_at: Time.utc(2026, 10, 20, 9))
+}
 ```
 
-### Available Cache Stores
+## Plain Ruby
 
-CalInvite supports the following cache stores:
+Written for Ruby 3.4 and run on Ruby 4.0. Ruby 4.0 doesn't add anything that changes these patterns; see [Ruby 4.0](#ruby-40) below.
 
-1. Memory Store (default)
-```ruby
-config.cache_store = :memory_store
-```
+### A small in-process LRU cache
 
-2. Null Store (for disabling caching)
-```ruby
-config.cache_store = :null_store
-```
+A `Hash` keeps insertion order, so deleting and re-inserting a key on each hit makes the first key the least recently used one. A `Mutex` keeps it safe under threaded servers like Puma.
 
-3. Custom Cache Store
 ```ruby
-# Any object that implements read/write/delete methods
-config.cache_store = MyCacheStore.new
-```
+class IcsCache
+  def initialize(max_entries: 1_000)
+    @max_entries = max_entries
+    @entries = Hash.new(capacity: max_entries) # Ruby 3.4+: allocate the table once
+    @lock = Mutex.new
+  end
 
-4. Rails Cache
-```ruby
-# Use your Rails application's configured cache
-config.cache_store = Rails.cache
+  def fetch(key)
+    @lock.synchronize do
+      return @entries[key] = @entries.delete(key) if @entries.key?(key) # move to most recent
+    end
+
+    value = yield # generate outside the lock
+    @lock.synchronize do
+      @entries[key] = value
+      @entries.shift while @entries.size > @max_entries # evict least recently used
+    end
+    value
+  end
+end
+
+ICS_CACHE = IcsCache.new
+
+def meeting_ics(meeting)
+  ICS_CACHE.fetch([meeting.cache_version, :ics, :publish]) do
+    meeting.to_cal_invite_event.generate_calendar_url(:ics)
+  end
+end
 ```
 
-### Cache Configuration Options
+When a meeting changes, its `cache_version` changes, so the next call misses and the old entry ages out. Nothing has to be deleted by hand.
 
-- `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')
+Each server process has its own copy of this cache. That's fine for a single process or a small app. If several processes or machines should share one cache, use a shared store such as Redis.
 
-### Custom Cache Adapters
+### ActiveSupport cache stores
 
-You can implement custom cache adapters by creating a class that responds to the following methods:
+CalInvite already depends on `activesupport`, so its cache stores are available without Rails. `MemoryStore` adds a size limit and expiry to the pattern above, and the same `fetch` call works with `RedisCacheStore` (add the `redis` gem) or `FileStore` when processes need to share a cache.
 
 ```ruby
-class CustomCacheStore
-  def read(key)
-    # Implementation for retrieving cached value
-  end
+require "active_support"
 
-  def write(key, value, options = {})
-    # Implementation for storing value in cache
-    # options may include :expires_in
-  end
+STORE = ActiveSupport::Cache::MemoryStore.new(size: 32 * 1024 * 1024, expires_in: 3600)
 
-  def delete(key)
-    # Implementation for removing cached value
+def meeting_ics_from_store(meeting)
+  STORE.fetch(["meeting-ics", meeting.cache_version]) do
+    meeting.to_cal_invite_event.generate_calendar_url(:ics)
   end
+end
+```
+
+On ActiveSupport 7.x and earlier, loading the cache stores also loads some of ActiveSupport's core extensions. ActiveSupport 8 doesn't.
+
+### Ruby 4.0
+
+Nothing in Ruby 4.0 improves this kind of caching. The headline changes are the `Ractor::Port` API, `Set` becoming a core class, and the experimental `Ruby::Box` isolation. The `Mutex`-guarded `Hash` above can't be shared between Ractors, but web servers and frameworks run requests on threads or processes rather than Ractors, so this doesn't affect normal applications. Both examples above run unchanged on 4.0.
+
+## Rails 8.1
+
+Tested with Rails 8.1. `Rails.cache` is the cache store (Solid Cache by default since Rails 8.0), and `stale?` handles conditional GET: it sets `ETag` and `Last-Modified` from the record and answers `304 Not Modified` when the client's copy is current. Rails already knows the `text/calendar` MIME type as `:ics`.
+
+```ruby
+# config/routes.rb
+resources :meetings, only: :show
 
-  def clear
-    # Implementation for clearing all cached values
+# app/models/meeting.rb
+class Meeting < ApplicationRecord
+  def to_cal_invite_event
+    CalInvite::Event.new(title: title, start_time: starts_at, end_time: ends_at, uid: uid, sequence: sequence)
   end
 end
 
-# Configure CalInvite to use your custom cache store
-CalInvite.configure do |config|
-  config.cache_store = CustomCacheStore.new
+# app/controllers/meetings_controller.rb
+class MeetingsController < ApplicationController
+  def show
+    meeting = Meeting.find(params[:id])
+
+    respond_to do |format|
+      format.ics do
+        # ETag from meeting.cache_key_with_version, Last-Modified from updated_at (rule 3)
+        if stale?(meeting, public: true)
+          ics = Rails.cache.fetch([meeting, :ics, :publish]) do
+            meeting.to_cal_invite_event.generate_calendar_url(:ics)
+          end
+          send_data ics, type: :ics, disposition: "inline", filename: "meeting-#{meeting.id}.ics"
+        end
+      end
+    end
+  end
 end
 ```
 
-### Automatic Cache Invalidation
+`GET /meetings/1.ics` returns the file, and a repeat request with the `ETag` it got back returns `304`. Passing `meeting` in the cache key uses its `cache_key_with_version`, which changes with `updated_at`, so updating the record (including bumping `sequence`) also refreshes the cached copy. If `sequence` lives somewhere that doesn't touch `updated_at`, add it to both the key and `stale?(etag: ...)`.
+
+The [example app](Example/calendar_app) has a complete version in `MeetingsController#show`, with tests. Its meetings list attendees, so it keeps `Cache-Control` private (no `public: true`), uses `belongs_to :meeting, touch: true` so an attendee's RSVP change expires the cache, and bumps `sequence` with `increment!(:sequence, touch: true)`, because `increment!` alone doesn't update `updated_at`.
 
-The cache is automatically invalidated in the following scenarios:
+## Sinatra
 
-1. When event attributes are updated via `update_attributes`
-2. When a new calendar URL is generated
-3. When the configuration changes
+Tested with Sinatra 4.2. The `etag` and `last_modified` helpers stop the route with a `304` when the client's copy is current, so the `.ics` is only generated, or read from the cache, for clients that need it.
 
-### Best Practices
+```ruby
+require "sinatra/base"
+
+class CalendarApp < Sinatra::Base
+  get "/meetings/:id.ics" do
+    meeting = MEETINGS.fetch(params[:id].to_i) { halt 404 }
 
-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
+    cache_control :public, max_age: 300
+    last_modified meeting.updated_at
+    etag meeting.cache_version # halts with 304 if If-None-Match matches
 
-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
+    content_type "text/calendar", charset: "utf-8"
+    meeting_ics(meeting) # the IcsCache helper from the plain Ruby section
+  end
+end
+```
 
-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)
+## Hanami
 
-### Example Rails Integration
+Tested with hanami-action 3.0, the action library in Hanami 2.3 and later. Register the `ics` format once in `config/app.rb` with `config.actions.formats.register(:ics, "text/calendar")`. Hanami 2.2 and earlier used `formats.add`, which was removed in hanami-action 3.0.
 
-Here's a complete example of setting up caching in a Rails application:
+`response.fresh` sets the `ETag`/`Last-Modified` headers and halts with `304` when the request is still fresh, before the `.ics` is built.
 
 ```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
+module Calendar
+  module Actions
+    module Meetings
+      class Show < Calendar::Action
+        def handle(request, response)
+          meeting = MEETINGS.fetch(request.params[:id].to_i) { halt 404 }
+
+          response.cache_control :public, max_age: 300
+          response.fresh etag: meeting.cache_version, last_modified: meeting.updated_at
+
+          response.format = :ics
+          response.body = meeting_ics(meeting)
+        end
+      end
+    end
   end
-
-  config.cache_prefix = "cal_invite:#{Rails.env}"
-  config.timezone = 'UTC'
 end
 ```
 
-### Testing with Caching
+## Grape
 
-When writing tests that involve caching:
+Tested with Grape 4.0. Grape has no conditional-GET helper, so the endpoint compares `If-None-Match` itself. Registering an `ics` content type and a pass-through formatter makes `GET /meetings/1.ics` return the `.ics` string as-is, without JSON-encoding it.
 
 ```ruby
-# In your test setup
-CalInvite.configure do |config|
-  config.cache_store = :memory_store
-  config.cache_expires_in = 3600 # 1 hour in seconds
+require "grape"
+
+class CalendarAPI < Grape::API
+  content_type :ics, "text/calendar"
+  formatter :ics, ->(object, _env) { object }
+
+  resource :meetings do
+    get ":id" do
+      meeting = MEETINGS.fetch(params[:id].to_i) { error!("Not found", 404) }
+      etag = %("#{meeting.cache_version}")
+
+      header "ETag", etag
+      header "Cache-Control", "public, max-age=300"
+      if env["HTTP_IF_NONE_MATCH"] == etag
+        status 304
+        return ""
+      end
+
+      content_type "text/calendar; charset=utf-8"
+      meeting_ics(meeting)
+    end
+  end
 end
+```
 
-# Clear cache between tests
-def setup
-  CalInvite.configuration.cache_store.clear
-end
-```
+The same API can still serve JSON from other endpoints. The `.ics` extension selects the formatter.

data/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Cal Invite
 
+## [v0.3.1] - 2026-10-22
+
+No changes to the library code; this release is packaging and documentation.
+
+- **Smaller gem.** The package no longer includes `assets/` (README images) or the unused `lib/tasks/rdoc.rake`: 52 KB instead of 973 KB.
+- **API reference fixed.** The published docs at https://dashapi-ai.github.io/cal-invite/ were missing `lib/cal_invite.rb` and every provider class (`Google`, `Outlook`, `Office365`, `Yahoo`, `Ics`, `Ical`, `IcsContent`, `IcsDownload`, `BaseProvider`), because the docs workflow's `lib/**/*.rb` glob only matched one directory level. The workflow now runs `rake rdoc` and also publishes the README, CONFIGURATION.md, CACHING.md and CHANGELOG.md.
+- **New CACHING.md** on caching CalInvite output in your app (plain Ruby, Rails 8.1, Sinatra, Hanami, Grape), including HTTP caching for `.ics` feeds. The example app gains a cached `.ics` download (`MeetingsController#show`).
+- **README rewritten** for 0.3.0, with accurate examples that run in plain Ruby.
+- **Gem metadata:** the RubyGems changelog link pointed at a non-existent `master` branch; it now points at `main`, and a documentation link was added.
+
+## [v0.3.0] - 2026-10-22
+
+### Upgrading from 0.2.x
+
+These changes can break existing callers:
+
+- **Unknown `Event` attributes raise.** `Event.new` and `Event#update_attributes` raise `ArgumentError` (`Unknown attribute(s): locaton`) for keys that aren't `Event` attributes, instead of silently ignoring them. If you pass a whole params hash, slice it first. A rejected `update_attributes` leaves the event unchanged. (#10)
+- **`timezone` is validated.** It must be `'UTC'` or an IANA identifier known to tzinfo (e.g. `'America/New_York'`); anything else, including raw offsets like `'+01:00'`, raises `ArgumentError`. Such values previously produced invalid `.ics` (a `TZID=` with no `VTIMEZONE`, times shifted by the offset) and could inject parameters. (#7)
+- **Time order is validated.** `ArgumentError` when `end_time` isn't after `start_time` (all-day events may end on the same date), or a `multi_day_sessions` entry is missing a time or ends before it starts. (#9)
+- **Provider names are validated.** `generate_calendar_url` raises `ArgumentError` listing the supported providers for anything outside `CalInvite::Providers::SUPPORTED_PROVIDERS` (`:ics_content` still works as an alias of `:ics`). Previously e.g. `:string` resolved Ruby's `String` and failed confusingly. (#11)
+- **`config.timezone` is now honored** as the default `Event#timezone` when `timezone:` isn't passed, as documented. If you set it to something other than `'UTC'`, your events now render in that zone. An explicit `timezone:` still wins. (#22)
+- **No more blanket `active_support/core_ext`.** Requiring `cal_invite` no longer monkey-patches core classes (`Integer#hours`, `Object#blank?`, `String#squish`, ...) in non-Rails apps. Plain-Ruby code that used those only because `cal_invite` loaded them must `require "active_support/core_ext"` (or the specific file). Rails apps are unaffected. This also lets the gem load with ActiveSupport 6.0 on Ruby 4.0. (#15)
+
+### Removed
+
+- **Output caching.** `generate_calendar_url` builds its output fresh on every call and never touches a cache store; `update_attributes` no longer wipes every event's cache entries. The cache ignored `cache_prefix`, almost never hit, froze `.ics` `DTSTAMP`, and cost more than regenerating. Output is unchanged. To cache anyway, do it in your app; CONFIGURATION.md has an example. (#14)
+- **Cache helpers.** `CalInvite.fetch_from_cache`, `write_to_cache`, `read_from_cache`, `clear_cache!`, `clear_event_cache!`, `clear_provider_cache!` and `CalInvite::Caching` are gone. They had never worked (every call raised `NoMethodError`). `CACHING.md` is gone too. (#32)
+
+### Deprecated (removed in 0.4.0)
+
+- **`config.cache_store=`, `cache_prefix=`, `cache_expires_in=`** have no effect. They print `warning: [cal_invite] Configuration#cache_store= is deprecated and has no effect ...` pointing at your initializer line, but still store the value, so code that reads them keeps working. Delete them from your initializer. (#32)
+- **`::BaseProvider`.** The provider base class is now `CalInvite::Providers::BaseProvider`, so the gem no longer owns a top-level constant that can collide with your app's. `::BaseProvider` remains as an alias (not defined at all if your app has its own `BaseProvider`). Ruby prints `constant ::BaseProvider is deprecated` when deprecation warnings are enabled (e.g. `RUBYOPT=-W:deprecated`). (#13)
+
+### Security
+
+- **Fix content-line/parameter injection in `.ics` output** (`:ics`, `:ical`, `IcsContent`). A CR or LF in event attributes (title, description, attendee/organizer names and emails, `uid`, `rrule`, `visibility`, `geo`, ...), or a `"` in a display name, could add arbitrary properties to a generated invite (e.g. extra attendees, a different `METHOD:`). URL providers were not affected. (#5)
+  - TEXT values are escaped per RFC 5545 (backslashes were previously left unescaped and lone `\r` passed through).
+  - `CN=` display names are quoted and escaped per RFC 6868.
+  - `URL:` is no longer TEXT-escaped (it's a URI; commas and semicolons in links were being corrupted).
+  - Values that can't be escaped raise `ArgumentError` if they contain a line break. `visibility` must be `:public`/`:private`/`:confidential`, `geo` numeric, and `sequence` an integer.
+- `SECURITY.md`: real policy (supported versions, private reporting via GitHub Security Advisories).
+
+### Added
+
+- `organizer:` accepts a plain email string (`organizer: "jane@example.com"`), like `attendees`; a string previously crashed `.ics` generation with `TypeError`. String-keyed hashes are read too. (#12)
+- Multi-day events no longer need top-level `start_time`/`end_time`: they default to the earliest session start and latest session end, so the README's multi-day example works. `:google`/`:outlook`/`:office365` show the overall span; `:ics`/`:ical`/`:yahoo` still emit one entry per session. Explicit times win. (#24)
+
+### Fixed
+
+- `.ics` content lines longer than 75 octets are folded (RFC 5545 §3.1), never splitting a multi-byte UTF-8 character. Long lines could be mangled or rejected by Outlook and mail gateways. (#6)
+- `'UTC'` events emit `Z`-suffixed `DTSTART`/`DTEND` instead of `TZID=UTC` with no `VTIMEZONE`. (#7)
+- `:ical` and `IcsContent` now produce exactly the same content as `:ics`. `IcsContent` previously emitted UTC-only times with no `VTIMEZONE`, ignored `notes`, and didn't support all-day events. `:ics` all-day events without times default to today, as `:ical` did. (#4)
+- Non-UTC timezones under tzinfo 1.x (Rails/ActiveSupport 6.0): `:ics`/`:ical` raised `NoMethodError` (`to_local`) and silently omitted `VTIMEZONE`. (#17)
+- `Event.new` no longer mutates the attributes hash passed in (it used to delete several keys from it, so reusing the hash dropped them). (#8)
+
+### Docs
+
+- README "Testing" section covers `rake test`, `bin/console`, and the Example app's local-path Gemfile workflow. `CLAUDE.md` merged into `AGENTS.md`.
+
 ## [v0.2.1] - 2026-08-10
 
 - `:google` provider: honor `Event#attendees`/`show_attendees` (`add=`), `Event#timezone` (`ctz=`), `Event#rrule` (`recur=`), and `Event#busy` (`crm=BUSY`/`AVAILABLE`) in the generated Google Calendar URL — these were already modeled on `Event` for the ics providers but never wired into `:google`.
@@ -56,7 +115,7 @@
 
 ## [v0.1.2] - 2024-12-17
 
-⚠️ This version should not be used
+**Warning:** This version should not be used
 
 - Add support to Microsoft office 365 calendar invite URL
 - Update the README
@@ -65,7 +124,7 @@
 
 ## [v0.1.1] - 2024-12-17
 
-⚠️ This version should not be used
+**Warning:** This version should not be used
 
 Fixing a bug in the gemspec file