docs(11): add pattern map for per-event reminders

2026-06-13 21:20:55 -04:00
parent cfeb8d8660
commit 6109d4ca49
1 changed files with 485 additions and 0 deletions
@@ -0,0 +1,485 @@
+# Phase 11: Per-Event Reminders - Pattern Map
+
+**Mapped:** 2026-06-13
+**Files analyzed:** 8 modified + 2 extended test files
+**Analogs found:** 10 / 10 (all modify-existing — no greenfield files)
+
+---
+
+## File Classification
+
+| Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|---|---|---|---|---|
+| `apps/api/src/broker/vevent.ts` | utility / builder | transform | self (extend `extractRruleString`) | exact |
+| `apps/api/src/broker/outboxWorker.ts` | worker | event-driven | self (extend `hasExplicitRecurrence` + `resolveFinalRrule`) | exact |
+| `apps/api/src/broker/reminderScheduler.ts` | scheduler | event-driven | self (extend `runReminderCheck`) | exact |
+| `apps/api/src/broker/sync.ts` | service | CRUD | self (extend upsert at line 144) | exact |
+| `apps/api/src/broker/expand.ts` | utility | transform | self (extend `CalendarOccurrence` interface) | exact |
+| `apps/api/src/routes/events.ts` | route/controller | request-response | self (extend `eventFieldsSchema`) | exact |
+| `apps/pwa/src/api/client.ts` | client utility | request-response | self (extend `CreateEventPayload`) | exact |
+| `apps/pwa/src/components/EventForm.tsx` | component | request-response | self (Recurrence picker at lines 848–885) | exact |
+| `apps/api/tests/broker/vevent.test.ts` | test | — | self (extend existing describe blocks) | exact |
+| `apps/api/tests/broker/reminderScheduler.test.ts` | test | — | self (extend existing describe blocks) | exact |
+
+---
+
+## Pattern Assignments
+
+### `apps/api/src/broker/vevent.ts` (utility/builder, transform)
+
+**Changes:** (1) Add `reminderLeadMinutes`, `valarms`, `allDayAlertInstantUtc` to `NewEventParams`. (2) Add VALARM emission block after the RRULE block. (3) Add `classifyValarms()` and `extractValarms()` exported functions.
+
+**Analog pattern — RRULE property construction** (vevent.ts lines 149–153):
+The RRULE block is the template for VALARM emission. It uses `new ICAL.Property` + `resetType`/`setValue` to avoid string-serialization bugs — the same technique required for TRIGGER to avoid `VALUE=TEXT` (Pitfall 2).
+
+```typescript
+// RRULE analog — lines 149–153 (DO NOT COPY verbatim; adapt for VALARM)
+if (params.rruleString) {
+  const recur = ICAL.Recur.fromString(params.rruleString);
+  const rruleProp = new ICAL.Property('rrule');
+  rruleProp.setValue(recur);
+  vevent.addProperty(rruleProp);
+}
+```
+
+**Adapt for VALARM emission** (insert after line 153, before optional fields):
+```typescript
+// VALARM — preserve path (edit with no picker change)
+if (params.valarms && params.valarms.length > 0) {
+  for (const alarm of params.valarms) {
+    vevent.addSubcomponent(alarm);
+  }
+}
+// VALARM — new alarm path (create, or user changed picker)
+else if (params.reminderLeadMinutes != null) {
+  if (params.allDay && params.allDayAlertInstantUtc) {
+    // Absolute DATE-TIME trigger for all-day events
+    const valarm = new ICAL.Component('valarm');
+    valarm.addPropertyWithValue('action', 'DISPLAY');
+    valarm.addPropertyWithValue('description', 'Reminder');
+    const triggerProp = new ICAL.Property('trigger');
+    triggerProp.resetType('date-time');
+    triggerProp.setValue(ICAL.Time.fromJSDate(params.allDayAlertInstantUtc, true));
+    valarm.addProperty(triggerProp);
+    vevent.addSubcomponent(valarm);
+  } else if (!params.allDay && params.reminderLeadMinutes > 0) {
+    // Relative DURATION trigger for timed events
+    const valarm = new ICAL.Component('valarm');
+    valarm.addPropertyWithValue('action', 'DISPLAY');
+    valarm.addPropertyWithValue('description', 'Reminder');
+    const triggerProp = new ICAL.Property('trigger');
+    triggerProp.resetType('duration'); // critical: prevents VALUE=TEXT (Pitfall 2)
+    triggerProp.setValue(ICAL.Duration.fromSeconds(-params.reminderLeadMinutes * 60));
+    valarm.addProperty(triggerProp);
+    vevent.addSubcomponent(valarm);
+  }
+  // allDay=false && reminderLeadMinutes===0: no VALARM (timed 0 = None per D-06)
+}
+```
+
+**`extractRruleString` as pattern for `extractValarms`** (vevent.ts lines 63–79):
+```typescript
+// EXISTING — extractRruleString (lines 63–79) — copy structure for extractValarms
+export function extractRruleString(rawVevent: string): string | undefined {
+  let parsed: ReturnType<typeof ICAL.parse>;
+  try {
+    parsed = ICAL.parse(rawVevent);
+  } catch {
+    return undefined;
+  }
+  const comp = new ICAL.Component(parsed);
+  const vevent = comp.getFirstSubcomponent('vevent');
+  if (!vevent) return undefined;
+  const rrule = vevent.getFirstPropertyValue('rrule');
+  if (!rrule) return undefined;
+  return typeof rrule === 'string' ? rrule : (rrule as ICAL.Recur).toString();
+}
+```
+
+**`NewEventParams` interface extension** (vevent.ts lines 21–33):
+Add three optional fields to the existing interface:
+```typescript
+// ADD to NewEventParams (after line 32, before closing brace):
+reminderLeadMinutes?: number | null; // null = no VALARM; 0 = same-day all-day; positive = timed lead
+valarms?: ICAL.Component[];           // pre-parsed VALARMs from rawVevent (preserve-on-edit, D-08)
+allDayAlertInstantUtc?: Date;         // 9 AM local on alert day in UTC (computed by worker for all-day)
+```
+
+---
+
+### `apps/api/src/broker/outboxWorker.ts` (worker, event-driven)
+
+**Changes:** (1) Add `reminderLeadMinutes` to `outboxPayloadSchema`. (2) In update branch: add `hasExplicitReminder` check mirroring `hasExplicitRecurrence`. (3) Pass `valarms`/`reminderLeadMinutes`/`allDayAlertInstantUtc` to `buildVeventString`. (4) Same additions in create branch.
+
+**Key analog — `hasExplicitRecurrence` pattern** (outboxWorker.ts lines 425–466):
+```typescript
+// EXISTING — lines 425–426: template for hasExplicitReminder
+const hasExplicitRecurrence = Object.prototype.hasOwnProperty.call(fields, 'recurrence');
+// ...
+// EXISTING — lines 464–466: template for VALARM preserve-on-no-change
+if (!hasExplicitRecurrence && freshEtagRows.length > 0 && freshEtagRows[0].rawVevent) {
+  preservedRrule = extractRruleString(freshEtagRows[0].rawVevent);
+}
+```
+
+**Adapt for VALARM** (insert adjacent to the RRULE preserve block in the update branch):
+```typescript
+// ADD alongside the hasExplicitRecurrence block:
+const hasExplicitReminder = Object.prototype.hasOwnProperty.call(fields, 'reminderLeadMinutes');
+let valarmsToPreserve: ICAL.Component[] = [];
+let allDayAlertInstantUtc: Date | undefined;
+
+if (!hasExplicitReminder && freshEtagRows.length > 0 && freshEtagRows[0].rawVevent) {
+  // D-08: user did not touch the picker — preserve existing VALARM verbatim
+  valarmsToPreserve = extractValarms(freshEtagRows[0].rawVevent);
+} else if (hasExplicitReminder && fields.reminderLeadMinutes != null && fields.allDay) {
+  // All-day: compute 9 AM local UTC instant for the absolute DATE-TIME trigger
+  allDayAlertInstantUtc = computeAlertInstantUtc(
+    fields.start, // 'YYYY-MM-DD'
+    fields.reminderLeadMinutes / 1440, // leadDays
+    process.env.TZ ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+  );
+}
+```
+
+**`buildVeventString` call extension** (outboxWorker.ts lines 483–492):
+```typescript
+// EXISTING call (lines 483–492) — add three new params:
+const { icsString } = buildVeventString({
+  uid: row.uid,
+  summary: fields.title,
+  allDay: fields.allDay,
+  dtstart: fields.allDay ? fields.start : new Date(fields.start),
+  dtend: fields.allDay ? fields.end : new Date(fields.end),
+  location: fields.location,
+  description: fields.description,
+  rruleString: finalRruleString,
+  // ADD:
+  reminderLeadMinutes: hasExplicitReminder ? fields.reminderLeadMinutes : undefined,
+  valarms: valarmsToPreserve,
+  allDayAlertInstantUtc,
+});
+```
+
+**`outboxPayloadSchema` extension** (outboxWorker.ts lines 73–95):
+```typescript
+// EXISTING schema — add reminderLeadMinutes after recurrenceCount (line 93):
+reminderLeadMinutes: z.number().int().min(0).nullable().optional(),
+// Semantics: absent=no-change (D-08), null=clear VALARM, 0=same-day all-day, positive=timed lead
+```
+
+---
+
+### `apps/api/src/broker/reminderScheduler.ts` (scheduler, event-driven)
+
+**Changes:** (1) Change dedup key from bare `uid` to `uid:${dtstartMs}`. (2) Replace fixed `(now, now+16min]` window with per-event variable-lead query. (3) Drop `isShared=true` restriction. (4) Add all-day 9 AM UTC branch. (5) Replace hardcoded body string with `humanizeLeadMinutes()`.
+
+**Key analog — existing dedup map and dispatch loop** (reminderScheduler.ts lines 48, 141–188):
+```typescript
+// EXISTING dedup map (line 48) — change value type comment; key changes to uid:dtstartMs
+const sentReminders = new Map<string, number>(); // key: uid:dtstartMs
+
+// EXISTING dispatch loop pattern (lines 141–188) — preserve structure, change:
+// 1. dedup key: uid → `${uid}:${event.dtstartUtc.getTime()}`
+// 2. body: `Starts in ${minutes} min` → humanizeLeadMinutes(event.reminderLeadMinutes)
+// 3. post-dispatch sentReminders.set now uses compound key
+
+// EXISTING body string (line 157) — REPLACE:
+body: `Starts in ${minutes} min`,
+// WITH:
+body: humanizeLeadMinutes(event.reminderLeadMinutes),
+```
+
+**SQL query changes** (reminderScheduler.ts lines 84–107):
+The existing query is the structural template. Remove `eq(calendars.isShared, true)` and `eq(calendarEvents.allDay, false)`. Add `reminder_lead_minutes IS NOT NULL`. Split into two sub-queries (timed and all-day) or use a single query fetching all events with non-null leads and filter in JS:
+
+```typescript
+// EXISTING query structure (lines 84–107) — adapt WHERE clause:
+// REMOVE: eq(calendars.isShared, true)  — NOTIF-05: all events, not just shared
+// REMOVE: eq(calendarEvents.allDay, false)  — all-day events now supported (D-02)
+// ADD:    sql`${calendarEvents.reminderLeadMinutes} IS NOT NULL`
+// ADD:    reminderLeadMinutes to .select()
+
+// For timed events: keep dtstartUtc window logic (variable per-event lead)
+// For all-day events: fetch with non-null leads, compute 9 AM UTC in JS, filter in-memory
+```
+
+**Existing prune pattern** (reminderScheduler.ts lines 193–197):
+```typescript
+// EXISTING prune (lines 193–197) — key name changes to uid:dtstartMs but structure identical
+for (const [key, dtstartMs] of sentReminders) {
+  if (dtstartMs <= now.getTime()) {
+    sentReminders.delete(key);
+  }
+}
+```
+
+---
+
+### `apps/api/src/broker/sync.ts` (service, CRUD)
+
+**Changes:** Add VALARM parsing in the per-object loop to extract `reminderLeadMinutes`, then write it in the `onDuplicateKeyUpdate` call.
+
+**Key analog — existing upsert values block** (sync.ts lines 144–170):
+```typescript
+// EXISTING .values() call (lines 144–157) — add reminderLeadMinutes:
+await db
+  .insert(calendarEvents)
+  .values({
+    calendarId: cal.id,
+    uid,
+    etag: obj.etag ?? null,
+    objectUrl: obj.url ?? null,
+    rawVevent: obj.data as string,
+    title: titleValue,
+    dtstartUtc: dtstartUtcValue,
+    dtstartDate: dtstartDateValue,
+    allDay,
+    hasRrule: isRecurring,
+    // ADD:
+    reminderLeadMinutes: reminderLeadMinutesValue, // null when no VALARM
+  })
+  .onDuplicateKeyUpdate({
+    set: {
+      // ... existing fields ...
+      // ADD:
+      reminderLeadMinutes: reminderLeadMinutesValue,
+      updatedAt: new Date(),
+    },
+  });
+```
+
+**Extraction pattern** (mirrors `extractRruleString` from vevent.ts — use `classifyValarms`):
+Insert before the `await db.insert(...)` call, alongside the existing field extractions (lines 123–142):
+```typescript
+// ADD after titleValue / locationValue extraction:
+// Extract reminderLeadMinutes from VALARM (if any) — written to DB for scheduler ground truth
+const alarmClass = classifyValarms(obj.data as string);
+const reminderLeadMinutesValue: number | null =
+  alarmClass.kind === 'preset' || alarmClass.kind === 'offlist'
+    ? alarmClass.leadMinutes
+    : null; // 'custom' (absolute/multi) and 'none' both map to null
+```
+
+---
+
+### `apps/api/src/broker/expand.ts` (utility, transform)
+
+**Change:** Add `reminderLeadMinutes` field to `CalendarOccurrence` interface so edit mode can pre-populate the picker.
+
+**Key analog — existing `CalendarOccurrence` interface** (expand.ts lines 37–69):
+```typescript
+// EXISTING interface — add after hasRrule (line 68):
+/**
+ * Per-event reminder lead in minutes. NULL = no reminder. 0 = same-day all-day.
+ * Positive integer = N minutes before event start.
+ * D-06: NULL and 0 are semantically distinct.
+ */
+reminderLeadMinutes: number | null;
+```
+
+The corresponding DB select in the events route must also include `reminderLeadMinutes` in the join result passed to `expandOccurrences`. The `OccurrenceMeta` interface (expand.ts line 75+) may also need `reminderLeadMinutes` depending on how expansion propagates it.
+
+---
+
+### `apps/api/src/routes/events.ts` (route, request-response)
+
+**Change:** Add `reminderLeadMinutes` to `eventFieldsSchema`.
+
+**Key analog — existing `eventFieldsSchema`** (events.ts lines 101–120):
+```typescript
+// EXISTING schema (lines 101–120) — add after recurrenceCount (line 119):
+reminderLeadMinutes: z.number().int().min(0).nullable().optional(),
+// absent = no-change (edit, D-08); null = clear VALARM; 0 = same-day all-day; positive = timed lead
+```
+
+The schema comment pattern (lines 112–119) documents the security rationale inline — follow the same style for the new field.
+
+---
+
+### `apps/pwa/src/api/client.ts` (client utility, request-response)
+
+**Change:** Add `reminderLeadMinutes` to `CreateEventPayload` and to `CalendarOccurrence`.
+
+**Key analog — `CreateEventPayload` interface** (client.ts lines 175–198):
+```typescript
+// EXISTING interface — add after description (line 196):
+/**
+ * Per-event reminder lead in minutes.
+ * absent/undefined = no-change (edit omits it so server preserves existing VALARM, D-08)
+ * null = explicit "None" (clear any VALARM)
+ * 0 = same-day all-day (fire 9 AM on event date, D-05)
+ * positive integer = N minutes before event start
+ */
+reminderLeadMinutes?: number | null;
+```
+
+**`CalendarOccurrence` extension** (client.ts lines 108–134):
+Add after `hasRrule` (line 133), mirroring the server-side expand.ts change:
+```typescript
+reminderLeadMinutes: number | null; // mirrors expand.ts CalendarOccurrence (atomic mirror, Plan 06-05)
+```
+
+---
+
+### `apps/pwa/src/components/EventForm.tsx` (component, request-response)
+
+**Change:** Add reminder `<select>` after the Recurrence picker block (line 885), with allDay-aware option swap and edit-mode pre-population via `classifyValarms`.
+
+**Key analog — Recurrence picker block** (EventForm.tsx lines 848–885):
+This is the exact structural template for the reminder picker. Copy the entire block structure.
+
+```tsx
+// EXISTING Recurrence picker (lines 848–885) — reminder picker follows IDENTICAL structure:
+<div style={fieldStyle}>
+  <label htmlFor="event-recurrence" style={labelStyle}>
+    Repeat
+  </label>
+  <select
+    id="event-recurrence"
+    value={recurrence}
+    disabled={eventFormMode === 'edit'}
+    onChange={(e) => setRecurrence(e.target.value as RecurrencePreset)}
+    style={{
+      ...inputStyle,
+      padding: '0 var(--space-3)',
+      cursor: eventFormMode === 'edit' ? 'not-allowed' : 'pointer',
+      opacity: eventFormMode === 'edit' ? 0.6 : 1,
+    }}
+  >
+    <option value="none">None</option>
+    ...
+  </select>
+  {eventFormMode === 'edit' && (
+    <div style={{ fontSize: 'var(--text-label-size)', color: 'var(--color-text-secondary)', marginTop: 'var(--space-1)' }}>
+      ...helper text...
+    </div>
+  )}
+</div>
+```
+
+**Reminder picker differences from Recurrence picker:**
+1. `id="event-reminder"`, label text `"Reminder"` (UI-SPEC).
+2. NOT disabled on edit — reminder IS editable.
+3. Options are allDay-conditional: `{allDay ? <allDayOptions/> : <timedOptions/>}`.
+4. Off-list / Custom (kept) synthetic options appended dynamically.
+5. `onChange` resets synthetic option once a preset is chosen.
+6. Helper text shown when `alarmClass.kind === 'custom'` regardless of mode.
+
+**allDay-conditional option swap pattern** (mirrors existing `{!allDay && (...)}` conditionals already in EventForm.tsx for time fields):
+```tsx
+// Use the same allDay state variable already present in EventForm.tsx:
+{allDay ? (
+  // D-02 all-day presets
+  <>
+    <option value="__none__">None</option>
+    <option value="0">Same day (9 AM)</option>
+    <option value="1440">1 day before (9 AM)</option>
+    <option value="2880">2 days before (9 AM)</option>
+    <option value="10080">1 week before (9 AM)</option>
+  </>
+) : (
+  // D-01 timed presets
+  <>
+    <option value="__none__">None</option>
+    <option value="5">5 minutes before</option>
+    <option value="10">10 minutes before</option>
+    <option value="15">15 minutes before</option>
+    <option value="30">30 minutes before</option>
+    <option value="60">1 hour before</option>
+    <option value="120">2 hours before</option>
+    <option value="1440">1 day before</option>
+    <option value="2880">2 days before</option>
+  </>
+)}
+```
+
+**allDay toggle reset pattern** (D-03 — reset picker to None when allDay changes):
+```tsx
+// In the existing allDay onChange handler, also reset reminderLeadMinutes state:
+setReminderValue('__none__'); // reset to None on allDay toggle
+```
+
+---
+
+## Shared Patterns
+
+### ICAL.Property + resetType + setValue (Pitfall 2 prevention)
+**Source:** vevent.ts lines 149–153 (RRULE) — same technique for TRIGGER
+**Apply to:** `vevent.ts` VALARM emission, `vevent.ts` `buildRelativeTrigger`/`buildAbsoluteTrigger`
+```typescript
+// CORRECT — avoids VALUE=TEXT:
+const prop = new ICAL.Property('trigger');
+prop.resetType('duration');
+prop.setValue(ICAL.Duration.fromSeconds(-leadMinutes * 60));
+// WRONG — may emit VALUE=TEXT:
+// vevent.addPropertyWithValue('trigger', '-PT15M');
+```
+
+### `hasExplicitX` sentinel (absent-vs-null distinction, D-06/D-08)
+**Source:** outboxWorker.ts line 425
+**Apply to:** outboxWorker.ts `hasExplicitReminder` in both update and create branches
+```typescript
+const hasExplicitRecurrence = Object.prototype.hasOwnProperty.call(fields, 'recurrence');
+// Copy: const hasExplicitReminder = Object.prototype.hasOwnProperty.call(fields, 'reminderLeadMinutes');
+```
+
+### ICAL.parse try/catch + getFirstSubcomponent (sync.ts / vevent.ts)
+**Source:** vevent.ts lines 64–79 (`extractRruleString`); sync.ts lines 89–101
+**Apply to:** `extractValarms()` and `classifyValarms()` in vevent.ts
+```typescript
+try {
+  parsed = ICAL.parse(rawVevent);
+} catch {
+  return /* safe default */;
+}
+const comp = new ICAL.Component(parsed);
+const vevent = comp.getFirstSubcomponent('vevent');
+if (!vevent) return /* safe default */;
+```
+
+### setInterval scheduling (no node-cron)
+**Source:** reminderScheduler.ts lines 209–215; outboxWorker.ts lines 897–901
+**Apply to:** `startReminderScheduler` (no change needed — already setInterval)
+```typescript
+// node-cron 4.2.1 silently skips ticks in the long-lived process — do not reintroduce
+setInterval(() => {
+  runReminderCheck().catch((err: unknown) => { ... });
+}, 60 * 1000);
+```
+
+### Zod `.nullable().optional()` for NULL-vs-absent distinction
+**Source:** RESEARCH.md Q2 (no existing analog — first use of this pattern in the codebase)
+**Apply to:** `eventFieldsSchema` (events.ts), `outboxPayloadSchema` (outboxWorker.ts), `CreateEventPayload` (client.ts)
+```typescript
+reminderLeadMinutes: z.number().int().min(0).nullable().optional(),
+// absent (undefined) = no-change; null = clear; 0 = same-day; positive = lead
+```
+
+### Per-item try/catch error isolation
+**Source:** reminderScheduler.ts lines 181–187 (per-event), lines 167–175 (per-sub)
+**Apply to:** Preserve in modified `runReminderCheck` — both per-event and per-sub catches remain
+```typescript
+// Per-event:
+} catch (err) {
+  console.error(`[broker/reminderScheduler] Error processing event uid=${uid}:`, ...);
+}
+// Per-sub:
+} catch (err) {
+  console.error(`[broker/reminderScheduler] Error dispatching reminder to sub id=${sub.id}:`, ...);
+}
+```
+
+---
+
+## No Analog Found
+
+No files in this phase lack an analog. All changes are targeted modifications of existing files. The `classifyValarms`, `extractValarms`, `computeAlertInstantUtc`, and `humanizeLeadMinutes` functions are new but live inside existing files; their patterns are documented in RESEARCH.md Code Examples and the RRULE-analog sections above.
+
+---
+
+## Metadata
+
+**Analog search scope:** `apps/api/src/broker/`, `apps/api/src/routes/`, `apps/api/src/db/`, `apps/pwa/src/components/`, `apps/pwa/src/api/`, `apps/api/tests/broker/`
+**Files read:** vevent.ts, outboxWorker.ts, reminderScheduler.ts, sync.ts (lines 1–200), expand.ts (lines 1–80), events.ts (lines 1–130), client.ts (lines 100–215), EventForm.tsx (lines 840–889), vevent.test.ts (lines 1–60), reminderScheduler.test.ts (lines 1–80)
+**Pattern extraction date:** 2026-06-13