docs(03-02): complete broker primitives plan — vevent.ts + write.ts GREEN
This commit is contained in:
Lucas Berger
@@ -0,0 +1,119 @@
|
||||
---
|
||||
phase: 03-event-write-back-pwa-install
|
||||
plan: 02
|
||||
subsystem: broker, caldav
|
||||
tags: [ical.js, tsdav, vevent-builder, caldav-write, d-13, tdd]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 03-event-write-back-pwa-install
|
||||
plan: 01
|
||||
provides: Wave 0 RED test scaffold (vevent.test.ts, write.test.ts), calendarOutbox schema
|
||||
|
||||
provides:
|
||||
- buildVeventString(NewEventParams) → { uid, icsString } in broker/vevent.ts
|
||||
- createCalendarEvent / updateCalendarEvent / deleteCalendarEvent in broker/write.ts
|
||||
- RRULE_PRESETS map and NewEventParams interface exported from vevent.ts
|
||||
|
||||
affects: [03-03, 03-04]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "ICAL.Recur.fromString + new ICAL.Property('rrule') for RRULE serialization (addPropertyWithValue on string produces char-split output)"
|
||||
- "ICAL.Time({ isDate: true }, ICAL.Timezone.localTimezone) for all-day DATE values (TS types require 2-arg constructor)"
|
||||
- "ICAL.Time.fromJSDate(date, true) for timed UTC events (useUTC=true → Z suffix, no TZID)"
|
||||
- "null etag passed as '' in tsdav calendarObject (safe default; tsdav skips If-Match header)"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- apps/api/src/broker/vevent.ts
|
||||
- apps/api/src/broker/write.ts
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "D-02-RRULE: ICAL.Recur.fromString + ICAL.Property('rrule') is required for correct RRULE serialization. ICAL.Component.addPropertyWithValue('rrule', string) treats the string as a TEXT value and serializes each character individually — unusable. Use ICAL.Recur.fromString → prop.setValue(recur) → vevent.addProperty(prop)."
|
||||
- "D-02-DATE-ZONE: ICAL.Time constructor TypeScript signature requires 2 args (data, zone). For all-day DATE values, isDate:true suppresses any TZID output regardless of which zone is passed. ICAL.Timezone.localTimezone is the safe choice; it satisfies the type without adding TZID to DATE properties."
|
||||
|
||||
# Metrics
|
||||
duration: ~4min
|
||||
completed: 2026-06-05
|
||||
---
|
||||
|
||||
# Phase 03 Plan 02: Broker Primitives — vevent.ts + write.ts Summary
|
||||
|
||||
**VEVENT builder and tsdav write wrappers implemented GREEN against Wave 0 RED scaffolds — all 13 broker tests pass, tsc clean**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~4 min
|
||||
- **Started:** 2026-06-05T21:44Z
|
||||
- **Completed:** 2026-06-05T21:48Z
|
||||
- **Tasks:** 2
|
||||
- **Files created:** 2
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Implemented `buildVeventString(params: NewEventParams): { uid: string; icsString: string }` in `broker/vevent.ts` using ical.js ICAL.Component/ICAL.Time APIs
|
||||
- D-13 DATE/DATETIME split: all-day events use `ICAL.Time({ isDate: true })` → VALUE=DATE (no TZID, no time); timed events use `ICAL.Time.fromJSDate(date, true)` → DTSTART:...Z (no TZID)
|
||||
- RRULE correctly serialized via `ICAL.Recur.fromString` + `ICAL.Property` (not `addPropertyWithValue` which produces char-split output)
|
||||
- Exported `NewEventParams` interface and `RRULE_PRESETS` map (daily/weekly/monthly/yearly preset strings)
|
||||
- Implemented `createCalendarEvent`, `updateCalendarEvent`, `deleteCalendarEvent` in `broker/write.ts` as the sole CalDAV write boundary (D-12)
|
||||
- All etag null-coalescion to `''` so tsdav safely omits the If-Match header rather than crashing
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: GREEN — buildVeventString** — `b23b959` (feat)
|
||||
2. **Task 2: GREEN — tsdav write wrappers + vevent.ts TS fix** — `a1243c1` (feat)
|
||||
|
||||
## Files Created
|
||||
|
||||
- `apps/api/src/broker/vevent.ts` — buildVeventString, NewEventParams, RRULE_PRESETS (117 lines)
|
||||
- `apps/api/src/broker/write.ts` — createCalendarEvent, updateCalendarEvent, deleteCalendarEvent (99 lines)
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **D-02-RRULE:** `ICAL.Component.addPropertyWithValue('rrule', string)` treats the raw string as a TEXT value and serializes character-by-character (e.g., `RRULE:0=F;1=R;2=E;3=Q...`). The correct approach is `ICAL.Recur.fromString(rruleString)` → `prop = new ICAL.Property('rrule')` → `prop.setValue(recur)` → `vevent.addProperty(prop)`. This produces the correct `RRULE:FREQ=WEEKLY;BYDAY=MO` output.
|
||||
|
||||
- **D-02-DATE-ZONE:** ical.js `ICAL.Time` TypeScript types require 2 arguments `(data: timeInit, zone: Timezone)`. For all-day DATE values, `isDate: true` in the data object suppresses any TZID/time output regardless of the zone passed. `ICAL.Timezone.localTimezone` is the appropriate second arg — it satisfies the type and has no effect on DATE serialization.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] RRULE serialization via addPropertyWithValue produces character-split output**
|
||||
- **Found during:** Task 1 — first test run showed `RRULE:0=F;1=R;2=E;3=Q...` instead of `RRULE:FREQ=WEEKLY;BYDAY=MO`
|
||||
- **Issue:** `vevent.addPropertyWithValue('rrule', string)` passes a JavaScript string where ical.js expects a RECUR value type. ical.js iterates the string object properties (0, 1, 2...) and serializes each character as a key-value pair.
|
||||
- **Fix:** Use `ICAL.Recur.fromString(params.rruleString)` to parse the string into a RECUR value object, then `new ICAL.Property('rrule')` + `prop.setValue(recur)` + `vevent.addProperty(prop)`.
|
||||
- **Files modified:** `apps/api/src/broker/vevent.ts`
|
||||
- **Commit:** `a1243c1` (combined with Task 2)
|
||||
|
||||
**2. [Rule 1 - Bug] ICAL.Time constructor TypeScript type error (2 args required)**
|
||||
- **Found during:** Task 2 — `tsc --noEmit` reported `Expected 2 arguments, but got 1` for `new ICAL.Time({ isDate: true })` calls
|
||||
- **Issue:** ical.js TypeScript declarations define `constructor(data: timeInit, zone: Timezone)` as requiring both arguments, though the JavaScript implementation accepts 1.
|
||||
- **Fix:** Pass `ICAL.Timezone.localTimezone` as the second arg. For `isDate: true` DATE values, the zone has no effect on serialization — it does not add TZID to the property.
|
||||
- **Files modified:** `apps/api/src/broker/vevent.ts`
|
||||
- **Commit:** `a1243c1`
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — both files are fully implemented primitives. No hardcoded placeholder values.
|
||||
|
||||
## Threat Surface Scan
|
||||
|
||||
No new network endpoints or auth paths introduced. `broker/write.ts` is a low-level CalDAV I/O primitive called only by the outbox worker (planned in 03-03). The T-03-03 (ical.js escaping) and T-03-04 (etag sourced server-side) mitigations from the threat model are implemented as designed.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- `apps/api/src/broker/vevent.ts` — exists (confirmed)
|
||||
- `apps/api/src/broker/write.ts` — exists (confirmed)
|
||||
- Commit `b23b959` — exists (git log confirmed)
|
||||
- Commit `a1243c1` — exists (git log confirmed)
|
||||
- `pnpm --filter @familysync/api exec vitest run tests/broker/vevent.test.ts` — 7/7 PASS
|
||||
- `pnpm --filter @familysync/api exec vitest run tests/broker/write.test.ts` — 6/6 PASS
|
||||
- `pnpm --filter @familysync/api exec tsc --noEmit` — clean (no errors)
|
||||
|
||||
---
|
||||
*Phase: 03-event-write-back-pwa-install*
|
||||
*Completed: 2026-06-05*
|
||||
Reference in New Issue
Block a user