aboutsummaryrefslogtreecommitdiffstats
path: root/docs/superpowers/specs
diff options
context:
space:
mode:
Diffstat (limited to 'docs/superpowers/specs')
-rw-r--r--docs/superpowers/specs/2026-11-16-receiving-invitations-design.md129
1 files changed, 129 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-11-16-receiving-invitations-design.md b/docs/superpowers/specs/2026-11-16-receiving-invitations-design.md
new file mode 100644
index 0000000..7d403e8
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-16-receiving-invitations-design.md
@@ -0,0 +1,129 @@
+# Receiving invitations
+
+Item 207, receiving half. Designed 2026-11-16. Sending invitations is item 216.
+
+## Problem
+
+"As it is today I don't have a way of accepting an invitation." `MimeParser`
+has no branch for `text/calendar`, so an invitation reaches the pane as an
+attachment chip or as nothing. The calendar (item 206) can store events but
+nothing connects a message to it.
+
+## Decisions made with the user
+
+1. **Receiving first.** Sending invites (attendee editing, `METHOD:REQUEST`,
+ applying the `REPLY`s that come back) is item 216.
+2. **The target calendar is mapped per account.** An optional
+ `calendar = <collection>` key in `[account.<key>]`. Unset: the first write
+ asks for a collection from a list.
+3. **A reply goes both ways.** Accept / Tentative / Decline send at once
+ through the existing send countdown; each also has a "...with note" entry
+ that opens a composer carrying the calendar part.
+4. **Decline writes nothing**, and removes the event if an earlier Accept
+ stored it.
+5. **Organiser updates and cancellations wait for a button.** Opening the
+ message changes nothing.
+
+## Approach
+
+A native **invitation bar** in `MessageView`, between the message bar and the
+web view, in the same family as the blocked-content and stale bars. Labels
+are `Qt::PlainText`, buttons are `QPushButton`s. Rejected: rendering it in
+the HTML body, which needs the interceptor to admit `qtmaildir:` actions and
+loosens the most security-sensitive area for a convenience; and a dialog from
+the attachment chip, which hides the invitation.
+
+## Parsing
+
+- `MimeParser` keeps the FIRST `text/calendar` part's decoded bytes on
+ `ParsedMessage` (`calendarPart`), whether it arrived inline in a
+ `multipart/alternative` or as an attachment. It stays an attachment chip too,
+ as today.
+- `CalendarStore` gains pure functions over bytes, so the logic is tested with
+ no widget, the `CardLayout` rule:
+ - `parseInvitation(bytes)` returns an `Invitation` value (`caltypes.h`):
+ method, uid, sequence, recurrence-id, summary, location, start, end,
+ all-day, organizer, attendees. A part that does not parse, has no `METHOD`,
+ or has no `VEVENT` returns an invalid one.
+ - `storedText(inviteBytes, myAddress, partstat)`: the event file to write.
+ `METHOD` removed (a stored object carries none), my `ATTENDEE`'s
+ `PARTSTAT` set, `RSVP` cleared, everything else as the organiser sent it,
+ including `TZID` parameters (the 120-files rule from 206: never convert).
+ - `replyText(inviteBytes, myAddress, partstat)`: a `METHOD:REPLY` calendar
+ holding the `VEVENT` with `UID`, `SEQUENCE`, `DTSTAMP`, `ORGANIZER`,
+ `RECURRENCE-ID` when present, and ONLY my `ATTENDEE` line, per RFC 5546.
+ - `findByUid(events, uid)`: the stored event, if any.
+- **"Me"** is the attendee whose address matches the `address` of the account
+ the message arrived on (case-insensitive, `mailto:` stripped). No match: the
+ bar says so and offers no reply.
+
+## Bar states
+
+A pure function `invitationState(invitation, storedEvent, meFound)` picks one,
+returning an enum; the widget only renders it.
+
+| State | Shown | Buttons |
+|---|---|---|
+| New request | title, time, place, organiser, attendee count | Accept, Tentative, Decline, each with "...with note" |
+| Update (stored, higher `SEQUENCE`) | the same, plus what changed: time, place | Update calendar, and the reply buttons |
+| Already answered (stored, same `SEQUENCE`) | the same, plus "In your calendar: <partstat>" | the reply buttons, to change the answer |
+| Cancel, stored | "Cancelled by the organiser" | Remove from calendar |
+| Cancel, not stored | "Cancelled; not in your calendar" | none. Normal, not an error |
+| Out of date (lower `SEQUENCE` than stored) | "Out of date: your calendar holds a newer version" | none |
+| One occurrence (`RECURRENCE-ID`) | details | none: "Changes to a single occurrence aren't supported yet" |
+| Not invited | details | none: "You are not on the attendee list" |
+| Other method (`REPLY`, `PUBLISH`, ...) | no bar | |
+
+No calendar configured (`calendarsDir()` empty): details only, no buttons.
+
+## Reply and write
+
+- `OutgoingMessage` gains `calendarPart` (bytes) and `calendarMethod`.
+ `MessageBuilder` adds it as a `text/calendar; method=<METHOD>; charset=utf-8`
+ part beside the text body. Subject: `Accepted: <summary>` /
+ `Tentative: ...` / `Declined: ...`, translated. To: the organiser.
+ From: the account the invitation arrived on.
+- One click hands the built message to the existing `SendDialog` countdown.
+ "...with note" opens a `ComposeWindow` with the part attached and the subject
+ and recipient filled; the user's text is the body.
+- **The calendar write happens only when the send SUCCEEDS.** An aborted
+ countdown or a failed send leaves the calendar untouched, so the calendar
+ never claims an answer the organiser never received. Accept and Tentative
+ write `storedText`; Decline removes a stored event; a change of answer
+ rewrites it.
+- Update calendar and Remove from calendar send nothing and write at once.
+- Every write goes through `CalendarWriter::replace` with the stored event's
+ bytes as `expected` (a new file expects absent), and a `Stale` result is
+ reported in the status bar rather than retried. A new event is written as
+ `<collection>/<uid-derived name>.ics`, the name sanitised as an attachment
+ filename is. A `CalendarSync` runs after.
+- An open `CalendarWindow` reloads after any such write.
+
+## Safety
+
+- Every value in the bar comes from a stranger: `Qt::PlainText`, no `URL`,
+ no `ATTACH`, no `DESCRIPTION` (it can be long and is in the body anyway).
+- A button acts on the `Invitation` the bar is displaying, captured with it,
+ never on a re-read of the message.
+- The `UID` reaches a filename: sanitised, and the resolved path must stay
+ inside the collection directory, compared as paths (the attachment rule).
+
+## Tests
+
+- `CalendarStore`: fixture `.ics` for a request, a cancel, an update, an older
+ sequence, a recurrence-id, and an invite without me. `storedText` keeps
+ `TZID`, drops `METHOD`, sets only my `PARTSTAT`; `replyText` carries only my
+ attendee and the right method.
+- `invitationState`: one case per row of the table.
+- `MimeParser`: the part is found inline and as an attachment.
+- `MessageBuilder`: the part is present with its `method` parameter.
+- The write-after-send rule: an aborted send writes nothing.
+- How the bar looks is the user's hand test.
+
+## Out of scope
+
+- Single-occurrence updates (`RECURRENCE-ID`).
+- Showing or applying replies to the user's own invitations, item 216.
+- Editing attendees and sending invitations, item 216.
+- Alarms on accepted events: kept if the organiser sent them, never fired,
+ as in 206.