@open-webapp/calendar 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# @open-webapp/calendar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Multi-account Google Calendar read-only sync (controller) plus React UI (`CalendarPane`, `CalendarSelector`). Storage and encryption are host-supplied adapters.
+
+> **0.2.0 is BREAKING.** See [Breaking changes in 0.2.0](#breaking-changes-in-020).
+
+## Install
+
+```bash
+npm install @open-webapp/calendar
+```
+
+Peer: `react ^19`. `vitest` is an optional peer, needed only for `@open-webapp/calendar/testing`'s `runStorageAdapterContract`.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@open-webapp/calendar` | core types, event helpers, fetch/sync/reconcile helpers, `createCalendarController`, `CalendarPane`, `CalendarSelector` |
+| `@open-webapp/calendar/testing` | `runStorageAdapterContract`, `LEGACY_EVENT`, `StorageContractHarness`, `createMemoryStorage`, `identityCrypto`, `installFakeFetch` |
+| `@open-webapp/calendar/styles.css` | stylesheet for the React components (import once) |
+
+## Usage
+
+```tsx
+import { createCalendarController, CalendarPane } from '@open-webapp/calendar';
+import '@open-webapp/calendar/styles.css';
+
+const controller = createCalendarController({
+  sources: [{ id: 'a', email: 'me@example.com' }],
+  getToken: async (sourceId) => accessTokenFor(sourceId),
+  storage,   // StorageAdapter
+  crypto,    // CryptoAdapter
+});
+await controller.hydrate();  // publishes cached events immediately (no network)
+void controller.refresh();   // then syncs from Google
+
+<CalendarPane
+  sources={sources}
+  controller={controller}
+  selectedRsvpStatuses={statuses}          // Set<RsvpStatus>
+  onRsvpStatusesChange={setStatuses}
+  connected={connected}                    // optional, see CalendarPane props
+  needsReauth={needsReauth}
+  onConnect={connect}
+  onReconnect={reconnect}
+/>
+```
+
+## Controller
+
+`createCalendarController({ sources, getToken, storage, crypto, now? })`
+
+- `hydrate(): Promise<void>` loads the stored rows and publishes cached events before any network call. Never throws. Offline, the cache stays visible.
+- `refresh(): Promise<void>` syncs every source in parallel; never throws.
+- `retryDeferred(): Promise<void>` re-runs a refresh after a deferred pass (see [Deferred refresh](#deferred-refresh)).
+- `getEvents(): CalendarEvent[]` stable snapshot (updated on `hydrate`/`refresh`/`setSelectedIds`/`clearSelectedIds`), sources concatenated in `sources` order. Only events that pass the read-time filter are returned (see [Window](#window)).
+- `getState(): { loading, error, deferred, lastSyncAt }`:
+  - `loading`: a refresh pass is in flight.
+  - `error`: true only when every selected calendar (across sources) errored and nothing is cached.
+  - `deferred`: the last pass was deferred.
+  - `lastSyncAt`: ms epoch of the most recent refresh pass across sources, or `null`.
+- `getSourceStatus()` / `sourceStatus`: `Record<sourceId, 'ok' | 'needs-scope' | 'error'>`.
+- `getCalendars(sourceId)`, `getSelectedIds(sourceId)`.
+- `setSelectedIds(sourceId, ids)`: see [Selection](#selection). Fetches calendars newly added to the selection; drops nothing it has cached for deselected calendars.
+- `clearSelectedIds(sourceId)`: resets the selection to the primary calendar.
+- `subscribe(listener): () => void`.
+
+### Selection
+
+- Default selection is the primary calendar.
+- On refresh, the stored selection is filtered to calendars that still exist. If none remain, the selection falls back to the primary calendar (else the first calendar).
+- Primary is not forced: a stored selection that omits primary is kept.
+- `setSelectedIds(id, [])` is ignored; at least one calendar always remains selected. Use `clearSelectedIds` to reset to primary.
+- `setSelectedIds` persists the selection and fetches any calendars newly added to it.
+- Deselecting a calendar keeps its cached events and sync tokens (retained, hidden by the read-time filter). Re-selecting it shows the cache immediately and syncs it.
+
+### sourceStatus
+
+- `ok`: last refresh succeeded, or only some calendars failed (also the initial value).
+- `needs-scope`: Google returned 403 `insufficientPermissions`; the host should prompt re-consent.
+- `error`: any other failure (401, 5xx, non-403 HTTP, unexpected exception).
+- Network failures leave the previous status unchanged and keep cached events.
+
+### Deferred refresh
+
+- A host `getToken` (or fetch path) may throw `RefreshDeferredError`, or any error with `deferred: true`. `isRefreshDeferredError(e)` recognises both.
+- A deferred pass is quiet: it does not change `sourceStatus`, does not set `getState().error`, and is not retried immediately. `getState().deferred` becomes `true`; the host calls `retryDeferred()` when it is ready.
+
+## Sync behavior
+
+Per calendar:
+
+- Full (windowed) sync when there is no sync token, no `lastFullSyncAt` for that calendar, or the last full sync is more than 24h old. Full sync uses `singleEvents=true`, window now -30d .. now +30d (RFC3339, no milliseconds), all pages (`maxResults=250`), and stores `nextSyncToken` and `lastFullSyncAt`.
+- Otherwise incremental with `syncToken` (no time bounds); cancelled items remove events.
+- HTTP 410 (`gone`): token dropped, full windowed resync.
+- A failing calendar is retried once immediately (deferred errors are not retried).
+- Calendars are isolated: one failing calendar keeps its cached events and token; other calendars and sources are unaffected.
+- Per-source status: if some targeted calendars succeed and none reports a scope error, the source is `ok` (failed calendars keep their cached events). A scope error gives `needs-scope`. If every targeted calendar fails, the status follows the `sourceStatus` rules above (`error` for non-network failures, unchanged on network-only failures).
+
+### Window
+
+- Stored events whose end is strictly before now -30d are pruned on refresh.
+- Read-time filter (`getEvents()`): events on deselected calendars are hidden; events are kept when they end after now -30d and start before now +30d (edges excluded, overlaps kept).
+
+## Adapters
+
+```ts
+interface StorageAdapter {
+  get(sourceId): Promise<StorageRow | null>;
+  put(sourceId, row: StorageRow): Promise<void>;
+  delete(sourceId): Promise<void>;
+  clear(sourceId): Promise<void>;
+}
+interface StorageRow { events: CalendarEvent[] | string | unknown[]; syncState: SyncState | string | null | unknown; selectedIds: string[] }
+interface SyncState {
+  tokens: Record<calendarId, string>;
+  lastFullSyncAt?: Record<calendarId, number>; // ms epoch; absent on 0.1.0 rows
+  lastSyncAt?: number;                         // ms epoch; absent on 0.1.0 rows
+}
+interface CryptoAdapter { encrypt(s: string): Promise<string>; decrypt(s: string): Promise<string> }
+```
+
+The controller writes `events` and `syncState` as `crypto.encrypt(JSON.stringify(...))` strings and `selectedIds` as a plain array. On read, string values are decrypted and parsed; non-string (legacy plain) values are used as-is. Corrupt rows or decrypt failures read back as empty.
+
+Rows written by 0.1.0 (no `lastFullSyncAt`/`lastSyncAt`, no retained-calendar data) still read. A missing `lastFullSyncAt` triggers one full windowed sync on the next refresh.
+
+### Contract harness
+
+```ts
+import { runStorageAdapterContract } from '@open-webapp/calendar/testing';
+runStorageAdapterContract(() => ({ storage, crypto, seedRaw?, wrongKeyCrypto?, encryptedFixture?, corruptRow? }));
+```
+
+Call at top level of a vitest file; it registers a `describe('StorageAdapter contract')` suite (round trip, source isolation, delete/clear, missing source, legacy plain row, legacy encrypted fixture, corrupt row, wrong key).
+
+### Event key
+
+`getCalendarEventKey(event)` returns `${sourceId}:${calendarId}:${eventId}` (e.g. `src1:calA:ev1`). This multi-source form is the one intentional divergence from notesdiary (`calA:ev1`), kept by decision for multi-source.
+
+## UI
+
+### CalendarPane props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `sources` | `Source[]` | shown accounts; 2+ enables multi-source UI (per-source color and email) |
+| `controller` | `CalendarController` | |
+| `selectedRsvpStatuses` | `Set<RsvpStatus>` | filter; `DEFAULT_RSVP_STATUSES` = accepted, tentative, needsAction |
+| `onRsvpStatusesChange` | `(next) => void` | |
+| `renderEventAction?` | `(event) => ReactNode` | per-event slot |
+| `connected?` | `boolean` | defaults to `sources.length > 0` (back-compat). `false` shows the not-connected block |
+| `needsReauth?` | `boolean` | defaults to every source being `needs-scope`. Shows the reauth block |
+| `onConnect?` | `() => void` | wired to the built-in "Connect Google Calendar" button |
+| `onReconnect?` | `() => void` | wired to the built-in "Reconnect to restore sync" button |
+| `emptyState?` | `ReactNode` | replaces the built-in not-connected block |
+| `sourceNotice?` | `(source) => ReactNode` | per-source slot, rendered for `needs-scope` sources (e.g. re-consent button); without it the built-in reauth block is shown |
+| `onClose?` | `() => void` | |
+| `popupName?` | `string` | `window.open` name for the event popup (default `notesdiary-cal-event`) |
+
+Built-in copy (overridable only through the slots above):
+
+- Not connected: "Not connected to Google Calendar." with "Connect Google Calendar".
+- Reauth: "Calendar connection needs reauthorization." with "Reconnect to restore sync".
+- Error with nothing cached: "Couldn't load calendar events. Try again shortly."
+- Loading: "Loading calendar…".
+- Empty: "No matching events in the next 30 days".
+
+### CalendarSelector props
+
+`calendars: CalendarInfo[]`, `selectedIds: string[]`, `onChange(ids)`, `heading?: string` (account heading in multi-source use). It has no slot props or `popupName`. At least one calendar stays selected (deselecting the last one is ignored). "Clear" resets to the primary calendar. Built-in copy: "Search calendars", "Select all", "Clear", "Done", "No calendars found", "No calendars available".
+
+### Host CSS
+
+`styles.css` is self-contained (plain colors, dark mode via `prefers-color-scheme`). It requires no host CSS variables. Variables it reads, all with defaults:
+
+- `--calendar-footer-height` (default `64px`, set on `.calendar-pane`; override to match host footer)
+- `--chip-row-height` (fallback `44px`; host may set it to match its chip row for sticky headers)
+- `--rsvp-bar` (set internally per RSVP status; do not override)
+
+## Breaking changes in 0.2.0
+
+BREAKING (0.1.0 to 0.2.0):
+
+- **Selection semantics.** Primary is no longer forced into the selection. Stored selections are honored (filtered to existing calendars). `setSelectedIds` no longer always adds primary, and an empty list is ignored. `clearSelectedIds` resets to primary.
+- **Cache and storage rows.** `setSelectedIds` no longer drops events and sync tokens of deselected calendars; they are retained. `syncState` gains optional `lastFullSyncAt` and `lastSyncAt`. Window pruning and the read-time window filter are new. 0.1.0 rows still read (missing fields take their defaults).
+- **Pane behavior.** `CalendarPane` gains `connected`, `needsReauth`, `onConnect`, `onReconnect`. Omitting `connected` keeps the old behavior (`sources.length > 0`). Deferred refreshes are quiet. `getState()` and `hydrate()` are new; hosts that want cache-first display should call `hydrate()` before `refresh()`.
+- Unchanged: event key form (`src1:calA:ev1`), `sourceStatus` values, `StorageAdapter`/`CryptoAdapter` signatures.

package/dist/core/controller.d.ts

@@ -0,0 +1,33 @@
+import type { CryptoAdapter, StorageAdapter } from './storage.js';
+import type { CalendarEvent, CalendarInfo, Source } from './types.js';
+export type SourceStatus = 'ok' | 'needs-scope' | 'error';
+export interface CalendarControllerOptions {
+    sources: Source[];
+    getToken: (sourceId: string) => Promise<string>;
+    storage: StorageAdapter;
+    crypto: CryptoAdapter;
+    now?: () => Date;
+}
+export interface CalendarControllerState {
+    loading: boolean;
+    /** True only when every selected calendar failed and nothing is cached. */
+    error: boolean;
+    deferred: boolean;
+    lastSyncAt: number | null;
+}
+export interface CalendarController {
+    hydrate(): Promise<void>;
+    refresh(): Promise<void>;
+    /** Re-runs a refresh after a deferred pass. */
+    retryDeferred(): Promise<void>;
+    getState(): CalendarControllerState;
+    getEvents(): CalendarEvent[];
+    getSourceStatus(): Record<string, SourceStatus>;
+    readonly sourceStatus: Record<string, SourceStatus>;
+    getCalendars(sourceId: string): CalendarInfo[];
+    getSelectedIds(sourceId: string): string[];
+    setSelectedIds(sourceId: string, ids: string[]): Promise<void>;
+    clearSelectedIds(sourceId: string): Promise<void>;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createCalendarController(opts: CalendarControllerOptions): CalendarController;

package/dist/core/controller.js

@@ -0,0 +1,251 @@
+import { CalendarFetchError, fetchCalendarList, isRefreshDeferredError } from './fetch.js';
+import { reconcileSelection } from './reconcile.js';
+import { syncCalendar } from './sync.js';
+export function createCalendarController(opts) {
+    const { sources, getToken, storage, crypto } = opts;
+    const now = opts.now ?? (() => new Date());
+    const state = new Map();
+    const listeners = new Set();
+    let snapshot = [];
+    let loadingCount = 0;
+    let deferred = false;
+    let statusSnapshot = {};
+    for (const s of sources) {
+        state.set(s.id, {
+            loaded: false,
+            events: [],
+            syncState: { tokens: {} },
+            selectedIds: ['primary'],
+            calendars: [],
+            status: 'ok',
+            errored: new Set(),
+            gen: 0,
+        });
+    }
+    function publish() {
+        snapshot = sources.flatMap((s) => {
+            const st = state.get(s.id);
+            const ws = now().getTime() - 30 * 86400000;
+            const we = now().getTime() + 30 * 86400000;
+            const ms = (v, d) => {
+                const t = v ? new Date(v).getTime() : NaN;
+                return Number.isNaN(t) ? d : t;
+            };
+            // read-time window: exact edges excluded, overlaps kept (notesdiary loadCached)
+            return st.events.filter((e) => (!e.calendarId || st.selectedIds.includes(e.calendarId)) &&
+                ms(e.end.dateTime ?? e.end.date, Infinity) > ws &&
+                ms(e.start.dateTime ?? e.start.date, -Infinity) < we);
+        });
+        statusSnapshot = Object.fromEntries(sources.map((s) => [s.id, state.get(s.id).status]));
+        listeners.forEach((l) => l());
+    }
+    async function decode(v, fallback) {
+        if (typeof v === 'string') {
+            try {
+                return JSON.parse(await crypto.decrypt(v));
+            }
+            catch {
+                return fallback;
+            }
+        }
+        return (v ?? fallback);
+    }
+    async function load(sourceId) {
+        const st = state.get(sourceId);
+        if (st.loaded)
+            return;
+        st.loaded = true;
+        try {
+            const row = await storage.get(sourceId);
+            if (!row)
+                return;
+            st.events = await decode(row.events, []);
+            const ss = await decode(row.syncState, null);
+            st.syncState = ss && ss.tokens ? ss : { tokens: {} };
+            if (Array.isArray(row.selectedIds))
+                st.selectedIds = row.selectedIds;
+        }
+        catch {
+            /* unreadable cache: start empty */
+        }
+    }
+    async function persist(sourceId) {
+        const st = state.get(sourceId);
+        try {
+            await storage.put(sourceId, {
+                events: await crypto.encrypt(JSON.stringify(st.events)),
+                syncState: await crypto.encrypt(JSON.stringify(st.syncState)),
+                selectedIds: st.selectedIds,
+            });
+        }
+        catch {
+            /* persistence is best-effort */
+        }
+    }
+    async function syncWithRetry(run) {
+        try {
+            return await run();
+        }
+        catch (e) {
+            if (isRefreshDeferredError(e))
+                throw e;
+            return run();
+        }
+    }
+    /** Returns true when the pass was deferred. `only` limits syncing to those calendars. */
+    async function refreshSource(sourceId, only) {
+        const st = state.get(sourceId);
+        await load(sourceId);
+        const gen = st.gen;
+        let wasDeferred = false;
+        try {
+            const token = await getToken(sourceId);
+            const calendars = await fetchCalendarList(token);
+            st.calendars = calendars;
+            const selected = reconcileSelection(st.selectedIds, calendars);
+            const targets = only ? selected.filter((c) => only.includes(c)) : selected;
+            const fresh = [];
+            const synced = [];
+            const tokens = { ...st.syncState.tokens };
+            const lastFull = { ...st.syncState.lastFullSyncAt };
+            const failures = [];
+            for (const calendarId of targets) {
+                try {
+                    const res = await syncWithRetry(() => syncCalendar({
+                        token,
+                        sourceId,
+                        calendarId,
+                        existing: st.events.filter((e) => e.calendarId === calendarId),
+                        syncToken: st.syncState.tokens[calendarId],
+                        lastFullSyncAt: st.syncState.lastFullSyncAt?.[calendarId],
+                        now: now(),
+                    }));
+                    fresh.push(...res.events);
+                    synced.push(calendarId);
+                    st.errored.delete(calendarId);
+                    if (res.syncToken)
+                        tokens[calendarId] = res.syncToken;
+                    else
+                        delete tokens[calendarId];
+                    if (res.full)
+                        lastFull[calendarId] = now().getTime();
+                }
+                catch (e) {
+                    if (isRefreshDeferredError(e))
+                        throw e;
+                    failures.push(e);
+                    st.errored.add(calendarId);
+                }
+            }
+            const winStart = new Date(now().getTime() - 30 * 86400000).getTime();
+            const endMs = (e) => {
+                const v = e.end.dateTime ?? e.end.date;
+                const t = v ? new Date(v).getTime() : NaN;
+                return Number.isNaN(t) ? Infinity : t;
+            };
+            st.events = [...st.events.filter((e) => !(e.calendarId && synced.includes(e.calendarId))), ...fresh].filter((e) => endMs(e) >= winStart);
+            st.syncState = { ...st.syncState, tokens, lastFullSyncAt: lastFull };
+            if (st.gen === gen)
+                st.selectedIds = selected;
+            if (failures.length === 0)
+                st.status = 'ok';
+            else if (failures.some((e) => e instanceof CalendarFetchError && e.kind === 'scope'))
+                st.status = 'needs-scope';
+            else if (failures.length < targets.length)
+                st.status = 'ok';
+            else if (failures.some((e) => !(e instanceof CalendarFetchError) || e.kind !== 'network'))
+                st.status = 'error';
+        }
+        catch (e) {
+            if (st.selectedIds.length === 0)
+                st.selectedIds = ['primary'];
+            if (isRefreshDeferredError(e)) {
+                wasDeferred = true;
+            }
+            else if (e instanceof CalendarFetchError) {
+                if (e.kind === 'scope')
+                    st.status = 'needs-scope';
+                else if (e.kind !== 'network')
+                    st.status = 'error';
+            }
+            else {
+                st.status = 'error';
+            }
+        }
+        st.syncState = { ...st.syncState, lastSyncAt: now().getTime() };
+        await persist(sourceId);
+        return wasDeferred;
+    }
+    async function runPass(only) {
+        loadingCount++;
+        try {
+            const ids = sources.map((s) => s.id).filter((id) => !only || only[id]);
+            const results = await Promise.all(ids.map((id) => refreshSource(id, only?.[id])));
+            deferred = results.some(Boolean);
+        }
+        catch {
+            /* never throws */
+        }
+        finally {
+            loadingCount--;
+        }
+        publish();
+    }
+    async function setSelected(sourceId, ids) {
+        const st = state.get(sourceId);
+        if (!st)
+            return;
+        await load(sourceId);
+        const next = [...new Set(ids)];
+        if (next.length === 0)
+            return;
+        const added = next.filter((id) => !st.selectedIds.includes(id));
+        st.selectedIds = next;
+        st.gen++;
+        await persist(sourceId);
+        publish();
+        if (added.length > 0)
+            await runPass({ [sourceId]: added });
+    }
+    const controller = {
+        async hydrate() {
+            try {
+                await Promise.all(sources.map((s) => load(s.id)));
+            }
+            catch {
+                /* never throws */
+            }
+            publish();
+        },
+        refresh: () => runPass(),
+        retryDeferred: () => runPass(),
+        getState() {
+            const sel = sources.flatMap((s) => {
+                const st = state.get(s.id);
+                return st.selectedIds.map((c) => st.errored.has(c));
+            });
+            const lasts = sources.map((s) => state.get(s.id).syncState.lastSyncAt).filter((v) => typeof v === 'number');
+            return {
+                loading: loadingCount > 0,
+                error: sel.length > 0 && sel.every(Boolean) && snapshot.length === 0,
+                deferred,
+                lastSyncAt: lasts.length ? Math.max(...lasts) : null,
+            };
+        },
+        getEvents: () => snapshot,
+        getSourceStatus: () => statusSnapshot,
+        get sourceStatus() {
+            return statusSnapshot;
+        },
+        getCalendars: (id) => state.get(id)?.calendars ?? [],
+        getSelectedIds: (id) => state.get(id)?.selectedIds ?? [],
+        setSelectedIds: (id, ids) => setSelected(id, ids),
+        clearSelectedIds: (id) => setSelected(id, [state.get(id)?.calendars.find((c) => c.primary)?.id ?? 'primary']),
+        subscribe(l) {
+            listeners.add(l);
+            return () => listeners.delete(l);
+        },
+    };
+    statusSnapshot = Object.fromEntries(sources.map((s) => [s.id, 'ok']));
+    return controller;
+}

package/dist/core/events.d.ts

@@ -0,0 +1,91 @@
+import type { CalendarEvent, CalendarInfo, ParseContext, RsvpStatus } from './types.js';
+export declare const DEFAULT_RSVP_STATUSES: RsvpStatus[];
+/** Keeps stored calendar selections that still exist, defaulting to the primary calendar. */
+export declare function reconcileSelectedCalendarIds(storedIds: string[] | null, calendars: CalendarInfo[]): string[];
+/** Filters calendars by a case-insensitive substring of their display name. */
+export declare function filterCalendarsByName(calendars: CalendarInfo[], query: string): CalendarInfo[];
+/** Event IDs are unique only within their calendar and source. */
+export declare function getCalendarEventKey(event: CalendarEvent): string;
+/** Produces the compact calendar-selection label shown in the filter control. */
+export declare function summarizeCalendarSelection(selectedIds: string[], calendars: CalendarInfo[]): string;
+/** True iff the event is an all-day event. Passthrough of the package-computed flag. */
+export declare function isAllDay(event: CalendarEvent): boolean;
+/**
+ * Rolling fetch window: now-30d to now+30d, as full RFC3339 timestamps.
+ * Google Calendar's `timeMin`/`timeMax` reject bare `YYYY-MM-DD` dates.
+ */
+export declare function getRollingWindow(now: Date): {
+    start: string;
+    end: string;
+};
+/**
+ * Returns events whose `selfResponseStatus` is a member of `selected` —
+ * declined is a normal, independently-selectable status now, not hard-excluded.
+ */
+export declare function filterByRsvp(events: CalendarEvent[], selected: ReadonlySet<RsvpStatus>): CalendarEvent[];
+/** displayName -> email -> "You" (only when organizer.self is true and both above are absent). */
+export declare function getOrganizerLabel(event: CalendarEvent): string;
+/**
+ * True iff `event` is a timed (non-all-day) event currently in progress at `now`:
+ * both `start.dateTime` and `end.dateTime` exist and parse to valid instants,
+ * start <= now < end.
+ */
+export declare function isEventCurrent(event: CalendarEvent, now: Date): boolean;
+/**
+ * Finds the soonest strictly-future timed event: `!isAllDay(event)`,
+ * `start.dateTime` exists and parses valid, and `startMs > now.getTime()`.
+ * Returns the smallest `startMs`; ties keep first-encountered array order.
+ * Returns `null` if none qualify.
+ */
+export declare function findNextUpcomingEvent(events: CalendarEvent[], now: Date): CalendarEvent | null;
+export interface DayGroup {
+    dateKey: string;
+    events: CalendarEvent[];
+}
+/**
+ * Group by local calendar date, sorted ascending by day. Within a day,
+ * all-day events come first (in list order), then timed events sorted by
+ * start time ascending.
+ *
+ * When `todayIso` is given and has no events, an empty group for it is
+ * still included (so a "Today" header can always be rendered / scrolled
+ * to), inserted in correct sorted position.
+ */
+export declare function groupByDay(events: CalendarEvent[], todayIso?: string): DayGroup[];
+/**
+ * "Today · Sept 26" / "Tomorrow · Sept 27" / else "Sept 28"-style.
+ * Includes year only when the event's year differs from today's year.
+ */
+export declare function formatDayHeader(dateKey: string, today: string): string;
+interface RawEvent {
+    id?: unknown;
+    status?: string;
+    summary?: string;
+    start?: CalendarEvent['start'];
+    end?: CalendarEvent['end'];
+    attendees?: {
+        self?: boolean;
+        responseStatus?: string;
+    }[];
+    organizer?: {
+        displayName?: string;
+        email?: string;
+        self?: boolean;
+    };
+    htmlLink?: string;
+    hangoutLink?: string;
+    conferenceData?: {
+        entryPoints?: {
+            entryPointType?: string;
+            uri?: string;
+        }[];
+    };
+    location?: string;
+    description?: string;
+}
+export declare function deriveSelfResponseStatus(raw: RawEvent): RsvpStatus;
+export declare function extractJoinUrl(raw: RawEvent): string | null;
+/** Parses a raw Google Calendar event. Returns null for cancelled/malformed input; never throws. */
+export declare function parseEvent(raw: RawEvent, ctx: ParseContext): CalendarEvent | null;
+export declare function parseEvents(items: RawEvent[], ctx: ParseContext): CalendarEvent[];
+export {};