cal-invite 0.2.1 → 0.3.1

data/CONFIGURATION.md

@@ -2,8 +2,6 @@
 
 Complete reference for every configurable option in CalInvite: `Event` attributes, providers, the `generate_calendar_url` call, ICS/email-invite delivery, and global `CalInvite.configure` settings.
 
-For caching-specific detail, see [CACHING.md](CACHING.md).
-
 ## Table of Contents
 
 - [Event attributes](#event-attributes)
@@ -22,23 +20,23 @@ For caching-specific detail, see [CACHING.md](CACHING.md).
 
 ## Event attributes
 
-All attributes are set via `CalInvite::Event.new(attributes)` or `event.update_attributes(attributes)`.
+All attributes are set via `CalInvite::Event.new(attributes)` or `event.update_attributes(attributes)` (symbol or string keys). Any key not listed below raises `ArgumentError` (`Unknown attribute(s): ...`); `update_attributes` checks all keys before changing anything.
 
 | Attribute             | Type            | Required                              | Default | Notes |
 |------------------------|-----------------|----------------------------------------|---------|-------|
 | `title`                | `String`        | yes                                    | —       | Non-blank. |
 | `start_time`           | `Time`          | yes, unless `all_day` or using `multi_day_sessions` | — | Always pass UTC. |
-| `end_time`             | `Time`          | yes, unless `all_day` or using `multi_day_sessions` | — | Always pass UTC. |
+| `end_time`             | `Time`          | yes, unless `all_day` or using `multi_day_sessions` | — | Always pass UTC. Must be after `start_time` (`ArgumentError` otherwise); all-day events may end on the same date they start. |
 | `description`          | `String`        | no                                     | `nil`   | Plain text; combined with `notes` in provider output. |
 | `location`             | `String`        | no                                     | `nil`   | Physical location only. Kept separate from `url` so each provider formats it correctly. |
 | `url`                  | `String`        | no                                     | `nil`   | Virtual meeting link (Zoom, Meet, Teams, etc). Kept separate from `location`. |
 | `attendees`            | `Array<String, Hash>` | no                               | `nil`   | Email strings, or `{ email:, name:, partstat:, rsvp: }` hashes for a display name (`CN=`), a specific RSVP status, and/or an explicit `RSVP=` override. Only emitted if `show_attendees` is `true`. `partstat` is one of `:accepted`, `:declined`, `:tentative`, `:needs_action` (default), `:delegated`. `rsvp:` defaults to `true` for `:request`/`:cancel`/`:publish` and `false` for `:reply`/`:counter`/`:decline_counter`; set it explicitly to override (e.g. `rsvp: false` on an already-`:accepted` attendee in a registration-confirmation invite — see [Replicating a ticketing-platform confirmation email](#replicating-a-ticketing-platform-confirmation-email)). |
 | `show_attendees`       | `Boolean`       | no                                     | `false` | Gate for including `attendees` in generated output. |
-| `organizer`             | `Hash`          | no, but required for `method: :request` | `nil`   | `{ name: "Jane Doe", email: "jane@example.com" }`. `name` is optional. See [Email meeting invites](#email-meeting-invites-rsvp-capable). |
-| `timezone`             | `String`        | no                                     | `'UTC'` | Controls display/formatting only — does not affect how `start_time`/`end_time` are interpreted. Any IANA identifier (e.g. `'America/New_York'`) produces a correctly converted `DTSTART;TZID=...` plus a full `VTIMEZONE` block; see [Timezones and VTIMEZONE](#timezones-and-vtimezone). |
+| `organizer`             | `String`/`Hash` | no, but required for `method: :request` | `nil`   | `"jane@example.com"` or `{ name: "Jane Doe", email: "jane@example.com" }`. `name` is optional. See [Email meeting invites](#email-meeting-invites-rsvp-capable). |
+| `timezone`             | `String`        | no                                     | `CalInvite.configuration.timezone` (`'UTC'`) | Controls display/formatting only — does not affect how `start_time`/`end_time` are interpreted. Must be `'UTC'` or an IANA identifier (e.g. `'America/New_York'`), which produces a correctly converted `DTSTART;TZID=...` plus a full `VTIMEZONE` block; anything else raises `ArgumentError`. See [Timezones and VTIMEZONE](#timezones-and-vtimezone). |
 | `notes`                | `String`        | no                                     | `nil`   | Appended to the description. |
 | `all_day`              | `Boolean`       | no                                     | `false` | When `true`, `start_time`/`end_time` validation is skipped. |
-| `multi_day_sessions`   | `Array<Hash>`   | no                                     | `[]`    | `[{ start_time:, end_time: }, ...]`. Used instead of `start_time`/`end_time` for multi-session events. |
+| `multi_day_sessions`   | `Array<Hash>`   | no                                     | `[]`    | `[{ start_time:, end_time: }, ...]`. Used instead of `start_time`/`end_time` for multi-session events. Each session needs both times, with `end_time` after `start_time`. `:ics`/`:ical` emit one `VEVENT` per session and `:yahoo` one URL per session (newline-separated); `:google`/`:outlook`/`:office365` can only express one range, so they use `start_time`/`end_time`, which default to the earliest session start and latest session end (explicit values win). |
 | `uid`                  | `String`        | no                                     | randomly generated, memoized per `Event` instance | Stable RFC 5545 identifier. **Must** be reused across calls when you send an update (`:request`) or cancellation (`:cancel`) for a previously sent invite — see [Updating and cancelling invites](#updating-and-cancelling-invites). |
 | `sequence`             | `Integer`       | no                                     | `0`     | RFC 5545 SEQUENCE. Increment it yourself each time you resend a `:request`/`:cancel` for the same `uid`. |
 | `geo`                  | `Array<Float>`, `Hash` | no                              | `nil`   | `[37.4595, -122.1418]` or `{ lat:, lng: }`. Emits `GEO:lat;lng` — lets Apple/Google Maps deep-link from the invite. |
@@ -88,7 +86,7 @@ Pass one of these symbols to `generate_calendar_url`:
 
 `CalInvite::Providers::SUPPORTED_PROVIDERS` holds the full list programmatically.
 
-`CalInvite::Providers::IcsContent` is also available directly (not via `generate_calendar_url`) if you want raw `.ics` content without going through `Event#generate_calendar_url`'s caching path — see [ICS content and downloads](#ics-content-and-downloads).
+`CalInvite::Providers::IcsContent` is also available directly (not via `generate_calendar_url`) if you want raw `.ics` content without `Event#generate_calendar_url`'s validation — see [ICS content and downloads](#ics-content-and-downloads).
 
 ## `generate_calendar_url`
 
@@ -98,20 +96,26 @@ event.generate_calendar_url(provider, method: :publish)
 
 | Param     | Type     | Default    | Notes |
 |-----------|----------|------------|-------|
-| `provider`| `Symbol` | required   | One of the provider symbols above. |
+| `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). |
 
-Results are cached (when caching is configured) keyed on all event attributes, `provider`, and `method` together — changing any of them produces a distinct cache entry.
+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
+  meeting.to_cal_invite_event.generate_calendar_url(:ics, method: :request)
+end
+```
 
 ## ICS content and downloads
 
 Two ways to get raw `.ics` content:
 
 ```ruby
-# Via Event (goes through validation + caching)
+# Via Event (goes through validation)
 content = event.generate_calendar_url(:ics, method: :publish)
 
-# Directly via the provider (bypasses Event caching)
+# Directly via the provider (skips Event#validate!)
 content = CalInvite::Providers::Ics.new(event, method: :publish).generate
 ```
 
@@ -331,10 +335,8 @@ A working reference implementation of this whole pattern — a `Meeting` model
 persisting `uid`/`sequence`, and controller actions that send/reschedule/cancel
 — lives in [`Example/calendar_app`](Example/calendar_app): see
 `app/models/meeting.rb` and `app/controllers/meetings_controller.rb`. It
-depends on the attendee-hash/`uid`/`sequence` features documented here, so it
-needs whatever gem version ships those (0.2.0+) — the example app's `Gemfile`
-tracks the published gem, so point it at `path: "../.."` locally if you want
-to run this demo before that release is out.
+depends on the attendee-hash/`uid`/`sequence` features documented here, which
+shipped in 0.2.0, so it runs against the published gem.
 
 ## Tracking RSVPs: what the gem does and doesn't do
 
@@ -506,20 +508,17 @@ For any `timezone` other than `'UTC'` that's a recognized IANA/Olson identifier
 timestamps with no `VTIMEZONE` block, which every calendar client understands
 unambiguously.
 
-If `timezone` isn't a recognized IANA identifier (e.g. a raw offset string like
-`'+01:00'`), both providers fall back to treating `start_time`/`end_time` as
-already being in that zone's wall-clock time — the pre-existing behavior — since
-there's no timezone database entry to convert against or build a `VTIMEZONE`
-from.
+Any other value — including raw offset strings like `'+01:00'` — raises
+`ArgumentError` from `Event.new`/`update_attributes`: there's no timezone
+database entry to convert against or build a `VTIMEZONE` from, and emitting a
+`TZID` with no matching `VTIMEZONE` is invalid RFC 5545. Use the IANA name for
+the place instead (e.g. `'Europe/Paris'`), or `'UTC'`.
 
 ## Global configuration (`CalInvite.configure`)
 
 ```ruby
 # config/initializers/cal_invite.rb
 CalInvite.configure do |config|
-  config.cache_store = Rails.cache        # or :memory_store, :null_store, or a custom read/write/delete object
-  config.cache_prefix = 'my_app_cal_invite'
-  config.cache_expires_in = 3600           # seconds
   config.webhook_secret = ENV['CAL_INVITE_WEBHOOK_SECRET']
   config.timezone = 'UTC'
 end
@@ -527,10 +526,7 @@ end
 
 | Option              | Type                                   | Default        | Notes |
 |---------------------|-----------------------------------------|----------------|-------|
-| `cache_store`       | `:memory_store`, `:null_store`, or any object implementing `read`/`write`/`delete` | `nil` (caching disabled) | See [CACHING.md](CACHING.md) for full detail. |
-| `cache_prefix`      | `String`                                | `'cal_invite'` | Namespaces cache keys. |
-| `cache_expires_in`  | `Integer` (seconds)                     | `86400` (24h)  | |
 | `webhook_secret`    | `String`                                | `nil`          | Reserved for webhook signature verification in consuming apps. |
-| `timezone`          | `String`                                | `'UTC'`        | Configuration-level default; per-event `timezone` attribute takes precedence for that event's display formatting. |
+| `timezone`          | `String`                                | `'UTC'`        | Default `timezone` for events created without one; an explicit per-event `timezone:` wins. Validated like any event timezone, so an unknown value makes `Event.new` raise `ArgumentError`. |
 
-Caching is disabled unless `cache_store` is set — without it, `generate_calendar_url` regenerates output on every call.
+`cache_store`, `cache_prefix` and `cache_expires_in` are deprecated and have no effect. Setting one prints a warning, and they'll be removed in 0.4.0, so delete them from your initializer.

data/README.md

@@ -1,268 +1,210 @@
-# 📅 CalInvite
+# CalInvite
 
-A Ruby gem for generating calendar invitations across multiple calendar platforms with caching and 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
+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.
 
-## Supported Calendar Platforms
+## Contents
 
-Direct Integration:
-- Apple iCal (with proper timezone support)
-- Microsoft Outlook
-- Microsoft Outlook 365
-- Google Calendar
-- Yahoo Calendar
-- Standard .ics file generation
-
-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 invites with RSVP
 
-### Sending Email Meeting Invites (RSVP-capable)
+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.
 
-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).
-
-### 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"
+  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 Support
-
-CalInvite includes built-in caching support to improve performance when generating calendar URLs. To enable caching in your Rails application:
+Global settings:
 
 ```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
+  config.timezone = "America/New_York"   # default for events that don't set one
 end
 ```
 
-For detailed information about configuring caching in Rails applications and available options, see our [Caching Guide](https://github.com/DashAPI-ai/cal-invite/blob/master/CACHING.md). For every other configuration option (`Event` attributes, providers, email invites), see [CONFIGURATION.md](CONFIGURATION.md).
+## Upgrading to 0.3.0
 
-## Development
+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.
 
-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.
+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).
 
-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).
+## Documentation
 
-## Testing
+- [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.
 
-Add test(s) as necessary.
+## Development
 
-Run all the tests before submitting: `bundle exec rake test`
+```bash
+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
+```
 
-## Contributing
+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.
 
-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).
+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.
 
-## Documentation
+## Contributing
 
-The documentation is spread across the README, [CONFIGURATION.md](CONFIGURATION.md), [CACHING.md](CACHING.md), and the doc folder.
+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).
 
-The documentation can be generated using `bundle exec rake rdoc`
+## Sponsor
 
-## License
+CalInvite is sponsored by [DashAPI](https://dashapi.ai).
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+<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>
 
-## Code of Conduct
+## License
 
-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

@@ -25,7 +25,8 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.options << '--exclude' << '^(test|spec|features)/'
 
   # 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/SECURITY.md

@@ -2,20 +2,49 @@
 
 ## Supported Versions
 
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
+Security fixes are released for the latest minor version only. Please upgrade to
+the most recent release before reporting.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 5.1.x   | :white_check_mark: |
-| 5.0.x   | :x:                |
-| 4.0.x   | :white_check_mark: |
-| < 4.0   | :x:                |
+| 0.2.x   | :white_check_mark: |
+| < 0.2   | :x:                |
 
 ## Reporting a Vulnerability
 
-Use this section to tell people how to report a vulnerability.
+**Please do not open a public issue for security problems.**
 
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.
+Report vulnerabilities privately through GitHub:
+[Report a vulnerability](https://github.com/DashAPI-ai/cal-invite/security/advisories/new)
+(Security tab → "Report a vulnerability").
+
+Please include:
+
+- the affected version(s) and provider(s) (`:ics`, `:google`, ...)
+- a minimal `CalInvite::Event` that reproduces the issue, and the output you got
+- the impact you expect (e.g. injected `.ics` properties, broken URL encoding)
+
+What to expect:
+
+- an acknowledgement within 5 business days;
+- an assessment, and a fix timeline if the report is accepted, within 14 days;
+- a patched release plus a published GitHub Security Advisory (with credit, if
+  you'd like it) once a fix is available. If the report is declined, we'll
+  explain why.
+
+## Scope
+
+CalInvite turns `CalInvite::Event` attributes into calendar URLs and `.ics`
+content. Attribute values are treated as untrusted:
+
+- **URL providers** (`:google`, `:outlook`, `:office365`, `:yahoo`) URL-encode
+  every value.
+- **`.ics` providers** (`:ics`, `:ical`, `IcsContent`) escape TEXT values per
+  RFC 5545, quote and escape parameter values (e.g. `CN=`) per RFC 6868, and raise
+  `ArgumentError` rather than emit a value that would break out of its content
+  line.
+
+Anything that lets attribute values alter the structure of generated output
+(extra properties, components, parameters, or URL query parameters) is in scope.
+How the host application stores, sends, or serves the generated content (email
+delivery, HTTP headers you set yourself, etc.) is out of scope.