cal-invite 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a320d848302c940f549394fa7d2d76c2160415efa3eb4ef007e3613c9ef9196
-  data.tar.gz: 25bd69ff530c5b2479c0ac5f23862618089384c53994a10eaec3c8e3b59b8ce3
+  metadata.gz: 859781c1ae62094d375450f6a4ce69578eeae805a9986fca889927cdd49f446c
+  data.tar.gz: aed11a758d0b1a9d4eabf09e56609c9f1bd800b85503a5e171c7c9858f03c6dd
 SHA512:
-  metadata.gz: dd3569a38b9f741d27dfe5964b98223e425539e94bca9e3a6c90b5f1baa1a2d390af7935d39c3fb04ab1272bf9d501ab3759b867d8926bc287f2019ece5021bf
-  data.tar.gz: fc43475e14f1eb253319de3d671288a261fe296b006e4807b388cfbc96707738e36f15ed0a4e1e0698afed32d5a67cd0adf3fcb36bb19fee6c8b001ec72b536c
+  metadata.gz: ee1118ede1a8f029d66d59d22615d95eaf17ffcc9290fe82a3d59e98808d4f1b5de58df375c88ebc1f4d9f62228437632a1724fceccb28b039f8002174e51f94
+  data.tar.gz: 259efb6d6829b774aeb6d2d35e0c1518c00831cd81340ff519b3a7f4b7e726b0fb881f586bcf20fe98a89f4a46e4057e70aafc6dc790f28f213f9afa75f96f43

data/AGENTS.md

@@ -45,7 +45,7 @@ Tests are Minitest-based, files live under `test/cal_invite/`, named `*_test.rb`
 
 ## 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), and `app/controllers/event_replies_controller.rb` (illustrative inbound `METHOD:REPLY` parsing, not wired to a real inbound-email provider).
+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

@@ -0,0 +1,240 @@
+# Caching CalInvite output in your application
+
+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.
+
+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.
+
+## 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
+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))
+}
+```
+
+## Plain Ruby
+
+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.
+
+### A small in-process LRU cache
+
+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.
+
+```ruby
+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
+
+  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
+```
+
+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.
+
+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.
+
+### ActiveSupport cache stores
+
+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
+require "active_support"
+
+STORE = ActiveSupport::Cache::MemoryStore.new(size: 32 * 1024 * 1024, expires_in: 3600)
+
+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
+
+# 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
+
+# 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
+```
+
+`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`.
+
+## Sinatra
+
+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.
+
+```ruby
+require "sinatra/base"
+
+class CalendarApp < Sinatra::Base
+  get "/meetings/:id.ics" do
+    meeting = MEETINGS.fetch(params[:id].to_i) { halt 404 }
+
+    cache_control :public, max_age: 300
+    last_modified meeting.updated_at
+    etag meeting.cache_version # halts with 304 if If-None-Match matches
+
+    content_type "text/calendar", charset: "utf-8"
+    meeting_ics(meeting) # the IcsCache helper from the plain Ruby section
+  end
+end
+```
+
+## Hanami
+
+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.
+
+`response.fresh` sets the `ETag`/`Last-Modified` headers and halts with `304` when the request is still fresh, before the `.ics` is built.
+
+```ruby
+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
+end
+```
+
+## Grape
+
+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
+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
+```
+
+The same API can still serve JSON from other endpoints. The `.ics` extension selects the formatter.

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Cal Invite
 
+## [v0.3.2] - 2026-10-22
+
+No changes to the library code; this release is documentation and CI.
+
+- **API docs layout fixed.** The README's wide banner image ran under the "On This Page" sidebar on the published docs. RDoc now loads `assets/rdoc-overrides.css`, which keeps images inside the content column.
+- **Docs deploy on their own.** The documentation workflow runs on every push to `main` that changes a file the docs render, and can be started by hand from the Actions tab on any branch. Release tags still publish the docs as before.
+- **Faster CI for doc-only changes.** Changes that touch only Markdown files or `assets/` skip the test matrix. Tag pushes always run the full pipeline.
+- **Docs checked on pull requests.** A PR that changes a file the docs render now runs the RDoc build, so a broken build fails before merge. Nothing is deployed from a PR.
+- **Workflow lint and wider test matrix.** `actionlint` runs on the workflows, and the test matrix adds Ruby 3.4.
+- **CI tidy-ups.** Superseded pull request runs are cancelled. Documentation deploys queue instead of cancelling each other. Workflow permissions are narrowed, and the test job has a 20-minute timeout.
+
+## [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
@@ -105,7 +126,7 @@ These changes can break existing callers:
 
 ## [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
@@ -114,7 +135,7 @@ These changes can break existing callers:
 
 ## [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
 

data/CONFIGURATION.md

@@ -99,7 +99,7 @@ event.generate_calendar_url(provider, method: :publish)
 | `provider`| `Symbol` | required   | One of the provider symbols above (a String also works). Anything else raises `ArgumentError` listing the supported providers. `:ics_content` is accepted as a legacy alias of `:ics`. |
 | `method`  | `Symbol` | `:publish` | `:publish`, `:request`, `:cancel`, `:reply`, `:counter`, or `:decline_counter`. Only honored by `:ics`/`:ical` — ignored by URL-based providers. `:request` requires `organizer` to be set on the event; see below. `:cancel` requires reusing the original `uid` — see [Updating and cancelling invites](#updating-and-cancelling-invites). `:reply`/`:counter`/`:decline_counter` omit `RSVP=TRUE` on `ATTENDEE` lines — see [Attendee RSVP status and METHOD:REPLY](#attendee-rsvp-status-and-methodreply) and [Attendee-proposed reschedules (COUNTER)](#attendee-proposed-reschedules-counter). Note: `:decline_counter` renders as `METHOD:DECLINECOUNTER` (one word, per RFC 5545). |
 
-Output is generated fresh on every call. CalInvite doesn't cache anything: building the output takes microseconds, and a cached `.ics` would keep a stale `DTSTAMP`. If you want caching anyway, do it in your app, keyed on whatever identifies the content and changes with it:
+Output is generated fresh on every call. CalInvite doesn't cache anything: building the output takes microseconds, and a cached `.ics` would keep a stale `DTSTAMP`. If you want caching anyway, do it in your app, keyed on whatever identifies the content and changes with it (more examples, including HTTP caching, in [CACHING.md](CACHING.md)):
 
 ```ruby
 Rails.cache.fetch([meeting, meeting.sequence, :ics]) do

data/README.md

@@ -1,280 +1,210 @@
-# 📅 CalInvite
+# CalInvite
 
-A Ruby gem for generating calendar invitations across multiple calendar platforms with webhook support.
+![CalInvite: calendar invitations for Ruby. Google, Outlook, Apple, Yahoo, .ics](assets/social/cal-invite-github.webp)
 
-[![Gem Version](https://badge.fury.io/rb/cal-invite.svg)](https://badge.fury.io/rb/cal-invite)
-![Build Status](https://github.com/DashAPI-ai/cal-invite/actions/workflows/main.yml/badge.svg)
+Generate "add to calendar" links and `.ics` calendar invites from Ruby, for Google Calendar, Outlook, Outlook 365, Yahoo, Apple Calendar, and any client that reads iCalendar files.
 
+[![Gem Version](https://img.shields.io/gem/v/cal-invite)](https://rubygems.org/gems/cal-invite)
+![Build Status](https://github.com/DashAPI-ai/cal-invite/actions/workflows/main.yml/badge.svg)
 ![License](https://img.shields.io/github/license/DashAPI-ai/cal-invite.svg)
 
-## Compatibility
-
-- Ruby >= 3.0.0
-- Rails 6.0, 6.1, 7.0, 7.1, 8.0, 8.1
-
-## Supported Calendar Platforms
+You describe an event once and get a link or `.ics` content for each provider. With `method: :request`, the `.ics` is an RFC 5545 meeting request that Gmail, Outlook and Apple Mail show with Accept/Decline buttons, and later updates or cancellations replace the original invite. Any IANA timezone gets a full `VTIMEZONE` with correctly converted times. Attribute values are escaped, so end-user input can't add properties to an invite.
 
-Direct Integration:
-- Apple iCal (with proper timezone support)
-- Microsoft Outlook
-- Microsoft Outlook 365
-- Google Calendar
-- Yahoo Calendar
-- Standard .ics file generation
+## Contents
 
-Any calendar application that supports the iCalendar (.ics) standard should work, including but not limited to:
-- Proton Calendar
-- FastMail Calendar
-- Thunderbird Calendar
-- Zoho Calendar
-- Microsoft Teams Calendar
-- Zoom Calendar Integration
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Providers](#providers)
+- [More examples](#more-examples)
+- [Serving a downloadable .ics file](#serving-a-downloadable-ics-file)
+- [Sending email invites with RSVP](#sending-email-invites-with-rsvp)
+- [Things to know](#things-to-know)
+- [Upgrading to 0.3.0](#upgrading-to-030)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Sponsor](#sponsor)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+CalInvite is published on [RubyGems](https://rubygems.org/gems/cal-invite). It requires Ruby 3.0 or newer. It works with or without Rails, and supports Rails 6.0 through 8.1.
 
 ```ruby
-gem 'cal-invite'
+# Gemfile
+gem "cal-invite"
 ```
 
-And then execute:
 ```bash
-$ bundle install
+bundle install
 ```
 
-Or install it yourself as:
-```bash
-$ gem install cal-invite
+## Quick start
+
+```ruby
+require "cal_invite"
+
+event = CalInvite::Event.new(
+  title: "Team Meeting",
+  start_time: Time.utc(2026, 11, 2, 15, 0),   # always pass UTC
+  end_time:   Time.utc(2026, 11, 2, 16, 0),
+  timezone: "America/New_York",               # how the time is displayed
+  description: "Weekly sync",
+  location: "Conference Room A",              # physical place
+  url: "https://zoom.us/j/123456789"          # virtual meeting link
+)
+
+event.generate_calendar_url(:google)  # => "https://calendar.google.com/calendar/render?action=TEMPLATE&..."
+event.generate_calendar_url(:ics)     # => "BEGIN:VCALENDAR\r\n..." (.ics file content)
 ```
 
-## Usage
+## Providers
 
-### Basic Event Creation
+| Provider     | Returns | Notes |
+|--------------|---------|-------|
+| `:google`    | URL | Opens Google Calendar's "add event" page. |
+| `:outlook`   | URL | Outlook.com (personal accounts). |
+| `:office365` | URL | Outlook on the web for work/school (Microsoft 365) accounts. |
+| `:yahoo`     | URL | One URL per session for multi-day events, separated by newlines. |
+| `:ics`       | `.ics` content | Standard iCalendar file; works with Apple Calendar, Thunderbird, Proton, Fastmail and others. |
+| `:ical`      | `.ics` content | Same content as `:ics`; kept for Apple Calendar naming. |
 
-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
+Only `:ics` and `:ical` support the `method:` option (`:publish` by default, also `:request`, `:cancel`, `:reply`, `:counter`, `:decline_counter`). Any other provider name raises `ArgumentError`.
 
-For the full list of `Event` attributes, providers, and configuration options, see [CONFIGURATION.md](CONFIGURATION.md).
+## More examples
 
 ```ruby
-# Create an event with physical location
-event = CalInvite::Event.new(
-  title: "Team Meeting",
-  start_time: Time.current.utc,  # Always use UTC times
-  end_time: Time.current.utc + 2.hours,
-  description: "Weekly team sync",
-  location: "Conference Room A",  # Physical location
-  timezone: "America/New_York",  # Display timezone
-  attendees: ["person@example.com"],
-  show_attendees: true,
-  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"],
+# Attendees: email strings, or hashes with a display name and RSVP status
+CalInvite::Event.new(
+  title: "Planning",
+  start_time: Time.utc(2026, 11, 2, 15), end_time: Time.utc(2026, 11, 2, 16),
+  attendees: ["bob@example.com", { email: "ada@example.com", name: "Ada", partstat: :accepted }],
   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"
+CalInvite::Event.new(title: "Company Offsite", start_time: Time.utc(2026, 12, 4), all_day: true)
+
+# Recurring event, with a reminder 15 minutes before
+CalInvite::Event.new(
+  title: "Standup",
+  start_time: Time.utc(2026, 11, 2, 14), end_time: Time.utc(2026, 11, 2, 14, 15),
+  timezone: "Europe/Paris",
+  rrule: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
+  reminders: [15]
 )
 
-# Multi-day event
-event = CalInvite::Event.new(
+# Multi-day event with separate sessions
+CalInvite::Event.new(
   title: "Training Workshop",
   multi_day_sessions: [
-    {
-      start_time: Time.parse("2024-03-01 08:00:00 UTC"),
-      end_time: Time.parse("2024-03-01 17:00:00 UTC")
-    },
-    {
-      start_time: Time.parse("2024-03-02 09:00:00 UTC"),
-      end_time: Time.parse("2024-03-02 13:00:00 UTC")
-    }
+    { start_time: Time.utc(2026, 3, 1, 13), end_time: Time.utc(2026, 3, 1, 22) },
+    { start_time: Time.utc(2026, 3, 2, 14), end_time: Time.utc(2026, 3, 2, 18) }
   ],
-  description: "Advanced Ruby Training",
-  location: "Training Center",
-  url: "https://zoom.us/j/123456789",  # Virtual meeting URL kept separate
   timezone: "America/New_York",
-  notes: "Bring your own laptop"
+  location: "Training Center"
 )
-
-# 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
+For a multi-day event, `:ics`, `:ical` and `:yahoo` produce one entry per session. Google and Outlook can only show one range, so they show the whole span, from the first session's start to the last session's end.
 
-To enable ICS file downloads in your application, you'll need to:
+Every attribute (`organizer`, `geo`, `busy`, `visibility`, `importance`, `calendar_name`, ...) is listed in [CONFIGURATION.md](CONFIGURATION.md#event-attributes).
 
-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:
+## Serving a downloadable .ics file
 
 ```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'
+# app/controllers/events_controller.rb
+def calendar
+  event = CalInvite::Event.new(...)
+  download = CalInvite::Providers::IcsDownload.wrap_for_download(
+    event.generate_calendar_url(:ics), event.title
   )
+
+  send_data download[:content],
+            type: download[:headers]["Content-Type"],
+            filename: "#{CalInvite::Providers::IcsDownload.sanitize_filename(event.title)}.ics",
+            disposition: "attachment"
 end
 ```
 
-You can implement this in any controller and route that makes sense for your application's architecture.
-
-### Sending Email Meeting Invites (RSVP-capable)
-
-By default, a `.ics` attachment opens as a file in most mail clients. To get
-Gmail/Outlook/Apple Mail to render the message as an invite with Accept/Decline
-actions (like Luma or Google Calendar invites do), set an `organizer` on the
-event and pass `method: :request` when generating. Full walkthrough and all
-options in [CONFIGURATION.md](CONFIGURATION.md#email-meeting-invites-rsvp-capable).
+## Sending email invites with RSVP
 
-### ICS File Generation
+A plain `.ics` attachment opens as a file. To have mail clients show it as a meeting invite with Accept/Decline buttons, you need three things: an `organizer`, `method: :request`, and a matching `method=REQUEST` on the attachment's content type.
 
-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"
+  title: "Design Review",
+  start_time: Time.utc(2026, 11, 2, 15), end_time: Time.utc(2026, 11, 2, 16),
+  organizer: { name: "Jane Doe", email: "jane@example.com" },
+  attendees: ["guest@example.com"],
+  show_attendees: true
 )
 
-# Generate ICS content
-content = CalInvite::Providers::Ics.new(event).generate
+# In your ActionMailer method:
+attachments["invite.ics"] = {
+  mime_type: "text/calendar; method=REQUEST",
+  content: event.generate_calendar_url(:ics, method: :request)
+}
 ```
 
-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
+Save `event.uid`. To reschedule or cancel later, rebuild the event with the same `uid` and a higher `sequence`, then send `method: :request` again (for a reschedule) or `method: :cancel`. See [Updating and cancelling invites](CONFIGURATION.md#updating-and-cancelling-invites). The [example Rails app](Example/calendar_app) has a working implementation.
 
-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
+## Things to know
 
-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
+- Pass `start_time` and `end_time` as UTC `Time`s. `timezone` only controls how the time is displayed. It must be `"UTC"` or an IANA name such as `"America/New_York"`, and defaults to `CalInvite.configuration.timezone` (`"UTC"`).
+- Put the physical place in `location` and the video-call link in `url`. Each provider formats them its own way.
+- Invalid input raises `ArgumentError`: a misspelled attribute (`locaton:`), an unknown timezone, an end time before the start time, or an unsupported provider.
+- CalInvite generates links and invites but doesn't receive RSVP replies. It also can't set options that exist only in the Google and Microsoft APIs, such as guest permissions. See [Tracking RSVPs](CONFIGURATION.md#tracking-rsvps-what-the-gem-does-and-doesnt-do).
+- Output is cheap to build, so nothing is cached and it's generated fresh on every call. To cache it in your app, or answer repeat downloads with `304 Not Modified`, see [CACHING.md](CACHING.md).
 
-## Caching
+Global settings:
 
-CalInvite doesn't cache anything. Generated URLs and `.ics` content are cheap to build and always fresh. The old `cache_store`/`cache_prefix`/`cache_expires_in` settings are deprecated no-ops (removed in 0.4.0). See [CONFIGURATION.md](CONFIGURATION.md#generate_calendar_url) for caching at your own layer, and for every other option.
-
-## 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.
+```ruby
+# config/initializers/cal_invite.rb
+CalInvite.configure do |config|
+  config.timezone = "America/New_York"   # default for events that don't set one
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Upgrading to 0.3.0
 
-## Testing
+0.3.0 is stricter. Unknown attributes, invalid timezones and invalid time ranges now raise `ArgumentError`, where 0.2.x silently produced a broken invite. The gem also no longer loads all of `active_support/core_ext`. In plain Ruby, `1.hour` and `Time.current` no longer work unless you require them yourself.
 
-Add test(s) as necessary.
+The `cache_store`/`cache_prefix`/`cache_expires_in` settings and the top-level `::BaseProvider` constant are deprecated. They still work, but print a warning, and they'll be removed in 0.4.0. The full list of changes is in [CHANGELOG.md](CHANGELOG.md).
 
-Run all the tests before submitting: `bundle exec rake test`
+## Documentation
 
-There are three ways to exercise the gem while working on a change:
+- [CONFIGURATION.md](CONFIGURATION.md): every attribute, provider and option, plus guides for email invites, updates and cancellations, RSVP status, COUNTER proposals, and timezones.
+- [API reference](https://dashapi-ai.github.io/cal-invite/): generated from the YARD comments (`bundle exec rake rdoc` builds it locally).
+- [CACHING.md](CACHING.md): caching output in plain Ruby, Rails, Sinatra, Hanami and Grape, including HTTP caching for `.ics` feeds.
+- [CHANGELOG.md](CHANGELOG.md): release history.
 
-**1. Unit tests** (Minitest, under `test/cal_invite/`) — use these to lock a change in:
+## Development
 
 ```bash
-bundle exec rake test                                      # full suite (+ SimpleCov report in coverage/)
-bundle exec rake test TEST=test/cal_invite/event_test.rb   # a single file
+bin/setup                                                  # install dependencies
+bundle exec rake test                                      # full suite (+ coverage report in coverage/)
+bundle exec rake test TEST=test/cal_invite/event_test.rb   # one file
+bin/console                                                # IRB with the local lib/ loaded
 ```
 
-**2. Interactive console** — `bin/console` opens IRB with your local `lib/` loaded, handy for eyeballing generated URLs and `.ics` output:
+To try unreleased changes in the [example Rails app](Example/calendar_app), switch its Gemfile to the commented-out `gem "cal-invite", path: "../../"` line and run `bundle install`. Switch it back before committing.
 
-```ruby
-event = CalInvite::Event.new(
-  title: "Demo",
-  start_time: Time.utc(2026, 11, 1, 15),
-  end_time: Time.utc(2026, 11, 1, 16),
-  timezone: "America/New_York",
-  organizer: { email: "me@example.com", name: "Me" },
-  attendees: ["guest@example.com"],
-  show_attendees: true
-)
-
-puts event.generate_calendar_url(:ics, method: :request)  # raw .ics content
-event.generate_calendar_url(:google)                      # provider URL
-```
-
-**3. Example Rails app** (`Example/calendar_app`) — for end-to-end checks in a real browser or mail client (downloading the `.ics`, RSVP buttons, etc.). Its Gemfile points at the published gem; to test unreleased changes, temporarily swap `gem "cal-invite"` for the commented-out `gem "cal-invite", path: "../../"` line and run `bundle install`. Revert the Gemfile and re-run `bundle install` before committing.
+To release, bump `lib/cal_invite/version.rb`, update `CHANGELOG.md`, merge to `main`, and push a `vX.Y.Z` tag. CI then runs the tests, publishes the gem to RubyGems and deploys the docs.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/DashAPI-ai/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/DashAPI-ai/cal-invite/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/DashAPI-ai/cal-invite). Please add tests for your change and run `bundle exec rake test` before opening a PR. To report a security issue, see [SECURITY.md](SECURITY.md). Everyone taking part in the project is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
 
-## Documentation
+## Sponsor
 
-The documentation is spread across the README, [CONFIGURATION.md](CONFIGURATION.md), and the doc folder.
+CalInvite is sponsored by [DashAPI](https://dashapi.ai).
 
-The documentation can be generated using `bundle exec rake rdoc`
+<a href="https://dashapi.ai">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/dashapi-logo-dark.svg">
+    <img src="assets/sponsors/dashapi-logo-light.svg" alt="DashAPI" width="140">
+  </picture>
+</a>
 
 ## 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/DashAPI-ai/cal-invite/blob/master/CODE_OF_CONDUCT.md).
+Released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -23,9 +23,11 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.options << '--markup' << 'markdown'
   rdoc.options << '--all'
   rdoc.options << '--exclude' << '^(test|spec|features)/'
+  rdoc.options << '--template-stylesheets' << 'assets/rdoc-overrides.css'
 
   # Include files to document
-  rdoc.rdoc_files.include('README.md', 'LICENSE.txt', 'lib/**/*.rb')
+  rdoc.rdoc_files.include('README.md', 'CONFIGURATION.md', 'CACHING.md', 'CHANGELOG.md',
+                          'SECURITY.md', 'CODE_OF_CONDUCT.md', 'LICENSE.txt', 'lib/**/*.rb')
   rdoc.rdoc_files.exclude('lib/cal_invite/version.rb')
 end
 

data/lib/cal_invite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CalInvite
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cal-invite
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Stephane Paquet
@@ -105,6 +105,7 @@ files:
 - ".rdoc_options"
 - ".rubocop.yml"
 - AGENTS.md
+- CACHING.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONFIGURATION.md
@@ -112,7 +113,6 @@ files:
 - README.md
 - Rakefile
 - SECURITY.md
-- assets/social/cal-invite-github.png
 - gemfiles/Gemfile.rails6
 - gemfiles/Gemfile.rails7
 - gemfiles/Gemfile.rails8
@@ -130,7 +130,6 @@ files:
 - lib/cal_invite/providers/outlook.rb
 - lib/cal_invite/providers/yahoo.rb
 - lib/cal_invite/version.rb
-- lib/tasks/rdoc.rake
 - sig/cal/invite.rbs
 homepage: https://github.com/DashAPI-ai/cal-invite
 licenses:
@@ -138,7 +137,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/DashAPI-ai/cal-invite
   source_code_uri: https://github.com/DashAPI-ai/cal-invite
-  changelog_uri: https://github.com/DashAPI-ai/cal-invite/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/DashAPI-ai/cal-invite/blob/main/CHANGELOG.md
+  documentation_uri: https://dashapi-ai.github.io/cal-invite/
 post_install_message:
 rdoc_options:
 - "--title"

data/lib/tasks/rdoc.rake

@@ -1,13 +0,0 @@
-# lib/tasks/rdoc.rake
-require 'rdoc/task'
-
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title    = 'CalInvite Documentation'
-  rdoc.main     = 'README.md'
-  rdoc.options << '--line-numbers'
-  rdoc.options << '--charset' << 'UTF-8'
-  rdoc.options << '--markup' << 'markdown'
-  rdoc.rdoc_files.include('README.md', 'LICENSE', 'lib/**/*.rb')
-  rdoc.rdoc_files.exclude('lib/cal_invite/version.rb')
-end