Build the two pure broker primitives every write slice depends on: `vevent.ts`
(construct a valid iCalendar VEVENT from form params) and `write.ts` (wrap tsdav's
three CalDAV write methods to enforce the broker boundary, D-12). These are the most
testable units in the phase — defined input → defined ICS/HTTP output — so they are
built TDD against the RED stubs from Plan 01.
Purpose: CAL-04/05/06/07 all reduce to "produce the right VEVENT and PUT/DELETE it
through tsdav." Getting the D-13 DATE-vs-DATETIME split and the If-Match wiring right
here means the worker (Plan 03) and endpoints (Plan 04) just orchestrate.
Output: vevent.ts, write.ts, both GREEN against their Plan 01 test files.
@.planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md
@.planning/phases/03-event-write-back-pwa-install/03-PATTERNS.md
@apps/api/src/broker/client.ts
@apps/api/src/broker/sync.ts
Task 1: GREEN — buildVeventString VEVENT builder (vevent.ts)
apps/api/src/broker/vevent.ts, apps/api/tests/broker/vevent.test.ts
- apps/api/tests/broker/vevent.test.ts (RED stubs from Plan 01 — these define the contract)
- .planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md (§Pattern 1 — full buildVeventString reference incl. NewEventParams; §Pitfall 3 — DATE vs DATETIME)
- apps/api/src/broker/sync.ts (lines ~89-101 — the existing D-13 isDate split this must mirror in reverse)
- .planning/phases/03-event-write-back-pwa-install/03-PATTERNS.md (§vevent.ts — ICAL import, D-13 split, error isolation)
RED → GREEN. Tests assert:
- Timed event: output contains `BEGIN:VEVENT`, `DTSTART:` with a `Z` UTC suffix (no TZID param), matching UID and SUMMARY.
- All-day event (allDay:true): DTSTART is a DATE value (`VALUE=DATE` or 8-digit YYYYMMDD with no `T`/time), NO TZID, NO time component (D-13). End is also DATE.
- Recurring: passing `rruleString: 'FREQ=WEEKLY'` yields an `RRULE:FREQ=WEEKLY` line.
- location/description optional properties appear only when provided.
- omitting `uid` generates a `@familysync` UID via crypto.randomUUID().
Implement `buildVeventString(params: NewEventParams): { uid: string; icsString: string }` exactly per RESEARCH.md Pattern 1. Export the `NewEventParams` interface and a `RRULE_PRESETS` map (`daily:'FREQ=DAILY'`, `weekly:'FREQ=WEEKLY'`, `monthly:'FREQ=MONTHLY'`, `yearly:'FREQ=YEARLY'`). Use `import ICAL from 'ical.js'` and `import { randomUUID } from 'crypto'`. For all-day use `new ICAL.Time({ year, month, day, isDate: true })`; for timed use `ICAL.Time.fromJSDate(date, true)` (useUTC=true → Z suffix, no TZID). Always add VERSION 2.0 and PRODID `-//FamilySync//FamilySync//EN`. Use `.js`-suffixed relative imports if any. Never coerce DATE→DATETIME.
cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- broker/vevent
- `pnpm --filter @familysync/api test -- broker/vevent` is GREEN (all assertions pass).
- All-day test asserts no `T000000`/time component and no `TZID` in the DATE DTSTART.
- `grep -q "RRULE_PRESETS" apps/api/src/broker/vevent.ts`.
buildVeventString passes all vevent.test.ts cases including the D-13 DATE-vs-DATETIME split and RRULE serialization.
Task 2: GREEN — tsdav write wrappers (write.ts)
apps/api/src/broker/write.ts, apps/api/tests/broker/write.test.ts
- apps/api/tests/broker/write.test.ts (RED stubs from Plan 01 — the contract)
- .planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md (§Pattern 2 — full write.ts reference; status-code interpretation; §Pitfall 4 — etag may be null)
- apps/api/src/broker/client.ts (FastmailClient type; .js import convention; named-export style)
- .planning/phases/03-event-write-back-pwa-install/03-PATTERNS.md (§write.ts — header/imports/exports pattern)
RED → GREEN. With a mock FastmailClient, tests assert:
- createCalendarEvent({client, calendar, uid, icsString}) calls `client.createCalendarObject` with `filename === \`${uid}.ics\`` and the iCalString, and returns the raw Response.
- updateCalendarEvent(client, calendarObjectUrl, icsString, etag) calls `client.updateCalendarObject` with calendarObject `{ url, data, etag }` — etag drives the If-Match header.
- deleteCalendarEvent(client, calendarObjectUrl, etag) calls `client.deleteCalendarObject` with `{ url, etag }`.
- A null etag is passed through as `''` (no crash).
Implement `createCalendarEvent`, `updateCalendarEvent`, `deleteCalendarEvent` per RESEARCH.md Pattern 2 as named exports returning `Promise`. Import `FastmailClient` from `./client.js` and `DAVCalendar` from `tsdav`. These functions are the ONLY place outside client.ts/sync.ts/poller.ts that touch tsdav write methods (D-12 broker boundary). Do not interpret status codes here — return the raw Response so the worker (Plan 03) classifies transient/hard/conflict. If `deleteCalendarObject` requires a `data` field, pass `''`.
cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- broker/write && pnpm --filter @familysync/api exec tsc --noEmit
- `pnpm --filter @familysync/api test -- broker/write` is GREEN.
- `grep -Eq "createCalendarObject|updateCalendarObject|deleteCalendarObject" apps/api/src/broker/write.ts` (all three present).
- tsc --noEmit passes.
write.ts wraps all three tsdav write methods with correct filenames/If-Match wiring; tests GREEN; types compile.
<threat_model>
Trust Boundaries
Boundary
Description
broker → Fastmail CalDAV
Only write.ts issues PUT/DELETE to Fastmail (D-12)
STRIDE Threat Register
Threat ID
Category
Component
Disposition
Mitigation Plan
T-03-03
Tampering
VEVENT field serialization (summary/location/description with special chars)
